Scanning API

1# Create scan from GitHub repository
2curl -X POST https://api.bloodhoundsecurity.ca/v1/scans \
3  -H "Authorization: Bearer bh_your_api_key" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "source": {
7      "type": "github",
8      "repository": "owner/repo",
9      "branch": "main",
10      "commit": "abc123"
11    },
12    "options": {
13      "mode": "advanced",
14      "engines": ["pattern", "sast", "taint", "ai"],
15      "severity_filter": ["critical", "high", "medium"]
16    }
17  }'
18
19# Response
20{
21  "id": "scan_abc123xyz",
22  "status": "pending",
23  "created_at": "2024-01-15T10:30:00Z",
24  "source": {
25    "type": "github",
26    "repository": "owner/repo",
27    "branch": "main",
28    "commit": "abc123"
29  },
30  "options": {
31    "mode": "advanced",
32    "engines": ["pattern", "sast", "taint", "ai"]
33  },
34  "links": {
35    "self": "/v1/scans/scan_abc123xyz",
36    "findings": "/v1/scans/scan_abc123xyz/findings"
37  }
38}

1# Get scan status
2curl https://api.bloodhoundsecurity.ca/v1/scans/scan_abc123xyz \
3  -H "Authorization: Bearer bh_your_api_key"
4
5# Response (in progress)
6{
7  "id": "scan_abc123xyz",
8  "status": "running",
9  "progress": {
10    "current_engine": "taint",
11    "engines_completed": 2,
12    "engines_total": 4,
13    "files_scanned": 1523,
14    "files_total": 2847,
15    "percent_complete": 54
16  },
17  "created_at": "2024-01-15T10:30:00Z",
18  "started_at": "2024-01-15T10:30:05Z"
19}
20
21# Response (completed)
22{
23  "id": "scan_abc123xyz",
24  "status": "completed",
25  "created_at": "2024-01-15T10:30:00Z",
26  "started_at": "2024-01-15T10:30:05Z",
27  "completed_at": "2024-01-15T10:35:42Z",
28  "duration_seconds": 337,
29  "summary": {
30    "total_findings": 47,
31    "by_severity": {
32      "critical": 2,
33      "high": 8,
34      "medium": 21,
35      "low": 12,
36      "info": 4
37    },
38    "files_scanned": 2847,
39    "languages": ["typescript", "javascript", "python"]
40  },
41  "links": {
42    "self": "/v1/scans/scan_abc123xyz",
43    "findings": "/v1/scans/scan_abc123xyz/findings",
44    "report": "/v1/scans/scan_abc123xyz/report"
45  }
46}

1# List recent scans
2curl "https://api.bloodhoundsecurity.ca/v1/scans?limit=10" \
3  -H "Authorization: Bearer bh_your_api_key"
4
5# Filter by repository
6curl "https://api.bloodhoundsecurity.ca/v1/scans?repository=owner/repo" \
7  -H "Authorization: Bearer bh_your_api_key"
8
9# Filter by status
10curl "https://api.bloodhoundsecurity.ca/v1/scans?status=completed" \
11  -H "Authorization: Bearer bh_your_api_key"
12
13# Response
14{
15  "data": [
16    {
17      "id": "scan_abc123xyz",
18      "status": "completed",
19      "repository": "owner/repo",
20      "branch": "main",
21      "summary": {
22        "total_findings": 47,
23        "critical": 2,
24        "high": 8
25      },
26      "created_at": "2024-01-15T10:30:00Z"
27    },
28    // ... more scans
29  ],
30  "pagination": {
31    "total": 156,
32    "page": 1,
33    "per_page": 10,
34    "total_pages": 16
35  }
36}

1# Get all findings
2curl "https://api.bloodhoundsecurity.ca/v1/scans/scan_abc123xyz/findings" \
3  -H "Authorization: Bearer bh_your_api_key"
4
5# Filter by severity
6curl "https://api.bloodhoundsecurity.ca/v1/scans/scan_abc123xyz/findings?severity=critical,high" \
7  -H "Authorization: Bearer bh_your_api_key"
8
9# Response
10{
11  "data": [
12    {
13      "id": "finding_xyz789",
14      "rule_id": "SQL-001",
15      "title": "SQL Injection",
16      "severity": "critical",
17      "confidence": "high",
18      "cwe": "CWE-89",
19      "location": {
20        "file": "src/api/users.ts",
21        "start_line": 142,
22        "end_line": 145,
23        "snippet": "const query = `SELECT * FROM users WHERE id = '${userId}'`"
24      },
25      "description": "User input is concatenated directly into SQL query",
26      "remediation": "Use parameterized queries instead of string concatenation",
27      "engines": ["pattern", "taint"],
28      "data_flow": [
29        {
30          "location": "src/routes/api.ts:34",
31          "type": "source",
32          "description": "req.params.id (user input)"
33        },
34        {
35          "location": "src/api/users.ts:142",
36          "type": "sink",
37          "description": "SQL query execution"
38        }
39      ]
40    }
41    // ... more findings
42  ],
43  "pagination": {
44    "total": 47,
45    "page": 1,
46    "per_page": 20
47  }
48}

1# Include webhook URL when creating scan
2curl -X POST https://api.bloodhoundsecurity.ca/v1/scans \
3  -H "Authorization: Bearer bh_your_api_key" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "source": {
7      "type": "github",
8      "repository": "owner/repo"
9    },
10    "webhook": {
11      "url": "https://your-app.com/webhooks/bloodhound",
12      "secret": "your_webhook_secret",
13      "events": ["scan.completed", "scan.failed"]
14    }
15  }'
16
17# Webhook payload (scan.completed)
18{
19  "event": "scan.completed",
20  "timestamp": "2024-01-15T10:35:42Z",
21  "data": {
22    "scan_id": "scan_abc123xyz",
23    "status": "completed",
24    "repository": "owner/repo",
25    "summary": {
26      "total_findings": 47,
27      "critical": 2,
28      "high": 8
29    },
30    "links": {
31      "findings": "https://api.bloodhoundsecurity.ca/v1/scans/scan_abc123xyz/findings",
32      "report": "https://app.bloodhoundsecurity.ca/scans/scan_abc123xyz"
33    }
34  }
35}
36
37# Verify webhook signature
38# The X-Bloodhound-Signature header contains HMAC-SHA256
39signature = HMAC-SHA256(webhook_secret, request_body)