ZeroClaw Agent Intergrate with Rate limiting issue currently

Setup.md

@@ -0,0 +1,117 @@
+# ZeroClaw Scanner Setup Guide
+
+This guide explains how to install and configure the **ZeroClaw Scanner** and the underlying **ZeroClaw Rust Agent** on a new client device or server.
+
+## Prerequisites
+
+Before starting, ensure the target system has the following installed:
+- **Python 3.10+** (with `pip`)
+- **Rust & Cargo** (Required to install the ZeroClaw binary)
+  ```bash
+  # Install Rust via rustup if not already installed
+  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+  ```
+
+---
+
+## 1. Install the ZeroClaw Rust Agent
+
+The Python scanner relies on the core ZeroClaw Rust binary to perform AI enrichment. 
+
+1. Install the binary using Cargo:
+   ```bash
+   cargo install zeroclaw
+   ```
+2. Verify the installation:
+   ```bash
+   ~/.cargo/bin/zeroclaw --version
+   ```
+
+---
+
+## 2. Install the Python Scanner Package
+
+Clone this repository and install the Python package. We recommend using a virtual environment or installing it system-wide using `pipx`.
+
+```bash
+# Clone the repository (if not already done)
+git clone <repository-url>
+cd zeroclaw-scanner
+
+# Option A: Install via Pipx (Recommended for global CLI usage)
+pipx install .
+
+# Option B: Install into a local virtual environment
+python3 -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+---
+
+## 3. Configure the ZeroClaw Agent
+
+The agent requires a configuration file at `~/.zeroclaw/config.toml` to define its model provider, risk profile, and alias. 
+
+1. Create the `~/.zeroclaw` directory if it doesn't exist:
+   ```bash
+   mkdir -p ~/.zeroclaw
+   ```
+2. Create or edit `~/.zeroclaw/config.toml` with the following configuration. 
+
+> [!IMPORTANT]
+> **Free Tier Consideration:** If you are using OpenRouter's free tier, many free models reject API payloads that include "tools" or function-calling arrays. The model `google/gemma-4-31b-it:free` is specifically configured below because it correctly handles these payloads without returning a 404 error.
+
+```toml
+schema_version = 3
+
+[providers.models.openrouter.scanner]
+# Recommended free model that supports the ZeroClaw tool payload
+model = "google/gemma-4-31b-it:free"
+temperature = 0.2
+api_key_env = "OPENROUTER_API_KEY"
+max_tokens = 1024
+fallback_models = []
+native_tools = false
+
+[agents.scanner]
+model_provider = "openrouter.scanner"
+risk_profile = "default"
+skill_bundles = []
+enabled = true
+
+[risk_profiles.default]
+level = "full"
+workspace_only = false
+block_high_risk_commands = false
+```
+
+---
+
+## 4. Set the OpenRouter API Key
+
+The agent uses OpenRouter to communicate with LLMs. You must provide an OpenRouter API key.
+
+1. Get a free API key from [OpenRouter](https://openrouter.ai/keys).
+2. Set the key in your environment. You can add this to your `~/.bashrc` or `~/.zshrc`:
+   ```bash
+   export OPENROUTER_API_KEY="sk-or-v1-your-key-here"
+   ```
+
+*(Alternatively, you can securely store the key directly inside the ZeroClaw config by running: `~/.cargo/bin/zeroclaw config set providers.models.openrouter.scanner.api_key`)*
+
+---
+
+## 5. Run the Scanner
+
+Once everything is installed and the API key is set, you can run the scanner against any target directory.
+
+```bash
+# Example: Scan a target directory
+python -m zeroclaw.cli scan --target /path/to/target/codebase
+```
+
+The scanner will execute 3 phases:
+1. **Static Analysis**: Scans for secrets, dependencies, and code patterns.
+2. **Enrichment**: Sends the findings to the ZeroClaw agent to generate remediation steps and fixed code.
+3. **Reporting**: Outputs the AI-enriched findings.

docs/architecture/schema.json

@@ -0,0 +1,202 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "LifeAtlasEcosystemSecurityFindingSchema",
+  "description": "Standardized JSON data contract for automated security scanners across the 6-stream cohort.",
+  "type": "object",
+  "required": [
+    "scan_metadata",
+    "target_scope",
+    "summary",
+    "findings"
+  ],
+  "properties": {
+    "scan_metadata": {
+      "type": "object",
+      "required": [
+        "timestamp",
+        "scanner_tool",
+        "execution_environment"
+      ],
+      "properties": {
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "The exact date and time the security scan was initiated (ISO-8601 format)."
+        },
+        "scanner_tool": {
+          "type": "string",
+          "enum": [
+            "pip-audit",
+            "npm-audit",
+            "cargo-audit",
+            "bandit",
+            "gitleaks",
+            "semgrep",
+            "custom-regex",
+            "detect-secrets"
+          ],
+          "description": "The specific static analysis or dependency utility that generated this report."
+        },
+        "execution_environment": {
+          "type": "string",
+          "enum": [
+            "github-actions-ci",
+            "local-dev-env",
+            "pre-commit-hook"
+          ],
+          "description": "The platform context where the scanning binary was executed."
+        }
+      }
+    },
+    "target_scope": {
+      "type": "object",
+      "required": [
+        "stream_id",
+        "repository_name",
+        "commit_sha"
+      ],
+      "properties": {
+        "stream_id": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 6,
+          "description": "The numeric identifier of the cohort stream being audited (1-6)."
+        },
+        "repository_name": {
+          "type": "string",
+          "description": "The exact name of the target repository as configured on GitHub."
+        },
+        "commit_sha": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40}$",
+          "description": "The full 40-character SHA-1 hash of the specific Git commit scanned."
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "total_findings",
+        "critical_count",
+        "high_count",
+        "medium_count",
+        "low_count"
+      ],
+      "properties": {
+        "total_findings": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "critical_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "high_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "medium_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "low_count": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "reasoning_chain",
+          "severity",
+          "stride_classification",
+          "owasp_alignment",
+          "affected_component",
+          "description",
+          "remediation"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The industry standard CVE/GHSA designation, or custom internal tracking vulnerability index."
+          },
+          "reasoning_chain": {
+            "type": "string",
+            "description": "A mandatory step-by-step logical explanation of why this code violates a specific OWASP rule or STRIDE category. Must justify the severity rating. If the chain cannot logically prove the vulnerability, the finding must be dropped."
+          },
+          "severity": {
+            "type": "string",
+            "enum": [
+              "CRITICAL",
+              "HIGH",
+              "MEDIUM",
+              "LOW",
+              "INFO"
+            ],
+            "description": "The calculated severity barrier of the vulnerability based on CVSS or internal risk assessment."
+          },
+          "stride_classification": {
+            "type": "string",
+            "enum": [
+              "Spoofing",
+              "Tampering",
+              "Repudiation",
+              "Information Disclosure",
+              "Denial of Service",
+              "Elevation of Privilege"
+            ],
+            "description": "The core threat vector category mapped according to the Stream 5 STRIDE Model."
+          },
+          "owasp_alignment": {
+            "type": "string",
+            "enum": [
+              "LA-01",
+              "LA-02",
+              "LA-03",
+              "LA-04",
+              "LA-05",
+              "LA-06",
+              "LA-07",
+              "LA-08",
+              "LA-09",
+              "LA-10"
+            ],
+            "description": "The specific custom category from the LifeAtlas Custom OWASP Top 10 Pass/Fail Criteria."
+          },
+          "affected_component": {
+            "type": "string",
+            "description": "The name of the outdated software module, manifest library, or specific relative source code file path."
+          },
+          "current_version": {
+            "type": "string",
+            "description": "The active installed deployment version of the package (omit if scanning static files/directories)."
+          },
+          "description": {
+            "type": "string",
+            "description": "A clear, concise engineering summary of the vulnerability footprint and potential compromise vectors."
+          },
+          "remediation": {
+            "type": "object",
+            "required": [
+              "steps"
+            ],
+            "properties": {
+              "fixed_version": {
+                "type": "string",
+                "description": "The target secure dependency version threshold. Must be omitted for non-dependency architectural or logic findings."
+              },
+              "steps": {
+                "type": "string",
+                "description": "Explicit instructions, terminal commands, or design patterns needed to completely execute the fix."
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

pyproject.toml

@@ -24,7 +24,7 @@ dev = [
 ]
 
 [project.scripts]
-zeroclaw = "zeroclaw.cli:main"
+zeroclaw-scanner = "zeroclaw.cli:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]