Metadata-Version: 2.4
Name: bastion-ai-security
Version: 0.1.6
Summary: Supply-chain security, capability intelligence, and trust system for AI agents
Author: Bastion AI
License: MIT
Project-URL: Homepage, https://github.com/brantley-creator/Bastion_ai
Project-URL: Documentation, https://github.com/brantley-creator/Bastion_ai#readme
Project-URL: Repository, https://github.com/brantley-creator/Bastion_ai
Project-URL: Issues, https://github.com/brantley-creator/Bastion_ai/issues
Keywords: ai,security,agents,supply-chain,sbom,aibom
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: flask>=3.1.2
Requires-Dist: flask-dance>=7.1.0
Requires-Dist: flask-login>=0.6.3
Requires-Dist: flask-session>=0.8.0
Requires-Dist: flask-sqlalchemy>=3.1.1
Requires-Dist: gunicorn>=25.0.3
Requires-Dist: oauthlib>=3.3.1
Requires-Dist: psycopg2-binary>=2.9.11
Requires-Dist: pyjwt>=2.11.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.28
Provides-Extra: js
Requires-Dist: esprima>=4.0; extra == "js"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: esprima>=4.0; extra == "all"
Requires-Dist: mcp>=1.0; extra == "all"
Dynamic: license-file

# 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/

## Two Ways to Use Bastion

Bastion works for both **humans operating from the command line** and **AI agents acting autonomously**.

### Path 1: Human-Operated CLI

You install Bastion, run scans yourself, and review results in the terminal or cloud dashboard. This is the traditional security workflow — a developer or security engineer vetting plugins before deployment.

```
pip install bastion-ai-security
bastion init
bastion scan
```

You see the results, make decisions, and optionally connect to the cloud dashboard for monitoring and trust scores.

### Path 2: AI Agent Integration (MCP Server)

Bastion runs as an MCP (Model Context Protocol) server, letting AI agents like Claude, Cursor, or any MCP-compatible client use it as a built-in security tool. The agent can scan directories, analyze files, and check trust scores autonomously — acting as its own security gate before installing or using third-party plugins.

```
pip install bastion-ai-security[mcp]
bastion mcp-serve
```

The AI agent calls Bastion's tools directly through the MCP protocol. No human in the loop required — the agent makes security decisions based on scan results.

Both paths produce the same security artifacts, trust scores, and detection coverage across all 10 capability categories.

## 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 across 10 security categories:

- **System execution** — detects capabilities that allow running arbitrary commands
- **Network access** — identifies outbound network communication
- **Secret/environment access** — flags reading of credentials and environment variables
- **File system access** — detects reading/writing to the local filesystem
- **Dynamic code execution** — identifies runtime code generation and execution
- **Obfuscation patterns** — catches attempts to hide malicious intent through encoding
- **Sandbox bypass** — flags attempts to disable or circumvent safety controls
- **Install script risks** — detects potentially dangerous installation behaviors
- **Hardcoded secrets** — finds credentials embedded directly in source code
- **Privilege escalation** — identifies plugins requesting excessive combined permissions

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 ./my-plugins
```

### OpenClaw SKILL.md Analysis

Bastion has first-class support for OpenClaw skills. When scanning with `--openclaw`, it analyzes `SKILL.md` files for dangerous agent instructions, unsafe configuration flags, suspicious install metadata, and skills that instruct agents to download and execute remote code.

```bash
bastion scan --openclaw
```

This directly addresses research findings on skill-based supply chain attacks, where innocent-looking documentation can bundle malicious instructions.

### MCP Server (AI Agent Integration)

Bastion can run as an MCP (Model Context Protocol) server, letting AI agents and LLMs use it as a security tool directly.

Install with MCP support:

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

Start the MCP server:

```bash
bastion mcp-serve
```

Or run it directly:

```bash
bastion-mcp
```

The MCP server exposes these tools:

| Tool | Description |
|------|-------------|
| `scan_directory` | Scan a directory for plugin/skill security risks |
| `analyze_file` | Analyze a single file for dangerous capabilities |
| `get_project_status` | Get current Bastion project configuration |
| `list_detection_categories` | List all detection categories with descriptions |
| `check_trust_score` | Check trust score from Bastion Cloud |

To configure in Claude Desktop or other MCP clients, add to your config:

```json
{
  "mcpServers": {
    "bastion-security": {
      "command": "bastion-mcp"
    }
  }
}
```

This allows an AI agent running on your machine to automatically verify plugins before installing them — acting as a security gate in the agent's workflow.

### 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 discovers plugins using framework-aware heuristics. It recognizes common agent frameworks (OpenClaw, LangChain, AutoGPT, CrewAI, and others) and finds plugins without manual configuration.

### Capability Analysis

Each discovered plugin is analyzed using language-appropriate static analysis:
- **Python**: AST-based analysis
- **JavaScript/TypeScript**: Parser-based analysis with fallback strategies
- **SKILL.md**: Structured document analysis for agent instruction risks

### Detection Categories

Bastion scans across 10 capability categories at varying severity levels:

| Category | Severity |
|----------|----------|
| System Execution | Critical |
| Dynamic Code | Critical |
| Obfuscation | Critical |
| Sandbox Bypass | Critical |
| Hardcoded Secret | Critical |
| Privilege Escalation | Critical/High |
| Network Access | High |
| Secret/Env Access | High |
| Install Script Risk | High/Medium |
| File System Access | Medium |

### Privilege Escalation Detection

Bastion automatically flags plugins that combine multiple dangerous capabilities, identifying over-privileged plugins that pose elevated risk.

### 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
```

Uses exit codes to signal whether security risks were found, suitable for automated gates.

## Language Support

- Python (`.py`)
- JavaScript (`.js`, `.jsx`)
- TypeScript (`.ts`, `.tsx`)
- SKILL.md (OpenClaw skill format)

## 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

If Bastion doesn't find your plugins automatically, point it at the right directory:

```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
