agentscanner 0.1.0__tar.gz

agentscanner-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+*.sarif
+claudit.sarif

agentscanner-0.1.0/DESIGN.md

@@ -0,0 +1,291 @@
+# Claude Code Configuration Security Scanner — Design Document
+
+> Working title: **`agentscanner`** (Claude + audit). A Checkov/Terrascan-style static
+> analyzer for Claude Code configuration artifacts: settings, permissions, hooks,
+> MCP servers, agents/subagents, skills, slash commands, and `CLAUDE.md` memory.
+
+Status: **DRAFT for review** · Owner: sanjeev.k2 · Last updated: 2026-06-15
+
+---
+
+## 1. Problem statement
+
+Developers and product teams increasingly drive their SDLC through Claude Code,
+customizing it with `settings.json`, hooks, skills, subagents, MCP servers, and
+`CLAUDE.md` instructions — at **global (`~/.claude`), project (`.claude/`), local,
+and enterprise/managed** scopes. These artifacts are *powerful by design*: a hook
+is arbitrary code that runs on every tool call; an MCP server is an arbitrary
+process; a permission rule decides what the agent may do without asking; a skill
+or `CLAUDE.md` is untrusted text that steers the model.
+
+Misconfigurations and malicious contributions in these files create real risk:
+**code execution, credential exfiltration, permission bypass, supply-chain
+compromise, and prompt injection** — yet there is no `checkov` for them. Reviewers
+eyeball JSON and Markdown by hand, and CI has nothing to gate on.
+
+`agentscanner` fills that gap: a fast, **static, read-only** scanner that discovers
+Claude Code artifacts, evaluates them against a curated policy catalog, and emits
+prioritized, framework-mapped findings (CLI table, JSON, SARIF) suitable for local
+use, pre-commit, and CI.
+
+### Non-goals (v1)
+- Not a runtime/EDR monitor — it does not observe a live Claude Code session.
+- Not a full "effective permission" simulator — cross-file precedence is handled by
+  a *targeted* check class, not a complete merge engine (see §6, deferred to v2).
+- Not an LLM-based reviewer — checks are deterministic. (An optional
+  `--llm-assist` triage pass is a roadmap item, off by default.)
+
+---
+
+## 2. Core security invariant — the scanner never executes what it parses
+
+`agentscanner` ingests *untrusted* config and prompt files. The single most important
+property: **it MUST NOT execute, source, shell-expand, resolve, or network-fetch
+anything it reads.**
+
+- No running hook commands, `apiKeyHelper`, `statusLine`, or `awsCredentialExport`
+  scripts.
+- No launching MCP servers (`command`/`args` are inspected as data, never spawned).
+- No shell evaluation of interpolated strings; no `eval`, no `subprocess` of parsed
+  content; no following of `url`/`command` targets over the network.
+- File reads are bounded (size cap, no symlink-following outside the scan root).
+
+This is both a safety property (the moment a scanner execs untrusted input, it
+*becomes* the vulnerability) and a selling point we state in the README.
+
+---
+
+## 3. What we scan (artifact taxonomy)
+
+Grounded in the **current** Claude Code schema (verified against live docs,
+2026-06; see §11 sources), not memory.
+
+| Artifact | Locations (user / project / local / managed / plugin) | Format | Why it matters |
+|---|---|---|---|
+| **Settings** | `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, managed `/managed-settings.json`, plugin settings | JSON | permissions, hooks, env, MCP, code-exec helpers, permission mode |
+| **Hooks** | inside settings (`hooks`), agent frontmatter (`hooks`) | JSON | arbitrary command/http/mcp/agent execution at 30+ lifecycle events |
+| **MCP servers** | `.mcp.json`, settings `mcpServers`, agent `mcpServers` | JSON | arbitrary process / remote endpoint; plaintext secrets; supply chain |
+| **Agents / subagents** | `~/.claude/agents/*.md`, `.claude/agents/*.md`, plugin `agents/` | Markdown + YAML frontmatter | tool grants, `permissionMode`, model, prompt content |
+| **Skills** | `~/.claude/skills/*/SKILL.md`, `.claude/skills/...`, plugin `skills/` | Markdown + YAML frontmatter | `allowed-tools`, auto-invocation, prompt content |
+| **Slash commands** | `~/.claude/commands/*.md`, `.claude/commands/*.md` | Markdown + (optional) frontmatter | `allowed-tools`, prompt content |
+| **Memory / instructions** | `CLAUDE.md`, `.claude/CLAUDE.md`, imported memory files | Markdown | prompt-injection / steering vector |
+| **Plugin manifest** | `.claude-plugin/marketplace.json`, `plugin.json` | JSON | provenance / trust of bundled artifacts |
+
+---
+
+## 4. Threat model (what the checks defend against)
+
+Mapped to OWASP LLM Top 10, OWASP Agentic threats, and NIST AI RMF where relevant.
+
+| # | Threat | Example | Primary framework |
+|---|---|---|---|
+| T1 | **Arbitrary code execution via hooks/helpers** | hook runs `curl … \| sh`; `apiKeyHelper` points to a fetched script | OWASP LLM05 (Improper Output Handling) / Agentic "tool misuse" |
+| T2 | **Permission over-grant** | `Bash(*)`, `Bash(curl:*)`, unscoped `sudo`/`rm`/`eval` in `allow` | Agentic "excessive autonomy"; LLM06 Excessive Agency |
+| T3 | **Permission bypass / weakened posture** | `defaultMode: bypassPermissions`, `dontAsk` misuse, project file re-allowing a managed/user deny | LLM06; NIST GOVERN/MANAGE |
+| T4 | **Credential exfil / MITM via endpoint redirect** | `ANTHROPIC_BASE_URL`/`ANTHROPIC_AUTH_TOKEN` pointed at a non-Anthropic host | LLM02 Sensitive Info Disclosure |
+| T5 | **Hardcoded secrets** | plaintext API keys/tokens in `env`, MCP `env`, settings | LLM02 |
+| T6 | **MCP supply chain / untrusted server** | `npx -y`/`uvx` unpinned remote package; auto-trust all project MCP; remote `http://` MCP | LLM03 Supply Chain; MCP guidance |
+| T7 | **Prompt injection in steering files** | `CLAUDE.md`/skill/agent text saying "ignore previous instructions", "disable hooks", exfil instructions; zero-width/bidi unicode | LLM01 Prompt Injection |
+| T8 | **Over-privileged agents/skills** | agent `tools: *` + `permissionMode: bypassPermissions`; skill auto-invocable with broad tools | LLM06 Excessive Agency |
+| T9 | **Hook command/shell injection** | hook does `sh -c "… $tool_input …"` interpolating untrusted input | LLM05 |
+
+---
+
+## 5. Check catalog (v1 MVP — high precision over breadth)
+
+IDs follow **`CC-<CATEGORY>-NNN`** (CC = Claude Code). Each check declares the
+resource type(s) it applies to, a severity, a message, a remediation, and a
+framework mapping. Severities: `CRITICAL / HIGH / MEDIUM / LOW / INFO`.
+
+**MVP set (~14, implemented first):**
+
+| ID | Severity | Title | Applies to |
+|---|---|---|---|
+| `AS-HOOK-001` | CRITICAL | Hook fetches & executes remote code (`curl\|sh`, `wget\|sh`, `eval $(curl)`) | hooks |
+| `AS-HOOK-002` | HIGH | Hook command runs script from relative/world-writable/untrusted path | hooks |
+| `AS-HOOK-003` | MEDIUM | Context-injecting hook (SessionStart/UserPromptSubmit/InstructionsLoaded) makes network calls | hooks |
+| `AS-HOOK-004` | LOW | Hook has no `timeout` (or excessive timeout) | hooks |
+| `AS-PERM-001` | HIGH | Permission mode weakens prompts (`bypassPermissions` / `dontAsk` as default) | settings |
+| `AS-PERM-002` | HIGH | Overly broad Bash allow (`Bash(*)`, `Bash(:*)`, bare-wildcard rules) | settings |
+| `AS-PERM-003` | MEDIUM | Dangerous command allowed unscoped (`curl`, `sudo`, `rm`, `eval`, `chmod`, `nc`) | settings |
+| `AS-MCP-001` | HIGH | Plaintext secret in MCP `env` (key/token pattern) | mcp |
+| `AS-MCP-002` | HIGH | Remote MCP server over non-HTTPS `http://` | mcp |
+| `AS-MCP-003` | HIGH | `enableAllProjectMcpServers: true` (auto-trusts all project MCP) | settings |
+| `AS-MCP-004` | MEDIUM | stdio MCP uses unpinned remote fetch (`npx -y`, `uvx` w/o version) | mcp |
+| `AS-ENV-001` | HIGH | API endpoint/token redirected to non-Anthropic host (`ANTHROPIC_BASE_URL`/`_AUTH_TOKEN`) | settings |
+| `AS-SECRET-001` | HIGH | Hardcoded secret/API key anywhere in a config file | settings, mcp, agent |
+| `AS-AGENT-001` | HIGH | Over-privileged agent/skill (`tools: *`/`All` **and** `permissionMode: bypassPermissions`/`acceptEdits`) | agent, skill |
+| `AS-PROMPT-001` | MEDIUM | Prompt-injection / steering indicators in `CLAUDE.md`/skill/agent (incl. zero-width & bidi unicode) | agent, skill, command, memory |
+
+**Roadmap (v1.x / v2):** `AS-ENV-002` (code-exec helpers `apiKeyHelper`/`statusLine`/`awsCredentialExport` → review), `AS-HOOK-005` (unsafe `tool_input` interpolation), `AS-MCP-005` (unknown/untrusted server vs. allowlist), `CC-XFILE-001` (project re-allows a denied rule — needs cross-file pass), `CC-XFILE-002` (committed permissive `settings.local.json` not gitignored), `AS-PROMPT-002` (large base64/obfuscated blobs).
+
+> **Bypass checks rest on verified matching semantics, not guesses.** Claude Code
+> matches Bash rules with space-boundary-aware wildcards, splits compound commands
+> on `&& || ; | & \n` and matches each subcommand independently, strips a fixed set
+> of wrappers (`timeout`, `nice`, …) but NOT `npx`/`docker exec`, and resolves
+> `deny > ask > allow` with managed scope unoverridable. `AS-PERM-002/003` encode
+> exactly this so we don't ship confident false positives (see §11).
+
+---
+
+## 6. Architecture
+
+```
+                 ┌────────────┐
+  scan target →  │ Discovery  │  walk user/project/local/managed/plugin scopes,
+                 └─────┬──────┘  classify each file → ArtifactType
+                       │
+                 ┌─────▼──────┐
+                 │  Parsers   │  JSON (position-preserving) + Markdown/YAML
+                 └─────┬──────┘  frontmatter → normalized IR with line map
+                       │
+                 ┌─────▼──────┐    Resource{ type, path, attrs, raw, line_index }
+                 │     IR     │
+                 └─────┬──────┘
+                       │
+                 ┌─────▼──────┐  registry of Check objects; each declares
+                 │   Engine   │  applies_to + run(resource) → [Finding]
+                 └─────┬──────┘  (single-file checks now; cross-file class = v2)
+                       │
+                 ┌─────▼──────┐  baseline/suppression, severity threshold,
+                 │  Findings  │  inline `# agentscanner:ignore CC-XXX` directives
+                 └─────┬──────┘
+                       │
+                 ┌─────▼──────┐  CLI table · JSON · SARIF (GitHub code scanning)
+                 │ Reporters  │  exit code from --fail-on / --soft-fail
+                 └────────────┘
+```
+
+### Key design decisions (locked now — costly to retrofit)
+1. **Line mapping is in the IR from day one.** Every `Resource` carries a
+   `value → (line, col)` index. JSON via a position-preserving parse; YAML
+   frontmatter via `ruamel.yaml` (line-aware). Findings always cite `file:line`.
+2. **Per-file scanning for v1.** No global effective-merge resolver. Cross-file
+   posture issues (project re-allowing a managed/user deny) are a *separate check
+   class* run after all files parse — explicitly deferred to v2 to bound scope.
+3. **Curated, high-precision MVP** (~14 checks). Noise on day one kills adoption;
+   breadth is additive later.
+4. **Two check authoring styles.** (a) Python `Check` subclasses for logic-heavy
+   rules; (b) declarative **YAML policies** (jsonpath/regex/conditions) for simple,
+   community-contributable rules — loaded from a built-in dir and `--policy-dir`.
+5. **Rules are independently authored.** The `awesome-claude-security` repo
+   (GPL-3.0) is used as *inspiration and as a fixture corpus to scan*, never as
+   copied rule text/taxonomy — keeping `agentscanner` free to license permissively
+   (Apache-2.0 proposed). See §10.
+
+### Module layout
+```
+src/agentscanner/
+  cli.py            # Typer CLI
+  models.py         # Severity, ArtifactType, Resource (IR), Finding
+  discovery.py      # scope walking + classification
+  parsers/          # json_parser.py (line-aware), markdown_parser.py (frontmatter)
+  checks/
+    base.py         # Check ABC + @register; severity/framework metadata
+    permissions.py  mcp.py  hooks.py  env_secrets.py  agents_skills.py  prompts.py
+  policies/         # built-in declarative YAML rules
+  reporters/        # cli.py  json.py  sarif.py
+  data/             # secret regexes, dangerous-command list, allow/deny patterns
+hardened/           # reference hardened settings (item 5) — the canonical GOOD fixture
+tests/fixtures/{bad,good}/   # paired per-check fixtures (see §8)
+```
+
+---
+
+## 7. CLI UX (Checkov-flavored)
+
+```
+agentscanner scan [PATH]                 # default: scan ./ (+ optional --include-user)
+  --include-user                    # also scan ~/.claude
+  --framework all|settings|hooks|mcp|agents|skills|prompts
+  --check AS-HOOK-001,...           # run only these
+  --skip-check AS-PERM-003,...      # skip these
+  --severity-threshold HIGH         # only report >= threshold
+  --output cli|json|sarif           # default cli
+  --output-file results.sarif
+  --baseline .agentscanner.baseline.json # suppress known/accepted findings
+  --config .agentscanner.yaml            # project config (skips, thresholds, policy-dir)
+  --policy-dir ./policies           # load custom YAML policies
+  --fail-on HIGH                    # exit nonzero if any finding >= level (CI gate)
+  --soft-fail                       # always exit 0
+agentscanner list-checks                 # print catalog (id, severity, title)
+agentscanner version
+```
+
+> **v1 implements a subset of the flags above.** Shipped now: `scan` (with
+> `--include-user`, `--check`, `--skip-check`, `--severity-threshold`, `--output`
+> cli/json/sarif, `--output-file`, `--fail-on`, `--soft-fail`), `list-checks`,
+> `version`. **Roadmap:** `--baseline`, `--config`, `--policy-dir` and the
+> declarative-YAML policy engine (the `policies/` dir). v1 ships Python-coded
+> checks only; shared patterns live in `data.py` (not a separate `data/` dir).
+Distribution: **PyPI** (`pip install agentscanner` / `pipx`/`uvx`), plus a published
+**pre-commit hook** and a **GitHub Action** wrapper. Python 3.9+.
+
+---
+
+## 8. Verification plan (item 3)
+
+**Paired fixtures, not one clean run.** `tests/fixtures/bad/` has one minimal
+artifact per check that MUST trigger exactly that finding; `tests/fixtures/good/`
+holds clean artifacts that MUST scan with zero findings. The **`hardened/`
+reference settings are the canonical known-good fixture**, and every hardening
+choice maps 1:1 to a check — the hardened config and the catalog are duals.
+
+Additional verification:
+- Run `agentscanner` against **real corpora**: this machine's `~/.claude` (settings,
+  hooks, agents, skills) and a checkout of `awesome-claude-security` — confirm
+  signal, measure false-positive rate, hand-triage.
+- Golden-output snapshot tests for JSON/SARIF.
+- SARIF validated against the schema so GitHub code scanning ingests it.
+
+---
+
+## 9. Hardened reference settings (item 5)
+
+Ship `hardened/settings.json` (+ commentary in `hardened/README.md`) as an
+opinionated secure baseline teams can adopt: explicit `deny` for secret-file
+reads/edits, scoped `ask` for `sudo`/`git push`, no `bypassPermissions` default,
+no endpoint redirection, fail-open security hooks with timeouts, pinned MCP
+servers, and no plaintext secrets. Each line is annotated with the `CC-*` check it
+satisfies, making the file both documentation and the primary good-fixture.
+
+---
+
+## 10. Licensing & provenance
+
+- **`agentscanner` license: Apache-2.0** (permissive; PyPI-friendly).
+- `awesome-claude-security` is **GPL-3.0**. We treat it strictly as *inspiration*
+  and as an input corpus to scan; we do **not** copy its rule text, taxonomy, or
+  structure into the package (which could force GPL on `agentscanner`). Cited as prior
+  art in README, not vendored.
+
+---
+
+## 11. Sources (verified, current as of 2026-06)
+
+Permission/settings/hook/agent semantics confirmed against live Claude Code docs
+(`code.claude.com/docs`: `permissions`, `settings`, `env-vars`, `hooks`,
+`mcp-quickstart`, `sub-agents`, `commands`). Threat framing draws on the curated
+AI-security corpus: OWASP LLM Top 10 (`LLMAll_en-US_FINAL.pdf`), OWASP Agentic
+threats (`Agentic-AI-Threats-and-Mitigations_v1.0a.pdf`,
+`OWASP-Top-10-for-Agentic-Applications-2026-12.6-1.pdf`), MCP security
+(`A-Practical-Guide-for-Secure-MCP-Server-Development…pdf`,
+`…Securely-Using-third-party-MCP-Servers1.0.pdf`), and NIST AI RMF
+(`AI_RMF_Playbook.pdf`).
+
+Key verified semantics encoded by checks:
+- Bash rule wildcards are space-boundary aware (`Bash(ls:*)` ≠ `lsof`); compound
+  commands split on `&& || ; | & \n`, each subcommand matched independently;
+  wrappers `timeout/time/nice/nohup/stdbuf/xargs` stripped, but `npx/docker exec/
+  uvx` are NOT.
+- Resolution order **deny → ask → allow**; scope precedence **managed > CLI >
+  local > project > user**; managed deny is unoverridable.
+- Permission modes: `default, acceptEdits, plan, auto, dontAsk, bypassPermissions`;
+  `--dangerously-skip-permissions` = session `bypassPermissions`.
+- Code-exec settings keys: `hooks, apiKeyHelper, awsCredentialExport,
+  awsAuthRefresh, gcpAuthRefresh, otelHeadersHelper, statusLine, mcpServers`.
+- Posture env vars: `ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY`,
+  `CLAUDE_CODE_CERT_STORE`, `DISABLE_*`.
+- 30+ hook events; context-injecting ones (SessionStart, UserPromptSubmit,
+  InstructionsLoaded) add stdout to model context (injection-relevant).
+```

agentscanner-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 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 2026 Sanjeev Jaiswal
+
+   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.

agentscanner-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: agentscanner
+Version: 0.1.0
+Summary: Static security scanner for agentic AI configuration: settings, permissions, hooks, MCP servers, agents, skills, and steering files (Checkov for AI agent stacks).
+Project-URL: Homepage, https://github.com/jassics/agentscanner
+Project-URL: Issues, https://github.com/jassics/agentscanner/issues
+Author-email: "Sanjeev Jaiswal (Jassi)" <jassics@gmail.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agent-security,agentic-ai,claude-code,devsecops,llm-security,mcp,sast,security,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# agentscanner
+
+**Static security scanner for Claude Code configuration** — settings,
+permissions, hooks, MCP servers, agents/subagents, skills, slash commands, and
+`CLAUDE.md`. Think *Checkov / Terrascan, but for your `.claude/` directory.*
+
+Claude Code is customized through powerful, trust-bearing artifacts: a hook is
+arbitrary code that runs on every tool call; an MCP server is an arbitrary
+process; a permission rule decides what the agent may do without asking; a skill
+or `CLAUDE.md` is untrusted text that steers the model. Misconfigurations and
+malicious contributions create real risk — code execution, credential exfil,
+permission bypass, supply-chain compromise, and prompt injection. `agentscanner` finds
+them.
+
+## Core safety invariant
+
+> **agentscanner never executes what it parses.** It does not run hook commands,
+> launch MCP servers, resolve `apiKeyHelper`/`statusLine` scripts, or fetch any
+> URL. It reads untrusted config as *data only* — the moment a scanner execs its
+> input, it becomes the vulnerability.
+
+## Install
+
+```bash
+pip install agentscanner        # or: pipx install agentscanner / uvx agentscanner
+```
+
+## Usage
+
+```bash
+agentscanner scan .                       # scan the current repo's .claude/, .mcp.json, CLAUDE.md
+agentscanner scan . --include-user        # also scan ~/.claude (user scope)
+agentscanner scan . --severity-threshold HIGH
+agentscanner scan . --output sarif --output-file agentscanner.sarif   # for GitHub code scanning
+agentscanner scan . --fail-on HIGH        # CI gate: nonzero exit on HIGH+ findings
+agentscanner list-checks                  # show the check catalog
+```
+
+Every resource is tagged with its **scope** (project / local / user / managed /
+plugin), so a single run cleanly covers a repo, your global config, or both.
+
+## Check catalog (v1)
+
+| ID | Severity | What it catches |
+|---|---|---|
+| `AS-HOOK-001` | CRITICAL | Hook fetches & executes remote code (`curl\|sh`, `eval $(curl)`) |
+| `AS-HOOK-002` | HIGH | Hook runs a script from a relative / world-writable path |
+| `AS-HOOK-003` | MEDIUM | Context-injecting hook (SessionStart/UserPromptSubmit) makes network calls |
+| `AS-HOOK-004` | LOW | Hook has no `timeout` |
+| `AS-PERM-001` | HIGH | `defaultMode: bypassPermissions` / `acceptEdits` weakens prompts |
+| `AS-PERM-002` | HIGH | Overly broad Bash allow (`Bash(*)`, `Bash(:*)`) |
+| `AS-PERM-003` | MEDIUM | Dangerous command allowed unscoped (`curl`, `sudo`, `rm`, `eval`, …) |
+| `AS-MCP-001` | HIGH | Plaintext secret in MCP server `env` |
+| `AS-MCP-002` | HIGH | Remote MCP server over cleartext `http://` |
+| `AS-MCP-003` | HIGH | `enableAllProjectMcpServers: true` (auto-trust all project MCP) |
+| `AS-MCP-004` | MEDIUM | stdio MCP pulls an unpinned remote package (`npx -y pkg`) |
+| `AS-ENV-001` | HIGH | API endpoint/token redirected away from Anthropic |
+| `AS-SECRET-001` | HIGH | Hardcoded secret/API key in a config file |
+| `AS-AGENT-001` | HIGH | Over-privileged agent/skill (`bypassPermissions`, `tools: *`) |
+| `AS-PROMPT-001` | MEDIUM | Prompt-injection / hidden-unicode indicators in steering files |
+| `AS-SKILL-001` | CRITICAL | Skill requests write access to agent identity files |
+| `AS-SKILL-002` | HIGH | Skill has a social-engineering `Prerequisites` section with pipe-to-shell |
+| `AS-SKILL-003` | HIGH | Universal-Format skill missing a cryptographic signature |
+| `AS-SKILL-004` | HIGH | Skill sets `permissions.network: true` (binary boolean, not a domain allowlist) |
+| `AS-SKILL-005` | HIGH | Skill declares explicit shell access |
+| `AS-SKILL-006` | HIGH | Skill `risk_tier` contradicts declared permissions (risk-tier spoofing) |
+| `AS-SKILL-007` | CRITICAL | Skill file contains YAML unsafe-execution tags |
+| `AS-SKILL-008` | HIGH | Skill explicitly disables sandboxed execution |
+| `AS-SKILL-009` | MEDIUM | Universal-Format skill missing `version` field (update-drift risk) |
+| `AS-SKILL-010` | MEDIUM | Skill body contains a standalone base64-encoded block (obfuscated payload) |
+| `AS-SKILL-011` | MEDIUM | Universal-Format skill missing `publisher` field (governance gap) |
+| `AS-SKILL-012` | MEDIUM | Multi-platform skill missing a signature (security metadata lost in translation) |
+
+See [`DESIGN.md`](DESIGN.md) for the architecture, threat model, and the verified
+Claude Code semantics the permission checks are grounded in. A secure baseline
+config lives in [`hardened/`](hardened/).
+
+## CI
+
+GitHub Actions (SARIF upload to code scanning):
+
+```yaml
+- run: pipx install agentscanner
+- run: agentscanner scan . --output sarif --output-file agentscanner.sarif --soft-fail
+- uses: github/codeql-action/upload-sarif@v3
+  with: { sarif_file: agentscanner.sarif }
+```
+
+pre-commit:
+
+```yaml
+- repo: local
+  hooks:
+    - id: agentscanner
+      name: agentscanner
+      entry: agentscanner scan . --fail-on HIGH
+      language: system
+      pass_filenames: false
+```
+
+## Prior art & license
+
+Inspired by [`awesome-claude-security`](https://github.com/jassics/awesome-claude-security)
+(used as inspiration and as a corpus to scan, not as a source of rule text).
+All rules are independently authored. **License: Apache-2.0.**