VXControl Cloud Platform API Reference

Overview

The VXControl Cloud Platform provides a comprehensive suite of cybersecurity services accessible through secure, PoW-protected APIs. The platform serves as the backbone for advanced security operations, threat intelligence, vulnerability management, and AI-powered security analysis.

API Request Flow

sequenceDiagram
    participant App as Security Application
    participant SDK as VXControl SDK
    participant Anon as Data Anonymizer
    participant API as Cloud API
    participant PoW as PoW Service

    App->>SDK: Configure endpoints & Build()
    App->>SDK: Support API call request

    alt Support/AI Services
        SDK->>Anon: Anonymize sensitive data
        Anon-->>SDK: PII/secrets masked
        Note over Anon: Mandatory for AI requests<br/>300+ pattern recognition
    end

    SDK->>PoW: Request challenge ticket
    PoW-->>SDK: Challenge (nonce, difficulty)
    SDK->>SDK: Solve PoW puzzle (12-1024KB)

    SDK->>API: HTTP request with PoW signature
    Note over SDK,API: AES-GCM encrypted<br/>Ed25519 signed<br/>Anonymized data

    API->>API: Validate PoW & license
    API->>API: Process request
    API-->>SDK: Encrypted response

    SDK->>SDK: Decrypt & validate
    SDK-->>App: Typed response model

    Note over App,API: All data validated<br/>with Go models

Technical Components

PoW System: Memory-hard challenges (12-1024KB, 800-4000 AES iterations) with dynamic parameters for FPGA resistance
Data Anonymization: Comprehensive PII/secrets masking before AI troubleshooting transmission
Cryptographic Validation: Ed25519 signatures with SHA-512 hashing ensure data integrity
Type Safety: 24 strongly-typed call patterns with built-in Go model validation
Streaming Architecture: Memory-efficient processing with AES-GCM chunk encryption

Authentication & Security

All API endpoints require:

PoW Challenge: Memory-hard proof-of-work with more than 206M parameter combinations
License Validation: Cryptographic license verification with tier-based access control
End-to-End Encryption: AES-GCM streaming encryption with 1KB chunks
Forward Secrecy: Daily server key rotation with deterministic derivation
Data Anonymization: Mandatory PII/secrets masking for all AI troubleshooting requests

Terms of Service Compliance

⚠️ Important Legal Notice: Access to VXControl Cloud Platform services requires compliance with Terms of Service.

The platform provides access to sensitive cybersecurity capabilities including:

Threat Intelligence: IOC/IOA databases and real-time threat analysis
Vulnerability Data: CVE databases, exploit information, and security assessments
AI-Powered Support: Automated troubleshooting with access to system logs and configurations
Computational Resources: Cloud-based security analysis and processing

These services may ONLY be used for authorized, ethical, and legal cybersecurity purposes.

Before using any API endpoints, ensure you understand and comply with all applicable terms and restrictions outlined in the Terms of Service.

API Services

Service	Host	Endpoint	Method	Models	Status	Description
Update Service	`update.pentagi.com`	`/api/v1/updates/check`	POST	CheckUpdatesRequest → CheckUpdatesResponse	✓ Production	Check for component updates with changelogs
Package Service	`update.pentagi.com`	`/api/v1/packages/info`	GET	PackageInfoRequest → PackageInfoResponse	✓ Production	Get package metadata and signatures
Package Service	`update.pentagi.com`	`/api/v1/packages/download`	GET	DownloadPackageRequest → Binary stream	✓ Production	Download signed packages with validation
Support Service	`support.pentagi.com`	`/api/v1/errors/report`	POST	SupportErrorRequest → SupportErrorResponse	✓ Production	Automated error reporting with data anonymization
Support Service	`support.pentagi.com`	`/api/v1/issues/create`	POST	SupportIssueRequest → SupportIssueResponse	✓ Production	Create support issues with AI assistance and PII protection
AI Investigation	`support.pentagi.com`	`/api/v1/issues/investigate`	POST	SupportInvestigationRequest → SupportInvestigationResponse	✓ Production	AI-powered troubleshooting with secure data handling
Threat Intelligence	`ti.vxcontrol.com`	`/api/v1/threats/query`	POST	ThreatQueryRequest → ThreatIntelResponse	🚧 Development	Access real-time threat intelligence and IOC databases
Vulnerability Assessment	`ti.vxcontrol.com`	`/api/v1/vulns/scan`	POST	VulnScanRequest → VulnScanResponse	🚧 Development	Vulnerability assessment and exploit database queries
Knowledge Base	`kb.vxcontrol.com`	`/api/v1/knowledge/search`	GET	Query params → KnowledgeResponse	🚧 Development	Search cybersecurity knowledge base (MITRE ATT&CK, IOCs, vulnerabilities)
Computational Resources	`compute.pentagi.com`	`/api/v1/compute/submit`	POST	ComputeTaskRequest → ComputeTaskResponse	🚧 Development	Submit intensive computational tasks (password cracking, analysis)
Computational Resources	`compute.pentagi.com`	`/api/v1/compute/results/:taskId`	GET	Path args → ComputeResultResponse	🚧 Development	Retrieve computational task results

