VulnTracker API: Automated Vulnerability Detection and Management

The VulnTracker API provides developers with programmatic access to comprehensive vulnerability scanning and management capabilities. This REST API enables integration of security scanning directly into development workflows, allowing teams to identify, track, and remediate vulnerabilities across their codebase and dependencies.

Getting Started

Before using the VulnTracker API, you'll need to create an account and obtain an API key.

Account Registration

curl -X POST https://api.aaido.dev/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "your-secure-password",
    "organization": "Your Company Name"
  }'

Upon successful registration, you'll receive an API key that must be included in all subsequent requests as a Bearer token in the Authorization header.

API Authentication

All API requests require authentication using your API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.aaido.dev/v1/products/vulntracker

Core Functionality

Initiating Vulnerability Scans

The primary function of VulnTracker is to scan codebases for known vulnerabilities. You can initiate scans by providing repository information or uploading code artifacts.

curl -X POST https://api.aaido.dev/v1/products/vulntracker/scans \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository_url": "https://github.com/username/project",
    "branch": "main",
    "scan_type": "comprehensive",
    "include_dependencies": true
  }'

Response:

{
  "scan_id": "scan_12345",
  "status": "initiated",
  "estimated_completion": "2024-01-15T10:30:00Z",
  "repository": "username/project",
  "branch": "main"
}

Checking Scan Status

Monitor scan progress using the scan ID:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.aaido.dev/v1/products/vulntracker/scans/scan_12345

Response:

{
  "scan_id": "scan_12345",
  "status": "completed",
  "started_at": "2024-01-15T10:15:00Z",
  "completed_at": "2024-01-15T10:28:00Z",
  "vulnerabilities_found": 7,
  "severity_breakdown": {
    "critical": 1,
    "high": 2,
    "medium": 3,
    "low": 1
  }
}

Retrieving Vulnerability Details

Get comprehensive information about discovered vulnerabilities:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.aaido.dev/v1/products/vulntracker/scans/scan_12345/vulnerabilities

Response:

{
  "vulnerabilities": [
    {
      "id": "vuln_001",
      "cve_id": "CVE-2023-12345",
      "severity": "critical",
      "component": "lodash",
      "version": "4.17.15",
      "description": "Prototype pollution vulnerability in lodash",
      "remediation": "Upgrade to version 4.17.21 or later",
      "file_path": "package.json",
      "confidence": "high"
    }
  ],
  "total_count": 7,
  "page": 1,
  "per_page": 20
}

Practical Use Cases

Use Case 1: Pre-commit Security Validation

Integrate VulnTracker into your pre-commit hooks to catch vulnerabilities before code reaches the main branch:

#!/bin/bash
# pre-commit-security-check.sh

# Create temporary scan for staged changes
RESPONSE=$(curl -s -X POST https://api.aaido.dev/v1/products/vulntracker/scans \
  -H "Authorization: Bearer $VULNTRACKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"repository_url\": \"$(git remote get-url origin)\",
    \"branch\": \"$(git branch --show-current)\",
    \"scan_type\": \"quick\"
  }")

SCAN_ID=$(echo $RESPONSE | jq -r '.scan_id')

# Wait for scan completion
while true; do
  STATUS=$(curl -s -H "Authorization: Bearer $VULNTRACKER_API_KEY" \
    https://api.aaido.dev/v1/products/vulntracker/scans/$SCAN_ID | jq -r '.status')

  if [ "$STATUS" = "completed" ]; then
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Security scan failed"
    exit 1
  fi

  sleep 5
done

# Check for critical vulnerabilities
CRITICAL_COUNT=$(curl -s -H "Authorization: Bearer $VULNTRACKER_API_KEY" \
  https://api.aaido.dev/v1/products/vulntracker/scans/$SCAN_ID | \
  jq '.severity_breakdown.critical')

if [ "$CRITICAL_COUNT" -gt 0 ]; then
  echo "Critical vulnerabilities found. Commit blocked."
  exit 1
fi

echo "Security scan passed"

Use Case 2: Dependency Monitoring

Set up automated monitoring for new vulnerabilities in project dependencies:

curl -X POST https://api.aaido.dev/v1/products/vulntracker/monitors \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository_url": "https://github.com/username/project",
    "monitor_type": "dependencies",
    "notification_webhook": "https://your-app.com/webhooks/security",
    "schedule": "daily",
    "severity_threshold": "medium"
  }'

