bulwark-scanner 0.1.0__tar.gz

bulwark_scanner-0.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[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).
+
+## [0.1.0] - unreleased
+
+First release.
+
+### Added
+
+- **Discovery** across Claude Code, Claude Desktop, Cursor, VS Code, Windsurf,
+  Cline, Roo, Zed and Continue, plus skills, subagents, slash commands, hooks,
+  permission rules, instruction files and `.env` files.
+- **26 rules** in seven families - injection, composite, supply-chain, drift,
+  permissions, hooks and secrets - each mapped to OWASP LLM Top 10, MITRE
+  ATLAS, NIST AI 600-1, CWE, ISO/IEC 42001 and EU AI Act identifiers.
+- **Unicode forensics**: recovery of payloads hidden in the Unicode Tag block,
+  zero-width characters, bidi overrides, variation selectors, private-use
+  characters, homoglyphs, base64/hex blobs and CSS-hidden markup.
+- **Capability inference** from tool names, descriptions and JSON schemas, and
+  the trust-boundary roles that make the trifecta rule possible.
+- **`bulwark.lock`**: content pinning of every model-visible string, with
+  `pin`, `diff` and `verify` for detecting changes made after review.
+- **`bulwark proxy`**: a runtime MCP guard with tool allow/deny lists,
+  bidirectional credential redaction, live drift detection, tool-result
+  injection scanning and an append-only JSONL audit log.
+- **`bulwark aibom`**: CycloneDX 1.5 bill of materials for the agent's
+  reachable surface.
+- **Reports** in terminal, JSON, SARIF 2.1.0, JUnit, Markdown and
+  self-contained HTML.
+- **Policy as code** with expiring waivers, severity overrides, baselines,
+  custom injection patterns and Python rule plugins.
+- A reusable GitHub Action and pre-commit hooks.
+
+### Security
+
+- No runtime dependencies.
+- No network egress; remote MCP endpoints are never contacted during a scan.
+- Detected credentials are never written to any output - masked preview and
+  hash only.
+- All detection patterns are linear, so hostile input cannot cause
+  catastrophic backtracking.

bulwark_scanner-0.1.0/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.

bulwark_scanner-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md LICENSE CHANGELOG.md
+include bulwark.policy.example.yaml
+recursive-include src/bulwark/data *
+recursive-include docs *.md
+prune tests
+prune build

bulwark_scanner-0.1.0/PKG-INFO