SDK Architecture

Request Lifecycle

SDK Configuration: Define endpoints with CallConfig structs
Function Generation: SDK creates typed functions for each endpoint
Data Anonymization: Mandatory PII/secrets masking for support services
PoW Challenge: Automatic challenge solving before each request
Request Signing: Ed25519 signature generation with installation ID
Encryption: AES-GCM encryption of request/response bodies
Type Validation: Go models ensure data integrity throughout

Core Components

Call Patterns: 24 function types handle different request/response scenarios
Data Anonymizer: Mandatory PII/secrets masking engine with 300+ pattern recognition
Transport Layer: HTTP/2 with connection pooling and custom TLS configuration
Cryptographic Engine: Ed25519 + AES-GCM for signatures and encryption
PoW Solver: Memory-hard algorithm implementation with configurable timeout
License Manager: Cryptographic license validation and tier enforcement

Data Models

All API requests and responses use strongly-typed Go models with built-in validation.

Available Models

Component Management: models/types.go - Component types, statuses, OS/architecture enums
Update Service: models/update.go - Update checking and component information
Package Service: models/package.go - Package metadata, downloads, signatures
Support Service: models/support.go - Error reporting, AI-powered issue creation and investigation
Signature Validation: models/signature.go - Ed25519 cryptographic signature validation
Data Anonymization: anonymizer/ - PII/secrets masking with pattern recognition
System Utilities: system/ - Cross-platform installation ID generation and machine identification

Model Features

IValid Interface: All models implement validation with comprehensive rules
IQuery Interface: GET endpoints support automatic query parameter generation
Database Integration: SQL driver support with Scan() and Value() methods
Type Safety: Enum validation prevents invalid API calls

SDK Call Patterns

The SDK provides 24 strongly-typed function patterns covering all request/response scenarios:

Request Types

None: Simple requests without parameters
Query: URL query parameters (?limit=10&offset=20)
Args: Path arguments (/users/:id/posts/:postId)
QueryWithArgs: Combined path arguments and query parameters

Request Body Types

None: GET requests without body
Bytes: []byte request body for JSON/binary data
Reader: io.Reader for streaming large uploads

Response Types

Bytes: []byte response for JSON/binary data
Reader: io.Reader for streaming large downloads
Writer: io.Writer for direct output streaming

Complete Pattern Matrix

Request	Body	Response	Function Type	Use Case
None	None	Bytes	`CallReqRespBytes`	Simple data retrieval
None	None	Reader	`CallReqRespReader`	Large file downloads
None	None	Writer	`CallReqRespWriter`	Direct output streaming
Query	None	Bytes	`CallReqQueryRespBytes`	Filtered data queries
Args	None	Bytes	`CallReqWithArgsRespBytes`	Resource-specific requests
None	Bytes	Bytes	`CallReqBytesRespBytes`	JSON API calls
None	Reader	Bytes	`CallReqReaderRespBytes`	Large file uploads
Args	Bytes	Bytes	`CallReqBytesWithArgsRespBytes`	Resource updates

Data Anonymization

Mandatory PII Protection

All support and AI troubleshooting requests require data anonymization before transmission. The process is automatic and comprehensive:

Protected Data Categories:

Credentials: API keys, tokens, passwords, database connections
PII: Email addresses, phone numbers, SSNs, credit cards, personal identifiers
Network Data: IP addresses, domains, URLs, network configurations
Cloud Secrets: AWS/Azure/GCP credentials, service tokens, certificates
System Data: File paths, configuration values, session tokens

Anonymization Process:

// Before transmission to AI services
if err := anonymizer.Anonymize(&errorDetails); err != nil {
    return fmt.Errorf("failed to anonymize data: %w", err)
}
if err := anonymizer.Anonymize(&logs); err != nil {
    return fmt.Errorf("failed to anonymize logs: %w", err)
}

