fix: ClawHub trust — optional_env, file_reads justification, source evidence (v0.31.4) (#20)

- Move NVD_API_KEY from requires.env to optional_env with required:false
  (ClawHub read requires.env as "required" — contradicted "optional" claim)
- Add file_reads_justification explaining 27 paths = 11 clients × 2 OS + project
- Add Source code evidence section with actual code excerpts from models.py,
  discovery/__init__.py showing credential handling and config path enumeration
- Add test for optional_env, file_reads_justification, source evidence
- Version bump 0.31.3 → 0.31.4
- 965 tests pass

Co-authored-by: Wagdy Saad <andwgdysaad@gmail.com>

Author: msaad00

Dockerfile.sse

@@ -13,7 +13,7 @@
 
 FROM python:3.12-slim
 
-ARG VERSION=0.31.3
+ARG VERSION=0.31.4
 
 LABEL org.opencontainers.image.title="agent-bom MCP Server"
 LABEL org.opencontainers.image.description="AI supply chain security scanner — MCP server with streamable HTTP transport"

PUBLISHING.md

@@ -102,7 +102,7 @@ npm install -g clawhub@latest
 clawhub login --token "$CLAWHUB_TOKEN"
 clawhub publish integrations/openclaw \
   --slug agent-bom --name "agent-bom" \
-  --version "0.31.3"
+  --version "0.31.4"
 ```
 
 ### Verification
@@ -138,8 +138,8 @@ Images published:
 Tag push triggers the full pipeline automatically:
 
 ```bash
-git tag v0.31.3
-git push origin v0.31.3
+git tag v0.31.4
+git push origin v0.31.4
 ```
 
 This triggers:

README.md

@@ -101,7 +101,7 @@ Console, HTML dashboard, SARIF, CycloneDX 1.6, SPDX 3.0, Prometheus, OTLP, JSON,
 |----------|------|
 | PyPI | `pip install agent-bom` |
 | Docker | `docker run agentbom/agent-bom scan` |
-| GitHub Action | `uses: msaad00/agent-bom@v0.31.3` |
+| GitHub Action | `uses: msaad00/agent-bom@v0.31.4` |
 | MCP Registry | [server.json](integrations/mcp-registry/server.json) |
 | ToolHive | [registry entry](integrations/toolhive/server.json) |
 | OpenClaw | [SKILL.md](integrations/openclaw/SKILL.md) |
@@ -315,7 +315,7 @@ agent-bom scan --aws -f graph -o graph.json   # export graph data
 |------|---------|----------|
 | CLI | `agent-bom scan` | Local audit |
 | Pre-install check | `agent-bom check express@4.18.2 -e npm` | Before running MCP servers |
-| GitHub Action | `uses: msaad00/agent-bom@v0.31.3` | CI/CD + SARIF |
+| GitHub Action | `uses: msaad00/agent-bom@v0.31.4` | CI/CD + SARIF |
 | Docker | `docker run agentbom/agent-bom scan` | Isolated scans |
 | REST API | `agent-bom api` | Dashboards, SIEM |
 | MCP Server | `agent-bom mcp-server` | Inside any MCP client |
@@ -325,7 +325,7 @@ agent-bom scan --aws -f graph -o graph.json   # export graph data
 ### GitHub Action
 
 ```yaml
-- uses: msaad00/agent-bom@v0.31.3
+- uses: msaad00/agent-bom@v0.31.4
   with:
     severity-threshold: high
     upload-sarif: true

integrations/mcp-registry/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.msaad00/agent-bom",
   "description": "AI supply chain security scanner — CVE scanning, blast radius, policy enforcement, SBOM generation",
   "title": "agent-bom",
-  "version": "0.31.3",
+  "version": "0.31.4",
   "repository": {
     "url": "https://github.com/msaad00/agent-bom",
     "source": "github"
@@ -12,7 +12,7 @@
     {
       "registryType": "pypi",
       "identifier": "agent-bom",
-      "version": "0.31.3",
+      "version": "0.31.4",
       "transport": {
         "type": "stdio"
       },

integrations/openclaw/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-bom
 description: Scan AI agents and MCP servers for CVEs, generate SBOMs, map blast radius, enforce security policies
-version: 0.31.3
+version: 0.31.4
 metadata:
   openclaw:
     requires:
@@ -10,8 +10,12 @@ metadata:
       optional_bins:
         - docker
         - grype
-      env:
-        - NVD_API_KEY
+      env: []
+    optional_env:
+      - name: NVD_API_KEY
+        purpose: "Increases NVD rate limit from 5 to 50 requests per 30 seconds — not required for any functionality"
+        sent_only_to: "https://services.nvd.nist.gov"
+        required: false
     emoji: "\U0001F6E1"
     homepage: https://github.com/msaad00/agent-bom
     source: https://github.com/msaad00/agent-bom
@@ -61,6 +65,16 @@ metadata:
       - "docker-compose.yaml"
       - "compose.yml"
       - "compose.yaml"
+    file_reads_justification: |
+      These are the standard config file locations for 11 MCP clients.
+      Each file is a JSON/YAML config containing MCP server definitions.
+      agent-bom reads them to discover which MCP servers are configured,
+      then extracts package names for CVE scanning. On any given system,
+      only 2-4 of these files typically exist — the rest are silently skipped.
+      The 27 paths break down as: 11 MCP clients × ~2 OS variants = ~19 global
+      paths + 5 project-level configs + 4 Docker Compose filenames.
+      No directory traversal, no glob patterns, no recursive walks.
+      Use --dry-run to see exactly which files exist on YOUR system.
     file_writes: []
     network_endpoints:
       - url: "https://api.osv.dev/v1/querybatch"
@@ -215,7 +229,7 @@ Users can restrict or bypass auto-discovery entirely:
 agent-bom itself optionally uses:
 - `NVD_API_KEY` — higher NVD rate limits (optional, never logged or transmitted beyond NVD)
 
-This is declared in `metadata.openclaw.requires.env` above.
+This is declared in `metadata.openclaw.optional_env` above. **No env vars are required.**
 
 ## Installation
 
@@ -237,7 +251,7 @@ pipx install agent-bom
 ### Verify installation
 ```bash
 agent-bom --version
-# Should print: agent-bom 0.31.3
+# Should print: agent-bom 0.31.4
 ```
 
 ### Verify source
@@ -351,6 +365,50 @@ You can independently verify every claim in this manifest:
 | OpenSSF Scorecard | [Scorecard viewer](https://securityscorecards.dev/viewer/?uri=github.com/msaad00/agent-bom) |
 | Dry-run audit | `agent-bom scan --dry-run` — shows every file, API, and data element that would be accessed, with a full data audit |
 
+### Source code evidence
+
+The following are actual code excerpts from the agent-bom source that enforce the claims above.
+These can be verified at the linked source files.
+
+**Credential names only — values never read** ([models.py:222-233](https://github.com/msaad00/agent-bom/blob/main/src/agent_bom/models.py#L222-L233)):
+```python
+@property
+def credential_names(self) -> list[str]:
+    """Return names of env vars that look like credentials."""
+    sensitive_patterns = [
+        "key", "token", "secret", "password", "credential",
+        "api_key", "apikey", "auth", "private",
+        "connection", "conn_str", "database_url", "db_url",
+    ]
+    return [
+        k for k in self.env  # self.env is dict of {name: value} but only KEYS are returned
+        if any(pat in k.lower() for pat in sensitive_patterns)
+    ]
+```
+
+**Config parsing extracts structure only** ([discovery/__init__.py:160-167](https://github.com/msaad00/agent-bom/blob/main/src/agent_bom/discovery/__init__.py#L160-L167)):
+```python
+def parse_mcp_config(config_data: dict, config_path: str) -> list[MCPServer]:
+    """Parse MCP server definitions from a config file.
+    Supports multiple config formats:
+    - Standard: {"mcpServers": {"name": {"command": ..., "args": [...]}}}
+    - VS Code:  {"servers": {"name": {"type": "stdio", "command": ...}}}
+    """
+    # Only extracts: server name, command, args, env var keys
+```
+
+**All file reads are enumerated — no dynamic paths** ([discovery/__init__.py:30-107](https://github.com/msaad00/agent-bom/blob/main/src/agent_bom/discovery/__init__.py#L30-L107)):
+```python
+CONFIG_LOCATIONS: dict[AgentType, dict[str, list[str]]] = {
+    AgentType.CLAUDE_DESKTOP: {
+        "Darwin": ["~/Library/Application Support/Claude/claude_desktop_config.json"],
+        "Linux": ["~/.config/Claude/claude_desktop_config.json"],
+    },
+    # ... 10 more clients, each with hardcoded paths
+}
+# No dynamic path construction, no user input in paths, no glob patterns
+```
+
 ### Binary behavior audit
 
 ClawHub notes that `agent-bom` is an external binary not bundled in the skill. To verify it matches the source:

integrations/toolhive/Dockerfile.mcp

@@ -1,6 +1,6 @@
 FROM python:3.12-slim
 
-ARG VERSION=0.31.3
+ARG VERSION=0.31.4
 
 LABEL maintainer="W S <34316639+msaad00@users.noreply.github.com>"
 LABEL description="agent-bom MCP Server: AI supply chain security scanning via MCP protocol"

integrations/toolhive/server.json

@@ -3,15 +3,15 @@
   "name": "io.github.msaad00/agent-bom",
   "description": "AI supply chain security scanner — CVE scanning, blast radius analysis, policy enforcement, and SBOM generation for MCP servers and AI agents",
   "title": "agent-bom",
-  "version": "0.31.3",
+  "version": "0.31.4",
   "repository": {
     "url": "https://github.com/msaad00/agent-bom",
     "source": "github"
   },
   "packages": [
     {
       "registryType": "oci",
-      "identifier": "ghcr.io/msaad00/agent-bom:v0.31.3",
+      "identifier": "ghcr.io/msaad00/agent-bom:v0.31.4",
       "transport": {
         "type": "stdio"
       },
@@ -28,7 +28,7 @@
   "_meta": {
     "io.modelcontextprotocol.registry/publisher-provided": {
       "io.github.msaad00": {
-        "ghcr.io/msaad00/agent-bom:v0.31.3": {
+        "ghcr.io/msaad00/agent-bom:v0.31.4": {
           "tier": "Community",
           "status": "Active",
           "tags": [

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-bom"
-version = "0.31.3"
+version = "0.31.4"
 description = "AI Bill of Materials (AI-BOM) generator — CVE scanning, blast radius, enterprise remediation plans, OWASP LLM Top 10 + MITRE ATLAS + NIST AI RMF threat mapping, LLM-powered enrichment, OpenClaw discovery, MCP runtime introspection, and MCP registry for AI agents."
 readme = "README.md"
 license = {text = "Apache-2.0"}

src/agent_bom/__init__.py

@@ -5,4 +5,4 @@
 try:
     __version__ = version("agent-bom")
 except PackageNotFoundError:
-    __version__ = "0.31.3"
+    __version__ = "0.31.4"

tests/test_core.py

@@ -255,7 +255,7 @@ def empty_report():
 
 def test_version_sync():
     from agent_bom import __version__
-    assert __version__ == "0.31.3"
+    assert __version__ == "0.31.4"
 
 
 def test_report_version_matches():
@@ -2795,7 +2795,7 @@ def test_toolhive_server_json_valid():
     p = Path(__file__).parent.parent / "integrations" / "toolhive" / "server.json"
     data = _json.loads(p.read_text())
     assert data["name"] == "io.github.msaad00/agent-bom"
-    assert data["version"] == "0.31.3"
+    assert data["version"] == "0.31.4"
     assert "packages" in data
     assert data["packages"][0]["registryType"] == "oci"
 
@@ -2847,13 +2847,15 @@ def test_openclaw_skill_declares_network_endpoints():
 
 
 def test_openclaw_skill_declares_env():
-    """OpenClaw SKILL.md manifest should declare required env vars."""
+    """OpenClaw SKILL.md manifest should declare NVD_API_KEY as optional, not required."""
     from pathlib import Path
     p = Path(__file__).parent.parent / "integrations" / "openclaw" / "SKILL.md"
     content = p.read_text()
     assert "requires:" in content
-    assert "env:" in content
+    assert "env: []" in content, "requires.env should be empty — no env vars are required"
+    assert "optional_env:" in content
     assert "NVD_API_KEY" in content
+    assert "required: false" in content
 
 
 def test_openclaw_skill_has_all_install_methods():
@@ -2875,6 +2877,19 @@ def test_openclaw_skill_has_verification_section():
     assert "cosign verify-blob" in content
     assert "Binary behavior audit" in content
     assert "--dry-run" in content
+    # Source code evidence for binary verifiability
+    assert "Source code evidence" in content
+    assert "credential_names" in content
+    assert "CONFIG_LOCATIONS" in content
+
+
+def test_openclaw_skill_has_file_reads_justification():
+    """OpenClaw SKILL.md should justify the broad file_reads list."""
+    from pathlib import Path
+    p = Path(__file__).parent.parent / "integrations" / "openclaw" / "SKILL.md"
+    content = p.read_text()
+    assert "file_reads_justification:" in content
+    assert "silently skipped" in content
 
 
 def test_openclaw_skill_nvd_auth_consistent():
@@ -2899,6 +2914,7 @@ def test_openclaw_skill_nvd_auth_consistent():
 def test_cli_dry_run_shows_data_audit():
     """--dry-run should include Data Audit section showing what gets extracted and sent."""
     from click.testing import CliRunner
+
     from agent_bom.cli import main
     runner = CliRunner()
     result = runner.invoke(main, ["scan", "--dry-run"])
@@ -2952,7 +2968,7 @@ def test_badge_output_clean():
 
 def test_badge_output_with_vulns():
     """Badge output should reflect vulnerability severity."""
-    from agent_bom.models import AIBOMReport, Agent, AgentType, MCPServer, Package, Vulnerability, Severity
+    from agent_bom.models import Agent, AgentType, AIBOMReport, MCPServer, Package, Severity, Vulnerability
     report = AIBOMReport()
     vuln = Vulnerability(id="CVE-2024-0001", severity=Severity.HIGH, summary="test")
     pkg = Package(name="test-pkg", version="1.0.0", ecosystem="npm", vulnerabilities=[vuln])