Passa al contenuto principale

Riferimento Zenzic GitHub Action

La PythonWoods/zenzic-action è l'action ufficiale CI per il sistema di qualità documentale Zenzic. In modalità non-audit esegue una pipeline di validazione in tre fasi: zenzic check all (finding strutturali), zenzic score (governance DQS: fail_under + suppression_cap) e zenzic score --check-stamp (freshness badge, abilitato di default). I finding vengono pubblicati in GitHub Code Scanning, mentre il gate di regressione qualità è gestito da zenzic diff quando è configurata una baseline.

Sorgente: github.com/PythonWoods/zenzic-action

Input​

InputDefaultRichiestoDescrizione
version<version>NoVersione di Zenzic da installare (latest o un pin di versione esatto). Fissa a una versione specifica per CI riproducibile.
formatsarifNoFormato di output: text, json o sarif.
sarif-filezenzic-results.sarifNoPercorso di output SARIF. Deve essere un percorso relativo all'interno del workspace. I percorsi assoluti e le sequenze di traversal .. vengono rifiutati dal wrapper.
upload-sariftrueNoCarica il SARIF in GitHub Code Scanning. Richiede il permesso security-events: write.
strictfalseNoTratta i warning come errori — promuove tutti i finding con severità warning ad error.
fail-on-errortrueNoFa fallire lo step del workflow su exit 1 (finding di qualità). Non sopprime exit 2 o 3.
config-file(auto)NoPercorso esplicito a un file di configurazione .zenzic.toml. Auto-scopre .zenzic.toml → .github/.zenzic.toml se omesso.
auditfalseNoModalità sovereign audit — bypassa tutti i commenti zenzic:ignore inline e tutte le voci governance.per_file_ignores. Rivela lo stato reale e non filtrato della documentazione.
diff-base(snapshot)NoPercorso a un file JSON di baseline per il confronto con zenzic diff. Quando impostato, l'action confronta il punteggio corrente contro questo file invece del .zenzic-score.json salvato. Usa un artefatto da main per implementare il Zenzic Quality Gate.
guard-scanfalseNoEsegue zenzic guard scan come step Defense-in-Depth prima del gate principale. Rileva credenziali hardcodate e pattern vietati in repo dove gli sviluppatori hanno bypassato i pre-commit hook. Il fallimento è sempre fatale — non governato da fail-on-error.
check-stamptrueNoEsegue zenzic score --check-stamp dopo la validazione di governance. Fa fallire il workflow quando i badge in badge_stamp_files sono stale. Imposta false per fare opt-out.

Output​

OutputDescrizione
sarif-filePercorso del file SARIF generato.
findings-countNumero totale di finding riportati. I finding di sicurezza (exit 2/3) impongono un minimo di 1.
scoreDocumentation Quality Score (0–100). Popolato quando format: json o quando diff-base è impostato. Stringa vuota negli altri modi.
suppression-debt-ptsPunti di Technical Debt detratti dal punteggio a causa delle soppressioni attive. 0 quando non ci sono soppressioni attive o quando la modalità audit è abilitata.
cap-exceeded"true" quando il CAP di soppressione è stato superato e ha bloccato la build; "false" altrimenti.

Contratto Exit Code​

CodiceNomeSignificatoSopprimibile?
0CleanTutti i controlli superati — punteggio superiore o uguale a fail_under—
1QualityUno o più finding; il punteggio potrebbe essere sotto fail_underSì (fail-on-error: "false")
2CredentialZ201 CREDENTIAL_SECRET rilevato — scansione interrottaMai
3Path TraversalZ202/Z203 PATH_TRAVERSAL rilevato — scansione interrottaMai

I codici di uscita 2 e 3 non vengono mai soppressi da fail-on-error: "false", --exit-zero o qualsiasi altro flag. Il wrapper lo applica incondizionatamente — i finding di sicurezza sono fatti, non finding da negoziare.

Il Zenzic Quality Gate​

