aigis-lint 0.2.0__tar.gz

aigis_lint-0.2.0/.aigis.yaml

@@ -0,0 +1,8 @@
+# Aigis project-level configuration
+#
+# The examples/ directory contains intentionally unsafe code
+# used for demos and documentation. Suppress findings there.
+
+suppressions:
+  - path: "**/examples/**"
+    reason: "Demo fixtures — intentionally unsafe for documentation"

aigis_lint-0.2.0/.github/workflows/aigis.yml

@@ -0,0 +1,30 @@
+# Aigis Governance Scan
+#
+# Scans Python code for unsafe AI agent autonomy patterns on every push and PR.
+
+name: Aigis Governance Scan
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  aigis:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Aigis
+        run: pip install -e . && pip install pytest
+
+      - name: Run Aigis scan
+        run: aigis scan . -f console
+
+      - name: Run tests
+        run: python -m pytest tests/ -q

aigis_lint-0.2.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+*.so
+.env
+.venv/
+venv/
+test-repos/
+aigis-baseline.json
+.claude/
+.cursor/
+.windsurfrules
+northStar.txt
+AGENTS.md
+CLAUDE.md
+project-state/
+.github/copilot-instructions.md

aigis_lint-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aigis contributors
+
+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.

aigis_lint-0.2.0/PKG-INFO

