agentguards 1.0.0__tar.gz

agentguards-1.0.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.5
+Name: agentguards
+Version: 1.0.0
+Summary: GitHub Action that detects authorization and tenant-isolation regressions in Python/Django pull requests
+Author: AgentGuard Team
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: pydantic-settings>=2.4.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tree-sitter-python>=0.24.0
+Requires-Dist: tree-sitter>=0.24.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.8.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgentGuard
+
+AgentGuard is a GitHub Action that detects authorization and tenant-isolation regressions in Python/Django pull requests, especially AI-generated ones.
+
+## Install
+
+```bash
+pip install agentguard
+```
+
+## Dev setup
+
+```bash
+# Clone the repo
+cd agentguard
+
+# Install with uv (recommended)
+uv sync --dev
+
+# Or with pip
+pip install -e ".[dev]"
+```
+
+## Test commands
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=src/agentguard
+
+# Lint
+ruff check src/ tests/
+
+# Format
+ruff format src/ tests/
+
+# Type check
+mypy --strict src/
+```
+
+## CLI usage
+
+```bash
+agentguard version
+agentguard scan --base main --head feature-branch --format json --mode observe --output report.json
+```
+
+## GitHub Action
+
+See `.github/workflows/ci.yml` for the CI pipeline and `action.yml` for the composite action.

agentguards-1.0.0/README.md

@@ -0,0 +1,52 @@
+# AgentGuard
+
+AgentGuard is a GitHub Action that detects authorization and tenant-isolation regressions in Python/Django pull requests, especially AI-generated ones.
+
+## Install
+
+```bash
+pip install agentguard
+```
+
+## Dev setup
+
+```bash
+# Clone the repo
+cd agentguard
+
+# Install with uv (recommended)
+uv sync --dev
+
+# Or with pip
+pip install -e ".[dev]"
+```
+
+## Test commands
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=src/agentguard
+
+# Lint
+ruff check src/ tests/
+
+# Format
+ruff format src/ tests/
+
+# Type check
+mypy --strict src/
+```
+
+## CLI usage
+
+```bash
+agentguard version
+agentguard scan --base main --head feature-branch --format json --mode observe --output report.json
+```
+
+## GitHub Action
+
+See `.github/workflows/ci.yml` for the CI pipeline and `action.yml` for the composite action.

agentguards-1.0.0/agentguard/__init__.py

@@ -0,0 +1,3 @@
+"""AgentGuard - authorization and tenant-isolation regression detection for Python/Django PRs."""
+
+__version__ = "0.1.0"

agentguards-1.0.0/agentguard/cli.py

