Skip to Content
Alprina is in active development. Join us in building the future of security scanning.
CLI Referencealprina scan

alprina scan

Run AI-powered security scans on local files, directories, URLs, or IP addresses. The scan command is the core of Alprina, using AI agents to detect vulnerabilities and security issues.

Synopsis

alprina scan <target> [OPTIONS]

Description

The scan command performs security analysis on the specified target. It automatically detects whether the target is local (file/directory) or remote (URL/IP) and applies appropriate scanning techniques.

Key Features:

  • Local Scanning: No authentication required for files/directories
  • Remote Scanning: Requires authentication for URLs and IPs
  • AI-Powered: Uses intelligent agents for deep analysis
  • Safe by Default: Only runs non-intrusive scans unless configured otherwise
  • Multiple Profiles: Customize scanning behavior with profiles

Arguments

<target> (Required)

The target to scan. Can be:

Local Targets:

  • Single file: app.py, config.yaml
  • Directory: ./src, /path/to/project
  • Current directory: .

Remote Targets (requires auth):

  • URL: https://api.example.com
  • Domain: example.com
  • IP address: 192.168.1.1

Options

Core Options

--profile, -p <profile>

Scan profile to use. Profiles determine what checks are run and how thorough the scan is.

Default: default

Available Profiles:

ProfileDescriptionUse Case
defaultStandard security scanDaily development, quick checks
code-auditDeep static code analysisPre-release, security audits
web-reconWeb application reconnaissanceAPI testing, penetration testing
api-securityAPI endpoint security testingREST API validation

Examples:

# Standard scan
alprina scan ./src
 
# Deep code audit
alprina scan ./src --profile code-audit
 
# Web reconnaissance
alprina scan https://api.example.com --profile web-recon
 
# API security testing
alprina scan https://api.example.com/v1 --profile api-security

--safe-only

Only run safe, non-intrusive scans. When enabled, Alprina will not attempt any actions that could modify data or trigger security alerts.

Default: true

Examples:

# Safe scans only (default)
alprina scan 192.168.1.1 --safe-only
 
# Allow potentially intrusive scans
alprina scan 192.168.1.1 --safe-only=false

Note: Disabling safe-only mode requires explicit confirmation and is only available with proper authorization.

--output, -o <file>

Save scan results to a file.

Format: Automatically detected from file extension (.json, .html, .txt)

Examples:

# Save as JSON
alprina scan ./src --output results.json
 
# Save as HTML
alprina scan ./src --output report.html
 
# Save to specific path
alprina scan ./src --output ~/scans/$(date +%Y%m%d).json

Global Flags

These flags work with all commands:

--verbose, -v

Enable verbose output with detailed logging.

alprina scan ./src --verbose

--debug

Enable debug mode with maximum logging detail.

alprina scan ./src --debug

Scan Profiles Deep Dive

default Profile

Standard security scan for daily development.

What it checks:

  • Hardcoded secrets (API keys, passwords)
  • Common vulnerabilities (SQL injection, XSS)
  • Dependency vulnerabilities
  • Basic security misconfigurations

Speed: Fast (2-5 minutes for medium projects)

Best for: Daily development, pre-commit checks

alprina scan ./src

code-audit Profile

Comprehensive deep analysis for security audits.

What it checks:

  • All items from default profile
  • Complex data flow analysis
  • Authentication/authorization flaws
  • Cryptographic issues
  • Business logic vulnerabilities
  • OWASP Top 10

Speed: Thorough (10-30 minutes for medium projects)

Best for: Pre-release audits, security reviews, compliance

alprina scan ./src --profile code-audit

web-recon Profile

Web application reconnaissance and discovery.

What it checks:

  • Subdomain enumeration (passive)
  • Technology stack detection
  • SSL/TLS configuration
  • Security headers
  • Exposed endpoints
  • Directory enumeration (safe)

Speed: Medium (5-15 minutes)

Best for: External security assessment, penetration testing prep

Requires: Authentication

alprina scan https://example.com --profile web-recon

api-security Profile

API endpoint security testing.

What it checks:

  • Authentication mechanisms
  • Authorization bypass attempts
  • Input validation
  • Rate limiting
  • CORS misconfigurations
  • API-specific vulnerabilities

Speed: Medium (5-15 minutes)

Best for: API security testing, REST API validation

Requires: Authentication

alprina scan https://api.example.com --profile api-security

Output Formats

Terminal Output (Default)

