ElectricSheep API Reference

This document provides comprehensive API documentation for all ElectricSheep services, including authentication, endpoints, and integration guides.

Service APIs Overview

Service Base URL Authentication Documentation
Admin Dashboard https://admin.electricsheep.farm Session-based Admin API
OSCAL Compliance https://oscal.electricsheep.farm Session-based OSCAL API
AI Risk Assessment https://airisk.electricsheep.farm JWT Token AI Risk API
Security Agent https://aisecurity.electricsheep.farm API Key Security API

Authentication

Session-Based Authentication (Admin/OSCAL)

Login

POST /admin/login
Content-Type: application/json

{
  "username": "your_username",
  "password": "your_password"
}

Response:

{
  "success": true,
  "message": "Login successful",
  "user": {
    "id": 1,
    "username": "admin",
    "role": "administrator"
  }
}

Logout

POST /admin/logout

Check Authentication Status

GET /admin/user

JWT Token Authentication (AI Risk Assessment)

Obtain Token

POST /api/auth/login
Content-Type: application/json

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

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "role": "user"
  }
}

Using Token

Authorization: Bearer <access_token>

API Key Authentication (Security Agent)

X-API-Key: your_api_key_here

Admin Dashboard API

Base URL: https://admin.electricsheep.farm

System Monitoring

Get System Status

GET /api/system/status

Response:

{
  "status": "healthy",
  "services": {
    "database": "healthy",
    "redis": "healthy",
    "storage": "healthy"
  },
  "metrics": {
    "uptime": "7d 14h 32m",
    "cpu_usage": 45.2,
    "memory_usage": 68.1,
    "disk_usage": 32.7
  }
}

Get Service Health

GET /api/system/health/{service_name}

Get System Metrics

GET /api/system/metrics

User Management

List Users

GET /api/users

Create User

POST /api/users
Content-Type: application/json

{
  "username": "newuser",
  "email": "user@example.com",
  "password": "secure_password",
  "role": "user"
}

Update User

PUT /api/users/{user_id}
Content-Type: application/json

{
  "username": "updated_username",
  "email": "updated@example.com",
  "role": "admin"
}

Delete User

DELETE /api/users/{user_id}

Configuration Management

Get Configuration

GET /api/config

Update Configuration

PUT /api/config
Content-Type: application/json

{
  "setting_name": "setting_value",
  "another_setting": "another_value"
}

Log Management

Get Logs

GET /api/logs?level=error&limit=100&offset=0

Search Logs

GET /api/logs/search?query=error&start_date=2025-08-01&end_date=2025-08-25

OSCAL Compliance API

Base URL: https://oscal.electricsheep.farm

Assessment Management

List Assessments

GET /api/assessments

Response:

{
  "assessments": [
    {
      "id": 1,
      "name": "NIST CSF Assessment",
      "framework": "nist_csf",
      "status": "in_progress",
      "completion": 65.2,
      "created_date": "2025-08-01T00:00:00Z",
      "last_updated": "2025-08-25T10:30:00Z"
    }
  ],
  "total": 1
}

Create Assessment

POST /api/assessments
Content-Type: application/json

{
  "name": "SOC 2 Assessment",
  "framework": "soc2",
  "description": "Annual SOC 2 Type II assessment",
  "scope": ["security", "availability", "confidentiality"]
}

Get Assessment Details

GET /api/assessments/{assessment_id}

Update Assessment

PUT /api/assessments/{assessment_id}
Content-Type: application/json

{
  "name": "Updated Assessment Name",
  "status": "completed"
}

Delete Assessment

DELETE /api/assessments/{assessment_id}

Framework Management

List Available Frameworks

GET /api/frameworks

Response:

{
  "frameworks": [
    {
      "id": "nist_csf",
      "name": "NIST Cybersecurity Framework",
      "version": "1.1",
      "controls_count": 108,
      "categories": ["identify", "protect", "detect", "respond", "recover"]
    },
    {
      "id": "iso27001",
      "name": "ISO/IEC 27001:2013",
      "version": "2013",
      "controls_count": 114,
      "categories": ["organizational", "technical", "physical"]
    }
  ]
}

Get Framework Details

GET /api/frameworks/{framework_id}

Get Framework Controls

GET /api/frameworks/{framework_id}/controls

Control Assessment

Get Control Details

GET /api/controls/{control_id}

Update Control Assessment

PUT /api/controls/{control_id}/assessment
Content-Type: application/json

{
  "implementation_status": "implemented",
  "maturity_level": 3,
  "evidence": [
    {
      "type": "document",
      "name": "Security Policy",
      "url": "/evidence/security-policy.pdf"
    }
  ],
  "notes": "Control fully implemented with documented procedures"
}

Evidence Management

Upload Evidence

POST /api/evidence
Content-Type: multipart/form-data

file: [binary file data]
control_id: "AC-1"
description: "Access Control Policy Document"

List Evidence

GET /api/evidence?control_id=AC-1

Download Evidence

GET /api/evidence/{evidence_id}/download

Gap Analysis

Generate Gap Analysis

POST /api/assessments/{assessment_id}/gap-analysis

Response:

{
  "summary": {
    "total_controls": 108,
    "implemented": 65,
    "partially_implemented": 23,
    "not_implemented": 20,
    "overall_maturity": 2.3
  },
  "gaps": [
    {
      "control_id": "PR.AC-1",
      "control_name": "Access Control Policy",
      "current_status": "not_implemented",
      "priority": "high",
      "recommendations": ["Develop access control policy", "Implement access controls"]
    }
  ]
}