Use Case 3: Security Reporting Dashboard

Generate comprehensive security reports for stakeholder communication:

# Get summary across all projects
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.aaido.dev/v1/products/vulntracker/reports/summary?period=30d" \
  | jq '{
    total_scans: .total_scans,
    vulnerabilities_by_severity: .severity_breakdown,
    trend: .vulnerability_trend,
    top_vulnerable_components: .top_components[0:5]
  }'

CI/CD Integration Example

Here's a complete GitHub Actions workflow that integrates VulnTracker into your deployment pipeline:

name: Security Scan with VulnTracker

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  security-scan:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v3

    - name: Initiate VulnTracker scan
      id: scan
      run: |
        RESPONSE=$(curl -X POST https://api.aaido.dev/v1/products/vulntracker/scans \
          -H "Authorization: Bearer ${{ secrets.VULNTRACKER_API_KEY }}" \
          -H "Content-Type: application/json" \
          -d '{
            "repository_url": "${{ github.server_url }}/${{ github.repository }}",
            "branch": "${{ github.ref_name }}",
            "scan_type": "comprehensive",
            "include_dependencies": true
          }')

        SCAN_ID=$(echo $RESPONSE | jq -r '.scan_id')
        echo "scan_id=$SCAN_ID" >> $GITHUB_OUTPUT

    - name: Wait for scan completion
      run: |
        while true; do
          RESPONSE=$(curl -s -H "Authorization: Bearer ${{ secrets.VULNTRACKER_API_KEY }}" \
            https://api.aaido.dev/v1/products/vulntracker/scans/${{ steps.scan.outputs.scan_id }})

          STATUS=$(echo $RESPONSE | jq -r '.status')

          if [ "$STATUS" = "completed" ]; then
            echo "Scan completed successfully"
            break
          elif [ "$STATUS" = "failed" ]; then
            echo "Scan failed"
            exit 1
          fi

          sleep 10
        done

    - name: Evaluate results
      run: |
        RESPONSE=$(curl -s -H "Authorization: Bearer ${{ secrets.VULNTRACKER_API_KEY }}" \
          https://api.aaido.dev/v1/products/vulntracker/scans/${{ steps.scan.outputs.scan_id }})

        CRITICAL=$(echo $RESPONSE | jq '.severity_breakdown.critical')
        HIGH=$(echo $RESPONSE | jq '.severity_breakdown.high')

        echo "Critical vulnerabilities: $CRITICAL"
        echo "High severity vulnerabilities: $HIGH"

        # Fail build if critical vulnerabilities found
        if [ "$CRITICAL" -gt 0 ]; then
          echo "Build failed due to critical vulnerabilities"
          exit 1
        fi

        # Warning for high severity (but don't fail build)
        if [ "$HIGH" -gt 0 ]; then
          echo "::warning::High severity vulnerabilities detected"
        fi

Best Practices

• Rate Limiting: The API enforces rate limits. Implement exponential backoff for production integrations.
• Webhook Integration: Use webhooks for long-running scans instead of polling.
• Caching: Cache scan results for unchanged codebases to avoid unnecessary API calls.
• Error Handling: Always implement proper error handling for network failures and API errors.

Conclusion

The VulnTracker API provides a robust foundation for integrating security scanning into modern development workflows. By automating vulnerability detection and providing detailed remediation guidance, teams can maintain security standards without sacrificing development velocity.

For complete API documentation and advanced features, visit the VulnTracker API documentation.