acuvity/risk-auditor repository overview

⁠

⁠ ⁠ ⁠

⁠🔍 What is Acuvity Risk Auditor?

Description: Comprehensive risk assessment tool for AI services with advanced reachability checks and security log processing

Packaged by Acuvity for risk auditing in customer environments. Features automated browser testing, TLS certificate analysis, and security log processing capabilities.

⁠💡 Why We Built This

At Acuvity⁠, understanding AI service accessibility and security posture is critical for our mission. The Acuvity Risk Auditor addresses this need by providing comprehensive risk auditing with optional security log correlation for AI services across customer networks.

⁠📚 Quick reference

Maintained by:

• the Acuvity team⁠ for packaging and security

Where to get help:

• Acuvity Support⁠

Supported host architectures:

• amd64 - natively
• arm64 - via emulation with --platform linux/amd64, chrome browser which is required for advanced tests doesn't have build for arm64 linux

Current supported version:

• container: latest

⁠Table of Contents

• 🚀 Quickstart⁠
• 🎯 Usage Modes⁠
• 🐳 Run it with Docker⁠
  • Mount Structure⁠
  • ⚙️ Command Line Options⁠
  • 📋 Examples⁠
    • Acuvity Knowledge Base Scanning⁠
    • Direct Domain Scanning⁠
    • Security Log Processing⁠
    • Custom CA Certificates⁠
  • 🔧 Advanced Configuration⁠
  • 📁 Output Files⁠
• 📝 Security Log Processing⁠
• 🔑 Environment Variables⁠

⁠🚀 Quickstart

# Set your Acuvity API token as environment variable first
export ACUVITY_TOKEN="your-token-here"

# Create directory structure
mkdir -p ./data/{input,output,logs}

# Optionally copy your security logs to input directory
cp your_security_logs.csv ./data/input/

# Run complete scan with security log processing and file output, leave out --security-log option if no logs are available
docker run --platform linux/amd64 --rm \
  -v "$(pwd)/data:/app/data" \
  -e ACUVITY_TOKEN \
  acuvity/risk-auditor:latest \
  --security-log /app/data/input/your_security_logs.csv \
  --output-dir /app/data/output \
  --log-file /app/data/logs/auditor.log

This example will:

• Scan domains from Acuvity's knowledge base + specified custom domains
• Process your security logs for correlation
• Save detailed results to ./data/output/
• Generate debug logs in ./data/logs/

⁠🎯 Usage Modes

The auditor supports three main operational modes which can be combined together. Results are automatically uploaded to Acuvity platform.

⁠Acuvity Knowledge Base Scanning

Scan domains from Acuvity's AI domains database.

⁠Direct Domain Scanning

Scan specific domains on top of domains from Acuvity's database. Use --domains to specify which domains to test.

⁠Security Log Processing

Process security logs to correlate with AI domain usage. Supports CSV format with automatic URL extraction. Have to be combined with either direct domains or Acuvity Knowledge Base domains.

⁠🐳 Run it with Docker

⁠Mount Structure

The container uses /app/data as the main data directory. Create the following local directory structure based on the features you want to use.

mkdir -p ./data/{input,output,logs,certs}

• ./data/input/ - Security log file
• ./data/output/ - Scan results
• ./data/logs/ - Application log files for debugging
• ./data/certs/ - Custom CA certificates (PEM format) to install in container if needed

⁠⚙️ Command Line Options

The auditor supports the following key options:

Custom Domain Sources:

• --domains domain1.com domain2.com - Scan specific domains directly

Input/Output:

• --output-dir /path/to/output - Save results to directory (enables file persistence)
• --security-log /path/to/security.csv - Process security log file for correlation

Testing Control:

• --timeout 15 - Network timeout in seconds (default: 10)
• --skip-advanced-tests - Disable browser-based testing

Logging:

• --log-level DEBUG - Set logging level (DEBUG, INFO, WARNING, ERROR)
• --log-file /path/to/auditor.log - Save logs to file

Metadata:
In metadata you can specify any number of key=value pairs:

• --metadata location=US team=QA

⁠📋 Examples

⁠Acuvity Knowledge Base Scanning

# Set your Acuvity API token as environment variable first
export ACUVITY_TOKEN="your-token-here"

# Acuvity Knowledge Base scan with console output (no mounts needed)
docker run --platform linux/amd64 --rm \
  -e ACUVITY_TOKEN \
  acuvity/risk-auditor:latest