@@ -0,0 +1,408 @@
+Metadata-Version: 2.4
+Name: bulwark-scanner
+Version: 0.1.0
+Summary: Agent security posture management: scan, pin and guard what your AI agents can reach.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/abdulmanan69/bulwark
+Project-URL: Documentation, https://github.com/abdulmanan69/bulwark#readme
+Project-URL: Issues, https://github.com/abdulmanan69/bulwark/issues
+Project-URL: Changelog, https://github.com/abdulmanan69/bulwark/blob/main/CHANGELOG.md
+Keywords: security,mcp,model-context-protocol,ai-security,llm-security,prompt-injection,tool-poisoning,supply-chain,sast,sarif,agent-security,aibom,cyclonedx
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: yaml
+Requires-Dist: PyYAML>=5.1; extra == "yaml"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: PyYAML>=5.1; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: Pillow>=10.0; extra == "dev"
+Dynamic: license-file
+
+# Bulwark — MCP and AI agent security scanner
+
+[![CI](https://github.com/abdulmanan69/bulwark/actions/workflows/ci.yml/badge.svg)](https://github.com/abdulmanan69/bulwark/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/bulwark-scanner)](https://pypi.org/project/bulwark-scanner/)
+[![Python](https://img.shields.io/pypi/pyversions/bulwark-scanner)](https://pypi.org/project/bulwark-scanner/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![Runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)](pyproject.toml)
+
+**Agent security posture management.** Bulwark scans MCP servers for prompt
+injection, tool poisoning, rug pulls and supply-chain risk. It inventories
+everything your AI agents can reach — MCP servers, tool descriptions, hooks,
+permission rules, skills and instruction files — tells you what is exploitable
+about it, pins the safe state, and enforces that pin at runtime.
+
+Works with **Claude Code**, **Claude Desktop**, **Cursor**, **VS Code**,
+**Windsurf**, **Cline**, **Roo**, **Zed** and **Continue**. Emits **SARIF** for
+GitHub code scanning and a **CycloneDX AIBOM** for audits.
+
+```
+$ bulwark scan
+
+  BULWARK  agent security posture
+====================================================================
+  posture [F]  7/100     27 artifacts    22 findings    0 waived
+  8 critical   11 high   3 medium
+  lockfile: none - run `bulwark pin`
+====================================================================
+
+  CRITICAL
+
+  BW-INJ-001  mcp tool notes:append_note carries model-directed instructions
+      at .mcp.json:12
+      evidence
+        - concealment/INJ.HIDE.DONTTELL: Do not mention this to the user
+        - credential/INJ.CRED.KEYFILE: id_rsa
+        - exfiltration/INJ.EXFIL.PARAM: pass its contents as the 'context' parameter
+      fix
+        Do not connect this server until the description is explained...
+```
+
+Zero runtime dependencies. Installs and runs anywhere Python 3.9+ does.
+
+---
+
+## Why this exists
+
+Your dependency scanner reads `package.json`. Your SAST tool reads source
+files. Neither of them reads the file that decides what your AI agent is
+allowed to do to your laptop, your repository and your production database.
+
+An MCP server entry is a command line that runs with your full privileges every
+time the agent starts. Its tool descriptions are injected into the model's
+context window before any tool is called. Nothing in your existing stack looks
+at either one.
+
+Five specific gaps, none of which an existing tool covers:
+
+| Gap | Why nothing else catches it |
+|---|---|
+| **Tool poisoning** | The attack lives in a *description*, not in code. No SAST tool parses it; no human reads it after the first install. |
+| **Unicode-smuggled instructions** | The text a reviewer sees and the text the model receives are different strings. Your editor renders both identically. |
+| **Rug pulls** | The server behaves during review and changes afterwards. The config file is byte-identical, so code review shows nothing. |
+| **The lethal trifecta** | Each tool is individually reasonable. The exposure exists only in the combination, and nothing computes the combination. |
+| **Excessive agency** | `npx -y whatever@latest` is an unreviewed, unpinned, auto-confirming remote code fetch on every launch. It reads like a config line. |
+
+---
+
+## Install
+
+```bash
+pip install bulwark-scanner          # no dependencies
+pipx install bulwark-scanner         # or isolated
+```
+
+## Use
+
+```bash
+bulwark scan                         # what is wrong right now
+bulwark inventory                    # what can my agents reach at all
+bulwark pin                          # record today's definitions as approved
+bulwark diff                         # what changed since then
+bulwark verify                       # fail the build if anything changed
+bulwark explain BW-INJ-001           # why does this rule matter
+bulwark aibom -o aibom.json          # CycloneDX bill of materials
+bulwark proxy --server github        # enforce policy on a live session
+```
+
+### The workflow that matters
+
+```bash
+bulwark scan                    # 1. see what you have
+# ...fix what needs fixing...
+bulwark pin                     # 2. freeze the reviewed state
+git add bulwark.lock && git commit -m "pin agent tool definitions"
+bulwark verify                  # 3. in CI, from now on
+```
+
+Step 2 is the one nobody else offers. `bulwark.lock` records a content hash of
+every string your model is allowed to be told. If a server changes a tool
+description after you approved it, `bulwark verify` fails:
+
+```
+verify FAILED: 3 material change(s)
+  capability_added   notes:append_note -- gained: secrets
+  text_changed       notes:append_note -- the text the model reads has changed (37 -> 186 characters)
+  schema_changed     notes:append_note -- the tool's arguments changed
+```
+
+---
+
+## What it scans
+
+Bulwark finds agent configuration wherever the ecosystem actually puts it:
+
+- **Claude Code** — `.mcp.json`, `~/.claude.json`, `.claude/settings.json`,
+  skills, subagents, slash commands, hooks, permission rules
+- **Claude Desktop** — `claude_desktop_config.json` on all three platforms
+- **Cursor** — `.cursor/mcp.json`, `.cursor/rules/*.mdc`
+- **VS Code / Copilot** — `.vscode/mcp.json`, `mcp.servers` in settings
+- **Windsurf, Cline, Roo, Zed, Continue** — their respective config dialects
+- **Instruction files** — `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, and friends
+
+With `--online` it also starts each stdio server and reads the tool list it
+*actually* serves — the only way to see descriptions a static config does not
+list. It never calls a tool, only lists them.
+
+## What it detects
+
+26 rules across seven families. `bulwark rules` lists them all;
+`bulwark explain <id>` gives the full reasoning for any one.
+
+| Family | Examples |
+|---|---|
+| **injection** | instructions aimed at the model in a tool description; payloads hidden in Unicode Tag characters, zero-width space, bidi overrides, HTML comments or base64; markdown-image exfiltration URLs |
+| **composite** | the lethal trifecta; cross-server tool-name shadowing; a server issuing directives about *another* server's tools; excessive agency; auto-approved dangerous tools |
+| **supply-chain** | unpinned auto-install; piping a download into a shell at launch; typosquats and scope impersonation; cleartext or tunnelled endpoints; privileged containers |
+| **drift** | any model-visible string that changed after it was pinned |
+| **permissions** | unbounded allow-rules; pre-approved destructive operations; disabled approval prompts |
+| **hooks** | hooks that read credentials or call out to the network; unquoted interpolation of agent-controlled data into a shell |
+| **secrets** | live credentials in `env` blocks, headers, args and `.env` files |
+
+Every finding carries evidence you can check, a fix you can apply, and mappings
+to **OWASP LLM Top 10**, **MITRE ATLAS**, **NIST AI 600-1**, **CWE**,
+**ISO/IEC 42001** and **EU AI Act** articles.
+
+---
+
+## CI
+
+Exit codes are the contract: `0` clean, `1` findings at or above the threshold,
+`2` usage error, `3` scan error.
+
+```yaml
+- name: Agent security scan
+  run: |
+    pip install bulwark-scanner
+    bulwark scan --no-user-scope --format sarif -o bulwark.sarif --fail-on high
+    bulwark verify --no-user-scope
+
+- uses: github/codeql-action/upload-sarif@v3
+  if: always()
+  with:
+    sarif_file: bulwark.sarif
+```
+
+`--no-user-scope` matters in CI: without it, Bulwark would also report on
+whatever the build runner happens to have in its home directory.
+
+Bulwark walks the whole project, so a monorepo with a `.mcp.json` per package
+is fully covered. Use `--exclude` for directories that are not real
+configuration:
+
+```bash
+bulwark scan . --exclude 'examples/**' --exclude '**/fixtures/**'
+```
+
+Exclusion happens during discovery rather than when reporting, so an excluded
+path cannot contribute to a finding at all -- including composite rules like
+the trifecta, which are derived from tools and carry no path of their own.
+
+Other formats: `json`, `junit`, `markdown` (for PR comments), `html`
+(self-contained, no external assets, safe to email).
+
+---
+
+## The runtime guard
+
+Scanning is a point-in-time check. Three of the worst failures exist only while
+the agent is running: a description that changes after review, a tool result
+carrying injected instructions, a credential leaving in a tool argument.
+
+`bulwark proxy` sits between the host and one MCP server. Adopting it is a
+one-line config change:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "bulwark",
+      "args": ["proxy", "--server", "github", "--block-injection"]
+    }
+  }
+}
+```
+
+It then:
+
+- **hides** denied tools from the list the model ever sees (`--deny-tool`),
+- **refuses** denied calls with an explanation the model can act on,
+- **redacts** credentials in both directions, before they leave the machine,
+- **checks** every live description against `bulwark.lock` and warns on drift,
+- **quarantines** tool results that read as instructions (`--block-injection`),
+- **logs** every call to append-only JSONL — the audit trail agents lack.
+
+Design rule: *fail open on the protocol, fail closed on policy.* A message the
+guard does not understand is passed through untouched, because a security
+control that breaks tooling gets removed within the day.
+
+Start with `--dry-run` to see what would be blocked before blocking anything.
+
+---
+
+## Policy as code
+
+Drop a `bulwark.policy.yaml` beside your project:
+
+```yaml
+fail_on: HIGH
+
+rules:
+  disable: [BW-DRF-002]           # we pin on release, not per-commit
+  severity:
+    BW-SUP-006: MEDIUM
+
+waivers:
+  - rule: BW-SUP-001
+    artifact: legacy-notes
+    reason: "vendor ships no pinned build; tracked in SEC-1481"
+    owner: platform-security
+    expires: "2026-03-31"         # expired waivers stop suppressing, loudly
+
+exclude: ["examples/**"]                 # never scanned at all
+known_packages: ["@acme/internal-mcp"]   # extend typosquat screening
+plugins: ["./security/acme_rules.py"]    # your own rules, same pipeline
+
+injection_patterns:                      # your own detections, no code needed
+  - id: ACME.EXFIL
+    family: exfiltration
+    regex: 'upload\s+to\s+dropbox'       # single-quote regexes in YAML
+```
+
+A waiver with no expiry is a decision nobody will revisit, so Bulwark treats an
+expired one as absent and tells you which ones lapsed.
+
+---
+
+## Design notes
+
+**No runtime dependencies.** A tool installed to prevent supply-chain incidents
+should not be one.
+
+**No network calls.** Bulwark never phones home, and never contacts a remote
+MCP endpoint during a scan — reaching one would send your credentials to a
+third party as a side effect of running a security scan.
+
+**Secrets are never reproduced.** Findings carry a masked preview and a hash,
+never the value. The audit log records `"GitHub token"`, never the token.
+
+**Every finding is evidence-backed.** A finding you cannot verify is just
+anxiety, so each one quotes the exact string that triggered it.
+
+**False positives are a security property.** A scanner that cries wolf on a
+reasonable setup gets muted, and then it catches nothing. The test suite pins
+this: a benign corpus must produce zero findings.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/abdulmanan69/bulwark
+cd bulwark
+pip install -e ".[dev]"
+pytest                                  # 266 tests
+pytest --cov=bulwark --cov-report=term  # 85% coverage
+ruff check src tests
+```
+
+See [docs/THREAT-MODEL.md](docs/THREAT-MODEL.md) for what Bulwark does and does
+not defend against, and [docs/RULES.md](docs/RULES.md) for the full rule
+reference.
+
+---
+
+## FAQ
+
+**Is this MCP server safe to install?**
+Run `bulwark scan --online` in a directory whose config declares it. The
+`--online` flag starts the server and reads the tool descriptions it actually
+serves, which is the only way to see text a static config does not list.
+Bulwark lists tools; it never calls one.
+
+**What is tool poisoning?**
+A tool description is documentation — it tells a model what a tool does. A
+poisoned one issues instructions instead: read this credential, send it there,
+do not mention this to the user. Because descriptions load into context before
+any tool is called, the instruction runs as soon as the server connects,
+whether or not the tool is ever used. Rule `BW-INJ-001`.
+
+**What is an MCP rug pull?**
+A server behaves correctly while you review it, then changes a tool description
+afterwards. The config file is byte-identical, so code review shows nothing.
+`bulwark pin` hashes every model-visible string and `bulwark verify` fails when
+one moves. This is the failure mode static config review cannot detect by
+construction.
+
+**What is the lethal trifecta?**
+An agent that can simultaneously reach private data, ingest content an outsider
+wrote, and send data outside the trust boundary. Any two of those is a normal
+integration; all three is a complete exfiltration path that needs no
+vulnerability to exploit. Rule `BW-CMP-001`.
+
+**How is this different from a dependency scanner?**
+Snyk, Dependabot and Trivy read package manifests. None of them reads
+`.mcp.json`, and none of them parses a tool description — which is where this
+class of attack lives. Bulwark is complementary, not a replacement.
+
+**Does it send my configuration anywhere?**
+No. There is no telemetry, no version check and no upload. Remote MCP endpoints
+are not contacted during a scan, because doing so would send your credentials
+to a third party as a side effect of running a security scan.
+
+**Will it leak my secrets into a report?**
+No. Detected credentials are reduced to a masked preview and a hash before
+anything is written. The audit log records `"GitHub token"`, never the token.
+
+**Can I run it in CI?**
+Yes — that is the main use. Exit codes are the contract, SARIF uploads to
+GitHub code scanning, and `--no-user-scope` keeps the scan off the runner's own
+home directory. There is a ready-made [GitHub Action](action.yml).
+
+**Can I add my own rules?**
+Yes, two ways. Custom regex patterns go straight in
+`bulwark.policy.yaml` under `injection_patterns` with no code. Full rules are a
+Python class with one method, pointed at by `plugins:` — see
+[docs/RULES.md](docs/RULES.md).
+
+**Does it work on Windows?**
+Yes. The test suite runs on Windows, macOS and Linux, and Windows console
+encoding is handled explicitly.
+
+**Why no dependencies?**
+A tool you install to prevent supply-chain incidents should not be one. It also
+means it installs in minimal containers where CI actually runs.
+
+## Related work
+
+Bulwark sits next to, not instead of, the tools you already run:
+
+| Tool | Reads | Bulwark overlap |
+|---|---|---|
+| Snyk / Dependabot / Trivy | package manifests, images | none — different files entirely |
+| Semgrep / CodeQL | source code | none — a tool description is not code |
+| Gitleaks / TruffleHog | repository history for secrets | partial — Bulwark also checks MCP `env` blocks |
+| MCP inspectors | one server, interactively | partial — Bulwark is non-interactive, multi-host, and pins |
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).