deepsec

deepsec è uno scanner di vulnerabilità basato su agenti che puoi eseguire nella tua infrastruttura, ottimizzato per effettuare revisioni on-demand di tutto il codice in repository esistenti su larga scala.

deepsec è progettato per far emergere problemi difficili da trovare che si nascondono nelle applicazioni da molto tempo. È configurato per utilizzare i migliori modelli ai massimi livelli di ragionamento (regolabili tramite --thinking-level, vedi docs/models.md), il che significa che le scansioni possono costare migliaia o addirittura decine di migliaia di dollari per codebase di grandi dimensioni. I nostri clienti hanno ritenuto che il costo ne valesse la pena per la velocità con cui sono riusciti a correggere vulnerabilità che altrimenti sarebbero rimaste irrisolte.

Per codebase di grandi dimensioni, il lavoro si distribuisce in parallelo su macchine worker. Se un'esecuzione viene interrotta o termina con errore a metà, basta rieseguire lo stesso comando — deepsec riprende da dove aveva interrotto, saltando i file già analizzati e investigando solo il resto.

Per iniziare

Naviga alla radice del repository che vuoi scansionare, poi:

npx deepsec init       # creates .deepsec/ with this repo as the first project
cd .deepsec
pnpm install           # installs deepsec from npm

# Proceed as instructed by `init` output

Ora fai avviare l'installazione al tuo agente di codifica. Apri l'agente scelto e fornisci il prompt:

Leggi .deepsec/node_modules/deepsec/SKILL.md per comprendere lo strumento. Poi leggi .deepsec/data/<id>/SETUP.md e seguilo: sfoglia il README di questo repository, eventuali AGENTS.md/CLAUDE.md, e alcuni file di codice rappresentativi, poi sostituisci ogni sezione di .deepsec/data/<id>/INFO.md.

Mantienilo CORTO — puntare a 50–100 righe totali. Scegli 3–5 esempi per sezione, non un elenco esaustivo. Nomina primitive (helper di autenticazione, middleware) ma senza numeri di riga. Salta le categorie CWE generiche — i matcher integrati le coprono. Copri solo ciò che è specifico del progetto. INFO.md viene iniettato in ogni batch di scansione; un contesto verboso indebolisce il segnale.

Poi esegui la scansione dall'interno di .deepsec/:

pnpm deepsec scan
pnpm deepsec process    
pnpm deepsec revalidate # optional, cuts FP rate
pnpm deepsec export --format md-dir --out ./findings

Se ritieni che deepsec dovrebbe esaminare più parti del codice, fornisci il documento sulla scrittura dei matcher per trovare punti di partenza più preziosi nella tua codebase.

Documentazione

• docs/getting-started.md — guida alla prima scansione
• docs/reviewing-changes.md — process --diff per la revisione delle PR e il gating CI
• docs/supported-tech.md — framework ed ecosistemi che deepsec riconosce nativamente
• docs/writing-matchers.md — fai espandere il tuo set di matcher dal tuo agente di codifica
• docs/configuration.md — riferimento a deepsec.config.ts
• docs/plugins.md — creazione di plugin
• docs/models.md — selezione del modello, valori predefiniti, rifiuti, modelli futuri
• docs/vercel-setup.md — AI Gateway + chiavi/token di Vercel Sandbox
• docs/architecture.md — interni della pipeline
• docs/data-layout.md — schemi di data/ (FileRecord, RunMeta, …)
• docs/faq.md — costo, scelta del modello, modalità sandbox, tasso di falsi positivi
• samples/ — punti di partenza copia-incolla (attualmente: webapp/)

Provider AI

Quando viene eseguito localmente, deepsec utilizza il tuo abbonamento esistente a claude / codex se hai effettuato l'accesso su questa macchina. Gli abbonamenti (Claude Pro/Max, ChatGPT Plus) sono utili per valutare deepsec ma generalmente non hanno abbastanza capacità per scansioni complete del repository.

Per scansioni reali, utilizza Vercel AI Gateway. Una singola chiave copre sia Claude che Codex, e le quote predefinite del gateway sono dimensionate per una ricerca altamente concorrente.

AI_GATEWAY_API_KEY=vck_...

Vedi docs/vercel-setup.md per ottenere una chiave e per la configurazione di Vercel Sandbox. Per bypassare il gateway, imposta esplicitamente ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL (o la coppia OpenAI). I valori espliciti hanno sempre la priorità rispetto all'espansione di AI_GATEWAY_API_KEY.

Se un'esecuzione di process o revalidate si arresta perché la credenziale upstream ha esaurito la quota o i crediti, deepsec si ferma con garbo e ti indica dove ricaricare. Riesegui lo stesso comando in seguito e riprenderà da dove aveva interrotto.

Esecuzione distribuita (opzionale)

I grandi monorepo possono distribuire il lavoro su microVM di Vercel Sandbox:

pnpm deepsec sandbox process --project-id my-app --sandboxes 10 --concurrency 4

Richiede un account Vercel. L'albero di lavoro locale viene archiviato in un tarball e caricato; .git è escluso. Sono supportati sia i token OIDC (locali) che i token di accesso (CI) — vedi docs/vercel-setup.md.

Modello di sicurezza di deepsec stesso

Tratta deepsec come un agente di codifica con accesso completo alla shell sull'ambiente in cui è in esecuzione. È progettato per funzionare su input attendibili (il tuo codice sorgente) ma potresti comunque preoccuparti di un'iniezione di prompt a causa di dipendenze esterne o codice venduto.

L'esecuzione in una sandbox (vedi sopra) limita sostanzialmente la potenziale esposizione:

• Le chiavi API per gli agenti di codifica vengono iniettate all'esterno della sandbox e quindi non possono essere esfiltrate
• Per le sandbox worker, l'uscita di rete dalla sandbox è limitata agli host degli agenti di codifica (l'uscita è consentita durante il processo di bootstrap, ma questo non esegue l'agente di codifica)

Riferimento ai flussi di lavoro

Licenza

Apache 2.0. Vedi LICENSE e NOTICE.