agentguard-linter 0.1.0__tar.gz

agentguard_linter-0.1.0/.dockerignore

@@ -0,0 +1,15 @@
+.git
+.github
+.venv
+.venvs
+__pycache__
+*.py[cod]
+.mypy_cache
+.pytest_cache
+.ruff_cache
+build
+dist
+web/node_modules
+web/.next
+web/tsconfig.tsbuildinfo
+*.log

agentguard_linter-0.1.0/.env.example

@@ -0,0 +1,6 @@
+# Local server settings. Keep real credentials in your shell or secret manager.
+AGENTGUARD_DATABASE_URL=postgresql+psycopg://agentguard:agentguard@localhost:5432/agentguard
+AGENTGUARD_CORS_ORIGINS=http://localhost:3000
+# AGENTGUARD_AUTH_REQUIRED=true
+# AGENTGUARD_API_TOKENS=replace-me=local;read|write;acme/demo
+# AGENTGUARD_GITHUB_WEBHOOK_SECRET=replace-me

agentguard_linter-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

agentguard_linter-0.1.0/.github/actions/agentguard/action.yml

@@ -0,0 +1,53 @@
+name: AgentGuard scan
+description: Run AgentGuard and produce a SARIF report.
+inputs:
+  path:
+    description: File or directory to scan.
+    required: false
+    default: "."
+  output:
+    description: SARIF output path.
+    required: false
+    default: "agentguard.sarif"
+  select:
+    description: Comma-separated rule selection patterns.
+    required: false
+    default: ""
+  ignore:
+    description: Comma-separated rule ignore patterns.
+    required: false
+    default: ""
+  fail-on:
+    description: Finding threshold that fails the step.
+    required: false
+    default: "error"
+  python-version:
+    description: Python version used by uv.
+    required: false
+    default: "3.13"
+runs:
+  using: composite
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python-version }}
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        version: "0.13.0"
+        enable-cache: true
+    - name: Run AgentGuard
+      shell: bash
+      env:
+        AG_PATH: ${{ inputs.path }}
+        AG_OUTPUT: ${{ inputs.output }}
+        AG_SELECT: ${{ inputs.select }}
+        AG_IGNORE: ${{ inputs.ignore }}
+        AG_FAIL_ON: ${{ inputs.fail-on }}
+      run: |
+        set -euo pipefail
+        args=("$AG_PATH" --format sarif --output "$AG_OUTPUT" --fail-on "$AG_FAIL_ON")
+        if [[ -n "$AG_SELECT" ]]; then args+=(--select "$AG_SELECT"); fi
+        if [[ -n "$AG_IGNORE" ]]; then args+=(--ignore "$AG_IGNORE"); fi
+        uvx --python "${{ inputs.python-version }}" --from agentguard agentguard scan "${args[@]}"

agentguard_linter-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: agentguard
+          POSTGRES_PASSWORD: agentguard
+          POSTGRES_DB: agentguard_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U agentguard -d agentguard_test"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      UV_LINK_MODE: copy
+      UV_PYTHON: ${{ matrix.python-version }}
+      AGENTGUARD_TEST_DATABASE_URL: postgresql://agentguard:agentguard@localhost:5432/agentguard_test
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.13.0"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: make install
+
+      - name: Run checks
+        run: make check
+
+  web:
+    name: Dashboard TypeScript
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install dashboard dependencies
+        run: npm ci
+
+      - name: Check dashboard types
+        run: npm test
+
+      - name: Build dashboard
+        run: npm run build

agentguard_linter-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python caches and virtual environments
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+.venvs/
+web/node_modules/
+web/.next/
+
+# Build and coverage outputs
+*.egg-info/
+.coverage
+.coverage.*
+build/
+coverage.xml
+dist/
+htmlcov/
+
+# Local configuration and secrets
+.env
+.env.*
+!.env.example
+
+# Editors and operating systems
+.DS_Store
+.idea/
+.vscode/
+*.swp

agentguard_linter-0.1.0/.nvmrc

@@ -0,0 +1 @@
+20.17.0

agentguard_linter-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,7 @@
+- id: agentguard
+  name: AgentGuard
+  description: Scan staged Python files for agent reliability and security findings.
+  entry: agentguard scan --fail-on error
+  language: python
+  types: [python]
+  pass_filenames: true

