Sirius Scan Documentation

The Sirius Agent System is a distributed architecture designed to manage remote security agents that perform vulnerability detection and system scanning across various environments (Linux, Windows, macOS, and Remote).

Key architectural components include:

• Sirius Platform: Composed of sirius-api (Go/Fiber) and sirius-ui (Next.js).
• Agent Server: A gRPC-based central hub that manages agent connections, distributes commands via RabbitMQ, and synchronizes templates using Valkey/Redis.
• Agent Client: A remote endpoint that maintains a bidirectional gRPC stream with the server, executes commands (internal or shell-based), and performs vulnerability scans using cached templates.
• Communication: Uses gRPC bidirectional streaming for real-time interaction and RabbitMQ for command queuing.

The Sirius UI design system (v0.4.0) follows a dark mode first philosophy with a violet theme. It is built on ShadCN UI and customized using Tailwind CSS. Key visual characteristics include:

• Glassmorphism: Use of subtle backdrop blur and transparency for depth.
• Violet Accents: The primary brand color is applied throughout the interface.
• High Contrast: Designed for clear visual hierarchy and readability.
• Consistent Spacing & Animations: Predictable layouts and smooth transitions for loading and interactive states.

The Sirius Go API SDK (github.com/SiriusScan/go-api) is a shared library designed for use across multiple Sirius projects (scanners, API servers, and agents). It provides a single source of truth for core data models and abstracts complex operations for databases, message queues, and key-value stores.

Key Capabilities:

• Core Data Models: Unified structures for Host, Port, Vulnerability, and Service.
• Database Operations: PostgreSQL management via GORM.
• Message Queue: RabbitMQ integration for pub/sub.
• Key-Value Store: ValKey/Redis integration.
• NVD Integration: Enrichment of vulnerability data via the NVD API.

Sirius Scan is composed of three primary application services that handle different layers of the system:

• sirius-ui: The frontend user interface and Backend-For-Frontend (BFF). It provides the GUI for managing scans, viewing results, and configuring settings.
• sirius-api: The backend RESTful services providing the core API.
• sirius-engine: The core service responsible for scanning and processing tasks.

Additionally, the go-api library serves as a shared SDK for Go-based backend services.

The following hooks are available for integrating scanner functionality into your React components:

Data Hooks

• useScanResults: Polls ValKey for live scan data, including hosts, vulnerabilities, and progress.
• useScanDataMapping: Maps raw scan results into table-ready data structures.
• useSourceFiltering: Filters data by discovery source.

Orchestration & Control Hooks

• useScanOrchestration: Composes useStartScan and useStopScan with profile logic to provide high-level scan management.
• useStartScan: Initiates a scan via tRPC.
• useStopScan: Cancels a running scan via tRPC.

The administrator service consists of three primary functional areas and integrates with existing Sirius infrastructure:

Core Components

• Administrator Binary: A standalone Go application used to perform administrative operations.
• API Integration: The mechanism used to connect to the main Sirius API for system management.
• Command Processing: The logic layer that handles incoming administrative commands and operations.

System Integrations

• Sirius API: Used for core system management tasks.
• System Monitoring: Provides operational insights for the administrator.
• Configuration Management: Used to manage and apply system settings.

The Sirius Scanner is a message-driven vulnerability scanning engine.

Core Flow:

1. Receive scan message via RabbitMQ.
2. Expand targets.
3. Distribute tasks to a worker pool.
4. Execute scanning strategies.
5. Enrich results.
6. Submit results to the API.

Key Components:

• ScanManager: Orchestrates the scanning process.
• ScanStrategies: Integrations with external tools.
• TemplateManager: Manages scan configurations.
• NSE system: Manages Nmap Scripting Engine scripts.

Integration Points:

• Input: RabbitMQ
• State: ValKey
• Results: PostgreSQL
• Enrichment: NVD API (for CVE data)

Development Environment:

• Requires Go 1.23+.
• Runs within the sirius-engine container.
• Supports live reload using Air.

The Agent Template API provides endpoints for managing vulnerability detection templates used by Sirius agents. These templates define the detection logic used to identify vulnerabilities on target systems.

Base URL: http://localhost:9001/api

The Agent Identity System provides structured, role-specific context for AI interactions (such as in Cursor) across the Sirius project. It solves the problem of losing project-specific knowledge when starting fresh AI conversations by providing comprehensive documents (~1200-1500 lines) that include:

• Role-specific project context
• Technology stack and architecture details
• Development workflows and best practices
• Common tasks and troubleshooting guides
• Integration with the broader system

The system uses a hybrid approach, combining manual narrative (philosophy, best practices) with auto-generated sections (file structure, ports, dependencies, configurations) to ensure identities stay synchronized with the actual codebase.