diff --git a/CITATION.cff b/CITATION.cff index cd6665a..087d8d8 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -16,7 +16,7 @@ abstract: > source-first — no build framework required — and integrates with any Markdown-based documentation system via a plugin adapter protocol. version: 0.5.0a4 -date-released: 2026-04-03 +date-released: 2026-04-08 url: "https://zenzic.pythonwoods.dev/" repository-code: "https://github.com/PythonWoods/zenzic" license: Apache-2.0 diff --git a/README.it.md b/README.it.md index 729da50..4a98611 100644 --- a/README.it.md +++ b/README.it.md @@ -12,7 +12,7 @@ SPDX-License-Identifier: Apache-2.0

- PyPI Version + PyPI Version Python Versions @@ -64,31 +64,28 @@ gli altri strumenti citati sono progetti di terze parti. --- -## v0.5.0a3 — La Sentinella - -- **Inizializzazione Intelligente**: `zenzic init` rileva `pyproject.toml` e offre di - incorporare la configurazione come `[tool.zenzic]` invece di creare un `zenzic.toml` - separato. Usa `--pyproject` per saltare il prompt. Auto-detection dell'engine in - entrambe le modalità. -- **Sentinel UI**: banner Indigo monolitico, gutter traceback con spaziatura a 2 spazi - (`│ 16 ❱`), sottolineature caret chirurgiche e respiro verticale tra i finding. -- **Target Agnostico**: `zenzic check all README.md` o `zenzic check all content/` - limita l'audit a un singolo file o directory. `VanillaAdapter` selezionato - automaticamente per target fuori da docs. -- **Plugin SDK**: `zenzic init --plugin ` scaffolda un pacchetto regole - pronto all'uso. Namespace pubblico `zenzic.rules` stabile — `BaseRule`, - `RuleFinding`, `CustomRule`, `Violation`, `Severity`. -- **Hybrid Adaptive Engine**: `scan_docs_references` seleziona esecuzione sequenziale - o parallela automaticamente in base alla dimensione del repository (soglia: 50 file). - Validazione ancore deterministica a due fasi elimina falsi positivi da race condition. -- **Z001/Z002 Split**: link rotti (Z001 errore) vs link a pagine orfane (Z002 warning). - Senza `--strict`, i warning orfani non bloccano la build. -- **Mutation-tested**: 86.7% mutation score (242/279 killed su `rules.py`). - 706 test, Hypothesis property-based testing con profili tiered. -- **Config `pyproject.toml`**: incorpora la configurazione Zenzic in `[tool.zenzic]` - quando `zenzic.toml` è assente. `zenzic.toml` vince sempre se entrambi esistono. -- **Zenzic Shield**: rilevamento credenziali (7 famiglie) + protezione path traversal. - Codice di uscita 2 riservato per eventi di sicurezza. +## v0.5.0a4 — La Sentinella Blindata + +- **Sentinella di Sangue (Exit Code 3)**: I link che escono da `docs/` e puntano a + directory di sistema del SO (`/etc/`, `/root/`, `/var/`, `/proc/`, `/sys/`, `/usr/`) + vengono classificati come `security_incident` e terminano con codice **3**. Priorità: + `3 > 2 (Shield) > 1 (errori)`. Non soppresso da `--exit-zero`. +- **Graph Integrity (Θ(V+E))**: Rilevamento dei link circolari tramite DFS iterativa + sull'intero grafo di link interni. Costruito una sola volta (Fase 1.5); ogni query + della Fase 2 è O(1). `CIRCULAR_LINK` è advisory (severità `info`) — i link di + navigazione reciproca sono struttura valida e non bloccano mai la CI. +- **Hex Shield**: Lo Shield ora rileva payload hex-encoded — 3 o più sequenze `\xNN` + consecutive — intercettando credenziali offuscate nei blocchi di codice. +- **Controllo Rumore (`--show-info`)**: I finding informativi sono soppressi per + default. Una nota a piè di pagina li conta: *"N info findings suppressed — usa + --show-info per i dettagli."* Disponibile su tutti i 7 comandi di check. +- **ZRT-005 Risolto — Bootstrap Paradox**: `zenzic init` funziona ora correttamente + in una directory completamente vuota. Il `zenzic.toml` generato include un blocco + Shield commentato con tutte le 8 famiglie di pattern rilevate. +- **Rigore Bilingue**: Parità di documentazione raggiunta tra Inglese e Italiano. + `checks.md`, `arch_gaps.md`, `architecture.md` e `INTERNAL_GLOSSARY.toml` (15 + termini canonici) ora disponibili in entrambe le lingue. +- **759 test. Preflight verde.** --- @@ -227,15 +224,18 @@ zenzic serve --port 9000 | `0` | Tutti i controlli selezionati sono passati | | `1` | Uno o più controlli hanno segnalato problemi | | **`2`** | **SECURITY CRITICAL — Zenzic Shield ha rilevato una credenziale esposta** | +| **`3`** | **SECURITY CRITICAL — Sentinella di Sangue ha rilevato un path traversal di sistema** | > **Attenzione:** -> Il **codice di uscita 2** è riservato esclusivamente agli eventi di sicurezza. Se -> `zenzic check references` esce con codice 2, una credenziale è stata trovata nella -> documentazione. Ruotare la credenziale immediatamente. - -Lo **Zenzic Shield** rileva 7 famiglie di credenziali (chiavi OpenAI, token GitHub, access key -AWS, chiavi live Stripe, token Slack, chiavi API Google e chiavi private PEM) su **ogni riga del -file sorgente** — incluse le righe dentro i blocchi di codice `bash`, `yaml` e senza etichetta. +> Il **codice di uscita 2** è riservato agli eventi Shield (credenziali esposte). Il **codice +> di uscita 3** è riservato alla Sentinella di Sangue (path traversal verso directory di sistema +> come `/etc/`, `/root/`). Entrambi non vengono mai soppressi da `--exit-zero`. Ruotare e +> verificare immediatamente. + +Lo **Zenzic Shield** rileva 8 famiglie di credenziali (chiavi OpenAI, token GitHub, access key +AWS, chiavi live Stripe, token Slack, chiavi API Google, chiavi private PEM e payload +hex-encoded) su **ogni riga del file sorgente** — incluse le righe dentro i blocchi di codice +`bash`, `yaml` e senza etichetta. Una credenziale in un esempio di codice è comunque una credenziale esposta. --- diff --git a/README.md b/README.md index 2f36bac..0992775 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ SPDX-License-Identifier: Apache-2.0

