Metadata-Version: 2.4
Name: aigov
Version: 0.5.0
Summary: AI Governance-as-Code CLI — discover, classify, and govern AI systems
Author-email: Abhay K <kshirabhay@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/abhaykshir/aigov
Project-URL: Repository, https://github.com/abhaykshir/aigov
Project-URL: Issues, https://github.com/abhaykshir/aigov/issues
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer
Requires-Dist: rich
Requires-Dist: pyyaml
Requires-Dist: gitpython
Provides-Extra: aws
Requires-Dist: boto3; extra == "aws"

# aigov

**AI Governance-as-Code CLI — discover, classify, and govern AI systems across your infrastructure.**

---

## tl;dr

aigov scans your codebase, CI pipeline, and cloud infrastructure to automatically discover every AI system in use, produce an automated EU AI Act risk signal for each one, and flag the compliance gaps your team needs to close. It works like `trivy` for CVEs — but for AI governance risk. Built for engineering teams who must achieve EU AI Act compliance before the August 2026 enforcement deadline.

> **Disclaimer:** aigov classifications are automated signals based on pattern matching. They are **not legal advice**. Consult qualified legal counsel for compliance decisions.

---

## What problem are we solving?

The EU AI Act's full enforcement deadline is **2 August 2026**. Every organisation deploying AI in or selling into the EU must maintain a documented inventory of its AI systems — yet most engineering teams have no idea how many AI integrations actually live in their codebases. Studies show 80%+ of knowledge workers use AI tools without formal approval, creating pervasive "shadow AI" that nobody has inventoried or risk-assessed. No open-source tool existed to automatically discover and inventory AI usage the way `trivy` or `grype` handle CVEs. aigov fills that gap — run one command, get a full AI inventory with EU AI Act risk classifications.

---

## What does aigov do?

aigov runs a four-stage pipeline: **discover** AI systems from imports, API keys, MCP configs, and cloud resources; produce an **automated risk signal** against the EU AI Act risk tiers (pattern matching, not legal advice); **gap-analyze** what compliance controls are missing; and **generate** draft documentation and conformity declarations. The full pipeline runs in a single command:

```bash
aigov scan . --classify --gaps --docs
```

---

## Quick Start

```bash
pip install aigov
aigov scan . --classify
```

Example output:

```
                        AI Systems Found (6)
┌──────────────────────────────────────────────────────────────────────┐
│  #  Name                   Type         Provider     Risk            │
├──────────────────────────────────────────────────────────────────────┤
│  1  openai (gpt-4o)        api_service  OpenAI       ⚠  limited     │
│  2  anthropic (claude-3)   api_service  Anthropic    ⚠  limited     │
│  3  rekognition             model        AWS          🔴 high_risk   │
│  4  filesystem              mcp_server   —            ✓  minimal     │
│  5  langchain               agent        LangChain    ⚠  limited     │
│  6  deepseek                api_service  DeepSeek     ⚠  limited     │
└──────────────────────────────────────────────────────────────────────┘

Found 6 AI systems · 1 high-risk · 3 limited-risk · 2 minimal-risk
```

Export to JSON, Markdown, or CSV for compliance evidence and GRC platform import:

```bash
aigov scan . --output json --out-file inventory.json
aigov scan . --output markdown --out-file AIINVENTORY.md
aigov scan . --classify --output csv --out-file inventory.csv
```

Export a saved scan result directly to CSV or flat JSON for Excel, CISO Assistant, ServiceNow, or any GRC tool:

```bash
aigov export inventory.json --format csv --out-file inventory.csv
aigov export inventory.json --format json --out-file inventory-flat.json
```

---

## Scanners

