CI/CD Integration

Run OpenA2A security checks automatically in your CI/CD pipeline.

Key Flags for CI

FlagPurpose
--ciDisable interactive prompts. Exit with non-zero on failures.
--format jsonMachine-readable output for parsing.
--format sarifGitHub Code Scanning compatible output.
--quietSuppress non-essential output.

GitHub Actions

name: Security Checks
on:
  pull_request:
    branches: [main]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Security assessment
        run: npx opena2a-cli init --ci --format json > security-report.json

      - name: Credential check
        run: |
          npx opena2a-cli protect --dry-run --ci --format json > cred-report.json
          # Fail if any credentials found
          jq -e '.totalFound == 0' cred-report.json

      - name: Config integrity
        run: npx opena2a-cli guard verify --ci

      - name: Package verification
        run: npx opena2a-cli verify --ci --format json

GitLab CI

security-scan:
  image: node:20
  stage: test
  script:
    - npx opena2a-cli init --ci --format json > security-report.json
    - npx opena2a-cli protect --dry-run --ci --format json > cred-report.json
    - npx opena2a-cli guard verify --ci
    - npx opena2a-cli verify --ci --format json
  artifacts:
    reports:
      sast: security-report.json
    paths:
      - security-report.json
      - cred-report.json

SARIF Integration

Use SARIF output for GitHub Code Scanning integration:

- name: Security scan (SARIF)
  run: npx opena2a-cli scan --ci --format sarif > results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Recommended Pipeline Order

  1. opena2a init --ci - Assess project security posture
  2. opena2a protect --dry-run --ci - Check for hardcoded credentials
  3. opena2a guard verify --ci - Verify config file integrity
  4. opena2a verify --ci - Verify package integrity against registry
  5. opena2a scan --ci - Run security checks (if HackMyAgent is available)

Exit Codes

When using --ci, all commands follow a consistent exit code convention:

Exit CodeMeaning
0All checks passed. No critical findings.
1One or more critical findings detected, or the command failed to run.
2Configuration error (missing required flags, invalid arguments).

Full Pipeline Example

This GitHub Actions workflow runs the full security assessment pipeline. Each step is independent, so failures in one step do not prevent others from running. The final step uploads SARIF results to GitHub Code Scanning.

name: Full Security Pipeline
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      # Step 1: Trust score assessment
      - name: Security posture
        run: npx opena2a-cli init --ci --format json > posture.json
        continue-on-error: true

      # Step 2: Credential check (fail on any exposed secrets)
      - name: Credential scan
        run: npx opena2a-cli protect --dry-run --ci --format json > creds.json

      # Step 3: Config integrity
      - name: Guard verification
        run: npx opena2a-cli guard verify --ci
        continue-on-error: true

      # Step 4: Package integrity
      - name: Package verification
        run: npx opena2a-cli verify --ci --format json > verify.json
        continue-on-error: true

      # Step 5: Governance scan
      - name: SOUL.md compliance
        run: npx opena2a-cli scan-soul --ci --format json > soul.json
        continue-on-error: true

      # Step 6: HMA scan with SARIF for Code Scanning
      - name: Security scan (SARIF)
        run: npx opena2a-cli scan --ci --format sarif > results.sarif
        continue-on-error: true

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

JSON Output Format

With --format json, each command outputs a JSON object with consistent top-level fields. Use jq to extract specific values for pipeline decisions:

# Check trust score threshold
SCORE=$(npx opena2a-cli init --ci --format json | jq '.trustScore')
if [ "$SCORE" -lt 50 ]; then
  echo "Trust score $SCORE is below threshold"
  exit 1
fi

# Check for credential findings
CREDS=$(npx opena2a-cli protect --dry-run --ci --format json | jq '.totalFound')
if [ "$CREDS" -gt 0 ]; then
  echo "Found $CREDS exposed credentials"
  exit 1
fi

Related

CLI Overviewinitprotectreview