What Are REST API Handlers in CyberStrikeAI? A Deep Dive into the Gin-Based HTTP Layer

REST API Handlers in CyberStrikeAI are Go structs and methods that bridge HTTP routes to internal business logic, handling request validation, service orchestration, and JSON responses within a Gin framework.

CyberStrikeAI exposes its core functionality—vulnerability management, skill execution, role configuration, and robot session control—through a standardized HTTP interface. The REST API Handlers serve as the primary entry point for this interaction, translating incoming requests from front-end clients, bots, and external tools into domain-specific operations while maintaining clean separation from database and execution layers.

Core Responsibilities of REST API Handlers

The handler layer in internal/handler/ encapsulates five critical concerns that define the system's public contract.

Route Mapping and Context Handling

Each handler method registers with the Gin router in cmd/server/main.go to map specific URL patterns to executable functions. For example, router.POST("/vulnerabilities", h.CreateVulnerability) binds the creation endpoint to the corresponding handler method, which receives a *gin.Context object containing request metadata and response writers.

Request Validation and Data Binding

Handlers enforce type safety by using Gin’s built-in binding mechanisms. Methods like CreateVulnerability in internal/handler/vulnerability.go call c.ShouldBindJSON to deserialize incoming payloads into strongly-typed Go structs, while query parameters for pagination (e.g., limit=10&offset=0) are parsed automatically from the URL context.

Service Orchestration

Rather than embedding business logic directly, handlers delegate to specialized internal services. You will see references to h.db.* for database operations, h.manager.* for skill lifecycle management, and h.agentHandler.* for robot agent interactions. This delegation pattern keeps the REST layer thin and focused on transport concerns.

Structured Response Generation

All handlers return JSON responses using c.JSON(http.StatusOK, …) or appropriate error codes. Success payloads include serialized domain objects, while error paths return standardized HTTP status codes with descriptive messages, ensuring predictable client-side handling.

Observability and Logging

The handlers integrate Zap for structured logging, capturing request outcomes, processing durations, and error traces. This logging strategy supports debugging and operational monitoring without cluttering the core business logic.

Key Handler Components and File Structure

The REST API layer is organized into domain-specific files that group related endpoints:

• internal/handler/vulnerability.go: Implements CreateVulnerability (lines 40-69) and ListVulnerabilities (lines 94-119) for CRUD operations on security findings, including severity tracking and proof-of-concept storage.

• internal/handler/skills.go: Manages the skill registry through GetSkill (lines 65-78) and CreateSkill (lines 30-60), enabling dynamic loading of penetration testing capabilities like Nmap scans or port detection.

• internal/handler/role.go: Provides endpoints for role definition and skill-to-role binding, separating permission management from execution logic.

• internal/handler/robot.go: Contains cmdSwitch (lines 227-241) and related methods that process incoming messages from enterprise chat platforms (DingTalk, Lark), routing them to the AI agent for contextual processing.

• internal/handler/terminal.go: Exposes system command execution via HTTP, supporting both synchronous and streaming response modes for real-time terminal interaction.

• internal/mcp/server.go: Registers internal tool handlers that extend the REST API surface area, particularly for Model Context Protocol (MCP) integrations that expose skill execution as callable endpoints.

Practical API Usage Examples

The following curl commands demonstrate how external clients interact with the handler endpoints. Replace localhost:8080 with your deployed instance address.

Creating a Vulnerability Record

curl -X POST http://localhost:8080/api/v1/vulnerabilities \
  -H "Content-Type: application/json" \
  -d '{
        "conversation_id":"conv-123",
        "title":"SQL Injection",
        "description":"User input not escaped",
        "severity":"high",
        "status":"open",
        "type":"web",
        "target":"http://example.com/login",
        "proof":"' OR '1'='1",
        "impact":"Data breach",
        "recommendation":"Use prepared statements"
      }'

This request targets the CreateVulnerability handler in internal/handler/vulnerability.go, which validates the payload against the vulnerability schema before persisting to the database.

Retrieving Paginated Vulnerability Lists

curl "http://localhost:8080/api/v1/vulnerabilities?limit=10&offset=0"

The ListVulnerabilities handler parses the query parameters to implement cursor-based pagination, returning a subset of records to optimize front-end performance.

Managing Security Skills

Retrieve a specific skill definition:

curl http://localhost:8080/api/v1/skills/port-scan

Create a new reusable skill template:

curl -X POST http://localhost:8080/api/v1/skills \
  -H "Content-Type: application/json" \
  -d '{
        "name":"nmap-scan",
        "description":"Run an Nmap scan",
        "content":"nmap -sV {{target}}"
      }'

These endpoints interact with internal/handler/skills.go, specifically the GetSkill and CreateSkill methods.

Robot Role Switching

For chatbot integrations, switch a user’s operational role:

curl -X POST http://localhost:8080/api/v1/robot/cmd/switch \
  -H "Content-Type: application/json" \
  -d '{"platform":"dingtalk","user_id":"U12345","role":"渗透测试"}'

This invokes cmdSwitch in internal/handler/robot.go, which updates the session context for AI agent interactions.

Router Initialization and Handler Wiring

The connection between HTTP routes and handler methods occurs in cmd/server/main.go, where the application instantiates handler structs with their dependencies (database connections, skill managers, and agent handlers) and registers them with the Gin engine. This centralized wiring configuration ensures that middleware chains—authentication, CORS, and logging—wrap the REST API Handlers consistently across all endpoints.

Summary

• REST API Handlers act as the HTTP transport layer for CyberStrikeAI, built on the Gin framework and located in internal/handler/.
• Five primary duties: route mapping, request validation (c.ShouldBindJSON), service delegation (h.db.*, h.manager.*), JSON response generation (c.JSON), and structured logging with Zap.
• Domain-specific files organize endpoints logically: vulnerability.go for security findings, skills.go for capability management, robot.go for chatbot integration, and terminal.go for command execution.
• Clean architecture separates transport concerns from business logic, with handlers depending on internal services rather than direct database implementation details.

Frequently Asked Questions

How do REST API Handlers validate incoming request data?

Handlers use Gin’s c.ShouldBindJSON method to automatically unmarshal and validate JSON payloads against Go struct definitions. If validation fails, the handler returns an HTTP 400 error with details before any business logic executes.

What is the difference between the handlers in internal/handler/ and the MCP server?

The files in internal/handler/ implement standard REST endpoints for direct HTTP clients, while internal/mcp/server.go registers specialized tool handlers that conform to the Model Context Protocol, often exposing the same underlying skills through a different integration pattern.

Can external tools integrate with CyberStrikeAI without using the REST API Handlers?

No, the REST API Handlers constitute the primary public interface for CyberStrikeAI. All external interactions—including front-end dashboards, chatbots, and CI/CD pipelines—must route through these handlers to access the vulnerability database, skill engine, or robot agent functionality.

Where is the routing configuration that maps URLs to specific handler methods?

The mapping occurs in cmd/server/main.go, where the application initializes handler instances and calls Gin registration methods like router.POST("/vulnerabilities", h.CreateVulnerability) to bind HTTP verbs and paths to the corresponding struct methods.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}