# Bastion AI

Supply-chain security, capability intelligence, and trust system for AI agents.

Bastion AI protects bot-first ecosystems by detecting malicious or risky skills/plugins/tools, tracking capability drift over time, and producing machine-readable security artifacts (Dynamic AIBOM).

## Installation

```bash
pip install bastion-ai-security
```

For JavaScript/TypeScript analysis support:

```bash
pip install bastion-ai-security[js]
```

PyPI: https://pypi.org/project/bastion-ai-security/

## Quick Start

### Initialize a project

```bash
cd your-agent-project
bastion init
```

This creates a `.bastion/` directory with project configuration and prepares for scanning.

### Scan for risks

```bash
bastion scan
```

Bastion auto-discovers plugins, skills, and tools in your project and analyzes them for:

- **System execution** — subprocess, os.system, child_process, etc.
- **Network access** — requests, fetch, urllib, etc.
- **Secret/environment access** — os.environ, process.env, dotenv, etc.
- **File system access** — open, pathlib, glob, shutil, fs module, etc.
- **Dynamic code execution** — eval, exec, Function constructor, etc.
- **Obfuscation patterns** — base64+exec, encoded strings, etc.

For each plugin, the scan also captures:

- **Dependencies** — third-party libraries imported by the plugin
- **Skills** — exported functions and classes
- **Metadata** — description (from docstrings), file count, and lines of code

Scan a specific directory:

```bash
bastion scan --path ./skills
```

### Check project status

```bash
bastion status
```

Shows your project ID, version, baseline status, cloud connection, and verification URL.

### Connect to Bastion Cloud

```bash
bastion connect
```

Links your project to Bastion Cloud for continuous monitoring, trust scores, and a security dashboard.

After connecting, the CLI prints a **claim URL** — click it to link the project to your account on the dashboard. If you're not signed in yet, you'll be prompted to sign in first, and the project will be linked automatically.

Once connected, every `bastion scan` automatically uploads results to the cloud. No extra flags needed.

Dashboard: https://bastion-ai-hub.replit.app

### Share verification with partners

After a scan uploads to the cloud, the CLI prints a **verification URL** like:

```
https://bastion-ai-hub.replit.app/verify/abc123...
```

Share this link with business partners, customers, or integrators. The public verification page shows:

- Trust score and verification status
- Detected capabilities
- Number of scans and plugins analyzed
- Last scan date

No login is required to view a verification page.

## How It Works

### Plugin Discovery

Bastion automatically finds plugins by scanning:
- Known framework directories (`skills/`, `tools/`, `plugins/`, `extensions/`)
- Framework-specific patterns (OpenClaw, LangChain, AutoGPT, CrewAI)
- File naming conventions (`*_skill.py`, `*_tool.js`, etc.)

### Capability Analysis

Each discovered plugin is analyzed using:
- **Python**: AST-based static analysis
- **JavaScript/TypeScript**: esprima parsing with regex fallback

### Risk Levels

| Level | Description |
|-------|-------------|
| Critical | System execution, dynamic code, obfuscation detected |
| High | Network access, secret/env access detected |
| Medium | New plugin without dangerous capabilities |
| Low | No risky capabilities detected |

### Drift Detection

On subsequent scans, Bastion compares against the baseline to detect:
- **New plugins** added since last scan
- **Modified plugins** with changed capabilities
- **Removed plugins** no longer present

### Generated Artifacts

All artifacts are written to `.bastion/`:

| File | Description |
|------|-------------|
| `security_state.json` | Overall security posture |
| `capability_surface.json` | All plugin capabilities |
| `drift_summary.json` | Changes since last scan |
| `aibom.json` | Dynamic AI Bill of Materials |
| `events.log.jsonl` | Rolling event log |
| `baseline.json` | Baseline for drift comparison |

## CI/CD Usage

```bash
bastion init
bastion scan --ci
```

Exit codes:
- `0` — No high-risk findings
- `1` — High or Critical findings detected

## Language Support

- Python (`.py`)
- JavaScript (`.js`, `.jsx`)
- TypeScript (`.ts`, `.tsx`)

## Troubleshooting

### "bastion: command not found"

Make sure the pip install directory is in your PATH:

```bash
python3 -m bastion --version
```

Or:

```bash
pip install --user bastion-ai-security
export PATH="$HOME/.local/bin:$PATH"
bastion --version
```

### Scan finds no plugins

Bastion looks for plugins in common directories like `skills/`, `tools/`, `plugins/`, `extensions/`. If your plugins are elsewhere:

```bash
bastion scan --path /path/to/your/plugins
```

### Cloud connection issues

Scans work fully offline — results are saved locally in `.bastion/` even if the cloud is unreachable.

## License

MIT
