CyberSec-CLI API Documentation

Table of Contents

All API requests require authentication using an API key passed in the Authorization header.

Getting an API Key

POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response:

{
  "success": true,
  "data": {
    "user_id": "usr_abc123",
    "api_key": "sk_live_abc123xyz789",
    "expires_at": "2025-12-31T23:59:59Z"
  }
}

Using API Keys

GET /api/v1/scans
Authorization: Bearer sk_live_abc123xyz789

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1640995200

When rate limited:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 3600 seconds.",
    "retry_after": 3600
  }
}

Response Format

Success Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "metadata": {
    "timestamp": "2024-02-06T12:00:00Z",
    "request_id": "req_abc123"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_TARGET",
    "message": "Target hostname is invalid",
    "details": {
      "field": "target",
      "value": "invalid..host"
    }
  },
  "metadata": {
    "timestamp": "2024-02-06T12:00:00Z",
    "request_id": "req_abc123"
  }
}

Error Codes

Endpoints

POST /api/v1/scans
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "target": "example.com",
  "scan_type": "tcp",
  "ports": "1-1000",
  "options": {
    "os_detection": true,
    "service_detection": true,
    "ssl_check": true,
    "fast_mode": false
  }
}

{
  "success": true,
  "data": {
    "scan_id": "scan_abc123",
    "status": "queued",
    "target": "example.com",
    "created_at": "2024-02-06T12:00:00Z",
    "estimated_duration": 120,
    "websocket_url": "ws://localhost:8000/ws/scans/scan_abc123",
    "sse_url": "http://localhost:8000/api/v1/scans/scan_abc123/stream"
  }
}

GET /api/v1/scans/{scan_id}
Authorization: Bearer {api_key}

{
  "success": true,
  "data": {
    "scan_id": "scan_abc123",
    "status": "running",
    "target": "example.com",
    "scan_type": "tcp",
    "progress": 45,
    "started_at": "2024-02-06T12:00:00Z",
    "estimated_completion": "2024-02-06T12:02:00Z",
    "results": {
      "open_ports": 12,
      "closed_ports": 433,
      "filtered_ports": 10
    }
  }
}

GET /api/v1/scans/{scan_id}/results
Authorization: Bearer {api_key}

{
  "success": true,
  "data": {
    "scan_id": "scan_abc123",
    "target": "example.com",
    "scan_type": "tcp",
    "started_at": "2024-02-06T12:00:00Z",
    "completed_at": "2024-02-06T12:02:15Z",
    "duration": 135,
    "summary": {
      "total_ports_scanned": 1000,
      "open_ports": 12,
      "closed_ports": 978,
      "filtered_ports": 10
    }
  }
}

GET /api/v1/scans
Authorization: Bearer {api_key}

DELETE /api/v1/scans/{scan_id}
Authorization: Bearer {api_key}

GET /api/v1/scans/{scan_id}/export
Authorization: Bearer {api_key}

DELETE /api/v1/scans/{scan_id}/results
Authorization: Bearer {api_key}

POST /api/v1/ai/ask
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "question": "What does an open SSH port on 22 mean for security?",
  "context": {
    "scan_id": "scan_abc123"
  }
}

POST /api/v1/ai/explain
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "concept": "port scanning",
  "level": "beginner"
}

POST /api/v1/ai/report
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "scan_id": "scan_abc123",
  "report_type": "executive",
  "include_sections": ["summary", "vulnerabilities", "recommendations"]
}

GET /api/v1/health

GET /api/v1/stats
Authorization: Bearer {api_key}

GET /api/v1/user/profile
Authorization: Bearer {api_key}

WebSocket API

Real-time bidirectional communication for live scan updates.

const ws = new WebSocket('ws://localhost:8000/ws/scans/scan_abc123?api_key=sk_live_abc123xyz789');

ws.onopen = () => {
  console.log('Connected to scan stream');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Scan update:', data);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('Disconnected from scan stream');
};

Server-Sent Events (SSE)

One-way real-time updates, simpler than WebSockets.

const eventSource = new EventSource('http://localhost:8000/api/v1/scans/scan_abc123/stream?api_key=sk_live_abc123xyz789');

eventSource.addEventListener('progress', (event) => {
  const data = JSON.parse(event.data);
  console.log('Progress:', data.progress);
});

eventSource.addEventListener('port_found', (event) => {
  const data = JSON.parse(event.data);
  console.log('Port found:', data.port);
});

eventSource.addEventListener('complete', (event) => {
  const data = JSON.parse(event.data);
  console.log('Scan complete');
  eventSource.close();
});

eventSource.onerror = (error) => {
  console.error('SSE error:', error);
  eventSource.close();
};

Code Examples

Python Example

import requests
import json

API_KEY = "sk_live_abc123xyz789"
BASE_URL = "http://localhost:8000/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{BASE_URL}/scans",
    headers=headers,
    json={
        "target": "example.com",
        "scan_type": "tcp",
        "ports": "1-1000",
        "options": {
            "service_detection": True,
            "ssl_check": True
        }
    }
)

scan_data = response.json()
scan_id = scan_data["data"]["scan_id"]
print(f"Scan started: {scan_id}")

JavaScript / Node.js Example

const axios = require('axios');

const API_KEY = 'sk_live_abc123xyz789';
const BASE_URL = 'http://localhost:8000/api/v1';

const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json'
};

async function scanTarget(target) {
  const scanResponse = await axios.post(`${BASE_URL}/scans`, {
    target,
    scan_type: 'tcp',
    ports: '1-1000',
    options: {
      service_detection: true,
      ssl_check: true
    }
  }, { headers });

  const scanId = scanResponse.data.data.scan_id;
  console.log(`Scan started: ${scanId}`);
}

cURL Examples

curl -X POST http://localhost:8000/api/v1/scans \
  -H "Authorization: Bearer sk_live_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "example.com",
    "scan_type": "tcp",
    "ports": "1-1000"
  }'

Best Practices

try:
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
except requests.exceptions.HTTPError as e:
    print(f"HTTP Error: {e.response.status_code}")
    print(f"Details: {e.response.json()}")

import time

retries = 0
max_retries = 5
backoff = 1

while retries < max_retries:
    try:
        response = requests.get(url, headers=headers)
        break
    except Exception as e:
        retries += 1
        time.sleep(backoff)
        backoff *= 2

response = requests.get(
    f"{BASE_URL}/scans?target=example.com&status=completed&sort=created_at&order=desc&per_page=1",
    headers=headers
)

Changelog