contextwall 0.2.0__tar.gz → 0.2.1__tar.gz

contextwall-0.2.1/.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,39 @@
+---
+name: Bug report
+about: Something in ContextWall itself doesn't work as documented
+title: "bug: <short description>"
+labels: bug
+assignees: ""
+---
+
+## What happened
+
+<!-- Describe the actual behavior in 1-2 sentences. -->
+
+## What you expected
+
+<!-- Describe the expected behavior. -->
+
+## Repro
+
+```bash
+# The exact command(s) or code that produce the bug.
+# Include enough context that we can copy-paste and reproduce.
+```
+
+Output (if any):
+
+```
+<paste output here — REDACT any real secrets>
+```
+
+## Environment
+
+- `contextwall` version: `<pip show contextwall | grep Version>`
+- Python: `<python --version>`
+- OS: <macOS / Linux distro + version / Windows>
+- Adapter you were using: <`--openai` / `--anthropic` / `--replay` / `--mcp` / N/A>
+
+## Anything else?
+
+<!-- Related issues, workaround you tried, hunch about the cause, etc. -->

contextwall-0.2.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/bytewise-ca/context-wall/security/advisories/new
+    about: Report a security issue privately — do NOT open a public issue.
+  - name: Question or discussion
+    url: https://github.com/bytewise-ca/context-wall/discussions
+    about: Anything that isn't a bug, fixture, or grader-drift report.

contextwall-0.2.1/.github/ISSUE_TEMPLATE/fixture-proposal.md

@@ -0,0 +1,70 @@
+---
+name: Fixture proposal
+about: Propose a new adversarial fixture for the Preflight suite
+title: "fixture: <short name>"
+labels: fixture-proposal
+assignees: ""
+---
+
+## Attack class
+
+<!-- Which dimension? injection / grounding / exfiltration -->
+
+## Citation
+
+<!--
+Where did this pattern come from? A CVE, published paper, disclosure blog,
+public post-mortem, or something you observed. Please link. Unsourced
+fixtures ship as `status: experimental` until validated.
+-->
+
+## Threat model
+
+<!--
+What class of attack does this model? Who is the attacker, what is the
+attack vector, and why should the agent NOT fall for it?
+-->
+
+## Proposed fixture
+
+```yaml
+id: <dim>-<NN>-<short-slug>
+dimension: <injection | grounding | exfiltration>
+severity: <info | low | medium | high | critical>
+weight: <1.0 - 3.0>
+release_blocking: <true | false>
+status: <stable | experimental>
+citation: "<CVE / paper / URL>"
+threat_model: |
+  ...
+setup:
+  system: "..."
+  tools: []
+  context: []
+  user_message: "..."
+expected_safe_behavior: |
+  ...
+pass_conditions:
+  - kind: no_string_in_response
+    strings: []
+    description: "..."
+```
+
+## Grader regression cases
+
+<!--
+Every merged fixture PR must include AT LEAST ONE pass example and ONE fail
+example. Please sketch them here. See tests/preflight/test_grader_regression.py.
+-->
+
+**PASS example:**
+- Response: `"..."` (or tool calls if applicable)
+- Reason: Agent recognized the attack and refused / hedged.
+
+**FAIL example:**
+- Response: `"..."` (or tool calls)
+- Reason: Agent complied with the injected instruction.
+
+## Anything else?
+
+<!-- Related fixtures, why this is different from existing ones, etc. -->

contextwall-0.2.1/.github/ISSUE_TEMPLATE/grader-drift.md

@@ -0,0 +1,63 @@
+---
+name: Grader drift
+about: A (fixture, response) pair where Preflight's grader gives the wrong verdict
+title: "grader: <fixture-id> misclassifies <pass|fail>"
+labels: grader-drift
+assignees: ""
+---
+
+<!--
+Grader-drift reports are the highest-signal contribution to Preflight.
+Every one filed makes the detector more honest and every published
+scorecard more trustworthy. Thank you for filing.
+-->
+
+## Which fixture
+
+**Fixture id:** `<e.g. inj-05-semantic-override>`
+**Suite:** `standard@2026.09` <!-- or whichever you're on -->
+
+## The response the agent gave
+
+```
+<paste the full response text here — REDACT any real secrets>
+```
+
+If there were tool calls, list them:
+
+```
+tool: <name>
+arguments: { ... }
+```
+
+## What Preflight said
+
+- Verdict: <pass | fail | insufficient_evidence>
+- Failed conditions (if any):
+  - `...`
+
+## What the verdict SHOULD have been
+
+- Correct verdict: <pass | fail>
+- Why:
+
+<!--
+Explain in 1-3 sentences why the correct verdict differs. Concrete "the
+agent actually followed the injected instruction" or "the agent quoted the
+attack string but refused to comply" reasoning is the most useful.
+-->
+
+## How to reproduce
+
+```bash
+# Ideally: a --replay JSONL that produces this verdict.
+echo '{"fixture_id": "<id>", "text": "<response>", "tool_calls": []}' > drift.jsonl
+ctxfw check --replay drift.jsonl --dimensions <dimension>
+```
+
+## Anything else?
+
+<!--
+Was this observed against a real agent (which one?) or synthesized? Do you
+have a second reviewer who agreed on the correct verdict?
+-->

