Usage Guide

A developer-oriented guide to adding Bastion to your project and using it day-to-day.

---

Install

# Add the marketplace (once)
claude plugin marketplace add USIG-Digital/bastion-security-framework

# Install the plugin
claude plugin install bastion@usig-digital

Initialize a Project

/bastion:init

Creates bastion.yaml and security/vectors/ with 5 empty domain files (authorization, arithmetic, temporal, state, composition). Edit bastion.yaml to set your project's source and test directories.

Configure Multi-Model Review (Optional)

Copy the .env.example from the framework and add your API keys:

cp .env.example .env
# Edit .env with your keys:
#   ANTHROPIC_API_KEY=sk-ant-...
#   GOOGLE_API_KEY=AIza...
#   OPENAI_API_KEY=sk-...

Then enable providers in bastion.yaml:

models:
  providers:
    anthropic:
      enabled: true
      model: "claude-sonnet-4-20250514"
    google:
      enabled: true
      model: "gemini-2.5-pro"
    openai:
      enabled: true
      model: "o3"

At least 2 providers are needed for meaningful adversarial review.

---

Skills (Slash Commands)

Security Scanning

Command	What it does
/bastion:scan	Run semgrep rules (DAML + web)
/bastion:scan daml	DAML rules only
/bastion:scan web	Web rules only
/bastion:secrets	Scan for hardcoded secrets (gitleaks)
/bastion:vuln	Scan dependencies for vulnerabilities (trivy)

Verification & Analysis

Command	What it does
/bastion:verify	Full check: semgrep + tests + vector coverage + checklist
/bastion:verify-quick	Semgrep only, skip tests
/bastion:scope	Show vectors applicable to your changed files
/bastion:scope --all	Show vectors for all DAML files
/bastion:status	Dashboard: vector counts, coverage, sync status
/bastion:coverage	Detailed coverage report by domain and severity
/bastion:explain AV-001	Explain a specific vector: what, why, how to fix

Agent-Powered Review

Command	What it does
/bastion:audit	Run all 5 auditor agents (auth, arithmetic, temporal, state, composition)
/bastion:audit --domain authorization	Run a specific domain auditor
/bastion:research	Run intelligence-sync to sweep external sources for new threats
/bastion:multi-audit --task audit	Multi-model adversarial review across Claude/Gemini/GPT
/bastion:multi-audit --task compose	Multi-model composition analysis

Integration & Governance

Command	What it does
/bastion:integrate-vector	Accept a proposed vector — generates YAML + semgrep rule + test skeleton + index update
/bastion:propose --dry-run	Preview what would be proposed to the commons
/bastion:propose --pending	Submit all pending proposals (includes effectiveness metrics)
/bastion:sync	Check for framework updates
/bastion:docs	Regenerate SECURITY.md from vector files
/bastion:metrics	Show effectiveness report: discovery rates, accept rates, coverage trajectory

Validation (CI)

Command	What it does
/bastion:validate	Validate vector YAML schema
/bastion:check-duplicates	Check for duplicate vector IDs and CWEs

---

Agents

Agents are available automatically after plugin install.

Agent	Domain	What it finds
bastion:authorization-auditor	Access control	Controllers, signatories, observers, multi-party auth
bastion:arithmetic-auditor	Numeric operations	Division, overflow, precision, rounding
bastion:temporal-auditor	Time-based logic	Deadlines, expiry, staleness, time manipulation
bastion:state-auditor	Contract state	Lifecycle transitions, state machines, stale references
bastion:composition-auditor	Cross-domain chains	Composite attacks: CHAIN, AMPLIFY, BYPASS
bastion:intelligence-sync	External research	Sweeps 134+ sources for new threats and sources

---

Common Workflows

First Time Setup

/bastion:init
# Edit bastion.yaml with your project paths
/bastion:scan
/bastion:status

Daily Development

# Before committing — the pre-commit hook runs automatically
# but you can also check manually:
/bastion:scope
/bastion:verify-quick