| Scanner | What it finds |
|---------|--------------|
| `code.python_imports` | AI/ML library imports in Python source — OpenAI, Anthropic, LangChain, HuggingFace, DeepSeek, and 20+ others mapped to provider and jurisdiction |
| `code.api_keys` | Hardcoded AI service API keys in source, config, and env files — values are never stored, only redacted previews |
| `config.mcp_servers` | MCP server configs from Claude Desktop, Cursor, Windsurf, VS Code, and project-level `.mcp.json` files |
| `cloud.aws` | AWS Bedrock foundation models, SageMaker endpoints, Comprehend, Rekognition, and Lex resources (`pip install aigov[aws]`) |
| `infra.docker` | Detects AI base images, model files, and ML frameworks in Dockerfiles and docker-compose |
| `infra.terraform` | Discovers AI service provisioning in Terraform/OpenTofu across AWS, Azure, and GCP |
| `infra.kubernetes` | Finds GPU workloads, AI containers, and ML platform CRDs in Kubernetes manifests |

All findings include `origin_jurisdiction` (ISO 3166-1) for geography-based policy filtering.

---

## Classification Frameworks

| Framework | Articles covered | Status |
|-----------|-----------------|--------|
| EU AI Act | Article 5 (prohibited practices), Annex III (high-risk categories), Article 50 (transparency obligations) | **Available** |
| Colorado AI Act (SB 205) | High-risk AI system obligations for Colorado residents | Roadmap |
| NIST AI RMF | Govern, Map, Measure, Manage functions | Roadmap |

---

## Risk Scoring

`aigov scan --with-risk` produces a deterministic 0–100 risk score per finding, combining the EU AI Act classification with deployment context (environment, exposure, data sensitivity, interaction type). Scores are pattern-matching signals, not legal determinations — see [docs/scoring-model.md](docs/scoring-model.md) for the base scores, modifier tables, banding, confidence calculation, and a worked example.

---

## CI/CD Integration

Add aigov to your workflow to block deployments if prohibited AI systems are detected:

```yaml
steps:
  - uses: actions/checkout@v4
  - uses: abhaykshir/aigov@v1
    with:
      scan-paths: "."
      classify: "true"
      fail-on: "prohibited,high_risk"
```

The action fails the step on any finding at or above the configured risk level. See [`action.yml`](action.yml) for all inputs and outputs.

---

## Continuous Monitoring

aigov ships three tools for ongoing AI governance — not just one-shot scans.

**Git hooks** — block commits that introduce prohibited AI systems:

```bash
aigov hooks install
# pre-commit hook now runs aigov scan --classify on every commit
# PROHIBITED systems block the commit; HIGH_RISK systems warn
```

Approve known systems so they don't trigger warnings:

```yaml
# .aigov-allowlist.yaml
approved:
  - id: "abc123def456"
    reason: "Approved by AI governance board 2026-01-15"
  - name_pattern: "internal-chatbot-*"
    reason: "Internal tools approved under policy AI-2026-003"
```

**Drift detection** — detect new AI systems since your last approved baseline:

```bash
# Save current state as the approved baseline
aigov baseline save

# In CI: compare against baseline and fail if new HIGH_RISK or PROHIBITED systems appear
aigov baseline diff --fail-on-drift
```

**Example CI workflow** combining all three:

```yaml
- uses: actions/checkout@v4
- uses: abhaykshir/aigov@v1
  with:
    scan-paths: "."
    classify: "true"
    fail-on: "prohibited,high_risk"
- name: Drift check
  run: aigov baseline diff --fail-on-drift --baseline .aigov-baseline.json
```

---

## Custom Rules

Layer your organisation's own governance policies on top of EU AI Act classification. Create `.aigov-rules.yaml` in your repo root — aigov auto-discovers it on every `scan` or `classify` run.

```yaml
# .aigov-rules.yaml
custom_rules:
  - name: "Block restricted jurisdictions"
    description: "Company policy prohibits AI from certain jurisdictions"
    match:
      jurisdiction: ["CN", "RU"]
    action:
      risk_level: prohibited
      reason: "Company policy restricts AI from this jurisdiction"

  - name: "Flag patient data AI"
    description: "AI processing patient data requires HIPAA review"
    match:
      keywords: ["patient", "diagnosis", "clinical", "health record"]
    action:
      risk_level: high_risk
      reason: "HIPAA review required per internal policy AI-2026-001"

  - name: "Register LLM usage"
    description: "All LLM API services need governance board approval"
    match:
      providers: ["OpenAI", "Anthropic", "Google", "Mistral"]
    action:
      risk_level: limited_risk
      reason: "LLM usage requires governance board registration"
```