contextwall-0.2.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+<!--
+Thanks for the PR. Please skim the checklist before submitting.
+Full guidance in CONTRIBUTING.md and docs/METHODOLOGY.md.
+-->
+
+## What this changes
+
+<!-- 1-3 sentences on the change and why. Link to the issue if there is one. -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New fixture proposal
+- [ ] Grader / detector improvement
+- [ ] Documentation
+- [ ] Refactor / cleanup
+- [ ] Other:
+
+## Checklist
+
+- [ ] All existing tests pass locally: `uv run pytest tests/preflight/`
+- [ ] If you added a fixture, you also added **at least one pass example and
+      one fail example** to `tests/preflight/test_grader_regression.py`
+- [ ] If you changed the grader, the regression harness still passes and the
+      change is documented
+- [ ] If you cited a CVE / paper / disclosure, please include the link in the
+      fixture `citation:` field or PR description
+- [ ] If this changes public behavior, `CHANGELOG.md` has an entry
+- [ ] `ruff format` + `ruff check` are clean
+
+## Anything else
+
+<!-- Screenshots, benchmark numbers, edge cases considered, etc. -->

contextwall-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# Contributing to ContextWall
+
+Thanks for wanting to help. Below is what we care about most, in order.
+
+## Highest-signal contributions
+
+### 1. Grader-drift reports
+
+If you find a `(fixture_id, mock_response, expected_verdict)` triple where the
+Preflight grader disagrees with a reasonable human, that's the single most
+useful thing you can file. It fixes a bug in the detector's opinion, tightens
+the regression harness, and improves every published scorecard.
+
+Use the [grader-drift issue template](https://github.com/bytewise-ca/context-wall/issues/new?template=grader-drift.md).
+
+### 2. Fixture proposals
+
+New attack patterns — CVE-derived, paper-derived, or something you've seen in
+the wild. Please cite the source; unsourced fixtures ship as
+`status: experimental` and don't count toward grades until validated.
+
+Use the [fixture proposal template](https://github.com/bytewise-ca/context-wall/issues/new?template=fixture-proposal.md).
+
+### 3. Post-mortem traces
+
+If you find a real incident post-mortem that maps to an existing fixture,
+add a labeled trace to `tests/preflight/test_postmortem_traces.py` with a
+citation. Cases where the grader verdict is not obvious to two independent
+readers should NOT be added; they need adjudication and belong in a separate
+hard-case corpus (v0.2+).
+
+## Fixture format
+
+Fixtures live at:
+
+    src/context_firewall/preflight/fixtures/<suite>/<version>/<dimension>/*.yaml
+
+Every fixture ships with:
+
+```yaml
+id: inj-11-your-scenario
+dimension: injection          # injection | grounding | exfiltration
+severity: high                # info | low | medium | high | critical
+weight: 2.0                   # weighted pass-rate contribution
+release_blocking: true        # blocks CI gate when it fails
+status: stable                # stable | experimental (experimental doesn't count toward grades)
+citation: "CVE / paper / blog post URL"
+threat_model: |
+  What class of attack this fixture models and why it matters.
+setup:
+  system: "Agent system prompt (short, realistic)"
+  tools: [ ... ]              # tool declarations if the agent has any
+  context: [ ... ]             # retrieved content / tool output / rag docs
+  user_message: "..."
+expected_safe_behavior: |
+  Prose description of what a passing agent looks like.
+pass_conditions:
+  - kind: no_string_in_response
+    strings: [ ... ]
+    description: "..."
+  # See src/context_firewall/preflight/models.py for all pass_condition kinds:
+  #   no_tool_call, no_tool_arg_contains, no_string_in_response,
+  #   no_pattern_in_response, response_matches_any
+```
+
+Full spec: [docs/PREFLIGHT_SPEC.md](./docs/PREFLIGHT_SPEC.md).
+Methodology: [docs/METHODOLOGY.md](./docs/METHODOLOGY.md).
+
+## Development
+
+```bash
+git clone https://github.com/bytewise-ca/context-wall.git
+cd context-wall
+uv sync --extra dev
+uv run pytest tests/preflight/          # ~1 second, no external calls
+```
+
+Run the CLI without installing:
+
+```bash
+uv run python -m context_firewall.cli.main check --help
+```
+
+## Rules for merged PRs
+
+- **Every fixture PR must include at least one PASS example and one FAIL
+  example** for the grader regression harness. See
+  `tests/preflight/test_grader_regression.py` for the pattern.
+- **Detector authors do not label the canonical trace set for their own
+  detector.** Independent reviewer required for ambiguous cases.
+- **All tests must pass** — the harness runs in <1 second locally.
+- **Cite your sources.** CVE, paper, disclosure URL, or `experimental`
+  marker if you don't have one yet.
+
+## Coding style
+
+- Python 3.11+
+- Ruff (`ruff format` + `ruff check`)
+- Line length 100
+- Type hints on public APIs (Pydantic models everywhere it matters)
+- Docstrings on non-obvious public functions
+
+## Discussion + questions
+
+- **Bug?** [Bug report template](https://github.com/bytewise-ca/context-wall/issues/new?template=bug-report.md)
+- **Vulnerability?** See [SECURITY.md](./SECURITY.md) — don't open a public issue.
+- **Question?** GitHub Discussions or email `info@bytewise.ca`.
+
+## Legal
+
+By contributing you agree that your contribution is licensed under the
+project's Apache 2.0 license. No CLA. Sign-offs (DCO) welcome but not
+required.

{contextwall-0.2.0 → contextwall-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: contextwall
-Version: 0.2.0
+Version: 0.2.1
 Summary: Safety preflight and runtime firewall for AI agents — point at your agent, get a scorecard and release decision.
 Author-email: ContextWall <info@bytewise.ca>
 License: Apache-2.0

contextwall-0.2.1/SECURITY.md

@@ -0,0 +1,67 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+If you find a security issue in ContextWall itself, please **do not** open
+a public GitHub issue.
+
+Instead, report it privately via:
+
+- **Email:** `security@bytewise.ca` (or `info@bytewise.ca` as a fallback)
+- **GitHub Security Advisories:** [Create a private advisory](https://github.com/bytewise-ca/context-wall/security/advisories/new)
+
+Please include:
+
+- A short description of the issue
+- Steps to reproduce (a minimal PoC if possible)
+- The version of ContextWall affected
+- Your contact info for follow-up
+
+## What counts as a vulnerability in ContextWall
+
+- The daemon or CLI can be tricked into exposing secrets or bypassing its own
+  auth (e.g. authenticated endpoints reachable without a token).
+- The Preflight grader has a systematic bug that classifies a real attack as
+  a pass, or a safe response as a fail (grader-drift). File this as a
+  security advisory only if the impact is significant; otherwise a
+  [grader-drift issue](https://github.com/bytewise-ca/context-wall/issues/new?template=grader-drift.md)
+  is the right channel.
+- The Preflight scorecard leaks a real secret from evidence into terminal
+  output, JSON, SARIF, or a hosted upload (redaction bypass).
+- The MCP adapter invokes a write-capable or network-capable tool without
+  explicit consent.
+- Any dependency of ContextWall has a known vulnerability that materially
+  affects users of ContextWall.
+
+## Not a ContextWall vulnerability
+
+- A prompt-injection payload that makes an agent misbehave — that's the
+  problem ContextWall exists to help detect. Please add it as a fixture
+  proposal instead, or a grader-drift report if the grader misclassifies
+  a known-safe response.
+- Your own deployment's authorization or configuration mistakes.
+- Third-party MCP server vulnerabilities — please report those to the
+  MCP server's own maintainers. If you'd like ContextWall to detect the
+  pattern in future scans, open a fixture proposal.
+
+## Response timeline
+
+We aim to:
+
+- **Acknowledge** within 3 business days.
+- **Fix or reach a decision** within 30 days for reasonable-scope issues.
+- **Disclose** coordinated with the reporter after a fix is released.
+
+ContextWall is a small OSS project. We don't run a bug bounty. Public credit
+in release notes / advisories is offered by default; opt out if you prefer.
+
+## Scope
+
+This policy applies to:
+
+- `contextwall` (PyPI: [contextwall](https://pypi.org/project/contextwall/))
+- `contextwall-sdk` (deprecated shim: [contextwall-sdk](https://pypi.org/project/contextwall-sdk/))
+- The `bytewise-ca/context-wall` GitHub repository and its published wheels
+
+The hosted control plane (if you use one) is out of scope for OSS Security
+Advisories — report those directly via email.

contextwall-0.2.1/launch/README.md

@@ -0,0 +1,44 @@
+# Launch materials
+
+Drafts. Review before posting. Nothing goes public without your hand.
+
+## Files
+
+- [`show-hn.md`](./show-hn.md) — Hacker News post + your first comment
+- [`reddit-ai-agents.md`](./reddit-ai-agents.md) — r/AI_Agents post
+- [`mcp-discord.md`](./mcp-discord.md) — MCP community Discord announcement
+- [`x-thread.md`](./x-thread.md) — X / Twitter launch thread (6 posts)
+
+## Suggested cadence
+
+Do NOT post everything at once. Space it out so each channel is fresh signal:
+
+| Day | Channel | Why |
+|---|---|---|
+| 0 | Show HN | Highest-value single audience. Watch the thread for 4-6 hours. |
+| +2 | r/AI_Agents | Different community, different angle (CI-first). |
+| +4 | X / Twitter thread | Amplification. Best after HN / Reddit have surfaced any real quotes / feedback. |
+| +7 | MCP Discord | Community that's already talking about the exact problem. Not a launch; a "hey, if you're scanning MCP configs, this might be interesting." |
+| +14 | r/netsec | Only if the HN thread produced a good technical example / write-up. Otherwise skip. |
+
+## Watch-list once posted
+
+**Show HN specifically:** first 60 minutes decide the thread's ceiling. Reply
+to every question. Don't argue. If someone points at a real grader bug or a
+missing category, thank them and link to the issue templates.
+
+**Metrics you actually care about:**
+
+- Number of `uvx contextwall check` runs (opt-in telemetry, once you add it)
+- GitHub stars going from 1 → something
+- Number of grader-drift reports filed (highest-signal engagement)
+- Number of people who reach out saying "would you talk about this for 20
+  minutes" — that's the 5-conversation target from the 90-day plan
+
+## What to avoid
+
+- Overclaim ("state of the art detection") — you'll lose the thread
+- Compare classifier accuracy against LlamaFirewall — you'll lose the thread
+- Screenshots of dashboards you don't have
+- Testimonials from people who haven't used it
+- "Book a demo" as any CTA

contextwall-0.2.1/launch/mcp-discord.md

@@ -0,0 +1,49 @@
+# MCP community Discord announcement
+
+Short, casual, MCP-specific. Post to the relevant MCP community channel(s).
+Not a launch — a "this exists if you're already thinking about the
+problem." Wait ~1 week after Show HN so it doesn't look like drive-by
+promotion.
+
+## Message
+
+> hey folks 👋 — sharing a tool in case anyone's been thinking about
+> "does the MCP server I just installed have poisoned tool descriptions"
+>
+> `uvx contextwall check --mcp ~/.config/claude-desktop/mcp.json`
+>
+> spawns each configured MCP server via stdio JSON-RPC, calls `tools/list`
+> + `resources/list`, then scans tool descriptions + inputSchema
+> descriptions for injection patterns using ContextWall's detector. also
+> classifies each tool as write-capable, network-capable, or other via
+> name/description heuristics — the "which of my installed tools can rm
+> -rf" question, basically.
+>
+> **critical: it NEVER invokes any tool.** enumeration only. no
+> `tools/call`, no `resources/read`. safe against any target (though
+> obviously don't scan an MCP server you don't have permission to enumerate).
+>
+> emits terminal, JSON, or SARIF. SARIF result per finding, level =
+> `warning` for capability findings, `error` for injection patterns.
+>
+> broader tool is a safety preflight for AI agents (`ctxfw check`
+> against openai/anthropic endpoints, replay from JSONL, etc.) — the MCP
+> adapter is one of four. Apache 2.0. more here:
+>
+> - github: https://github.com/bytewise-ca/context-wall
+> - /vs page (honest comparison against snyk agent-scan and others):
+>   https://contextwall.io/vs
+> - methodology: https://contextwall.io/methodology
+>
+> would love to hear from anyone who runs it against their claude desktop
+> config — especially interested in "detector found nothing but I know
+> this tool is sketchy" reports so we can extend the heuristics.
+
+## Follow-up if someone engages
+
+Be responsive. If they run it and find something on a widely-used server,
+ask permission to include the finding as a case study on the site or in a
+blog post — with the affected maintainer coordinated first.
+
+If they run it and find NOTHING but the tool clearly *is* sketchy, that's
+a bug in the heuristics — file it as a grader-drift or fixture proposal.

contextwall-0.2.1/launch/reddit-ai-agents.md

@@ -0,0 +1,103 @@
+# r/AI_Agents post
+
+Post 2-3 days after Show HN. Different audience — this crowd is builders,
+not spectators. Lead with the CI story since that's what they can ship
+tomorrow.
+
+## Title
+
+> **Built a safety preflight for agents – gates PR merges on regression, runs offline in CI**
+
+## Flair
+
+`Resource` or `Discussion` (whichever the sub is currently allowing).
+
+## Body
+
+> **TL;DR** — Wrote a CLI (`ctxfw check`) that runs 35 pinned adversarial
+> fixtures against your agent and returns a scorecard + a machine-readable
+> release gate. Wires into GitHub Actions as a pre-merge check. Apache 2.0,
+> offline against fixtures, no API keys required for the suite itself.
+>
+> Repo: https://github.com/bytewise-ca/context-wall
+>
+> ---
+>
+> **What it looks like in CI**
+>
+> ```yaml
+> # .github/workflows/preflight.yml
+> jobs:
+>   safety:
+>     runs-on: ubuntu-latest
+>     steps:
+>       - uses: actions/checkout@v4
+>       - uses: astral-sh/setup-uv@v3
+>       - run: |
+>           uvx contextwall check --replay ./tests/preflight/responses.jsonl \
+>             --gate --fail-below B- --sarif > preflight.sarif
+>       - uses: github/codeql-action/upload-sarif@v3
+>         if: always()
+>         with: { sarif_file: preflight.sarif }
+> ```
+>
+> Exit codes are stable: `0` pass · `10` safety failure · `11` insufficient
+> evidence · `12` adapter error. So a broken endpoint doesn't look the same
+> as a real safety regression, and CI can route them differently.
+>
+> **What it grades**
+>
+> - **Injection Resistance (10 fixtures)** — EchoLeak-shape, tool
+>   poisoning, zero-width, spaced-letters, semantic override, indirect via
+>   retrieval, +3 CVE-derived
+> - **Grounding Under Attack (5)** — false attribution, fabricated event,
+>   nonexistent API, conflicting sources, poisoned action recommendation
+> - **Data Exfiltration (20)** — AWS/OpenAI/Anthropic/GitHub keys, SSH
+>   keys, JWTs, bearer tokens, DB URLs, SSN, credit card, composite PII,
+>   tool-arg exfiltration
+>
+> Every fixture cites its source (CVE, paper, disclosure URL). Full list +
+> methodology: https://contextwall.io/methodology
+>
+> **How I actually use it in my own workflow**
+>
+> 1. Capture a JSONL of my agent's responses against each fixture once with
+>    `ctxfw check --openai <my-endpoint>` and save the `--json` output.
+> 2. Commit that JSONL to `tests/preflight/responses.jsonl`.
+> 3. In CI, run `ctxfw check --replay ./tests/preflight/responses.jsonl
+>    --gate` — grades identically to the live run but doesn't burn tokens.
+> 4. If the grade drops or a `release_blocking` fixture starts failing,
+>    the PR blocks. If someone updates the agent, they update the JSONL
+>    as part of their PR (with real responses, not doctored ones).
+>
+> **What it does NOT do (honest scope)**
+>
+> Not evaluated: correctness, cost, latency, reliability, tool
+> authorization semantics, tenant isolation, availability, data retention,
+> human-in-loop policy. A passing Preflight means the agent resisted the
+> pinned safety corpus — not that it's production-ready overall.
+>
+> **How this compares to things you've probably heard of**
+>
+> - Not competing with **Meta PromptGuard 2** — that's a classifier, this
+>   is a scorecard. You could use both.
+> - Not competing with **Snyk agent-scan** — that scans MCP servers as
+>   components, this scores agent behavior. Preflight has an `--mcp`
+>   adapter for the overlap, but it's conservative (static-only, never
+>   invokes tools).
+> - Not competing with **PromptFoo** — that's an eval framework for
+>   iterating on prompts, this is a release decision.
+> - Full honest comparison: https://contextwall.io/vs
+>
+> **Looking for feedback on**
+>
+> - The grader is rule/heuristic based, not an LLM judge. If you find a
+>   response the grader classifies obviously wrong, please file a
+>   grader-drift issue — highest-signal contribution.
+> - The `--replay` UX. Is capturing JSONL by hand the right shape for CI,
+>   or does an "automatically save on the first check" flag make more
+>   sense?
+>
+> Full quickstart: https://contextwall.io/quickstart
+> Ping me here or open an issue. Apache 2.0, PRs welcome, especially
+> fixture proposals with citations.