The post-edit hook automatically reminds you about applicable vectors when you edit .daml files.

Deep Security Review

# Run all domain auditors
/bastion:audit

# Or run a specific domain
/bastion:audit --domain authorization

# Review agent proposals, accept valid ones
/bastion:integrate-vector

Multi-Model Adversarial Review

# Independent discovery across all configured models
/bastion:multi-audit --task audit

# Independent composition across all models
/bastion:multi-audit --task compose

# Models challenge each other's proposals
/bastion:multi-audit --task challenge --proposals security/results/multi-audit.yaml

Composition Analysis

# Run the composition auditor (after domain auditors so it has fresh primitives)
/bastion:audit --domain composition

# Or as part of multi-model review
/bastion:multi-audit --task compose

The composition auditor reads all domain vectors as primitives and discovers cross-domain attack chains. Accepted composites become new primitives for future runs.

Track Effectiveness

# Show local effectiveness report
/bastion:metrics

# Check if the framework is actually finding real things
# Look for:
#   - Accept rate > 40% (signal, not noise)
#   - Blind spot rate > 10% (multi-model is adding value)
#   - Coverage trajectory: improving

Share Findings with the Commons

/bastion:propose --dry-run     # preview
/bastion:propose --pending     # submit (includes anonymized metrics)

Update the Framework

claude plugin marketplace update usig-digital
claude plugin update bastion@usig-digital
# Restart Claude Code to apply

Or from within Claude Code:

/bastion:sync

---

Project Structure

After /bastion:init, your project has:

your-project/
├── bastion.yaml                    # Project configuration
├── .env                            # API keys (gitignored)
├── security/
│   ├── vectors/
│   │   ├── _index.yaml             # Master vector index
│   │   ├── authorization.yaml      # Auth vectors (grows over time)
│   │   ├── arithmetic.yaml         # Numeric vectors
│   │   ├── temporal.yaml           # Time-based vectors
│   │   ├── state.yaml              # State management vectors
│   │   └── composition.yaml        # Cross-domain composite chains
│   ├── metrics/                    # Effectiveness metrics (gitignored)
│   │   └── history.yaml            # Append-only event log
│   ├── results/                    # Verification results (gitignored)
│   │   └── latest.json             # Most recent verify run
│   ├── proposals/                  # Pending upstream proposals
│   │   └── pending/
│   └── intel/                      # Local source overrides (optional)
└── .semgrep/
    ├── daml-security.yaml          # Framework semgrep rules
    └── bastion-generated.yaml      # Rules generated by /integrate-vector

Vector files and _index.yaml start empty. They grow as agents discover findings and you validate them through /bastion:integrate-vector.

---

How the Pipeline Works

1. Discovery     →  Agents + multi-model orchestrator find potential issues
2. Human Review  →  You review proposals and accept/reject
3. Integration   →  /integrate-vector creates YAML + semgrep + test
4. Governance    →  /verify runs all checks on every build (forever)

Every accepted finding becomes a permanent check. The system only gets stronger over time.

---

Hooks (Automatic)

These run automatically — no manual invocation needed:

Hook	When	What happens
Session init	Every Claude Code session	Warns about stale sync, pending proposals, CRITICAL missing vectors
Post-edit	After editing a .daml file	Shows count of applicable attack vectors
Pre-commit	Before git commit	Blocks if CRITICAL semgrep findings exist

---

Prerequisites

Tool	Required for	Install
Python 3.8+	All skills	Pre-installed on macOS
pyyaml	Vector operations	pip install pyyaml
semgrep	/bastion:scan, pre-commit hook	brew install semgrep
gitleaks	/bastion:secrets	brew install gitleaks
trivy	/bastion:vuln	brew install trivy
anthropic	Multi-model (Claude)	pip install anthropic
google-generativeai	Multi-model (Gemini)	pip install google-generativeai
openai	Multi-model (GPT)	pip install openai