Human-readable output with colors and formatting.

alprina scan ./src

Example output:

🛡️  Alprina Security Scan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 Starting scan on: ./src
Profile: default
Mode: Safe only

→ Detected local target: ./src
→ Scanning local files...

✓ Scan complete!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Results Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Found 3 findings:

  🔴 HIGH: Hardcoded API key detected
     File: src/config.py:12
     API_KEY = "sk_live_1234567890abcdef"

  🟡 MEDIUM: SQL injection vulnerability
     File: src/database.py:45
     query = f"SELECT * FROM users WHERE id = {user_id}"

  🟢 LOW: Outdated dependency
     Package: requests 2.25.0 (latest: 2.31.0)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 Run 'alprina mitigate' for fix suggestions
📊 Run 'alprina report' to generate detailed report

JSON Output

Machine-readable format for CI/CD integration.

alprina scan ./src --output results.json

Example structure:

{
  "scan_id": "scan_2024_11_03_abc123",
  "timestamp": "2024-11-03T10:30:00Z",
  "target": "./src",
  "profile": "default",
  "summary": {
    "total_findings": 3,
    "high": 1,
    "medium": 1,
    "low": 1
  },
  "findings": [
    {
      "id": "VULN-2024-001",
      "severity": "HIGH",
      "title": "Hardcoded API key detected",
      "description": "API key found in source code",
      "file": "src/config.py",
      "line": 12,
      "code_snippet": "API_KEY = \"sk_live_1234567890abcdef\"",
      "recommendation": "Move to environment variables"
    }
  ]
}

Examples

Basic Examples

Scan current directory:

alprina scan .

Scan specific directory:

alprina scan ./src

Scan single file:

alprina scan app.py

Profile Examples

Quick daily check:

alprina scan ./src

Pre-release security audit:

alprina scan ./src --profile code-audit --output audit-report.json

Web app security assessment:

alprina auth login
alprina scan https://staging.example.com --profile web-recon

API endpoint testing:

alprina scan https://api.example.com/v1 --profile api-security

CI/CD Examples

GitHub Actions:

# Fail build on HIGH severity
alprina scan ./src --output results.json
if [ $? -eq 10 ]; then
  echo "HIGH severity vulnerabilities found!"
  exit 1
fi

GitLab CI:

security_scan:
  script:
    - pip install alprina-cli
    - alprina auth login --api-key $ALPRINA_API_KEY
    - alprina scan ./src --output report.json
  artifacts:
    reports:
      alprina: report.json

Jenkins:

stage('Security Scan') {
  steps {
    sh 'pip install alprina-cli'
    sh 'alprina scan ./src --output results.json'
    archiveArtifacts artifacts: 'results.json'
  }
}

Advanced Examples

Scan with verbose output:

alprina scan ./src --verbose

Save results with timestamp:

alprina scan ./src --output "scan-$(date +%Y%m%d-%H%M%S).json"

Scan multiple targets sequentially:

alprina scan ./frontend --output frontend-results.json
alprina scan ./backend --output backend-results.json
alprina scan ./api --output api-results.json

Exit Codes

Alprina uses specific exit codes for CI/CD integration:

CodeMeaningDescription
0SuccessNo vulnerabilities found
1General errorScan failed due to error
2Authentication requiredRemote scan needs auth
3Policy violationTarget blocked by policy
10HIGH severity foundAt least one HIGH finding
130User cancelledCtrl+C pressed

Use in scripts:

alprina scan ./src
EXIT_CODE=$?
 
if [ $EXIT_CODE -eq 0 ]; then
  echo "✓ No vulnerabilities found"
elif [ $EXIT_CODE -eq 10 ]; then
  echo "✗ HIGH severity vulnerabilities detected"
  exit 1
else
  echo "✗ Scan failed with code $EXIT_CODE"
  exit $EXIT_CODE
fi

Local vs Remote Scanning

Local Scanning

No authentication required. Scans files and directories on your machine.

Advantages:

  • Works offline
  • No API key needed
  • Fast performance
  • Private - data stays local

Examples:

# Scan project directory
alprina scan ./my-project
 
# Scan specific file
alprina scan config.py
 
# Scan current directory
alprina scan .

What it checks:

  • Source code vulnerabilities
  • Hardcoded secrets
  • Dependency vulnerabilities
  • Security misconfigurations
  • Code quality issues

Remote Scanning

Requires authentication. Scans URLs, domains, and IP addresses.

Prerequisites:

# Login first
alprina auth login --api-key YOUR_API_KEY

Advantages:

  • External security assessment
  • Production environment testing
  • API security validation
  • SSL/TLS analysis

Examples:

# Scan public API
alprina scan https://api.example.com
 
# Scan with specific profile
alprina scan https://example.com --profile web-recon
 
# Scan IP address
alprina scan 192.168.1.1 --safe-only

What it checks:

  • Web application vulnerabilities
  • API security issues
  • SSL/TLS configuration
  • Security headers
  • Exposed services
  • Technology stack

Performance Tips

For Large Codebases

Use specific directories:

# Instead of scanning everything
alprina scan ./
 
# Scan specific modules
alprina scan ./src
alprina scan ./api

Run in parallel:

# In separate terminals or CI jobs
alprina scan ./frontend --output frontend.json &
alprina scan ./backend --output backend.json &
wait

For CI/CD

Cache dependencies:

# GitHub Actions
- uses: actions/cache@v3
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}

Use appropriate profiles:

# Fast checks on every commit
alprina scan ./src
 
# Deep audit weekly
alprina scan ./src --profile code-audit

Troubleshooting

”Command not found”

Issue: alprina: command not found

Solution:

# Verify installation
pip show alprina-cli
 
# Add to PATH
export PATH="$HOME/.local/bin:$PATH"

“Authentication required”

Issue: Remote scans fail with auth error

Solution:

# Login first
alprina auth login --api-key YOUR_KEY
 
# Verify auth status
alprina auth status

“Target blocked by policy”

Issue: Scan fails with policy violation

Solution:

# Check policy
cat alprina-policy.yaml
 
# Test target
alprina policy test your-target
 
# Update policy or use different target

Slow scan performance

Issue: Scans take too long

Solution:

# Use faster profile
alprina scan ./src
 
# Scan specific directories
alprina scan ./src/critical
 
# Check for large files
du -sh ./* | sort -hr | head -10

See Also

--quick, -q

Run a quick 5-second scan focusing only on critical security issues. Perfect for fast feedback during development.

Default: false

Examples:

# Quick scan for critical issues only
alprina scan . --quick
 
# Quick scan of specific file
alprina scan app.py --quick

What it checks:

  • Hardcoded secrets and API keys
  • Critical SQL injection patterns
  • Remote code execution vulnerabilities
  • Known critical CVEs

Use cases:

  • Pre-commit hooks
  • Fast CI/CD checks
  • IDE integration
  • Development workflow

--container

Scan a Docker container image for vulnerabilities.

Default: false

Examples:

# Scan local Docker image
alprina scan nginx:latest --container
 
# Scan specific image version
alprina scan myapp:v1.2.3 --container
 
# Scan image from registry
alprina scan docker.io/library/postgres:14 --container

What it checks:

  • Vulnerable packages in container layers
  • Misconfigurations in Dockerfile
  • Exposed secrets in environment variables
  • Security best practices violations
  • Known CVEs in base images

--agent, -a <agent>

Specify which security agent(s) to use for the scan. Can be used multiple times to run multiple agents.

Examples:

# Use Red Team agent
alprina scan api.example.com --agent red_teamer
 
# Use multiple agents
alprina scan ./src --agent code_security --agent guardrails
 
# Use specific agent for Android app
alprina scan app.apk --agent android_sast

Available Agents:

  • red_teamer - Offensive penetration testing
  • blue_teamer - Defensive security assessment
  • code_security - Source code vulnerability scanning
  • network_analyzer - Network security analysis
  • android_sast - Android app security testing
  • dfir - Digital forensics and incident response
  • memory_analysis - Memory forensics
  • reverse_engineer - Binary analysis
  • wifi_security - Wireless penetration testing
  • replay_attack - Protocol replay detection
  • subghz_sdr - RF and Sub-GHz analysis
  • retester - Remediation verification
  • mail - Email security analysis
  • guardrails - Safety and compliance checking
  • llm_security - LLM application security

See Security Agents for detailed information about each agent.

--verbose, -v

Show detailed output during the scan, including debug information and progress updates.

Default: false

Examples:

# Verbose output
alprina scan ./src --verbose
 
# Combine with other options
alprina scan ./src --profile code-audit --verbose

What you see with verbose:

  • File-by-file scan progress
  • Agent initialization details
  • LLM request/response info
  • Detailed finding explanations
  • Performance metrics
Last updated on
alprina quickstartConfiguration