@@ -0,0 +1,211 @@
+"""Typer CLI entrypoint for AgentGuard."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from agentguard.config import AgentGuardConfig, Mode
+from agentguard.logging import setup_logging
+
+from agentguard.models.baseline import Baseline, TenantModelMap
+from agentguard.models.findings import Confidence, Finding, RuleId, Severity
+from agentguard.models.fingerprint import AuthFingerprint
+
+app = typer.Typer(
+    name="agentguard",
+    help="AgentGuard: detect authorization and tenant-isolation regressions in PRs.",
+)
+
+
+@app.command()
+def version() -> None:
+    """Print the AgentGuard version."""
+    from agentguard import __version__
+
+    typer.echo(f"agentguard {__version__}")
+
+
+@app.command()
+def scan(
+    base: str = typer.Option("main", "--base", "-b", help="Base git ref"),
+    head: str = typer.Option("HEAD", "--head", "-H", help="Head git ref"),
+    format: str = typer.Option("json", "--format", "-f", help="Output format: json, sarif, markdown"),
+    mode: str = typer.Option("observe", "--mode", "-m", help="Scan mode: observe, warn, enforce"),
+    output: str | None = typer.Option(None, "--output", "-o", help="Output file path"),
+) -> int:
+    """Scan a git diff for authorization and tenant-isolation regressions."""
+    from agentguard.config import AgentGuardConfig, Mode
+    from agentguard.logging import setup_logging
+
+    setup_logging()
+    config = AgentGuardConfig(mode=Mode(mode))
+
+    from agentguard.parsing.git_diff import resolve_base_head, list_changed_files, get_file_at_ref
+    from agentguard.parsing.python_django import DjangoExtractor
+    from agentguard.rules.engine import Engine, RuleContext
+    from agentguard.rules.auth_rules import AuthGuardRemoved, AuthGuardWeakened, NewEndpointUnGuarded
+    from agentguard.rules.tenant_rules import TenantFilterRemoved, NewQueryWithoutTenantFilter, PKLookupOnTenantModel
+    from agentguard.models.baseline import Baseline, TenantModelMap
+    from agentguard.models.findings import Finding
+    from agentguard.models.findings import Confidence
+    from agentguard.models.fingerprint import AuthFingerprint
+    from agentguard.rules.engine import Engine, RuleContext
+    from agentguard.rules.auth_rules import AuthGuardRemoved, AuthGuardWeakened, NewEndpointUnGuarded
+    from agentguard.rules.tenant_rules import TenantFilterRemoved, NewQueryWithoutTenantFilter, PKLookupOnTenantModel
+    from agentguard.reporting.json_report import JSONReport
+    from agentguard.reporting.sarif import SARIFReport
+    from agentguard.reporting.markdown import MarkdownReport
+
+    try:
+        base_sha, head_sha = resolve_base_head(base, head)
+    except ValueError as exc:
+        typer.echo(f"Error resolving refs: {exc}", err=True)
+        return 2
+
+    changed_files = list_changed_files(base_sha, head_sha)
+
+    extractor = DjangoExtractor()
+    base_fps: list[AuthFingerprint] = []
+    head_fps: list[AuthFingerprint] = []
+
+    for cf in changed_files:
+        if cf.status == "deleted":
+            content = get_file_at_ref(base_sha, cf.path)
+            if content:
+                import os
+                import tempfile
+
+                with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+                    f.write(content)
+                    tmp = f.name
+                base_fps.extend(extractor.extract_file(tmp))
+                os.unlink(tmp)
+        elif cf.status == "added":
+            content = get_file_at_ref(head_sha, cf.path)
+            if content:
+                import os
+                import tempfile
+
+                with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+                    f.write(content)
+                    tmp = f.name
+                head_fps.extend(extractor.extract_file(tmp))
+                os.unlink(tmp)
+        else:  # modified, renamed
+            base_content = get_file_at_ref(base_sha, cf.path)
+            head_content = get_file_at_ref(head_sha, cf.path)
+            if base_content:
+                import os
+                import tempfile
+
+                with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+                    f.write(base_content)
+                    tmp = f.name
+                base_fps.extend(extractor.extract_file(tmp))
+                os.unlink(tmp)
+            if head_content:
+                import os
+                import tempfile
+
+                with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+                    f.write(head_content)
+                    tmp = f.name
+                head_fps.extend(extractor.extract_file(tmp))
+                os.unlink(tmp)
+
+    context = RuleContext(
+        baseline=Baseline(),
+        tenant_model_map=TenantModelMap(),
+        base_fingerprints={fp.endpoint_id: fp for fp in base_fps},
+        head_fingerprints={fp.endpoint_id: fp for fp in head_fps},
+    )
+
+    rules = [
+        AuthGuardRemoved(),
+        AuthGuardWeakened(),
+        NewEndpointUnGuarded(),
+        TenantFilterRemoved(),
+        NewQueryWithoutTenantFilter(),
+        PKLookupOnTenantModel(),
+    ]
+
+    engine = Engine(rules)
+    findings = engine.run(base_fps, head_fps, context)
+
+    # Format output
+    report_format = format.lower()
+    if report_format == "sarif":
+        report = SARIFReport(findings).render()
+    elif report_format == "markdown":
+        report = MarkdownReport(findings).render()
+    else:
+        report = JSONReport(findings).render()
+
+    if output:
+        Path(output).write_text(report)
+    else:
+        typer.echo(report)
+
+    # Exit code logic
+    has_findings = len(findings) > 0
+    has_critical_or_high = any(
+        f.severity in (Severity.HIGH, Severity.CRITICAL) for f in findings
+    )
+
+    if config.mode == Mode.ENFORCE and has_findings:
+        return 1
+    if config.mode == Mode.WARN and has_critical_or_high:
+        return 1
+    return 0
+
+
+@app.command()
+def schemas(
+    output_dir: str = typer.Option(
+        "docs/schemas", "--output-dir", "-o", help="Output directory for JSON Schema files"
+    ),
+) -> None:
+    """Export JSON Schema for all AgentGuard data models."""
+    from agentguard.models.baseline import Baseline, TenantModelMap, TenantModelMapEntry
+    from agentguard.models.fingerprint import AuthFingerprint, GuardFact, QueryFact
+    from agentguard.models.findings import Confidence, Finding, RuleId
+
+    # Only export schemas for Pydantic v2 models; skip plain Enums
+    pydantic_models = {
+        "AuthFingerprint": AuthFingerprint,
+        "GuardFact": GuardFact,
+        "QueryFact": QueryFact,
+        "Finding": Finding,
+        "Baseline": Baseline,
+        "TenantModelMap": TenantModelMap,
+        "TenantModelMapEntry": TenantModelMapEntry,
+    }
+
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    for name, model_cls in pydantic_models.items():
+        schema = model_cls.model_json_schema()
+        schema_file = out / f"{name}.json"
+        schema_file.write_text(__import__("json").dumps(schema, indent=2))
+        typer.echo(f"Wrote {schema_file}")
+
+    # Export enum string values
+    enum_values = {
+        "Severity": list(Severity.__members__.values()),
+        "Confidence": list(Confidence.__members__.values()),
+        "RuleId": list(RuleId.__members__.values()),
+    }
+    enum_dir = out / "enums"
+    enum_dir.mkdir(parents=True, exist_ok=True)
+    for name, values in enum_values.items():
+        enum_file = enum_dir / f"{name}.txt"
+        enum_file.write_text("
+".join(v.value for v in values))
+        typer.echo(f"Wrote {enum_file}")
+
+
+if __name__ == "__main__":
+    app()

agentguards-1.0.0/agentguard/config.py

@@ -0,0 +1,38 @@
+"""AgentGuard configuration using pydantic-settings."""
+
+from enum import StrEnum
+
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+
+class Mode(StrEnum):
+    """Scan mode: observe (report only), warn (fail on findings), enforce (block build)."""
+
+    OBSERVE = "observe"
+    WARN = "warn"
+    ENFORCE = "enforce"
+
+
+class AgentGuardConfig(BaseSettings):
+    """AgentGuard runtime configuration."""
+
+    mode: Mode = Field(default=Mode.OBSERVE, description="Scan mode: observe, warn, or enforce")
+    max_file_size_bytes: int = Field(
+        default=1_000_000, description="Maximum file size to parse in bytes"
+    )
+    parse_timeout_seconds: float = Field(
+        default=10.0, description="Per-file parse timeout in seconds"
+    )
+    enable_dependency_guard: bool = Field(
+        default=False, description="Enable dependency guard scanning"
+    )
+    offline_fallback: bool = Field(
+        default=True, description="Fail open to REVIEW when network is unavailable"
+    )
+
+    model_config = {
+        "env_prefix": "AGENTGUARD_",
+        "env_file": ".env",
+        "extra": "ignore",
+    }

agentguards-1.0.0/agentguard/deps/__init__.py

@@ -0,0 +1 @@
+"""AgentGuard dependency guard module."""

agentguards-1.0.0/agentguard/deps/parsers.py

@@ -0,0 +1,127 @@
+"""Dependency file parsers for requirements, pyproject, lockfiles."""
+
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class Dependency:
+    """A single dependency with name and version."""
+
+    name: str
+    version: str | None = None
+    source_file: str = ""
+    line: int = 0
+
+
+def parse_requirements_txt(file_path: str) -> list[Dependency]:
+    """Parse a requirements*.txt file."""
+    deps: list[Dependency] = []
+    path = Path(file_path)
+    if not path.exists():
+        return deps
+    for i, line in enumerate(path.read_text().splitlines(), 1):
+        line = line.strip()
+        if not line or line.startswith("#") or line.startswith("-"):
+            continue
+        # Handle package==version, package>=version, package~=version
+        match = re.match(r"^([a-zA-Z0-9_.\-]+)\s*(?:==|>=|<=|~=|>|<|!)\s*(.+)", line)
+        if match:
+            deps.append(
+                Dependency(
+                    name=match.group(1), version=match.group(2), source_file=file_path, line=i
+                )
+            )
+        else:
+            # Bare package name
+            match = re.match(r"^([a-zA-Z0-9_.\-]+)", line)
+            if match:
+                deps.append(Dependency(name=match.group(1), source_file=file_path, line=i))
+    return deps
+
+
+def parse_pyproject_toml(file_path: str) -> list[Dependency]:
+    """Parse a pyproject.toml file for dependencies."""
+    deps: list[Dependency] = []
+    path = Path(file_path)
+    if not path.exists():
+        return deps
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return deps
+
+    # Check [project] dependencies
+    project = data.get("project", {})
+    for dep_str in project.get("dependencies", []):
+        match = re.match(r"^([a-zA-Z0-9_.\-]+)\s*(?:==|>=|<=|~=|>|<|!)\s*(.+)", dep_str)
+        if match:
+            deps.append(
+                Dependency(name=match.group(1), version=match.group(2), source_file=file_path)
+            )
+        else:
+            match = re.match(r"^([a-zA-Z0-9_.\-]+)", dep_str)
+            if match:
+                deps.append(Dependency(name=match.group(1), source_file=file_path))
+
+    # Check [tool.poetry] dependencies
+    poetry = data.get("tool", {}).get("poetry", {})
+    for name, ver in poetry.get("dependencies", {}).items():
+        if name == "python":
+            continue
+        version = ver if isinstance(ver, str) else None
+        deps.append(Dependency(name=name, version=version, source_file=file_path))
+
+    return deps
+
+
+def parse_lockfile(file_path: str) -> list[Dependency]:
+    """Parse a lockfile (poetry.lock, package-lock.json, etc.)."""
+    deps: list[Dependency] = []
+    path = Path(file_path)
+    if not path.exists():
+        return deps
+
+    name = path.name
+    if name == "poetry.lock":
+        return _parse_poetry_lock(path)
+    if name in ("package-lock.json", "package.json"):
+        return _parse_npm_lock(path)
+    if name in ("pnpm-lock.yaml", "yarn.lock"):
+        # Basic parsing - just return empty for now
+        return deps
+    return deps
+
+
+def _parse_poetry_lock(path: Path) -> list[Dependency]:
+    deps: list[Dependency] = []
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return deps
+    for pkg in data.get("package", []):
+        deps.append(
+            Dependency(name=pkg.get("name", ""), version=pkg.get("version"), source_file=str(path))
+        )
+    return deps
+
+
+def _parse_npm_lock(path: Path) -> list[Dependency]:
+    deps: list[Dependency] = []
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return deps
+    packages = data.get("packages", {})
+    for pkg_path, pkg_info in packages.items():
+        if not pkg_path:
+            continue
+        pkg_name = pkg_path.split("/")[-1] if "/" in pkg_path else pkg_path
+        version = pkg_info.get("version")
+        deps.append(Dependency(name=pkg_name, version=version, source_file=str(path)))
+    return deps

agentguards-1.0.0/agentguard/deps/registry.py

@@ -0,0 +1,131 @@
+"""Registry clients for PyPI and npm with caching and timeouts."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class RegistryInfo:
+    """Information about a package from a registry."""
+
+    name: str
+    exists: bool
+    first_publish: str | None = None
+    release_count: int = 0
+    download_count: int | None = None
+    maintainer_count: int = 0
+    recent_maintainer_changes: bool = False
+    has_install_scripts: bool = False
+
+
+@dataclass
+class PackageVerdict:
+    """Verdict for a dependency package."""
+
+    name: str
+    verdict: str  # ALLOW, REVIEW, BLOCK_HALLUCINATION, AUTO_REMEDIATE
+    reasons: list[str]
+    suggested_alternative: str | None = None
+    registry_info: RegistryInfo | None = None
+
+
+class PackageRegistry:
+    """Base class for package registry clients with caching."""
+
+    def __init__(self, cache_dir: str | None = None, timeout: float = 10.0) -> None:
+        self._timeout = timeout
+        self._cache: dict[str, tuple[float, RegistryInfo]] = {}
+        self._cache_dir = Path(cache_dir) if cache_dir else None
+        if self._cache_dir:
+            self._cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def _get_from_cache(self, name: str) -> RegistryInfo | None:
+        if name not in self._cache:
+            return None
+        timestamp, info = self._cache[name]
+        if time.time() - timestamp > 3600:  # 1 hour cache
+            del self._cache[name]
+            return None
+        return info
+
+    def _put_in_cache(self, name: str, info: RegistryInfo) -> None:
+        self._cache[name] = (time.time(), info)
+
+    def lookup(self, name: str) -> RegistryInfo:
+        """Look up a package in the registry."""
+        cached = self._get_from_cache(name)
+        if cached:
+            return cached
+        info = self._fetch(name)
+        self._put_in_cache(name, info)
+        return info
+
+    def _fetch(self, name: str) -> RegistryInfo:
+        raise NotImplementedError
+
+
+class PyPIRegistry(PackageRegistry):
+    """PyPI JSON API client."""
+
+    def _fetch(self, name: str) -> RegistryInfo:
+        url = f"https://pypi.org/pypi/{name}/json"
+        try:
+            req = urllib.request.Request(url, headers={"User-Agent": "AgentGuard/0.1"})
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:  # noqa: S310
+                data = json.loads(resp.read())
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                return RegistryInfo(name=name, exists=False)
+            return RegistryInfo(name=name, exists=False)
+        except Exception:  # noqa: S110
+            return RegistryInfo(name=name, exists=False)
+
+        info = data.get("info", {})
+        releases = data.get("releases", {})
+        return RegistryInfo(
+            name=name,
+            exists=True,
+            first_publish=info.get("first_upload"),
+            release_count=len(releases),
+            maintainer_count=len(info.get("maintainers", [])),
+        )
+
+
+class NPMRegistry(PackageRegistry):
+    """npm registry client."""
+
+    def _fetch(self, name: str) -> RegistryInfo:
+        url = f"https://registry.npmjs.org/{name}"
+        try:
+            req = urllib.request.Request(url, headers={"User-Agent": "AgentGuard/0.1"})
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:  # noqa: S310
+                data = json.loads(resp.read())
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                return RegistryInfo(name=name, exists=False)
+            return RegistryInfo(name=name, exists=False)
+        except Exception:  # noqa: S110
+            return RegistryInfo(name=name, exists=False)
+
+        time_data = data.get("time", {})
+        versions = data.get("versions", {})
+        first_publish = time_data.get("created")
+        maintainers = data.get("maintainers", [])
+
+        return RegistryInfo(
+            name=name,
+            exists=True,
+            first_publish=first_publish,
+            release_count=len(versions),
+            maintainer_count=len(maintainers),
+            has_install_scripts=any(
+                "scripts" in v and ("preinstall" in v["scripts"] or "postinstall" in v["scripts"])
+                for v in versions.values()
+            ),
+        )