diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..f39fb33 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,79 @@ +name: Bug report +description: Report a reproducible AgentFence problem without sharing private configuration. +title: "[Bug]: " +labels: + - bug +body: + - type: markdown + attributes: + value: | + Thanks for the report. Use synthetic inputs and do not paste credentials, private paths, raw reports, or unfixed security details. Report vulnerabilities through GitHub private vulnerability reporting. + + - type: input + id: agentfence-version + attributes: + label: AgentFence version + placeholder: 0.2.0 + validations: + required: true + + - type: input + id: node-version + attributes: + label: Node.js version + description: Output of `node --version`. + placeholder: v24.21.0 + validations: + required: true + + - type: dropdown + id: operating-system + attributes: + label: Operating system + options: + - Linux + - macOS + - Windows + - Other + validations: + required: true + + - type: textarea + id: command + attributes: + label: Command + description: Provide the exact AgentFence command after removing private paths or values. + render: shell + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual behavior + description: Include safe error codes or sanitized output only. + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Synthetic reproduction + description: Provide the smallest synthetic configuration that reproduces the problem. + validations: + required: true + + - type: checkboxes + id: safety + attributes: + label: Data-safety confirmation + options: + - label: I removed credentials, private configuration, private paths, raw reports, and other sensitive data. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..d54121d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Report a security vulnerability + url: https://github.com/Adulph3/AgentFence/security/advisories/new + about: Privately report unintended execution, data exposure, scope escape, or another security-sensitive defect. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..544502b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,45 @@ +name: Feature request +description: Propose a focused improvement to AgentFence's static audit scope or developer experience. +title: "[Feature]: " +labels: + - enhancement +body: + - type: markdown + attributes: + value: | + Describe the observable configuration problem first. AgentFence will not add execution of scanned content, live MCP access, telemetry, or remote analysis. + + - type: textarea + id: problem + attributes: + label: Problem + description: What review or automation problem is difficult today? + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed behavior + description: Describe the desired static behavior, including relevant configuration fields or output. + validations: + required: true + + - type: textarea + id: evidence + attributes: + label: Compatibility evidence + description: Link to official vendor documentation when proposing a new adapter or field interpretation. + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + + - type: checkboxes + id: safety + attributes: + label: Scope confirmation + options: + - label: This request can preserve no-execution, zero-runtime-network, read-only-default, deterministic, and safe-output behavior. + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..fce82bc --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,28 @@ +## Summary + +Describe the problem and the smallest change that solves it. + +## Security and compatibility impact + +- Does this change discovery, parsing, adapters, rules, scoring, schemas, reports, dependencies, or public APIs? +- Which documented vendor behavior or project invariant supports the change? +- What limitations remain? + +## Validation + +- [ ] `npm run typecheck` +- [ ] `npm run lint` +- [ ] `npm test` +- [ ] `npm run test:coverage` when security/scoring behavior changes +- [ ] `npm run build` +- [ ] `npm pack --dry-run --ignore-scripts` when package contents change +- [ ] Synthetic positive, negative, adversarial, and redaction cases were added where applicable + +## Safety checklist + +- [ ] Scanned content is never executed or imported +- [ ] `scan` and `doctor` initiate no application network activity +- [ ] No telemetry, backend, remote AI, or live MCP access was added +- [ ] Default scanning remains read-only and bounded +- [ ] Output contains no raw secrets, commands, URLs, parser errors, names, or paths +- [ ] This PR contains no credentials, private configuration, raw private reports, or machine-specific data diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1619291..303359f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,65 @@ # Contributing -Use only synthetic offline fixtures. Review every dependency and preserve the zero-network/no-execution and safe-output invariants. Run `npm ci --ignore-scripts`, `npm run typecheck`, `npm run lint`, `npm test`, `npm run build`, and package checks. Rule changes require positive, negative, adversarial, redaction, and deterministic tests. - -Do not add runtime rule loading, plugins, vendor SDKs, remote fixtures, real -credentials, or input-controlled imports. Keep raw parsed data inside parsing and -analysis boundaries; public DTOs and test assertions must use safe projections. -For a rule change, update the compiled registry metadata, its fixed remediation and -bundled HTTPS reference, then add executable positive, negative, adversarial and -redaction coverage. Review dependency purpose, version, license, lifecycle scripts -and transitive impact before changing the lockfile. Do not weaken a test solely to -make a gate pass. +Thanks for helping improve AgentFence. Keep changes focused, reproducible, and grounded in observable configuration behavior. + +## Before you start + +- Read `AGENTS.md`, `AGENTFENCE_MASTER_PLAN.md`, and `docs/PROGRESS.md`. +- Use Node.js 22 or 24; Node.js 24 is recommended. +- Use only synthetic offline fixtures. Never commit credentials, personal configuration, raw private reports, or machine-specific paths. +- For a suspected vulnerability, use [private vulnerability reporting](https://github.com/Adulph3/AgentFence/security/advisories/new) instead of a public issue. + +## Development setup + +```bash +git clone https://github.com/Adulph3/AgentFence.git +cd AgentFence +npm ci --ignore-scripts +``` + +Run the quality gates before opening a pull request: + +```bash +npm run typecheck +npm run lint +npm test +npm run test:coverage +npm run build +npm pack --dry-run --ignore-scripts +``` + +Do not weaken a test to make a gate pass. Fix the defect or document a genuine platform/evidence limitation. + +## Project invariants + +Every change must preserve: + +- no execution of scanned instructions, hooks, commands, packages, or configuration; +- no application-initiated runtime network access, telemetry, backend, or remote AI; +- read-only scanning unless the operator explicitly requests a new report file; +- bounded acquisition and parsing; +- deterministic analysis for identical complete inputs; and +- safe output that does not reproduce raw secrets, commands, URLs, parser errors, names, or paths. + +Do not add runtime rule loading, plugins, vendor SDKs, remote fixtures, input-controlled imports, or a redaction bypass. + +## Rule and adapter changes + +A detector change needs positive, negative, adversarial, redaction, and deterministic coverage. Update the compiled registry metadata, fixed remediation, bundled HTTPS reference, and detector documentation together. + +An adapter change must be based on documented vendor semantics and include bounded compatibility fixtures. Unknown behavior should remain an explicit coverage limitation rather than a guessed effective configuration. + +## Dependency changes + +Explain the dependency's purpose and review its exact version, license, lifecycle scripts, transitive graph, runtime capabilities, and effect on the no-network/no-execution boundary. Keep the lockfile and `THIRD_PARTY_NOTICES.md` consistent. + +## Pull requests + +Keep pull requests small enough to review. Describe: + +- the problem and intended behavior; +- security-boundary or schema impact; +- tests and platforms exercised; and +- remaining limitations or follow-up work. + +Do not paste secret-bearing output into the PR. A maintainer may request additional platform or adversarial coverage for security-sensitive changes. diff --git a/README.md b/README.md index 08dd034..345a701 100644 --- a/README.md +++ b/README.md @@ -1,281 +1,180 @@

