A Python script for importing custom Cypher queries into BloodHound Community Edition (CE). This tool allows you to easily import queries from various sources including GitHub repositories, local files, and direct JSON URLs.
- Import custom queries from multiple sources:
- GitHub repositories
- Local files (JSON, YAML, plain text)
- Direct JSON URLs
- Support for various query formats:
- Compass/ZephrFish format
- Simple array format
- Plain text queries
- Built-in rate limiting to prevent API throttling
- Automatic retry mechanism for failed requests
- Detailed error reporting and import summaries
- Python 3.6 or higher
- BloodHound CE instance
- BloodHound API credentials (Token ID and Token Key)
- Clone the repository:
git clone https://github.com/yourusername/bloodhound-query-importer.git
cd bloodhound-query-importer- Install the required dependencies:
pip install -r requirements.txtpython bloodhound_client.py --token-id "YOUR_TOKEN_ID" --token-key "YOUR_TOKEN_KEY" --url "YOUR_BLOODHOUND_URL"python bloodhound_client.py --token-id "YOUR_TOKEN_ID" --token-key "YOUR_TOKEN_KEY" --url "YOUR_BLOODHOUND_URL" --json-url "https://raw.githubusercontent.com/CompassSecurity/bloodhoundce-resources/main/customqueries.json"python bloodhound_client.py --token-id "YOUR_TOKEN_ID" --token-key "YOUR_TOKEN_KEY" --url "YOUR_BLOODHOUND_URL" --github "https://github.com/CompassSecurity/bloodhoundce-resources" --branch "main" --path "customqueries"python bloodhound_client.py --token-id "YOUR_TOKEN_ID" --token-key "<
9C40
/span>YOUR_TOKEN_KEY" --url "YOUR_BLOODHOUND_URL" --file "path/to/your/queries.json"To adjust the delay between requests (default: 0.5 seconds):
python bloodhound_client.py --token-id "YOUR_TOKEN_ID" --token-key "YOUR_TOKEN_KEY" --url "YOUR_BLOODHOUND_URL" --rate-limit 1.0| Argument | Description | Default |
|---|---|---|
--url |
BloodHound instance URL | http://localhost:8080 |
--token-id |
BloodHound API token ID | (required) |
--token-key |
BloodHound API token key | (required) |
--json-url |
URL to JSON file containing queries | |
--github |
GitHub repository URL | |
--file |
Local file path | |
--branch |
GitHub branch name | main |
--path |
Path within repository or directory | |
--rate-limit |
Delay between requests in seconds | 0.5 |
{
"queries": [
{
"name": "Query Group Name",
"category": "Category Name",
"queryList": [
{
"final": true,
"query": "MATCH (n) RETURN n"
}
]
}
]
}[
{
"name": "Query Name",
"query": "MATCH (n) RETURN n",
"description": "Query Description"
}
]The script includes comprehensive error handling:
- Rate limit detection and automatic retry
- Detailed error messages for failed imports
- Progress reporting during import
- Summary of successful and failed imports
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.