# Acuvity Knowledge Base scan with file output
mkdir -p ./data/output
docker run --platform linux/amd64 --rm \
  -v "$(pwd)/data:/app/data" \
  -e ACUVITY_TOKEN \
  acuvity/risk-auditor:latest \
  --output-dir /app/data/output

⁠Direct Domain Scanning

# Set your Acuvity API token as environment variable first
export ACUVITY_TOKEN="your-token-here"
docker run --platform linux/amd64 --rm \
  -e ACUVITY_TOKEN \
  acuvity/risk-auditor:latest \
  --domains chatgpt.com openai.com anthropic.com


# Scan with file output and logging
export ACUVITY_TOKEN="your-token-here"
mkdir -p ./data/{output,logs}
docker run --platform linux/amd64 --rm \
  -v "$(pwd)/data:/app/data" \
  -e ACUVITY_TOKEN \
  acuvity/risk-auditor:latest \
  --domains chatgpt.com openai.com anthropic.com \
  --output-dir /app/data/output \
  --log-file /app/data/logs/auditor.log

⁠Security Log Processing

# Prepare security log file
mkdir -p ./data/input
cp your_security_logs.csv ./data/input/

# Process security logs with Acuvity Knowledge Base domains (set token first)
export ACUVITY_TOKEN="your-token-here"
mkdir -p ./data/{input,output}
docker run --platform linux/amd64 --rm \
  -v "$(pwd)/data:/app/data" \
  -e ACUVITY_TOKEN \
  acuvity/risk-auditor:latest \
  --security-log /app/data/input/your_security_logs.csv \
  --output-dir /app/data/output

# Process security logs with specific domains
export ACUVITY_TOKEN="your-token-here"
docker run --platform linux/amd64 --rm \
  -v "$(pwd)/data:/app/data" \
  -e ACUVITY_TOKEN \
  acuvity/risk-auditor:latest \
  --security-log /app/data/input/your_security_logs.csv \
  --domains chatgpt.com openai.com anthropic.com \
  --output-dir /app/data/output \

⁠Custom CA Certificates

# Copy CA certificates to local certs directory
cp /path/to/your/ca-certificates/*.pem ./data/certs/

# Run with custom CA certificates
export ACUVITY_TOKEN="your-token-here"
docker run --platform linux/amd64 --rm \
  -v "$(pwd)/data:/app/data" \
  -e ACUVITY_TOKEN \
  acuvity/risk-auditor:latest \
  --domains internal-domain.com \
  --output-dir /app/data/output

⁠🔧 Advanced Configuration

⁠Custom CA Certificate Support

For environments with custom certificate authorities, place PEM files in ./data/certs/ and the auditor will automatically install them in the container.

⁠📁 Output Files

The auditor generates the following output files in the specified output directory:

• results_<timestamp>.json: Main scan results in JSON format
• payload_<timestamp>.json: API payload format results

⁠📝 Security Log Processing

⁠Supported Log Formats

The auditor can process security logs in various CSV formats:

• Flexible Column Detection: Automatically tries to detect timestamp, URL, and user columns
• Best-effort URL Extraction: Uses regex patterns to find URLs in any text content
• Subdomain Matching: Automatically matches subdomains to parent domains

While some common header names can be automatically detected, for best results the log header names should be set to timestamp, username and destination_url for the URL the user was trying to reach. The log can contain any additional columns which will be ignored.

⁠URL Matching Logic

Examples of subdomain matching:

• https://files01.api.chatgpt.com/uploads matches domain: chatgpt.com
• https://api.openai.com/v1/chat matches domain: openai.com
• https://claude.ai/chat matches domain: claude.ai

⁠Sample Security Log Format

timestamp,source_ip,destination_url,username,action
2024-01-15T10:30:00Z,192.168.1.100,https://chatgpt.com/chat,john.doe,ALLOW
2024-01-15T10:31:00Z,192.168.1.101,https://api.openai.com/v1/completions,jane.smith,ALLOW

⁠🔑 Environment Variables

Required for Acuvity Knowledge Base scanning and uploads:

• ACUVITY_TOKEN: Bearer authentication token (required)
• ACUVITY_BASE_URL: API base URL - override option, by default it is extracted from token
• ACUVITY_NAMESPACE: Namespace header value - override option, by default it is extracted from token