- AgentFence — local-first security scanner for AI coding-agent environments + AgentFence — local-first security scanner for AI coding-agent configurations

AgentFence

- Local-first security scanner for AI coding-agent environments.
- Audit supported configuration and instruction files without executing the content you scan. + Audit AI coding-agent configuration before it becomes an attack surface.
+ A local-first, non-executing static scanner for agent instructions, MCP configuration, hooks, permissions, and exposed capabilities.

+ npm version CI - Latest release - Node.js 22 and 24 - Linux, macOS, and Windows - MIT License + GitHub release + Node.js 22 and 24 + MIT license

- Quick Start - · Installation - · Usage examples - · Security + Quick start + · Checks + · Adapters + · Security model + · CLI

+```bash +npx @adulph3/agentfence@0.2.0 scan . +npx @adulph3/agentfence@0.2.0 doctor +``` + +No global installation is required. AgentFence v0.2.0 supports Node.js 22 and 24; Node.js 24 is recommended. + > [!IMPORTANT] -> AgentFence reports observable configuration exposure. It is not a sandbox, a runtime monitor, or a guarantee that an agent, repository, or machine is secure. +> The official npm package is **`@adulph3/agentfence`**. The unscoped package `agentfence` is unrelated to this project. -## What is AgentFence? +## Why AgentFence? -AgentFence is an offline static audit for supported AI coding-agent configuration and instruction files. It identifies review-worthy declarations—such as hooks, shell commands, MCP servers, credential-bearing environment references, broad filesystem roots, and unsafe instruction patterns—before you trust or run the surrounding tooling. +AI coding tools can consume instructions and configuration that grant or request meaningful local capabilities: shell hooks, MCP servers, environment references, filesystem roots, approval modes, and project-level instructions. Reviewing each vendor format by hand is easy to skip and hard to compare. -The scanner uses fixed local discovery, bundled parsers, deterministic rules, and safe terminal or JSON reports. It does not start an agent, execute a hook, launch an MCP server, install a package, resolve a remote endpoint, or send scan data anywhere. +AgentFence provides one conservative, deterministic view of the supported files that are present. It answers: -## Why AgentFence? +- Which agent configuration surfaces were found? +- What capability or risky behavior is declared? +- Which findings deserve review first? +- Was the scan complete, partial, or unable to assess supported input? +- How did each finding affect the observed-risk score? -AI coding agents can read project instructions, load MCP configuration, inherit local capabilities, and invoke lifecycle hooks. Those configuration surfaces are useful, but they can be difficult to review across tools and scopes. +AgentFence reports declarations and requests. It does not claim that a configuration is malicious, reachable, exploitable, or active at runtime. -AgentFence gives developers one conservative view of the supported configuration that is present: +## What it checks -- what agent ecosystem was detected; -- which declared capabilities deserve review; -- where the evidence exists through opaque source identifiers; -- how findings affect an explainable score; and -- whether coverage was complete, partial, or blocked. +| Area | Examples of observable risk | +| --- | --- | +| Secrets | Credential-bearing environment bindings and non-empty literals in recognized sensitive fields | +| Shell | Shell wrappers, elevation, recursive deletion, command composition, and Git push automation | +| Supply chain | Mutable or temporary npm package runners and download-to-interpreter flows | +| MCP | Local process servers, remote endpoints, transport, launcher, enablement, and dynamic construction | +| Network | Plain HTTP MCP endpoints outside literal loopback addresses | +| Filesystem | Broad roots passed through recognized filesystem-server schemas | +| Permissions | Documented approval-bypass or broad auto-approval settings | +| Instructions | Affirmative requests for credential access, safeguard bypass, data transmission, or risky automation | +| Unicode | Bidirectional controls and unusual hidden format/control characters | +| Capability combinations | Shell, network, and sensitive-environment capabilities declared for the same principal | -It describes declarations and requests—not intent, exploitability, live permissions, or compromise. +The executable catalog currently contains 23 versioned rules. See [detector coverage](docs/DETECTORS.md) for rule IDs, confidence boundaries, and intentional exclusions. -## Key features +## Supported ecosystem -| Capability | What AgentFence provides | +These are configuration adapters, not vendor partnerships or endorsements. + +| Adapter | Recognized project surfaces | | --- | --- | -| Cross-agent inspection | Fixed adapters for Codex, Claude Code, Cursor, Kiro, VS Code, and generic MCP configuration | -| MCP analysis | Transport, launcher, package selector, environment binding, enabled-state, endpoint-class, and recognized filesystem-root observations | -| Shell and supply-chain findings | Shell wrappers, elevation, recursive deletion, command composition, Git push automation, mutable package runners, and downloader-to-interpreter flows | -| Secret-safe environment analysis | Detects curated credential-bearing names and literal credential configuration without emitting secret values | -| Instruction and Unicode checks | Conservative instruction heuristics plus bidi and unusual control/format code-point detection | -| Filesystem safety | Bounded discovery and reads, containment checks, no-follow link handling, and explicit partial-coverage reporting | -| Deterministic results | Versioned rules and scoring with stable terminal and JSON output for identical complete inputs | -| Local operation | No application-initiated network requests, telemetry, analytics, backend, remote AI, or live MCP access during `scan` or `doctor` | -| Automation support | Safe JSON reports, threshold-based exits, severity filtering, and a fixed-surface `doctor` command | - -See [detector coverage](docs/DETECTORS.md), [scoring](docs/SCORING.md), and the [threat model](docs/THREAT_MODEL.md) for the precise contracts. - -## Supported ecosystems - -| Ecosystem | Recognized configuration and instruction surfaces | Status | -| --- | --- | :---: | -| OpenAI Codex | `.codex/config.toml`, `AGENTS.md`, `AGENTS.override.md` | Supported | -| Claude Code | `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE*.md`, `.claude/rules/*.md`, documented MCP and nested hook structures | Supported | -| Cursor | `.cursor/mcp.json`, `.cursor/hooks.json`, `.cursor/rules/*.mdc`, legacy `.cursorrules` | Supported | -| Kiro | `.kiro/settings/mcp.json`, `.kiro/hooks/*.json`, `.kiro/steering/*.md` | Supported | -| VS Code | `.vscode/mcp.json`, `.vscode/settings.json` | Supported | -| Generic MCP | `.mcp.json` universal transport, command/argv, URL, and environment semantics | Supported | - -Support is intentionally narrow and versioned. Unknown security-relevant syntax becomes a coverage limitation rather than guessed semantics. User-level configuration is opt-in through `--user-configs` and a fixed allowlist; AgentFence never crawls an entire home directory. See the full [compatibility matrix](docs/COMPATIBILITY.md). +| Codex | `.codex/config.toml`, `AGENTS.md`, `AGENTS.override.md` | +| Claude Code | `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE*.md`, `.claude/rules/*.md`, supported MCP and hook structures | +| Cursor | `.cursor/mcp.json`, `.cursor/hooks.json`, `.cursor/rules/*.mdc`, legacy `.cursorrules` | +| Kiro | `.kiro/settings/mcp.json`, `.kiro/hooks/*.json`, `.kiro/steering/*.md` | +| VS Code | `.vscode/mcp.json`, `.vscode/settings.json` | +| Generic MCP | Recognized `.mcp.json` transport, command/argv, URL, and environment fields | + +Support is intentionally narrow and versioned. Unknown security-relevant syntax becomes a coverage limitation instead of being assigned guessed semantics. `--user-configs` adds a fixed allowlist of supported Codex, Claude Code, Cursor, and Kiro locations; it does not crawl the home directory. See the [compatibility matrix](docs/COMPATIBILITY.md). ## Security model -AgentFence treats repository files, configuration, instructions, hooks, commands, URLs, names, links, and parser failures as hostile data. +Scanned content is hostile data, never authority. -| Guarantee | Behavior | +| Boundary | AgentFence behavior | | --- | --- | -| No scanned-content execution | No agent, hook, command, package, or MCP server is launched | -| No application network activity | `scan` and `doctor` do not initiate runtime network requests, update checks, uploads, or endpoint probes | -| No telemetry | No analytics, backend, cloud account, remote AI, or usage collection | -| Read-only by default | The scan reads bounded supported inputs; only explicit `--output` creates a new report file and it never overwrites an existing destination | -| Secret-safe reporting | Reports omit raw paths, names, values, URLs, commands, headers, parser errors, and secret-derived hashes | -| Explicit uncertainty | Unreadable, malformed, oversized, changing, or unsupported inputs produce partial coverage instead of a false clean result | +| Execution | Does not launch agents, hooks, commands, packages, or MCP servers | +| Network | `scan` and `doctor` make no application-initiated network requests, endpoint probes, uploads, or update checks | +| Privacy | No telemetry, analytics, backend, cloud account, or remote AI | +| Filesystem | Uses bounded discovery and reads; links, non-regular files, and observed containment failures are rejected | +| Output | Omits raw values, commands, URLs, headers, parser errors, secret-derived hashes, and raw paths | +| Writes | Read-only by default; `--output` exclusively creates a new report and never overwrites an existing file | +| Uncertainty | Malformed, unreadable, oversized, changing, or unsupported inputs make coverage partial rather than falsely clean | ```mermaid -flowchart LR - A["Known config & instruction files"] --> B["Bounded acquisition"] - B --> C["Bundled parsers & adapters"] - C --> D["Static rules & scoring"] - D --> E["Safe terminal / JSON report"] +flowchart TD + A["Workspace + opt-in user config"] --> B["Fixed discovery"] + B --> C["Bounded acquisition"] + C --> D["Bundled parsing + adapters"] + D --> E["Versioned rules + scoring"] + E --> F["Safe terminal or JSON report"] ``` -**No execution · No application-initiated network requests · No telemetry** +Raw bytes still exist briefly in process memory, and portable Node.js filesystem checks cannot prove containment against a concurrently hostile tree. For adversarial repositories, use an externally prepared immutable local snapshot. Read the complete [threat model](docs/THREAT_MODEL.md) and [privacy model](docs/PRIVACY.md). + +## Quick start -Raw source bytes still exist in process memory while being analyzed, and portable Node.js checks cannot prove containment against a concurrently hostile filesystem. For adversarial trees, scan an externally prepared immutable local snapshot. Read the complete [privacy model](docs/PRIVACY.md) and [threat model](docs/THREAT_MODEL.md). +### Requirements -## Quick Start +- Node.js 22 or 24 +- A local directory to inspect -AgentFence v0.2.0 supports Node.js 22 and 24; Node.js 24 is recommended. Untested odd-numbered releases are not supported. Once the scoped package is published, use it for a one-off scan without a permanent installation: +Scan the current directory without installing AgentFence globally: ```bash -npx @adulph3/agentfence scan -npx @adulph3/agentfence scan --user-configs +npx @adulph3/agentfence@0.2.0 scan . ``` -The optional permanent installation keeps the executable name `agentfence`: +Run the fixed-surface runtime and safety self-check: ```bash -npm install -g @adulph3/agentfence -agentfence scan -agentfence scan --user-configs +npx @adulph3/agentfence@0.2.0 doctor ``` -For an explicit package selection, `npx --package=@adulph3/agentfence agentfence scan` is equivalent. Verify the scoped package's publication before using these registry-backed commands. The unrelated unscoped npm package `agentfence` is **not this project**. npm/npx installation may contact the registry; AgentFence's `scan` and `doctor` commands make no application-initiated network requests. - -## Installation - -The platform-specific steps below remain available for the separately verified v0.1.0 GitHub artifact. For v0.2.0, use the scoped npm commands in [Quick Start](#quick-start) after confirming publication. - -AgentFence v0.1.0 requires **Node.js 24.x** (`>=24 <25`). It is distributed through GitHub Releases and is **not published to the npm registry**. The commands below install the downloaded local `.tgz` artifact. +`npx` may contact the npm registry to obtain the package. Once running, AgentFence's `scan` and `doctor` commands do not initiate application network activity. -Official artifact: [`agentfence-0.1.0.tgz`](https://github.com/Adulph3/AgentFence/releases/download/v0.1.0/agentfence-0.1.0.tgz) +## Common workflows -SHA-256: +### Scan another project -```text -4d5271aad1a7f56f66555752d6a3184643cac0213a712079af33d95709db278b +```bash +npx @adulph3/agentfence@0.2.0 scan ../another-project ``` -
-Linux - -1. Install Node.js 24 using your preferred version manager or the [official Node.js download](https://nodejs.org/en/download), then verify the runtime: - - ```bash - node --version - npm --version - ``` - - `node --version` must report `v24.x.x`. - -2. Download the official release artifact: - - ```bash - curl -fLO https://github.com/Adulph3/AgentFence/releases/download/v0.1.0/agentfence-0.1.0.tgz - ``` - -3. Verify the checksum: - - ```bash - printf '%s %s\n' \ - '4d5271aad1a7f56f66555752d6a3184643cac0213a712079af33d95709db278b' \ - 'agentfence-0.1.0.tgz' | sha256sum --check - ``` - -4. Install the local package and verify it: - - ```bash - npm install -g ./agentfence-0.1.0.tgz - agentfence --version - agentfence doctor - ``` - -
- -
-macOS - -1. Install Node.js 24 using your preferred version manager or the [official Node.js download](https://nodejs.org/en/download), then verify the runtime: - - ```bash - node --version - npm --version - ``` - - `node --version` must report `v24.x.x`. - -2. Download the official release artifact: - - ```bash - curl -fLO https://github.com/Adulph3/AgentFence/releases/download/v0.1.0/agentfence-0.1.0.tgz - ``` - -3. Verify the checksum: - - ```bash - expected='4d5271aad1a7f56f66555752d6a3184643cac0213a712079af33d95709db278b' - actual="$(shasum -a 256 agentfence-0.1.0.tgz | awk '{print $1}')" - [ "$actual" = "$expected" ] || { echo 'Checksum mismatch' >&2; exit 1; } - ``` - -4. Install the local package and verify it: - - ```bash - npm install -g ./agentfence-0.1.0.tgz - agentfence --version - agentfence doctor - ``` - -
- -
-Windows (PowerShell) - -1. Install Node.js 24 from the [official Node.js download](https://nodejs.org/en/download). Open a new PowerShell window and verify the runtime: - - ```powershell - node --version - npm --version - ``` - - `node --version` must report `v24.x.x`. - -2. Download the official release artifact: - - ```powershell - Invoke-WebRequest ` - -Uri "https://github.com/Adulph3/AgentFence/releases/download/v0.1.0/agentfence-0.1.0.tgz" ` - -OutFile "agentfence-0.1.0.tgz" - ``` +### Include supported user-level configuration -3. Verify the checksum: - - ```powershell - $expected = "4D5271AAD1A7F56F66555752D6A3184643CAC0213A712079AF33D95709DB278B" - $actual = (Get-FileHash .\agentfence-0.1.0.tgz -Algorithm SHA256).Hash - if ($actual -ne $expected) { throw "AgentFence checksum mismatch" } - ``` - -4. Install the local package and verify it: - - ```powershell - npm install -g .\agentfence-0.1.0.tgz - agentfence --version - agentfence doctor - ``` - - On Windows, `--output` files use the inherited ACL of the selected parent directory; operators must choose a suitably restricted parent directory. Mocked and lexical Windows tests do not validate real inherited-ACL confidentiality. - -
+```bash +npx @adulph3/agentfence@0.2.0 scan . --user-configs +``` -On POSIX systems, `--output` creates a new report with mode `0600`. On Windows, report confidentiality depends on the inherited ACL of the selected parent directory, which the operator must restrict appropriately; mocked or lexical Windows tests do not establish real ACL behavior. +### Show only High and Critical findings -## Usage examples +```bash +npx @adulph3/agentfence@0.2.0 scan . --severity high +``` -Run AgentFence from the project you want to inspect: +### Produce JSON for CI or other tooling ```bash -agentfence scan . +npx @adulph3/agentfence@0.2.0 scan . --json --fail-on high > agentfence-report.json ``` -Common workflows: +### Create a report without overwriting an existing file ```bash -# Safe JSON on stdout -agentfence scan . --json +npx @adulph3/agentfence@0.2.0 scan . --output agentfence-report.json +``` -# Create a new JSON report; existing files are never overwritten -agentfence scan . --output report.json +Reports are security artifacts even though raw paths and secret values are omitted. Store and share them accordingly. On POSIX systems, `--output` creates reports with mode `0600`. On Windows, confidentiality depends on the inherited ACL of the parent directory, so the operator must choose a suitably restricted parent directory. Mocked and lexical Windows tests do not prove inherited-ACL confidentiality on a real system. -# Opt into the fixed allowlist of supported user configuration -agentfence scan . --user-configs -# Show High/Critical findings and fail when either is present -agentfence scan . --severity high --fail-on high +## Understanding the report -# Run fixed-surface runtime and self-test diagnostics -agentfence doctor -agentfence doctor --json -``` +| Report element | Meaning | +| --- | --- | +| Coverage | How many eligible sources were analyzed and whether any input was skipped or unsupported | +| Agents | Configuration ecosystems inferred from supported evidence; not proof that a tool is installed or active | +| Findings | Versioned rule matches with severity, confidence, applicability, safe location, and remediation | +| Score | `100 - capped deductions` under scoring model `1.0.0`; a summary of observed configuration risk | +| Highest severity | The most severe finding, shown separately because one severe issue can coexist with a moderate score | +| Errors | Fixed safe codes describing partial or fatal coverage without echoing raw parser/OS errors | + +A score of 100 means no negative finding was observed in successfully assessed supported input. It does **not** certify the repository, agent, or machine as secure. A partial scan has a provisional score, and a scan with no supported input has no score. -The default failure threshold is `high`. A complete scan exits `1` when an applicable High or Critical finding reaches that threshold. +See [scoring](docs/SCORING.md) for weights, caps, grouping, and worked examples. JSON output conforms to the bundled schemas in [`schemas/`](schemas/). ## CLI reference @@ -283,134 +182,188 @@ The default failure threshold is `high`. A complete scan exits `1` when an appli | Command | Purpose | | --- | --- | -| `agentfence scan [PATH]` | Scan a local directory; `PATH` defaults to the invocation directory | -| `agentfence doctor` | Check Node.js support, fixed adapter metadata, and in-memory safety self-tests | -| `agentfence --help` | Print command usage without scanning | +| `agentfence scan [PATH]` | Scan a local directory; `PATH` defaults to the current directory | +| `agentfence doctor [--json]` | Check runtime support, adapter metadata, and in-memory safety self-tests | +| `agentfence --help` | Print usage without scanning | | `agentfence --version` | Print the installed version without scanning | ### Scan options | Option | Behavior | | --- | --- | -| `--json` | Write the complete safe JSON report to stdout | -| `--output PATH` | Create a new JSON report file; never overwrite an existing destination | -| `--severity LEVEL` | Filter terminal presentation only; one of `info`, `low`, `medium`, `high`, `critical` | -| `--fail-on LEVEL` | Set the exit threshold; one of `none`, `info`, `low`, `medium`, `high`, `critical` | +| `--json` | Emit the complete safe JSON report to stdout | +| `--output PATH` | Create a new JSON report; an existing destination is never overwritten | +| `--severity LEVEL` | Filter terminal display: `info`, `low`, `medium`, `high`, or `critical` | +| `--fail-on LEVEL` | Set the exit threshold: `none`, `info`, `low`, `medium`, `high`, or `critical` | | `--user-configs` | Add the fixed allowlist of supported user-level configuration | -| `--no-color` | Disable terminal color; non-empty `NO_COLOR` is also honored | +| `--no-color` | Disable color; a non-empty `NO_COLOR` is also honored | | `--` | End option parsing so a path beginning with `-` can be supplied | -`--severity` never removes findings from JSON and never changes the score. `--fail-on none` disables finding-threshold failures, but partial, fatal, output, and interruption exits still take precedence. `--json --output PATH` is valid and writes only the file. +`--severity` affects terminal presentation only; it never removes JSON findings or changes the score. The default failure threshold is `high`. `--fail-on none` disables finding-threshold failure, but partial, fatal, output, and interruption exits still apply. -## Exit codes +### Exit codes | Code | Meaning | | ---: | --- | -| `0` | Complete scan below the configured threshold, or successful help/version/doctor | +| `0` | Complete scan below the threshold, or successful help/version/doctor | | `1` | Complete scan with an applicable finding at or above `--fail-on` | | `2` | Invalid invocation/root, unsupported runtime, internal fatal error, or output failure | -| `3` | Partial coverage; findings remain useful, but the score is provisional | +| `3` | Partial coverage; known findings remain useful, but the score is provisional | | `130` | User interruption, unless an output failure takes precedence | -Precedence is `2` → `130` → `3` → `1` → `0`. A partial result does not conceal known findings or become successful under `--fail-on none`. +Precedence is `2` → `130` → `3` → `1` → `0`. CI should treat exit `3` as an incomplete assessment that requires review, not as a clean result. + +## Installation options -## CI and automation +### One-off, version-pinned + +```bash +npx @adulph3/agentfence@0.2.0 scan . +``` -Install the verified release artifact in your job, then use AgentFence as a threshold gate: +### Project development dependency ```bash -agentfence scan . --fail-on high +npm install --save-dev --save-exact @adulph3/agentfence@0.2.0 +npx agentfence scan . ``` -For machine-readable evidence: +### Global CLI ```bash -agentfence scan . --json --fail-on high > agentfence-report.json +npm install --global @adulph3/agentfence@0.2.0 +agentfence scan . ``` -Treat exit `1` as a configured policy threshold, exit `3` as incomplete coverage requiring review, and exit `2` as a scanner/runtime failure. Reports can contain sensitive configuration observations even though secret values and raw paths are omitted; handle them as security artifacts. +For reproducible security tooling, prefer an exact version. Confirm the package name includes the `@adulph3/` scope before installation. -The AgentFence repository's workflow is configured to run the complete quality-gate sequence on Ubuntu, macOS, and Windows with Node.js 22.23.2 and 24.21.0. +## How it works -## How AgentFence works +1. **Discovery** matches a fixed registry of supported project files and any explicitly enabled user allowlist. +2. **Acquisition** applies traversal, byte, entry, depth, link, device, and containment limits. +3. **Parsing** uses fixed bundled JSON, JSONC, TOML, and Markdown-aware workers; scanned content cannot select code to load. +4. **Normalization** maps vendor-specific structures to typed facts without preserving raw secret-bearing values. +5. **Analysis** applies a compiled, versioned rule catalog without executing or resolving external state. +6. **Scoring** groups duplicate risk, applies confidence weights and category caps, and marks incomplete scores provisional. +7. **Reporting** emits stable safe DTOs as terminal text or schema-validated JSON. -1. **Discovery** — match only the fixed registry of supported project files and any explicitly enabled user allowlist. -2. **Bounded acquisition** — enforce traversal, entry, file-size, total-byte, link, device, and containment checks. -3. **Isolated parsing** — send bounded bytes to fixed bundled parser/analysis workers; raw buffers and syntax trees do not return to reporters. -4. **Vendor normalization** — project documented Codex, Claude Code, Cursor, Kiro, VS Code, and MCP structures into typed facts. -5. **Static analysis** — apply the versioned rule catalog without executing commands or resolving external state. -6. **Deterministic scoring** — group and cap deductions under scoring model `1.0.0`; partial scores are marked provisional. -7. **Safe reporting** — emit escaped terminal text or schema-validated JSON containing only safe projections. +```text +src/cli command and exit behavior +src/discovery fixed supported-file registry +src/fs bounded local acquisition and exclusive output +src/parsers guarded JSON/JSONC/TOML/Markdown parsing +src/adapters Codex, Claude Code, Cursor, Kiro, VS Code, MCP +src/analysis normalized shell, environment, path, instruction facts +src/rules compiled detector registry +src/scoring deterministic observed-risk model +src/reporters safe terminal and JSON output +schemas versioned machine-readable contracts +``` -For implementation boundaries and public APIs, see [Architecture](docs/ARCHITECTURE.md). +For dependency direction, raw/safe boundaries, and public APIs, read [Architecture](docs/ARCHITECTURE.md). ## Release integrity -| Field | Verified value | +The current stable release is [`v0.2.0`](https://github.com/Adulph3/AgentFence/releases/tag/v0.2.0), built from commit [`36d1a7f`](https://github.com/Adulph3/AgentFence/commit/36d1a7f4ad938b57f52db101ee84a77d891f489c). + +| Field | Value | | --- | --- | -| Release | [`v0.1.0`](https://github.com/Adulph3/AgentFence/releases/tag/v0.1.0) | -| Artifact | [`agentfence-0.1.0.tgz`](https://github.com/Adulph3/AgentFence/releases/download/v0.1.0/agentfence-0.1.0.tgz) | -| SHA-256 | `4d5271aad1a7f56f66555752d6a3184643cac0213a712079af33d95709db278b` | -| Required runtime | Node.js `>=24 <25` | -| Distribution | GitHub Releases only; not the npm registry | +| npm package | [`@adulph3/agentfence@0.2.0`](https://www.npmjs.com/package/@adulph3/agentfence/v/0.2.0) | +| GitHub artifact | [`adulph3-agentfence-0.2.0.tgz`](https://github.com/Adulph3/AgentFence/releases/download/v0.2.0/adulph3-agentfence-0.2.0.tgz) | +| Artifact SHA-256 | `ac7c7bbcedcb07b1a290229ec417a353ce006f88d1efbd81f3184ecb30bd7429` | +| Runtime | Node.js 22 or 24 | +| Hosted CI | Ubuntu, macOS, and Windows on Node.js 22 and 24 | -Always verify the checksum before installing. The release artifact and its digest are also recorded on the [v0.1.0 release page](https://github.com/Adulph3/AgentFence/releases/tag/v0.1.0). +Verify the downloaded GitHub artifact on Linux: -## Project status +```bash +printf '%s %s\n' \ + 'ac7c7bbcedcb07b1a290229ec417a353ce006f88d1efbd81f3184ecb30bd7429' \ + 'adulph3-agentfence-0.2.0.tgz' | sha256sum --check +``` -| Check | Status | -| --- | --- | -| Previously verified GitHub release | v0.1.0 | -| Ubuntu / Node.js 24 CI | Passed | -| macOS / Node.js 24 CI | Passed | -| Windows / Node.js 24 CI | Passed | -| CodeQL default setup | [Passed](https://github.com/Adulph3/AgentFence/actions/runs/34972625363) | -| Private vulnerability reporting | [Available](https://github.com/Adulph3/AgentFence/security/advisories/new) | +On macOS, use `shasum -a 256`; on Windows, use `Get-FileHash -Algorithm SHA256`. Version-specific artifacts and checksums belong on [GitHub Releases](https://github.com/Adulph3/AgentFence/releases). -The platform statuses above refer to the repository's verified Node.js 24 quality-gate run. They do not establish Windows inherited-ACL confidentiality for arbitrary operator-selected output directories. +## Development + +```bash +git clone https://github.com/Adulph3/AgentFence.git +cd AgentFence +npm ci --ignore-scripts +npm run typecheck +npm run lint +npm test +npm run test:coverage +npm run build +``` + +Node.js 22 and 24 are supported. Use synthetic offline fixtures only. Changes to rules, adapters, dependencies, public schemas, or output safety require the focused checks described in [CONTRIBUTING.md](CONTRIBUTING.md). ## Limitations -AgentFence is deliberately static and narrow. It does not: +AgentFence is static analysis, not runtime enforcement. It does not: -- prove that a configuration is safe, malicious, reachable, or exploitable; -- monitor an agent after the scan; -- inspect live agent permissions, trust prompts, processes, or MCP tool descriptions; -- validate credentials, resolve environment values, query package provenance, or perform CVE lookup; -- execute arbitrary hook scripts or fully interpret shell grammar; -- scan Git history, arbitrary source code, an entire home directory, or unknown vendor formats; -- fully contain a filesystem that another process is changing during the scan; or -- guarantee memory zeroization for hostile bytes handled by JavaScript. +- prove that an agent, repository, endpoint, package, or machine is secure; +- observe live permissions, trust prompts, processes, or MCP tool descriptions; +- validate credentials or read their environment values; +- resolve DNS, test endpoint reachability, query CVEs, or verify package provenance; +- fully interpret arbitrary shell languages or execute referenced hook scripts; +- scan Git history, arbitrary application source code, or an entire home directory; +- guarantee complete containment while another process mutates the scanned filesystem; or +- guarantee memory zeroization for bytes handled by JavaScript. -Version pinning reduces selector drift but does not prove package integrity. Instruction heuristics are conservative and can miss multilingual, encoded, indirect, quoted, fenced, or negated requests. Unknown or unsupported security-relevant structures are reported as coverage limitations where possible. +English instruction heuristics can miss multilingual, encoded, indirect, quoted, fenced, or otherwise obfuscated requests. Unsupported formats and incomplete context remain explicit coverage limits. -## Updating and uninstalling +## FAQ -For the scoped npm package, update or uninstall with: +
+Does AgentFence modify my agent configuration? -```bash -npm install -g @adulph3/agentfence@latest -npm uninstall -g @adulph3/agentfence -``` +No. Scans are read-only. Only `--output` writes, and it exclusively creates a new report file. -For a GitHub Release artifact, download its `.tgz`, verify the published checksum, and install the local file: +
-```bash -npm install -g ./agentfence-VERSION.tgz -``` +
+Does it execute instructions, hooks, or MCP servers? + +No. Those values are classified as hostile data and are never executed by the scanner. -## Security reporting +
-Do not post credentials, raw reports, private paths, or exploit payloads in public issues. Report suspected vulnerabilities through [GitHub private vulnerability reporting](https://github.com/Adulph3/AgentFence/security/advisories/new) and include only the minimum synthetic reproduction required. +
+Does it upload my configuration? + +No. `scan` and `doctor` have no application backend, telemetry, remote AI, or application-initiated network requests. + +
+ +
+Does zero findings mean the system is secure? -See [SECURITY.md](SECURITY.md) for the supported scope and disclosure guidance. +No. It means no finding was produced for successfully assessed supported input under the current rule set. Runtime behavior and unsupported surfaces remain outside that conclusion. + +
+ +
+Can it run in CI? + +Yes. Use `--fail-on` for a finding threshold, JSON for automation, and handle partial exit code `3` explicitly. + +
+ +
+Why is the npm package scoped? + +The unscoped npm name is owned by a different project. This repository publishes only as `@adulph3/agentfence`; the executable remains `agentfence` after installation. + +
-## Contributing +## Security and contributing -Contributions must preserve the no-execution, no-application-network, read-only-default, deterministic, and safe-output invariants. Use only synthetic offline fixtures, review every dependency, and run the documented quality gates before opening a pull request. +Do not paste credentials, private configuration, raw reports, private paths, or unfixed exploit details into public issues. Report vulnerabilities through [GitHub private vulnerability reporting](https://github.com/Adulph3/AgentFence/security/advisories/new) and read [SECURITY.md](SECURITY.md). -Read [CONTRIBUTING.md](CONTRIBUTING.md) before changing rules, adapters, dependencies, or public report behavior. +Bug reports and focused pull requests are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and preserve the project's no-execution, zero-runtime-network, read-only-default, deterministic, and safe-output invariants. ## License -AgentFence is released under the [MIT License](LICENSE). +AgentFence is available under the [MIT License](LICENSE). Runtime dependency notices are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). diff --git a/SECURITY.md b/SECURITY.md index a922009..8e99a65 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,8 +1,34 @@ # Security policy -AgentFence v0.1.0 is published on GitHub Releases. v0.2.0 is a local distribution candidate, not a published release. Do not place credentials, raw reports, private paths, or exploit payloads in public issues. Report suspected vulnerabilities through [GitHub private vulnerability reporting](https://github.com/Adulph3/AgentFence/security/advisories/new). Scanner reports are static observations, not incident verdicts. +## Supported versions -If you discover a suspected defect, retain only the minimum synthetic reproduction -needed to explain it and avoid publishing scanned configuration, secret values, -machine paths, or an exploit chain. There is intentionally no claimed response SLA. -The published v0.1.0 GitHub artifact supports Node 24. The v0.2.0 local candidate targets Node 22 and 24 under the chosen npm name `@adulph3/agentfence`, with the `agentfence` executable. This repository has not published to npm. The unrelated unscoped npm package `agentfence` is not this project; npm publication and other runtimes are not yet a supported public distribution claim. +| Version | Status | Node.js | +| --- | --- | --- | +| 0.2.x | Supported | 22 or 24 | +| 0.1.x | Previous GitHub-only release | 24 | + +The current stable package is `@adulph3/agentfence`. The unscoped npm package `agentfence` is unrelated to this repository. + +## Report a vulnerability + +Use [GitHub private vulnerability reporting](https://github.com/Adulph3/AgentFence/security/advisories/new) for suspected vulnerabilities. Do not open a public issue for an unfixed security defect. + +Include only what is needed to reproduce the problem: + +- the AgentFence and Node.js versions; +- the operating system; +- the affected command or API surface; +- expected and observed behavior; and +- a minimal synthetic reproduction. + +Do not include real credentials, raw reports, private configuration, private paths, customer data, or a weaponized exploit chain. Use synthetic values and redact unrelated details. There is no guaranteed response SLA. + +## Security scope + +Useful reports include unintended execution, application-initiated network activity during `scan` or `doctor`, scope escape, unsafe output, secret disclosure, parser bypass, terminal injection, report overwrite, or a result that conceals materially incomplete coverage. + +AgentFence is static analysis. A missed unsupported format, a false positive without security impact, or the absence of a runtime-enforcement feature may be better suited to a regular issue. When uncertain, report privately. + +## Disclosure + +Please allow time to investigate and prepare a fix before public disclosure. Scanner output is an observation of supported configuration, not an incident verdict or a guarantee that a system is secure. diff --git a/docs/COMPATIBILITY.md b/docs/COMPATIBILITY.md index 048cd30..61b3d47 100644 --- a/docs/COMPATIBILITY.md +++ b/docs/COMPATIBILITY.md @@ -1,8 +1,8 @@ # Compatibility -v0.1 recognizes Codex TOML; Claude Code settings/MCP/instructions; Cursor MCP/hooks/rules; Kiro MCP/hooks/steering; VS Code MCP/settings JSONC; and generic `.mcp.json`. Compatibility is based on the dated official links in the master plan (2026-09-10). +AgentFence v0.2.0 recognizes Codex TOML; Claude Code settings/MCP/instructions; Cursor MCP/hooks/rules; Kiro MCP/hooks/steering; VS Code MCP/settings JSONC; and generic `.mcp.json`. Compatibility is based on the dated official links in the master plan (2026-09-10). -The local v0.2.0 `@adulph3/agentfence` distribution candidate preserves this detection scope and supports Node.js 22 and 24 on the existing platform matrix; Node 24 is recommended. The six hosted OS/runtime combinations have not yet run for v0.2.0. The published v0.1.0 GitHub artifact remains Node-24-only. The binary remains `agentfence`; the unrelated unscoped npm package is not this project. +The published v0.2.0 package `@adulph3/agentfence` preserves the v0.1 detection scope and supports Node.js 22 and 24; Node 24 is recommended. Hosted CI passed on Ubuntu, macOS, and Windows with both supported Node majors. The previous v0.1.0 GitHub artifact remains Node-24-only. The binary remains `agentfence`; the unrelated unscoped npm package is not this project. The scanner preserves direct argv boundaries and classifies only documented MCP fields: transport, enabled state, launcher family, package selector, literal numeric endpoint class, curated/sanitized environment binding class, and recognized filesystem-server roots. It does not resolve DNS, environment values, inputs, headers, URLs, commands, package selectors, or root paths. diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md index 58e8089..64c7e14 100644 --- a/docs/PROGRESS.md +++ b/docs/PROGRESS.md @@ -66,3 +66,9 @@ The Node 24 dry-run and actual pack agreed on the scoped package. The tested loc Using that exact archive and an already provisioned npm cache, offline `npm exec --package=` and explicit `npx --package=` passed on both runtimes without global installation. The packed binary reported 0.2.0; help, JSON doctor, clean scan, and opt-in user-config scan passed. The synthetic risky scan returned exit 1 with `AF-SUPPLY-003`; its secret canary was absent from output and its embedded sentinel command was not executed. Separate isolated offline consumers installed the tarball with lifecycle scripts disabled, imported scoped root/core/node entry points, and completed real packed-CLI scans on both runtimes. Two packed-CLI dogfood runs on each runtime were byte-identical across both runtimes (SHA-256 `1c00aaaf17e8a40d498fbbf5688e0045fce991b72e955c6dbdb2be0add11a5ef`): expected partial `AF_WALK_LIMIT`, six analyzed sources, ten findings, score 52. Remaining external gates: owner verification of npm account/scope rights and publication authorization; hosted v0.2.0 Node 22/24 Linux/macOS/Windows CI and required-check configuration; Linux denied-network syscall tracing; actual Windows output-parent ACL validation; and a wholly cache-empty offline consumer. The last is not expected to work without pre-provisioned runtime dependencies, and the local offline audit covers only the available cache. This local result does not claim `@adulph3/agentfence` is published. + +## v0.2.0 public release status + +The external publication gates were subsequently completed. `@adulph3/agentfence@0.2.0` is public on npm, and GitHub release `v0.2.0` points to release commit `36d1a7f4ad938b57f52db101ee84a77d891f489c`. Its GitHub artifact `adulph3-agentfence-0.2.0.tgz` has SHA-256 `ac7c7bbcedcb07b1a290229ec417a353ce006f88d1efbd81f3184ecb30bd7429`. Hosted CI passed on Ubuntu, macOS, and Windows for Node.js 22 and 24, and CodeQL passed. Historical candidate evidence above is retained as the pre-publication record. + +The remaining evidence limits are unchanged where publication does not address them: no Linux syscall-level denied-network trace, no assurance for a wholly cache-empty offline install, and no general Windows inherited-ACL confidentiality proof for arbitrary operator-selected output directories. diff --git a/docs/RELEASE.md b/docs/RELEASE.md index 5d028ae..9c3f8f1 100644 --- a/docs/RELEASE.md +++ b/docs/RELEASE.md @@ -1,17 +1,17 @@ # Release readiness -v0.1.0 is published as a verified [GitHub Release](https://github.com/Adulph3/AgentFence/releases/tag/v0.1.0). Its sole official asset is `agentfence-0.1.0.tgz` (SHA-256 `4d5271aad1a7f56f66555752d6a3184643cac0213a712079af33d95709db278b`). It is not an npm release. +v0.2.0 is the current stable [GitHub Release](https://github.com/Adulph3/AgentFence/releases/tag/v0.2.0) and npm package [`@adulph3/agentfence`](https://www.npmjs.com/package/@adulph3/agentfence/v/0.2.0). Its executable remains `agentfence`, and it supports Node.js 22 and 24. The unrelated unscoped npm package `agentfence` is not this project. -v0.2.0 is a local npm/npx preparation target under the owner-selected public scoped name `@adulph3/agentfence`; it is not yet published. Its executable remains `agentfence`. The unrelated unscoped npm package `agentfence` is not this project. A read-only lookup of `@adulph3/agentfence` on 2026-09-16 returned 404, which is consistent with an unpublished package but does not prove that the owner controls the npm scope. +The release commit is `36d1a7f4ad938b57f52db101ee84a77d891f489c`. The GitHub release artifact is `adulph3-agentfence-0.2.0.tgz` with SHA-256 `ac7c7bbcedcb07b1a290229ec417a353ce006f88d1efbd81f3184ecb30bd7429`. Hosted CI passed on Ubuntu, macOS, and Windows for Node.js 22 and 24, and CodeQL passed for the release. -The validated local Node 24 artifact is `adulph3-agentfence-0.2.0.tgz` (152 files, 90,144 bytes; SHA-256 `fb6327407b814176da352d652b7ff71b7b9d9ae21352066c3091f850b2f2ad56`). This is a local candidate, not a public npm or GitHub release artifact. Node 22 and 24 offline package execution and isolated consumer checks passed against those bytes; see `docs/PROGRESS.md` for the exact evidence and limits. +v0.1.0 remains available as the previous [GitHub-only release](https://github.com/Adulph3/AgentFence/releases/tag/v0.1.0). Its artifact `agentfence-0.1.0.tgz` has SHA-256 `4d5271aad1a7f56f66555752d6a3184643cac0213a712079af33d95709db278b` and requires Node.js 24. -Before any npm publication, the owner must verify npm account/scope access, review the final scoped tarball and security evidence, run the six Node 22/24 Linux/macOS/Windows CI jobs, update branch protection to their actual check names, and explicitly authorize publication. A Linux network-denied packaged runtime trace and actual Windows output-parent ACL validation remain external evidence gaps. Publishing, tags, remote repositories, provenance, and uploads require separate authorization. +A Linux network-denied packaged runtime trace and actual Windows output-parent ACL validation remain external evidence gaps. These limits do not change the verified application-level no-network tests or hosted platform results, and they must not be presented as stronger evidence than they are. Local release checklist: run typecheck, boundary/package checks, full tests, schema/CLI examples, deterministic dogfood, benchmark, and a dry-run package; verify the fixed rule registry and report schemas are packaged; review direct and transitive dependencies, licenses and lifecycle scripts; record exact evidence and the master-plan checksum. Treat an audit as evidence only for the reviewed cache or -network state in which it ran. Do not claim the v0.2.0 package is public until -those external gates and an authorized npm publication are independently complete. +network state in which it ran. Future tags, artifacts, npm publication, and release +notes still require their own explicit authorization and verification.