agentguard_linter-0.1.0/AGENTS.md

@@ -0,0 +1,128 @@
+# AGENTS.md
+
+Instructions for AI coding agents working on **AgentGuard**.
+Read this file and `SPEC.md` at the start of every session. `SPEC.md` is the source of truth for architecture, rules, and phases. This file is the source of truth for how you work.
+
+## Project
+
+AgentGuard is a static analysis CLI and plugin platform for AI agentic codebases (LangGraph, CrewAI, AutoGen, plain Python agents). It detects reliability, cost, and security bugs before the agent runs.
+
+- Language: Python 3.10+
+- Owner: Samarth (solo developer, student). Treat the owner as technically capable; be direct and concise.
+- **The repo starts empty.** No code exists yet. Build from Phase 0 of `SPEC.md`.
+- Current phase: **check `STATUS.md`**. If it does not exist, create it and start at Phase 0, Step 0.1.
+
+## Environment (WSL)
+
+This project runs in WSL Ubuntu, possibly under `/mnt/d/...` (a Windows drive). Quirks to handle:
+
+- Set `UV_LINK_MODE=copy` (hardlinks fail across filesystems). Put it in the Makefile and `README` setup notes.
+- Keep the virtualenv off the Windows drive for speed: use `UV_PROJECT_ENVIRONMENT="$HOME/.venvs/agentguard"`. Document this in the README and export it in the Makefile.
+- Use LF line endings. Add a `.gitattributes` with `* text=auto eol=lf`.
+- Do not use Windows paths in code or docs. Use `pathlib` and POSIX paths.
+- If a tool is missing (`make`, `uv`, `git`), tell the owner the install command instead of working around it.
+
+## Workflow (mandatory)
+
+1. **Plan first, then wait.** For any task beyond a trivial fix, write a plan and stop. The plan lists: files to create or change, approach, tests to add, risks. Do **not** edit files until the owner replies with approval.
+2. **One unit per task.** A unit is one rule, one adapter, one CLI command, or one refactor step. Do not bundle units.
+3. **Build, verify, stop.** After implementing, run `make check` (below). Fix failures. Then stop and give a summary: what changed, what was tested, what remains, anything you are unsure about.
+4. **Update `STATUS.md`** at the end of every unit: phase, what is done, what is next, known issues.
+5. **Never expand scope.** Touch only files relevant to the task. If you notice unrelated problems, list them in the summary; do not fix them.
+
+## Commands
+
+Use `uv` for environments and dependencies.
+
+```
+uv sync --all-extras          # install everything
+make check                    # lint + typecheck + tests (run before declaring done)
+make test                     # pytest only
+make lint                     # ruff check + ruff format --check
+make fmt                      # ruff format + ruff check --fix
+make types                    # mypy --strict
+```
+
+`make check` must pass with zero errors and zero warnings before any unit is considered done. If a command above does not exist yet, creating it is the first task of Phase 2.
+
+## Tooling (decided)
+
+| Purpose | Tool |
+|---|---|
+| Env / deps | `uv` |
+| Build backend | `hatchling` |
+| Tests | `pytest`, `hypothesis`, snapshot tests for reporters |
+| Lint + format | `ruff` |
+| Types | `mypy --strict` |
+| CLI | `typer` + `rich` |
+| Plugins | `pluggy` + entry points (group `agentguard`) |
+| Config models | `pydantic` v2 |
+| Autofix | `libcst` |
+
+Do not add dependencies without asking. If a new dependency is justified, put it in the plan with the reason.
+
+## Code standards
+
+- Fully typed. No `Any` unless justified in a comment.
+- Small functions, clear names, docstrings on public APIs.
+- Findings are deterministic: same input gives same output, sorted, stable fingerprints.
+- No network calls in core. LLM-related features live in optional plugins, off by default.
+- No print statements in library code; use `rich` in CLI layer only.
+- No broad `except Exception: pass`. Handle or re-raise with context.
+- Prefer the standard library for simple tasks.
+
+## Architecture rules
+
+- Rules operate on the **Agent IR**, never on raw framework syntax. Framework-specific logic belongs in adapters.
+- Rules are plugins implementing the `Rule` base class. Core ships built-in rules through the same mechanism third parties use.
+- Adapters translate framework code into IR. They never emit findings.
+- Reporters consume findings only. They never re-analyze code.
+- Do not let the engine import from adapters or rules directly; go through the plugin manager.
+
+## Testing rules
+
+- Every rule needs fixtures under `tests/fixtures/<rule_id>/`: `bad_*.py` (must trigger), `good_*.py` (must not), and at least one edge case. Mark expected findings with `# expect: AGxxx` on the exact line.
+- Every new reporter needs a snapshot test.
+- Every IR builder change needs a unit test.
+- **Never modify an existing test to make it pass.** If a test fails, fix the code. If you believe a test is wrong, say so in your summary and wait for approval.
+- Never delete or skip tests to get green. Never use `# type: ignore` or `# noqa` without a one-line reason.
+
+## Rule documentation
+
+Each rule needs `docs/rules/<ID>.md` containing: what it detects, why it matters, bad example, good example, how to fix, how to suppress. `agentguard explain <ID>` reads this file.
+
+## Git
+
+- Work on a feature branch, never directly on `main`.
+- Commit after each green unit with a conventional message (`feat(rules): add AG004 unbounded agent loop`).
+- Do not commit generated files, caches, or secrets.
+- Never force-push, rewrite history, or run destructive git commands without explicit approval.
+
+## Safety
+
+- Do not run `rm -rf`, delete directories, or modify files outside this repository without approval.
+- Never print or commit secrets. Read credentials from environment variables only.
+- Do not install global packages or modify system configuration.
+- When fixture code needs to look dangerous (shell calls, eval), keep it inert: it is parsed, never executed.
+
+## Verifying framework APIs
+
+LangGraph, CrewAI, and AutoGen change fast. Do not rely on memory for their APIs. Check the installed version's source or current docs before writing an adapter, and pin the tested version in the plan. If you cannot verify something, say so rather than guessing.
+
+## Summary format (end of every unit)
+
+```
+Done: <what was implemented>
+Tested: <commands run and results>
+Changed: <files>
+Not done / next: <remaining work>
+Concerns: <uncertainties, risks, things to review closely>
+```
+
+## What not to do
+
+- Do not start a new phase without approval.
+- Do not refactor code that is unrelated to the current task.
+- Do not add features not in `SPEC.md`; suggest them in the summary instead.
+- Do not report "done" with failing checks.
+- Do not guess when requirements are ambiguous. Ask one specific question.

