Un’API REST pubblica e versionata su api.hodeishield.com, una CLI open source e un server MCP ospitato che la utilizza. Nessuna superficie per sviluppatori modifica i dati del Suo tenant.
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": …
}
}Tutte leggono i dati del Suo tenant. Nessuna scrive.
Operazioni GET su fornitori, avvisi, rischi, conformità, evidenze ed endpoint. È la base della CLI e dell’MCP.
Ambito: Non ammette scritture sul tenant.
Linux x86_64 e arm64 · macOS universale · Windows x86_64
Client ufficiale a riga di comando, per terminale e script.
Ambito: Sola lettura. Si installa con Homebrew (macOS e Linux), con Scoop (Windows) o dall’archivio della versione.
https://mcp.hodeishield.com/mcp
Il Suo assistente di IA legge i Suoi dati tramite il protocollo MCP, senza installare nulla.
Ambito: Non modifica nulla. I risultati sono racchiusi in un involucro contro la prompt injection.
Script che controlla un’attestazione firmata offline e senza un account HodeiShield.
Ambito: Prova integrità, origine e momento; non che ciò che è affermato sia vero.
Il Suo endpoint HTTPS riceve gli eventi del tenant secondo le Sue regole di instradamento, firmati con HMAC-SHA256.
Ambito: È una destinazione di avvisi: notifica, non esegue nulla in HodeiShield.
Ogni chiave appartiene a un tenant e porta solo gli scope di lettura di cui ha bisogno.
Un amministratore crea la chiave nella console, con un nome, una scadenza e solo gli scope necessari. Il token (hsk_…) viene mostrato una sola volta. Per agire come una persona specifica, ad esempio dalla CLI o da un assistente, si usa OAuth 2.1 con PKCE.
Le raccolte accettano page (da 1) e per_page (da 1 a 200, 50 per impostazione predefinita) e restituiscono data e pagination. Gli errori hanno sempre lo stesso involucro, con un request_id per il supporto.
Prima lettura
curl -H "Authorization: Bearer $HODEISHIELD_API_KEY" "https://api.hodeishield.com/v1/vendors?per_page=5"Documento OpenAPI (senza autenticazione)
curl https://api.hodeishield.com/v1/openapi.jsonIl documento generato in /v1/openapi.json è la fonte autorevole; serve a generare client tipizzati.
| Operazione | Richiesta | Scope |
|---|---|---|
| Fornitori | GET /v1/vendors · /v1/vendors/{id} | supply_risk:read |
| Avvisi | GET /v1/alerts · /v1/alerts/{id} | supply_risk:read |
| Rischi | GET /v1/risks · /v1/risks/{id} | supply_risk:read |
| Controlli di conformità | GET /v1/compliance/controls?framework=… | compliance.<framework>:read |
| Postura di un framework | GET /v1/compliance/frameworks/{framework} | compliance.<framework>:read |
| Evidenze | GET /v1/evidence · /v1/evidence/{id} | evidence:read |
| Endpoint | GET /v1/endpoints | endpoints:read |
| Documento OpenAPI | GET /v1/openapi.json | nessuno |
La installi con Homebrew o Scoop, oppure scarichi l’archivio della Sua piattaforma dalla versione pubblicata, lo verifichi e lo collochi nel Suo PATH.
Homebrew (macOS e Linux) e Scoop (Windows x86_64) installano la versione 0.3.1 da repository pubblici di Hodeitek. L’eseguibile per Windows è firmato con Authenticode; quello per macOS non ancora.
Homebrew (macOS e Linux)
brew install hodeitek/hodeishield/hodeishieldHomebrew, se ha già aggiunto il tap
brew trust --formula hodeitek/hodeishield/hodeishieldScoop (Windows)
scoop bucket add hodeishield https://github.com/Hodeitek/scoop-hodeishield; scoop install hodeishieldOgni versione pubblica SHA256SUMS, un bundle Sigstore per archivio e la provenienza SLSA; dalla versione 0.2.0 pubblica anche uno SBOM CycloneDX per archivio. Gli archivi sono .tar.gz su Linux e macOS e .zip su Windows. Una firma cosign valida prova che l’archivio è stato costruito dal workflow release.yml del repository, avviato dal tag esatto che Lei si aspetta.
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 pushSi può anche compilare dal codice sorgente con cargo install --locked, fissando il tag della versione.
Con --json stampa la risposta dell’API senza modificarla; con --csv emette gli elenchi in CSV; con --all percorre tutte le pagine. I codici di uscita vanno da 0 a 8 e distinguono, ad esempio, credenziale assente, scope insufficiente, limite di utilizzo o licenza del tenant non in vigore.
Con una chiave API (script, CI)
export HODEISHIELD_API_KEY=hsk_...Come persona (browser, 2FA, passkey o SSO)
hodeishield loginhodeishield whoamihodeishield vendors list --criticality criticalhodeishield compliance posture nis2hodeishield alerts list --status open --all --json | jq -r '.[] | [.severity, .title] | @tsv'Un server ospitato, senza installazione. L’assistente vede ciò che vedrebbe Lei nel tenant che sceglie, e solo con gli scope che concede.
In un client MCP con server remoti e OAuth, aggiunga un connettore con questo URL. Il client scopre da solo il server di autorizzazione; Lei accede a app.hodeishield.com con i Suoi fattori abituali e sceglie un unico tenant.
URL del server MCP
https://mcp.hodeishield.com/mcpNessuno accetta un identificativo di tenant come parametro: non c’è modo di richiedere dati di un altro.
Verifichi sempre la firma prima di elaborare il corpo, e rifiuti le marche temporali vecchie.
Il segreto (whsec_…) viene mostrato una sola volta alla creazione del webhook; se lo perde, viene ruotato. Se il Suo endpoint non risponde 2xx, la consegna viene tentata fino a sei volte in totale (cinque nuovi tentativi, con attese tra 5 minuti e 24 ore); esauriti i tentativi, la consegna viene contrassegnata come fallita nella console e può rimetterla in coda.
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)Il verificatore è uno script bash e Python che può leggere per intero. Non chiama HodeiShield al momento della verifica.
Ambito: Prova integrità, origine e momento di ciò che è firmato. Non prova che le affermazioni siano vere, non sostituisce un audit e non esiste un registro di trasparenza. Passi sempre --expect-slug e --expect-issuer: senza di essi, anche l’attestazione valida di un’altra organizzazione risulta verificata. Il codice di uscita è 0 se verifica, 1 se fallisce e 2 se non è stato possibile controllare. Un documento autentico ma scaduto esce con 1 e la sua ultima riga inizia con «EXPIRED — the signature is valid».
Requisiti: bash 4, OpenSSL 3.5 o superiore e python3. Se la Sua macchina non li ha (macOS, Windows o Ubuntu 24.04), il repository del verificatore documenta come eseguire lo stesso script in un container con Docker o Podman; questo percorso installa OpenSSL e python3 all’avvio, perciò richiede la rete.
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.comPerché non lo scopra durante l’integrazione.
API, CLI e MCP sono di sola lettura. Per agire sul tenant si usa la console, e ACT passa sempre da una persona.
I comandi e l’output possono cambiare prima della 1.0. Fissi la versione nei Suoi script.
Il server non controlla ciò che il Suo client fa con i risultati. Consideri non attendibile il testo di terzi che contengono.
La disponibilità dell’API e dell’MCP dipende dalla Sua licenza e si conferma per tenant; la vediamo nella demo.
Non pubblichiamo SLA, tempi di risposta né disponibilità dell’API su questo sito.
L’API restituisce ciò che la piattaforma ha già raccolto: l’agente riferisce per ciclo e le scansioni sono periodiche.
Ciò che un team tecnico chiede di solito prima di iniziare.
No. L’API /v1 è di sola lettura: qualsiasi metodo diverso da GET restituisce 405. La CLI e l’MCP la utilizzano, quindi nemmeno loro scrivono.
Con una chiave API del tenant (hsk_…) creata da un amministratore con i soli scope di lettura necessari. Nella CLI basta esportare HODEISHIELD_API_KEY.
Ogni versione pubblica SHA256SUMS, bundle Sigstore e provenienza SLSA. Verifichi con cosign che l’archivio sia stato costruito dal workflow release.yml del repository per il tag esatto.
Ciò che vedrebbe Lei nell’unico tenant che sceglie al momento di concedere l’accesso e solo con gli scope che concede. Nessuno strumento accetta un identificativo di tenant.
Sì. Scarica la chiave pubblica da /api/public/attest/keys ed esegue il verificatore open source. Funziona offline con bash 4, OpenSSL 3.5 e python3, oppure in un container con Docker o Podman.
Nella demo vediamo che cosa leggere via API, CLI o MCP, e come si inserisce con i Suoi avvisi e le Sue pipeline.
Un colloquio di lavoro, senza impegno.