A public, versioned REST API at api.hodeishield.com, an open-source CLI and a hosted MCP server that consumes it. No developer surface changes your tenant's data.
curl -H "Authorization: Bearer $HODEISHIELD_API_KEY" "https://api.hodeishield.com/v1/vendors?per_page=5"{
"data": [ … ],
"pagination": {
"page": 1, "per_page": 5,
"total": …, "total_pages": …
}
}All of them read your tenant's data. None of them writes.
GET operations over vendors, alerts, risks, compliance, evidence and endpoints. It is the base of the CLI and the MCP server.
Scope: It accepts no writes to the tenant.
Linux x86_64 and arm64 · macOS universal · Windows x86_64
The official command-line client, for terminals and scripts.
Scope: Read-only. Install it with Homebrew (macOS and Linux), with Scoop (Windows) or from the release archive.
https://mcp.hodeishield.com/mcp
Your AI assistant reads your data through the MCP protocol, with nothing to install.
Scope: It changes nothing. Results come wrapped in a prompt-injection envelope.
A script that checks a signed attestation offline, with no HodeiShield account.
Scope: It proves integrity, origin and time; not that what is claimed is true.
Your HTTPS endpoint receives the tenant's events according to your routing rules, signed with HMAC-SHA256.
Scope: It is an alert destination: it notifies, and runs nothing in HodeiShield.
Each key belongs to one tenant and carries only the read scopes it needs.
An administrator creates the key in the console, with a name, an expiry and only the scopes needed. The token (hsk_…) is shown once. To act as a specific person, from the CLI or an assistant for example, you use OAuth 2.1 with PKCE.
Collections accept page (from 1) and per_page (1 to 200, 50 by default) and return data and pagination. Errors always use the same envelope, with a request_id for support.
A first read
curl -H "Authorization: Bearer $HODEISHIELD_API_KEY" "https://api.hodeishield.com/v1/vendors?per_page=5"OpenAPI document (no authentication)
curl https://api.hodeishield.com/v1/openapi.jsonThe document generated at /v1/openapi.json is the authoritative source; use it to generate typed clients.
| Operation | Request | Scope |
|---|---|---|
| Vendors | GET /v1/vendors · /v1/vendors/{id} | supply_risk:read |
| Alerts | GET /v1/alerts · /v1/alerts/{id} | supply_risk:read |
| Risks | GET /v1/risks · /v1/risks/{id} | supply_risk:read |
| Compliance controls | GET /v1/compliance/controls?framework=… | compliance.<framework>:read |
| Framework posture | GET /v1/compliance/frameworks/{framework} | compliance.<framework>:read |
| Evidence | GET /v1/evidence · /v1/evidence/{id} | evidence:read |
| Endpoints | GET /v1/endpoints | endpoints:read |
| OpenAPI document | GET /v1/openapi.json | none |
Install it with Homebrew or Scoop, or download the archive for your platform from the published release, verify it and put it on your PATH.
Homebrew (macOS and Linux) and Scoop (Windows x86_64) install version 0.3.1 from public Hodeitek repositories. The Windows executable is signed with Authenticode; the macOS one is not yet.
Homebrew (macOS and Linux)
brew install hodeitek/hodeishield/hodeishieldHomebrew, if you already added the tap
brew trust --formula hodeitek/hodeishield/hodeishieldScoop (Windows)
scoop bucket add hodeishield https://github.com/Hodeitek/scoop-hodeishield; scoop install hodeishieldEvery release publishes SHA256SUMS, a Sigstore bundle per archive and the SLSA provenance; from version 0.2.0 it also publishes a CycloneDX SBOM per archive. Archives are .tar.gz on Linux and macOS and .zip on Windows. A valid cosign signature proves the file was built by the repository's release.yml workflow, run by the exact tag you expect.
sha256sum --ignore-missing -c SHA256SUMScosign verify-blob hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz --bundle hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz.sigstore.json --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.3.1 --certificate-oidc-issuer https://token.actions.githubusercontent.com --certificate-github-workflow-trigger pushYou can also build from source with cargo install --locked, pinning the release tag.
--json prints the API body unchanged; --csv prints lists as CSV; --all walks every page. Exit codes run from 0 to 8 and tell apart, for example, a missing credential, a missing scope, a rate limit and a tenant licence not in force.
With an API key (scripts, CI)
export HODEISHIELD_API_KEY=hsk_...As a person (browser, 2FA, passkey or SSO)
hodeishield loginhodeishield whoamihodeishield vendors list --criticality criticalhodeishield compliance posture nis2hodeishield alerts list --status open --all --json | jq -r '.[] | [.severity, .title] | @tsv'A hosted server, nothing to install. The assistant sees what you would see in the tenant you choose, and only with the scopes you grant.
In an MCP client that supports remote servers with OAuth, add a connector with this URL. The client discovers the authorization server on its own; you sign in at app.hodeishield.com with your usual factors and choose a single tenant.
MCP server URL
https://mcp.hodeishield.com/mcpNone accepts a tenant identifier as a parameter: there is no way to ask for another tenant's data.
Always verify the signature before processing the body, and reject old timestamps.
The secret (whsec_…) is shown once when you create the webhook; if you lose it, rotate it. If your endpoint does not answer 2xx, delivery is attempted up to six times in all (five retries, from 5 minutes up to 24 hours apart); once attempts are exhausted the delivery is marked failed in the console and you can requeue it.
import hashlib
import hmac
def is_valid(secret: str, timestamp: str, body: bytes, received_signature: str) -> bool:
message = f"{timestamp}.".encode() + body
expected = "sha256=" + hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, received_signature)The verifier is a bash and Python script you can read in full. It makes no call to HodeiShield at verification time.
Scope: It proves the integrity, origin and time of what was signed. It does not prove the claims are true, it does not replace an audit, and there is no transparency log. Always pass --expect-slug and --expect-issuer: without them a valid attestation of a different organisation verifies just as well. The exit code is 0 if it verifies, 1 if it fails and 2 if it could not be checked. A genuine but expired document exits 1 and its last line starts with "EXPIRED — the signature is valid".
Requirements: bash 4, OpenSSL 3.5 or later, and python3. If your machine lacks them (macOS, Windows or Ubuntu 24.04), the verifier repository documents how to run the same script in a container with Docker or Podman; that route installs OpenSSL and python3 on start, so it needs network access.
curl -s https://app.hodeishield.com/api/public/attest/keys -o keys.json./verify-attestation.sh --attestation attestation.json --jwks keys.json --expect-slug SLUG --expect-issuer https://app.hodeishield.comSo you do not find out while integrating them.
The API, CLI and MCP are read-only. To act on the tenant you use the console, and ACT always goes through a person.
Commands and output may change before 1.0. Pin the version in your scripts.
The server cannot control what your client does with the results. Treat third-party text inside them as untrusted.
Availability of the API and MCP depends on your licence and is confirmed per tenant; we cover it in the demo.
We publish no SLA, response times or API availability on this site.
The API returns what the platform has already collected: the agent reports per cycle and scans are periodic.
What a technical team usually asks before starting.
No. The /v1 API is read-only: any method other than GET returns 405. The CLI and the MCP server use it, so they do not write either.
With a tenant API key (hsk_…) created by an administrator with only the read scopes needed. In the CLI, exporting HODEISHIELD_API_KEY is enough.
Every release publishes SHA256SUMS, Sigstore bundles and SLSA provenance. Use cosign to check that the archive was built by the repository's release.yml workflow for the exact tag.
What you would see in the single tenant you choose when you grant access, and only with the scopes you grant. No tool accepts a tenant identifier.
Yes. Download the public key from /api/public/attest/keys and run the open-source verifier. It works offline with bash 4, OpenSSL 3.5 and python3, or in a container with Docker or Podman.
In the demo we look at what to read through the API, CLI or MCP, and how it fits your alerts and pipelines.
A working conversation, no commitment.