Reporting

Generate Report

POST /api/assessments/{assessment_id}/report
Content-Type: application/json

{
  "format": "pdf",
  "template": "executive_summary",
  "include_evidence": true
}

Download Report

GET /api/reports/{report_id}/download

AI Risk Assessment API

Base URL: https://airisk.electricsheep.farm

Risk Assessment

Create Risk Assessment

POST /api/v1/assessments
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "AI Model Risk Assessment",
  "model_type": "classification",
  "use_case": "customer_scoring",
  "data_sources": ["customer_data", "transaction_history"],
  "deployment_environment": "production"
}

List Assessments

GET /api/v1/assessments
Authorization: Bearer <token>

Get Assessment Results

GET /api/v1/assessments/{assessment_id}/results
Authorization: Bearer <token>

Model Analysis

Analyze Model

POST /api/v1/models/analyze
Authorization: Bearer <token>
Content-Type: application/json

{
  "model_file": "base64_encoded_model",
  "model_type": "neural_network",
  "analysis_type": ["bias", "fairness", "explainability"]
}

Get Analysis Results

GET /api/v1/models/{model_id}/analysis
Authorization: Bearer <token>

Bias Detection

Run Bias Analysis

POST /api/v1/bias/analyze
Authorization: Bearer <token>
Content-Type: application/json

{
  "dataset": "base64_encoded_data",
  "protected_attributes": ["gender", "race", "age"],
  "target_variable": "outcome"
}

Fairness Metrics

Calculate Fairness Metrics

POST /api/v1/fairness/metrics
Authorization: Bearer <token>
Content-Type: application/json

{
  "predictions": [0, 1, 0, 1, 1],
  "ground_truth": [0, 1, 1, 1, 0],
  "protected_groups": ["A", "B", "A", "B", "A"],
  "metrics": ["demographic_parity", "equalized_odds"]
}

Security Agent API

Base URL: https://aisecurity.electricsheep.farm (Coming Soon)

Threat Detection

Submit Event for Analysis

POST /api/v1/events
X-API-Key: your_api_key
Content-Type: application/json

{
  "timestamp": "2025-08-25T10:30:00Z",
  "source": "web_application",
  "event_type": "login_attempt",
  "details": {
    "user": "admin",
    "ip_address": "192.168.1.100",
    "user_agent": "Mozilla/5.0..."
  }
}

Get Threat Intelligence

GET /api/v1/threats?severity=high&status=active
X-API-Key: your_api_key

Monitoring

Get Security Metrics

GET /api/v1/metrics
X-API-Key: your_api_key

Get Alerts

GET /api/v1/alerts?limit=50&status=open
X-API-Key: your_api_key

Webhooks

OSCAL Compliance Webhooks

Register webhook endpoints to receive notifications:

Assessment Completion

{
  "event": "assessment.completed",
  "assessment_id": 123,
  "framework": "nist_csf",
  "completion_date": "2025-08-25T10:30:00Z",
  "overall_score": 85.2
}

Control Status Change

{
  "event": "control.status_changed",
  "control_id": "PR.AC-1",
  "old_status": "not_implemented",
  "new_status": "implemented",
  "assessment_id": 123
}

AI Risk Assessment Webhooks

Analysis Complete

{
  "event": "analysis.completed",
  "model_id": "model_123",
  "analysis_type": "bias_detection",
  "results": {
    "bias_detected": true,
    "severity": "medium"
  }
}

Rate Limiting

All APIs implement rate limiting:

  • Standard endpoints: 100 requests per minute
  • Heavy computation endpoints: 10 requests per minute
  • File upload endpoints: 50 requests per hour

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1693123456

Error Handling

Standard error response format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    }
  },
  "timestamp": "2025-08-25T10:30:00Z",
  "request_id": "req_123456"
}

Common HTTP Status Codes

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 422 - Validation Error
  • 429 - Rate Limit Exceeded
  • 500 - Internal Server Error

SDKs and Client Libraries

Python SDK

pip install electricsheep-sdk

from electricsheep import ElectricSheepClient

client = ElectricSheepClient(
    api_key="your_api_key",
    base_url="https://admin.electricsheep.farm"
)

# Get system status
status = client.system.get_status()
print(status)

JavaScript SDK

npm install electricsheep-js

import { ElectricSheepClient } from 'electricsheep-js';

const client = new ElectricSheepClient({
  apiKey: 'your_api_key',
  baseURL: 'https://admin.electricsheep.farm'
});

// Get assessments
const assessments = await client.assessments.list();
console.log(assessments);

Integration Examples

OSCAL Compliance Integration

# Complete compliance assessment workflow
import electricsheep

client = electricsheep.OSCALClient()

# Create assessment
assessment = client.assessments.create({
    "name": "Q3 Compliance Review",
    "framework": "nist_csf"
})

# Upload evidence
evidence = client.evidence.upload(
    file_path="security_policy.pdf",
    control_id="PR.AC-1"
)

# Generate report
report = client.reports.generate(
    assessment_id=assessment.id,
    format="pdf"
)

AI Risk Assessment Integration

// AI bias detection workflow
const client = new ElectricSheepClient();

// Analyze model for bias
const analysis = await client.models.analyzeBias({
  modelData: modelFile,
  protectedAttributes: ['gender', 'race'],
  threshold: 0.05
});

if (analysis.biasDetected) {
  console.log('Bias detected:', analysis.details);
}

For more detailed examples and use cases, refer to the individual service documentation and GitHub repositories.