- PyPI Version + PyPI Version Python Versions @@ -63,31 +63,28 @@ referenced ecosystem tools are third-party projects. --- -## v0.5.0a3 Highlights — The Sentinel - -- **Smart Initialization**: `zenzic init` detects `pyproject.toml` and offers to - embed config as `[tool.zenzic]` instead of a standalone `zenzic.toml`. Use - `--pyproject` to skip the prompt. Engine auto-detection in both modes. -- **Sentinel UI**: monolithic Indigo banner, traceback gutter with 2-space - padding (`│ 16 ❱`), surgical caret underlines, and vertical breathing - between findings. -- **Agnostic Target**: `zenzic check all README.md` or `zenzic check all content/` - scopes audits to a single file or directory. `VanillaAdapter` auto-selected for - out-of-docs targets. -- **Plugin SDK**: `zenzic init --plugin ` scaffolds a ready-to-edit rule - package. `zenzic.rules` public namespace is stable — `BaseRule`, `RuleFinding`, - `CustomRule`, `Violation`, `Severity`. -- **Hybrid Adaptive Engine**: `scan_docs_references` selects sequential or parallel - execution automatically based on repository size (threshold: 50 files). - Deterministic two-phase anchor validation eliminates race-induced false positives. -- **Z001/Z002 Split**: broken links (Z001 error) vs orphan-page links (Z002 warning). - Without `--strict`, orphan warnings don't block the build. -- **Mutation-tested**: 86.7% mutation score (242/279 killed on `rules.py`). - 706 tests, Hypothesis property-based testing with tiered profiles. -- **`pyproject.toml` config**: embed Zenzic config in `[tool.zenzic]` when - `zenzic.toml` is absent. `zenzic.toml` always wins if both exist. -- **Zenzic Shield**: credential detection (7 secret families) + path traversal - protection. Exit code 2 reserved for security events. +## v0.5.0a4 Highlights — The Hardened Sentinel + +- **Blood Sentinel (Exit Code 3)**: Path traversal links that escape `docs/` and + target OS system directories (`/etc/`, `/root/`, `/var/`, `/proc/`, `/sys/`, + `/usr/`) are classified as `security_incident` and exit with code **3**. Priority + order: `3 > 2 (Shield) > 1 (errors)`. Never suppressed by `--exit-zero`. +- **Graph Integrity (Θ(V+E))**: Circular link detection via iterative DFS over the + full internal link graph. Built once (Phase 1.5); every Phase 2 per-query lookup + is O(1). `CIRCULAR_LINK` is advisory (`info` severity) — mutual navigation links + are valid documentation structure and never block CI. +- **Hex Shield**: The Shield now detects hex-encoded payloads — 3 or more consecutive + `\xNN` escape sequences — catching obfuscated credentials inside fenced code blocks. +- **Signal-to-Noise Control (`--show-info`)**: Advisory findings are suppressed by + default. A footer note counts them: *"N info findings suppressed — use --show-info + for details."* Available on all 7 check commands. +- **ZRT-005 Fixed — Bootstrap Paradox**: `zenzic init` now works correctly in a + completely empty directory. The generated `zenzic.toml` includes a commented Shield + block listing all 8 detected credential pattern families. +- **Bilingual Rigor**: Full documentation parity achieved across English and Italian. + `checks.md`, `arch_gaps.md`, `architecture.md`, and `INTERNAL_GLOSSARY.toml` (15 + canonical terms) are now available in both languages. +- **759 tests. Preflight green.** --- @@ -419,11 +416,12 @@ zenzic serve --no-preflight | `0` | All selected checks passed | | `1` | One or more checks reported issues | | **`2`** | **SECURITY CRITICAL — Zenzic Shield detected a leaked credential** | +| **`3`** | **SECURITY CRITICAL — Blood Sentinel detected a system-path traversal** | > **Warning:** -> **Exit code 2** is reserved exclusively for security events. If `zenzic check references` exits -> with code 2, a secret (OpenAI API key, GitHub token, or AWS access key) was found embedded in a -> reference URL inside your documentation. Rotate the credential immediately. +> **Exit code 2** is reserved for Shield events (leaked credentials). **Exit code 3** is +> reserved for Blood Sentinel events (path traversal to OS system directories such as +> `/etc/`, `/root/`). Both are never suppressed by `--exit-zero`. Rotate and audit immediately. --- @@ -463,7 +461,7 @@ Build aborted. Rotate the exposed credential immediately. 1. The Shield runs *inside* Pass 1 — before Pass 2 validates links and before any HTTP ping is issued. A document containing a leaked credential is never used to make outbound requests. 2. Patterns use exact-length quantifiers (`{48}`, `{36}`, `{16}`) — no backtracking, O(1) per line. -3. Seven credential families are covered out of the box: +3. Eight credential families are covered out of the box: | Type | Pattern | | --- | --- | @@ -474,6 +472,7 @@ Build aborted. Rotate the exposed credential immediately. | Slack token | `xox[baprs]-[0-9a-zA-Z]{10,48}` | | Google API key | `AIza[0-9A-Za-z\-_]{35}` | | PEM private key | `-----BEGIN [A-Z ]+ PRIVATE KEY-----` | +| Hex-encoded payload | 3+ consecutive `\xNN` escape sequences | 1. **No blind spots** — the Shield scans every line of the source file, including lines inside fenced code blocks (`bash`, `yaml`, unlabelled, etc.). A credential committed inside a code