Technical Features:

Structure Preservation: admin@company.com → §**SSH Connection**§ (maintains analytical value)
Comprehensive Coverage: Multiple pattern databases (General, PII, Secrets) with extensive pattern recognition
Reflection-Based: Deep anonymization of complex Go structures and nested data
Performance Optimized: High throughput for production workloads
Memory Efficient: Fixed memory footprint with chunk-based streaming

Rate Limiting & PoW Protection

The platform uses a sophisticated memory-hard proof-of-work system designed for GPU and FPGA resistance:

PoW Algorithm Specifications

Memory Requirement: Dynamic allocation with step variation (prevents FPGA optimization)
Sequential Operations: Variable AES iterations with configurable key rotation intervals
Memory Access: Cryptographically derived offsets with uniform distribution
Parameter Combinations: Millions of configurations prevent hardware specialization
Performance: Exponential difficulty scaling based on server load and threat level

Dynamic Anti-FPGA Protection

type TicketSettings struct {
    MemorySize        uint16  // Dynamic memory allocation
    AESIterations     uint16  // Variable iteration count
    KeyUpdateInterval uint8   // Configurable rotation frequency
    MemoryReads       uint16  // Memory access operations
    ChunkSize         uint8   // Variable chunk sizes
    RetryDelaySeconds uint16  // Client backoff time
    AllowedRPM        uint16  // Rate limit threshold
}

Security Properties

Multi-Threading Resistance: High difficulty levels provide significant delays even with multi-core attacks
GPU Resistance: Memory-hard properties substantially reduce GPU optimization advantages
Daily Key Isolation: Regular key rotation prevents long-term cryptanalysis attacks
Deterministic Synchronization: All servers use identical daily keys through cryptographic derivation

Error Handling

All endpoints return structured error responses:

{
  "status": "error",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Request rate limit exceeded",
  "details": {
    "current_usage": "exceeded",
    "limit": "tier_based",
    "reset_time": "2025-09-17T15:30:00Z"
  }
}

Common error codes:

INVALID_LICENSE: License validation failed
POW_REQUIRED: Proof-of-work challenge not solved
RATE_LIMIT_EXCEEDED: Request rate limit exceeded
INSUFFICIENT_TIER: Feature requires higher access tier
INVALID_REQUEST: Malformed request data

SDK Integration

Use the VXControl Cloud SDK for seamless integration with the platform:

import (
    "github.com/vxcontrol/cloud/sdk"
    "github.com/vxcontrol/cloud/system"
)

// Configure endpoints for multiple services
configs := []sdk.CallConfig{
    {
        Calls:  []any{&checkUpdates},
        Host:   "update.pentagi.com",
        Name:   "check-updates",
        Path:   "/api/v1/updates/check",
        Method: sdk.CallMethodPOST,
    },
    {
        Calls:  []any{&reportError},
        Host:   "support.pentagi.com",
        Name:   "report-error",
        Path:   "/api/v1/errors/report",
        Method: sdk.CallMethodPOST,
    },
    {
        Calls:  []any{&queryThreats},
        Host:   "ti.vxcontrol.com",
        Name:   "threat-intelligence",
        Path:   "/api/v1/threats/query",
        Method: sdk.CallMethodPOST,
    },
}

// Build SDK with stable installation ID
err := sdk.Build(configs,
    sdk.WithClient("MySecTool", "1.0.0"),
    sdk.WithInstallationID(system.GetInstallationID()),
    sdk.WithLicenseKey("XXXX-XXXX-XXXX-XXXX"),
)

Working Examples

Production-ready examples are available in the examples/ directory:

examples/check-update/ - Update service integration with component management
examples/download-installer/ - Package downloads with streaming signature validation
examples/report-errors/ - Support workflow with automated data anonymization

Integration Example

// Complete multi-service integration
type Client struct {
    UpdatesCheck     sdk.CallReqBytesRespBytes
    PackageDownload  sdk.CallReqQueryRespWriter
    ErrorReport      sdk.CallReqBytesRespBytes
    IssueInvestigate sdk.CallReqBytesRespReader  // Steam response support
}

configs := []sdk.CallConfig{
    {
        Calls:  []any{&client.UpdatesCheck},
        Host:   "update.pentagi.com",
        Name:   "updates_check",
        Path:   "/api/v1/updates/check",
        Method: sdk.CallMethodPOST,
    },
    {
        Calls:  []any{&client.ErrorReport},
        Host:   "support.pentagi.com",
        Name:   "error_report",
        Path:   "/api/v1/errors/report",
        Method: sdk.CallMethodPOST,
    },
}