agentguard_linter-0.1.0/Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    UV_LINK_MODE=copy \
+    UV_PROJECT_ENVIRONMENT=/opt/agentguard/.venv
+
+WORKDIR /opt/agentguard
+
+COPY pyproject.toml uv.lock README.md LICENSE ./
+COPY packages ./packages
+COPY docs ./docs
+COPY benchmarks ./benchmarks
+COPY tests ./tests
+COPY Makefile ./Makefile
+
+RUN pip install --no-cache-dir uv==0.13.0 \
+    && uv sync --locked --all-extras --all-packages --no-dev
+
+EXPOSE 8000
+
+CMD ["uv", "run", "--locked", "--package", "agentguard-server", "uvicorn", "agentguard_server.main:app", "--host", "0.0.0.0", "--port", "8000"]

agentguard_linter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samarth
+
+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_linter-0.1.0/Makefile

@@ -0,0 +1,28 @@
+.PHONY: install check test server-test lint fmt types
+
+UV_LINK_MODE := copy
+UV_PROJECT_ENVIRONMENT ?= $(HOME)/.venvs/agentguard
+export UV_LINK_MODE
+export UV_PROJECT_ENVIRONMENT
+
+install:
+	uv sync --locked --all-extras --all-packages
+
+check: lint types test server-test
+
+test:
+	uv run --locked --all-extras pytest
+
+server-test:
+	uv run --locked --all-extras --package agentguard-server pytest packages/agentguard-server/tests
+
+lint:
+	uv run --locked --all-extras ruff check .
+	uv run --locked --all-extras ruff format --check .
+
+fmt:
+	uv run --locked --all-extras ruff check --fix .
+	uv run --locked --all-extras ruff format .
+
+types:
+	uv run --locked --all-extras mypy --strict packages/agentguard-core/src packages/agentguard-langgraph/src packages/agentguard-graph/src packages/agentguard-owasp/src packages/agentguard-llm-triage/src packages/agentguard-trace/src packages/agentguard-server/src tests