Three match types can be combined (AND logic across types, OR within each list):

| Match type | Field checked |
|------------|--------------|
| `keywords` | Record name, description, and source location (case-insensitive) |
| `jurisdiction` | `origin_jurisdiction` tag (ISO 3166-1 country code) |
| `providers` | Provider name (case-insensitive) |

Custom rules **only escalate** — they never downgrade a regulatory classification already set by the EU AI Act classifier. Use `--rules` to specify a non-default path:

```bash
aigov scan . --classify --rules ./policies/ai-rules.yaml
```

---

## Architecture

```mermaid
flowchart LR
    CLI["CLI\naigov scan"] --> Engine["Scan Engine"]
    Engine --> S1["code.python_imports"]
    Engine --> S2["code.api_keys"]
    Engine --> S3["config.mcp_servers"]
    Engine --> S4["cloud.aws"]
    S1 & S2 & S3 & S4 --> Records["AISystemRecord[]"]
    Records --> Classifier["Classifier\n(EU AI Act)"]
    Classifier --> Gaps["Gap Analyzer"]
    Gaps --> Docs["Docs Generator"]
    Docs --> Out1["JSON / Markdown"]
    Docs --> Out2["Conformity Declarations"]
```

---

## Security

See [SECURITY.md](SECURITY.md) for the full policy.

- **No secrets stored** — API keys detected but never recorded; only type, location, and a 4-char redacted preview are kept
- **Read-only** — never modifies source files, cloud resources, or system configurations
- **Local processing** — no telemetry, no external API calls, no data leaves your machine
- **Minimal dependencies** — small, auditable dependency tree from trusted sources with pinned versions

---

## Tests

959 tests passing across the scanner, classifier, risk-scoring, policy, explainability, graph, and CI subsystems. Run them locally with `pytest` from the repo root.

---

## Roadmap

> aigov is in active alpha development. Features are functional but evolving. Feedback and contributions welcome.

| Phase | Status | Description |
|-------|--------|-------------|
| 1 — Discovery | Shipped (alpha) | Python imports, API keys, MCP server scanners |
| 2 — Risk Classification | Shipped (alpha) | EU AI Act Article 5, Annex III, Article 50 |
| 3 — Gap Analysis | Shipped (alpha) | Compliance gap analyzer — missing controls per finding |
| 4 — Documentation Generator | Shipped (alpha) | Draft conformity declarations and DPIA stubs |
| 5 — Cloud Scanners | Shipped (alpha) | AWS Bedrock, SageMaker, Comprehend, Rekognition, Lex |
| 6 — CI/CD Integration | Shipped (alpha) | GitHub Actions reusable action and `aigov-check` CLI |
| 7 — Continuous Monitoring | Shipped (alpha) | Git hooks, allowlist, and baseline drift detection |
| 8 — Custom Rules & GRC Export | Shipped (alpha) | Org-specific rules engine; CSV/JSON export for GRC platforms |
| 9 — Additional Frameworks | 📋 Planned | Colorado AI Act SB 205, NIST AI RMF |
| 10 — More Scanners | 📋 Planned | JS/TS imports, Terraform AI resources, Docker image scanning |
| 11 — Dashboard | 📋 Planned | Web UI for inventory visualization and compliance tracking |

---

## Contributing

Contributions are welcome — especially new scanners, classification rules, and framework mappings. See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.

---

## Governance

This project is maintained by [Abhay K](https://github.com/abhaykshir). See [GOVERNANCE.md](GOVERNANCE.md) for the decision process and regulatory accuracy policy.

---

## License

Apache 2.0 — see [LICENSE](LICENSE).