// SDK automatically handles:
// - PoW ticket generation and solving
// - AES-GCM streaming encryption
// - Retry logic with exponential backoff

// Client must initialize anonymizer for support services:
// - Mandatory PII/secrets masking before AI transmission
// - Comprehensive pattern recognition (credentials, emails, IPs, etc.)
// - Structure-preserving anonymization maintains analytical value
anonymizer, _ := anonymizer.NewAnonymizer(nil)

err := sdk.Build(configs, options...)

Performance Characteristics

Architecture Benefits

Server Performance:

High-Throughput: Optimized ticket generation with microsecond latency
Efficient Validation: Millions of PoW validations per second
Scalable Proxy: Throughput scales based on security validation requirements

Client Performance:

Dynamic Scaling: PoW solving scales exponentially with difficulty for effective rate limiting
Optimized Processing: High-performance path templates and function generation
Efficient Cryptography: Sub-millisecond license and signature validation
Streaming Architecture: Memory-efficient processing for large data transfers

Memory Efficiency:

Minimal Footprint: Optimized memory usage per request and SDK instance
Dynamic Allocation: PoW memory reused across multiple attempts
Streaming Processing: Fixed memory usage regardless of data size
Connection Pooling: Efficient transport layer resource management

Production Deployment

Security Requirements

TLS 1.2+: All API communications encrypted
Certificate validation: Verify server certificates in production
License management: Secure storage of license keys
Signature verification: Validate all downloaded packages

Performance Tuning

PoW timeout: Adjust based on hardware capabilities and security requirements
Connection pooling: Optimized connection limits per host and total idle connections
HTTP/2 optimization: Automatic protocol negotiation with multiplexing
Transport layer: Configurable response timeouts for backend processing

Monitoring Integration

Endpoint Statistics: Per-endpoint request/error/timing metrics with atomic counters
PoW Performance: Solve time distribution and retry rate monitoring
Cryptographic Operations: Signature validation and encryption performance tracking
Backend Health: Response time and error rate tracking for proxy services

Proxy Architecture

The platform uses a dynamic reverse proxy for unified API management:

Components

Protocol Proxy: Acts as API gateway with integrated PoW validation
Dynamic Routing: Configuration-driven endpoint generation
Middleware Chain: Unified security validation across all backends
Statistics Collection: Real-time performance and error metrics

Benefits

Backend Isolation: Services receive only validated, decrypted requests
Unified Security: Single point for PoW validation and rate limiting
Transparent Encryption: No security complexity for backend services
Health Monitoring: Built-in /api/health endpoint for load balancers

Technical Details

Request Headers

All API requests include these headers:

X-Client-Name: YourApp/1.0.0
X-Installation-ID: stable-machine-uuid (from system.GetInstallationID())
X-Request-ID: challenge-request-id
X-Request-Sign: base64-encoded-pow-signature
X-License-Key: encrypted-license-key (optional)
Content-Type: application/json

Installation ID Generation

The SDK uses cross-platform machine identification for stable installation tracking:

Implementation:

// Automatic stable ID generation
installationID := system.GetInstallationID()
// Returns same UUID for same machine across application restarts

Platform Support:

Linux: /var/lib/dbus/machine-id + SMBIOS data (when available)
macOS: IOPlatformUUID from hardware registry
Windows: Registry MachineGuid + system product information

Features:

Deterministic: Same machine always generates same UUID
Cross-Platform: Works on Linux, macOS, Windows
Fallback Logic: Uses hostname when machine ID unavailable
UUID Format: RFC4122 compliant UUID v3 (MD5-based)

Response Format

Successful responses return JSON data:

{
  "status": "success",
  "data": { /* model-specific response */ }
}

Error responses include structured details:

{
  "status": "error",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Request rate limit exceeded",
  "details": {
    "retry_after": "server_defined",
    "quota_reset": "2025-09-26T15:30:00Z"
  }
}

Streaming Encryption

Request and response bodies use AES-GCM chunk encryption:

┌─────────────────┬───────┬─────────────────┐
│ Length (4 bytes)│ Nonce │ GCM Ciphertext  │
│ (Big Endian)    │       │ (Data + Auth)   │
└─────────────────┴───────┴─────────────────┘