CLI API Reference

1# Install via npm (recommended)
2npm install -g @agnech/bloodhound-cli
3
4# Or via Homebrew (macOS/Linux)
5brew install agnech/tap/bloodhound
6
7# Or via curl (Linux/macOS)
8curl -fsSL https://get.bloodhoundsecurity.ca | bash
9
10# Verify installation
11bloodhound version
12
13# Output:
14# Bloodhound CLI v2.4.0
15# Platform: darwin-arm64
16# Engines: 7 active

1# Interactive login
2bloodhound auth login
3
4# Login with API key
5bloodhound auth login --key YOUR_API_KEY
6
7# Login via environment variable
8export BLOODHOUND_API_KEY=YOUR_API_KEY
9bloodhound scan .  # Automatically uses env var
10
11# Check authentication status
12bloodhound auth status
13
14# Output:
15# ✓ Authenticated as: developer@company.com
16# ✓ Organization: Acme Corp
17# ✓ Plan: Pro
18# ✓ API Key: bh_****...****
19
20# Logout
21bloodhound auth logout

1# Scan current directory
2bloodhound scan .
3
4# Scan specific path
5bloodhound scan ./src
6
7# Scan with specific mode
8bloodhound scan . --mode advanced
9bloodhound scan . --mode ultimate
10bloodhound scan . --mode apex
11
12# Output to file
13bloodhound scan . --output results.json
14bloodhound scan . --output results.sarif
15bloodhound scan . --output report.html
16
17# Filter by severity
18bloodhound scan . --severity critical,high
19
20# Fail on findings (for CI/CD)
21bloodhound scan . --fail-on high
22bloodhound scan . --fail-on critical
23
24# Verbose output
25bloodhound scan . -v
26bloodhound scan . -vv  # More verbose
27bloodhound scan . -vvv # Debug level

1# Get help for any command
2bloodhound --help
3bloodhound scan --help
4bloodhound report --help
5
6# Scan command options
7bloodhound scan [path] [options]
8
9Options:
10  --mode <mode>           Analysis mode (standard|advanced|ultimate|apex)
11  --engines <list>        Comma-separated engines to use
12  --severity <list>       Filter findings by severity
13  --output <file>         Output file path
14  --format <format>       Output format (json|sarif|html|csv|markdown)
15  --fail-on <severity>    Exit with code 1 if findings at severity
16  --config <file>         Config file path
17  --timeout <seconds>     Scan timeout
18  --parallel <n>          Number of parallel workers
19  --incremental           Only scan changed files
20  --quiet                 Suppress non-essential output
21  -v, --verbose           Increase verbosity
22
23# Report command options
24bloodhound report <type> [options]
25
26Types:
27  executive               Executive summary for leadership
28  technical               Detailed technical analysis
29  catalog                 Full vulnerability catalog
30  roadmap                 Remediation roadmap
31  compliance              Compliance framework report
32  financial               Financial impact analysis
33
34Options:
35  --output <file>         Output file path
36  --format <format>       Output format (pdf|html|json|csv)
37  --period <duration>     Time period (7d|30d|90d|1y)
38  --framework <name>      Compliance framework (soc2|pci|hipaa)
39  --compare-previous      Include comparison to previous period

1# bloodhound.yaml
2
3version: 1
4
5# Default scan settings
6scan:
7  mode: advanced
8  engines:
9    - pattern
10    - sast
11    - dependencies
12    - taint
13    - ai
14
15  # Paths to include/exclude
16  include:
17    - "src/**"
18    - "lib/**"
19  exclude:
20    - "**/*.test.ts"
21    - "**/__mocks__/**"
22    - "node_modules/**"
23
24  # Severity threshold
25  severity:
26    - critical
27    - high
28    - medium
29
30  # Performance settings
31  parallel: 8
32  timeout: 300
33
34# CI/CD settings
35ci:
36  fail_on: high
37  comment_on_pr: true
38  sarif_upload: true
39
40# Report settings
41reports:
42  default_format: html
43  output_dir: ./security-reports
44
45# Suppressions
46suppressions:
47  - id: "DEPS-001"
48    reason: "False positive - not in production path"
49    expires: "2024-12-31"
50
51  - pattern: "**/*.test.ts"
52    reason: "Test files excluded"
53
54# Custom rules
55rules:
56  - path: ./custom-rules.yaml

1# Config management commands
2
3# Initialize config in current directory
4bloodhound config init
5
6# View current config
7bloodhound config show
8
9# Set specific values
10bloodhound config set scan.mode ultimate
11bloodhound config set ci.fail_on critical
12
13# Validate config file
14bloodhound config validate

1# Example CI/CD usage with exit codes
2
3# GitHub Actions
4- name: Security Scan
5  run: bloodhound scan . --fail-on high
6  continue-on-error: false  # Fail build on exit code 1
7
8# Shell script
9bloodhound scan .
10EXIT_CODE=$?
11
12if [ $EXIT_CODE -eq 0 ]; then
13  echo "No security issues found"
14elif [ $EXIT_CODE -eq 1 ]; then
15  echo "Security findings detected - review required"
16  exit 1
17else
18  echo "Scan error (code: $EXIT_CODE)"
19  exit $EXIT_CODE
20fi