Security
Package security is secret scanning for your code: submit sources, get findings, masked never raw.
Package security is secret scanning for your code: submit sources, get findings, masked never raw.
| Base URL | https://api.hanzo.ai |
| Operations | 7 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
security
GET /v1/security/findings/{id}
One finding
Returns a single finding: which rule fired, where (path and line), the masked preview and the SHA-256 fingerprint of the secret — the raw secret is not stored and cannot be read back. Scoped to the caller's org, and a finding belonging to another org is the same 404 as one that never existed.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
GET /v1/security/findings
The org's findings, across scans or within one
Lists the caller org's findings — rule, severity, path, line, masked preview and fingerprint — newest first. scanId narrows to a single scan, minSeverity (critical | high | medium | low) drops everything below that rank, and limit caps the page; a minSeverity outside that set is refused with 400 rather than quietly ignored, so a filter typo cannot read as "no findings". Strictly org-scoped, and a caller with no validated org is refused.
GET /v1/security/health
Liveness, and how many detection rules are loaded
Reports that the scanning subsystem is serving and how many secret-detection rules the engine holds. It has no external dependency — the answer is ok whenever the findings store opened — so it measures this process rather than anything downstream. Reads no tenant: a prober that sends no principal is answered, not refused.
GET /v1/security/rules
The secret-detection catalog the engine scans with
Returns every rule a scan can fire — the id, name and severity a finding cites — so a caller can render or triage results without hard-coding the catalog. It is the same for everyone and discloses nothing tenant-specific, so it carries no org scope.
GET /v1/security/scans/{id}
One scan and every finding on it
Returns the scan summary together with all of its findings, so the detail view is one round-trip rather than a list call per scan. The findings carry masked previews and fingerprints, never secrets.
Scoped to the caller's org: a scan id belonging to another org is the same 404 as an id that never existed, so a probe learns nothing about what exists elsewhere. No validated org is refused.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
GET /v1/security/scans
The org's scan history
Lists the caller org's scans, newest first, each as the same summary the submission answered — files read, findings fired, tally by severity. limit caps the page. Strictly org-scoped: a caller only ever sees its own scans, and one with no validated org is refused.
POST /v1/security/scans
Scan submitted source for hardcoded secrets
Runs the detection engine over a batch of {path, content} files and answers 201 with the scan summary: how many files were read, how many findings fired, and the tally by severity.
THE SUBMITTED CONTENT IS NEVER STORED. It is scanned in memory; what persists is the finding — its rule, its path and line, a MASKED preview (first and last characters kept, the middle starred) and the SHA-256 fingerprint of the raw secret. The fingerprint is what makes the same secret recognisable across scans and after rotation without the secret ever being written down.
Requires a validated org, which scopes the stored scan and every finding on it; a caller with no org is refused. project in the body names the sub-scope and is refused with 400 if it is not a valid slug; omit it and the caller's project header is used instead, where an unusable value is simply ignored. Bounded at 500 files and 8 MiB of total content per submission — split a larger tree across scans. One scan is one metered unit, and the scan is recorded in the audit log with its tally, never with its findings.
How is this guide?