@@ -0,0 +1,350 @@
+Metadata-Version: 2.4
+Name: aigis-lint
+Version: 0.2.0
+Summary: AI Execution Governance Linter — static analysis for unsafe AI autonomy
+Project-URL: Homepage, https://github.com/tyreamer/aigis
+Project-URL: Repository, https://github.com/tyreamer/aigis
+Project-URL: Issues, https://github.com/tyreamer/aigis/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,governance,linter,security,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Description-Content-Type: text/markdown
+
+# aigis
+
+**Governance linting for AI agents.** Verify that your agents can't delete, execute, or exfiltrate without approval — before they ever run.
+
+Aigis statically analyzes Python AI agent code and reports missing governance controls: approval gates on dangerous tools, consent wrappers on privileged operations, and execution budgets on agent loops. It works across LangChain, LangGraph, OpenAI Agents SDK, CrewAI, and AutoGen — with zero runtime dependencies.
+
+> **Public Alpha (v0.2.0)** — core rules are stable and validated against real-world repos. API surface and framework coverage may evolve. [Feedback welcome.](https://github.com/tyreamer/aigis/issues)
+
+---
+
+## Why This Exists
+
+AI agents call tools. Tools can delete files, run shell commands, and send HTTP requests. Most agent frameworks make it easy to expose these capabilities — and easy to forget the controls.
+
+Traditional SAST finds software vulnerabilities (SQL injection, XSS). Runtime AI safety tools catch bad behavior after deployment. Neither answers the question that matters before you ship:
+
+**Can this agent take high-impact actions without human approval, and can it run forever?**
+
+Aigis answers that question at build time, from code alone, with no LLM required.
+
+## What One Scan Gives You
+
+```bash
+$ aigis scan examples/unsafe_tool.py
+```
+```
+aigis v0.2.0 - AI Execution Governance Linter
+Scanning: examples/unsafe_tool.py
+
+  AIGIS001  ERROR  examples/unsafe_tool.py:13:0
+    Tool 'run_cmd' reaches side-effecting sink(s) [subprocess.run] without an approval gate
+    Evidence: sink=subprocess execution | approval=no | confidence=high
+    Fix: Add an approval decorator or wrap side-effecting calls with a confirmation check.
+
+  AIGIS002  ERROR  examples/unsafe_tool.py:13:0
+    Tool 'run_cmd' performs privileged operation(s) [subprocess.run] without a consent/policy wrapper
+    Evidence: sink=subprocess execution | approval=no | confidence=high
+    Fix: Add a consent/policy decorator (e.g. @requires_consent, @policy_check).
+
+Found 2 finding(s) (2 error, 0 warning)
+```
+
+From one scan, you get:
+- Every tool that can mutate, execute, or send data — and whether it has an approval gate
+- Every privileged operation (subprocess, system commands) — and whether it has a consent wrapper
+- Every agent entry point — and whether it has an iteration/budget limit
+- Structured evidence explaining *what* was found, *why* it matters, and *how* to fix it
+- Output in console, JSON, SARIF, or a visual HTML report
+
+## The Code That Defines the Category
+
+```python
+@tool
+def run_cmd(cmd: str, timeout: int = 30) -> str:
+    """Execute a shell command."""
+    result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
+    return result.stdout
+```
+
+An AI agent tool that runs arbitrary shell commands with `shell=True` and agent-controlled input. No human approval. No consent policy. No iteration limit on the agent calling it.
+
+Aigis fires both **AIGIS001** (no approval gate) and **AIGIS002** (no consent wrapper). This pattern was found in a real course repo with hundreds of forks.
+
+## Who This Is For
+
+- **AI platform teams** building tool-using agents for production
+- **AppSec engineers** adding agent code to their security review process
+- **Architecture leads** establishing governance standards for agentic systems
+- **Platform engineering** teams shipping LangGraph/CrewAI/OpenAI Agents infrastructure
+
+Aigis is built for teams where agents interact with real systems — not toy chatbots.
+
+## Install
+
+```bash
+pip install git+https://github.com/tyreamer/aigis.git
+```
+
+Or clone and install locally:
+
+```bash
+git clone https://github.com/tyreamer/aigis.git
+cd aigis
+pip install -e .
+```
+
+## 5-Minute Quick Start
+
+```bash
+# Scan your agent code
+aigis scan /path/to/your/project
+
+# Scan the included examples
+aigis scan examples/unsafe_tool.py       # fires AIGIS001 + AIGIS002
+aigis scan examples/unbounded_agent.py   # fires AIGIS001 + AIGIS003
+aigis scan examples/safe_agent.py        # clean — no findings
+
+# Generate a visual HTML report
+aigis scan /path/to/your/project -f html -o report.html
+
+# CI-ready outputs
+aigis scan . -f json                     # structured JSON
+aigis scan . -f sarif -o results.sarif   # GitHub Code Scanning
+
+# Baseline workflow: accept current findings, fail only on new ones
+aigis baseline . -o .aigis-baseline.json
+aigis scan . --baseline .aigis-baseline.json
+```
+
+## Rules
+
+### AIGIS001 — Mutating Tool Without Approval Gate
+
+Fires when a tool performs side effects (file I/O, subprocess, HTTP mutations) with no approval mechanism.
+
+```python
+# Flagged:
+@tool
+def delete_user(user_id: str):
+    os.remove(f"/data/{user_id}.json")
+
+# Clean:
+@tool
+@requires_approval
+def delete_user(user_id: str):
+    os.remove(f"/data/{user_id}.json")
+```
+
+**Detected sinks:** `os.remove`, `shutil.rmtree`, `subprocess.run`, `os.system`, `requests.post`, `httpx.put`, `open()` with write mode, and more.
+
+### AIGIS002 — Privileged Operation Without Consent Wrapper
+
+Fires when a tool calls subprocess or system commands without an explicit consent or policy wrapper. Generic `@requires_approval` is not sufficient — requires `@requires_consent`, `@policy_check`, or similar.
+
+```python
+# Flagged (generic approval is not consent-level):
+@tool
+@requires_approval
+def run_command(cmd: str):
+    subprocess.run(cmd, shell=True)
+
+# Clean:
+@tool
+@requires_consent
+def run_command(cmd: str):
+    subprocess.run(cmd, shell=True)
+```
+
+### AIGIS003 — Missing Execution Budget
+
+Fires when an agent entry point has no iteration or budget limit — neither on the constructor nor on any execution call in the same file.
+
+```python
+# Flagged:
+agent = Agent(name="x", tools=[my_tool])
+Runner.run(agent, input="go")               # no max_turns anywhere
+
+# Clean (constructor budget):
+agent = AgentExecutor(agent=llm, tools=[t], max_iterations=10)
+
+# Clean (execution-time budget):
+agent = Agent(name="x", tools=[my_tool])
+Runner.run(agent, input="go", max_turns=10)
+```
+
+Aigis checks budget controls at both construction time and execution time, including `Runner.run(max_turns=N)`, `app.invoke(config={"recursion_limit": N})`, `initiate_group_chat(max_rounds=N)`, and config variable resolution.
+
+### AIGIS004 — Unbounded Retry / Loop
+
+Fires when a tool contains a retry decorator without max attempts, or a `while True` loop without a break condition.
+
+```python
+# Flagged:
+@tool
+@retry                              # no stop=, no max_retries=
+def fetch_data(url: str) -> str:
+    return requests.post(url).text
+
+# Clean:
+@tool
+@retry(stop=stop_after_attempt(3))
+def fetch_data(url: str) -> str:
+    return requests.post(url).text
+```
+
+### AIGIS005 — User-Controlled Budget Without Cap
+
+Fires when an execution budget parameter (`max_turns`, `recursion_limit`, etc.) receives its value from a variable rather than a constant, with no visible server-side cap.
+
+```python
+# Flagged:
+def run_agent(user_max_turns: int):
+    Runner.run(agent, input="go", max_turns=user_max_turns)  # no cap
+
+# Clean:
+def run_agent(user_max_turns: int):
+    Runner.run(agent, input="go", max_turns=min(user_max_turns, 50))
+```
+
+### AIGIS006 — Raw Chat History as Retrieval Query
+
+Fires when a raw chat history variable (`messages`, `chat_history`, `conversation`) is passed directly to a retrieval function without a query rewriting step.
+
+```python
+# Flagged:
+results = store.similarity_search(chat_history)  # raw transcript as query
+
+# Clean:
+query = condense_question(chat_history)
+results = store.similarity_search(query)
+```
+
+## Supported Frameworks
+
+| Framework | Tool Detection | Entry Points | Budget Controls |
+|-----------|---------------|-------------|-----------------|
+| **LangChain** | `@tool` | `AgentExecutor` | `max_iterations`, `timeout` |
+| **LangGraph** | `add_node` | `compile()` | `recursion_limit` |
+| **OpenAI Agents** | `@function_tool` | `Agent()` | `max_turns` (constructor or `Runner.run`) |
+| **CrewAI** | `@tool` | `Crew()` | `max_iter`, `max_rpm` |
+| **AutoGen / AG2** | `register_for_llm` | `AssistantAgent`, `GroupChat` | `max_turns`, `max_round` |
+
+## Output Formats
+
+| Format | Use Case | Command |
+|--------|----------|---------|
+| **Console** | Local development | `aigis scan .` |
+| **JSON** | CI pipelines, scripting | `aigis scan . -f json` |
+| **SARIF** | GitHub Code Scanning | `aigis scan . -f sarif -o results.sarif` |
+| **HTML** | Reports, reviews, demos | `aigis scan . -f html -o report.html` |
+
+The HTML report is a self-contained dark-mode file with filters, expandable evidence cards, remediation guidance, and framework-specific context. No backend required — open it in any browser.
+
+## Suppression
+
+### Inline
+
+```python
+@tool  # aigis: disable=AIGIS001 -- reviewed and accepted risk
+def my_tool():
+    os.remove(path)
+```
+
+### Config File
+
+Create `.aigis.yaml` in your project root:
+
+```yaml
+suppressions:
+  - rule: AIGIS001
+    path: "scripts/**"
+    reason: "Internal tooling with runtime approval"
+
+  - rule: AIGIS003
+    symbol: my_agent
+    reason: "Budget enforced by external orchestrator"
+```
+
+### Baseline
+
+Accept current findings, fail only on new ones:
+
+```bash
+aigis baseline . -o .aigis-baseline.json
+aigis scan . --baseline .aigis-baseline.json
+```
+
+Fingerprints use rule ID + file path + tool name (not line numbers), so they survive code edits.
+
+## How Aigis Is Different
+
+| | Traditional SAST | Runtime AI Safety | **Aigis** |
+|---|---|---|---|
+| **When** | Build time | Runtime | **Build time** |
+| **What** | Software vulns (SQLi, XSS) | Model behavior, guardrails | **Agent governance controls** |
+| **Checks for** | Code flaws | Harmful outputs | **Missing approval, consent, bounds** |
+| **Requires runtime** | No | Yes | **No** |
+| **AI/LLM needed** | No | Often | **No** |
+
+Aigis is not a prompt scanner, a model guardrail, or a vulnerability finder. It checks whether the structural controls that should exist in agent code — approval gates, consent wrappers, execution budgets — are actually present.
+
+## What It Does NOT Detect
+
+- **Cross-file call graphs** — sinks must be in the same function body as the tool
+- **Data-flow analysis** — cannot track tainted inputs through variables
+- **Runtime behavior** — all analysis is static and deterministic
+- **SQL mutations** — `cursor.execute()` is too ambiguous without query analysis
+- **Dynamic tool registration** — runtime reflection / metaprogramming
+- **Non-Python code** — Python only
+- **LLM-based judgment** — purely pattern-based, no semantic understanding
+
+## Roadmap
+
+**What works well today:**
+- Tool detection and sink analysis across 6 frameworks
+- Approval/consent/budget governance checks
+- Constructor-time and execution-time budget detection
+- Suppression, baselines, and 4 output formats
+
+**What's next:**
+- Cross-file call graph support
+- Data-flow tracking for indirect sinks
+- Posture summary (aggregate governance metrics per scan)
+- PyPI package publishing (`pip install aigis`)
+- Published GitHub Action
+- Additional framework depth (LlamaIndex, Google ADK)
+
+**Explicitly out of scope for now:**
+- TypeScript/JavaScript support
+- Runtime monitoring
+- LLM-based detection
+- Cloud dashboard or hosted service
+
+## Design Principles
+
+- **Deterministic** — code patterns only, never LLM judgment
+- **Tri-state** — yes / no / unknown; unknown does not fail
+- **Low noise** — false negatives over false positives
+- **Missing guard is first-class** — the absence of a control is the finding
+- **Evidence-first** — every finding explains what, why, and how to fix
+
+## Feedback
+
+Aigis is in public alpha. If you're building tool-using agents and want governance visibility before production, we want to hear from you.
+
+- [Open an issue](https://github.com/tyreamer/aigis/issues) with findings, false positives, or framework gaps
+- [Start a discussion](https://github.com/tyreamer/aigis/discussions) about your governance workflow
+
+We're especially interested in feedback from teams shipping agents with file access, network access, or subprocess execution.