agentguard-tool 1.0.5__tar.gz

agentguard_tool-1.0.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hermes Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentguard_tool-1.0.5/PKG-INFO

@@ -0,0 +1,328 @@
+Metadata-Version: 2.4
+Name: agentguard-tool
+Version: 1.0.5
+Summary: AI-native quality gate for agent-generated code — scan, audit, auto-fix, trend
+Author: Hermes Labs
+License: MIT License
+        
+        Copyright (c) 2026 Hermes Labs
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/weijinsheng123456/agentguard
+Project-URL: Issues, https://github.com/weijinsheng123456/agentguard/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: ruff>=0.4.0
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://img.shields.io/badge/AgentGuard-1.0.0-8A2BE2?style=for-the-badge&logo=python&logoColor=white" width="300" alt="AgentGuard">
+</p>
+
+<p align="center">
+  <em>AI-native quality gate for agent-generated code.</em>
+  <br>
+  Scan · Audit · Auto-fix · Track trends
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#commands">Commands</a> •
+  <a href="#demo">Demo</a> •
+  <a href="#rules">Rules</a> •
+  <a href="#write-custom-rules">Custom Rules</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/weijinsheng123456/agentguard/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/weijinsheng123456/agentguard/ci.yml?branch=main&label=CI&logo=github&color=success" alt="CI">
+  </a>
+  <a href="https://pypi.org/project/agentguard/">
+    <img src="https://img.shields.io/pypi/v/agentguard?label=PyPI&logo=pypi&color=blue" alt="PyPI">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
+  </a>
+  <a href="https://github.com/weijinsheng123456/agentguard/stargazers">
+    <img src="https://img.shields.io/github/stars/weijinsheng123456/agentguard?style=social" alt="Stars">
+  </a>
+  <a href="https://www.python.org/">
+    <img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue?logo=python" alt="Python">
+  </a>
+  <a href="https://github.com/weijinsheng123456/agentguard/blob/main/CHANGELOG.md">
+    <img src="https://img.shields.io/badge/version-1.0.0-8A2BE2" alt="Version">
+  </a>
+</p>
+
+---
+
+# 🚀 Install in 3 seconds
+
+```bash
+pip install agentguard-tool
+cd your-project
+gate run
+```
+
+Done. AgentGuard scans your code, detects AI-specific issues (hardcoded secrets, unsafe APIs, hallucinations), auto-fixes what it can, and tracks quality trends over time.
+
+---
+
+## Why AgentGuard?
+
+Traditional linters like SonarQube and CodeQL were built for **human-written code**. AI agents write code differently — they hallucinate module names, leave placeholder comments, generate giant functions, and introduce patterns that human linters miss.
+
+**AgentGuard is built for the age of AI-generated code.**
+
+It understands the patterns, pitfalls, and security risks specific to code written by LLMs. It runs as a CI-ready CLI, a pre-commit hook, or a daily cron.
+
+---
+
+## Features
+
+### 🔍 AI-Specific Detection (3 rules)
+| Rule | Severity | What It Finds |
+|------|----------|---------------|
+| `unsafe_api` | 🚫 BLOCKER | `eval()`, `exec()`, `os.system()`, `subprocess(shell=True)`, `pickle.loads()` |
+| `secret_leak` | 🚫 BLOCKER | Hardcoded API keys, tokens, passwords in source code |
+| `ai_hallucination` | ℹ️ INFO | AI placeholder comments, suspicious module names, giant auto-generated functions |
+
+### 📊 Agent Behavior Audit
+Reads agent trace data and produces a daily report:
+- Tool call frequency & ranking
+- Error rate & anomaly detection
+- Token consumption & cost estimates
+- Model usage distribution
+
+### 📈 Trend Dashboard
+Text-based trend chart with zero external dependencies:
+```
+━━━ 📈 Quality Trend (Last 14 days) ━━━
+  05/08 ████████████████   0 issues  ✅
+  05/09 ████████████░░░░   3 issues  ⚠️
+  05/10 ████████████████   0 issues  ✅
+```
+Data persists in SQLite. View anytime with `gate trend`.
+
+### 🔧 Auto-Fix Pipeline
+Automatically fixes what it can, backed up and git-committed:
+- Unused imports (`F401`) and variables (`F841`)
+- Bare `except:` → `except Exception:`
+- Hardcoded paths → `$HOME` references
+- Ruff-safe auto-fixes
+
+### 🧩 Plugin Rule Architecture
+Rules are Python classes. Adding a new rule = one file, one class, one decorator.
+```python
+@register_rule
+class MyRule(Rule):
+    name = "my_rule"
+    severity = Severity.BLOCKER
+
+    def diagnose(self, filepath: str) -> list[Issue]:
+        # Your detection logic here
+        ...
+```
+
+---
+
+## Quick Start
+
+```bash
+# 🎯 Scan your project
+pip install agentguard-tool
+cd your-project
+gate run
+
+# 🔍 Quick check (staged files only)
+gate run --quick
+
+# 📊 Agent behavior audit
+gate audit
+
+# 📈 View quality trends
+gate trend
+
+# 🔧 Install pre-commit hooks
+gate install
+```
+
+### Run from source
+```bash
+git clone https://github.com/weijinsheng123456/agentguard.git
+cd agentguard
+python gate.py run
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `gate run` | Full scan + auto-fix + commit + audit |
+| `gate run --quick` | Pre-commit check (staged files only) |
+| `gate run --fixme` | Auto-fix staged files |
+| `gate audit` | Agent behavior audit only |
+| `gate trend [N]` | Show last N days of quality trends |
+| `gate install` | Install pre-commit hooks & cron |
+| `gate version` | Show version |
+
+---
+
+## Rules
+
+### Built-in Rules (8 total)
+
+**Code Quality (ported from ruff):**
+| Rule | Code | Severity | Auto-fix |
+|------|------|----------|:--------:|
+| `syntax_check` | `SYNTAX` | BLOCKER | ❌ |
+| `ruff_blocker` | `F821`, `E999` | BLOCKER | ❌ |
+| `ruff_fixable` | `F401`, `F841`, `E711`, `E712` | FIXABLE | ✅ |
+| `bare_except` | `E722` | FIXABLE | ✅ |
+| `hardcoded_paths` | `HARDCODE` | FIXABLE | ✅ |
+
+**AI-Specific:**
+| Rule | Code | Severity | Auto-fix |
+|------|------|----------|:--------:|
+| `unsafe_api` | `UNSAFE_*` | BLOCKER | ❌ |
+| `secret_leak` | `LEAK_SECRET` | BLOCKER | ❌ |
+| `ai_hallucination` | `AI_*` | INFO | ❌ |
+
+---
+
+## Write Custom Rules
+
+Create a new `.py` file in `qg/rules/`:
+
+```python
+from qg.models import Issue, Severity
+from qg.rules.base import Rule, register_rule
+
+@register_rule
+class MyCustomRule(Rule):
+    name = "my_custom_rule"
+    severity = Severity.FIXABLE
+    description = "Detects something specific"
+
+    def should_check(self, filepath: str) -> bool:
+        return filepath.endswith(".py")
+
+    def diagnose(self, filepath: str) -> list[Issue]:
+        issues = []
+        # Your detection logic...
+        return issues
+
+    def fix(self, filepath: str, issue: Issue) -> bool:
+        # Your fix logic...
+        return True
+```
+
+Rules support two modes:
+- **`Rule`** — per-file scanning (for AST analysis, regex)
+- **`BatchRule`** — directory-level scanning (for ruff, 10-50x faster)
+
+---
+
+## Configuration
+
+```yaml
+scan_dirs:
+  - "~/my-project/src"
+  - "~/my-project/scripts"
+
+ignore_patterns:
+  - "*__pycache__*"
+  - "*/tests/*"
+
+severity:
+  blocker_codes: ["F821", "E999", "SYNTAX"]
+  auto_fix_codes: ["F401", "F841", "E711", "E712", "E722", "HARDCODE"]
+
+report:
+  to_wechat: true
+```
+
+---
+
+## Architecture
+
+```
+gate.py (CLI entry)
+└── qg/
+    ├── scanner.py      # File discovery
+    ├── engine.py       # Diagnostic engine (rule dispatching)
+    ├── fixer.py        # Auto-fix engine
+    ├── verifier.py     # Post-fix verification
+    ├── committer.py    # Git commit automation
+    ├── reporter.py     # Report generation (console + log)
+    ├── auditor.py      # Agent behavior audit
+    ├── dashboard.py    # Trend tracking (SQLite)
+    ├── models.py       # Data models
+    ├── config.py       # Configuration loader
+    └── rules/          # Plugin rules (hot-pluggable)
+        ├── base.py     # Rule + BatchRule base classes
+        ├── syntax_check.py
+        ├── ruff_blocker.py     (BatchRule)
+        ├── ruff_fixable.py     (BatchRule)
+        ├── bare_except.py
+        ├── hardcoded_paths.py
+        ├── unsafe_api.py
+        ├── secret_leak.py
+        └── ai_hallucination.py
+```
+
+---
+
+## Roadmap
+
+- [x] Phase 1: Python rewrite + plugin architecture
+- [x] Phase 2: AI-specific rules + agent audit + trend dashboard
+- [x] Phase 3: Open-source release + CI integration
+- [ ] Phase 4: Security rules (OWASP Top 10 for AI code)
+- [ ] Phase 5: GitHub Actions native action
+- [ ] Phase 6: VS Code extension
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE)
+
+---
+
+<p align="center">
+  Built for the age of AI-generated code.
+  <br>
+  <sub>Because code quality doesn't matter less when AI writes it — it matters more.</sub>
+</p>

agentguard_tool-1.0.5/README.md

@@ -0,0 +1,283 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/AgentGuard-1.0.0-8A2BE2?style=for-the-badge&logo=python&logoColor=white" width="300" alt="AgentGuard">
+</p>
+
+<p align="center">
+  <em>AI-native quality gate for agent-generated code.</em>
+  <br>
+  Scan · Audit · Auto-fix · Track trends
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#commands">Commands</a> •
+  <a href="#demo">Demo</a> •
+  <a href="#rules">Rules</a> •
+  <a href="#write-custom-rules">Custom Rules</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/weijinsheng123456/agentguard/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/weijinsheng123456/agentguard/ci.yml?branch=main&label=CI&logo=github&color=success" alt="CI">
+  </a>
+  <a href="https://pypi.org/project/agentguard/">
+    <img src="https://img.shields.io/pypi/v/agentguard?label=PyPI&logo=pypi&color=blue" alt="PyPI">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
+  </a>
+  <a href="https://github.com/weijinsheng123456/agentguard/stargazers">
+    <img src="https://img.shields.io/github/stars/weijinsheng123456/agentguard?style=social" alt="Stars">
+  </a>
+  <a href="https://www.python.org/">
+    <img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue?logo=python" alt="Python">
+  </a>
+  <a href="https://github.com/weijinsheng123456/agentguard/blob/main/CHANGELOG.md">
+    <img src="https://img.shields.io/badge/version-1.0.0-8A2BE2" alt="Version">
+  </a>
+</p>
+
+---
+
+# 🚀 Install in 3 seconds
+
+```bash
+pip install agentguard-tool
+cd your-project
+gate run
+```
+
+Done. AgentGuard scans your code, detects AI-specific issues (hardcoded secrets, unsafe APIs, hallucinations), auto-fixes what it can, and tracks quality trends over time.
+
+---
+
+## Why AgentGuard?
+
+Traditional linters like SonarQube and CodeQL were built for **human-written code**. AI agents write code differently — they hallucinate module names, leave placeholder comments, generate giant functions, and introduce patterns that human linters miss.
+
+**AgentGuard is built for the age of AI-generated code.**
+
+It understands the patterns, pitfalls, and security risks specific to code written by LLMs. It runs as a CI-ready CLI, a pre-commit hook, or a daily cron.
+
+---
+
+## Features
+
+### 🔍 AI-Specific Detection (3 rules)
+| Rule | Severity | What It Finds |
+|------|----------|---------------|
+| `unsafe_api` | 🚫 BLOCKER | `eval()`, `exec()`, `os.system()`, `subprocess(shell=True)`, `pickle.loads()` |
+| `secret_leak` | 🚫 BLOCKER | Hardcoded API keys, tokens, passwords in source code |
+| `ai_hallucination` | ℹ️ INFO | AI placeholder comments, suspicious module names, giant auto-generated functions |
+
+### 📊 Agent Behavior Audit
+Reads agent trace data and produces a daily report:
+- Tool call frequency & ranking
+- Error rate & anomaly detection
+- Token consumption & cost estimates
+- Model usage distribution
+
+### 📈 Trend Dashboard
+Text-based trend chart with zero external dependencies:
+```
+━━━ 📈 Quality Trend (Last 14 days) ━━━
+  05/08 ████████████████   0 issues  ✅
+  05/09 ████████████░░░░   3 issues  ⚠️
+  05/10 ████████████████   0 issues  ✅
+```
+Data persists in SQLite. View anytime with `gate trend`.
+
+### 🔧 Auto-Fix Pipeline
+Automatically fixes what it can, backed up and git-committed:
+- Unused imports (`F401`) and variables (`F841`)
+- Bare `except:` → `except Exception:`
+- Hardcoded paths → `$HOME` references
+- Ruff-safe auto-fixes
+
+### 🧩 Plugin Rule Architecture
+Rules are Python classes. Adding a new rule = one file, one class, one decorator.
+```python
+@register_rule
+class MyRule(Rule):
+    name = "my_rule"
+    severity = Severity.BLOCKER
+
+    def diagnose(self, filepath: str) -> list[Issue]:
+        # Your detection logic here
+        ...
+```
+
+---
+
+## Quick Start
+
+```bash
+# 🎯 Scan your project
+pip install agentguard-tool
+cd your-project
+gate run
+
+# 🔍 Quick check (staged files only)
+gate run --quick
+
+# 📊 Agent behavior audit
+gate audit
+
+# 📈 View quality trends
+gate trend
+
+# 🔧 Install pre-commit hooks
+gate install
+```
+
+### Run from source
+```bash
+git clone https://github.com/weijinsheng123456/agentguard.git
+cd agentguard
+python gate.py run
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `gate run` | Full scan + auto-fix + commit + audit |
+| `gate run --quick` | Pre-commit check (staged files only) |
+| `gate run --fixme` | Auto-fix staged files |
+| `gate audit` | Agent behavior audit only |
+| `gate trend [N]` | Show last N days of quality trends |
+| `gate install` | Install pre-commit hooks & cron |
+| `gate version` | Show version |
+
+---
+
+## Rules
+
+### Built-in Rules (8 total)
+
+**Code Quality (ported from ruff):**
+| Rule | Code | Severity | Auto-fix |
+|------|------|----------|:--------:|
+| `syntax_check` | `SYNTAX` | BLOCKER | ❌ |
+| `ruff_blocker` | `F821`, `E999` | BLOCKER | ❌ |
+| `ruff_fixable` | `F401`, `F841`, `E711`, `E712` | FIXABLE | ✅ |
+| `bare_except` | `E722` | FIXABLE | ✅ |
+| `hardcoded_paths` | `HARDCODE` | FIXABLE | ✅ |
+
+**AI-Specific:**
+| Rule | Code | Severity | Auto-fix |
+|------|------|----------|:--------:|
+| `unsafe_api` | `UNSAFE_*` | BLOCKER | ❌ |
+| `secret_leak` | `LEAK_SECRET` | BLOCKER | ❌ |
+| `ai_hallucination` | `AI_*` | INFO | ❌ |
+
+---
+
+## Write Custom Rules
+
+Create a new `.py` file in `qg/rules/`:
+
+```python
+from qg.models import Issue, Severity
+from qg.rules.base import Rule, register_rule
+
+@register_rule
+class MyCustomRule(Rule):
+    name = "my_custom_rule"
+    severity = Severity.FIXABLE
+    description = "Detects something specific"
+
+    def should_check(self, filepath: str) -> bool:
+        return filepath.endswith(".py")
+
+    def diagnose(self, filepath: str) -> list[Issue]:
+        issues = []
+        # Your detection logic...
+        return issues
+
+    def fix(self, filepath: str, issue: Issue) -> bool:
+        # Your fix logic...
+        return True
+```
+
+Rules support two modes:
+- **`Rule`** — per-file scanning (for AST analysis, regex)
+- **`BatchRule`** — directory-level scanning (for ruff, 10-50x faster)
+
+---
+
+## Configuration
+
+```yaml
+scan_dirs:
+  - "~/my-project/src"
+  - "~/my-project/scripts"
+
+ignore_patterns:
+  - "*__pycache__*"
+  - "*/tests/*"
+
+severity:
+  blocker_codes: ["F821", "E999", "SYNTAX"]
+  auto_fix_codes: ["F401", "F841", "E711", "E712", "E722", "HARDCODE"]
+
+report:
+  to_wechat: true
+```
+
+---
+
+## Architecture
+
+```
+gate.py (CLI entry)
+└── qg/
+    ├── scanner.py      # File discovery
+    ├── engine.py       # Diagnostic engine (rule dispatching)
+    ├── fixer.py        # Auto-fix engine
+    ├── verifier.py     # Post-fix verification
+    ├── committer.py    # Git commit automation
+    ├── reporter.py     # Report generation (console + log)
+    ├── auditor.py      # Agent behavior audit
+    ├── dashboard.py    # Trend tracking (SQLite)
+    ├── models.py       # Data models
+    ├── config.py       # Configuration loader
+    └── rules/          # Plugin rules (hot-pluggable)
+        ├── base.py     # Rule + BatchRule base classes
+        ├── syntax_check.py
+        ├── ruff_blocker.py     (BatchRule)
+        ├── ruff_fixable.py     (BatchRule)
+        ├── bare_except.py
+        ├── hardcoded_paths.py
+        ├── unsafe_api.py
+        ├── secret_leak.py
+        └── ai_hallucination.py
+```
+
+---
+
+## Roadmap
+
+- [x] Phase 1: Python rewrite + plugin architecture
+- [x] Phase 2: AI-specific rules + agent audit + trend dashboard
+- [x] Phase 3: Open-source release + CI integration
+- [ ] Phase 4: Security rules (OWASP Top 10 for AI code)
+- [ ] Phase 5: GitHub Actions native action
+- [ ] Phase 6: VS Code extension
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE)
+
+---
+
+<p align="center">
+  Built for the age of AI-generated code.
+  <br>
+  <sub>Because code quality doesn't matter less when AI writes it — it matters more.</sub>
+</p>