Il Zenzic Quality Gate è il setup di enforcement PR raccomandato. Combina controlli strutturali, scoring di governance, freshness dei badge (opzionale) e confronto di regressione per bloccare i merge che riducono la qualità della documentazione.

Implementazione: vedi Integrazione CI/CD → Protocollo Diff per il workflow completo zenzic-quality-gate.yml.

Logica del Gate​

PR aperta
  └─ zenzic check all → exit 0/1/2/3 (finding)
  └─ zenzic score → exit 0/1 (fail_under + suppression_cap)
  └─ zenzic score --check-stamp (default: true) → exit 0/1 (freshness)
  └─ zenzic diff --base <baseline-main>
       ├─ punteggio stabile o migliorato → exit 0 ✅ La PR può fare merge

Il suppression debt è incluso nel punteggio usato per il confronto. Una PR che aggiunge soppressioni per nascondere finding mostrerà un punteggio inferiore. Gli exit di sicurezza (2/3) restano non sopprimibili e falliscono sempre l'esecuzione.

Modalità Sovereign Audit​

Quando audit: "true" è impostato, l'action viene eseguita con il flag --audit, che bypassa:

  • Tutti i commenti inline <!-- zenzic:ignore ZXXX -->
  • Tutte le voci [governance.per_file_ignores] in .zenzic.toml

Le exclusion zone (excluded_dirs, excluded_file_patterns) non vengono bypassate dalla modalità audit — definiscono il perimetro di scansione, non la policy di soppressione.

Casi d'uso:

  • Build notturne — verifica che il debt soppresso rimanga intenzionale.
  • Security Review — porta in superficie tutti i finding Z2xx indipendentemente dalla soppressione.
  • Audit pre-release — misura lo stato reale (non filtrato) della documentazione prima del rilascio.

Raccomandato: imposta fail-on-error: "false" nei workflow di audit. La modalità audit è osservazionale per design.

Scoperta della Configurazione​

PrioritàPosizioneQuando usata
1Input esplicito config-fileSempre rispettato quando fornito
2.zenzic.toml nella root del repositoryAuto-scoperto quando non c'è override esplicito
3.github/.zenzic.tomlFallback quando il file root è assente
—(nessuno trovato)Zenzic usa i suoi default integrati

Contratto di Intento Sovrano: se fornisci config-file: path/to/custom.toml e il file non esiste, l'action non fa fallback all'auto-scoperta. Ricevi un'annotazione ::warning (o un ::error fatale con strict: "true").

Architettura di Sicurezza​

GuardiaCosa blocca
Guardia Jailbreak SARIFsarif-file con percorso assoluto o traversal .. — rifiutato prima dell'esecuzione
Guardia Jailbreak Configconfig-file con percorso assoluto o traversal .. — rifiutato prima dell'esecuzione
Guardia Jailbreak diff-basediff-base con percorso assoluto o traversal .. — rifiutato prima dell'esecuzione
Controllo integrità SARIFSARIF JSON troncato (da SIGKILL/abort runtime) — emette ::warning, carica comunque
Contratto Exit CodeExit 2/3 si propagano sempre — non possono essere silenziati da nessun input o env var

Permessi​

Permessi minimi richiesti per le configurazioni più comuni:

ScenarioPermessi
Upload SARIF in Code Scanningcontents: read, security-events: write
Upload artefatto (baseline)contents: read
Solo audit (nessun upload)contents: read

Variabili d'Ambiente (Avanzato)​

La variabile d'ambiente ZENZIC_EXTRA_ARGS passa flag aggiuntivi direttamente alla CLI di Zenzic senza modificare gli input dell'action:

- uses: PythonWoods/zenzic-action@<version>
  with:
    version: "<version>"
  env:
    ZENZIC_EXTRA_ARGS: >-
      --exclude-url https://staging.example.com
      --exclude-url https://example.com/blog/unreleased-post

Il word-split è intenzionale (ogni coppia --exclude-url <url> diventa elementi argv separati). L'espansione dei glob è disabilitata nel wrapper prima di costruire l'array degli argomenti.

Vedi Anche​