SafeAI-Static-Analyzer 2.2.1__tar.gz → 2.4.0__tar.gz

{safeai_static_analyzer-2.2.1 → safeai_static_analyzer-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SafeAI-Static-Analyzer
-Version: 2.2.1
+Version: 2.4.0
 Summary: The lightweight, open-source Static AI Capability & Risk Analyzer for CI/CD pipelines.
 Author: IkarusCareer
 License-Expression: Apache-2.0
@@ -31,17 +31,29 @@ Provides-Extra: standalone
 Requires-Dist: pyinstaller>=6.0; extra == "standalone"
 Dynamic: license-file
 
-# SafeAI — Static AI Capability & Risk Analyzer
+# SafeAI — Agent Authority Security for the Software Supply Chain
 
 [![CI](https://github.com/ikaruscareer/SafeAI/actions/workflows/ci.yml/badge.svg)](https://github.com/ikaruscareer/SafeAI/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ikaruscareer/SafeAI/badge)](https://scorecard.dev/viewer/?uri=github.com/ikaruscareer/SafeAI)
 [![Website](https://img.shields.io/badge/web-safeai--analyzer.ikaruscareer.com-0f766e)](https://safeai-analyzer.ikaruscareer.com)
-[![Latest Release](https://img.shields.io/badge/latest-v2.0.1-0f766e)](https://github.com/ikaruscareer/SafeAI/releases/tag/v2.0.1)
+[![Latest Release](https://img.shields.io/badge/latest-v2.3.0-0f766e)](https://github.com/ikaruscareer/SafeAI/releases/tag/v2.3.0)
 [![Best Practices](https://bestpractices.dev/projects/14126/badge)](https://www.bestpractices.dev/en/projects/14126)
 
 Enjoying SafeAI? A ⭐ on [GitHub](https://github.com/ikaruscareer/SafeAI) helps more security teams find it.
 
-**SafeAI** is a static analysis tool that scans AI application source code for security risks, capability exposure, and governance gaps. It is offline and source-private by default — it never executes agents or calls LLMs, and network activity occurs only through explicitly enabled integration commands (currently only `--pr-comment-post`). It integrates into CI/CD pipelines.
+**Know what your AI agent can do before you deploy it.**
+
+**SafeAI** statically maps agent capabilities, tools, MCP integrations, and authority changes, then turns material changes into explainable CI/CD security decisions and portable evidence. Technically, SafeAI is a *Static AI Capability & Risk Analyzer*: it scans AI application source code for security risks, capability exposure, and governance gaps. It is offline and source-private by default — it never executes agents or calls LLMs, and network activity occurs only through explicitly enabled integration commands (currently only `--pr-comment-post`). It integrates into CI/CD pipelines.
+
+**Three pillars — DISCOVER / COMPARE / GOVERN:**
+
+| Pillar | Question | What SafeAI does |
+|---|---|---|
+| **DISCOVER** | What can the agent access? | Builds an evidence-backed model of agent authority: tools, MCP servers, filesystem, shell, databases, APIs, destinations, memory, delegation, autonomy, approval controls |
+| **COMPARE** | What changed? | Diffs authority against the approved baseline: new tools, `read → write` widening, new destinations, removed approval gates |
+| **GOVERN** | Should that change be allowed? | Deterministic CI/CD decisions — `pass`, `review-required`, `block`, `accepted-exception` — with evidence, never an opaque score |
+
+> SafeAI is not a runtime guardrail and does not certify an agent as safe. It provides source-first, evidence-backed visibility into agent authority and meaningful changes *before deployment*.
 
 > 🌐 [safeai-analyzer.ikaruscareer.com](https://safeai-analyzer.ikaruscareer.com) — project landing page
 
@@ -75,6 +87,65 @@ Designed to be lightweight, explainable, and community-driven, SafeAI aims to be
 
 SafeAI sits before runtime guardrails and red-teaming tools in the security lifecycle. It scans agent source code at commit time — detecting framework-specific capabilities, MCP misconfigurations, and prompt injection patterns — before you ever deploy an agent to staging. It does not replace runtime tools (Microsoft AGT), evaluation frameworks (LangSmith, DeepEval), or red-teaming scanners (Promptfoo, Garak). It complements them: find the risk in code first, then validate at runtime.
 
+---
+
+## Example: authority-change report
+
+*SafeAI's most important security event is not simply that a finding exists. It is that an agent's effective authority materially changes.*
+
+```
+Agent: customer-support-agent            Baseline: release v2.4.0 (approved)
+
+AUTHORITY CHANGE (material)
++ tool:        crm_update
++ capability:  database write
++ destination: production CRM
++ access:      read → write
+- human approval gate (GOV_APPROVAL_MISSING)
+
+Policy decision: BLOCK
+Reason: production write authority was added without an approved
+        exception or required approval control.
+Evidence: source files · tool definition · baseline manifest ·
+          current manifest · policy profile · SafeAI version ·
+          ruleset version · commit SHA
+```
+
+The reviewer learns *what the agent can now do that it could not do
+before* — and the decision cites evidence, not a score.
+
+---
+
+## Agent Authority Model
+
+SafeAI builds an analytical model — not an observation of runtime
+permissions — of what an agent is empowered to do:
+
+```
+Agent
+  → Tool / MCP Server / Skill / Workflow Node
+    → Capability
+      → Access Mode (none < read < write < mutate < execute)
+        → Data / Destination / Resource
+          → Authority
+```
+
+Every authority statement carries a class: **declared** (config says so),
+**detected** (code shows it), **inferred** (heuristic, confidence-labelled),
+**repository/IaC-observed** (in-repo infrastructure grants), or
+**unknown**. Runtime-granted authority (live IAM, deployed network policy,
+runtime identity) is explicitly **unknown** to the static scanner —
+*unknown is an evidence state, not evidence of safety*, and SafeAI never
+converts it into a pass.
+
+**What decisions mean.** `pass` means no configured deterministic gate
+triggered — never "the agent is safe." `unknown` means unattributable
+evidence — never "no risk detected." Organizations can govern unknown
+authority explicitly (`authority.unknown` policy, `--unknown-authority`),
+but the default leaves it visible and unfailed.
+
+---
+
 <img width="1024" height="1024" alt="SafeAI_Concept" src="https://github.com/user-attachments/assets/c07999b2-79d5-4200-9eec-ce1ab4e63cc8" />
 
 
@@ -84,7 +155,7 @@ SafeAI sits before runtime guardrails and red-teaming tools in the security life
 
 | Feature | Description |
 |---------|-------------|
-| **Framework Detection** | Detects and parses 17 AI agent frameworks (AST + config + regex, no mutual exclusion) |
+| **Framework Detection** | Detects and parses 19 AI agent frameworks (AST + config + regex, no mutual exclusion) |
 | **Tool Identity & Access Modes** | Capabilities attributed to named tools (agent / MCP server / skill / tool / workflow node) on an access scale `none < read < write < mutate < execute`; inferred modes are flagged, never overstated |
 | **Capability Discovery** | Maps 19 capability categories (shell, filesystem, network, database, memory, MCP, ...) with evidence, confidence, and provenance |
 | **Capability Escalation Detection** | Per-tool authority diffs between scans (new shell, read→write widening, new MCP server, removed approval gate, ...) — 14 rules, including gating-aware subsumption |
@@ -101,7 +172,7 @@ SafeAI sits before runtime guardrails and red-teaming tools in the security life
 | **Baseline & Escalation Gating** | `--fail-on-new` for new/regressed findings, `--fail-on-escalation` for authority changes, `--pr-comment` PR summaries |
 | **Policy-as-Code & Suppressions** | `allow`/`warn`/`require_review`/`deny` policy with selectors; required-reason suppressions |
 | **Assurance Boundary** | Every scan states exactly what it did and could not verify — never a fixed disclaimer |
-| **Security Scorecard** | Deterministic 0–10 score with per-category breakdown and `pass`/`warn`/`fail` outcome; `--scorecard`, `--scorecard-json`, `--scorecard-summary`, and `--scorecard-fail-under` to gate CI on a minimum score |
+| **Security Scorecard** | Deterministic 0–10 score with per-category breakdown and `pass`/`warn`/`fail` outcome; informational unless you opt into `--scorecard-fail-under` gating — evidence and policy decide, the score does not |
 | **CI/CD Integration** | SARIF 2.1.0 output, exit codes, GitHub Actions **Marketplace action** and workflow included |
 | **Community Scan** | Governed private-pilot workflow for scanning public third-party agent frameworks with responsible disclosure (`community-scans/`) — private by default, human-reviewed before any publication |
 | **Multi-Format Reports** | Terminal, JSON, SARIF 2.1.0, HTML, canonical KYA manifest, PR comment, Security Scorecard |
@@ -170,6 +241,8 @@ Registry & Reports — shared SQLite registry; terminal, JSON, SARIF 2.1.0, HTML
 | n8n | ✔ | Partial | Minimal | Minimal | Experimental |
 | Cursor (.cursorrules) | ✔ | Minimal | Minimal | Minimal | Experimental |
 | Windsurf (.windsurfrules) | ✔ | Minimal | Minimal | Minimal | Experimental |
+| OpenClaw config | ✔ | Minimal | Minimal | Minimal | Experimental |
+| GitHub Copilot instructions | ✔ | Minimal | Minimal | Minimal | Experimental |
 
 
 ### Framework Support Details
@@ -194,6 +267,12 @@ Registry & Reports — shared SQLite registry; terminal, JSON, SARIF 2.1.0, HTML
 - **Cursor (.cursorrules)** — detects declared tools/permissions and
   capability-relevant keywords (shell, filesystem, HTTP, database) in the
   IDE's rules config, JSON, YAML, or free text
+- **Windsurf (.windsurfrules)** — detects declared tools, models, and
+  capability-relevant keywords in JSON, YAML, or free-text rules
+- **OpenClaw config** — detects JSON/YAML files under `.openclaw/` and
+  `.openclaw.yaml`, including declared tools, models, and MCP servers
+- **GitHub Copilot instructions** — detects repository instruction Markdown,
+  YAML frontmatter, and `.copilot/*.yml` tool or permission grants
 
 Maturity is on the scale defined in [`docs/reference/FRAMEWORK_SUPPORT.md`](docs/reference/FRAMEWORK_SUPPORT.md):
 **Partial** = reliable detection and discovery with capability/risk analysis over
@@ -211,6 +290,8 @@ Representative test fixtures and validation tests for framework detection:
 | LlamaIndex | `test_llamaindex_framework.py` | `fixtures/llamaindex/representative/agent.py` | @adnqcr7-code [#61] |
 | CrewAI | `test_crewai_framework.py` | `fixtures/crewai/representative/crew.py` | @adnqcr7-code [#62] |
 | Claude Code | `test_claude_code_deep.py` | `fixtures/claude_code/compatibility/` | @adnqcr7-code [#59] |
+| OpenClaw config | `test_config_adapters.py` | `fixtures/openclaw/representative/.openclaw/config.json` | @YaoSong808 [#159] |
+| GitHub Copilot instructions | `test_config_adapters.py` | `fixtures/copilot/representative/.github/copilot-instructions.md` | @YaoSong808 [#159] |
 
 ---
 
@@ -302,6 +383,16 @@ to a shared path, or use `--no-registry` for ephemeral scans.
 - Python 3.11, 3.12, or 3.13
 - PyYAML (for YAML configuration parsing)
 
+### Install from PyPI (recommended)
+
+```bash
+pip install SafeAI-Static-Analyzer
+```
+
+Unpinned on purpose — this always resolves to the latest stable
+release (see [releases](https://github.com/ikaruscareer/SafeAI/releases)).
+Verify the download with [`docs/reference/VERIFICATION.md`](docs/reference/VERIFICATION.md).
+
 ### Install from source
 
 ```bash
@@ -343,6 +434,7 @@ python -m safeai registry <subcommand> [options]
 | `--json` | — | JSON output path |
 | `--html` | — | HTML report output path |
 | `--manifest` | — | Canonical KYA manifest output path (`safeai-manifest.json`) |
+| `--digest-file` | — | With `--manifest`: write `<canonical-sha256>  <manifest-basename>` to this path. The digest is the one `safeai manifest verify` reports, not a raw file hash, so it is not `sha256sum -c` compatible |
 | `--baseline` | — | Prior manifest/report for new/existing comparison |
 | `--fail-on-new` | off | With `--baseline`: fail only on new/regressed findings |
 | `--policy` | `.safeai/policy.yml` | Policy-as-code YAML file |
@@ -450,7 +542,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with: { python-version: '3.12' }
-      - uses: ikaruscareer/SafeAI@v1
+      - uses: ikaruscareer/SafeAI@v2
         with: { path: '.', fail-on: critical }
       - uses: github/codeql-action/upload-sarif@v3
         if: always()
@@ -504,9 +596,13 @@ contributors who have helped make AI safer:
 | [@hadbiaghiles](https://github.com/hadbiaghiles) | AutoGen framework documentation |
 | [@D05TL3](https://github.com/D05TL3) | GitHub Actions scanning example |
 | [@mikemikimike](https://github.com/mikemikimike) | Adapter negative detection tests |
+| [@burakeyler](https://github.com/burakeyler) | `--digest-file` manifest digest sidecar (PR #148) |
+| [@YaoSong808](https://github.com/YaoSong808) | OpenClaw and GitHub Copilot config-file adapters (PR #159) |
 | [@mah](https://github.com/mahirhir) | Claude Code deep analysis documentation |
 | [@asarakhatun17-lgtm](https://github.com/asarakhatun17-lgtm) | Supported frameworks consistency fix |
 | [@yugaaank](https://github.com/yugaaank) | Capability detectors (Docker, Kubernetes, Redis, S3, GCP, Slack, Jira, browser) |
+| [@Teachmeplaycode](https://github.com/Teachmeplaycode) | Benchmark corpus expansion, static subprocess precision gap documentation (PR #174) |
+| [@nikitajos7](https://github.com/nikitajos7) | Policy profile display in terminal and HTML reports (PR #175) |
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved.
 

{safeai_static_analyzer-2.2.1 → safeai_static_analyzer-2.4.0}/README.md

@@ -1,14 +1,26 @@
-# SafeAI — Static AI Capability & Risk Analyzer
+# SafeAI — Agent Authority Security for the Software Supply Chain
 
 [![CI](https://github.com/ikaruscareer/SafeAI/actions/workflows/ci.yml/badge.svg)](https://github.com/ikaruscareer/SafeAI/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ikaruscareer/SafeAI/badge)](https://scorecard.dev/viewer/?uri=github.com/ikaruscareer/SafeAI)
 [![Website](https://img.shields.io/badge/web-safeai--analyzer.ikaruscareer.com-0f766e)](https://safeai-analyzer.ikaruscareer.com)
-[![Latest Release](https://img.shields.io/badge/latest-v2.0.1-0f766e)](https://github.com/ikaruscareer/SafeAI/releases/tag/v2.0.1)
+[![Latest Release](https://img.shields.io/badge/latest-v2.3.0-0f766e)](https://github.com/ikaruscareer/SafeAI/releases/tag/v2.3.0)
 [![Best Practices](https://bestpractices.dev/projects/14126/badge)](https://www.bestpractices.dev/en/projects/14126)
 
 Enjoying SafeAI? A ⭐ on [GitHub](https://github.com/ikaruscareer/SafeAI) helps more security teams find it.
 
-**SafeAI** is a static analysis tool that scans AI application source code for security risks, capability exposure, and governance gaps. It is offline and source-private by default — it never executes agents or calls LLMs, and network activity occurs only through explicitly enabled integration commands (currently only `--pr-comment-post`). It integrates into CI/CD pipelines.
+**Know what your AI agent can do before you deploy it.**
+
+**SafeAI** statically maps agent capabilities, tools, MCP integrations, and authority changes, then turns material changes into explainable CI/CD security decisions and portable evidence. Technically, SafeAI is a *Static AI Capability & Risk Analyzer*: it scans AI application source code for security risks, capability exposure, and governance gaps. It is offline and source-private by default — it never executes agents or calls LLMs, and network activity occurs only through explicitly enabled integration commands (currently only `--pr-comment-post`). It integrates into CI/CD pipelines.
+
+**Three pillars — DISCOVER / COMPARE / GOVERN:**
+
+| Pillar | Question | What SafeAI does |
+|---|---|---|
+| **DISCOVER** | What can the agent access? | Builds an evidence-backed model of agent authority: tools, MCP servers, filesystem, shell, databases, APIs, destinations, memory, delegation, autonomy, approval controls |
+| **COMPARE** | What changed? | Diffs authority against the approved baseline: new tools, `read → write` widening, new destinations, removed approval gates |
+| **GOVERN** | Should that change be allowed? | Deterministic CI/CD decisions — `pass`, `review-required`, `block`, `accepted-exception` — with evidence, never an opaque score |
+
+> SafeAI is not a runtime guardrail and does not certify an agent as safe. It provides source-first, evidence-backed visibility into agent authority and meaningful changes *before deployment*.
 
 > 🌐 [safeai-analyzer.ikaruscareer.com](https://safeai-analyzer.ikaruscareer.com) — project landing page
 
@@ -42,6 +54,65 @@ Designed to be lightweight, explainable, and community-driven, SafeAI aims to be
 
 SafeAI sits before runtime guardrails and red-teaming tools in the security lifecycle. It scans agent source code at commit time — detecting framework-specific capabilities, MCP misconfigurations, and prompt injection patterns — before you ever deploy an agent to staging. It does not replace runtime tools (Microsoft AGT), evaluation frameworks (LangSmith, DeepEval), or red-teaming scanners (Promptfoo, Garak). It complements them: find the risk in code first, then validate at runtime.
 
+---
+
+## Example: authority-change report
+
+*SafeAI's most important security event is not simply that a finding exists. It is that an agent's effective authority materially changes.*
+
+```
+Agent: customer-support-agent            Baseline: release v2.4.0 (approved)
+
+AUTHORITY CHANGE (material)
++ tool:        crm_update
++ capability:  database write
++ destination: production CRM
++ access:      read → write
+- human approval gate (GOV_APPROVAL_MISSING)
+
+Policy decision: BLOCK
+Reason: production write authority was added without an approved
+        exception or required approval control.
+Evidence: source files · tool definition · baseline manifest ·
+          current manifest · policy profile · SafeAI version ·
+          ruleset version · commit SHA
+```
+
+The reviewer learns *what the agent can now do that it could not do
+before* — and the decision cites evidence, not a score.
+
+---
+
+## Agent Authority Model
+
+SafeAI builds an analytical model — not an observation of runtime
+permissions — of what an agent is empowered to do:
+
+```
+Agent
+  → Tool / MCP Server / Skill / Workflow Node
+    → Capability
+      → Access Mode (none < read < write < mutate < execute)
+        → Data / Destination / Resource
+          → Authority
+```
+
+Every authority statement carries a class: **declared** (config says so),
+**detected** (code shows it), **inferred** (heuristic, confidence-labelled),
+**repository/IaC-observed** (in-repo infrastructure grants), or
+**unknown**. Runtime-granted authority (live IAM, deployed network policy,
+runtime identity) is explicitly **unknown** to the static scanner —
+*unknown is an evidence state, not evidence of safety*, and SafeAI never
+converts it into a pass.
+
+**What decisions mean.** `pass` means no configured deterministic gate
+triggered — never "the agent is safe." `unknown` means unattributable
+evidence — never "no risk detected." Organizations can govern unknown
+authority explicitly (`authority.unknown` policy, `--unknown-authority`),
+but the default leaves it visible and unfailed.
+
+---
+
 <img width="1024" height="1024" alt="SafeAI_Concept" src="https://github.com/user-attachments/assets/c07999b2-79d5-4200-9eec-ce1ab4e63cc8" />
 
 
@@ -51,7 +122,7 @@ SafeAI sits before runtime guardrails and red-teaming tools in the security life
 
 | Feature | Description |
 |---------|-------------|
-| **Framework Detection** | Detects and parses 17 AI agent frameworks (AST + config + regex, no mutual exclusion) |
+| **Framework Detection** | Detects and parses 19 AI agent frameworks (AST + config + regex, no mutual exclusion) |
 | **Tool Identity & Access Modes** | Capabilities attributed to named tools (agent / MCP server / skill / tool / workflow node) on an access scale `none < read < write < mutate < execute`; inferred modes are flagged, never overstated |
 | **Capability Discovery** | Maps 19 capability categories (shell, filesystem, network, database, memory, MCP, ...) with evidence, confidence, and provenance |
 | **Capability Escalation Detection** | Per-tool authority diffs between scans (new shell, read→write widening, new MCP server, removed approval gate, ...) — 14 rules, including gating-aware subsumption |
@@ -68,7 +139,7 @@ SafeAI sits before runtime guardrails and red-teaming tools in the security life
 | **Baseline & Escalation Gating** | `--fail-on-new` for new/regressed findings, `--fail-on-escalation` for authority changes, `--pr-comment` PR summaries |
 | **Policy-as-Code & Suppressions** | `allow`/`warn`/`require_review`/`deny` policy with selectors; required-reason suppressions |
 | **Assurance Boundary** | Every scan states exactly what it did and could not verify — never a fixed disclaimer |
-| **Security Scorecard** | Deterministic 0–10 score with per-category breakdown and `pass`/`warn`/`fail` outcome; `--scorecard`, `--scorecard-json`, `--scorecard-summary`, and `--scorecard-fail-under` to gate CI on a minimum score |
+| **Security Scorecard** | Deterministic 0–10 score with per-category breakdown and `pass`/`warn`/`fail` outcome; informational unless you opt into `--scorecard-fail-under` gating — evidence and policy decide, the score does not |
 | **CI/CD Integration** | SARIF 2.1.0 output, exit codes, GitHub Actions **Marketplace action** and workflow included |
 | **Community Scan** | Governed private-pilot workflow for scanning public third-party agent frameworks with responsible disclosure (`community-scans/`) — private by default, human-reviewed before any publication |
 | **Multi-Format Reports** | Terminal, JSON, SARIF 2.1.0, HTML, canonical KYA manifest, PR comment, Security Scorecard |
@@ -137,6 +208,8 @@ Registry & Reports — shared SQLite registry; terminal, JSON, SARIF 2.1.0, HTML
 | n8n | ✔ | Partial | Minimal | Minimal | Experimental |
 | Cursor (.cursorrules) | ✔ | Minimal | Minimal | Minimal | Experimental |
 | Windsurf (.windsurfrules) | ✔ | Minimal | Minimal | Minimal | Experimental |
+| OpenClaw config | ✔ | Minimal | Minimal | Minimal | Experimental |
+| GitHub Copilot instructions | ✔ | Minimal | Minimal | Minimal | Experimental |
 
 
 ### Framework Support Details
@@ -161,6 +234,12 @@ Registry & Reports — shared SQLite registry; terminal, JSON, SARIF 2.1.0, HTML
 - **Cursor (.cursorrules)** — detects declared tools/permissions and
   capability-relevant keywords (shell, filesystem, HTTP, database) in the
   IDE's rules config, JSON, YAML, or free text
+- **Windsurf (.windsurfrules)** — detects declared tools, models, and
+  capability-relevant keywords in JSON, YAML, or free-text rules
+- **OpenClaw config** — detects JSON/YAML files under `.openclaw/` and
+  `.openclaw.yaml`, including declared tools, models, and MCP servers
+- **GitHub Copilot instructions** — detects repository instruction Markdown,
+  YAML frontmatter, and `.copilot/*.yml` tool or permission grants
 
 Maturity is on the scale defined in [`docs/reference/FRAMEWORK_SUPPORT.md`](docs/reference/FRAMEWORK_SUPPORT.md):
 **Partial** = reliable detection and discovery with capability/risk analysis over
@@ -178,6 +257,8 @@ Representative test fixtures and validation tests for framework detection:
 | LlamaIndex | `test_llamaindex_framework.py` | `fixtures/llamaindex/representative/agent.py` | @adnqcr7-code [#61] |
 | CrewAI | `test_crewai_framework.py` | `fixtures/crewai/representative/crew.py` | @adnqcr7-code [#62] |
 | Claude Code | `test_claude_code_deep.py` | `fixtures/claude_code/compatibility/` | @adnqcr7-code [#59] |
+| OpenClaw config | `test_config_adapters.py` | `fixtures/openclaw/representative/.openclaw/config.json` | @YaoSong808 [#159] |
+| GitHub Copilot instructions | `test_config_adapters.py` | `fixtures/copilot/representative/.github/copilot-instructions.md` | @YaoSong808 [#159] |
 
 ---
 
@@ -269,6 +350,16 @@ to a shared path, or use `--no-registry` for ephemeral scans.
 - Python 3.11, 3.12, or 3.13
 - PyYAML (for YAML configuration parsing)
 
+### Install from PyPI (recommended)
+
+```bash
+pip install SafeAI-Static-Analyzer
+```
+
+Unpinned on purpose — this always resolves to the latest stable
+release (see [releases](https://github.com/ikaruscareer/SafeAI/releases)).
+Verify the download with [`docs/reference/VERIFICATION.md`](docs/reference/VERIFICATION.md).
+
 ### Install from source
 
 ```bash
@@ -310,6 +401,7 @@ python -m safeai registry <subcommand> [options]
 | `--json` | — | JSON output path |
 | `--html` | — | HTML report output path |
 | `--manifest` | — | Canonical KYA manifest output path (`safeai-manifest.json`) |
+| `--digest-file` | — | With `--manifest`: write `<canonical-sha256>  <manifest-basename>` to this path. The digest is the one `safeai manifest verify` reports, not a raw file hash, so it is not `sha256sum -c` compatible |
 | `--baseline` | — | Prior manifest/report for new/existing comparison |
 | `--fail-on-new` | off | With `--baseline`: fail only on new/regressed findings |
 | `--policy` | `.safeai/policy.yml` | Policy-as-code YAML file |
@@ -417,7 +509,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with: { python-version: '3.12' }
-      - uses: ikaruscareer/SafeAI@v1
+      - uses: ikaruscareer/SafeAI@v2
         with: { path: '.', fail-on: critical }
       - uses: github/codeql-action/upload-sarif@v3
         if: always()
@@ -471,9 +563,13 @@ contributors who have helped make AI safer:
 | [@hadbiaghiles](https://github.com/hadbiaghiles) | AutoGen framework documentation |
 | [@D05TL3](https://github.com/D05TL3) | GitHub Actions scanning example |
 | [@mikemikimike](https://github.com/mikemikimike) | Adapter negative detection tests |
+| [@burakeyler](https://github.com/burakeyler) | `--digest-file` manifest digest sidecar (PR #148) |
+| [@YaoSong808](https://github.com/YaoSong808) | OpenClaw and GitHub Copilot config-file adapters (PR #159) |
 | [@mah](https://github.com/mahirhir) | Claude Code deep analysis documentation |
 | [@asarakhatun17-lgtm](https://github.com/asarakhatun17-lgtm) | Supported frameworks consistency fix |
 | [@yugaaank](https://github.com/yugaaank) | Capability detectors (Docker, Kubernetes, Redis, S3, GCP, Slack, Jira, browser) |
+| [@Teachmeplaycode](https://github.com/Teachmeplaycode) | Benchmark corpus expansion, static subprocess precision gap documentation (PR #174) |
+| [@nikitajos7](https://github.com/nikitajos7) | Policy profile display in terminal and HTML reports (PR #175) |
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved.
 

{safeai_static_analyzer-2.2.1 → safeai_static_analyzer-2.4.0}/SafeAI_Static_Analyzer.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SafeAI-Static-Analyzer
-Version: 2.2.1
+Version: 2.4.0
 Summary: The lightweight, open-source Static AI Capability & Risk Analyzer for CI/CD pipelines.
 Author: IkarusCareer
 License-Expression: Apache-2.0
@@ -31,17 +31,29 @@ Provides-Extra: standalone
 Requires-Dist: pyinstaller>=6.0; extra == "standalone"
 Dynamic: license-file
 
-# SafeAI — Static AI Capability & Risk Analyzer
+# SafeAI — Agent Authority Security for the Software Supply Chain
 
 [![CI](https://github.com/ikaruscareer/SafeAI/actions/workflows/ci.yml/badge.svg)](https://github.com/ikaruscareer/SafeAI/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ikaruscareer/SafeAI/badge)](https://scorecard.dev/viewer/?uri=github.com/ikaruscareer/SafeAI)
 [![Website](https://img.shields.io/badge/web-safeai--analyzer.ikaruscareer.com-0f766e)](https://safeai-analyzer.ikaruscareer.com)
-[![Latest Release](https://img.shields.io/badge/latest-v2.0.1-0f766e)](https://github.com/ikaruscareer/SafeAI/releases/tag/v2.0.1)
+[![Latest Release](https://img.shields.io/badge/latest-v2.3.0-0f766e)](https://github.com/ikaruscareer/SafeAI/releases/tag/v2.3.0)
 [![Best Practices](https://bestpractices.dev/projects/14126/badge)](https://www.bestpractices.dev/en/projects/14126)
 
 Enjoying SafeAI? A ⭐ on [GitHub](https://github.com/ikaruscareer/SafeAI) helps more security teams find it.
 
-**SafeAI** is a static analysis tool that scans AI application source code for security risks, capability exposure, and governance gaps. It is offline and source-private by default — it never executes agents or calls LLMs, and network activity occurs only through explicitly enabled integration commands (currently only `--pr-comment-post`). It integrates into CI/CD pipelines.
+**Know what your AI agent can do before you deploy it.**
+
+**SafeAI** statically maps agent capabilities, tools, MCP integrations, and authority changes, then turns material changes into explainable CI/CD security decisions and portable evidence. Technically, SafeAI is a *Static AI Capability & Risk Analyzer*: it scans AI application source code for security risks, capability exposure, and governance gaps. It is offline and source-private by default — it never executes agents or calls LLMs, and network activity occurs only through explicitly enabled integration commands (currently only `--pr-comment-post`). It integrates into CI/CD pipelines.
+
+**Three pillars — DISCOVER / COMPARE / GOVERN:**
+
+| Pillar | Question | What SafeAI does |
+|---|---|---|
+| **DISCOVER** | What can the agent access? | Builds an evidence-backed model of agent authority: tools, MCP servers, filesystem, shell, databases, APIs, destinations, memory, delegation, autonomy, approval controls |
+| **COMPARE** | What changed? | Diffs authority against the approved baseline: new tools, `read → write` widening, new destinations, removed approval gates |
+| **GOVERN** | Should that change be allowed? | Deterministic CI/CD decisions — `pass`, `review-required`, `block`, `accepted-exception` — with evidence, never an opaque score |
+
+> SafeAI is not a runtime guardrail and does not certify an agent as safe. It provides source-first, evidence-backed visibility into agent authority and meaningful changes *before deployment*.
 
 > 🌐 [safeai-analyzer.ikaruscareer.com](https://safeai-analyzer.ikaruscareer.com) — project landing page
 
@@ -75,6 +87,65 @@ Designed to be lightweight, explainable, and community-driven, SafeAI aims to be
 
 SafeAI sits before runtime guardrails and red-teaming tools in the security lifecycle. It scans agent source code at commit time — detecting framework-specific capabilities, MCP misconfigurations, and prompt injection patterns — before you ever deploy an agent to staging. It does not replace runtime tools (Microsoft AGT), evaluation frameworks (LangSmith, DeepEval), or red-teaming scanners (Promptfoo, Garak). It complements them: find the risk in code first, then validate at runtime.
 
+---
+
+## Example: authority-change report
+
+*SafeAI's most important security event is not simply that a finding exists. It is that an agent's effective authority materially changes.*
+
+```
+Agent: customer-support-agent            Baseline: release v2.4.0 (approved)
+
+AUTHORITY CHANGE (material)
++ tool:        crm_update
++ capability:  database write
++ destination: production CRM
++ access:      read → write
+- human approval gate (GOV_APPROVAL_MISSING)
+
+Policy decision: BLOCK
+Reason: production write authority was added without an approved
+        exception or required approval control.
+Evidence: source files · tool definition · baseline manifest ·
+          current manifest · policy profile · SafeAI version ·
+          ruleset version · commit SHA
+```
+
+The reviewer learns *what the agent can now do that it could not do
+before* — and the decision cites evidence, not a score.
+
+---
+
+## Agent Authority Model
+
+SafeAI builds an analytical model — not an observation of runtime
+permissions — of what an agent is empowered to do:
+
+```
+Agent
+  → Tool / MCP Server / Skill / Workflow Node
+    → Capability
+      → Access Mode (none < read < write < mutate < execute)
+        → Data / Destination / Resource
+          → Authority
+```
+
+Every authority statement carries a class: **declared** (config says so),
+**detected** (code shows it), **inferred** (heuristic, confidence-labelled),
+**repository/IaC-observed** (in-repo infrastructure grants), or
+**unknown**. Runtime-granted authority (live IAM, deployed network policy,
+runtime identity) is explicitly **unknown** to the static scanner —
+*unknown is an evidence state, not evidence of safety*, and SafeAI never
+converts it into a pass.
+
+**What decisions mean.** `pass` means no configured deterministic gate
+triggered — never "the agent is safe." `unknown` means unattributable
+evidence — never "no risk detected." Organizations can govern unknown
+authority explicitly (`authority.unknown` policy, `--unknown-authority`),
+but the default leaves it visible and unfailed.
+
+---
+
 <img width="1024" height="1024" alt="SafeAI_Concept" src="https://github.com/user-attachments/assets/c07999b2-79d5-4200-9eec-ce1ab4e63cc8" />
 
 
@@ -84,7 +155,7 @@ SafeAI sits before runtime guardrails and red-teaming tools in the security life
 
 | Feature | Description |
 |---------|-------------|
-| **Framework Detection** | Detects and parses 17 AI agent frameworks (AST + config + regex, no mutual exclusion) |
+| **Framework Detection** | Detects and parses 19 AI agent frameworks (AST + config + regex, no mutual exclusion) |
 | **Tool Identity & Access Modes** | Capabilities attributed to named tools (agent / MCP server / skill / tool / workflow node) on an access scale `none < read < write < mutate < execute`; inferred modes are flagged, never overstated |
 | **Capability Discovery** | Maps 19 capability categories (shell, filesystem, network, database, memory, MCP, ...) with evidence, confidence, and provenance |
 | **Capability Escalation Detection** | Per-tool authority diffs between scans (new shell, read→write widening, new MCP server, removed approval gate, ...) — 14 rules, including gating-aware subsumption |
@@ -101,7 +172,7 @@ SafeAI sits before runtime guardrails and red-teaming tools in the security life
 | **Baseline & Escalation Gating** | `--fail-on-new` for new/regressed findings, `--fail-on-escalation` for authority changes, `--pr-comment` PR summaries |
 | **Policy-as-Code & Suppressions** | `allow`/`warn`/`require_review`/`deny` policy with selectors; required-reason suppressions |
 | **Assurance Boundary** | Every scan states exactly what it did and could not verify — never a fixed disclaimer |
-| **Security Scorecard** | Deterministic 0–10 score with per-category breakdown and `pass`/`warn`/`fail` outcome; `--scorecard`, `--scorecard-json`, `--scorecard-summary`, and `--scorecard-fail-under` to gate CI on a minimum score |
+| **Security Scorecard** | Deterministic 0–10 score with per-category breakdown and `pass`/`warn`/`fail` outcome; informational unless you opt into `--scorecard-fail-under` gating — evidence and policy decide, the score does not |
 | **CI/CD Integration** | SARIF 2.1.0 output, exit codes, GitHub Actions **Marketplace action** and workflow included |
 | **Community Scan** | Governed private-pilot workflow for scanning public third-party agent frameworks with responsible disclosure (`community-scans/`) — private by default, human-reviewed before any publication |
 | **Multi-Format Reports** | Terminal, JSON, SARIF 2.1.0, HTML, canonical KYA manifest, PR comment, Security Scorecard |
@@ -170,6 +241,8 @@ Registry & Reports — shared SQLite registry; terminal, JSON, SARIF 2.1.0, HTML
 | n8n | ✔ | Partial | Minimal | Minimal | Experimental |
 | Cursor (.cursorrules) | ✔ | Minimal | Minimal | Minimal | Experimental |
 | Windsurf (.windsurfrules) | ✔ | Minimal | Minimal | Minimal | Experimental |
+| OpenClaw config | ✔ | Minimal | Minimal | Minimal | Experimental |
+| GitHub Copilot instructions | ✔ | Minimal | Minimal | Minimal | Experimental |
 
 
 ### Framework Support Details
@@ -194,6 +267,12 @@ Registry & Reports — shared SQLite registry; terminal, JSON, SARIF 2.1.0, HTML
 - **Cursor (.cursorrules)** — detects declared tools/permissions and
   capability-relevant keywords (shell, filesystem, HTTP, database) in the
   IDE's rules config, JSON, YAML, or free text
+- **Windsurf (.windsurfrules)** — detects declared tools, models, and
+  capability-relevant keywords in JSON, YAML, or free-text rules
+- **OpenClaw config** — detects JSON/YAML files under `.openclaw/` and
+  `.openclaw.yaml`, including declared tools, models, and MCP servers
+- **GitHub Copilot instructions** — detects repository instruction Markdown,
+  YAML frontmatter, and `.copilot/*.yml` tool or permission grants
 
 Maturity is on the scale defined in [`docs/reference/FRAMEWORK_SUPPORT.md`](docs/reference/FRAMEWORK_SUPPORT.md):
 **Partial** = reliable detection and discovery with capability/risk analysis over
@@ -211,6 +290,8 @@ Representative test fixtures and validation tests for framework detection:
 | LlamaIndex | `test_llamaindex_framework.py` | `fixtures/llamaindex/representative/agent.py` | @adnqcr7-code [#61] |
 | CrewAI | `test_crewai_framework.py` | `fixtures/crewai/representative/crew.py` | @adnqcr7-code [#62] |
 | Claude Code | `test_claude_code_deep.py` | `fixtures/claude_code/compatibility/` | @adnqcr7-code [#59] |
+| OpenClaw config | `test_config_adapters.py` | `fixtures/openclaw/representative/.openclaw/config.json` | @YaoSong808 [#159] |
+| GitHub Copilot instructions | `test_config_adapters.py` | `fixtures/copilot/representative/.github/copilot-instructions.md` | @YaoSong808 [#159] |
 
 ---
 
@@ -302,6 +383,16 @@ to a shared path, or use `--no-registry` for ephemeral scans.
 - Python 3.11, 3.12, or 3.13
 - PyYAML (for YAML configuration parsing)
 
+### Install from PyPI (recommended)
+
+```bash
+pip install SafeAI-Static-Analyzer
+```
+
+Unpinned on purpose — this always resolves to the latest stable
+release (see [releases](https://github.com/ikaruscareer/SafeAI/releases)).
+Verify the download with [`docs/reference/VERIFICATION.md`](docs/reference/VERIFICATION.md).
+
 ### Install from source
 
 ```bash
@@ -343,6 +434,7 @@ python -m safeai registry <subcommand> [options]
 | `--json` | — | JSON output path |
 | `--html` | — | HTML report output path |
 | `--manifest` | — | Canonical KYA manifest output path (`safeai-manifest.json`) |
+| `--digest-file` | — | With `--manifest`: write `<canonical-sha256>  <manifest-basename>` to this path. The digest is the one `safeai manifest verify` reports, not a raw file hash, so it is not `sha256sum -c` compatible |
 | `--baseline` | — | Prior manifest/report for new/existing comparison |
 | `--fail-on-new` | off | With `--baseline`: fail only on new/regressed findings |
 | `--policy` | `.safeai/policy.yml` | Policy-as-code YAML file |
@@ -450,7 +542,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with: { python-version: '3.12' }
-      - uses: ikaruscareer/SafeAI@v1
+      - uses: ikaruscareer/SafeAI@v2
         with: { path: '.', fail-on: critical }
       - uses: github/codeql-action/upload-sarif@v3
         if: always()
@@ -504,9 +596,13 @@ contributors who have helped make AI safer:
 | [@hadbiaghiles](https://github.com/hadbiaghiles) | AutoGen framework documentation |
 | [@D05TL3](https://github.com/D05TL3) | GitHub Actions scanning example |
 | [@mikemikimike](https://github.com/mikemikimike) | Adapter negative detection tests |
+| [@burakeyler](https://github.com/burakeyler) | `--digest-file` manifest digest sidecar (PR #148) |
+| [@YaoSong808](https://github.com/YaoSong808) | OpenClaw and GitHub Copilot config-file adapters (PR #159) |
 | [@mah](https://github.com/mahirhir) | Claude Code deep analysis documentation |
 | [@asarakhatun17-lgtm](https://github.com/asarakhatun17-lgtm) | Supported frameworks consistency fix |
 | [@yugaaank](https://github.com/yugaaank) | Capability detectors (Docker, Kubernetes, Redis, S3, GCP, Slack, Jira, browser) |
+| [@Teachmeplaycode](https://github.com/Teachmeplaycode) | Benchmark corpus expansion, static subprocess precision gap documentation (PR #174) |
+| [@nikitajos7](https://github.com/nikitajos7) | Policy profile display in terminal and HTML reports (PR #175) |
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved.