Overview

The OSSASAI audit script (ossasai-audit.sh) provides automated verification of security controls. It can be run manually, integrated into CI/CD, or scheduled for continuous monitoring.

Installation

# Download audit script
curl -sSL https://raw.githubusercontent.com/gensecaihq/ossasai/main/tools/ossasai-audit.sh -o ossasai-audit.sh
chmod +x ossasai-audit.sh

# Verify signature (recommended)
curl -sSL https://raw.githubusercontent.com/gensecaihq/ossasai/main/tools/ossasai-audit.sh.sig -o ossasai-audit.sh.sig
gpg --verify ossasai-audit.sh.sig ossasai-audit.sh

Basic Usage

# Run full audit at specified level
./ossasai-audit.sh --level L2

# Check specific control
./ossasai-audit.sh --check CP-01

# Check specific domain
./ossasai-audit.sh --domain TB

# Verbose output
./ossasai-audit.sh --level L2 --verbose

# JSON output
./ossasai-audit.sh --level L2 --output-format json > report.json

Command Reference

Option	Description
--level L1\|L2\|L3	Target assurance level
--check CONTROL	Check specific control
--domain DOMAIN	Check all controls in domain
--config PATH	Configuration file to audit
--output-format text\|json\|junit	Output format
--verbose	Detailed output
--quiet	Minimal output
--fail-on-warning	Exit 1 on warnings

Output Interpretation

Text Output

OSSASAI Security Audit
====================
Target Level: L2
Config: /etc/ocsas/config.yaml

Control Results:
----------------
[PASS] CP-01: Secure Default Configuration
[PASS] CP-02: Permission Model Enforcement
[FAIL] NS-01: TLS Enforcement
       Finding: HTTP endpoints found on port 8080
       Remediation: Configure TLS termination

Summary:
--------
Passed: 15/17 (88.2%)
Failed: 2
Level: L2 NOT ACHIEVED

JSON Output

{
  "assessment": {
    "timestamp": "2026-01-15T10:30:00Z",
    "version": "1.0.0",
    "target_level": "L2",
    "config_path": "/etc/ocsas/config.yaml"
  },
  "summary": {
    "total_controls": 17,
    "passing": 15,
    "failing": 2,
    "not_applicable": 0,
    "compliance_percentage": 88.2,
    "level_achieved": false
  },
  "controls": [
    {
      "id": "CP-01",
      "title": "Secure Default Configuration",
      "status": "PASS",
      "verification": "automated",
      "evidence": ["config-defaults verified"]
    },
    {
      "id": "NS-01",
      "title": "TLS Enforcement",
      "status": "FAIL",
      "finding": "HTTP endpoints found on port 8080",
      "remediation": "Configure TLS termination",
      "severity": "high"
    }
  ]
}

Control-Specific Checks

CP Domain (Control Plane)

# CP-01: Secure defaults
./ossasai-audit.sh --check CP-01
# Verifies: Security settings enabled by default

# CP-02: Permission model
./ossasai-audit.sh --check CP-02
# Verifies: Permission boundaries defined and enforced

# CP-03: Update integrity
./ossasai-audit.sh --check CP-03
# Verifies: Update signature verification enabled

# CP-04: Tamper detection
./ossasai-audit.sh --check CP-04
# Verifies: Configuration integrity monitoring

TB Domain (Tool Blast Radius)

# TB-01: Filesystem sandboxing
./ossasai-audit.sh --check TB-01
# Verifies: Filesystem scope restricted
# Tests: Path traversal, symlink escape

# TB-02: Command restrictions
./ossasai-audit.sh --check TB-02
# Verifies: Command allowlist enforced
# Tests: Shell injection, dangerous commands

# TB-03: Resource limits
./ossasai-audit.sh --check TB-03
# Verifies: CPU/memory/disk limits configured

NS Domain (Network Security)

# NS-01: TLS enforcement
./ossasai-audit.sh --check NS-01
# Verifies: TLS 1.2+ required, weak ciphers disabled

# NS-02: Certificate validation
./ossasai-audit.sh --check NS-02
# Verifies: Certificate chain validation enabled

# NS-03: API security
./ossasai-audit.sh --check NS-03
# Verifies: Authentication, rate limiting, headers

Additional Audit Commands

Dependency Scanning

# Generate SBOM
./ossasai-audit.sh --generate-sbom > sbom.json

# Scan for vulnerabilities
./ossasai-audit.sh --scan-vulnerabilities sbom.json

# Check lockfile integrity
./ossasai-audit.sh --verify-lockfiles

Secret Detection

# Scan for exposed secrets
./ossasai-audit.sh --scan-secrets

# Scan specific paths
./ossasai-audit.sh --scan-secrets --path ./src

Policy Validation

# Validate policy syntax
./ossasai-audit.sh --validate-policies

# Run policy tests
./ossasai-audit.sh --test-policies

# Check policy coverage
./ossasai-audit.sh --policy-coverage

CI/CD Integration

See CI/CD Integration for detailed examples.

# CI-friendly mode (exit codes)
./ossasai-audit.sh --level L2 --ci

# Exit codes:
# 0 = All controls pass
# 1 = One or more controls fail
# 2 = Error running audit

Troubleshooting

Audit script fails to run

- Verify bash is available - Check script permissions (`chmod +x`) - Verify dependencies (jq, curl)

False positives

- Update to latest audit script - Check configuration path is correct - Review control-specific documentation

Missing checks

- Ensure target level is specified - Verify configuration file exists - Check for audit script updates