CyberStrikeAI/docs/en-US/developer-guide.md

Developer Guide

中文

This guide is for contributors extending CyberStrikeAI. The project is a Go single-service application with a static frontend, SQLite persistence, Agent/MCP orchestration, and optional high-risk security subsystems.

Project Layout

cmd/server/              service entrypoint
internal/app/            app wiring, routes, MCP tool registration
internal/handler/        HTTP handlers
internal/database/       SQLite access
internal/security/       auth, rate limits, shell execution
internal/mcp/            MCP server and external MCP manager
internal/multiagent/     Eino single-agent, multi-agent, middleware
internal/workflow/       graph orchestration runtime
internal/knowledge/      indexing and retrieval
internal/c2/             built-in C2
internal/project/        project fact blackboard
web/static/              frontend JS/CSS/assets
web/templates/           HTML templates
tools/                   YAML command tools
roles/                   role YAML
agents/                  multi-agent Markdown definitions
skills/                  Agent Skills
docs/                    documentation

Development Startup

go run ./cmd/server --config config.yaml

The frontend is static. Most JS/CSS/template changes only require a browser refresh.

Adding a Business Module

Do not add only a handler. A complete module usually needs:

1. Data model and SQLite migration.
2. Handler: parameters, errors, pagination/filtering.
3. Audit: management actions.
4. Monitor: long-running execution state.
5. MCP: whether Agents should call it.
6. HITL: approval boundary for MCP tools.
7. OpenAPI: update /api/openapi/spec.
8. Frontend: i18n, states, empty/error UI.
9. Tests: DB, handler, edge cases.
10. Docs: config, usage, troubleshooting, safety impact.

Missing one of these usually becomes a later usability or safety bug.

Error Response Design

Prefer stable JSON:

{
  "error": "machine_readable_code",
  "message": "human-readable explanation"
}

Frontend needs stable fields, users need actionable messages, and logs need detailed internal errors.

Long-Running Tasks

For scanning, indexing, batch tasks, C2, or external operations, answer:

• Can it be cancelled?
• Can progress be queried?
• Can it be retried?
• Where is the result stored?
• Does state survive page refresh?
• Does it block the HTTP request?

If not, use task tables, event streams, or monitoring.

Extending Tools

Prefer tools/*.yaml for command tools. Use Go built-in tools when the tool needs internal state or structured integration.

Built-in tools should define clear input schemas, handle timeouts and errors, and respect HITL for risky actions.

Frontend Changes

Use existing helpers such as apiFetch, modal utilities, notifications, and i18n. Update both web/static/i18n/zh-CN.json and web/static/i18n/en-US.json for new visible text.

Avoid putting secrets or provider keys in frontend code.

Test Priority

High-value tests:

• config hot-apply;
• HITL branches;
• shell timeout/no-output;
• external MCP recovery;
• KB indexing and post-processing;
• WebShell OS/encoding detection;
• SQLite migration compatibility.

Source Anchors

• App wiring: internal/app/app.go
• Config apply: internal/handler/config.go
• OpenAPI: internal/handler/openapi.go
• Tool executor: internal/security/executor.go
• Skill package: internal/skillpackage/