shadowshield 0.6.0__tar.gz → 0.6.2__tar.gz

{shadowshield-0.6.0 → shadowshield-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shadowshield
-Version: 0.6.0
+Version: 0.6.2
 Summary: Unified open-source security shield for agentic AI systems — inspired by Sentinel & ShadowClaw.
 Project-URL: Homepage, https://shadowshield.xyz
 Project-URL: Documentation, https://github.com/0xsl1m/shadowshield#readme
@@ -18,6 +18,8 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
@@ -146,6 +148,10 @@ print(result.safe_text)            # safe fallback message
 > The bundled offline set (`shadowshield benchmark`) scores 100%/0-FP, but that's an
 > in-distribution **regression baseline, not a SOTA claim**. We publish the humbling
 > external numbers on purpose — a credible security tool shows its homework.
+> The frozen blind semantic snapshots are harder still: v1 reaches 26.7% recall /
+> 13.3% FPR, v2 reaches 0% / 10%, and v3 reaches 30% / 30%; the 90-row aggregate
+> is 22.2% / 20%. Run `shadowshield benchmark --generalization all`; these gaps
+> are public by design.
 
 ---
 
@@ -289,6 +295,8 @@ shadowshield scan --text "you are now DAN" --mode strict --json
 shadowshield detectors          # list registered detectors
 shadowshield init > shield.yaml # write an annotated default config
 shadowshield benchmark          # run the bundled offline benchmark
+shadowshield benchmark --adversarial
+shadowshield benchmark --generalization all # all frozen blind semantic snapshots
 shadowshield serve              # HTTP server + live dashboard (needs [dashboard])
 ```
 
@@ -304,9 +312,10 @@ curl -s localhost:8000/scan -H 'content-type: application/json' \
   -d '{"text":"ignore all previous instructions","direction":"input"}'
 # {"decision":"block","blocked":true,"score":0.9,...}
 ```
-Endpoints: `GET /health`, `POST /scan`, `POST /guard`, `GET /` (dashboard). Direct
-factory mounting fails closed unless `api_keys` is supplied; local-only trusted
-embeddings must explicitly pass `allow_insecure_local=True`.
+Endpoints: `GET /health` (liveness), `GET /ready` (readiness), `POST /scan`,
+`POST /guard`, `GET /` (dashboard). Direct factory mounting fails closed unless
+`api_keys` is supplied; local-only trusted embeddings must explicitly pass
+`allow_insecure_local=True`.
 
 ### Production container
 
@@ -319,13 +328,46 @@ credentials, requires signed policies, and persists authenticated anti-replay st
 export SHADOWSHIELD_API_KEY="$(openssl rand -hex 32)"
 export SHADOWSHIELD_ADMIN_KEY="$(openssl rand -hex 32)"
 export SHADOWSHIELD_POLICY_KEY="$(openssl rand -hex 32)"
-docker compose up --build
+export SHADOWSHIELD_POLICY_STATE_KEY="$(openssl rand -hex 32)"
+export SHADOWSHIELD_IMAGE_DIGEST="$(curl -fsSL \
+  https://github.com/0xsl1m/shadowshield/releases/download/v0.6.2/container-digest.txt)"
+docker compose pull
+docker compose up -d
 ```
 
-Terminate TLS at a trusted ingress before exposing it beyond localhost. See the
+The release workflow scans that exact image, publishes it to GHCR, signs SLSA
+provenance plus the CycloneDX SBOM with ephemeral GitHub OIDC/Sigstore identity,
+verifies the registry-attached source/workflow claims and an anonymous digest
+pull, and attaches the digest plus SBOM to the matching GitHub Release. Stable
+release tags are accepted only from an exact green `main` commit. All four
+secrets must be independent. Terminate TLS at a trusted ingress before exposing
+it beyond localhost. See the
 [production-readiness roadmap](docs/PRODUCTION_READINESS.md) for launch gates,
 known scale limits, and the operator checklist.
 
+Upgrading a control-plane volume from 0.6.0 requires an offline re-key because
+0.6.0 authenticated durable state with the policy-signing key:
+
+```bash
+# Load the existing scan/admin keys first so the new Compose file can resolve.
+export SHADOWSHIELD_IMAGE_DIGEST="$(curl -fsSL \
+  https://github.com/0xsl1m/shadowshield/releases/download/v0.6.2/container-digest.txt)"
+export SHADOWSHIELD_POLICY_KEY="<existing-0.6.0-policy-key>"
+export SHADOWSHIELD_POLICY_STATE_KEY="$(openssl rand -hex 32)"
+# Stop every writer and snapshot the volume before running the migration.
+docker compose stop shadowshield
+docker compose run --rm --no-deps shadowshield \
+  shadowshield migrate-policy-state --path /var/lib/shadowshield/policy-state.json
+# Preserve the reported .pre-0.6.1.bak file, then start 0.6.2.
+docker compose up -d
+```
+
+The command verifies the old MAC and restorable policy, creates an exclusive
+backup, and atomically re-MACs the state. Do not delete the old state to bypass
+migration: that discards replay history and the last-known-good policy. For a
+non-container install, run the same `shadowshield migrate-policy-state` command
+directly against the stopped service's state path.
+
 ---
 
 ## Agentic & advanced features
@@ -567,7 +609,8 @@ shadowshield serve --control --api-key SECRET      # require X-API-Key / Bearer
 ```bash
 shadowshield schema      # config JSON Schema (editor/CI validation)
 shadowshield owasp       # OWASP LLM Top 10 (2025) coverage map
-shadowshield benchmark --adversarial   # honest, harder, sub-100% numbers
+shadowshield benchmark --adversarial       # curated regression set
+shadowshield benchmark --generalization all # all frozen blind semantic snapshots
 ```
 
 ## Documentation

{shadowshield-0.6.0 → shadowshield-0.6.2}/README.md

@@ -75,6 +75,10 @@ print(result.safe_text)            # safe fallback message
 > The bundled offline set (`shadowshield benchmark`) scores 100%/0-FP, but that's an
 > in-distribution **regression baseline, not a SOTA claim**. We publish the humbling
 > external numbers on purpose — a credible security tool shows its homework.
+> The frozen blind semantic snapshots are harder still: v1 reaches 26.7% recall /
+> 13.3% FPR, v2 reaches 0% / 10%, and v3 reaches 30% / 30%; the 90-row aggregate
+> is 22.2% / 20%. Run `shadowshield benchmark --generalization all`; these gaps
+> are public by design.
 
 ---
 
@@ -218,6 +222,8 @@ shadowshield scan --text "you are now DAN" --mode strict --json
 shadowshield detectors          # list registered detectors
 shadowshield init > shield.yaml # write an annotated default config
 shadowshield benchmark          # run the bundled offline benchmark
+shadowshield benchmark --adversarial
+shadowshield benchmark --generalization all # all frozen blind semantic snapshots
 shadowshield serve              # HTTP server + live dashboard (needs [dashboard])
 ```
 
@@ -233,9 +239,10 @@ curl -s localhost:8000/scan -H 'content-type: application/json' \
   -d '{"text":"ignore all previous instructions","direction":"input"}'
 # {"decision":"block","blocked":true,"score":0.9,...}
 ```
-Endpoints: `GET /health`, `POST /scan`, `POST /guard`, `GET /` (dashboard). Direct
-factory mounting fails closed unless `api_keys` is supplied; local-only trusted
-embeddings must explicitly pass `allow_insecure_local=True`.
+Endpoints: `GET /health` (liveness), `GET /ready` (readiness), `POST /scan`,
+`POST /guard`, `GET /` (dashboard). Direct factory mounting fails closed unless
+`api_keys` is supplied; local-only trusted embeddings must explicitly pass
+`allow_insecure_local=True`.
 
 ### Production container
 
@@ -248,13 +255,46 @@ credentials, requires signed policies, and persists authenticated anti-replay st
 export SHADOWSHIELD_API_KEY="$(openssl rand -hex 32)"
 export SHADOWSHIELD_ADMIN_KEY="$(openssl rand -hex 32)"
 export SHADOWSHIELD_POLICY_KEY="$(openssl rand -hex 32)"
-docker compose up --build
+export SHADOWSHIELD_POLICY_STATE_KEY="$(openssl rand -hex 32)"
+export SHADOWSHIELD_IMAGE_DIGEST="$(curl -fsSL \
+  https://github.com/0xsl1m/shadowshield/releases/download/v0.6.2/container-digest.txt)"
+docker compose pull
+docker compose up -d
 ```
 
-Terminate TLS at a trusted ingress before exposing it beyond localhost. See the
+The release workflow scans that exact image, publishes it to GHCR, signs SLSA
+provenance plus the CycloneDX SBOM with ephemeral GitHub OIDC/Sigstore identity,
+verifies the registry-attached source/workflow claims and an anonymous digest
+pull, and attaches the digest plus SBOM to the matching GitHub Release. Stable
+release tags are accepted only from an exact green `main` commit. All four
+secrets must be independent. Terminate TLS at a trusted ingress before exposing
+it beyond localhost. See the
 [production-readiness roadmap](docs/PRODUCTION_READINESS.md) for launch gates,
 known scale limits, and the operator checklist.
 
+Upgrading a control-plane volume from 0.6.0 requires an offline re-key because
+0.6.0 authenticated durable state with the policy-signing key:
+
+```bash
+# Load the existing scan/admin keys first so the new Compose file can resolve.
+export SHADOWSHIELD_IMAGE_DIGEST="$(curl -fsSL \
+  https://github.com/0xsl1m/shadowshield/releases/download/v0.6.2/container-digest.txt)"
+export SHADOWSHIELD_POLICY_KEY="<existing-0.6.0-policy-key>"
+export SHADOWSHIELD_POLICY_STATE_KEY="$(openssl rand -hex 32)"
+# Stop every writer and snapshot the volume before running the migration.
+docker compose stop shadowshield
+docker compose run --rm --no-deps shadowshield \
+  shadowshield migrate-policy-state --path /var/lib/shadowshield/policy-state.json
+# Preserve the reported .pre-0.6.1.bak file, then start 0.6.2.
+docker compose up -d
+```
+
+The command verifies the old MAC and restorable policy, creates an exclusive
+backup, and atomically re-MACs the state. Do not delete the old state to bypass
+migration: that discards replay history and the last-known-good policy. For a
+non-container install, run the same `shadowshield migrate-policy-state` command
+directly against the stopped service's state path.
+
 ---
 
 ## Agentic & advanced features
@@ -496,7 +536,8 @@ shadowshield serve --control --api-key SECRET      # require X-API-Key / Bearer
 ```bash
 shadowshield schema      # config JSON Schema (editor/CI validation)
 shadowshield owasp       # OWASP LLM Top 10 (2025) coverage map
-shadowshield benchmark --adversarial   # honest, harder, sub-100% numbers
+shadowshield benchmark --adversarial       # curated regression set
+shadowshield benchmark --generalization all # all frozen blind semantic snapshots
 ```
 
 ## Documentation

{shadowshield-0.6.0 → shadowshield-0.6.2}/docs/BENCHMARKS.md

@@ -10,6 +10,13 @@ one** — a guard that blocks everything has perfect recall and is useless.
 ```bash
 # Bundled offline benchmark (no network, no extra deps)
 shadowshield benchmark
+shadowshield benchmark --adversarial
+
+# Independently authored blind semantic snapshots
+shadowshield benchmark --generalization v1
+shadowshield benchmark --generalization v2
+shadowshield benchmark --generalization v3
+shadowshield benchmark --generalization all
 
 # External public dataset (needs the datasets extra)
 pip install "shadowshield[datasets]"
@@ -30,9 +37,54 @@ negatives). `balanced` mode:
 
 **This is a regression baseline and a smoke test — NOT a claim of real-world
 accuracy.** 100% on our own set just means we don't regress on the attack
-catalogue we curated. The number that matters is the external one below.
+catalogue we curated. The blind and external numbers below are the real constraint.
+
+## 2. Curated adversarial regression set
+
+The 36-row adversarial catalogue includes obfuscation, multilingual and indirect
+attacks, plus benign trigger-heavy counterexamples. It improved from
+15/2/16/3 to 18/0/18/0 (TP/FP/TN/FN):
+
+| recall | FPR | precision | F1 |
+|---:|---:|---:|---:|
+| 100% | 0% | 100% | 100% |
+
+This is still a curated regression set. The signatures were developed with these
+cases visible, so its perfect score is not a generalization claim.
+
+## 3. Blind semantic snapshots (the anti-gaming result)
+
+Three balanced snapshots were authored independently without detector or regex
+context, then frozen. They deliberately pair attacks with benign text containing
+similar roleplay, authority, debug, and policy vocabulary.
+
+Isolation protocol: the v1/v2 authoring tasks received only the five semantic
+category names, required row/balance counts, and a request for attack/benign
+contrast pairs. The v3 task received modality coverage requirements but no
+detector source, signatures, or current predictions. The files were frozen before
+detector tuning and are integrity-pinned in tests:
+v1 SHA-256 `b3281ba1a42d266bb930bbb41943016d47b38dbc822ff7cff5131f3448a0248f`;
+v2 SHA-256 `aa8b8c81c00a55bb65180e15ff743b6241d24845b3886e8e60b52b9b23db47fa`;
+v3 SHA-256 `2285031e8143572311a522a4b6ec1a39c96a34ac2b42785f17818e8a145342bf`.
+
+| snapshot | rows | TP/FP/TN/FN | recall | FPR | balanced accuracy |
+|---|---:|---:|---:|---:|---:|
+| v1 | 30 | 4/2/13/11 | 26.7% | 13.3% | 56.7% |
+| v2 | 20 | 0/1/9/10 | 0% | 10% | 45% |
+| v3 | 40 | 6/6/14/14 | 30% | 30% | 50% |
+| **aggregate** | **90** | **10/9/36/35** | **22.2%** | **20%** | **51.1%** |
+
+The v3 snapshot was opened only after a detector candidate and acceptance bar
+were frozen. That candidate raised aggregate recall to 55.6% but failed the
+predeclared false-positive and balanced-accuracy gates (24.4% FPR; 65.6%
+balanced accuracy), so it was discarded in full. No v3-driven detector tuning
+ships in 0.6.2; the table records the unchanged released core.
+
+These snapshots expose the core deterministic tier's semantic-generalization
+ceiling and are development evidence for a fresh-corpus classifier/conjunction
+tranche, not numbers to hide or a set to tune against.
 
-## 2. External: `deepset/prompt-injections` (out-of-distribution — the honest number)
+## 4. External: `deepset/prompt-injections` (out-of-distribution)
 
 The field's standard public smoke set (662 rows, English + German, diverse
 phrasings). This is where in-distribution scores collapse — and ours do too.
@@ -72,7 +124,7 @@ via `use_transformer="meta-llama/Llama-Prompt-Guard-2-22M"`. Note: the Prompt-Gu
 models are **gated** on HuggingFace — accept the license and run `huggingface-cli
 login` (or set `HF_TOKEN`) first. The default ProtectAI model needs no token.
 
-## 3. Interpretation & roadmap
+## 5. Interpretation & roadmap
 
 - **Use the deterministic tiers** for cheap, explainable, obfuscation-aware,
   zero-false-positive catches and for everything the classifier can't do
@@ -90,6 +142,7 @@ it needs `pip install agentdojo` and an LLM API key; the adapter and a
 standalone `scan_messages_for_injection` helper are tested and ready. Publishing
 the ASR-at-fixed-utility number is the next milestone.
 
-> Numbers measured 2026-06-12 on CPU. Latency is hardware-dependent; the
+> External model numbers measured 2026-06-12; curated/blind snapshots measured
+> 2026-07-25 on CPU. Latency is hardware-dependent; the
 > classifier adds tens of ms/scan on CPU, the vector tier ~20 ms, vs. sub-ms for
 > the deterministic tiers.

{shadowshield-0.6.0 → shadowshield-0.6.2}/docs/PRODUCTION_READINESS.md

@@ -1,6 +1,6 @@
 # Production readiness roadmap
 
-**Baseline:** ShadowShield 0.6.0 · **Audit date:** 2026-07-25
+**Baseline:** ShadowShield 0.6.2 · **Audit date:** 2026-07-25
 
 This roadmap is the release gate for the Python library and the optional HTTP
 control plane. A checked item is implemented and locally verified; unchecked
@@ -10,12 +10,12 @@ items require an explicit operator or maintainer decision before public launch.
 
 | Area | State | Evidence / remaining action |
 |---|---|---|
-| Correctness | Ready | Full unit/integration suite; strict mypy; Ruff lint and format |
+| Correctness | Ready | 290+ unit/integration cases; strict mypy; Ruff lint/format; CodeQL extended scanning |
 | Packaging | Ready | Isolated sdist/wheel build, Twine metadata check, installed-wheel CI smoke test |
 | Runtime security | Ready with configuration | Early API-key/Bearer auth, body limits, restricted CORS, immutable protection floor, non-root read-only container |
-| Supply chain | Ready | SHA-pinned Actions, PyPI OIDC publishing, and CI dependency audit |
+| Supply chain | Ready | Repository-enforced Action SHA pins, PyPI OIDC, exact-green-main release gates, pre-push image vulnerability gate, anonymous GHCR digest pull, registry-verified SLSA and CycloneDX attestations |
 | Observability | Ready for single process | Content-free telemetry, Prometheus endpoint, bounded in-memory event feed |
-| Detection quality | Beta | Adversarial baseline: 83.3% recall, 11.1% FPR; tune in shadow mode before enforcement |
+| Detection quality | Beta | Curated adversarial: 100%/0% FPR; blind v1–v3 aggregate: 22.2%/20%; v3: 30%/30%; deepset core: 23.3%/0% |
 | Scale / HA | Not yet | Counters, events, configuration, and rate limits are process-local |
 | Streaming | Not yet | Outputs must be buffered before scanning |
 
@@ -38,28 +38,58 @@ items require an explicit operator or maintainer decision before public launch.
   signed last-known-good policy state.
 - [x] Bound scan concurrency and ensure permanently hung judges cannot block shutdown.
 - [x] Pin every third-party GitHub Action to a reviewed commit SHA.
+- [x] Separate policy-state authentication from policy signing and reject all
+  pairwise-equal production credentials.
+- [x] Add a verified offline 0.6.0 policy-state migration and reject state that
+  would exceed the bounded restart parser before changing the live policy.
+- [x] Add non-loading readiness probes and explicit fail-fast detector warmup.
+- [x] Make Transformer loading and Vector mutation single-flight/transactional.
+- [x] Bound Reporter flush/retry/close lifecycle under concurrency.
+- [x] Pin the base image by digest, gate the exact release image on Trivy, publish
+  it to GHCR, verify an anonymous digest pull, and attach its immutable digest
+  plus CycloneDX SBOM to the release.
+- [x] Sign release-image SLSA provenance and the CycloneDX SBOM with ephemeral
+  GitHub OIDC/Sigstore identity, then verify repository, workflow, runner, and
+  source-commit claims from the OCI registry before completing the release.
+- [x] Reject release publication unless a stable, non-prerelease tag matches the
+  package version, resolves to `main`, and has a successful exact-SHA `main` CI run.
+- [x] Reject symlink/non-regular durable policy-state files, use unpredictable
+  exclusive temporary files, and revision-check reads, migrations, and replaces.
+- [x] Coalesce concurrent failed Transformer/Vector load generations while giving
+  every waiter a fresh bounded exception traceback and allowing a later retry.
+- [x] Enable Dependabot security updates, extended CodeQL scanning, secret
+  push-protection, and repository-level enforcement of full-SHA Action pins.
+- [x] Publish a third independently authored blind snapshot and reject—not
+  tune—the first frozen candidate when it missed the predeclared FPR/accuracy bar.
 
 ## P1 — launch procedure (operator-owned)
 
-- [ ] Set independent high-entropy `SHADOWSHIELD_API_KEY`, `SHADOWSHIELD_ADMIN_KEY`, and `SHADOWSHIELD_POLICY_KEY` values; terminate TLS at a trusted ingress.
+- [ ] Set independent high-entropy `SHADOWSHIELD_API_KEY`,
+  `SHADOWSHIELD_ADMIN_KEY`, `SHADOWSHIELD_POLICY_KEY`, and
+  `SHADOWSHIELD_POLICY_STATE_KEY` values; terminate TLS at a trusted ingress.
+- [ ] When upgrading a 0.6.0 durable volume, stop all writers, snapshot the
+  volume, run `shadowshield migrate-policy-state`, retain its verified backup,
+  and confirm the restored policy/version before accepting traffic.
 - [ ] Set an explicit CORS allowlist or leave CORS disabled.
 - [ ] Run the adversarial and application-specific eval sets in permissive/shadow mode.
 - [ ] Choose thresholds from measured false-positive cost; record the accepted baseline.
 - [ ] Connect Prometheus and content-free telemetry; alert on error, block-rate, and latency shifts.
 - [ ] Load-test representative payload sizes and concurrency on the target instance class.
-- [ ] Pin the image by digest, scan it, generate/store an SBOM, and rehearse rollback.
+- [ ] Record the deployed image digest and CI SBOM, then rehearse backup/restore
+  and rollback against the target environment.
 - [ ] Protect the PyPI GitHub Environment with required reviewers before publishing.
 
 ## P2 — next engineering milestones
 
 1. Add a rolling-window streaming scanner that blocks before unsafe output is emitted.
 2. Move rate limits, event history, and metrics aggregation to shared external stores for multi-worker HA.
-3. Add readiness/startup probes that validate optional model assets when ML detectors are enabled.
-4. Publish signed container images, provenance attestations, and an SBOM from the release workflow.
-5. Calibrate detector scores on a larger independently sourced corpus and publish confidence intervals.
-6. Add soak, concurrency, and fault-injection tests for reporters, judges, and hot policy updates.
-7. Split the current administrator credential into narrower observe and mutation scopes.
-8. Add single-flight model loading and synchronized vector-index mutation.
+3. Build a fresh independently sourced development corpus, then evaluate the
+   next detector candidate once on a new sealed snapshot and publish confidence intervals.
+4. Add multi-hour soak and network fault-injection tests for reporters, judges, and hot policy updates.
+5. Split the current administrator credential into narrower observe and mutation scopes.
+6. Design cross-process model/index coordination and durable Reporter spooling.
+7. Split unprivileged container build/scan from the write/OIDC publication job.
+8. Refactor release evidence into a draft-first pipeline, then enable immutable releases.
 
 ## Go / no-go gates
 

shadowshield-0.6.2/docs/RELEASING.md

@@ -0,0 +1,109 @@
+# Releasing ShadowShield
+
+ShadowShield publishes via **PyPI Trusted Publishing** (OpenID Connect from GitHub
+Actions). No API token is ever created, stored, or pasted anywhere — PyPI trusts
+this specific GitHub workflow directly. The pipeline is
+[`publish.yml`](../.github/workflows/publish.yml).
+
+The same GitHub Release also triggers
+[`container-release.yml`](../.github/workflows/container-release.yml). It builds
+one image from the release tag, generates a CycloneDX SBOM, rejects fixable
+high/critical findings, pushes that exact scanned image to GHCR, signs SLSA
+provenance and CycloneDX attestations through GitHub's Sigstore-backed OIDC
+service, verifies the signed provenance and an anonymous pull by digest, and
+attaches `container-digest.txt` plus the SBOM to the GitHub Release.
+
+## One-time setup (PyPI account owner only)
+
+This must be done in the PyPI web UI by the account that will own the project —
+it cannot be automated.
+
+1. Create a PyPI account (and enable 2FA): <https://pypi.org/account/register/>.
+2. Go to **<https://pypi.org/manage/account/publishing/>** → "Add a new pending
+   publisher" and enter **exactly**:
+   - **PyPI Project Name:** `shadowshield`
+   - **Owner:** `0xsl1m`
+   - **Repository name:** `shadowshield`
+   - **Workflow name:** `publish.yml`
+   - **Environment name:** *(leave blank — the workflow declares no environment)*
+3. Save. This registers a *pending publisher*; the PyPI project is created
+   automatically on the first successful publish.
+
+> Optional hardening: create a GitHub Environment named `pypi` with required
+> reviewers, add `environment: pypi` to the `publish` job, and set the same
+> environment name in the PyPI publisher config. Then every publish needs manual
+> approval in GitHub.
+
+## One-time setup (GHCR package owner only)
+
+GitHub may create a first-published container package as private. The release
+workflow deliberately fails its anonymous-pull gate if that happens.
+
+1. Let the first `Publish release container` run push the package.
+2. If the anonymous-pull step fails, open the `shadowshield` package settings
+   under the `0xsl1m` account and change visibility to **Public**.
+3. Re-run the failed workflow job. Do not publish the release digest to operators
+   until the anonymous pull and evidence-attachment steps are green.
+
+## Cutting a release
+
+Only release an exact commit whose PR and `main` CI checks are green:
+
+```bash
+# 1. bump the version in pyproject.toml + src/shadowshield/__init__.py, update CHANGELOG
+# 2. merge through a reviewed PR and wait for main CI + site deployment
+# 3. create the release/tag at that exact merge commit
+merge_sha="$(git rev-parse origin/main)"
+gh release create vX.Y.Z --target "$merge_sha" \
+  --title "ShadowShield X.Y.Z" --notes "..."
+# -> PyPI publishing and exact-image scan/publish run independently
+```
+
+Do not create the release while required checks are pending. A partial release
+is recoverable by fixing the failed workflow and re-running it, but the PyPI
+version itself cannot be replaced.
+
+Both publication workflows independently reject non-stable tags, tag/source
+version mismatches, commits outside `main`, and commits without a successful
+exact-SHA `main` CI run. There is no manual-dispatch publication path; use
+GitHub's **Re-run failed jobs** control to recover a failed release workflow.
+
+## Verify
+
+```bash
+pip index versions shadowshield          # should list the new version
+pip install shadowshield==X.Y.Z          # clean-env smoke test
+python -c "import shadowshield as ss; print(ss.__version__)"
+
+gh release download vX.Y.Z \
+  --pattern container-digest.txt --pattern shadowshield-sbom.cdx.json
+digest="$(cat container-digest.txt)"
+image="ghcr.io/0xsl1m/shadowshield@$digest"
+docker pull "$image"
+gh attestation verify "oci://$image" \
+  --repo 0xsl1m/shadowshield \
+  --bundle-from-oci \
+  --signer-workflow 0xsl1m/shadowshield/.github/workflows/container-release.yml \
+  --source-digest "$(git rev-list -n 1 vX.Y.Z)" \
+  --deny-self-hosted-runners
+gh attestation verify "oci://$image" \
+  --repo 0xsl1m/shadowshield \
+  --bundle-from-oci \
+  --predicate-type https://cyclonedx.org/bom \
+  --signer-workflow 0xsl1m/shadowshield/.github/workflows/container-release.yml \
+  --source-digest "$(git rev-list -n 1 vX.Y.Z)" \
+  --deny-self-hosted-runners
+```
+
+## Notes
+
+- **Versions are immutable.** A published version can never be re-uploaded, only
+  *yanked*. Always confirm `twine check` is green (CI does this) before releasing.
+- Deploy the container by the exact `image@sha256` value in
+  `container-digest.txt`, never by a mutable version tag or a local Compose
+  rebuild. The release SBOM describes that exact pre-push-scanned image.
+- The default install stays lightweight; the ML/vector/PII/dataset stacks are
+  optional extras (see `pyproject.toml`).
+- Want to rehearse first? Configure a second pending publisher on
+  <https://test.pypi.org> and add a TestPyPI step — but the production path above
+  is already `twine check`-validated.

{shadowshield-0.6.0 → shadowshield-0.6.2}/docs/index.md

@@ -8,7 +8,7 @@ systems. This directory is the deep-dive companion to the top-level
 
 - [Benchmarks](BENCHMARKS.md) — measured detection/FPR on the bundled set **and** the public `deepset` set (regex-only vs. classifier).
 - [Comparison](COMPARISON.md) — competitive audit + capability matrix vs. LLM Guard, LlamaFirewall, NeMo, Guardrails, Rebuff.
-- [Releasing](RELEASING.md) — how ShadowShield ships to PyPI (Trusted Publishing, no tokens).
+- [Releasing](RELEASING.md) — PyPI Trusted Publishing plus exact scanned GHCR images and SBOMs.
 - [Production readiness](PRODUCTION_READINESS.md) — release gates, deployment
   checklist, known scale limits, and the next engineering milestones.
 - [Security model](security-model.md) — threat taxonomy, layers, trust boundaries.

{shadowshield-0.6.0 → shadowshield-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shadowshield"
-version = "0.6.0"
+version = "0.6.2"
 description = "Unified open-source security shield for agentic AI systems — inspired by Sentinel & ShadowClaw."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -30,6 +30,8 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Security",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed",

{shadowshield-0.6.0 → shadowshield-0.6.2}/src/shadowshield/__init__.py

@@ -71,7 +71,7 @@ from .plugins import PluginManager, ShadowShieldPlugin
 from .reporter import Reporter, attach_reporter
 from .responders import Responder, spotlight
 
-__version__ = "0.6.0"
+__version__ = "0.6.2"
 
 __all__ = [
     "__version__",

{shadowshield-0.6.0 → shadowshield-0.6.2}/src/shadowshield/_security.py

@@ -15,6 +15,7 @@ Configuration precedence: explicit arguments first, then environment:
 - ``SHADOWSHIELD_ADMIN_KEY``   - comma-separated control/metrics administrator keys.
 - ``SHADOWSHIELD_CORS_ORIGINS`` - comma-separated list of allowed origins.
 - ``SHADOWSHIELD_POLICY_KEY``  - HMAC key required for remotely exposed policy updates.
+- ``SHADOWSHIELD_POLICY_STATE_KEY`` - independent HMAC key for durable policy state.
 - ``SHADOWSHIELD_POLICY_STATE_PATH`` - durable anti-replay state file.
 
 Keys are compared with :func:`hmac.compare_digest` (constant-time) at request time.
@@ -26,6 +27,7 @@ import asyncio
 import hmac
 import json
 import os
+from collections.abc import Sequence
 from typing import Any
 
 MAX_HTTP_BODY_BYTES = 1_048_576
@@ -75,11 +77,40 @@ def resolve_policy_key(explicit: bytes | str | None = None) -> bytes | None:
     return value
 
 
+def resolve_policy_state_key(explicit: bytes | str | None = None) -> bytes | None:
+    """Policy-state HMAC key from args or ``SHADOWSHIELD_POLICY_STATE_KEY``."""
+    value: bytes | str | None = explicit or os.environ.get("SHADOWSHIELD_POLICY_STATE_KEY")
+    if isinstance(value, str):
+        return value.encode("utf-8") if value else None
+    return value
+
+
 def resolve_policy_state_path(explicit: str | None = None) -> str | None:
     """Durable anti-replay state path from args or the deployment environment."""
     return explicit or os.environ.get("SHADOWSHIELD_POLICY_STATE_PATH") or None
 
 
+def secret_groups_overlap(
+    left: Sequence[bytes | str],
+    right: Sequence[bytes | str],
+) -> bool:
+    """Return whether two credential groups share a value.
+
+    Every candidate comparison uses :func:`hmac.compare_digest`; the loops do
+    not short-circuit when a match is found.
+    """
+
+    overlap = False
+    for left_value in left:
+        left_bytes = left_value.encode("utf-8") if isinstance(left_value, str) else left_value
+        for right_value in right:
+            right_bytes = (
+                right_value.encode("utf-8") if isinstance(right_value, str) else right_value
+            )
+            overlap |= hmac.compare_digest(left_bytes, right_bytes)
+    return overlap
+
+
 def extract_key(x_api_key: str | None, authorization: str | None) -> str | None:
     """Pull a presented key from either the ``X-API-Key`` or ``Bearer`` header."""
     if x_api_key: