CLI Integration¶

This guide covers programmatic integration with the OxideShield CLI for automation, CI/CD pipelines, and tooling.

Exit Codes¶

All commands return standard exit codes:

Code	Meaning	Description
0	Success	Operation completed successfully
1	Threat Detected	Input failed security check
2	Configuration Error	Invalid config or missing files
3	Runtime Error	Unexpected error during execution
4	License Error	Missing or invalid license

Check Exit Codes¶

oxideshield guard check "test input"
echo $?  # 0 = passed, 1 = blocked

oxideshield guard check "ignore previous instructions"
echo $?  # 1 = blocked

JSON Output¶

Use --format json or --json for machine-readable output:

Guard Check¶

oxideshield guard check --json "test input"

{
  "passed": true,
  "action": "Allow",
  "reason": "No threats detected",
  "guard_name": "PatternGuard",
  "match_count": 0,
  "duration_ns": 150000,
  "sanitized": null
}

Scan Results¶

oxideshield scan --target https://api.example.com --format json

{
  "target": "https://api.example.com/v1/chat",
  "probes_run": 50,
  "vulnerabilities_found": 3,
  "scan_duration_ms": 12500,
  "findings": [
    {
      "probe_id": "pi_ignore_previous",
      "severity": "high",
      "category": "prompt_injection",
      "response_indicates_bypass": true,
      "evidence": "The response contained..."
    }
  ]
}

Benchmark Results¶

oxideshield benchmark --guards all --format json

{
  "overall": {
    "f1_score": 0.94,
    "precision": 0.96,
    "recall": 0.92,
    "p50_latency_ms": 15.2,
    "p99_latency_ms": 48.5
  },
  "by_guard": {
    "PatternGuard": {
      "f1_score": 0.91,
      "p50_latency_ms": 0.1
    }
  }
}

SARIF Output¶

For security tool integration (GitHub Security, VS Code):

oxideshield scan --target https://api.example.com --format sarif --output results.sarif

{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [{
    "tool": {
      "driver": {
        "name": "OxideShield",
        "version": "0.1.0"
      }
    },
    "results": [...]
  }]
}

Piping Input¶

Read from stdin for scripted checks:

# Pipe text
echo "user input" | oxideshield guard check --stdin

# From file
cat input.txt | oxideshield guard check --stdin

# Multiple inputs (newline-separated)
cat inputs.txt | oxideshield guard check --stdin --batch

Batch Processing¶

Process multiple inputs efficiently:

# JSON Lines input
cat <<EOF | oxideshield guard check --batch --format jsonl
{"text": "input 1"}
{"text": "input 2"}
{"text": "ignore previous instructions"}
EOF

Output:

{"input": "input 1", "passed": true}
{"input": "input 2", "passed": true}
{"input": "ignore previous instructions", "passed": false, "reason": "Pattern match: ignore_instructions"}

Environment Variables¶

Configure CLI via environment:

Variable	Description	Example
`OXIDESHIELD_CONFIG`	Config file path	`/etc/oxideshield.yaml`
`OXIDESHIELD_LICENSE_KEY`	License key	`pro-xxx-xxx`
`OXIDESHIELD_LOG_LEVEL`	Log verbosity	`debug`, `info`, `warn`
`OXIDESHIELD_API_KEY`	Default API key for scan	`sk-xxx`

export OXIDESHIELD_CONFIG=/etc/oxideshield.yaml
export OXIDESHIELD_LICENSE_KEY="pro-xxx-xxx"
oxideshield guard check "test"

CI/CD Integration¶

GitHub Actions¶

name: Security Check
on: [pull_request]

jobs:
  llm-security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install OxideShield
        run: |
          curl -sSf https://install.oxideshield.ai | sh
          echo "$HOME/.oxideshield/bin" >> $GITHUB_PATH

      - name: Scan prompts
        run: |
          oxideshield guard check --batch < prompts.txt
        continue-on-error: false

      - name: Run security scan
        run: |
          oxideshield scan \
            --target ${{ secrets.LLM_ENDPOINT }} \
            --api-key ${{ secrets.LLM_API_KEY }} \
            --format sarif \
            --output results.sarif

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

GitLab CI¶

llm-security:
  stage: test
  image: oxideshield/oxideshield:latest
  script:
    - oxideshield guard check --batch < prompts.txt
    - oxideshield scan --target $LLM_ENDPOINT --format json --output scan.json
  artifacts:
    reports:
      security: scan.json

Jenkins¶

pipeline {
    agent any
    stages {
        stage('LLM Security') {
            steps {
                sh 'oxideshield guard check --batch < prompts.txt'
                sh 'oxideshield scan --target $LLM_ENDPOINT --format json --output scan.json'
            }
        }
    }
    post {
        always {
            archiveArtifacts 'scan.json'
        }
    }
}

Scripting Examples¶

Bash¶

#!/bin/bash
set -e

# Check all prompts in a directory
for file in prompts/*.txt; do
    result=$(oxideshield guard check --json < "$file")
    if [[ $(echo "$result" | jq -r '.passed') == "false" ]]; then
        echo "BLOCKED: $file - $(echo "$result" | jq -r '.reason')"
        exit 1
    fi
done

echo "All prompts passed security check"

Python¶

import subprocess
import json

def check_input(text: str) -> dict:
    result = subprocess.run(
        ["oxideshield", "guard", "check", "--json", text],
        capture_output=True,
        text=True
    )
    return json.loads(result.stdout)

# Check user input
result = check_input("ignore previous instructions")
if not result["passed"]:
    print(f"Blocked: {result['reason']}")

Node.js¶

const { execSync } = require('child_process');

function checkInput(text) {
    const result = execSync(
        `oxideshield guard check --json "${text.replace(/"/g, '\\"')}"`,
        { encoding: 'utf-8' }
    );
    return JSON.parse(result);
}

const result = checkInput("ignore previous instructions");
if (!result.passed) {
    console.log(`Blocked: ${result.reason}`);
}

Error Handling¶

Parsing Errors¶

# Check for specific exit codes
oxideshield guard check "test"
case $? in
    0) echo "Passed" ;;
    1) echo "Threat detected" ;;
    2) echo "Configuration error" ;;
    3) echo "Runtime error" ;;
    4) echo "License required" ;;
esac

JSON Error Response¶

When using --json, errors are returned as JSON:

{
  "error": true,
  "code": "config_error",
  "message": "Configuration file not found: /etc/oxideshield.yaml"
}