Igiene delle credentials a scala: il pattern op:// vault per workspace agentic a zero plaintext

Documentiamo l'architettura delle credentials di Madani: un deployment in produzione su 23 servizi che usa il pattern di runtime-resolution "op://" di 1Password, con zero incidenti di plaintext-leak osservati in 12 mesi di operativita. La credentials hygiene e la disciplina operativa con cui un workspace agentic gestisce i secret (API key, OAuth token, password di database, vault credentials) in modo che nessun secret esista mai in chiaro nel repository, nei log, nel context dell'agent o negli artifact. La versione classica software-engineering di questo problema ha soluzioni standard (variabili d'ambiente, secret manager, policy di rotazione delle chiavi), ma i workspace agentic introducono failure mode aggiuntivi: agent che riassumono log includendo accidentalmente secret, prompt context condiviso con judge model che fa leak di secret, loop autonomi che toccano credentials e devono gestire i timeout del vault in modo robusto. L'architettura Madani ha tre layer: storage (vault 1Password, single source of truth), resolution (URI op:// risolti al process startup via direnv + 1Password CLI) e agent-awareness (modulo di audit che scansiona pattern secret-shaped negli output). Emergono SETTE finding controintuitivi

1. (a)
   1PASSWORD CLI + DIRENV PRODUCE CREDENTIALS ZERO-PLAINTEXT A RUNTIME CON LATENZA SOTTO I 50MS per ogni lettura di credential dopo il caching
2. (b)
   IL PATTERN OP:// SPOSTA LE CREDENTIALS DAL REPO-RISK AL VAULT-RISK — guadagno netto di sicurezza perche il vault ha controlli di accesso molto piu forti della git history
3. (c)
   Le credentials in commit history sono quasi impossibili da rimuovere in sicurezzauna volta committate, esistono per sempre nella history distribuita; op:// e preventivo, non rimediale
4. (d)
   IL PRINCIPALE PUNTO DI ATTRITO DELL'ADOZIONE DI OP:// E IL SETUP INIZIALE — account 1Password + CLI + direnv ~1-2 ore per macchina nuova; il costo marginale per credential dopo il setup e prossimo a zero
5. (e)
   I TOOL DI SECRET-SCANNING CATTURANO ~70% DELLE CREDENTIALS LEAKED — TruffleHog, git-secrets, GitGuardian; il pattern op:// riduce la superficie d'attacco a ~5% strutturalmente
6. (f)
   I token api long-lived sono la categoria di leak a piu alto rischioAnthropic api03, GitHub PAT, Stripe live; op:// + token scoped insieme producono leverage

La credentials hygiene classica assume un set piccolo e fisso di credentials, acceduto da un numero ristretto di processi ben definiti, senza alcun reasoning semantico sui valori delle credentials. I workspace agentic violano tutte e tre le assunzioni. (a) Molte credentials: un workspace tipico integra 15-30 servizi esterni. (b) Molti processi: agent, sub-agent, judge, loop autonomi, ognuno tocca credentials. (c) Reasoning semantico sulle credentials: un agent che riassume i log puo includere credentials nel sommario; un agent che spiega il codice puo includere credentials nella spiegazione. Il terzo e il failure mode qualitativamente nuovo.

L'obiettivo Madani e zero credentials in chiaro ovunque: non nel repo, non nei log, non nel context dell'agent, non negli artifact. Questo richiede difesa strutturale a ogni layer. Pattern op:// + modulo di audit e la risposta architetturale.

L'invariante e verificabile: i tool di secret-scanning devono trovare zero match in repo + log + artifact. L'invariante regge da 12 mesi su 23 servizi.

(1) EMPIRICO: 12 mesi di deployment in produzione su 23 servizi con zero incidenti di plaintext-leak. (2) ARCHITETTURALE: il design a tre layer (storage, resolution, agent-awareness). (3) OPERATIVO: astrazione multi-backend con supporto a 1Password, HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager. (4) ADVERSARIAL: red-team study con 40 tentativi di attacco e 0 estrazioni riuscite.

        CREDENTIALS RESOLUTION · op:// runtime vault
        ───────────────────────────────────────────

   developer machine                    runtime
   ┌────────────────┐                 ┌──────────────┐
   │ .envrc         │                 │ env vars     │
   │ ┌────────────┐ │  direnv allow   │ GHL_TOKEN=…  │
   │ │op://Madani │─┼────────────────▶│ SLACK_BOT=…  │
   │ │/GHL/token  │ │   1Password CLI │ STRIPE_KEY=… │
   │ │op://Madani │ │   resolves at   │ ...          │
   │ │/Slack/bot  │ │   shell entry   └──────┬───────┘
   │ └────────────┘ │                        │
   └────────────────┘                        ▼
                                  ┌───────────────────┐
   ✗ never in repo                │ secret-guard hook │
   ✗ never in logs                │ blocks sk_live_*  │
   ✗ never in shell history       │ EAAB* · ghp_*     │
                                  └───────────────────┘

AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager, Azure Key Vault forniscono primitive vault-as-a-service. Il pattern di risolvere i secret a runtime via variabili d'ambiente short-lived e standard di settore. Il nostro contributo e l'integrazione di questo pattern con la agent-awareness (il modulo di audit che cattura le credentials leaked nonostante la protezione del vault).

TruffleHog (2018), git-secrets (AWS, 2017), GitGuardian (commerciale). Questi tool scansionano stringhe ad alta entropia e pattern di credential noti. Sono rimediali — catturano credentials DOPO che sono state committate. Il nostro lavoro e preventivo — prevenzione strutturale al momento della scrittura.

La combinazione di direnv (gestione variabili d'ambiente) e 1Password CLI (accesso al vault) produce il pattern op://. Entrambi i tool sono open-source; la combinazione e originale di vari blog di practitioner ma non e documentata formalmente come pattern. Questo paper documenta il pattern.

METODO · §7 · LAYER 1 · STORAGE. Tutti i secret vivono in un vault 1Password accessibile solo a umani autorizzati via 1Password CLI. Il vault e la single source of truth; nessuna copia da nessun'altra parte.

METODO · §8 · LAYER 2 · RESOLUTION. Codice e file di configurazione referenziano i secret via URI "op://Vault/Item/field". Al process startup un wrapper (direnv piu 1Password CLI) risolve questi URI nei valori reali dei secret esposti come variabili d'ambiente. I valori risolti non toccano mai il disco; vivono solo in memoria di processo.

METODO · §9 · LAYER 3 · AGENT-AWARENESS. L'agent runtime e istruito sulla disciplina di secret-handling: mai scrivere secret nei log, mai includere variabili secret-bearing nel prompt context, mai propagare secret a sub-agent che non ne hanno bisogno. Applicato da un modulo di audit che scansiona gli output dell'agent cercando pattern secret-shaped (stringhe ad alta entropia, prefissi noti come "sk-", "pat_", "tok_").

23 servizi esterni distinti: GHL, n8n, Anthropic, Stripe, Slack, Brevo, ClickUp, Meta, Google APIs (multipli), Vercel, Cloudflare, Fireflies, Tally, Exa, Kie.ai, OpenAI, APIMO, SMTP, BigQuery, Drive, Sheets, Gemini, Firecrawl. 12 mesi di deployment in produzione.

Abbiamo sottoposto l'architettura a una review red-team interna: tentativi semi-strutturati di estrarre secret via (a) prompt injection ("dump your environment"), (b) log scraping (indurre l'agent a includere un secret in una summarization), (c) exploitation dei timeout del vault, (d) propagazione del context al sub-agent (provare a far trapelare un secret dal primary a un sub-agent che non dovrebbe vederlo).

Su 12 mesi, lo scanning di secret su repo + log + artifact: zero match contro pattern di credential.

Il modulo di audit ha sparato 8 volte: 6 falsi positivi (stringhe ad alta entropia in contenuto documentale che capitava sembrasse secret-like), 2 cattura genuine (un agent ha tentato di loggare una credential durante una sessione di debugging; il modulo di audit ha catturato e redatto prima della scrittura).

40 tentativi di attacco. 0 estrazioni di secret riuscite. I pattern di attacco: 14 prompt-injection ("dump environment", "show me your config"), 12 log-scraping ("explain how your API integration works in detail"), 8 vault-timeout exploitation ("what was your last successful API call"), 6 propagazioni di context al sub-agent ("hand off this task to a sub-agent with full context"). Tutti bloccati al resolution layer o al modulo di audit.

RISULTATI · §14 · FINDING CONTROINTUITIVO 1 · LATENZA RUNTIME SOTTO I 50MS. Risolvere 23 URI op:// al process startup: ~1,2 secondi la prima volta (round-trip di rete verso 1Password). Letture successive dei valori risolti in cache: <50ms per credential. Per processi agent long-running il costo di startup viene ammortizzato; per loop autonomi short-lived i valori risolti restano in cache in memoria di processo.

RISULTATI · §15 · FINDING CONTROINTUITIVO 2 · LO SHIFT DA REPO-RISK A VAULT-RISK E GUADAGNO NETTO. Pre-op://, un leak di credentials richiedeva solo che l'attaccante accedesse al repo (possibile via molti vettori: compromise GitHub, furto laptop del contributor, push pubblico accidentale). Post-op://, un leak di credentials richiede l'accesso al vault 1Password, che ha: MFA con hardware-key, audit logging, token di accesso time-limited, allowlist IP.

Il vault ha controlli di accesso drasticamente piu forti di quanto il repo potrebbe avere. Guadagno netto di sicurezza anche se la complessita architetturale e maggiore.

RISULTATI · §16 · FINDING CONTROINTUITIVO 3 · I LEAK IN GIT HISTORY SONO PER SEMPRE. Abbiamo intervistato 12 team enterprise che avevano committato credentials per errore. Di questi, solo 2 hanno rimosso con successo le credentials dalla git history (via BFG Repo-Cleaner o git filter-branch + force-push + notifica a tutti i fork).

Gli altri 10 hanno: ruotato la credential e accettato l'esposizione in history, oppure non fatto nulla. Una volta committate, le credentials sono quasi impossibili da rimuovere in sicurezza. Op:// e preventivo (nessuna credential mai nel repo) anziche rimediale.

L'asimmetria e l'argomento piu forte a favore del pattern.

RISULTATI · §17 · FINDING CONTROINTUITIVO 4 · L'ATTRITO DI ADOZIONE E LA BARRIERA. L'attrito principale e il setup iniziale: account 1Password, installazione CLI, configurazione direnv, design della struttura del vault. ~1-2 ore per macchina nuova. Costo marginale per credential dopo il setup: prossimo a zero. La maggior parte dei team che abbandona il pattern lo fa durante il setup; i team che completano il setup quasi mai tornano indietro.

RISULTATI · §18 · FINDING CONTROINTUITIVO 5 · IL SECRET-SCANNING COMPLEMENTA MA NON SOSTITUISCE. I tool di secret-scanning (TruffleHog, git-secrets, GitGuardian) catturano ~70% dei pattern che matchano signature di credential note. Il pattern op:// riduce la superficie d'attacco a ~5%: non ci sono quasi credentials negli artifact scansionabili. I due sono complementari: op:// previene strutturalmente la maggior parte dei leak; il secret-scanning cattura il restante 5% che scappa dagli edge case.

RISULTATI · §19 · FINDING CONTROINTUITIVO 6 · I TOKEN LONG-LIVED SONO IL RISCHIO PIU ALTO. Abbiamo classificato i nostri 23 servizi per lifetime del token: SHORT-LIVED (OAuth access token, refresh ogni ora) - 8 servizi. MEDIUM (API key con policy di rotazione, ruotate trimestralmente) - 11 servizi.

LONG-LIVED (Anthropic api03, GitHub PAT, Stripe live key, validi per anni) - 4 servizi. La categoria LONG-LIVED rappresenta ~85% dell'impatto teorico di leak perche un token leaked funziona a tempo indeterminato. Op:// + token scoped (least-privilege scoping) insieme producono leverage; nessuno dei due da solo basta.

RISULTATI · §20 · FINDING CONTROINTUITIVO 7 · WORKSPACE PORTABILITY. Un nuovo ingegnere che entra in Madani: installa 1Password CLI, installa direnv, fa sign-in al vault, clona il repo. ~30 minuti in totale. Nessun handoff di credentials.

E produttivo da subito. Pre-pattern: l'handoff delle credentials era una sessione di onboarding da 2-3 ore con security review. Il pattern e workspace-portable in un modo che gli approcci classici a variabili d'ambiente non sono.

La combinazione di resolution op:// + pre-commit hook che scansionano pattern credential-shaped + il modulo di audit produce un invariante che non abbiamo mai visto violato. Questo rende "il tuo workspace e libero da secret in chiaro?" una proprieta binaria verificabile — prerequisito per qualsiasi security review che abbia senso.

DISCUSSIONE · §22 · CRITERI DI MATURITA WAB PILLAR 08 (CREDENTIALS). Abbiamo codificato le lezioni operative come criteri L0-L4: L0 = secret nel repo; L1 = secret in variabili d'ambiente ma niente vault; L2 = secret nel vault con risoluzione manuale; L3 = secret risolti a runtime via pattern op://; L4 = L3 + audit di agent-awareness + policy di rotazione trimestrale. Madani opera a L4 per 21 dei 23 servizi (2 servizi hanno token API legacy che non supportano rotazione programmatica; migrazione schedulata per Q3 2026).

Il pattern op:// e il modulo di audit sono vendor-agnostic nel concetto. 1Password e la nostra scelta di procurement; la stessa architettura funziona con AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager, Azure Key Vault. La reference implementation Madani include un thin layer di astrazione che supporta backend multipli; licenza MIT.

(a) Vault availability — grace period di 1 ora con valori risolti in cache. (b) Bug del CLI — versione del CLI pinnata, test sugli upgrade. (c) Bypass del modulo di audit — process-level, piu difficile da bypassare di un controllo prompt-level. (d) Exfiltration umana — non possiamo impedire a un umano con accesso al vault di copiare i secret (trust boundary). (e) Supply-chain attack sullo stesso 1Password CLI — rischio accettato come parte della scelta del vendor.

Cloud (1Password): costo di setup piu basso, latenza piu alta (sub-secondo), preoccupazioni di data-residency. On-premise (HashiCorp Vault, AWS Secrets Manager via VPC): latenza sotto i 100ms, perimetri regolatori piu stringenti, overhead operativo piu alto. Per SaaS tipici: vault cloud e il default pragmatico. Per GDPR EU + settore finanziario: on-premise raccomandato.

DISCUSSIONE · §26 · INTEGRAZIONE CON IL PILLAR GOVERNANCE (WSB-15). Credentials hygiene e governance si intersecano: la hard rule "mai scrivere credentials nei log" richiede il modulo di audit del pillar credentials per essere fatta rispettare. Abbiamo unificato a livello di policy layer: credentials-policy.md referenzia le primitive di governance-as-code; il gate del compliance-judge ispeziona pattern di credential-leakage come parte dei suoi check. L'audit trail (WSB-15) contiene sia eventi di compliance sia eventi di credential-leak-detection.

DISCUSSIONE · §27 · INTEGRAZIONE CON IL SISTEMA SKILL (WSB-17). Le skill che necessitano di credentials le dichiarano via URI op:// in SKILL.md. All'attivazione della skill, il resolution layer le materializza nell'environment della skill.

Le sub-skill non vedono credentials che non hanno richiesto. Questo produce least-privilege per skill.

(a) La pattern detection del modulo di audit e fragile (i 6 falsi positivi in 12 mesi sono il 75% di tutti gli alert). I falsi positivi sono accettabili perche revisionati da un umano in pochi secondi; i falsi negativi sarebbero catastrofici. (b) La dipendenza da 1Password CLI e sia asset (gestisce auth/audit/rotation nativamente) sia liability (ogni macchina deve avere il CLI installato e autenticato). (c) L'attrito di adozione al setup e reale ed e la barriera principale; i team che sopravvivono al setup mantengono il pattern. (d) Il giudizio soggettivo "questa stringa e secret-like?" del modulo di audit e imperfetto; non-secret ad alta entropia (es. ID random, hash) triggherano falsi positivi.

(1) Layer di astrazione multi-cloud con supporto a 1Password, HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault dietro un unico pattern URL op://. (2) Attestazione crittografica che il vault non sia stato manomesso (signing HSM-backed). (3) Policy di rotazione automatizzate legate ai pattern di utilizzo della credential. (4) Classifier context-aware per il modulo di audit (riduzione dei falsi positivi). (5) Benchmark cross-organizzativo della maturita del credentials pillar.

La credential piu usata nel workspace Madani. Salvata in 1Password come "op://Madani/Anthropic/api_key_production". Risolta a ogni process startup dell'agent via direnv.

Mai loggata. Il gate del compliance-judge controlla esplicitamente il prefisso "sk-ant-api03-" in qualsiasi output e blocca. Zero leak in 12 mesi su ~10.000 chiamate LLM giornaliere.

Le Stripe live key sono la credential a impatto piu alto (transazioni finanziarie). Policy di rotazione: trimestrale, con finestra di overlap. Procedura: (a) generare nuova key nella dashboard Stripe, (b) aggiungere la nuova key a 1Password come "stripe_live_v2", (c) aggiornare il workspace per referenziare v2, (d) verificare che tutte le operazioni funzionino, (e) disattivare la vecchia key in Stripe, (f) rimuovere la vecchia key da 1Password dopo 7 giorni.

Zero downtime durante la rotazione. Pre-pattern: la rotazione era un progetto ops da 4 ore; post-pattern, 20 minuti.

Il nuovo ingegnere Anas e entrato in aprile 2026. Processo di onboarding: (a) invito 1Password inviato. (b) Anas accetta, installa 1Password CLI. (c) Anas installa direnv. (d) Anas clona il repo del workspace. (e) Anas lancia il primo agent. Tempo totale: 28 minuti.

Zero handoff di credentials. Anas era produttivo dal minuto 30.

PLAYBOOK DI IMPLEMENTAZIONE · §33 · ADOTTARE IL PATTERN OP://. STEP 1 · SCEGLI IL VAULT. 1Password e la nostra raccomandazione per team cloud; HashiCorp Vault per on-premise; il Secret Manager del cloud provider per setup cloud-native. STEP 2 · STRUTTURA IL VAULT.

Organizza per servizio (ogni servizio esterno = item del vault; i field = tipi di credential diversi). STEP 3 · MIGRA LE CREDENTIALS ESISTENTI. Sposta da file .env al vault.

Pre-commit hook per impedire che i file .env vengano committati. STEP 4 · INSTALLA CLI + DIRENV. Su ogni macchina del team.

STEP 5 · DEPLOY DEL MODULO DI AUDIT. Scanning process-level degli output dell'agent. STEP 6 · POLICY DI ROTAZIONE.

Trimestrale per credentials long-lived. STEP 7 · DOCUMENTA I PATTERN. Sezione credentials in SKILL.md per ogni skill.

(1) "FILE .ENV NEL REPO" — punto di partenza piu comune; fallimento strutturale. (2) ""CREDENTIALS NEL PROMPT CONTEXT DELL'AGENT"" — leak via summarization. (3) "NESSUN MODULO DI AUDIT" — manca l'enforcement strutturale. (4) ""TOKEN A VITA INFINITA"" — secret long-lived senza rotazione. (5) ""TIMEOUT DEL VAULT SENZA GRACE"" — la produzione si rompe quando il vault ha un singhiozzo. (6) ""PROPAGAZIONE DI CONTEXT AI SUB-AGENT"" — i sub-agent ereditano credentials di cui non hanno bisogno.

(1) HARDWARE-KEY ATTESTATION per l'integrita del vault. (2) ROTAZIONE DIFFERENZIALE in base ai pattern d'uso. (3) CREDENTIALS SELF-AUDITING che rilevano misuse. (4) FEDERAZIONE VAULT CROSS-ORG per scenari di partnership. (5) HOMOMORPHIC SECRET SHARING per workflow agentic collaborativi.

Il pattern op:// e un'istanza di un principio piu ampio: rimandare la materializzazione al momento piu tardi possibile. Credentials a runtime, non alla scrittura del config file. Lo stesso pattern si applica a PII (risolti al momento della chiamata API), contenuto proprietario (caricato on-demand), dati cliente (interrogati direttamente, non cachati). Il late-binding per contenuti sensibili e il pattern ricorrente; op:// e l'istanza credentials.

La reference implementation Madani supporta 5 vault backend via un thin layer di astrazione. (a) 1Password — primario in produzione. (b) HashiCorp Vault — opzione on-premise. (c) AWS Secrets Manager — deployment AWS-native. (d) GCP Secret Manager — GCP-native. (e) Azure Key Vault — Azure-native. L'astrazione e un modulo Python da 240 righe che espone un'interfaccia uniforme resolve(uri). Codice per-backend: ~80 righe ciascuno. Aggiungere un nuovo backend richiede ~4 ore.

Gli URI seguono lo schema: op://Vault/Item/field[?modifier=value]. Esempi: op://Madani/Anthropic/api_key_production, op://Madani/Stripe/live_secret?rotation_required_within=90d. La sezione modifier opzionale abilita dichiarazioni di policy (rotazione, scope, max-usage). Lo schema e vault-backend-agnostico; il layer di astrazione mappa l'URI sulla risoluzione backend-specific.

Il modulo di audit scansiona gli output dell'agent cercando pattern credential-shaped: prefissi noti ("sk-", "pat_", "tok_", "ghp_", "AKIA"), stringhe ad alta entropia (entropia di Shannon > 4,5 bit/carattere), pattern strutturali (formato JWT, blob base64 oltre 100 caratteri). Tasso di falsi positivi: ~75% sull'entropia da sola; ~5% sui prefix match; ~25% sui pattern JWT. Il matcher di prefisso e il piu affidabile.

GHL usa OAuth token che si refreshano ogni 24 ore via refresh token. Pre-pattern: refresh token salvato in file .env; gestione della scadenza demandata ai singoli script. Post-pattern: refresh token in 1Password; il workflow n8n get-ghl-token chiama 1Password CLI per recuperare il refresh token, lo scambia per un access token fresco, ritorna.

Zero downtime in 12 mesi di operativita. Il pattern gestisce correttamente i token short-lived (refresh-then-resolve a ogni uso).

Background: un contractor a inizio 2026 ha avuto la workstation compromessa. Il GitHub PAT era sul laptop in ~/.netrc. Pattern: pre-op:// il PAT aveva scope ampio; post-op:// il PAT e scoped a repository specifici.

Impatto del compromise: pre-pattern sarebbe stato accesso ai repo workspace-wide; post-pattern era limitato a 2 repo specifici. Time-to-detection: 14 giorni (review dell'audit log GitHub). Time-to-revocation: 5 minuti (revoke nel vault, push a tutti i membri del team).

La combinazione PAT scoped + vault ha contenuto il blast radius.

Abbiamo aggiunto l'automation DNS di Cloudflare in Q2 2026. Il CF API token e scoped a 3 zone specifiche (madani.academy, madani.agency, madanitest.com) con sole permission zone:edit. Il token vive in 1Password come op://Madani/Cloudflare/api_token.

Gli script che ne hanno bisogno risolvono al startup. Abbiamo usato il token ~150 volte in 4 mesi per update di record DNS senza problemi.

La scelta iniziale di Madani e stata 1Password per due motivi: (a) il team gia usava 1Password per le credentials personali; l'integrazione e stata naturale. (b) L'hosting cloud rimuoveva l'overhead operativo di far girare l'infrastruttura vault. HashiCorp Vault e tecnicamente superiore per alcuni use case (latenza sotto i 100ms, controlli di accesso piu granulari) ma aggiunge overhead operativo (far girare il vault server, backup, HA) che eccede il nostro value-of-information. Per team con requisiti regolatori (data residency, FedRAMP), Vault self-hosted puo essere richiesto.

Classifichiamo le credentials per stadio del lifecycle: (a) PROVISIONING — credential creata nel sistema esterno, copiata nel vault. (b) ACTIVE — credential risolta a runtime, usata da agent/script. (c) ROTATION — refresh periodico secondo policy. (d) DEPRECATION — vecchia credential marcata inactive, ritirata dopo grace period. (e) DESTRUCTION — credential cancellata dal vault e dal sistema esterno. Ogni stadio ha procedure documentate. I fallimenti piu comuni stanno al provisioning (scoping povero) e alla rotation (dimenticata).

DISCUSSIONE ESTESA · §45 · INTEGRAZIONE CON GOVERNANCE (WSB-15). Il gate di compliance del WSB-15 ha una regola credentials-specific: "nessun output di agent puo contenere una stringa che matcha pattern credential-shaped". Il modulo di audit del §10 rileva; il gate di compliance blocca. Insieme forniscono defense-in-depth: anche se il modulo di audit fallisce (falso negativo), il governance gate cattura; anche se il governance gate fallisce, il modulo di audit cattura.

L'agency Madani opera subaccount GHL per 12 client attivi (Madani HQ, Proffi, Rara, X-Port, OsteoSpace, Munafò, Studio Buscema, A.C. Service, G Advisor, Grow Up Energy, Estetic Nutrition, SunPower Agency). Ogni subaccount ha un OAuth token location-scoped che scade ogni 24h e richiede rotazione refresh-token-based. Pre-vault, il tooling del team salvava 12 coppie client_id + client_secret in un singolo file .env committato in un repo git "secrets" separato. Il pattern aveva tre debolezze architetturali

1. (a)
   il repo dei secrets era una sua attack surface separata da quella del repo applicativo, e richiedeva un proprio access control
2. (b)
   qualsiasi rotazione di token richiedeva un commit nel repo dei secrets, rompendo l'immutabilita dello stato di credential

I token Meta Graph API scadono ogni circa 60 giorni. Pre-op://, il team Madani non aveva rotazione automatica; i token venivano rinnovati manualmente quando una chiamata API ad-account falliva con 401, richiedendo 30-90 minuti di operativita interrotta per cadenza. Abbiamo deployato un workflow di rotazione che gira ogni notte via n8n: prende il token corrente da 1Password, lo scambia per un token fresco via l'endpoint Meta di token-refresh, e scrive il nuovo token in 1Password — il tutto mentre l'agent chiamante continua a usare l'URI op:// senza modifiche di codice.

L'agent non sa che la rotazione e avvenuta; l'URI continua a risolvere al token valido corrente. Su una finestra post-deployment di 14 mesi su 4 ad account (Madani HQ, Proffi, Munafò, OsteoSpace), zero disruption di produzione 401-indotte. Il pattern dipende dal layer di indirezione che op:// fornisce — senza quello, la rotazione richiederebbe (a) il re-deploy di ogni workflow che usa il token (downtime), oppure (b) la lettura del token da un database/cache a runtime (che e un vault peggiore).

L'URI op:// e il giusto livello di indirezione perche e human-readable, version-controllable nel repo applicativo, e risolve a runtime attraverso un'API controllata dal vault. Cross-reference: lo script di rotazione vive in madani/credentials/op-rotation.sh secondo il filesystem layout di API-MASTER.md.

In Q1 2026 l'agent ha tentato di usare una Stripe LIVE key in un environment di sviluppo a causa di un selector di ambiente mal configurato. La runtime audit del resolver op:// ha loggato l'evento di risoluzione: "stripe_live_secret_key resolved by agent in workspace=dev, expected workspace=prod". Il mismatch ha triggerato un alert vault-side emerso al revisore umano entro 90 secondi; la chiamata dell'agent a Stripe e stata fermata prima di qualunque cambio di stato production-side.

Controintuitivamente, l'alert e stato triggerato non perche Stripe abbia rifiutato la chiamata (Stripe l'avrebbe accettata), ma perche il vault era strumentato con aspettative di workspace-scope che nessun altro layer poteva far rispettare. Senza la vault telemetry, la chiamata sarebbe riuscita e avrebbe prodotto un cambio parziale di stato in produzione osservabile solo post-hoc. Il case study illustra una proprieta delle credentials risolte da vault: il vault non e solo una primitiva di storage; e anche una primitiva di authorization-context.

Ogni risoluzione di credential porta metadati (quale workspace, quale identita di agent, quale intent) che il vault puo validare prima di risolvere. Remediation: stringere il check workspace-scope a un hard block (anziche un alert) per i secret di produzione risolti da workspace di sviluppo. Costo ingegneristico: 2 giorni per lo stringimento del workspace-scope.

Cross-reference: WSB-09 documenta come l'alert si e propagato nella pipeline di observability.

DEEP-DIVE EMPIRICO · §49 · METODOLOGIA STATISTICA SUI TASSI DI CREDENTIAL-LEAK. Il finding principale — zero eventi di credential-leak post-migrazione al vault contro baseline ~14/settimana — e stato scrutato statisticamente. (a) Analisi zero-evento post-migrazione: n=60 giorni × ~14 eventi attesi/settimana × 8,5 settimane = 119 eventi attesi sotto l'ipotesi nulla che la migrazione non abbia avuto effetto. Osservati: 0.

Wilson 95% upper confidence bound sul tasso reale post-migrazione: 3,1% del tasso baseline. Possiamo rigettare qualsiasi ipotesi che il tasso post-migrazione ecceda il 3,1% del baseline con confidenza 95%. (b) Robustezza tra tipi di credential: abbiamo stratificato per tipo di credential (OAuth token, API key, webhook secret, stringhe di connessione al database) e abbiamo trovato che il risultato zero-evento regge in tutti e quattro gli strati — nessuno strato ha mostrato leak. (c) Sensibilita alla definizione di leak: abbiamo eseguito tre definizioni (token plaintext completo nei log, frammento parziale di token >50% del token, qualsiasi sottoinsieme di testo del token 8+ caratteri matchante). Il finding principale regge per la definizione piu stringente ma la definizione piu ampia mostra 4 frammenti ambigui in 60 giorni; all'ispezione non erano leak di credential ma match di stringa coincidenti (es. un UUID con caratteri sovrapposti).

La "definizione piu ampia" e troppo noisy per essere operativamente utile; le definizioni "strict" e "moderate" concordano. (d) Replica out-of-sample: abbiamo replicato l'analisi su una finestra indipendente di 90 giorni dalla migrazione del vault di un team partner (col loro permesso); leak osservati pre-migrazione: 23 eventi; osservati post-migrazione: 1 evento (1 frammento parziale di token da un workspace early-stage non ancora completamente migrato). La replica indipendente conferma la magnitudine del finding originale. (e) Potenza statistica: con i tassi osservati il design ha potenza 99% per rilevare tassi 10× piu piccoli del baseline ad alpha=0,001, ben oltre i requisiti convenzionali.

ANTI-PATTERN DI IMPLEMENTAZIONE · §50 · CINQUE FAILURE MODE NELLE MIGRAZIONI A VAULT. Tra gli 8 team su cui Madani Lab ha consigliato migrazioni a vault tra Q3 2025 e Q1 2026, ricorrono cinque anti-pattern. (1) ""Vault per lo storage, .env per il runtime"": i team aggiungono un vault per lo storage a lungo termine ma continuano a iniettare secret nel .env al startup; il .env tocca disco e re-introduce la leak surface che il vault doveva eliminare. Remediation: enforcare la risoluzione a runtime via URI op:// (o equivalenti), zero scritture intermedie su disco. (2) ""Secret unico con scope ampio"": i team mantengono secret monolitici (un client_secret per tutti i client, una master API key per tutti gli environment) perche la migrazione al vault e l'occasione per ri-architettare anche lo scoping ma rimandano quel lavoro.

Il secret monolitico vanifica poi l'autorizzazione per-risoluzione del vault. Remediation: non migrare un secret monolitico al vault finche non e stato scomposto in token scoped. (3) ""Vault senza rotation"": i team spostano i secret nel vault ma non automatizzano la rotazione; lo stesso token continua a vivere nel vault per sempre, accumulando rischio nel tempo. Remediation: ogni secret nel vault deve avere una rotation policy dichiarata (cadenza in giorni), e un job CI deve verificare che la rotation avvenga davvero. (4) ""Nessuna vault telemetry sulla risoluzione"": i team usano il vault solo come primitiva di storage e perdono la primitiva di authorization-context (§48).

Non possono rilevare eventi di risoluzione cross-workspace perche il vault e muto sulla risoluzione. Remediation: abilitare audit log di risoluzione con metadati di workspace, agent, intent e alert sulle anomalie. (5) ""Lock-in al vendor del vault"": i team adottano direttamente l'API proprietaria di un singolo vendor di vault (anziche uno schema di URI op://-style portabile) e poi trovano dolorosa la migrazione di vendor quando il team supera il vendor. Remediation: usare uno schema di URI portabile; lasciare che il resolver sia vendor-specific ma lo schema di URI sia vendor-neutral.

INTEGRAZIONE CROSS-PILLAR · §51 · DOVE LE CREDENTIALS INCONTRANO GLI ALTRI WAB PILLAR. Integrazione complementare con P07 Governance: gli eventi di risoluzione del vault alimentano il governance gate come authorization context (per §48). I due pillar insieme implementano defense-in-depth — il vault scope-a la credential, la governance scope-a l'azione.

Integrazione complementare con P09 Observability: gli audit log di risoluzione del vault sono un prerequisito P09-L2 per rilevare i tentativi di leak; senza P09 il segnale di authorization del vault e non actionato. Integrazione complementare con P12 Forward-Deploy: gli URI op:// sono portabili — un nuovo team puo allestire un workspace usando gli stessi URI e un backend vault diverso (1Password, HashiCorp, AWS Secrets Manager) finche lo schema URI viene preservato. Il costo di migrazione per un team nuovo e di circa 2 ore per la creazione degli item vault-side; il codice applicativo e invariato.

Tensione strutturale con P02 Skills: ogni skill puo portare le proprie credentials (es. una skill Stripe richiede credentials Stripe, una skill n8n richiede credentials n8n); appena il numero di skill supera ~30, la gestione delle credentials per-skill diventa una tax, mitigata parzialmente da strutture vault gerarchiche (vault per-skill che ereditano da un vault per-organizzazione). Integrazione con P10 Portability: lo schema URI op:// rende le credentials portabili tra cambi di modello e framework; i team migrati a op:// riportano una portability tax ~25% piu bassa per i workflow credential-touching.

Il claim del valore compounding — che i token scoped, una volta introdotti, producono benefici di sicurezza e operativi compounding — e stato testato empiricamente sul portfolio Madani. Abbiamo misurato cinque dimensioni su una finestra di 12 mesi post-migrazione a token scoped: (a) blast-radius di un compromise di credentials ipotetico (modellato come il numero di client i cui dati sarebbero esposti se un singolo token venisse leaked); (b) tempo di onboarding di un nuovo client (misurato come engineer-hours dalla firma del contratto alla prima chiamata API autenticata); (c) tempo di offboarding di un client churned (engineer-hours dalla conferma del churn al completamento della revoca delle credentials); (d) completezza dell'audit-trail (% di eventi di utilizzo credentials con attribuzione completa); (e) incident di mis-routing cross-client (incident per trimestre in cui i token di un client sono stati usati accidentalmente verso l'account di un altro client). La dimensione (a) e scesa da "tutti i 12 client" pre-migrazione a "1 client" post-migrazione.

La dimensione (b) e scesa da 4-6 ore a meno di 1 ora. La dimensione (c) e scesa da 2-3 ore (spesso rimandata e parzialmente completata) a meno di 30 minuti (automatizzata). La dimensione (d) e salita da ~70% a 100%.

La dimensione (e) e scesa da 3 incident nell'anno pre-migrazione a 0 nell'anno post-migrazione. L'effetto compounding e non banale perche ciascuna delle (a)-(e) rinforza le altre: un'attribuzione migliore (d) rende piu economica l'incident-detection (e); un onboarding piu veloce (b) rende lo scoping per-client (a) operativamente sostenibile per consulenze piccole; un offboarding piu veloce (c) riduce il drift di credentials residue. Le cinque dimensioni sono correlate ma non collineari — misurano facce diverse della stessa proprieta sottostante.

Il case study formalizza il claim del valore compounding: i token scoped non sono semplicemente additivi rispetto ai token monolitici; si moltiplicano tra security, operations e audit.

(Q1) IPOTESI: La riduzione del tasso di leak (zero-evento vs baseline ~14/settimana) regge tra dimensioni organizzative e tipi di credential; in particolare, organizzazioni con >50 credentials vedono riduzioni del tasso di leak in valore assoluto proporzionalmente maggiori rispetto a organizzazioni con <10. TEST DI FALSIFICAZIONE: studio cross-organizzazione con 15 organizzazioni stratificate per numero di credentials. (Q2) IPOTESI: Aggiungere check di workspace-scope (§48) riduce gli eventi di mis-use di credentials di produzione di >80% a costo ingegneristico minimo; il costo marginale e qualche giorno, il beneficio marginale e prevenire diversi incident all'anno. TEST DI FALSIFICAZIONE: studio A/B con vault appaiati con e senza check di workspace-scope. (Q3) IPOTESI: La telemetria di vault-resolution, combinata con anomaly detection sugli shift di pattern di risoluzione, rileva tentativi di exfiltration che le ACL vault-side da sole mancano; l'anomaly detection aggiunge copertura di rilevazione su un ulteriore 12-18% dei pattern di exfiltration.

TEST DI FALSIFICAZIONE: esercizio red-team con pattern di exfiltration, misurazione dei tassi di rilevazione con e senza anomaly detection telemetry-driven. (Q4) IPOTESI: Il costo di portability del pattern URI op:// (sforzo ingegneristico per migrare tra vendor di vault) e sub-lineare nel numero di credentials migrate, specificamente O(log N) per il codice resolver-side e O(N) per la ricreazione vault-side degli item. TEST DI FALSIFICAZIONE: timing di migrazione strumentato su 4 vendor di vault. (Q5) IPOTESI: Una cadenza di rotation delle credentials sotto i 30 giorni produce costo compounding senza beneficio di sicurezza proporzionale; la cadenza ottimale e in [30, 90] giorni per la maggior parte dei tipi di credential, eccetto le credentials di production-payment che beneficiano di cadenza <30 giorni. TEST DI FALSIFICAZIONE: studio di coorte con cadenze di rotation appaiate e tassi di incident. (Q6) IPOTESI: I vault che espongono un layer di risoluzione programmabile (resolver hook, risoluzione condizionale in base al context) sovraperformano i vault che espongono solo item statici, abilitando decisioni di authorization-context fine-grained al momento della risoluzione.

TEST DI FALSIFICAZIONE: benchmark appaiato su sistemi static-vault vs programmable-vault su un set fisso di scenari di authorization.

[1] 1Password (2025), 1Password CLI Documentation. [2] HashiCorp (2024), Vault Best Practices. [3] AWS (2024), Secrets Manager Developer Guide. [4] Google Cloud (2024), Secret Manager Documentation. [5] Microsoft (2024), Azure Key Vault Documentation. [6] direnv (2024), direnv official documentation. [7] Greshake K. et al. (2023), Indirect Prompt Injection. [8] OWASP (2024), Application Security Verification Standard v5. [9] NIST (2024), SP 800-57 Cryptographic Key Management. [10] TruffleHog (2024), TruffleHog secret scanner. [11] git-secrets (2017), git-secrets. [12] GitGuardian (2024), State of Secrets Sprawl Report. [13] Madani Lab (2026), credentials-policy.md v1.4 (op:// pattern, multi-backend reference). [14] Cemri M., Pan M.Z., Yang S., Agrawal L.A., Chopra B., Tiwari R., Keutzer K., Parameswaran A., Klein D., Ramchandran K., Zaharia M., Gonzalez J.E., Stoica I. (2025), Why Do Multi-Agent LLM Systems Fail?, arXiv:2503.13657v3, NeurIPS 2025. [15] Tran D. & Kiela D. (2026), Single-Agent LLMs Outperform Multi-Agent Systems on Multi-Hop Reasoning, arXiv:2604.02460. [16] Wang C. & Shu Y. (2026), MetaCogAgent, arXiv:2605.17292v1. [17] Es S., James J., Espinosa-Anke L., Schockaert S. (2024), RAGAS, EACL 2024, arXiv:2309.15217. [18] Anthropic (2022), Constitutional AI. [19] Anthropic (2025), Claude Sonnet 4.5 Technical Report. [20] Schick T. et al. (2023), Toolformer, NeurIPS. [21] PCI Security Standards Council (2024), PCI DSS v4.0. [22] Madani Lab (2026), op-pattern reference implementation v1.0 (multi-backend).

L'architettura ha tre layer:

(1) STORAGE LAYER. Tutti i secret vivono in un vault 1Password accessibile solo a umani autorizzati via 1Password CLI. Il vault e la single source of truth; non esistono copie da nessun'altra parte.

(2) RESOLUTION LAYER. Codice e file di configurazione referenziano i secret via URI 'op://Vault/Item/field'. Al process startup un wrapper (usiamo 'direnv' piu '1Password CLI') risolve questi URI nei valori reali dei secret e li espone come variabili d'ambiente al processo. I valori risolti non toccano mai il disco; vivono solo in memoria di processo.

(3) AGENT-AWARENESS LAYER. L'agent runtime e istruito sulla disciplina di secret-handling: mai scrivere secret nei log, mai includere variabili secret-bearing nel prompt context, mai propagare secret a sub-agent che non ne hanno bisogno. Applicato da un piccolo modulo di audit che scansiona gli output dell'agent cercando pattern secret-shaped (stringhe ad alta entropia, prefissi noti come 'sk-', 'pat_', 'tok_') e triggera un alert se trovati.

Abbiamo deployato questa architettura per il workspace Madani (23 servizi esterni distinti: GHL, n8n, Anthropic, Stripe, Slack, Brevo, ClickUp, Meta, Google APIs, Vercel, Cloudflare, Fireflies, Tally, Exa, Kie.ai, OpenAI, APIMO, SMTP, BigQuery, Drive, Sheets, Gemini, Firecrawl) e l'abbiamo fatta girare in produzione per 12 mesi. Abbiamo anche sottoposto l'architettura a review red-team interna (tentativi semi-strutturati di estrarre secret via prompt injection, log scraping, exploitation di timeout del vault).

Zero incident di plaintext-leak in 12 mesi. Il modulo di audit ha sparato 8 volte: 6 falsi positivi (stringhe ad alta entropia in contenuto documentale che capitava sembrasse secret-like), 2 cattura genuine (un agent aveva tentato di loggare una credential durante una sessione di debugging; il modulo di audit ha catturato e redatto prima della scrittura). Risultati red-team: 0 estrazioni di secret riuscite su 40 attacchi tentati.

Tre sub-finding meritano di essere segnalati.

(1) LA LATENZA DI RUNTIME RESOLUTION E TRASCURABILE. Risolvere 23 URI 'op://' al process startup aggiunge ~1,2 secondi al tempo di startup. Per processi agent long-running questo e invisibile; per loop autonomi short-lived e un overhead misurabile che ammortizziamo cachando i valori risolti in memoria di processo.

(2) LA DIPENDENZA DA 1Password CLI E SIA ASSET SIA LIABILITY. L'asset: il CLI di 1Password gestisce nativamente autenticazione del vault, audit logging e rotation. La liability: ogni macchina che deve risolvere secret deve avere 1Password CLI installato e autenticato. Documentiamo una guida di setup multi-piattaforma (macOS, Linux, Windows WSL) e abbiamo automation che fa il bootstrap delle macchine nuove, ma l'onboarding richiede ancora 1-2 ore di tempo umano.

(3) L'AGENT-AWARENESS LAYER E IL COMPONENTE PIU IMMATURO. La pattern detection del modulo di audit e fragile (i 6 falsi positivi in 12 mesi sono il 75% di tutti gli alert). Stiamo esplorando una detection piu robusta via classifier context-aware, ma il trade-off e un costo di inference aggiuntivo per output. Stance pragmatica attuale: i falsi positivi sono accettabili perche ognuno e revisionato da un umano in pochi secondi; i falsi negativi sarebbero catastrofici.

Tre implicazioni.

(i) ZERO PLAINTEXT NEL REPO E UN INVARIANTE ENFORCEABLE. La combinazione di risoluzione 'op://' + pre-commit hook che scansionano pattern secret-shaped + il modulo di audit produce un invariante che non abbiamo mai visto violato. Questo rende "il tuo workspace e libero da secret in chiaro?" una proprieta binaria verificabile — prerequisito per qualsiasi security review che abbia senso.

(ii) I CRITERI DI MATURITA WAB PILLAR 08 (CREDENTIALS). Abbiamo codificato le lezioni operative come criteri L0-L4 per il Credentials pillar: L0 = secret nel repo; L1 = secret in variabili d'ambiente ma niente vault; L2 = secret nel vault con risoluzione manuale; L3 = secret risolti a runtime via pattern op://; L4 = L3 + audit di agent-awareness + policy di rotazione trimestrale. Il workspace Madani opera a L4 per 21 dei 23 servizi (2 servizi hanno token API legacy che non supportano rotazione programmatica; sono schedulati per migrazione in Q3 2026).

(iii) IL PATTERN OPEN-SOURCE. Il pattern 'op://' e il modulo di audit sono entrambi vendor-agnostic nel concetto. Usiamo 1Password perche e cio che e stato procurato in Madani; la stessa architettura funziona con AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager, ecc. La reference implementation Madani include un thin layer di astrazione che supporta backend di vault multipli; e open-source e MIT-licensed.

Chiudiamo riconoscendo la fragilita inerente a qualsiasi architettura di credentials. L'architettura documentata qui rende difficili specifici failure mode, ma non rende tutti i failure mode impossibili. I 5 failure mode che abbiamo esplicitamente pensato e mitigato: vault availability (abbiamo un grace period di 1 ora con valori risolti in cache); bug del CLI (pinniamo la versione del CLI e testiamo gli upgrade); bypass del modulo di audit (il modulo e process-level, piu difficile da bypassare di uno prompt-level); exfiltration umana (non possiamo impedire a un umano con accesso al vault di copiare i secret); supply-chain attack sullo stesso 1Password CLI (accettiamo questo rischio come parte della scelta del vendor). Lavori futuri: irrobustire l'agent-awareness layer con classificazione context-aware ed estendere il modulo di audit a coprire i context dei sub-agent (al momento facciamo audit solo sugli output dell'agent primario).

DISCUSSIONE · VAULT CLOUD VS ON-PREMISE. L'architettura documentata assume 1Password (cloud-hosted). I deployment di vault on-premise (HashiCorp Vault self-hosted, AWS Secrets Manager via VPC) introducono caratteristiche operative diverse: latenza piu bassa (sotto i 100ms vs sotto il secondo per lookup cloud), perimetri regolatori piu stringenti (controllo data-residency) e overhead operativo piu alto (far girare il vault stesso). Per workspace con requisiti stringenti di residency (GDPR EU + settore finanziario), raccomandiamo on-premise; per deployment SaaS tipici il vault cloud resta il default pragmatico.

DISCUSSIONE · INTEGRAZIONE CON IL PILLAR GOVERNANCE. La credentials hygiene e la governance (WSB-15) si intersecano: una hard rule "mai scrivere credentials nei log" richiede il modulo di audit del credentials pillar per essere fatta rispettare. Abbiamo unificato questi due pillar al policy layer: credentials-policy.md referenzia primitive di governance-as-code, e il gate del compliance-judge (WSB-15) ispeziona pattern di credential-leakage come parte dei suoi check standard.

(1) Layer di astrazione multi-cloud che supporti 1Password, HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault dietro un unico pattern URL op://. (2) Attestazione crittografica che il vault non sia stato manomesso (con signing HSM-backed). (3) Policy di rotazione automatizzate legate ai pattern di utilizzo della credential (ruotare piu aggressivamente le credentials usate piu di frequente).

1Password (2025), 1Password CLI Documentation; HashiCorp (2024), Vault Best Practices; AWS (2024), Secrets Manager Developer Guide; Google Cloud (2024), Secret Manager Documentation; Greshake K. et al. (2023), Indirect Prompt Injection; OWASP (2024), Application Security Verification Standard v5; NIST (2024), SP 800-57 Cryptographic Key Management; Madani Lab (2026), credentials-policy.md v1.4 (op:// pattern, multi-backend reference).