bezoar 1.0.0a2__tar.gz

bezoar-1.0.0a2/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# bezoar runtime
+.bezoar-cache/
+.bezoar-baseline.json
+*.sarif
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/
+
+# Test fixtures: platform config dirs MUST be tracked even though editor
+# gitignores (the .vscode/ above, and common global excludes like .cursor/)
+# hide them — the corpus and adapter fixtures live inside these dirs.
+!tests/**/.vscode/
+!tests/**/.vscode/**
+!tests/**/.cursor/
+!tests/**/.cursor/**
+!tests/**/node_modules/
+!tests/**/node_modules/**

bezoar-1.0.0a2/CHANGELOG.md

@@ -0,0 +1,141 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0a2] - 2026-09-05
+
+Second alpha: security remediation wave, fully wired serve API, green
+Windows CI, and a console design-system upgrade.
+
+### Security
+
+- Never cache partial scan outcomes: a rule timeout or detector error no
+  longer replays as a complete scan from a warm cache
+- Rule-pack lint now rejects polynomial ReDoS shapes (adjacent-star,
+  complement-pair, and match-anything wrappers at every sequence level)
+- Redaction covers JSON-quoted keys (`"password":"…"`), spaced assignments,
+  headers, Basic auth, and Slack webhook URLs — and no longer redacts
+  40-hex git SHAs
+- `metadata.identity` and MCP config `Location.relpath` no longer leak
+  absolute host paths into default JSON reports
+- `bezoar serve`: any-NUL path rejection (400), generic 500 bodies, 405s
+  with security headers, Host header guard on static files, serve token via
+  `BEZOAR_SERVE_TOKEN` / `--token-file`, and `X-Bezoar-Client` enforced on
+  all write methods
+- MCP probe: cross-host redirects no longer leak Authorization; CGNAT and
+  NAT64 ranges blocked alongside RFC1918
+
+### Added
+
+- `bezoar serve` API fully wired: policy validate, explain, baseline
+  read/write, and scan endpoints (schema-invalid `PUT /policy` → 422)
+- Console: seed-derived 8-step token ramps via `color-mix(in oklch)` with a
+  parser test enforcing WCAG AA contrast in both themes
+- Console: floating row actions (Open / Set series / Export / Delete) on the
+  reports table — keyboard reachable, axe-clean
+- Console policy editor: YAML 1.1 boolean round-trip and raw-byte report
+  import
+
+### Fixed
+
+- Windows: CRLF code-fence parsing crash in detectors, concurrent baseline
+  write `PermissionError` (retry with backoff), home-directory resolution in
+  tests (`USERPROFILE`), UTF-8 console output
+- CI: `uv venv` everywhere (PEP 668), pytest `pythonpath` for bare `pytest`,
+  pinned pnpm via `pnpm/action-setup`, test-fixture directories re-included
+  from gitignore
+- `--changed-since` handles non-ASCII filenames (NUL-delimited git diff) and
+  anchors at the git toplevel for subdirectory scans
+
+## [1.0.0a1] - 2026-09-05
+
+First public alpha of bezoar — an offline-first security scanner for the
+AI-agent supply chain (skills, MCP servers, plugins, subagents, rules,
+commands, hooks, CLI helpers, and agent configs).
+
+### Added
+
+#### Core
+
+- Package `bezoar` `1.0.0a1` (Python 3.11+, hatchling src layout, runtime
+  dependency `pyyaml>=6.0`)
+- Six platform adapters: Claude Code, Cursor, Codex CLI, Gemini CLI, GitHub
+  Copilot, and generic discovery
+- Wheel ships `bezoar/data/rules/*.yml` + `MANIFEST.json`, seven
+  `bezoar/data/harness/*.yml` vocabularies, `bezoar/data/policy/default.yml`,
+  `bezoar/data/NOTICE`, and `bezoar/data/schemas/policy.v1.schema.json`
+  (required for an installed `bezoar scan`)
+
+#### Detectors
+
+- 136 declarative rule-pack rules in four builtin packs (`data/rules/`,
+  counted in `MANIFEST.json`): secrets 80, prompt_injection 36,
+  external_instructions 8, exfil_sinks 12
+- Programmatic detectors: harness-envelope forgery (the differentiator —
+  data-driven vocabs + structural-sequence matchers), hidden behavior,
+  permissions, supply chain, data exfiltration, external instructions,
+  MCP tool-poisoning
+- Flag-gated MCP live probe (`--probe-mcp`; INFO-only, cannot move a band)
+- Advisory LLM judge (`--judge`; `NullProvider` via entry point
+  `bezoar.judge:null`; cannot move a band)
+
+#### Policy and bands
+
+- Band algebra (`safe` | `potential_risk` | `unsafe` | `malicious`) with
+  disposition caps and corroboration
+- Policy engine (`.bezoar.yml` layered merge, builtin `data/policy/default.yml`)
+  mapping bands to decisions (`allow` | `allow_with_notice` | `alert` | `block`)
+- Expiring exceptions, pins, baselines; band is a fact, decision is policy
+
+#### CLI, reporters, schemas
+
+- Console script `bezoar` (`scan`, `discover`, `rules lint`, `policy
+  validate|explain`, `baseline update|diff`, `cache stats|clear`, `serve`,
+  `version`)
+- Scan flags include `--fail-on`, `--format text|json|sarif`, `--changed-since`,
+  `--config`, `--baseline`, `--jobs`, `--no-cache`, `--cache-dir`
+- Three reporters: text, JSON (`schemas/scan-result.v1.schema.json`), SARIF 2.1.0
+- Versioned schemas: `scan-result.v1`, `policy.v1`, `rulepack.v1`
+
+#### Integrations
+
+- Composite GitHub Action (`action.yml`): maps to the CLI flags above, always
+  writes `bezoar.sarif` from stdout, uploads via `github/codeql-action/upload-sarif`
+  when `upload-sarif` is true (including after a failed gate), then re-raises
+  the CLI exit code
+- Extra `bezoar[console]` → `bezoar-console==1.0.0a1`
+- Entry-point groups: `bezoar.detectors`, `bezoar.adapters`, `bezoar.reporters`,
+  `bezoar.judge` (`null = bezoar.judge:NullProvider`)
+- Multi-stage `Dockerfile` (python:3.12-slim)
+- CI matrix: CPython 3.11/3.12/3.13 × Ubuntu/macOS/Windows, plus
+  `python -m bezoar.rules.lint`
+
+#### Web console
+
+- Static report viewer (drag/drop `bezoar.scan/v1` JSON → IndexedDB)
+- `bezoar serve` (stdlib server + `/api/v1`) when `bezoar-console` is installed
+- See [docs/console.md](docs/console.md)
+
+#### Evaluation and performance
+
+- Bundled corpus `tests/corpus` + `scripts/eval/score.py`: detection rate
+  **1.0000** (41/41 malicious), finding-level FP rate **0.0000** (0/47 benign)
+- Reference machine: 10,001-file / ~200 MiB synthetic
+  monorepo through `map_files` + file cache — **12.72 s** cold / **1.54 s**
+  warm (targets: < 60 s / < 5 s)
+
+#### Supply-chain hygiene
+
+- Reproducible `uv build` (`SOURCE_DATE_EPOCH`)
+- Dual SBOMs: CycloneDX and SPDX
+- Sigstore keyless signatures
+- SLSA provenance (`actions/attest-build-provenance`)
+- PyPI trusted publishing (OIDC, `pypi` environment — maintainer setup TODO)
+
+[Unreleased]: https://github.com/IsmailKharoub/bezoar/compare/v1.0.0a1...HEAD
+[1.0.0a1]: https://github.com/IsmailKharoub/bezoar/releases/tag/v1.0.0a1

bezoar-1.0.0a2/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

bezoar-1.0.0a2/NOTICE

@@ -0,0 +1,9 @@
+bezoar
+Copyright 2026 the bezoar authors
+
+This product is licensed under the Apache License, Version 2.0.
+See the LICENSE file for the full license text.
+
+Third-party pattern attributions for builtin rule packs (principally
+gitleaks, MIT) are in src/bezoar/data/NOTICE, which is also installed
+in the wheel as bezoar/data/NOTICE.

bezoar-1.0.0a2/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: bezoar
+Version: 1.0.0a2
+Summary: Open-source security scanner for the AI-agent supply chain — skills, MCPs, plugins, subagents
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: console
+Requires-Dist: bezoar-console==1.0.0a2; extra == 'console'
+Provides-Extra: dev
+Requires-Dist: hypothesis; extra == 'dev'
+Requires-Dist: jsonschema; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-xdist; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: sbom
+Requires-Dist: cyclonedx-bom; extra == 'sbom'
+Description-Content-Type: text/markdown
+
+# bezoar
+
+**The open-source security scanner for the AI-agent supply chain** — skills, MCP servers,
+plugins, subagents, and CLI add-ons across every major agent platform.
+
+> *Bezoar: the legendary stone believed to neutralize any poison. This one neutralizes
+> poisoned agent add-ons.*
+
+`bezoar scan` audits an add-on before it enters your agent's context: static detectors,
+four verdict **bands**, and a policy layer that turns those bands into **decisions**.
+Think `npm audit` for agent add-ons — offline-first, deterministic, CI-friendly,
+SARIF/JSON output.
+
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/bezoar.svg)](https://pypi.org/project/bezoar/)
+[![CI](https://github.com/IsmailKharoub/bezoar/actions/workflows/ci.yml/badge.svg)](https://github.com/IsmailKharoub/bezoar/actions/workflows/ci.yml)
+[![SARIF](https://img.shields.io/badge/SARIF-2.1.0-informational)](docs/ci.md)
+
+**1.0.0a2** ships the scanner, CLI, SARIF/JSON reporters, GitHub Action, and web
+console. The commands below and the guides in `docs/` describe that shipped
+surface.
+
+## 60-second quickstart
+
+Requires Python ≥ 3.11.
+
+```bash
+# From this checkout (works before PyPI)
+uv tool install .
+
+# After the 1.0.0a2 tag is published
+# uv tool install bezoar==1.0.0a2
+
+bezoar version
+bezoar scan tests/corpus/benign/claude_code/skill-markdown-lint --fail-on unsafe
+```
+
+Point `bezoar scan` at any skill directory or repo root. Flags: `--format
+text|json|sarif` (reports go to stdout; there is no `--output`), `--fail-on`,
+`--config`, `--changed-since`, `--baseline`. Exit `0` = gate passed, `1` =
+band ≥ `--fail-on`, `2` usage, `3` incomplete, `4` internal.
+
+See [Getting started](docs/getting-started.md) for reading findings.
+
+### Illustrative text report
+
+The live text reporter prints a band table, then per-component rows.
+The excerpt below is the finding shape: `band` is a fact; `decision` is
+policy; locations are raw `file:line:column`; rule ids use `<family>/<rule>`.
+
+```text
+✗  band=malicious  decision=block  components=1  findings=4
+
+generic:skill:pdf-optimizer@<hash12>  malicious → block  (band_default)
+
+  [critical] harness_forgery/control-tag-close      SKILL.md:16:1  [hidden]
+             Close of a trusted harness wrapper — the breakout primitive
+             evidence: </system-reminder>
+
+  [    high] harness_forgery/control-tag-open       SKILL.md:17:1  [hidden]
+             Open of a reminder-role control tag with an imperative body
+             evidence: <system-reminder priority="critical">
+
+  [    high] harness_forgery/prose-terminator       SKILL.md:22:1  [hidden]
+             Prose-form function-end marker (semantic escape)
+             evidence: [Function results halted by user]
+
+  [critical] prompt_injection/instruction-override  SKILL.md:27:1
+             Instruction-override language
+             evidence: Ignore all previous instructions
+```
+
+`--format json` and `--format sarif` are the stable machine interfaces.
+JSON/SARIF are byte-identical across runs (modulo `stats.duration_ms`).
+
+## Bands and decisions
+
+**Band is a fact about the component. Decision is what the org does.** No exception,
+pin, baseline, or vendor trust rewrites a band.
+
+| Band (fact) | Default decision (policy) |
+|---|---|
+| `safe` | `allow` |
+| `potential_risk` | `allow_with_notice` |
+| `unsafe` | `alert` |
+| `malicious` | `block` |
+
+Four bands, four decisions. The three enforcement outcomes people quote
+(allow / alert / block) are the same table: `allow_with_notice` is the fourth decision —
+allow, but surface the risk. Capability-only findings (permissions, unpinned-only
+supply-chain, metadata) cap the band at `potential_risk` unless an intent-bearing
+finding corroborates them. Details: [Policy](docs/policy.md).
+
+## Why bezoar
+
+Enterprises deploy coding agents with no seatbelt. Skills and MCPs are executable
+supply-chain artifacts that load straight into an agent's context. Public scanners
+catch generic jailbreak phrases and leaked keys; they miss the class that actually
+steers the model — **harness-envelope forgery** (content impersonating the host
+harness's own control syntax). bezoar maps findings to the
+[OWASP Agentic Skills Top 10](https://owasp.org/www-project-agentic-skills-top-10/)
+and adds that missing family. See [Harness-envelope forgery](docs/harness-forgery.md).
+
+A default scan performs **no network requests** and **never executes** scanned
+artifacts. Same inputs → same JSON/SARIF.
+
+## Comparison
+
+Public posture as of 2026-09. “Harness-envelope forgery” means a first-class,
+per-platform vocabulary of harness control syntax plus structural-sequence
+matchers — not generic “ignore previous instructions” or “system message”
+regexes.
+
+| | Offline | Deterministic | Harness-forgery detection | Policy-as-code | SARIF | Price |
+|---|---|---|---|---|---|---|
+| **bezoar** | Yes (default) | Yes | Yes | Yes (`.bezoar.yml`) | Yes | Apache-2.0 |
+| [Snyk agent-scan](https://github.com/snyk/agent-scan) | No (`SNYK_TOKEN` + hosted analysis) | No | No | No (Snyk org / API) | No (JSON) | Free Snyk account required; commercial platform |
+| [Cisco skill-scanner](https://github.com/cisco-ai-defense/skill-scanner) | Partial (patterns/YARA offline; LLM optional) | Partial (LLM judge optional) | No | Yes (YAML presets) | Yes | Apache-2.0 |
+| [invariantlabs mcp-scan](https://github.com/invariantlabs-ai/mcp-scan) | No (Invariant API or OpenAI; connects to MCP servers) | No | No | Partial (proxy guardrails) | No | Apache-2.0 + cloud / OpenAI |
+| [AIR](https://air.security) | No (inline firewall + cloud) | No | No | Yes (product policy) | Not documented | Commercial |
+
+`invariantlabs-ai/mcp-scan` now redirects into Snyk agent-scan; the column reflects
+the historical Invariant CLI that still appears in comparisons. AIR is the commercial
+category reference — see [FAQ](docs/faq.md#how-does-bezoar-relate-to-air).
+
+## Docs
+
+| Doc | What it covers |
+|---|---|
+| [Getting started](docs/getting-started.md) | Install, first scan, reading findings, exit codes |
+| [Policy](docs/policy.md) | `.bezoar.yml`, bands vs decisions, exceptions, vendor trust |
+| [Rules authoring](docs/rules-authoring.md) | Rule-pack schema, severity / disposition / confidence, `bezoar rules lint` |
+| [CI](docs/ci.md) | GitHub Action, baselines, SARIF → Code Scanning |
+| [Web console](docs/console.md) | Static JSON viewer and `bezoar serve` |
+| [Harness-envelope forgery](docs/harness-forgery.md) | The differentiator, per-platform vocabularies, tuning |
+| [Platforms](docs/platforms.md) | Discovery matrix and per-platform limits |
+| [FAQ](docs/faq.md) | Offline, determinism, LLM judge, AIR, license |
+
+## Web console
+
+The console **never computes security facts** — it renders `bezoar.scan/v1` JSON
+from the CLI.
+
+- **Viewer:** open the static export (`console/apps/web/out/index.html` or
+  `bezoar_console.dist_path()` after `pip install bezoar-console`). Drag-drop a
+  JSON report; it stays in IndexedDB. SARIF is rejected — re-scan with
+  `--format json`.
+- **Serve:** `bezoar serve` (loopback + `/api/v1`). Needs the console extra:
+
+```bash
+pip install 'bezoar[console]'   # bezoar-console==1.0.0a2
+bezoar serve
+```
+
+Details: [docs/console.md](docs/console.md).
+
+## GitHub Action
+
+```yaml
+# permissions: { contents: read, security-events: write }
+- uses: IsmailKharoub/bezoar@v1.0.0a2
+  with:
+    path: .
+    fail-on: malicious
+    upload-sarif: true
+```
+
+The Action always writes `bezoar.sarif` from `bezoar scan --format sarif`
+(stdout; the CLI has no `--output`), uploads it to Code Scanning when
+`upload-sarif` is true — including after a failed gate — then re-raises the
+CLI exit code.
+
+## License
+
+Apache-2.0. Rule-pack pattern attributions (gitleaks) are in [`NOTICE`](NOTICE)
+and [`src/bezoar/data/NOTICE`](src/bezoar/data/NOTICE).