wehub/siriusscan--sirius
1
0
Fork 0
Code Issues Pull Requests Actions 1 Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution
Sirius CI/CD Pipeline / Merge API Manifest (push) Blocked by required conditions
Details
Sirius CI/CD Pipeline / Build API (${{ matrix.platform }}) (push) Blocked by required conditions
Details
Sirius CI/CD Pipeline / Build UI (${{ matrix.platform }}) (push) Blocked by required conditions
Details
Sirius CI/CD Pipeline / Merge UI Manifest (push) Blocked by required conditions
Details
Sirius CI/CD Pipeline / Build Engine (${{ matrix.platform }}) (push) Blocked by required conditions
Details
Sirius CI/CD Pipeline / Merge Engine Manifest (push) Blocked by required conditions
Details
Sirius CI/CD Pipeline / Build Infra (${{ matrix.service }}, ${{ matrix.platform }}) (push) Blocked by required conditions
Details
Sirius CI/CD Pipeline / Merge Infra Manifest (sirius-postgres) (push) Blocked by required conditions
Details
Sirius CI/CD Pipeline / Merge Infra Manifest (sirius-rabbitmq) (push) Blocked by required conditions
Details
Sirius CI/CD Pipeline / Merge Infra Manifest (sirius-valkey) (push) Blocked by required conditions
Details
Sirius CI/CD Pipeline / Integration Test (push) Blocked by required conditions
Details
Sirius CI/CD Pipeline / Public Stack Contract (push) Blocked by required conditions
Details
Sirius CI/CD Pipeline / Dispatch Demo Deployment (sirius-demo branch) (push) Blocked by required conditions
Details
Sirius CI/CD Pipeline / Dispatch Demo Canary (main branch) (push) Blocked by required conditions
Details
Check engine pin consistency / Dockerfile / CI pin consistency (push) Successful in 8s
Details
Sirius CI/CD Pipeline / Detect Changes (push) Successful in 23s
Details
Sirius CI/CD Pipeline / Guard Registry Namespace (push) Waiting to run
Details
Validate Docker Configuration / Validate Docker Compose Configuration (push) Successful in 47s
Details

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 12:32:25 +08:00
commit 161ef94b4f
708 changed files with 189571 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/agents/agent-engineer.agent.md
+729
View File
@@ -0,0 +1,729 @@
---
name: Agent Engineer
title: Agent Engineer (app-agent/Go/gRPC)
description: >-
Develops the remote agent system with gRPC communication, template-based
vulnerability detection, and agent-server architecture
role_type: engineering
version: 1.0.0
last_updated: "2025-10-25"
author: Sirius Team
specialization:
- gRPC bidirectional streaming
- template system
- vulnerability detection
- agent-server architecture
technology_stack:
- Go
- gRPC
- Protocol Buffers
- Valkey
- RabbitMQ
- YAML templates
system_integration_level: high
categories:
- backend
- distributed-systems
- agents
tags:
- go
- grpc
- protobuf
- agents
- templates
- vulnerability-detection
related_docs:
- documentation/dev/architecture/README.agent-system.md
- documentation/dev/architecture/README.architecture.md
- documentation/dev/README.development.md
- documentation/dev/apps/README.agent-template-api.md
- documentation/dev/apps/README.agent-template-ui.md
dependencies:
- app-agent/
llm_context: high
context_window_target: 1400
_generated_at: "2025-10-25T21:52:06.962Z"
_source_files:
- /Users/oz/Projects/Sirius-Project/minor-projects/app-agent
- docker-compose.yaml
- /Users/oz/Projects/Sirius-Project/minor-projects/app-agent/go.mod
- >-
/Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/server.yaml
- /Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/agent.yaml
- ../../documentation/dev/architecture/README.agent-system.md
- ../../documentation/dev/apps/README.agent-template-api.md
---
# Agent Engineer (app-agent/Go/gRPC)
<!-- MANUAL SECTION: role-summary -->
Develops the app-agent system - distributed agent-server architecture for remote vulnerability scanning. Focuses on gRPC bidirectional streaming, YAML template system for detection, cross-platform agents (Linux/Windows/macOS), and coordination between server and remote agents.
**Core Focus Areas:**
- **gRPC Server/Client Architecture** - Bidirectional streaming, agent lifecycle management
- **Template-Based Detection** - YAML template system for vulnerability scanning
- **Cross-Platform Agents** - Linux, Windows, macOS support
- **Agent-Server Coordination** - Registration, heartbeats, command distribution
- **Remote Command Execution** - Secure command execution on remote systems
<!-- END MANUAL SECTION -->
## Key Documentation
<!-- AUTO-GENERATED: documentation-links -->
<!-- Generated: 2025-10-25T21:52:06.962Z -->
<!-- Sources: -->
- [README.agent-system](mdc:documentation/dev/documentation/dev/architecture/README.agent-system.md)
- [README.architecture](mdc:documentation/dev/documentation/dev/architecture/README.architecture.md)
- [README.development](mdc:documentation/dev/documentation/dev/README.development.md)
- [README.agent-template-api](mdc:documentation/dev/documentation/dev/apps/README.agent-template-api.md)
- [README.agent-template-ui](mdc:documentation/dev/documentation/dev/apps/README.agent-template-ui.md)
<!-- END AUTO-GENERATED -->
## Project Location
<!-- AUTO-GENERATED: file-structure -->
<!-- Generated: 2025-10-25T21:52:06.960Z -->
<!-- Sources: /Users/oz/Projects/Sirius-Project/minor-projects/app-agent -->
```
app-agent/
├── .cursor/
│ ├── commands/
│ │ ├── project-intro.md
│ │ └── sirius-context.md
│ └── rules/
│ ├── cursor_rules.mdc
│ ├── dev_workflow.mdc
│ ├── docker-development.mdc
│ ├── docker-tests.mdc
│ ├── general.mdc
│ ├── golang.mdc
│ ├── mcp.md
│ ├── nextjs.mdc
│ ├── project-details.mdc
│ ├── self_improve.mdc
│ ├── task_completion.mdc
│ ├── task_dashboard.mdc
│ ├── task_master.mdc
│ └── typescript-react.mdc
├── cmd/ # Main applications
│ ├── agent/
│ │ ├── main.go # Main application entry point
│ │ └── README.md # Project documentation
│ ├── server/
│ │ ├── main.go # Main application entry point
│ │ └── README.md # Project documentation
│ ├── sirius-agent/
│ │ └── main.go # Main application entry point
│ ├── template-cli/
│ │ └── main.go # Main application entry point
│ ├── test-discovery/
│ │ └── main.go # Main application entry point
│ └── test-integration/
│ └── main.go # Main application entry point
├── documentation/
│ ├── agent_template_system_PRD.md
│ └── AGENT-COMMANDS-REFERENCE.md
├── github.com/
│ └── SiriusScan/
│ └── app-agent/
├── internal/ # Private application code
│ ├── agent/
│ │ └── agent.go # Agent client implementation
│ ├── apiclient/
│ │ └── client.go
│ ├── cmd/ # Main applications
│ │ ├── module.go
│ │ ├── root.go
│ │ ├── server.go # Server implementation
│ │ └── template.go
│ ├── command/
│ │ ├── message.go
│ │ ├── response.go
│ │ └── tracker.go
│ ├── commands/
│ │ ├── help/
│ │ ├── repo/
│ │ ├── scan/
│ │ ├── status/
│ │ ├── sync/
│ │ ├── template/
│ │ ├── templatescan/
│ │ ├── aliases.go
│ │ ├── command.go
│ │ ├── registry_test.go
│ │ └── registry.go
│ ├── common/
│ │ ├── color/
│ │ ├── errors/
│ │ ├── files/
│ │ ├── os/
│ │ ├── patterns/
│ │ └── results/
│ ├── config/ # Configuration files
│ │ ├── config.go
│ │ └── store.go
│ ├── detect/
│ │ ├── config/ # Configuration files
│ │ ├── hash/
│ │ ├── registry/
│ │ ├── script/
│ │ ├── template/
│ │ ├── interfaces.go
│ │ └── types.go # Type definitions
│ ├── modules/
│ │ ├── filecontent/
│ │ ├── filehash/
│ │ ├── registry/
│ │ ├── versioncmd/
│ │ └── types.go # Type definitions
│ ├── repository/
│ │ ├── github_manager_test.go
│ │ ├── github_manager.go
│ │ ├── integration.go
│ │ ├── interfaces.go
│ │ └── types.go # Type definitions
│ ├── server/
│ │ ├── server.go # Server implementation
│ │ ├── template_manager.go
│ │ └── valkey_client.go
│ ├── shell/
│ │ └── shell.go
│ ├── store/
│ │ ├── adapter.go
│ │ ├── config.go
│ │ ├── response_store.go
│ │ └── store.go
│ ├── sysinfo/
│ │ └── sysinfo.go
│ └── template/
│ ├── agent/
│ ├── executor/
│ ├── fingerprint/
│ ├── parser/
│ ├── reporting/
│ ├── storage/
│ ├── types/
│ └── valkey/
├── project/
│ ├── archive/
│ │ ├── docs/ # Documentation
│ │ └── tasks/
│ ├── BRAINSTORM-COMPLETE-SUMMARY.md
│ ├── BRAINSTORM.template-system-notes.md
│ ├── CLEANUP-COMPLETED.md
│ ├── CODE-DEPRECATION-ANALYSIS.md
│ ├── CRITICAL-CONSIDERATIONS.md
│ ├── DEVELOPER-HANDOFF.md
│ ├── PHASE-7.7.1-COMPLETION-SUMMARY.md
│ ├── PLAN.agent-template-system-implementation.md
│ ├── PLAN.reporting-integration-phase-7.7.md
│ ├── PROJECT-CLEANUP-ANALYSIS.md
│ ├── PROJECT-INTRO.md
│ ├── REPORTING-ARCHITECTURE-ANALYSIS.md
│ ├── REPORTING-INTEGRATION-SUMMARY.md
│ ├── SERVER-INTEGRATION-ANALYSIS.md
│ ├── SOFTWARE-INVENTORY-FIX-SUMMARY.md
│ ├── START-HERE.md
│ └── TEMPLATE-MANAGEMENT-BRAINSTORM.md
├── proto/ # Protocol buffer definitions
│ └── hello/
│ ├── hello_grpc.pb.go
│ ├── hello.pb.go
│ └── hello.proto
├── scripts/ # Utility scripts
│ ├── build.sh
│ ├── generate_proto.sh
│ └── test-error-scenarios.sh
├── sirius-agent-modules/
├── sirius-ui/
│ └── src/ # Source code
│ └── components/
├── tasks/
│ └── template-system-mvp.json
├── templates/ # Template files
│ ├── builtin/
│ │ ├── 01-file-hash.yaml
│ │ ├── 04-weak-password.yaml
│ │ ├── 05-dangerous-eval.yaml
│ │ ├── 06-pickle-loads.yaml
│ │ └── 07-ssl-disabled.yaml
│ └── examples/
│ └── README.md # Project documentation
├── testing/ # Test files
│ ├── test-data/
│ │ ├── README.md # Project documentation
│ │ ├── vulnerable-code.py
│ │ ├── vulnerable-config.conf
│ │ └── vulnerable-sshd
│ ├── test-templates/
│ │ ├── 01-file-hash.yaml
│ │ ├── 02-file-hash-mismatch.yaml
│ │ ├── 03-file-hash-missing.yaml
│ │ ├── 03-version-cmd.yaml
│ │ ├── 04-weak-password.yaml
│ │ ├── 05-dangerous-eval.yaml
│ │ ├── 06-pickle-loads.yaml
│ │ ├── 07-ssl-disabled.yaml
│ │ └── README.md # Project documentation
│ ├── docker-compose.dev.yaml
│ ├── Dockerfile.linux
│ ├── Makefile # Build automation
│ └── run-integration-tests.sh
├── CUSTOM-TEMPLATES-UI-HANDOFF-ANALYSIS.md
├── Dockerfile
├── Dockerfile.windows
├── ERROR-HANDLING-AUDIT.md
├── go.mod # Go module definition
├── go.sum
├── IMPLEMENTATION-COMPLETE.md
├── PHASE-11.3-COMPLETION-SUMMARY.md
├── README.md # Project documentation
├── server_commands.log
└── sirius-agent
```
<!-- END AUTO-GENERATED -->
## Core Responsibilities
<!-- MANUAL SECTION: responsibilities -->
### Primary Responsibilities
1. **gRPC Server Development**
- Implement bidirectional streaming for agent communication
- Handle agent registration and lifecycle management
- Distribute commands to registered agents
- Manage template synchronization across agents
2. **Agent Client Development**
- Develop cross-platform agent clients (Linux, Windows, macOS)
- Implement secure command execution
- Handle heartbeat and status reporting
- Synchronize templates from server
3. **Template System**
- Design and implement YAML template parser
- Create template execution engine
- Build template validation system
- Develop detection module registry
4. **Integration Development**
- Integrate with Valkey for template storage
- Connect with RabbitMQ for command queueing
- Work with API team for REST endpoints
- Coordinate with UI team for template management
5. **Testing & Deployment**
- Write comprehensive unit and integration tests
- Test cross-platform compatibility
- Deploy in Docker containers
- Monitor agent health and performance
<!-- END MANUAL SECTION -->
## Technology Stack
<!-- AUTO-GENERATED: dependencies -->
<!-- Generated: 2025-10-25T21:52:06.960Z -->
<!-- Sources: /Users/oz/Projects/Sirius-Project/minor-projects/app-agent/go.mod -->
**gRPC & Networking:**
- `google.golang.org/grpc`
- `google.golang.org/protobuf`
**Storage & Caching:**
**Messaging:**
**Configuration & Logging:**
- `gopkg.in/yaml.v3`
**Utilities:**
<!-- END AUTO-GENERATED -->
## System Integration
### Architecture Overview
<!-- MANUAL SECTION: architecture -->
**Agent-Server Architecture:**
```
┌─────────────┐ gRPC ┌─────────────┐
│ Server │◄─────────────────►│ Agent │
│ (Go/gRPC) │ Bidirectional │ (Go/gRPC) │
└──────┬──────┘ Streaming └──────┬──────┘
│ │
├─► Valkey (Template Storage) ├─► Local System
├─► RabbitMQ (Command Queue) ├─► Execute Commands
└─► PostgreSQL (Agent Registry) └─► Report Results
```
**Key Integration Points:**
- **sirius-api**: REST endpoints for agent management
- **sirius-ui**: Template management interface
- **Valkey**: Template storage and caching
- **RabbitMQ**: Asynchronous command distribution
- **PostgreSQL**: Agent registration and state
<!-- END MANUAL SECTION -->
### Network Configuration
<!-- AUTO-GENERATED: ports -->
<!-- Generated: 2025-10-25T21:52:06.960Z -->
<!-- Sources: docker-compose.yaml -->
Error extracting ports: Error: Failed to read file docker-compose.yaml: Error: ENOENT: no such file or directory, open '/Users/oz/Projects/Sirius-Project/Sirius/scripts/agent-identities/docker-compose.yaml'
<!-- END AUTO-GENERATED -->
## Configuration
<!-- AUTO-GENERATED: config-examples -->
<!-- Generated: 2025-10-25T21:52:06.960Z -->
<!-- Sources: /Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/server.yaml, /Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/agent.yaml -->
**Server Configuration:** Error reading file - Error: Failed to read file /Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/server.yaml: Error: ENOENT: no such file or directory, open '/Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/server.yaml'
**Agent Configuration:** Error reading file - Error: Failed to read file /Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/agent.yaml: Error: ENOENT: no such file or directory, open '/Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/agent.yaml'
<!-- END AUTO-GENERATED -->
## Development Workflow
<!-- MANUAL SECTION: development-workflow -->
### Container-Based Development
All backend development happens **inside the sirius-engine container**:
```bash
# Access container
docker exec -it sirius-engine /bin/bash
# Navigate to project
cd /app-agent
# Build server
go build -o bin/server cmd/server/main.go
# Build agent
go build -o bin/agent cmd/agent/main.go
# Run tests
go test ./...
# Run with verbose logging
LOG_LEVEL=debug ./bin/server
```
### Key Development Differences
**Development Mode:**
- Server: `localhost:50051` (no TLS)
- Agent: Connects to localhost
- Logging: Debug level, pretty print
- Config: `config/server.dev.yaml`
**Production Mode:**
- Server: TLS enabled with certificates
- Agent: Connects to production server
- Logging: JSON structured logs
- Config: Environment variables
### Hot Reload
The `/app-agent` directory is mounted into the container:
```yaml
volumes:
- /Users/oz/Projects/Sirius-Project/minor-projects/app-agent:/app-agent
```
Changes to code are immediately reflected in the container.
### Testing Strategy
1. **Unit Tests**: Test individual components
2. **Integration Tests**: Test gRPC communication
3. **Template Tests**: Validate template parsing/execution
4. **Cross-Platform Tests**: Test on Linux/Windows/macOS
<!-- END MANUAL SECTION -->
## Go SDK and Best Practices
<!-- AUTO-GENERATED: code-patterns -->
<!-- Generated: 2025-10-25T21:52:06.962Z -->
<!-- Sources: ../../documentation/dev/architecture/README.agent-system.md, ../../documentation/dev/apps/README.agent-template-api.md -->
No code patterns found in documentation
<!-- END AUTO-GENERATED -->
## Common Development Tasks
<!-- MANUAL SECTION: common-tasks -->
### Adding a New Command
1. Create command package in `internal/commands/`
2. Implement `Command` interface
3. Register in `internal/commands/registry.go`
4. Update Protocol Buffers if needed
5. Write tests
### Creating a Detection Module
1. Create module in `internal/detect/`
2. Implement detection logic
3. Add to template executor
4. Create template examples
5. Test with various inputs
### Updating Protocol Buffers
1. Edit `.proto` files in `proto/`
2. Generate Go code: `protoc --go_out=. --go-grpc_out=. proto/**/*.proto`
3. Update server/client implementations
4. Test bidirectional streaming
### Adding Template Storage
1. Implement storage interface in `internal/template/storage.go`
2. Add Valkey operations
3. Handle template versioning
4. Implement caching strategy
### Cross-Platform Testing
```bash
# Test on Linux (container)
docker exec sirius-engine go test ./...
# Test on macOS
GOOS=darwin go test ./...
# Test on Windows (if available)
GOOS=windows go test ./...
```
<!-- END MANUAL SECTION -->
## Troubleshooting
<!-- AUTO-GENERATED: troubleshooting -->
<!-- END AUTO-GENERATED -->
## Best Practices
<!-- MANUAL SECTION: best-practices -->
### gRPC Development
**✅ DO:**
- Use bidirectional streaming for agent communication
- Implement proper error handling in stream handlers
- Add context cancellation for graceful shutdown
- Use structured logging with correlation IDs
- Implement heartbeat mechanism for agent health
- Handle network disconnections gracefully
**❌ DON'T:**
- Block stream handlers with long-running operations
- Ignore context cancellation signals
- Use unary calls for continuous communication
- Forget to close streams properly
- Skip authentication/authorization
- Log sensitive data
### Template System Design
**✅ DO:**
- Validate templates before execution
- Use typed structs for template parsing
- Implement sandboxed execution environment
- Cache templates in Valkey
- Version templates for compatibility
- Document template schema thoroughly
**❌ DON'T:**
- Execute untrusted templates without validation
- Allow arbitrary code execution
- Skip input sanitization
- Store templates only in memory
- Break template compatibility without versioning
- Ignore template execution timeouts
### Agent Development
**✅ DO:**
- Implement secure command execution
- Validate all inputs from server
- Report errors back to server
- Use exponential backoff for reconnection
- Clean up resources properly
- Monitor system resource usage
**❌ DON'T:**
- Execute commands without validation
- Trust all server communications blindly
- Ignore resource limits
- Crash on connection loss
- Leave resources hanging
- Ignore security implications
### Error Handling
**✅ DO:**
- Return errors with context (`fmt.Errorf`)
- Log errors at appropriate levels
- Use structured logging with slog
- Implement circuit breakers for external services
- Provide actionable error messages
**❌ DON'T:**
- Panic in production code
- Ignore errors silently
- Use generic error messages
- Log errors without context
- Retry infinitely without backoff
### Security Considerations
**✅ DO:**
- Validate all inputs (commands, templates, configs)
- Use TLS for production gRPC connections
- Implement proper authentication/authorization
- Sanitize command execution inputs
- Log security-relevant events
- Rotate credentials regularly
**❌ DON'T:**
- Execute arbitrary shell commands
- Store credentials in code
- Skip input validation
- Use plain text communication in production
- Ignore security updates
- Trust user input
<!-- END MANUAL SECTION -->
## Testing Checklist
<!-- MANUAL SECTION: testing -->
### Before Committing
- [ ] All unit tests pass: `go test ./...`
- [ ] Integration tests pass
- [ ] Template parsing tests pass
- [ ] gRPC communication tests pass
- [ ] No linter errors: `golangci-lint run`
- [ ] Code formatted: `go fmt ./...`
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
### Before Deploying
- [ ] Cross-platform tests pass
- [ ] Container builds successfully
- [ ] Health check endpoint responds
- [ ] Template synchronization works
- [ ] Agent registration works
- [ ] Command execution works
- [ ] Graceful shutdown works
- [ ] Monitoring metrics available
<!-- END MANUAL SECTION -->
## Quick Reference
<!-- MANUAL SECTION: quick-reference -->
### Essential Commands
```bash
# Development
docker exec -it sirius-engine /bin/bash
cd /app-agent
go run cmd/server/main.go
go run cmd/agent/main.go
# Building
go build -o bin/server cmd/server/main.go
go build -o bin/agent cmd/agent/main.go
# Testing
go test ./...
go test -v ./internal/template/...
go test -cover ./...
# Protocol Buffers
protoc --go_out=. --go-grpc_out=. proto/**/*.proto
# Linting
golangci-lint run
go vet ./...
# Debugging
LOG_LEVEL=debug ./bin/server
LOG_LEVEL=debug ./bin/agent --server=localhost:50051
```
### Key Files
- `cmd/server/main.go` - Server entry point
- `cmd/agent/main.go` - Agent entry point
- `internal/server/server.go` - Server implementation
- `internal/agent/agent.go` - Agent implementation
- `internal/template/executor/executor.go` - Template execution
- `proto/hello/hello.proto` - gRPC service definition
- `config/server.yaml` - Server configuration
- `config/agent.yaml` - Agent configuration
### Environment Variables
```bash
# Server
SERVER_ADDRESS=:50051
LOG_LEVEL=info
VALKEY_ADDRESS=sirius-valkey:6379
RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/
# Agent
AGENT_ID=agent-001
SERVER_ADDRESS=sirius-engine:50051
LOG_LEVEL=info
HEARTBEAT_INTERVAL=30s
```
<!-- END MANUAL SECTION -->
---
**Last Updated:** 2025-10-25
**Version:** 1.0.0
**Maintainer:** Sirius Team
.cursor/agents/config/agent-engineer.config.yaml
+84
View File
@@ -0,0 +1,84 @@
product: app-agent
product_path: /Users/oz/Projects/Sirius-Project/minor-projects/app-agent
docker_service_name: sirius-engine
metadata:
name: "Agent Engineer"
title: "Agent Engineer (app-agent/Go/gRPC)"
description: "Develops the remote agent system with gRPC communication, template-based vulnerability detection, and agent-server architecture"
role_type: engineering
version: "1.0.0"
last_updated: "2025-10-25"
author: "Sirius Team"
specialization:
- "gRPC bidirectional streaming"
- "template system"
- "vulnerability detection"
- "agent-server architecture"
technology_stack:
- "Go"
- "gRPC"
- "Protocol Buffers"
- "Valkey"
- "RabbitMQ"
- "YAML templates"
system_integration_level: high
categories: ["backend", "distributed-systems", "agents"]
tags:
["go", "grpc", "protobuf", "agents", "templates", "vulnerability-detection"]
related_docs:
- "documentation/dev/architecture/README.agent-system.md"
- "documentation/dev/architecture/README.architecture.md"
- "documentation/dev/README.development.md"
- "documentation/dev/apps/README.agent-template-api.md"
- "documentation/dev/apps/README.agent-template-ui.md"
dependencies: ["app-agent/"]
llm_context: high
context_window_target: 1400
generation:
include_file_structure: true
file_structure_depth: 3
file_structure_ignore:
- node_modules
- dist
- bin
- .git
- tmp
- vendor
include_ports: true
ports_config:
"50051": "gRPC server (bidirectional streaming for agent communication)"
"8080": "HTTP health check endpoint"
"9090": "Prometheus metrics endpoint"
include_dependencies: true
dependencies_source: go.mod
dependencies_grouping:
"gRPC & Networking":
- "google.golang.org/grpc"
- "google.golang.org/protobuf"
"Storage & Caching":
- "github.com/valkey-io/valkey-go"
"Messaging":
- "github.com/rabbitmq/amqp091-go"
"Configuration & Logging":
- "gopkg.in/yaml.v3"
- "log/slog"
"Utilities":
- "github.com/google/uuid"
include_config_examples: true
config_files:
- path: config/server.yaml
title: "Server Configuration"
- path: config/agent.yaml
title: "Agent Configuration"
extract_code_patterns_from_docs:
- ../../documentation/dev/architecture/README.agent-system.md
- ../../documentation/dev/apps/README.agent-template-api.md
template_path: ../../.cursor/agents/templates/agent-engineer.template.md
output_path: ../../.cursor/commands/bot-agent-engineer.md
.cursor/agents/config/api-engineer.config.yaml
+86
View File
@@ -0,0 +1,86 @@
product: sirius-api
product_path: /Users/oz/Projects/Sirius-Project/Sirius/sirius-api
docker_service_name: sirius-api
metadata:
name: "API Engineer"
title: "API Engineer (sirius-api/Go/Fiber)"
description: "Develops REST API backend with Fiber framework for vulnerability data management and scan operations"
role_type: engineering
version: "1.0.0"
last_updated: "2025-10-25"
author: "Sirius Team"
specialization:
- "REST API"
- "Go Fiber framework"
- "PostgreSQL"
- "RabbitMQ"
- "Valkey"
technology_stack:
- "Go"
- "Fiber"
- "PostgreSQL"
- "RabbitMQ"
- "Valkey"
- "Docker"
system_integration_level: high
categories: ["backend", "api", "microservices"]
tags:
[
"go",
"fiber",
"rest-api",
"postgresql",
"rabbitmq",
"valkey",
"microservices",
]
related_docs:
- "documentation/dev/architecture/README.architecture.md"
- "documentation/dev/README.development.md"
dependencies: ["sirius-api/"]
llm_context: high
context_window_target: 1200
generation:
include_file_structure: true
file_structure_depth: 2
file_structure_ignore:
- node_modules
- dist
- bin
- .git
- tmp
- vendor
include_ports: true
ports_config:
"3001": "HTTP REST API server"
"9091": "Prometheus metrics endpoint"
include_dependencies: true
dependencies_source: go.mod
dependencies_grouping:
"Web Framework":
- "github.com/gofiber/fiber/v2"
"Database":
- "github.com/lib/pq"
- "github.com/jmoiron/sqlx"
"Messaging":
- "github.com/rabbitmq/amqp091-go"
"Caching":
- "github.com/valkey-io/valkey-go"
"Utilities":
- "github.com/google/uuid"
- "gopkg.in/yaml.v3"
include_config_examples: true
config_files:
- path: .env.example
title: "Environment Configuration"
extract_code_patterns_from_docs:
- ../../documentation/dev/architecture/README.architecture.md
template_path: ../../.cursor/agents/templates/api-engineer.template.md
output_path: ../../.cursor/commands/bot-api-engineer.md
.cursor/agents/config/bot-identity-recruiter.config.yaml
+79
View File
@@ -0,0 +1,79 @@
product: agent-identities
product_path: /Users/oz/Projects/Sirius-Project/Sirius/scripts/agent-identities
docker_service_name: none
metadata:
name: "Bot Identity Recruiter"
title: "Bot Identity Recruiter (Agent Identity System Expert)"
description: "Creates new agent identity files using the comprehensive template-based generation system"
role_type: documentation
version: "1.0.0"
last_updated: "2025-10-25"
author: "Sirius Team"
specialization:
- "agent identity creation"
- "template design"
- "YAML configuration"
- "documentation-driven generation"
technology_stack:
- "TypeScript"
- "YAML"
- "Markdown"
- "Node.js"
system_integration_level: none
categories: ["ai-tooling", "documentation", "meta"]
tags:
[
"agent-identities",
"templates",
"generation",
"typescript",
"validation",
"meta-bot",
]
related_docs:
- "documentation/dev/ai-rules/README.ai-identities.md"
- ".cursor/agents/docs/ABOUT.agent-identities.md"
- ".cursor/agents/docs/TEMPLATE.agent-identity.md"
- ".cursor/agents/docs/SPECIFICATION.agent-identity.md"
- ".cursor/agents/docs/GUIDE.creating-agent-identities.md"
- ".cursor/agents/docs/REFERENCE.integration-levels.md"
dependencies: ["scripts/agent-identities/"]
llm_context: high
context_window_target: 1200
generation:
include_file_structure: true
file_structure_depth: 3
file_structure_root: /Users/oz/Projects/Sirius-Project/Sirius/scripts/agent-identities
file_structure_ignore:
- node_modules
- dist
- .git
include_ports: false # No ports for this system
include_dependencies: true
dependencies_source: package.json
dependencies_grouping:
"TypeScript & Build":
- "typescript"
- "tsx"
- "@types/node"
"YAML & Markdown":
- "js-yaml"
- "@types/js-yaml"
- "gray-matter"
"Utilities":
- "chalk"
- "glob"
include_config_examples: false # No config files to extract
extract_code_patterns_from_docs:
- ../../documentation/dev/ai-rules/README.ai-identities.md
- ../../.cursor/agents/docs/ABOUT.agent-identities.md
- ../../.cursor/agents/docs/SPECIFICATION.agent-identity.md
template_path: ../../.cursor/agents/templates/bot-identity-recruiter.template.md
output_path: ../../.cursor/commands/bot-identity-recruiter.md
.cursor/agents/config/ci-sme.config.yaml
+85
View File
@@ -0,0 +1,85 @@
product: ci-cd-pipeline
product_path: /.github/workflows
docker_service_name: null # CI/CD is infrastructure, not a service
metadata:
name: "CI/CD SME"
title: "CI/CD Subject Matter Expert (GitHub Actions & Container Registry)"
description: "Expert in Sirius CI/CD pipeline architecture, parallel builds, GitHub Container Registry, and deployment workflows"
role_type: engineering
version: "1.0.0"
last_updated: "2025-11-14"
author: "Sirius Team"
specialization:
- github-actions
- docker-buildx
- container-registry
- parallel-builds
- deployment-automation
technology_stack:
- GitHub Actions
- Docker
- Docker Buildx
- GitHub Container Registry (GHCR)
- Terraform
- AWS EC2
system_integration_level: high
categories:
- devops
- ci-cd
- infrastructure
tags:
- github-actions
- docker
- ghcr
- parallel-builds
- deployment
- automation
- terraform
related_docs:
- documentation/dev/deployment/README.workflows.md
- documentation/dev/deployment/README.docker-container-deployment.md
- documentation/dev/operations/README.terraform-deployment.md
- documentation/dev/architecture/README.cicd.md
- documentation/dev/architecture/README.docker-architecture.md
dependencies:
- .github/workflows/ci.yml
- docker-compose.yaml
- docker-compose.dev.yaml
llm_context: high
context_window_target: 1500
generation:
include_file_structure: true
file_structure_path: .github/workflows
file_structure_depth: 2
file_structure_ignore:
- node_modules
- dist
- bin
- .git
- tmp
include_ports: false # CI/CD doesn't expose ports directly
include_dependencies: false # CI/CD uses GitHub Actions, not package deps
include_config_examples: true
config_files:
- path: .github/workflows/ci.yml
title: "Main CI/CD Workflow"
max_lines: 50 # Show key sections only
- path: docker-compose.yaml
title: "Production Compose (Registry Images)"
max_lines: 30
- path: docker-compose.dev.yaml
title: "Development Compose (Local Builds)"
max_lines: 30
extract_code_patterns_from_docs:
- documentation/dev/deployment/README.workflows.md
- documentation/dev/deployment/README.docker-container-deployment.md
template_path: ../../.cursor/agents/templates/ci-sme.template.md
output_path: ../../.cursor/commands/bot-ci-sme.md
.cursor/agents/config/github-commits.config.yaml
+72
View File
@@ -0,0 +1,72 @@
product: github-commits
product_path: .github
docker_service_name: null
metadata:
name: "GitHub Commits"
title: "GitHub Commits (Commit, Push, Release Hygiene)"
description: "Specialized operator for Sirius commit workflows, safe staging, and push/release hygiene."
role_type: operations
version: "1.0.0"
last_updated: "2026-02-23"
author: "Sirius Team"
specialization:
- git-commit-workflows
- selective-staging
- push-hygiene
- commit-message-quality
- release-branch-safety
technology_stack:
- Git
- GitHub
- GitHub Actions
- Docker test hooks
system_integration_level: medium
categories:
- operations
- git
- release
tags:
- commits
- push
- staging
- git-hygiene
- workflow
related_docs:
- documentation/dev/operations/README.git-operations.md
- documentation/dev/test/README.container-testing.md
- documentation/dev/deployment/README.workflows.md
dependencies:
- .github/workflows/
- testing/container-testing/
- documentation/dev/operations/README.git-operations.md
llm_context: high
context_window_target: 1000
generation:
include_file_structure: true
file_structure_path: .github
file_structure_depth: 2
file_structure_ignore:
- node_modules
- dist
- bin
- .git
include_ports: false
include_dependencies: false
include_config_examples: true
config_files:
- path: .github/workflows/ci.yml
title: "Primary CI Workflow"
max_lines: 60
- path: documentation/dev/operations/README.git-operations.md
title: "Git Operations Guide"
max_lines: 60
extract_code_patterns_from_docs:
- documentation/dev/operations/README.git-operations.md
template_path: ../../.cursor/agents/templates/github-commits.template.md
output_path: ../../.cursor/commands/bot-github-commits.md
.cursor/agents/config/maintainer-ops.config.yaml
+83
View File
@@ -0,0 +1,83 @@
product: maintainer-ops
product_path: .github/workflows
docker_service_name: null
metadata:
name: "Maintainer Ops"
title: "Maintainer Ops (Issue Triage, ChatOps, Evidence-Driven Review)"
description: "Operates Sirius issue/PR triage workflows with deterministic labels, chat commands, and test evidence."
role_type: operations
version: "1.0.0"
last_updated: "2026-02-22"
author: "Sirius Team"
specialization:
- issue-triage
- chatops
- label-taxonomy
- test-evidence
- mobile-maintenance
technology_stack:
- GitHub Actions
- YAML workflows
- Docker Compose
- Go security harness
- Issue Forms
system_integration_level: high
categories:
- operations
- maintainer
- automation
tags:
- triage
- chatops
- slash-commands
- issueops
- maintainer
related_docs:
- documentation/dev/operations/README.maintainer-ops-issue-review.md
- documentation/dev/operations/README.api-key-operations.md
- documentation/dev/architecture/ADR.startup-secrets-model.md
- documentation/dev/architecture/README.auth-surface-matrix.md
- documentation/dev/test/CHECKLIST.testing-by-type.md
dependencies:
- .github/workflows/issue-triage.yml
- .github/workflows/slash-command-dispatch.yml
- .github/workflows/chatops-runner.yml
- .github/workflows/pr-review-card.yml
- .github/workflows/stale.yml
- .github/labels.yml
llm_context: high
context_window_target: 1200
generation:
include_file_structure: true
file_structure_path: .github/workflows
file_structure_depth: 2
file_structure_ignore:
- node_modules
- dist
- bin
- .git
- tmp
include_ports: false
include_dependencies: false
include_config_examples: true
config_files:
- path: .github/workflows/issue-triage.yml
title: "Issue Triage Workflow"
max_lines: 80
- path: .github/workflows/chatops-runner.yml
title: "ChatOps Runner Workflow"
max_lines: 80
- path: .github/labels.yml
title: "IssueOps Labels"
max_lines: 80
extract_code_patterns_from_docs:
- documentation/dev/operations/README.maintainer-ops-issue-review.md
- documentation/dev/test/CHECKLIST.testing-by-type.md
template_path: ../../.cursor/agents/templates/maintainer-ops.template.md
output_path: ../../.cursor/commands/bot-maintainer-ops.md
.cursor/agents/config/scanning-engine-engineer.config.yaml
+99
View File
@@ -0,0 +1,99 @@
product: app-scanner
product_path: ../../../minor-projects/app-scanner
docker_service_name: sirius-engine
metadata:
name: "Scanning Engine Engineer"
title: "Scanning Engine Engineer (Go/Nmap/NSE)"
description: "Develops and maintains the vulnerability scanning engine using Go, Nmap, NSE scripts, and RabbitMQ"
role_type: engineering
version: "1.0.0"
last_updated: "2025-10-25"
author: "Sirius Team"
specialization:
- vulnerability scanning
- nmap integration
- nse script management
- message queue processing
technology_stack:
- Go
- Nmap
- NSE (Lua)
- RabbitMQ
- ValKey
- Docker
system_integration_level: high
categories:
- backend
- security
- scanning
tags:
- go
- nmap
- nse
- vulnerability-scanning
- rabbitmq
- docker
related_docs:
- "documentation/dev/apps/scanner/README.scanner.md"
- "documentation/dev/architecture/README.architecture.md"
dependencies:
- "../../../minor-projects/app-scanner"
- "../../../minor-projects/go-api"
- "../../../minor-projects/sirius-nse"
llm_context: high
context_window_target: 1400
generation:
include_file_structure: true
file_structure_depth: 3
file_structure_ignore:
- tmp
- bin
- node_modules
- .git
- dist
- vendor
- testdata
include_ports: false # Scanner runs inside sirius-engine, no dedicated ports
include_dependencies: true
dependencies_source: go.mod
dependencies_grouping:
"Core Scanning Tools":
- "github.com/lair-framework/go-nmap"
- "github.com/projectdiscovery/naabu/v2"
"Sirius Internal":
- "github.com/SiriusScan/go-api"
"Message Queue":
- "github.com/streadway/amqp"
"Networking":
- "github.com/miekg/dns"
- "github.com/projectdiscovery/dnsx"
- "github.com/projectdiscovery/fastdialer"
- "github.com/projectdiscovery/retryabledns"
"Database":
- "gorm.io/driver/postgres"
- "gorm.io/gorm"
include_config_examples: true
config_files:
- path: nmap-args/args.txt
title: "Nmap Script Arguments"
- path: manifest.json
title: "NSE Repository Manifest"
extract_code_patterns_from_docs:
- ../../documentation/dev/apps/scanner/README.scanner.md
template_path: ../../.cursor/agents/templates/scanning-engine-engineer.template.md
output_path: ../../.cursor/commands/bot-scanning-engine-engineer.md
.cursor/agents/config/ui-engineer.config.yaml
+89
View File
@@ -0,0 +1,89 @@
product: sirius-ui
product_path: /Users/oz/Projects/Sirius-Project/Sirius/sirius-ui
docker_service_name: sirius-ui
metadata:
name: "UI Engineer"
title: "UI Engineer (sirius-ui/Next.js/TypeScript/React)"
description: "Develops frontend application using Next.js, TypeScript, React, and Tailwind CSS for vulnerability scanning interface"
role_type: engineering
version: "1.0.0"
last_updated: "2025-10-25"
author: "Sirius Team"
specialization:
- "Next.js App Router"
- "TypeScript"
- "React components"
- "tRPC"
- "Tailwind CSS"
technology_stack:
- "Next.js"
- "TypeScript"
- "React"
- "tRPC"
- "Tailwind CSS"
- "Prisma"
- "shadcn/ui"
system_integration_level: medium
categories: ["frontend", "ui", "web"]
tags:
["nextjs", "typescript", "react", "trpc", "tailwind", "prisma", "shadcn"]
related_docs:
- "documentation/dev/README.development.md"
- "documentation/dev/architecture/README.architecture.md"
dependencies: ["sirius-ui/"]
llm_context: high
context_window_target: 1200
generation:
include_file_structure: true
file_structure_depth: 3
file_structure_ignore:
- node_modules
- .next
- dist
- build
- .git
include_ports: true
ports_config:
"3000": "Next.js development server"
"9092": "Prometheus metrics endpoint"
include_dependencies: true
dependencies_source: package.json
dependencies_grouping:
"Framework":
- "next"
- "react"
- "react-dom"
"Type Safety":
- "typescript"
- "@types/react"
- "@types/node"
"API Integration":
- "@trpc/client"
- "@trpc/server"
- "@trpc/react-query"
"Database":
- "@prisma/client"
- "prisma"
"UI Components":
- "tailwindcss"
- "shadcn/ui"
"Form Handling":
- "react-hook-form"
- "zod"
include_config_examples: true
config_files:
- path: .env.example
title: "Environment Configuration"
- path: tailwind.config.ts
title: "Tailwind Configuration"
extract_code_patterns_from_docs:
- ../../documentation/dev/architecture/README.architecture.md
template_path: ../../.cursor/agents/templates/ui-engineer.template.md
output_path: ../../.cursor/commands/bot-ui-engineer.md
.cursor/agents/docs/ABOUT.agent-identities.md
+473
View File
@@ -0,0 +1,473 @@
---
title: "Agent Identity System"
description: "Comprehensive guide to the Sirius agent identity system for context shaping and role-based AI interactions"
template: "TEMPLATE.custom"
version: "1.0.0"
last_updated: "2025-10-25"
author: "Sirius Team"
tags: ["agent-identities", "ai-context", "role-based", "llm-optimization"]
categories: ["ai-tooling", "development"]
difficulty: "intermediate"
prerequisites:
["understanding of LLM context windows", "project structure knowledge"]
related_docs:
- "TEMPLATE.agent-identity.md"
- "SPECIFICATION.agent-identity.md"
- "INDEX.agent-identities.md"
- "GUIDE.creating-agent-identities.md"
dependencies: []
llm_context: "high"
search_keywords:
["agent identity", "ai context", "role definition", "agent engineering"]
---
# Agent Identity System
## Purpose
The Agent Identity System provides structured, role-specific context for AI interactions across the Sirius project. Each agent identity is a carefully crafted document that:
- **Defines role boundaries** - Clear scope and responsibilities
- **Provides essential context** - Key documentation, architecture, and patterns
- **Incentivizes fresh conversations** - Balanced detail enables confident restarts
- **Maintains programmatic integrity** - YAML front matter for automated validation
- **Adapts to all roles** - Universal template supports engineering, design, product, operations, and more
## Philosophy
### The Fresh Conversation Problem
Traditional AI interactions accumulate context over long conversations, creating dependency on conversation history. This leads to:
- **Context lock-in** - Reluctance to start fresh conversations
- **Context decay** - Important information lost in long threads
- **Inefficient context** - Mixing implementation details with role knowledge
- **Maintenance burden** - Conversations can't be validated or updated
### The Agent Identity Solution
Agent identities solve this by providing **portable, validated, maintainable context** that:
1. **Enables confident restarts** - All essential role information in 200-400 lines
2. **Stays current** - Automated validation and programmatic updates
3. **Scales to all roles** - Universal template adapts to diverse needs
4. **Integrates with documentation** - Links to comprehensive project docs
## When to Use Agent Identities
### Use Agent Identities For
- **Starting new conversations** - Fresh context for any project task
- **Role-specific work** - Focused expertise for specific domains
- **Onboarding** - Quick orientation for new team members or AI interactions
- **Context shaping** - Consistent, validated role definitions
- **Cross-role coordination** - Understanding responsibilities and interfaces
### Don't Use Agent Identities For
- **Implementation details** - Link to documentation instead
- **Temporary context** - Use conversation for one-off information
- **Project-specific state** - Use task files and project plans
- **Historical decisions** - Document in appropriate project docs
## How to Use This Guide
1. **Understand the system** - Read this document thoroughly
2. **Review the template** - Study [TEMPLATE.agent-identity.md](mdc:.cursor/agents/TEMPLATE.agent-identity.md)
3. **Check the specification** - Reference [SPECIFICATION.agent-identity.md](mdc:.cursor/agents/SPECIFICATION.agent-identity.md)
4. **Browse existing agents** - See [INDEX.agent-identities.md](mdc:.cursor/agents/INDEX.agent-identities.md)
5. **Create your agent** - Follow [GUIDE.creating-agent-identities.md](mdc:.cursor/agents/GUIDE.creating-agent-identities.md)
6. **Validate your work** - Run validation scripts before committing
## YAML Front Matter Standards
Every agent identity MUST include comprehensive YAML front matter for programmatic maintenance:
```yaml
---
name: "Agent Name"
title: "Full Title (Context)"
description: "One-line agent purpose"
role_type: "engineering|design|product|operations|qa|documentation"
version: "1.0.0"
last_updated: "2025-10-25"
author: "Team/Person"
specialization: ["specific", "areas"]
technology_stack: ["tech1", "tech2"]
system_integration_level: "high|medium|low|none"
categories: ["backend", "frontend", "infrastructure"]
tags: ["go", "grpc", "templates"]
related_docs:
- "README.architecture.md"
- "README.development.md"
dependencies: []
llm_context: "high"
context_window_target: 300
---
```
### Required Fields
| Field | Description | Example |
| ----------------------- | ----------------------- | --------------------------------------------- |
| `name` | Short agent name | "Backend API Engineer" |
| `title` | Full title with context | "Backend API Engineer (Go/Fiber)" |
| `description` | One-line purpose | "Develops REST APIs using Go/Fiber framework" |
| `role_type` | Primary role category | "engineering", "design", "product" |
| `version` | Semantic version | "1.0.0" |
| `last_updated` | ISO date | "2025-10-25" |
| `llm_context` | AI relevance level | "high", "medium", "low" |
| `context_window_target` | Target line count | 300 |
### Optional Fields
| Field | Description | Example |
| -------------------------- | ------------------------- | ------------------------------------- |
| `author` | Creator/maintainer | "Backend Team" |
| `specialization` | Specific focus areas | ["REST APIs", "database integration"] |
| `technology_stack` | Technologies used | ["Go", "Fiber", "PostgreSQL"] |
| `system_integration_level` | Integration depth | "high", "medium", "low", "none" |
| `categories` | Organizational categories | ["backend", "api"] |
| `tags` | Searchable tags | ["go", "fiber", "rest"] |
| `related_docs` | Key documentation | ["README.architecture.md"] |
| `dependencies` | Required systems | ["sirius-api/"] |
## Agent Identity Structure
Each agent identity follows this structure (200-400 lines total):
### 1. Role Summary (2-3 sentences)
Clear, concise description of the agent's purpose and scope.
### 2. Key Documentation Links (5-10 critical docs)
Direct links to essential documentation for the role:
- Architecture documents
- Development workflows
- Testing systems
- Role-specific guides
### 3. Project Location (directory structure)
Show where this role's work lives in the codebase.
### 4. Core Responsibilities (bullet list)
Clear enumeration of what this role does:
- Primary tasks
- Secondary tasks
- Collaboration points
### 5. Technology Stack (tools, languages, frameworks)
Specific technologies this role uses:
- Programming languages
- Frameworks and libraries
- Tools and services
- Development environment
### 6. System Integration (conditional)
**Include when `system_integration_level` is medium or high:**
- Integration points with other services
- Protocols and communication patterns
- Data flows and dependencies
- Architecture diagrams (when relevant)
**Depth varies by level:**
- **High**: Detailed protocols, message formats, complete data flows
- **Medium**: Key integration points, high-level protocols
- **Low**: Minimal integration notes
- **None**: Omit this section
### 7. Development Workflow (common operations)
Standard processes for this role:
- Setup and initialization
- Daily development tasks
- Testing and validation
- Deployment procedures
### 8. Code Patterns & Best Practices (2-5 examples)
**Include inline code examples for roles with specific coding patterns:**
Show good vs bad patterns, idiomatic approaches, common pitfalls.
**Omit for non-coding roles** (product, design, documentation-focused).
### 9. Common Tasks (frequent operations)
Specific, actionable commands and procedures:
- Build commands
- Test commands
- Deployment commands
- Troubleshooting commands
### 10. Troubleshooting Quick Reference
Common issues and solutions:
- Error patterns
- Debugging commands
- Quick fixes
- Where to find help
## Role-Specific Customization
The universal template adapts to different role types:
### Engineering Roles
**Characteristics:**
- Detailed technology stack
- Code patterns and examples
- System integration details
- Build and test commands
**Examples:** Backend Engineer, Frontend Engineer, DevOps Engineer
### Design Roles
**Characteristics:**
- Design tools and workflows
- Component libraries and systems
- Collaboration processes
- Review and feedback cycles
**Examples:** UX Designer, UI Designer, Design System Engineer
### Product Roles
**Characteristics:**
- Product documentation
- Stakeholder interfaces
- Decision frameworks
- Metrics and analytics
**Examples:** Product Manager, Product Owner, Business Analyst
### Operations Roles
**Characteristics:**
- Infrastructure details
- Monitoring and alerting
- Incident response
- Capacity planning
**Examples:** SRE, Platform Engineer, Infrastructure Engineer
### QA Roles
**Characteristics:**
- Testing frameworks
- Test strategies
- Bug tracking workflows
- Quality metrics
**Examples:** QA Engineer, Test Automation Engineer
### Documentation Roles
**Characteristics:**
- Documentation systems
- Writing standards
- Publishing workflows
- Maintenance procedures
**Examples:** Technical Writer, Documentation Engineer
## Validation Requirements
Agent identities must pass automated validation before commit.
### Validation Checks
1. **YAML Front Matter**
- All required fields present
- Valid field values (enums)
- Proper format (dates, versions)
2. **Content Structure**
- Required sections present
- Role-appropriate sections
- Length constraints (200-400 lines warning)
3. **Documentation Links**
- Links to existing files
- Proper mdc: format
- No broken references
4. **Index Completeness**
- Agent listed in INDEX
- Metadata matches front matter
- Cross-references valid
### Running Validation
```bash
# Full validation
cd testing/container-testing
make lint-agents
# Quick validation
make lint-agents-quick
# Index validation
make lint-agent-index
# Complete validation
make validate-all
```
## Maintenance Standards
### Update Triggers
Update agent identities when:
- **Role responsibilities change**
- **Technology stack updates**
- **System architecture evolves**
- **Documentation structure changes**
- **Integration patterns shift**
- **Best practices improve**
### Version Management
- **Patch version** (1.0.0 → 1.0.1): Minor corrections, link updates
- **Minor version** (1.0.0 → 1.1.0): New sections, expanded content
- **Major version** (1.0.0 → 2.0.0): Role redefinition, structure changes
### Review Process
1. **Technical accuracy** - Verify all technical details
2. **Completeness** - Ensure all required sections present
3. **Clarity** - Check for clear, understandable language
4. **Validation** - Run automated validation
5. **Length check** - Confirm 200-400 line target
6. **Link verification** - Test all documentation links
## Integration with Development Workflow
### Pre-Commit Validation
The pre-commit hook automatically validates agent identities:
- Checks YAML front matter
- Validates required fields
- Verifies length constraints
- Updates index if needed
### CI/CD Integration
Agent validation is part of the complete validation suite:
```bash
make validate-all # Includes lint-agents
```
### Documentation System
Agent identities complement the documentation system:
- **Agent identities**: Role-specific context
- **Documentation**: Comprehensive technical details
- **Task files**: Project-specific state
- **Cursor rules**: Development guidelines
## Quality Assurance
### Pre-Publication Checklist
- [ ] YAML front matter complete and valid
- [ ] All required sections present
- [ ] Length within 200-400 lines
- [ ] Code examples tested (if applicable)
- [ ] Documentation links verified
- [ ] Role-appropriate content depth
- [ ] Integration level appropriate
- [ ] Validation scripts pass
- [ ] Listed in INDEX
- [ ] Cross-references valid
### Post-Publication
- Monitor usage patterns
- Collect feedback
- Update regularly with project evolution
- Track context window effectiveness
- Refine based on AI interaction quality
## Troubleshooting
### Common Issues
| Issue | Symptoms | Solution |
| -------------------- | ------------------------ | ------------------------------------------ |
| Missing front matter | Validation fails | Add complete YAML header |
| Invalid field values | Enum validation error | Check SPECIFICATION.md for valid values |
| Broken doc links | Link validation fails | Verify file paths, use correct mdc: format |
| Length violations | Warning about line count | Balance detail vs conciseness |
| Index mismatch | Index validation fails | Run lint-agent-index, update INDEX.md |
| Role ambiguity | Unclear responsibilities | Sharpen role definition, check examples |
### Debugging Commands
```bash
# Check agent status
cd testing/container-testing
make lint-agents
# Find agents by type
grep -r "role_type:" .cursor/agents/
# Check integration level distribution
grep -r "system_integration_level:" .cursor/agents/
# Validate specific agent
../../scripts/agent-identities/lint-agents.sh .cursor/agents/backend-api-engineer.agent.md
```
## Best Practices
### Writing Effective Agent Identities
1. **Start with role clarity** - Define boundaries clearly
2. **Link generously** - Reference comprehensive docs
3. **Show, don't tell** - Use code examples when relevant
4. **Balance detail** - Enough context, not too much
5. **Think fresh starts** - Would this enable a new conversation?
6. **Validate early** - Run scripts during development
7. **Review examples** - Study existing agents
8. **Test with AI** - Verify context effectiveness
### Maintaining Agent Identities
1. **Update proactively** - Don't wait for issues
2. **Version appropriately** - Follow semver guidelines
3. **Cross-reference** - Keep related agents in sync
4. **Monitor effectiveness** - Track AI interaction quality
5. **Gather feedback** - Learn from usage patterns
6. **Automate validation** - Trust the pre-commit hooks
---
_This document is the foundation of our agent identity system. Keep it updated as our practices evolve._
.cursor/agents/docs/GUIDE.creating-agent-identities.md
+754
View File
@@ -0,0 +1,754 @@
---
title: "Creating Agent Identities"
description: "Step-by-step guide to creating effective agent identities for the Sirius project"
template: "TEMPLATE.custom"
version: "1.0.0"
last_updated: "2025-10-25"
author: "Sirius Team"
tags: ["guide", "agent-identities", "creation", "howto"]
categories: ["ai-tooling", "documentation"]
difficulty: "intermediate"
prerequisites: ["ABOUT.agent-identities.md", "SPECIFICATION.agent-identity.md"]
related_docs:
- "ABOUT.agent-identities.md"
- "TEMPLATE.agent-identity.md"
- "SPECIFICATION.agent-identity.md"
- "REFERENCE.integration-levels.md"
dependencies: []
llm_context: "medium"
search_keywords:
["create agent", "agent howto", "agent guide", "writing agents"]
---
# Creating Agent Identities
Step-by-step guide to creating effective, validated agent identities for the Sirius project.
## Prerequisites
Before creating an agent identity, ensure you:
1. **Understand the system** - Read [ABOUT.agent-identities.md](mdc:.cursor/agents/ABOUT.agent-identities.md)
2. **Know the specification** - Review [SPECIFICATION.agent-identity.md](mdc:.cursor/agents/SPECIFICATION.agent-identity.md)
3. **Study the template** - Examine [TEMPLATE.agent-identity.md](mdc:.cursor/agents/TEMPLATE.agent-identity.md)
4. **Review examples** - Look at existing agents in [INDEX.agent-identities.md](mdc:.cursor/agents/INDEX.agent-identities.md)
5. **Understand integration levels** - Check [REFERENCE.integration-levels.md](mdc:.cursor/agents/REFERENCE.integration-levels.md)
## Step 1: Define the Role
### 1.1 Identify the Need
Ask yourself:
- What role or specialization is missing?
- Would this improve context shaping?
- Is this distinct from existing agents?
- Will it enable better fresh conversations?
**Good Reasons to Create an Agent:**
- New engineering specialization (e.g., "API Security Engineer")
- New technology adoption (e.g., "GraphQL Backend Engineer")
- New process role (e.g., "Release Manager")
- Refined specialization (e.g., splitting "Frontend Engineer" into "UI Engineer" and "State Management Engineer")
**Bad Reasons:**
- Temporary project need (use task files instead)
- One-time task (use conversation context)
- Too narrow (combine with existing agent)
- Duplicate existing agent
### 1.2 Choose Role Type
Select from valid role types:
- `engineering` - Software development, system building
- `design` - UX/UI design, design systems
- `product` - Product management, strategy
- `operations` - DevOps, SRE, infrastructure
- `qa` - Testing, quality assurance
- `documentation` - Technical writing, docs
**Example Decision:**
- **API Security Engineer** → `engineering` (writes code)
- **UX Researcher** → `design` (focuses on user experience)
- **Release Manager** → `operations` (manages deployments)
### 1.3 Determine Integration Level
Choose based on system knowledge needed:
- `none` - No system integration (pure UI design, documentation)
- `low` - Minimal (frontend consuming APIs)
- `medium` - Moderate (backend services, APIs)
- `high` - Deep (infrastructure, distributed systems)
See [REFERENCE.integration-levels.md](mdc:.cursor/agents/REFERENCE.integration-levels.md) for detailed guidelines.
## Step 2: Copy the Template
```bash
cd /Users/oz/Projects/Sirius-Project/Sirius/.cursor/agents
cp TEMPLATE.agent-identity.md your-role-name.agent.md
```
**Filename Rules:**
- Lowercase with hyphens
- Descriptive of role
- Must end with `.agent.md`
**Examples:**
- ✅ `api-security-engineer.agent.md`
- ✅ `release-manager.agent.md`
- ✅ `graphql-backend-engineer.agent.md`
- ❌ `API-Security.agent.md` (wrong case)
- ❌ `security.agent.md` (too vague)
## Step 3: Fill in YAML Front Matter
### 3.1 Required Fields
Open your new file and fill in required fields:
```yaml
---
name: "API Security Engineer"
title: "API Security Engineer (Go/REST/OAuth)"
description: "Implements API security, authentication, authorization, and security best practices"
role_type: "engineering"
version: "1.0.0"
last_updated: "2025-10-25"
llm_context: "high"
context_window_target: 320
```
**Tips:**
- `name`: 2-5 words, title case
- `title`: Include key technologies in parentheses
- `description`: Single sentence, action-oriented
- `role_type`: Must be valid enum
- `version`: Start with "1.0.0"
- `last_updated`: Today's date (ISO format)
- `context_window_target`: Estimate 200-400 range
### 3.2 Optional but Recommended
Add these for better discovery and context:
```yaml
author: "Security Team"
specialization: ["API security", "OAuth/JWT", "threat modeling"]
technology_stack: ["Go", "OAuth2", "JWT", "OpenAPI"]
system_integration_level: "medium"
categories: ["backend", "security"]
tags: ["security", "authentication", "authorization", "go"]
related_docs:
- "README.architecture.md"
- "README.api-security.md"
dependencies: ["sirius-api/"]
---
```
## Step 4: Write Role Summary
Replace the template's role summary with 2-3 sentences:
```markdown
# API Security Engineer (Go/REST/OAuth)
Implements and maintains security for Sirius REST APIs, focusing on authentication, authorization, and API security best practices. Works with Go/Fiber backend to integrate OAuth2, JWT, and secure API design patterns. Ensures compliance with security standards and performs threat modeling for API endpoints.
```
**Formula:**
1. **Sentence 1:** What they do and primary focus
2. **Sentence 2:** Technologies and integration points
3. **Sentence 3:** Additional responsibilities or scope
## Step 5: Link Key Documentation
Select 5-10 most critical documentation files for this role:
### Engineering Roles
**Always include:**
- System architecture
- Development workflow
- Container testing
- Role-specific technical docs
**Example:**
```markdown
## Key Documentation
### Architecture & Design
- [System Architecture](mdc:documentation/dev/architecture/README.architecture.md) - Overall system design
- [Docker Architecture](mdc:documentation/dev/architecture/README.docker-architecture.md) - Container infrastructure
- [API Design](mdc:documentation/dev/api/README.api-design.md) - API standards
### Development & Workflow
- [Development Workflow](mdc:documentation/dev/README.development.md) - Development standards
- [Container Testing](mdc:documentation/dev/test/README.container-testing.md) - Testing requirements
### Security-Specific
- [API Security Standards](mdc:documentation/dev/security/README.api-security.md) - Security requirements
- [OAuth Implementation](mdc:documentation/dev/security/README.oauth.md) - Authentication
- [Threat Modeling](mdc:documentation/dev/security/README.threat-modeling.md) - Security analysis
```
## Step 6: Define Project Location
Show where this role works in the codebase:
````markdown
## Project Location
\```
sirius-api/
├── internal/
│ ├── auth/ # Authentication middleware
│ │ ├── jwt.go # JWT handling
│ │ ├── oauth.go # OAuth2 integration
│ │ └── middleware.go # Auth middleware
│ ├── security/ # Security utilities
│ │ ├── rate_limit.go # Rate limiting
│ │ ├── cors.go # CORS configuration
│ │ └── validation.go # Input validation
│ └── api/ # API routes
│ └── middleware/ # API middleware
└── config/
└── security.yaml # Security configuration
\```
````
## Step 7: List Core Responsibilities
### Engineering Role Example
```markdown
## Core Responsibilities
### Primary Responsibilities
- **API Authentication** - Implement OAuth2, JWT, API key authentication
- **Authorization** - Role-based access control, permission systems
- **Security Middleware** - Rate limiting, input validation, CORS
- **Threat Modeling** - Identify and mitigate API security risks
### Secondary Responsibilities
- **Security Testing** - Automated security tests, vulnerability scanning
- **Security Documentation** - API security guides, best practices
- **Code Review** - Security-focused code reviews
### Collaboration Points
- **Backend API Engineer** - Security middleware integration, API design
- **Frontend Engineer** - OAuth flow, authentication UX
- **DevOps Engineer** - Secrets management, secure deployments
- **QA Engineer** - Security testing strategies
```
## Step 8: Document Technology Stack
```markdown
## Technology Stack
### Programming Languages
- **Go** - Primary language, version 1.21+
- **SQL** - Database security policies
### Frameworks & Libraries
- **Fiber** - v2.x, web framework with security middleware
- **golang-jwt** - v5.x, JWT implementation
- **oauth2** - Go OAuth2 library
- **bcrypt** - Password hashing
### Tools & Services
- **OAuth2 Providers** - Google, GitHub, custom
- **Secrets Management** - Environment variables, vaults
- **Security Scanners** - gosec, trivy
### Development Environment
- **Local Setup** - Go 1.21+, OAuth2 test apps
- **Container Environment** - `sirius-api` container
- **Dependencies** - PostgreSQL for user/session storage
```
## Step 9: System Integration (Conditional)
**Include only if `system_integration_level` is "medium" or "high".**
For our API Security Engineer (medium level):
````markdown
## System Integration
### Integration Architecture
API Security layer sits between external requests and application logic, protecting all API endpoints.
\```
┌─────────────────────────────────────────┐
│ External Clients │
└────────────────┬────────────────────────┘
│
│ HTTPS
▼
┌───────────────┐
│ API Gateway │
│ (Security) │
└───────┬───────┘
│
┌────────────┼────────────┐
│ │ │
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│ Auth │ │ Rate │ │ CORS │
│ Middle │ │ Limit │ │ Middle │
└────┬───┘ └────┬───┘ └────┬───┘
│ │ │
└───────────┼───────────┘
│
▼
┌───────────────┐
│ Application │
│ Logic │
└───────────────┘
\```
### Communication Protocols
- **OAuth2** - Authorization code flow, client credentials
- **JWT** - Token-based authentication, RS256 signing
- **HTTPS** - TLS 1.2+ for all communications
### Key Integration Points
- **Authentication Middleware** - All API routes protected
- **Session Storage** - PostgreSQL for session management
- **Token Validation** - JWT verification on each request
````
## Step 10: Development Workflow
````markdown
## Development Workflow
### Setup & Initialization
\```bash
# Navigate to API directory
cd sirius-api
# Install dependencies
go mod download
# Configure security settings
cp config/security.example.yaml config/security.yaml
# Edit with OAuth2 credentials, JWT secrets
# Start development environment
docker compose -f docker-compose.dev.yaml up -d sirius-api
\```
### Daily Development Tasks
\```bash
# Run with live reload
air
# View security logs
docker compose logs -f sirius-api | grep -i "auth\|security"
# Test authentication
curl -H "Authorization: Bearer \$TOKEN" http://localhost:9001/api/protected
\```
### Testing & Validation
\```bash
# Run security tests
go test ./internal/auth/... ./internal/security/...
# Run static security analysis
gosec ./...
# Scan for vulnerabilities
trivy fs .
# Test OAuth flow
go test ./internal/auth/oauth_test.go -v
\```
````
## Step 11: Code Patterns (Engineering Roles Only)
Include 2-5 key patterns with good/bad examples:
````markdown
## Code Patterns & Best Practices
### Pattern 1: JWT Middleware
Always validate JWT tokens before processing requests:
\```go
// ✅ GOOD: Proper JWT validation with error handling
func JWTMiddleware(secret string) fiber.Handler {
return func(c \*fiber.Ctx) error {
authHeader := c.Get("Authorization")
if authHeader == "" {
return c.Status(401).JSON(fiber.Map{"error": "missing authorization"})
}
token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
// Validate signing method
if _, ok := token.Method.(*jwt.SigningMethodRSA); !ok {
return nil, fmt.Errorf("unexpected signing method")
}
return signingKey, nil
})
if err != nil || !token.Valid {
return c.Status(401).JSON(fiber.Map{"error": "invalid token"})
}
c.Locals("user", token.Claims)
return c.Next()
}
}
// ❌ BAD: No validation, security vulnerabilities
func BadJWTMiddleware() fiber.Handler {
return func(c \*fiber.Ctx) error {
token := c.Get("Authorization")
// Skipping validation - NEVER DO THIS
c.Locals("user", token)
return c.Next()
}
}
\```
### Pattern 2: Rate Limiting
\```go
// ✅ GOOD: Proper rate limiting with sliding window
func RateLimitMiddleware(limit int, window time.Duration) fiber.Handler {
store := NewInMemoryStore()
return func(c *fiber.Ctx) error {
clientID := c.IP() // Or use user ID for authenticated requests
count, err := store.Increment(clientID, window)
if err != nil {
return c.Status(500).SendString("rate limit error")
}
if count > limit {
return c.Status(429).JSON(fiber.Map{
"error": "rate limit exceeded",
"retry_after": window.Seconds(),
})
}
return c.Next()
}
}
\```
````
## Step 12: Common Tasks
````markdown
## Common Tasks
### Authentication Tasks
#### Task 1: Generate JWT Token
\```bash
# For testing, generate a JWT token
go run ./cmd/generate-token/main.go --user-id=123 --email=test@example.com
\```
#### Task 2: Test OAuth Flow
\```bash
# Start OAuth test server
go run ./cmd/oauth-test/main.go
# Navigate to: http://localhost:8080/auth/google
# Complete OAuth flow and verify token
\```
### Security Tasks
#### Task 3: Run Security Scan
\```bash
# Static analysis
gosec ./...
# Dependency scan
trivy fs . --severity HIGH,CRITICAL
# Check for secrets in code
gitleaks detect --source . --verbose
\```
#### Task 4: Update Security Configuration
\```bash
# Rotate JWT signing keys
./scripts/rotate-jwt-keys.sh
# Update OAuth credentials
vi config/security.yaml
# Restart API service
docker compose restart sirius-api
\```
````
## Step 13: Troubleshooting Section
````markdown
## Troubleshooting Quick Reference
### Common Issues
| Issue | Symptoms | Solution |
| ------------------------------ | ---------------------------------- | ---------------------------------------------- |
| **Invalid JWT** | 401 errors on authenticated routes | Check token expiration, verify signing key |
| **OAuth callback fails** | Redirect errors after login | Verify callback URL in OAuth provider settings |
| **Rate limit false positives** | 429 errors for legitimate requests | Adjust rate limits in config/security.yaml |
| **CORS errors** | Preflight failures in browser | Update CORS configuration for allowed origins |
### Debugging Commands
\```bash
# Check JWT token validity
echo "$TOKEN" | jwt decode -
# View security logs
docker compose logs sirius-api | grep -i "auth\|jwt\|oauth"
# Test API authentication
curl -v -H "Authorization: Bearer $TOKEN" http://localhost:9001/api/test
# Check rate limit status
redis-cli get "ratelimit:$CLIENT_IP"
\```
### Quick Fixes
**Problem:** JWT token expired
**Solution:**
\```bash
# Generate new token
TOKEN=$(go run ./cmd/generate-token/main.go --user-id=123)
export TOKEN
\```
### When to Escalate
- **OAuth provider issues** - Contact provider support, check service status
- **Suspected security breach** - Immediately notify security team, rotate credentials
- **Performance degradation** - Check rate limits, review security middleware performance
````
## Step 14: Validate Your Agent
Before committing, run validation:
```bash
cd /Users/oz/Projects/Sirius-Project/Sirius/testing/container-testing
# Full validation
make lint-agents
# Quick check
make lint-agents-quick
```
**Fix any errors reported by the linter.**
## Step 15: Update the Index
Add your agent to [INDEX.agent-identities.md](mdc:.cursor/agents/INDEX.agent-identities.md):
1. **Quick Reference table** - Add row with agent info
2. **By Role Type section** - Add under appropriate role type
3. **Complete List** - Add alphabetically
4. **Agent Relationships** - Document integration points
5. **Statistics** - Update counts
Then validate the index:
```bash
make lint-agent-index
```
## Step 16: Test with AI
Create a test conversation using your new agent identity:
1. Start a new AI conversation
2. Reference your agent identity file
3. Give it a task appropriate for the role
4. Verify the AI:
- Understands the role boundaries
- References correct documentation
- Follows appropriate patterns
- Provides accurate guidance
If the agent is ineffective:
- **Too vague?** Add more specific patterns and examples
- **Too detailed?** Reduce to essential information, link to docs
- **Wrong focus?** Refine role summary and responsibilities
- **Missing context?** Add relevant documentation links
## Best Practices
### Do
- ✅ Study existing agents before creating new ones
- ✅ Keep within 200-400 line target
- ✅ Include concrete examples for engineering roles
- ✅ Link to comprehensive documentation
- ✅ Use appropriate integration level
- ✅ Validate before committing
- ✅ Test with actual AI conversations
### Don't
- ❌ Create agents for temporary needs
- ❌ Duplicate existing agent functionality
- ❌ Include implementation details (link to docs instead)
- ❌ Exceed 500 lines (maximum limit)
- ❌ Skip YAML validation
- ❌ Forget to update the index
- ❌ Commit without testing
## Common Pitfalls
### Too Broad
**Problem:** Agent tries to cover too much
**Example:** "Full Stack Engineer" covering frontend, backend, database, DevOps
**Solution:** Split into focused agents (Frontend Engineer, Backend Engineer, etc.)
### Too Narrow
**Problem:** Agent is too specific
**Example:** "Button Component Engineer" only handling button components
**Solution:** Broaden to "UI Component Engineer" covering all UI components
### Too Long
**Problem:** Agent exceeds 500 lines
**Solution:**
- Remove implementation details (link to docs)
- Reduce code examples (2-5 key patterns only)
- Condense workflow sections
- Use tables for common issues
### Missing Context
**Problem:** Agent lacks key information
**Solution:**
- Add essential documentation links
- Include critical patterns
- Document integration points
- Provide troubleshooting info
## Quick Start Checklist
- [ ] Read ABOUT, SPECIFICATION, and TEMPLATE
- [ ] Define role and determine role_type
- [ ] Choose appropriate integration level
- [ ] Copy template with correct filename
- [ ] Fill in complete YAML front matter
- [ ] Write clear 2-3 sentence role summary
- [ ] Link 5-10 key documentation files
- [ ] Define project location
- [ ] List core responsibilities
- [ ] Document technology stack
- [ ] Add system integration (if applicable)
- [ ] Document development workflow
- [ ] Include code patterns (engineering only)
- [ ] Provide common tasks
- [ ] Add troubleshooting section
- [ ] Run validation scripts
- [ ] Update INDEX.agent-identities.md
- [ ] Validate index
- [ ] Test with AI conversation
- [ ] Commit and push
---
_Follow this guide to create consistent, validated, effective agent identities. For questions, see [ABOUT.agent-identities.md](mdc:.cursor/agents/ABOUT.agent-identities.md)._
.cursor/agents/docs/INDEX.agent-identities.md
+300
View File
@@ -0,0 +1,300 @@
---
title: "Agent Identity Index"
description: "Central registry of all Sirius agent identities organized by role type"
template: "TEMPLATE.custom"
version: "1.0.0"
last_updated: "2025-10-25"
author: "Sirius Team"
tags: ["index", "agent-identities", "registry"]
categories: ["ai-tooling", "documentation"]
difficulty: "beginner"
prerequisites: []
related_docs:
- "ABOUT.agent-identities.md"
- "TEMPLATE.agent-identity.md"
- "SPECIFICATION.agent-identity.md"
dependencies: []
llm_context: "high"
search_keywords: ["agent index", "agent list", "agent registry"]
---
# Agent Identity Index
Central registry of all agent identities in the Sirius project. Use this index to discover available agents and their specializations.
## Quick Reference
| Agent | Role Type | Integration Level | Status |
| ---------------------------------------------------------------------------------- | ------------- | ----------------- | ------------- |
| [Backend API Engineer](mdc:.cursor/agents/backend-api-engineer.agent.md) | engineering | medium | ✅ Active |
| [CI/CD Engineer](mdc:.cursor/agents/cicd-engineer.agent.md) | operations | medium | ✅ Active |
| [Database Storage Engineer](mdc:.cursor/agents/database-storage-engineer.agent.md) | engineering | medium | ✅ Active |
| [DevOps Platform Engineer](mdc:.cursor/agents/devops-platform-engineer.agent.md) | operations | high | ✅ Active |
| [Engine Scanner Engineer](mdc:.cursor/agents/engine-scanner-engineer.agent.md) | engineering | medium | ✅ Active |
| [Frontend Engineer](mdc:.cursor/agents/frontend-engineer.agent.md) | engineering | low | ✅ Active |
| [Project Task Coordinator](mdc:.cursor/agents/project-task-coordinator.agent.md) | product | none | ✅ Active |
| [QA Test Engineer](mdc:.cursor/agents/qa-test-engineer.agent.md) | qa | low | ✅ Active |
| [Remote Agent Engineer](mdc:.cursor/commands/remote-agent-engineer.agent.md) | engineering | high | 🔄 Converting |
| [Scanner UI Engineer](mdc:.cursor/agents/scanner-ui-engineer.agent.md) | engineering | low | ✅ Active |
| [Security Template Curator](mdc:.cursor/agents/security-template-curator.agent.md) | documentation | none | ✅ Active |
| [SRE Monitoring Engineer](mdc:.cursor/agents/sre-monitoring-engineer.agent.md) | operations | high | ✅ Active |
| [Maintainer Ops](mdc:.cursor/commands/bot-maintainer-ops.md) | operations | high | ✅ Active |
| [GitHub Commits](mdc:.cursor/commands/bot-github-commits.md) | operations | medium | ✅ Active |
| [System Architect](mdc:.cursor/agents/system-architect.agent.md) | engineering | high | ✅ Active |
| [Technical Writer](mdc:.cursor/agents/technical-writer.agent.md) | documentation | none | ✅ Active |
## By Role Type
### Engineering
Agents focused on software development, system building, and technical implementation.
#### Backend Engineers
- **[Backend API Engineer](mdc:.cursor/agents/backend-api-engineer.agent.md)**
- Specialization: Go/Fiber REST APIs, PostgreSQL, Valkey, RabbitMQ
- Integration: Medium (API layer, database, message queue)
- Tech Stack: Go, Fiber, PostgreSQL, Valkey, RabbitMQ
- **[Remote Agent Engineer](mdc:.cursor/commands/remote-agent-engineer.agent.md)**
- Specialization: gRPC agent-server architecture, template system, vulnerability detection
- Integration: High (gRPC, RabbitMQ, Valkey, template sync)
- Tech Stack: Go, gRPC, Protocol Buffers, Valkey, RabbitMQ
- **[Database Storage Engineer](mdc:.cursor/agents/database-storage-engineer.agent.md)**
- Specialization: PostgreSQL, database design, migrations, performance
- Integration: Medium (database layer, data models)
- Tech Stack: PostgreSQL, Prisma, SQL
#### Frontend Engineers
- **[Frontend Engineer](mdc:.cursor/agents/frontend-engineer.agent.md)**
- Specialization: Next.js, TypeScript, React, Tailwind CSS
- Integration: Low (API consumption, UI components)
- Tech Stack: Next.js, TypeScript, React, Tailwind, tRPC
- **[Scanner UI Engineer](mdc:.cursor/agents/scanner-ui-engineer.agent.md)**
- Specialization: Scanner interface, scan management, results visualization
- Integration: Low (API consumption for scans)
- Tech Stack: Next.js, TypeScript, React, Tailwind
#### Infrastructure Engineers
- **[Engine Scanner Engineer](mdc:.cursor/agents/engine-scanner-engineer.agent.md)**
- Specialization: Vulnerability scanning, nmap, rustscan, naabu integration
- Integration: Medium (message queues, scan orchestration)
- Tech Stack: Go, nmap, rustscan, naabu, RabbitMQ
- **[System Architect](mdc:.cursor/agents/system-architect.agent.md)**
- Specialization: System architecture, microservices, data flows, cross-cutting design
- Integration: High (entire system, all services)
- Tech Stack: Architecture patterns, Docker, microservices
### Operations
Agents focused on infrastructure, deployment, and system reliability.
- **[DevOps Platform Engineer](mdc:.cursor/agents/devops-platform-engineer.agent.md)**
- Specialization: Docker, container orchestration, deployment automation
- Integration: High (entire platform, all containers)
- Tech Stack: Docker, Docker Compose, bash, infrastructure tools
- **[CI/CD Engineer](mdc:.cursor/agents/cicd-engineer.agent.md)**
- Specialization: Build pipelines, automated testing, deployment workflows
- Integration: Medium (CI/CD systems, build processes)
- Tech Stack: GitHub Actions, testing frameworks, deployment tools
- **[SRE Monitoring Engineer](mdc:.cursor/agents/sre-monitoring-engineer.agent.md)**
- Specialization: System monitoring, alerting, observability, incident response
- Integration: High (monitoring all services, metrics collection)
- Tech Stack: Monitoring tools, metrics systems, alerting platforms
- **[Maintainer Ops](mdc:.cursor/commands/bot-maintainer-ops.md)**
- Specialization: Issue triage taxonomy, ChatOps command handling, evidence-driven review
- Integration: High (issues, PRs, workflows, runbooks, test evidence)
- Tech Stack: GitHub Actions, issue forms, labels, container/security test harnesses
- **[GitHub Commits](mdc:.cursor/commands/bot-github-commits.md)**
- Specialization: Commit scope control, selective staging, safe push/release hygiene
- Integration: Medium (git workflow + CI hooks + release discipline)
- Tech Stack: Git, GitHub, GitHub Actions, repository policy workflows
### QA
Agents focused on quality assurance, testing, and validation.
- **[QA Test Engineer](mdc:.cursor/agents/qa-test-engineer.agent.md)**
- Specialization: Test strategies, test automation, quality metrics
- Integration: Low (test interfaces, validation)
- Tech Stack: Testing frameworks, Playwright, container testing
### Product
Agents focused on product management, coordination, and stakeholder communication.
- **[Project Task Coordinator](mdc:.cursor/agents/project-task-coordinator.agent.md)**
- Specialization: Task management, project planning, coordination
- Integration: None (process-focused, not technical)
- Tech Stack: Task Master CLI, project management tools
### Documentation
Agents focused on technical writing, documentation, and knowledge management.
- **[Technical Writer](mdc:.cursor/agents/technical-writer.agent.md)**
- Specialization: Technical documentation, API docs, user guides
- Integration: None (documentation-focused)
- Tech Stack: Markdown, documentation systems, templates
- **[Security Template Curator](mdc:.cursor/agents/security-template-curator.agent.md)**
- Specialization: Vulnerability templates, CVE tracking, template validation
- Integration: None (template content focused)
- Tech Stack: YAML, vulnerability databases, CVE resources
## Complete List
### System Files
- [ABOUT.agent-identities.md](mdc:.cursor/agents/ABOUT.agent-identities.md) - Agent identity system documentation
- [TEMPLATE.agent-identity.md](mdc:.cursor/agents/TEMPLATE.agent-identity.md) - Universal agent identity template
- [SPECIFICATION.agent-identity.md](mdc:.cursor/agents/SPECIFICATION.agent-identity.md) - Technical specification
- [INDEX.agent-identities.md](mdc:.cursor/agents/INDEX.agent-identities.md) - This index
- [GUIDE.creating-agent-identities.md](mdc:.cursor/agents/GUIDE.creating-agent-identities.md) - Creation guide
- [REFERENCE.integration-levels.md](mdc:.cursor/agents/REFERENCE.integration-levels.md) - Integration patterns
### Active Agents (Alphabetical)
1. **Backend API Engineer** - `backend-api-engineer.agent.md`
2. **CI/CD Engineer** - `cicd-engineer.agent.md`
3. **Database Storage Engineer** - `database-storage-engineer.agent.md`
4. **DevOps Platform Engineer** - `devops-platform-engineer.agent.md`
5. **Engine Scanner Engineer** - `engine-scanner-engineer.agent.md`
6. **Frontend Engineer** - `frontend-engineer.agent.md`
7. **Project Task Coordinator** - `project-task-coordinator.agent.md`
8. **QA Test Engineer** - `qa-test-engineer.agent.md`
9. **Remote Agent Engineer** - `remote-agent-engineer.agent.md` (in `.cursor/commands/`)
10. **Scanner UI Engineer** - `scanner-ui-engineer.agent.md`
11. **Security Template Curator** - `security-template-curator.agent.md`
12. **SRE Monitoring Engineer** - `sre-monitoring-engineer.agent.md`
13. **System Architect** - `system-architect.agent.md`
14. **Technical Writer** - `technical-writer.agent.md`
## Agent Relationships
### Service-Level Integration
```
┌─────────────────────────────────────────────┐
│ System Architect │
│ (High-level coordination) │
└─────────────┬───────────────────────────────┘
│
┌─────────┼─────────┬─────────┐
│ │ │ │
┌───▼────┐ ┌──▼───┐ ┌──▼───┐ ┌───▼────┐
│Frontend│ │Backend│ │Engine│ │DevOps │
│Engineer│ │ API │ │Scanner│ │Platform│
└────────┘ └──┬────┘ └──────┘ └───┬────┘
│ │
┌───▼────┐ ┌────▼───┐
│Database│ │ SRE │
│Storage │ │Monitor │
└────────┘ └────────┘
```
### Development Workflow
- **System Architect** ↔ All engineering agents (architecture decisions)
- **Backend API Engineer** ↔ **Frontend Engineer** (API contracts)
- **Backend API Engineer** ↔ **Database Storage Engineer** (data models)
- **Engine Scanner Engineer** ↔ **Backend API Engineer** (scan coordination)
- **DevOps Platform Engineer** ↔ All engineers (deployment)
- **QA Test Engineer** ↔ All engineers (quality validation)
- **Technical Writer** ↔ All engineers (documentation)
### Specialized Relationships
- **Remote Agent Engineer** ↔ **Backend API Engineer** (gRPC to REST translation)
- **Scanner UI Engineer** ↔ **Engine Scanner Engineer** (scan interface)
- **Security Template Curator** ↔ **Remote Agent Engineer** (template system)
- **SRE Monitoring Engineer** ↔ **DevOps Platform Engineer** (observability)
- **Project Task Coordinator** ↔ All agents (task management)
## Statistics
**Total Agents:** 16 active + 6 system files
**By Role Type:**
- Engineering: 7 agents (50%)
- Operations: 5 agents (31%)
- QA: 1 agent (7%)
- Product: 1 agent (7%)
- Documentation: 2 agents (14%)
**By Integration Level:**
- High: 4 agents (29%)
- Medium: 5 agents (36%)
- Low: 3 agents (21%)
- None: 2 agents (14%)
**Average Context Window Target:** ~280 lines
## Using This Index
### Finding the Right Agent
1. **By Technology**: Search for your tech stack (e.g., "Go", "React", "Docker")
2. **By Role Type**: Browse the role type sections
3. **By Integration Level**: Check agents with appropriate system knowledge
4. **By Specialization**: Look at specific focus areas
### Starting a Conversation
When starting a new AI conversation:
1. Identify the appropriate agent for your task
2. Reference the agent identity file in your prompt
3. Provide task-specific context beyond the agent identity
4. Let the agent guide you through the workflow
### Creating New Agents
See [GUIDE.creating-agent-identities.md](mdc:.cursor/agents/GUIDE.creating-agent-identities.md) for complete instructions on creating new agent identities.
## Maintenance
### Last Index Update
**Date:** 2025-10-25
**Updated By:** Sirius Team
**Changes:** Initial index creation
### Validation
Run index validation:
```bash
cd testing/container-testing
make lint-agent-index
```
### Adding New Agents
1. Create agent using [TEMPLATE.agent-identity.md](mdc:.cursor/agents/TEMPLATE.agent-identity.md)
2. Validate with `make lint-agents`
3. Add entry to this index
4. Verify with `make lint-agent-index`
5. Update statistics and relationships
---
_This index is automatically validated by the agent identity linting system. Last validated: 2025-10-25_
.cursor/agents/docs/REFERENCE.integration-levels.md
+858
View File
@@ -0,0 +1,858 @@
---
title: "Integration Levels Reference"
description: "Complete reference for system integration levels in agent identities"
template: "TEMPLATE.custom"
version: "1.0.0"
last_updated: "2025-10-25"
author: "Sirius Team"
tags: ["reference", "integration", "system-architecture"]
categories: ["ai-tooling", "architecture"]
difficulty: "intermediate"
prerequisites: ["ABOUT.agent-identities.md", "SPECIFICATION.agent-identity.md"]
related_docs:
- "ABOUT.agent-identities.md"
- "SPECIFICATION.agent-identity.md"
- "GUIDE.creating-agent-identities.md"
- "README.architecture.md"
dependencies: []
llm_context: "medium"
search_keywords:
["integration levels", "system integration", "architecture depth"]
---
# Integration Levels Reference
Complete guide to determining and implementing appropriate system integration levels for agent identities.
## Integration Level Overview
| Level | Focus | System Knowledge | Architecture Detail | Protocol Knowledge | Use Cases |
| ---------- | --------------------- | ------------------ | --------------------- | -------------------------- | ----------------------------------- |
| **none** | Isolated work | None required | None | None | UI design, documentation, product |
| **low** | Interface consumption | API contracts | High-level overview | HTTP/REST basics | Frontend, simple services |
| **medium** | Service integration | Service boundaries | Component diagrams | REST, basic message queues | Backend APIs, middleware |
| **high** | System architecture | End-to-end flows | Detailed architecture | All protocols, data flows | Infrastructure, distributed systems |
## None - Isolated Work
### Characteristics
Agents with no system integration work independently without needing to understand how services connect or communicate.
### When to Use
- **Pure UI/UX Design**: Design systems, component libraries, visual design
- **Documentation**: Technical writing, API docs without implementation
- **Product Management**: Feature planning, stakeholder communication
- **Content Creation**: Marketing content, user guides
### What to Include
**Required Sections:**
- Role summary
- Key documentation (design/product focused)
- Core responsibilities
- Tools and workflows (design tools, document systems)
- Common tasks (design/writing tasks)
- Troubleshooting (tool-specific issues)
**Omit:**
- System Integration section
- Protocol details
- Architecture diagrams
- Technical data flows
### Example Agents
#### UX Designer
```yaml
system_integration_level: "none"
specialization: ["user research", "wireframing", "prototyping"]
technology_stack: ["Figma", "Miro", "UserTesting"]
```
**Focus:**
- Design tools and workflows
- User research methods
- Prototyping and testing
- Collaboration with engineering
**No need to understand:**
- API implementation
- Database structure
- Service communication
- Infrastructure
#### Technical Writer
```yaml
system_integration_level: "none"
specialization: ["API documentation", "user guides", "tutorials"]
technology_stack: ["Markdown", "documentation systems", "diagrams"]
```
**Focus:**
- Documentation standards
- Writing workflows
- Publishing systems
- Content organization
**No need to understand:**
- How services communicate
- Implementation details
- Protocol specifics
- Infrastructure setup
## Low - Interface Consumption
### Characteristics
Agents that consume interfaces (usually APIs) but don't need deep understanding of implementation or inter-service communication.
### When to Use
- **Frontend Engineers**: Consuming REST/GraphQL APIs
- **Simple Services**: Single-purpose microservices
- **QA Engineers**: Testing interfaces without implementation knowledge
- **Integration Scripts**: Simple automation consuming APIs
### What to Include
**System Integration Section (Brief):**
```markdown
## System Integration
### Integration Overview
Consumes Sirius REST APIs for data retrieval and user actions.
### Communication
- **REST APIs**: Standard HTTP requests to backend services
- **Authentication**: JWT tokens in Authorization header
- **Data Format**: JSON request/response
### Key Integration Points
- `/api/scans` - Scan management
- `/api/vulnerabilities` - Vulnerability data
- `/api/agents` - Agent information
```
**Keep It High-Level:**
- API endpoints used
- Authentication method
- Data format
- No protocol implementation details
- No inter-service communication
### Example Agents
#### Frontend Engineer
```yaml
system_integration_level: "low"
specialization: ["React", "Next.js", "UI components"]
technology_stack: ["TypeScript", "React", "Next.js", "Tailwind"]
```
**Integration Section:**
```markdown
## System Integration
### Integration Overview
Frontend consumes Sirius API via tRPC for type-safe communication.
### Communication
- **tRPC**: Type-safe API calls
- **Authentication**: Session-based with JWT
- **Real-time**: WebSocket for scan updates
### Key Endpoints
- `scan.start` - Initiate vulnerability scans
- `scan.getResults` - Retrieve scan results
- `agent.list` - Get connected agents
```
**What They Need:**
- API contracts and types
- Authentication flow
- Error handling patterns
- Real-time update mechanisms
**What They Don't Need:**
- How backend processes requests
- Database schema
- Message queue implementation
- Service-to-service communication
## Medium - Service Integration
### Characteristics
Agents that implement services requiring understanding of adjacent services, protocols, and integration patterns.
### When to Use
- **Backend API Engineers**: Building REST/GraphQL APIs
- **Service Engineers**: Implementing microservices
- **DevOps Engineers**: Service deployment and orchestration
- **Integration Engineers**: Connecting multiple services
### What to Include
**System Integration Section (Detailed):**
```markdown
## System Integration
### Integration Architecture
[Component diagram showing service + adjacent services]
### Communication Protocols
- **REST**: Detailed endpoint specifications
- **Message Queue**: Queue names, message formats
- **Database**: Connection patterns, transaction handling
### Data Flows
Key data flows with processing steps
### Key Integration Points
Detailed integration with specific services
```
**Level of Detail:**
- Component-level architecture
- Protocol specifications
- Message formats
- Data flow diagrams
- Error handling patterns
- Integration testing approaches
### Example Agents
#### Backend API Engineer
```yaml
system_integration_level: "medium"
specialization: ["REST APIs", "database integration", "message queues"]
technology_stack: ["Go", "Fiber", "PostgreSQL", "RabbitMQ"]
```
**Integration Section:**
````markdown
## System Integration
### Integration Architecture
\```
┌──────────────┐
│ sirius-ui │
└──────┬───────┘
│ REST/tRPC
▼
┌──────────────────┐
│ sirius-api │◄────── RabbitMQ ────────► sirius-engine
│ (This Service) │
└──────┬───────────┘
│ SQL
▼
┌──────────────┐
│ PostgreSQL │
└──────────────┘
\```
### Communication Protocols
**REST API:**
- Exposes HTTP endpoints for UI
- Authentication via JWT middleware
- JSON request/response format
- Standard HTTP status codes
**RabbitMQ Integration:**
- Queue: `scan_requests` - Receives scan jobs
- Queue: `scan_results` - Publishes results
- Message format: JSON with schema validation
**Database:**
- PostgreSQL connection pool
- Transaction management for consistency
- Prepared statements for security
### Data Flows
**Scan Request Flow:**
1. UI → POST /api/scans → sirius-api
2. sirius-api validates and stores in PostgreSQL
3. sirius-api publishes to RabbitMQ `scan_requests`
4. sirius-engine consumes and processes
5. Results published to `scan_results`
6. sirius-api receives and updates PostgreSQL
7. UI receives update via WebSocket
### Key Integration Points
- **Frontend Integration**: tRPC router, type-safe contracts
- **Engine Integration**: RabbitMQ message queue
- **Database Integration**: PostgreSQL with Prisma
- **Cache Integration**: Valkey for session and rate limiting
````
**What They Need:**
- Service boundaries
- Protocol details
- Message formats
- Data flow understanding
- Integration patterns
- Error handling across services
**What They Don't Need:**
- Complete system architecture
- All service implementations
- Infrastructure details
- Deployment mechanisms
## High - System Architecture
### Characteristics
Agents requiring deep understanding of entire system, all protocols, complete data flows, and infrastructure.
### When to Use
- **System Architects**: Overall system design
- **Infrastructure Engineers**: Platform management
- **SRE Engineers**: Monitoring all services
- **Agent Engineers**: Complex distributed agent systems
- **Platform Engineers**: Cross-cutting infrastructure
### What to Include
**System Integration Section (Comprehensive):**
```markdown
## System Integration
### Complete System Architecture
[Full system diagram with all services]
### Detailed Communication Protocols
Complete specifications for all protocols used:
- gRPC with protobuf definitions
- REST with complete API specs
- Message queues with all queue/exchange details
- WebSocket patterns
- Database access patterns
### Complete Data Flows
End-to-end flows for all major operations with:
- Every service touched
- Every protocol used
- Every transformation step
- Error handling at each stage
- Performance considerations
### All Integration Points
Comprehensive documentation of every service integration
```
**Level of Detail:**
- Complete system architecture
- All protocols with specifications
- Message formats with schemas
- Complete data flow diagrams
- Infrastructure details
- Deployment architecture
- Monitoring and observability
- Security boundaries
- Performance characteristics
### Example Agents
#### System Architect
```yaml
system_integration_level: "high"
specialization: ["microservices", "data flows", "cross-cutting design"]
technology_stack: ["architecture patterns", "Docker", "system design"]
```
**Integration Section:**
````markdown
## System Integration
### Complete System Architecture
\```
┌─────────────────────────────────────────────────┐
│ External │
│ ┌────────────┐ │
│ │ Users │ │
│ └─────┬──────┘ │
└────────────────────┼────────────────────────────┘
│ HTTPS
▼
┌──────────────┐
│ sirius-ui │
│ (Next.js) │
└──────┬───────┘
│
┌────────────┼────────────┐
│ tRPC/HTTP │ │ WebSocket
▼ ▼ ▼
┌──────────────┐ ┌─────────────────────────┐
│ sirius-api │ │ Event System │
│ (Go/Fiber) │ │ │
└──────┬───────┘ └─────────────────────────┘
│
├─────► PostgreSQL (SQL)
├─────► Valkey (Redis Protocol)
└─────► RabbitMQ (AMQP)
│
│ Message Queue
▼
┌──────────────┐
│sirius-engine │
│ (Go) │
└──────┬───────┘
│
┌────────────┼────────────┬─────────────┐
│ │ │ │
▼ ▼ ▼ ▼
┌────────┐ ┌─────────┐ ┌────────┐ ┌──────────┐
│ nmap │ │ rustscan│ │ naabu │ │ agents │
└────────┘ └─────────┘ └────────┘ └────┬─────┘
│ gRPC
▼
┌─────────────┐
│agent-server │
│ (Go) │
└─────────────┘
\```
### Detailed Communication Protocols
**HTTP/tRPC (UI ↔ API):**
- Transport: HTTPS with TLS 1.2+
- Protocol: tRPC over HTTP POST
- Authentication: JWT in Authorization header
- Payload: JSON with Zod schema validation
- Error Handling: Typed tRPC errors
- Rate Limiting: 100 req/min per IP
**AMQP (API ↔ Engine via RabbitMQ):**
- Protocol: AMQP 0.9.1
- Exchanges:
- `scans.direct` (direct): Scan requests
- `results.fanout` (fanout): Scan results broadcast
- Queues:
- `scan.requests`: Durable, persistent messages
- `scan.results.api`: API-specific results
- `scan.results.events`: Event system feed
- Message Format: JSON with schema
\```json
{
"scan_id": "uuid",
"type": "nmap|rustscan|agent",
"target": "ip/hostname",
"config": {...}
}
\```
- Retry Policy: Exponential backoff, 3 attempts
- Dead Letter Queue: `scan.failed`
**gRPC (Engine ↔ Agent Server):**
- Protocol: gRPC with Protocol Buffers v3
- Service Definition:
\```protobuf
service HelloService {
rpc ConnectStream(stream AgentMessage)
returns (stream ServerMessage);
rpc Ping(PingRequest) returns (PingResponse);
}
\```
- Transport: HTTP/2 over TLS
- Authentication: Metadata-based agent ID
- Streaming: Bidirectional for heartbeat + commands
- Keepalive: 30s interval, 10s timeout
**SQL (API ↔ PostgreSQL):**
- Driver: pgx (PostgreSQL native)
- Connection Pool: 10-20 connections
- Transaction Isolation: Read Committed
- Migrations: Managed via Prisma
- Query Pattern: Prepared statements
- Performance: Indexed queries, EXPLAIN analysis
**Redis Protocol (API/Engine ↔ Valkey):**
- Protocol: RESP3 (Redis Serialization Protocol)
- Connection: Connection pooling
- Use Cases:
- Session storage: 24h TTL
- Rate limiting: Sliding window
- Template caching: 1h TTL
- Result caching: 5min TTL
- Data Structures: Strings, Hashes, Sets, Sorted Sets
### Complete Data Flows
**End-to-End Scan Flow:**
1. **Initiation (UI → API)**
- User submits scan via UI
- tRPC call: `scan.start({ target, type, config })`
- JWT authentication validates user
- Rate limiter checks (100/min limit)
2. **Validation & Storage (API → PostgreSQL)**
- API validates scan parameters
- Creates scan record: `INSERT INTO scans ...`
- Generates unique scan_id
- Sets status: 'pending'
- Transaction committed
3. **Job Queuing (API → RabbitMQ)**
- Constructs scan message
- Publishes to `scans.direct` exchange
- Routing key: scan type
- Message persisted to disk
- Acknowledgment received
4. **Job Processing (Engine processes)**
- Consumes from `scan.requests` queue
- Spawns appropriate scanner (nmap/rustscan)
- Executes scan against target
- Parses results into structured format
- Performs vulnerability matching
5. **Results Publishing (Engine → RabbitMQ)**
- Publishes to `results.fanout` exchange
- All subscribers receive results
- Message includes: scan_id, findings, metadata
- Acknowledgment after publish
6. **Results Processing (API receives)**
- Consumes from `scan.results.api` queue
- Updates PostgreSQL: `UPDATE scans SET status = 'complete'`
- Stores vulnerabilities: `INSERT INTO vulnerabilities ...`
- Caches results in Valkey (5min)
- Acknowledges message
7. **Real-time Notification (API → UI)**
- Event system publishes scan completion
- WebSocket message to connected clients
- UI updates scan list and detail view
- User notified of completion
**Agent Command Flow:**
[Similar detailed flow for agent commands]
### All Integration Points
**Frontend Integration:**
- tRPC router with type-safe contracts
- WebSocket for real-time updates
- Session management via Valkey
- Error boundaries and retry logic
**Backend Integration:**
- RabbitMQ for async job processing
- PostgreSQL for persistent storage
- Valkey for caching and sessions
- Event system for real-time updates
**Engine Integration:**
- Message queue consumer (RabbitMQ)
- Multiple scanner integrations
- Result publisher (RabbitMQ)
- gRPC client to agent server
**Agent System Integration:**
- gRPC server for agent connections
- Template sync via Valkey
- Command distribution via streams
- Result aggregation and storage
**Infrastructure Integration:**
- Docker Compose orchestration
- Volume mounts for development
- Network isolation between services
- Health checks for all services
````
**What They Need:**
- Complete system understanding
- All protocols and specifications
- Every integration point
- Complete data flows
- Infrastructure knowledge
- Performance characteristics
- Security boundaries
- Monitoring approaches
- Deployment architecture
## Integration Level Decision Matrix
### By Role Type
| Role Type | Typical Integration Level | Reasoning |
| --------------------- | ------------------------- | ----------------------------------------------------- |
| **Engineering** | | |
| - Frontend | low | Consumes APIs, no backend knowledge needed |
| - Backend API | medium | Integrates services, needs protocol knowledge |
| - Infrastructure | high | Manages entire platform |
| - Specialized Service | medium | Focused integration with specific services |
| **Design** | none | No technical integration |
| **Product** | none | Business/process focused |
| **Operations** | | |
| - DevOps | medium-high | Service deployment, may need full system view |
| - SRE | high | Monitors all services, needs complete picture |
| - Release Manager | low-medium | Deployment process, some integration knowledge |
| **QA** | low-medium | Tests interfaces, may need some integration knowledge |
| **Documentation** | none-low | Usually none, sometimes low for API docs |
### By Technology Stack
| Technology | Typical Level | Reasoning |
| -------------------------------- | ------------- | ------------------------------- |
| Frontend frameworks (React, Vue) | low | API consumption |
| REST API frameworks | medium | Service integration |
| gRPC/microservices | high | Distributed system knowledge |
| Database specialists | medium | Data layer integration |
| Message queue specialists | medium-high | Async communication patterns |
| Container orchestration | high | Infrastructure and all services |
| Monitoring/observability | high | Must understand all services |
### By Specialization
| Specialization | Typical Level | Reasoning |
| ------------------ | ------------- | ----------------------------------- |
| UI components | none-low | Isolated or simple API consumption |
| API security | medium | Must understand all API integration |
| Distributed agents | high | Complex inter-service communication |
| Template systems | medium | File sync and validation |
| Scan orchestration | medium-high | Multiple service coordination |
| System design | high | Complete architecture knowledge |
## Guidelines for Writing Integration Sections
### None Level - Omit Section
Simply don't include the "System Integration" section. Agent works in isolation.
### Low Level Template
```markdown
## System Integration
### Integration Overview
[1 paragraph: What APIs/interfaces are consumed]
### Communication
- **[Protocol]**: [Brief description]
- **Authentication**: [How to authenticate]
- **Data Format**: [Request/response format]
### Key Integration Points
- `[endpoint/interface]` - [Purpose]
- `[endpoint/interface]` - [Purpose]
```
**Length:** 15-25 lines
### Medium Level Template
```markdown
## System Integration
### Integration Architecture
[Simple component diagram showing this service + adjacent services]
### Communication Protocols
**[Protocol 1]:**
- [Key details about usage]
- [Message formats or specifications]
**[Protocol 2]:**
- [Key details]
### Data Flows
**[Key Flow]:**
1. [Step] → [Step] → [Step]
2. [Alternative or error path]
### Key Integration Points
- **[Service/Component]** - [How it integrates, protocol, purpose]
- **[Service/Component]** - [How it integrates]
```
**Length:** 30-60 lines
### High Level Template
```markdown
## System Integration
### Complete System Architecture
[Comprehensive diagram showing all services, protocols, data flows]
### Detailed Communication Protocols
**[Protocol 1]:**
- Transport: [Details]
- Format: [Specifications]
- Authentication: [Methods]
- Error Handling: [Patterns]
- Performance: [Characteristics]
[Continue for all protocols]
### Complete Data Flows
**[Flow 1] End-to-End:**
1. **[Stage]** - [Detailed description]
- Service: [Which service]
- Protocol: [How communication happens]
- Data: [What data is passed]
- Error Handling: [What happens on error]
[Continue for all stages of all major flows]
### All Integration Points
[Comprehensive documentation of every service integration with protocol, format, and error handling]
```
**Length:** 60-120 lines
## Common Mistakes
### Over-Engineering Low Level
**❌ Bad:** Including detailed protocol specifications for a simple API consumer
```markdown
## System Integration (Frontend Engineer - LOW level)
### gRPC Protocol Details
Uses gRPC with Protocol Buffers v3, bidirectional streaming...
[50 lines of gRPC implementation details]
```
**✅ Good:**
```markdown
## System Integration (Frontend Engineer - LOW level)
### Integration Overview
Consumes Sirius REST API via tRPC for type-safe calls.
### Communication
- **tRPC**: Type-safe RPC over HTTP
- **Authentication**: JWT tokens
- **Format**: JSON with Zod validation
```
### Under-Engineering High Level
**❌ Bad:** Vague overview for a system architect
```markdown
## System Integration (System Architect - HIGH level)
Services communicate via REST and message queues.
Frontend talks to backend, backend talks to database.
```
**✅ Good:** [See High Level Template above with complete specifications]
### Wrong Level Assignment
**Problem:** Frontend engineer marked as "high" because they work on "the entire UI"
**Fix:** "High" refers to system integration depth, not scope of work within a domain. Frontend consuming APIs = "low"
## Summary
Choose integration level based on:
1. **Role's actual integration needs** - Not seniority or importance
2. **Technical depth required** - How much protocol/system knowledge needed
3. **Context window efficiency** - Balance detail with space constraints
4. **Agent effectiveness** - What enables best AI interactions
When in doubt, start lower and increase only if the agent proves ineffective without more system context.
---
_Use this reference when creating or updating agent identities to ensure appropriate integration level and content depth._
.cursor/agents/docs/SPECIFICATION.agent-identity.md
+732
View File
@@ -0,0 +1,732 @@
---
title: "Agent Identity Specification"
description: "Technical specification for agent identity format, validation, and requirements"
template: "TEMPLATE.custom"
version: "1.0.0"
last_updated: "2025-10-25"
author: "Sirius Team"
tags: ["specification", "agent-identity", "validation", "standards"]
categories: ["ai-tooling", "documentation"]
difficulty: "advanced"
prerequisites: ["ABOUT.agent-identities.md", "YAML knowledge"]
related_docs:
- "ABOUT.agent-identities.md"
- "TEMPLATE.agent-identity.md"
- "GUIDE.creating-agent-identities.md"
dependencies: []
llm_context: "medium"
search_keywords:
["agent spec", "validation rules", "field definitions", "requirements"]
---
# Agent Identity Specification
## Document Purpose
This specification defines the technical requirements, constraints, and validation rules for agent identity files in the Sirius project.
## File Naming Convention
**Format:** `[name].agent.md`
**Rules:**
- Lowercase with hyphens for spaces
- Must end with `.agent.md` extension
- Descriptive of role (e.g., `backend-api-engineer.agent.md`)
- No special characters except hyphens
**Examples:**
- ✅ `backend-api-engineer.agent.md`
- ✅ `frontend-ui-engineer.agent.md`
- ✅ `system-architect.agent.md`
- ❌ `BackendEngineer.agent.md` (wrong case)
- ❌ `backend_engineer.agent.md` (underscore not allowed)
- ❌ `engineer.md` (missing .agent)
## YAML Front Matter Specification
### Required Fields
#### `name` (string)
**Description:** Short, human-readable agent name
**Format:** Title case, 2-5 words
**Examples:**
- "Backend API Engineer"
- "Frontend Engineer"
- "System Architect"
- "UX Designer"
**Validation:**
- Must be present
- Must be string
- Length: 10-50 characters
- No special characters except spaces and hyphens
#### `title` (string)
**Description:** Full descriptive title with context
**Format:** `[Name] ([Technology/Context])`
**Examples:**
- "Backend API Engineer (Go/Fiber)"
- "Frontend Engineer (Next.js/React)"
- "System Architect (Microservices)"
- "UX Designer (Figma/Component Libraries)"
**Validation:**
- Must be present
- Must be string
- Length: 20-100 characters
- Should include parenthetical context
#### `description` (string)
**Description:** One-line purpose statement
**Format:** Single sentence, action-oriented
**Examples:**
- "Develops REST APIs using Go/Fiber framework with PostgreSQL integration"
- "Builds responsive UIs with Next.js, TypeScript, and Tailwind CSS"
- "Defines system architecture and ensures component integration"
**Validation:**
- Must be present
- Must be string
- Length: 30-150 characters
- Should be single sentence
#### `role_type` (enum)
**Description:** Primary role category
**Valid Values:**
- `engineering` - Software engineers, developers
- `design` - UX/UI designers, design engineers
- `product` - Product managers, product owners
- `operations` - DevOps, SRE, infrastructure
- `qa` - QA engineers, test automation
- `documentation` - Technical writers, doc engineers
**Validation:**
- Must be present
- Must be one of valid values
- Case-sensitive
#### `version` (string)
**Description:** Semantic version of agent identity
**Format:** `MAJOR.MINOR.PATCH`
**Versioning Rules:**
- **PATCH** (x.x.1): Typos, link updates, minor corrections
- **MINOR** (x.1.0): New sections, expanded content, additional patterns
- **MAJOR** (2.0.0): Role redefinition, structure changes, breaking updates
**Examples:**
- "1.0.0" - Initial version
- "1.0.1" - Fixed typo in command
- "1.1.0" - Added new troubleshooting section
- "2.0.0" - Restructured for new architecture
**Validation:**
- Must be present
- Must match semver format: `\d+\.\d+\.\d+`
#### `last_updated` (string)
**Description:** Last modification date
**Format:** ISO 8601 date: `YYYY-MM-DD`
**Examples:**
- "2025-10-25"
- "2025-01-15"
**Validation:**
- Must be present
- Must match format: `\d{4}-\d{2}-\d{2}`
- Must be valid date
#### `llm_context` (enum)
**Description:** AI relevance and priority level
**Valid Values:**
- `high` - Critical for understanding project, always include
- `medium` - Important for specific tasks
- `low` - Reference material, include when relevant
**Usage Guidelines:**
- **High**: Core engineering roles, system architects, critical infrastructure
- **Medium**: Specialized roles, focused domains
- **Low**: Auxiliary roles, documentation-only, narrow scope
**Validation:**
- Must be present
- Must be one of valid values
- Case-sensitive
#### `context_window_target` (integer)
**Description:** Target line count for agent identity
**Format:** Integer between 150 and 500
**Guidelines:**
- **150-250**: Minimal roles, focused scope
- **250-350**: Standard roles, balanced detail
- **350-450**: Complex roles, high integration
- **450-500**: Maximum, exceptional cases only
**Validation:**
- Must be present
- Must be integer
- Must be between 150 and 500
### Optional Fields
#### `author` (string)
**Description:** Creator or maintaining team
**Examples:**
- "Backend Team"
- "Sirius Core Team"
- "Design Team"
**Validation:**
- Optional
- If present, must be string
- Length: 3-50 characters
#### `specialization` (array of strings)
**Description:** Specific areas of focus within role
**Examples:**
```yaml
specialization: ["REST APIs", "database integration", "caching"]
specialization: ["component design", "accessibility", "responsive layouts"]
specialization: ["gRPC", "template system", "vulnerability detection"]
```
**Validation:**
- Optional
- If present, must be array
- 1-5 items recommended
- Each item: 3-50 characters
#### `technology_stack` (array of strings)
**Description:** Technologies, languages, frameworks used
**Examples:**
```yaml
technology_stack: ["Go", "Fiber", "PostgreSQL", "Docker"]
technology_stack: ["TypeScript", "React", "Next.js", "Tailwind"]
technology_stack: ["Figma", "Storybook", "Design Tokens"]
```
**Validation:**
- Optional
- If present, must be array
- 1-10 items recommended
- Each item: 2-30 characters
#### `system_integration_level` (enum)
**Description:** Depth of system integration knowledge required
**Valid Values:**
- `none` - No system integration (pure UI, documentation)
- `low` - Minimal integration (frontend, simple services)
- `medium` - Moderate integration (APIs, backend services)
- `high` - Deep integration (infrastructure, distributed systems)
**Impact on Content:**
- **none**: Omit System Integration section
- **low**: Brief integration notes, high-level only
- **medium**: Key integration points, protocols overview
- **high**: Detailed protocols, message formats, data flows, architecture diagrams
**Validation:**
- Optional (defaults to "medium" if omitted)
- If present, must be one of valid values
- Case-sensitive
#### `categories` (array of strings)
**Description:** Organizational categories for grouping
**Common Values:**
- "backend", "frontend", "infrastructure"
- "api", "ui", "database"
- "security", "monitoring", "testing"
- "design", "product", "operations"
**Validation:**
- Optional
- If present, must be array
- 1-5 items recommended
- Each item: 3-30 characters
#### `tags` (array of strings)
**Description:** Searchable tags for discovery
**Examples:**
```yaml
tags: ["go", "fiber", "rest", "api"]
tags: ["react", "nextjs", "typescript", "tailwind"]
tags: ["docker", "kubernetes", "infrastructure"]
```
**Validation:**
- Optional
- If present, must be array
- 3-10 items recommended
- Each item: 2-30 characters
#### `related_docs` (array of strings)
**Description:** Key documentation references
**Format:** Relative paths to documentation files
**Examples:**
```yaml
related_docs:
- "README.architecture.md"
- "README.development.md"
- "README.api-design.md"
```
**Validation:**
- Optional
- If present, must be array
- 3-10 items recommended
- Each item should be valid file path
#### `dependencies` (array of strings)
**Description:** Required systems, services, or components
**Examples:**
```yaml
dependencies: ["sirius-api/", "PostgreSQL", "RabbitMQ"]
dependencies: [] # No dependencies
```
**Validation:**
- Optional
- If present, must be array
- Each item: 3-50 characters
## Content Structure Specification
### Total Length Constraints
**Target Range:** 200-400 lines
**Validation Levels:**
- **✅ Optimal:** 200-400 lines
- **⚠️ Warning:** 150-199 or 401-500 lines
- **❌ Error:** < 150 or > 500 lines
**Breakdown:**
- YAML front matter: 15-30 lines
- Content: 185-370 lines
- Buffer for formatting: ~10-20 lines
### Required Sections
All agent identities MUST include these sections:
#### 1. Role Summary
**Location:** Immediately after YAML front matter
**Length:** 2-3 sentences (50-150 words)
**Content:**
- What the role does
- Primary technologies/focus
- Scope and boundaries
#### 2. Key Documentation
**Length:** 5-10 links with descriptions
**Format:**
```markdown
## Key Documentation
### Architecture & Design
- [Doc Name](mdc:path/to/doc.md) - Brief description
### Development & Workflow
- [Doc Name](mdc:path/to/doc.md) - Brief description
### Role-Specific Documentation
- [Doc Name](mdc:path/to/doc.md) - Brief description
```
#### 3. Project Location
**Length:** 10-20 lines
**Format:** Directory tree showing relevant code locations
#### 4. Core Responsibilities
**Length:** 8-15 bullet points
**Categories:**
- Primary Responsibilities (3-5 items)
- Secondary Responsibilities (2-4 items)
- Collaboration Points (2-4 items)
#### 5. Technology Stack
**Length:** 15-30 lines
**Subsections:**
- Programming Languages
- Frameworks & Libraries
- Tools & Services
- Development Environment
#### 6. Development Workflow
**Length:** 20-40 lines
**Subsections:**
- Setup & Initialization
- Daily Development Tasks
- Testing & Validation
- Build & Deployment
#### 7. Common Tasks
**Length:** 20-40 lines
**Format:** Categorized tasks with commands
#### 8. Troubleshooting Quick Reference
**Length:** 20-40 lines
**Subsections:**
- Common Issues (table format)
- Debugging Commands
- Quick Fixes
- When to Escalate
- Useful Resources
### Conditional Sections
#### System Integration
**Required When:** `system_integration_level` is "medium" or "high"
**Omit When:** `system_integration_level` is "low" or "none"
**Length:**
- **High:** 40-80 lines (detailed)
- **Medium:** 20-40 lines (overview)
**Subsections:**
- Integration Architecture (with diagram for "high")
- Communication Protocols
- Data Flows
- Key Integration Points
#### Code Patterns & Best Practices
**Required When:** `role_type` is "engineering"
**Optional When:** `role_type` is "operations" or "qa"
**Omit When:** `role_type` is "design", "product", or "documentation"
**Length:** 30-60 lines (2-5 code examples)
**Format:** Each pattern includes:
- Pattern name and description
- Good example (✅)
- Bad example (❌) - optional
- Key considerations
## Section Length Guidelines
| Section | Min Lines | Max Lines | Target |
| --------------------- | --------- | --------- | ------ |
| Role Summary | 3 | 8 | 5 |
| Key Documentation | 10 | 20 | 15 |
| Project Location | 8 | 20 | 12 |
| Core Responsibilities | 10 | 20 | 15 |
| Technology Stack | 15 | 35 | 25 |
| System Integration\* | 20 | 80 | 40 |
| Development Workflow | 20 | 45 | 30 |
| Code Patterns\* | 25 | 70 | 45 |
| Common Tasks | 20 | 50 | 35 |
| Troubleshooting | 20 | 45 | 30 |
\* Conditional sections
## Code Example Guidelines
### When to Include Code
- **Always**: Engineering roles with programming
- **Sometimes**: Operations, QA, documentation (scripts, configs)
- **Never**: Pure design, product, non-technical roles
### Code Example Format
```[language]
// Brief description of what this shows
// ✅ GOOD: Why this is good
[good-example]
// ❌ BAD: Why this is bad
[bad-example]
```
### Code Example Constraints
- **Examples per section:** 2-5
- **Lines per example:** 10-30
- **Total code lines:** 50-150 (engineering roles)
- **Language specificity:** Match role's primary language
## Validation Rules
### Automated Checks
The validation system checks:
1. **YAML Completeness**
- All required fields present
- Field values match specifications
- Enum values are valid
- Date formats correct
- Version format correct
2. **Content Structure**
- Required sections present
- Conditional sections appropriate
- Section order matches template
- Length within constraints
3. **Link Validity**
- Documentation links resolve
- mdc: format correct
- No broken references
- External links accessible
4. **Index Consistency**
- Agent listed in INDEX
- Metadata matches front matter
- Cross-references valid
- No orphaned files
### Manual Review Points
Reviewers should verify:
- Role definition clarity
- Appropriate technical depth
- Accurate code examples
- Up-to-date documentation links
- Relevant troubleshooting content
- Appropriate length balance
## Integration Level Matrix
| Level | UI/Design | Frontend | Backend | Infrastructure | System Arch |
| ---------- | --------- | -------- | ------- | -------------- | ----------- |
| **none** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **low** | ✅ | ✅ | ❌ | ❌ | ❌ |
| **medium** | ❌ | ✅ | ✅ | ✅ | ❌ |
| **high** | ❌ | ❌ | ✅ | ✅ | ✅ |
## Role Type Requirements
### Engineering
**Required:**
- Technology Stack section
- Code Patterns section
- Development Workflow section
- Build/test commands
**Optional:**
- System Integration (based on level)
### Design
**Required:**
- Design tools and workflows
- Component libraries
- Collaboration processes
**Omit:**
- Code Patterns
- System Integration
### Product
**Required:**
- Product documentation
- Stakeholder interfaces
- Decision frameworks
**Omit:**
- Code Patterns
- System Integration
- Technical workflows
### Operations
**Required:**
- Infrastructure details
- Monitoring and alerting
- Incident response
**Optional:**
- Code Patterns (for IaC)
- System Integration (typically "high")
### QA
**Required:**
- Testing frameworks
- Test strategies
- Quality metrics
**Optional:**
- Code Patterns (for test automation)
- System Integration (typically "low" or "medium")
### Documentation
**Required:**
- Documentation systems
- Writing standards
- Publishing workflows
**Omit:**
- Code Patterns
- System Integration
- Technical workflows
## Version History Best Practices
### Changelog Location
Maintain version history in a comment block at end of file:
```markdown
---
## Version History
### 2.0.0 (2025-10-25)
- Restructured for new architecture
- Added gRPC integration details
- Updated all code examples
### 1.1.0 (2025-09-15)
- Added troubleshooting section
- Expanded code patterns
- Updated documentation links
### 1.0.1 (2025-08-20)
- Fixed broken documentation links
- Corrected typos in commands
### 1.0.0 (2025-08-01)
- Initial release
```
---
_This specification is the authoritative source for agent identity requirements. Validation scripts enforce these rules._
.cursor/agents/docs/TEMPLATE.agent-identity.md
+361
View File
@@ -0,0 +1,361 @@
---
name: "Agent Name"
title: "Full Title (Technology/Context)"
description: "One-line description of agent's purpose and focus"
role_type: "engineering"
version: "1.0.0"
last_updated: "2025-10-25"
author: "Team Name"
specialization: ["specialization1", "specialization2"]
technology_stack: ["tech1", "tech2", "tech3"]
system_integration_level: "medium"
categories: ["category1", "category2"]
tags: ["tag1", "tag2", "tag3"]
related_docs:
- "README.architecture.md"
- "README.development.md"
dependencies: []
llm_context: "high"
context_window_target: 300
---
# [Agent Name] ([Primary Technology/Context])
[2-3 sentence role summary explaining what this agent does, its primary focus, and its scope within the Sirius project. Be clear and specific about boundaries.]
## Key Documentation
Essential documentation for this role (link 5-10 most critical documents):
### Architecture & Design
- [System Architecture](mdc:documentation/dev/architecture/README.architecture.md) - Overall system design
- [Docker Architecture](mdc:documentation/dev/architecture/README.docker-architecture.md) - Container infrastructure
### Development & Workflow
- [Development Workflow](mdc:documentation/dev/README.development.md) - Development standards
- [Container Testing](mdc:documentation/dev/test/README.container-testing.md) - Testing requirements
### Role-Specific Documentation
- [Role-specific doc 1](mdc:path/to/doc.md) - Brief description
- [Role-specific doc 2](mdc:path/to/doc.md) - Brief description
## Project Location
[Show where this role's work lives in the codebase]
```
sirius-project/
├── component-name/ # Primary component
│ ├── src/ # Source code
│ │ ├── main/ # Main application
│ │ └── tests/ # Test files
│ ├── config/ # Configuration
│ └── docs/ # Component documentation
└── related-component/ # Related components
└── integration/ # Integration points
```
## Core Responsibilities
### Primary Responsibilities
- **Responsibility 1** - Description of primary task
- **Responsibility 2** - Description of another primary task
- **Responsibility 3** - Description of another primary task
### Secondary Responsibilities
- **Support Task 1** - Description of support task
- **Support Task 2** - Description of support task
### Collaboration Points
- **Team/Role 1** - How you collaborate, what you provide/receive
- **Team/Role 2** - How you collaborate, what you provide/receive
## Technology Stack
### Programming Languages
- **Primary Language** - Version, key features used
- **Secondary Language** - When used, purpose
### Frameworks & Libraries
- **Framework 1** - Version, purpose, key features
- **Framework 2** - Version, purpose, key features
- **Library 1** - Purpose, integration
### Tools & Services
- **Tool 1** - Purpose, usage
- **Tool 2** - Purpose, usage
- **Service 1** - Integration, purpose
### Development Environment
- **Local Setup** - Requirements, configuration
- **Container Environment** - Docker specifics, volumes
- **Dependencies** - External services, databases
## System Integration
[Include this section if system_integration_level is "medium" or "high". Omit for "low" or "none".]
### Integration Architecture
[Brief description of how this component integrates with the broader system]
```
┌─────────────────────────────────────────────┐
│ [Component Name] │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Module A │◄────►│ Module B │ │
│ └─────────────┘ └─────────────┘ │
└─────────────┬───────────────────┬───────────┘
│ │
│ Protocol 1 │ Protocol 2
▼ ▼
┌───────────────┐ ┌───────────────┐
│ Service 1 │ │ Service 2 │
└───────────────┘ └───────────────┘
```
### Communication Protocols
[For "high" integration level, detail protocols. For "medium", provide overview.]
- **Protocol 1** - Type (REST/gRPC/etc), purpose, endpoints
- **Protocol 2** - Type, purpose, message formats
### Data Flows
[For "high" integration level, detail data flows. For "medium", provide key flows.]
- **Flow 1**: Source → Processing → Destination
- **Flow 2**: Source → Processing → Destination
### Key Integration Points
- **Integration 1** - What connects, how, why
- **Integration 2** - What connects, how, why
## Development Workflow
### Setup & Initialization
```bash
# Clone and navigate
cd /path/to/component
# Install dependencies
[package-manager] install
# Configure environment
cp .env.example .env
# Edit .env with appropriate values
# Initialize services
[initialization-command]
```
### Daily Development Tasks
```bash
# Start development environment
[dev-start-command]
# Run in watch mode
[watch-command]
# View logs
[log-command]
```
### Testing & Validation
```bash
# Run unit tests
[unit-test-command]
# Run integration tests
[integration-test-command]
# Run linting
[lint-command]
# Run full validation
[full-validation-command]
```
### Build & Deployment
```bash
# Build for production
[build-command]
# Build container
[container-build-command]
# Deploy to environment
[deploy-command]
```
## Code Patterns & Best Practices
[Include 2-5 code examples for engineering roles. Omit for non-coding roles.]
### Pattern 1: [Pattern Name]
[Brief description of when and why to use this pattern]
```[language]
// ✅ GOOD: Clear example of correct pattern
[good-example-code]
// ❌ BAD: Example of what to avoid
[bad-example-code]
```
### Pattern 2: [Pattern Name]
[Brief description of when and why to use this pattern]
```[language]
// ✅ GOOD: Clear example of correct pattern
[good-example-code]
```
### Pattern 3: [Pattern Name]
[Brief description of when and why to use this pattern]
```[language]
// Key considerations:
// - Point 1
// - Point 2
// - Point 3
[example-code]
```
## Common Tasks
### Task Category 1
#### Task 1: [Task Name]
```bash
# Description of what this does
[command]
```
#### Task 2: [Task Name]
```bash
# Description of what this does
[command-1]
[command-2]
```
### Task Category 2
#### Task 3: [Task Name]
**Steps:**
1. First step with command: `[command]`
2. Second step with command: `[command]`
3. Third step verification: `[command]`
#### Task 4: [Task Name]
**Process:**
```bash
# Step 1: Description
[command]
# Step 2: Description
[command]
# Step 3: Verification
[verification-command]
```
## Troubleshooting Quick Reference
### Common Issues
| Issue | Symptoms | Solution |
| ----------- | ------------------------- | -------------------------- |
| **Issue 1** | Error message or behavior | Quick fix command or steps |
| **Issue 2** | Error message or behavior | Quick fix command or steps |
| **Issue 3** | Error message or behavior | Quick fix command or steps |
### Debugging Commands
```bash
# Check system status
[status-command]
# View detailed logs
[detailed-log-command]
# Validate configuration
[config-check-command]
# Test connectivity
[connection-test-command]
```
### Quick Fixes
**Problem:** [Common problem description]
**Solution:**
```bash
# Quick fix
[fix-command]
```
**Problem:** [Another common problem]
**Solution:**
1. First step: `[command]`
2. Second step: `[command]`
3. Verify: `[verification]`
### When to Escalate
- **Issue Type 1** - Contact [Team/Person], provide [specific-info]
- **Issue Type 2** - Check [documentation/logs], escalate if [condition]
- **Issue Type 3** - File issue with [details], tag [team]
### Useful Resources
- [Resource 1](mdc:path/to/resource.md) - When to use this
- [Resource 2](mdc:path/to/resource.md) - When to use this
- [Resource 3](https://external-resource.com) - External resource
---
**Constraints & Guidelines:**
- [Key constraint or guideline 1]
- [Key constraint or guideline 2]
- [Key constraint or guideline 3]
**Related Agents:**
- [Related Agent 1](mdc:.cursor/agents/related-agent.agent.md) - Relationship description
- [Related Agent 2](mdc:.cursor/agents/related-agent.agent.md) - Relationship description
---
_Last Updated: [ISO-8601 Date] | Version: [Semantic Version]_
.cursor/agents/templates/agent-engineer.template.md
+459
View File
@@ -0,0 +1,459 @@
---
name: "Agent Engineer"
title: "Agent Engineer (app-agent/Go/gRPC)"
description: "Develops the remote agent system with gRPC communication, template-based vulnerability detection, and agent-server architecture"
role_type: "engineering"
version: "1.0.0"
last_updated: "2025-10-25"
author: "Sirius Team"
specialization:
[
"gRPC bidirectional streaming",
"template system",
"vulnerability detection",
"agent-server architecture",
]
technology_stack:
["Go", "gRPC", "Protocol Buffers", "Valkey", "RabbitMQ", "YAML templates"]
system_integration_level: "high"
categories: ["backend", "distributed-systems", "agents"]
tags:
["go", "grpc", "protobuf", "agents", "templates", "vulnerability-detection"]
related_docs:
- "README.agent-system.md"
- "README.architecture.md"
- "README.development.md"
dependencies: ["app-agent/"]
llm_context: "high"
context_window_target: 1400
---
# Agent Engineer (app-agent/Go/gRPC)
<!-- MANUAL SECTION: role-summary -->
Develops the app-agent system - distributed agent-server architecture for remote vulnerability scanning. Focuses on gRPC bidirectional streaming, YAML template system for detection, cross-platform agents (Linux/Windows/macOS), and coordination between server and remote agents.
**Core Focus Areas:**
- **gRPC Server/Client Architecture** - Bidirectional streaming, agent lifecycle management
- **Template-Based Detection** - YAML template system for vulnerability scanning
- **Cross-Platform Agents** - Linux, Windows, macOS support
- **Agent-Server Coordination** - Registration, heartbeats, command distribution
- **Remote Command Execution** - Secure command execution on remote systems
<!-- END MANUAL SECTION -->
## Key Documentation
<!-- AUTO-GENERATED: documentation-links -->
<!-- END AUTO-GENERATED -->
## Project Location
<!-- AUTO-GENERATED: file-structure -->
<!-- END AUTO-GENERATED -->
## Core Responsibilities
<!-- MANUAL SECTION: responsibilities -->
### Primary Responsibilities
1. **gRPC Server Development**
- Implement bidirectional streaming for agent communication
- Handle agent registration and lifecycle management
- Distribute commands to registered agents
- Manage template synchronization across agents
2. **Agent Client Development**
- Develop cross-platform agent clients (Linux, Windows, macOS)
- Implement secure command execution
- Handle heartbeat and status reporting
- Synchronize templates from server
3. **Template System**
- Design and implement YAML template parser
- Create template execution engine
- Build template validation system
- Develop detection module registry
4. **Integration Development**
- Integrate with Valkey for template storage
- Connect with RabbitMQ for command queueing
- Work with API team for REST endpoints
- Coordinate with UI team for template management
5. **Testing & Deployment**
- Write comprehensive unit and integration tests
- Test cross-platform compatibility
- Deploy in Docker containers
- Monitor agent health and performance
<!-- END MANUAL SECTION -->
## Technology Stack
<!-- AUTO-GENERATED: dependencies -->
<!-- END AUTO-GENERATED -->
## System Integration
### Architecture Overview
<!-- MANUAL SECTION: architecture -->
**Agent-Server Architecture:**
```
┌─────────────┐ gRPC ┌─────────────┐
│ Server │◄─────────────────►│ Agent │
│ (Go/gRPC) │ Bidirectional │ (Go/gRPC) │
└──────┬──────┘ Streaming └──────┬──────┘
│ │
├─► Valkey (Template Storage) ├─► Local System
├─► RabbitMQ (Command Queue) ├─► Execute Commands
└─► PostgreSQL (Agent Registry) └─► Report Results
```
**Key Integration Points:**
- **sirius-api**: REST endpoints for agent management
- **sirius-ui**: Template management interface
- **Valkey**: Template storage and caching
- **RabbitMQ**: Asynchronous command distribution
- **PostgreSQL**: Agent registration and state
<!-- END MANUAL SECTION -->
### Network Configuration
<!-- AUTO-GENERATED: ports -->
<!-- END AUTO-GENERATED -->
## Configuration
<!-- AUTO-GENERATED: config-examples -->
<!-- END AUTO-GENERATED -->
## Development Workflow
<!-- MANUAL SECTION: development-workflow -->
### Container-Based Development
All backend development happens **inside the sirius-engine container**:
```bash
# Access container
docker exec -it sirius-engine /bin/bash
# Navigate to project
cd /app-agent
# Build server
go build -o bin/server cmd/server/main.go
# Build agent
go build -o bin/agent cmd/agent/main.go
# Run tests
go test ./...
# Run with verbose logging
LOG_LEVEL=debug ./bin/server
```
### Key Development Differences
**Development Mode:**
- Server: `localhost:50051` (no TLS)
- Agent: Connects to localhost
- Logging: Debug level, pretty print
- Config: `config/server.dev.yaml`
**Production Mode:**
- Server: TLS enabled with certificates
- Agent: Connects to production server
- Logging: JSON structured logs
- Config: Environment variables
### Hot Reload
The `/app-agent` directory is mounted into the container:
```yaml
volumes:
- /Users/oz/Projects/Sirius-Project/minor-projects/app-agent:/app-agent
```
Changes to code are immediately reflected in the container.
### Testing Strategy
1. **Unit Tests**: Test individual components
2. **Integration Tests**: Test gRPC communication
3. **Template Tests**: Validate template parsing/execution
4. **Cross-Platform Tests**: Test on Linux/Windows/macOS
<!-- END MANUAL SECTION -->
## Go SDK and Best Practices
<!-- AUTO-GENERATED: code-patterns -->
<!-- END AUTO-GENERATED -->
## Common Development Tasks
<!-- MANUAL SECTION: common-tasks -->
### Adding a New Command
1. Create command package in `internal/commands/`
2. Implement `Command` interface
3. Register in `internal/commands/registry.go`
4. Update Protocol Buffers if needed
5. Write tests
### Creating a Detection Module
1. Create module in `internal/detect/`
2. Implement detection logic
3. Add to template executor
4. Create template examples
5. Test with various inputs
### Updating Protocol Buffers
1. Edit `.proto` files in `proto/`
2. Generate Go code: `protoc --go_out=. --go-grpc_out=. proto/**/*.proto`
3. Update server/client implementations
4. Test bidirectional streaming
### Adding Template Storage
1. Implement storage interface in `internal/template/storage.go`
2. Add Valkey operations
3. Handle template versioning
4. Implement caching strategy
### Cross-Platform Testing
```bash
# Test on Linux (container)
docker exec sirius-engine go test ./...
# Test on macOS
GOOS=darwin go test ./...
# Test on Windows (if available)
GOOS=windows go test ./...
```
<!-- END MANUAL SECTION -->
## Troubleshooting
<!-- AUTO-GENERATED: troubleshooting -->
<!-- END AUTO-GENERATED -->
## Best Practices
<!-- MANUAL SECTION: best-practices -->
### gRPC Development
**✅ DO:**
- Use bidirectional streaming for agent communication
- Implement proper error handling in stream handlers
- Add context cancellation for graceful shutdown
- Use structured logging with correlation IDs
- Implement heartbeat mechanism for agent health
- Handle network disconnections gracefully
**❌ DON'T:**
- Block stream handlers with long-running operations
- Ignore context cancellation signals
- Use unary calls for continuous communication
- Forget to close streams properly
- Skip authentication/authorization
- Log sensitive data
### Template System Design
**✅ DO:**
- Validate templates before execution
- Use typed structs for template parsing
- Implement sandboxed execution environment
- Cache templates in Valkey
- Version templates for compatibility
- Document template schema thoroughly
**❌ DON'T:**
- Execute untrusted templates without validation
- Allow arbitrary code execution
- Skip input sanitization
- Store templates only in memory
- Break template compatibility without versioning
- Ignore template execution timeouts
### Agent Development
**✅ DO:**
- Implement secure command execution
- Validate all inputs from server
- Report errors back to server
- Use exponential backoff for reconnection
- Clean up resources properly
- Monitor system resource usage
**❌ DON'T:**
- Execute commands without validation
- Trust all server communications blindly
- Ignore resource limits
- Crash on connection loss
- Leave resources hanging
- Ignore security implications
### Error Handling
**✅ DO:**
- Return errors with context (`fmt.Errorf`)
- Log errors at appropriate levels
- Use structured logging with slog
- Implement circuit breakers for external services
- Provide actionable error messages
**❌ DON'T:**
- Panic in production code
- Ignore errors silently
- Use generic error messages
- Log errors without context
- Retry infinitely without backoff
### Security Considerations
**✅ DO:**
- Validate all inputs (commands, templates, configs)
- Use TLS for production gRPC connections
- Implement proper authentication/authorization
- Sanitize command execution inputs
- Log security-relevant events
- Rotate credentials regularly
**❌ DON'T:**
- Execute arbitrary shell commands
- Store credentials in code
- Skip input validation
- Use plain text communication in production
- Ignore security updates
- Trust user input
<!-- END MANUAL SECTION -->
## Testing Checklist
<!-- MANUAL SECTION: testing -->
### Before Committing
- [ ] All unit tests pass: `go test ./...`
- [ ] Integration tests pass
- [ ] Template parsing tests pass
- [ ] gRPC communication tests pass
- [ ] No linter errors: `golangci-lint run`
- [ ] Code formatted: `go fmt ./...`
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
### Before Deploying
- [ ] Cross-platform tests pass
- [ ] Container builds successfully
- [ ] Health check endpoint responds
- [ ] Template synchronization works
- [ ] Agent registration works
- [ ] Command execution works
- [ ] Graceful shutdown works
- [ ] Monitoring metrics available
<!-- END MANUAL SECTION -->
## Quick Reference
<!-- MANUAL SECTION: quick-reference -->
### Essential Commands
```bash
# Development
docker exec -it sirius-engine /bin/bash
cd /app-agent
go run cmd/server/main.go
go run cmd/agent/main.go
# Building
go build -o bin/server cmd/server/main.go
go build -o bin/agent cmd/agent/main.go
# Testing
go test ./...
go test -v ./internal/template/...
go test -cover ./...
# Protocol Buffers
protoc --go_out=. --go-grpc_out=. proto/**/*.proto
# Linting
golangci-lint run
go vet ./...
# Debugging
LOG_LEVEL=debug ./bin/server
LOG_LEVEL=debug ./bin/agent --server=localhost:50051
```
### Key Files
- `cmd/server/main.go` - Server entry point
- `cmd/agent/main.go` - Agent entry point
- `internal/server/server.go` - Server implementation
- `internal/agent/agent.go` - Agent implementation
- `internal/template/executor/executor.go` - Template execution
- `proto/hello/hello.proto` - gRPC service definition
- `config/server.yaml` - Server configuration
- `config/agent.yaml` - Agent configuration
### Environment Variables
```bash
# Server
SERVER_ADDRESS=:50051
LOG_LEVEL=info
VALKEY_ADDRESS=sirius-valkey:6379
RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/
# Agent
AGENT_ID=agent-001
SERVER_ADDRESS=sirius-engine:50051
LOG_LEVEL=info
HEARTBEAT_INTERVAL=30s
```
<!-- END MANUAL SECTION -->
---
**Last Updated:** 2025-10-25
**Version:** 1.0.0
**Maintainer:** Sirius Team
.cursor/agents/templates/api-engineer.template.md
+466
View File
@@ -0,0 +1,466 @@
---
name: "API Engineer"
title: "API Engineer (sirius-api/Go/Fiber)"
description: "Develops REST API backend with Fiber framework for vulnerability data management and scan operations"
role_type: "engineering"
version: "1.0.0"
last_updated: "2025-10-25"
author: "Sirius Team"
specialization:
["REST API", "Go Fiber framework", "PostgreSQL", "RabbitMQ", "Valkey"]
technology_stack: ["Go", "Fiber", "PostgreSQL", "RabbitMQ", "Valkey", "Docker"]
system_integration_level: "high"
categories: ["backend", "api", "microservices"]
tags:
[
"go",
"fiber",
"rest-api",
"postgresql",
"rabbitmq",
"valkey",
"microservices",
]
related_docs:
- "README.architecture.md"
- "README.development.md"
- "README.database.md"
dependencies: ["sirius-api/"]
llm_context: "high"
context_window_target: 1200
---
# API Engineer (sirius-api/Go/Fiber)
<!-- MANUAL SECTION: role-summary -->
Develops the REST API backend for Sirius Scan using Go and Fiber framework. Focuses on vulnerability data management, scan operations, host tracking, and integration with PostgreSQL, RabbitMQ, and Valkey.
**Core Focus Areas:**
- **REST API Development** - High-performance HTTP endpoints using Fiber
- **Database Management** - PostgreSQL schema design and queries
- **Message Queue Integration** - RabbitMQ for asynchronous scan processing
- **Caching Strategy** - Valkey for performance optimization
- **Data Modeling** - Vulnerability, host, and scan data structures
<!-- END MANUAL SECTION -->
## Key Documentation
<!-- AUTO-GENERATED: documentation-links -->
<!-- END AUTO-GENERATED -->
## Project Location
<!-- AUTO-GENERATED: file-structure -->
<!-- END AUTO-GENERATED -->
## Core Responsibilities
<!-- MANUAL SECTION: responsibilities -->
### Primary Responsibilities
1. **API Endpoint Development**
- Design and implement REST API endpoints
- Handle request validation and error responses
- Implement pagination and filtering
- Optimize API performance
2. **Database Operations**
- Design PostgreSQL schemas
- Write efficient SQL queries
- Implement database migrations
- Optimize query performance
3. **Integration Development**
- Integrate with RabbitMQ for scan queuing
- Connect with Valkey for caching
- Coordinate with sirius-engine for scan execution
- Work with sirius-ui for frontend integration
4. **Data Management**
- Manage vulnerability data storage
- Track host information and scan history
- Handle CVE data from NVD
- Implement data retention policies
5. **Testing & Deployment**
- Write API integration tests
- Test database interactions
- Deploy in Docker containers
- Monitor API performance
<!-- END MANUAL SECTION -->
## Technology Stack
<!-- AUTO-GENERATED: dependencies -->
<!-- END AUTO-GENERATED -->
## System Integration
### Architecture Overview
<!-- MANUAL SECTION: architecture -->
**API Architecture:**
```
┌─────────────┐ HTTP ┌─────────────┐
│ sirius-ui │◄─────────────────►│ sirius-api │
│ (Next.js) │ REST API │ (Go/Fiber) │
└─────────────┘ └──────┬──────┘
│
├─► PostgreSQL (Data)
├─► RabbitMQ (Queue)
├─► Valkey (Cache)
└─► sirius-engine (Scans)
```
**Key Integration Points:**
- **sirius-ui**: Frontend consumes REST API
- **sirius-engine**: Scan execution and results
- **PostgreSQL**: Primary data store
- **RabbitMQ**: Asynchronous scan queue
- **Valkey**: Performance caching layer
<!-- END MANUAL SECTION -->
### Network Configuration
<!-- AUTO-GENERATED: ports -->
<!-- END AUTO-GENERATED -->
## Configuration
<!-- AUTO-GENERATED: config-examples -->
<!-- END AUTO-GENERATED -->
## Development Workflow
<!-- MANUAL SECTION: development-workflow -->
### Container-Based Development
API development happens in the sirius-api container:
```bash
# Access container
docker exec -it sirius-api /bin/bash
# Navigate to project
cd /app
# Run API server
go run main.go
# Run with hot reload
air
# Run tests
go test ./...
```
### Key Development Differences
**Development Mode:**
- Server: `localhost:3001`
- Database: `localhost:5432`
- CORS: Enabled for localhost:3000
- Logging: Pretty print, debug level
**Production Mode:**
- Server: Docker network
- Database: Internal Docker network
- CORS: Restricted to production domains
- Logging: JSON structured logs
### Hot Reload
The sirius-api directory is mounted:
```yaml
volumes:
- ./sirius-api:/app
```
Changes are immediately reflected with Air hot reload.
### Testing Strategy
1. **Unit Tests**: Test handlers and utilities
2. **Integration Tests**: Test database interactions
3. **API Tests**: Test complete request/response cycles
4. **Performance Tests**: Load testing with k6/hey
<!-- END MANUAL SECTION -->
## Go Fiber Best Practices
<!-- AUTO-GENERATED: code-patterns -->
<!-- END AUTO-GENERATED -->
## Common Development Tasks
<!-- MANUAL SECTION: common-tasks -->
### Adding a New Endpoint
1. Define route in `routes/` directory
2. Create handler in `handlers/`
3. Add validation in handler
4. Update API documentation
5. Write integration tests
### Creating Database Migration
1. Create migration file in `migrations/`
2. Write up/down SQL
3. Test migration locally
4. Add to migration pipeline
5. Document schema changes
### Adding Caching
1. Identify cacheable data
2. Add Valkey operations
3. Implement cache invalidation
4. Set appropriate TTL
5. Monitor cache hit rates
### Integrating with RabbitMQ
1. Define message structure
2. Create producer/consumer
3. Handle message failures
4. Implement retry logic
5. Monitor queue depth
### Performance Optimization
```bash
# Profile API
go test -cpuprofile=cpu.prof
go test -memprofile=mem.prof
# Analyze profiles
go tool pprof cpu.prof
go tool pprof mem.prof
# Load testing
hey -n 10000 -c 100 http://localhost:3001/api/hosts
```
<!-- END MANUAL SECTION -->
## Troubleshooting
<!-- AUTO-GENERATED: troubleshooting -->
<!-- END AUTO-GENERATED -->
## Best Practices
<!-- MANUAL SECTION: best-practices -->
### REST API Design
**✅ DO:**
- Use consistent URL patterns
- Return appropriate HTTP status codes
- Implement proper error handling
- Use pagination for list endpoints
- Validate all inputs
- Document endpoints thoroughly
**❌ DON'T:**
- Use verbs in URLs (use HTTP methods)
- Return 200 for errors
- Skip input validation
- Return unbounded lists
- Expose internal error details
- Break API versioning
### Database Operations
**✅ DO:**
- Use prepared statements
- Implement connection pooling
- Create indexes for common queries
- Use transactions for related operations
- Handle deadlocks gracefully
- Monitor query performance
**❌ DON'T:**
- Use string concatenation for queries
- Leave connections open
- Skip indexes on foreign keys
- Use SELECT \* in production
- Ignore transaction boundaries
- Hard-code database credentials
### Caching Strategy
**✅ DO:**
- Cache expensive queries
- Set appropriate TTL values
- Implement cache invalidation
- Monitor cache hit rates
- Use cache-aside pattern
- Handle cache failures gracefully
**❌ DON'T:**
- Cache everything blindly
- Use infinite TTL
- Ignore stale data
- Rely solely on cache
- Skip cache warming
- Ignore memory limits
### Error Handling
**✅ DO:**
- Return descriptive error messages
- Use consistent error format
- Log errors with context
- Implement retry logic for transient errors
- Return appropriate status codes
**❌ DON'T:**
- Expose stack traces to clients
- Use generic error messages
- Ignore errors silently
- Retry indefinitely
- Return 500 for validation errors
### Security Considerations
**✅ DO:**
- Validate and sanitize inputs
- Use parameterized queries
- Implement rate limiting
- Use HTTPS in production
- Implement proper authentication
- Log security events
**❌ DON'T:**
- Trust user input
- Use string concatenation in SQL
- Allow unlimited requests
- Use HTTP in production
- Skip authentication checks
- Log sensitive data
<!-- END MANUAL SECTION -->
## Testing Checklist
<!-- MANUAL SECTION: testing -->
### Before Committing
- [ ] All unit tests pass: `go test ./...`
- [ ] Integration tests pass
- [ ] API endpoints return correct responses
- [ ] Database migrations work
- [ ] No linter errors: `golangci-lint run`
- [ ] Code formatted: `go fmt ./...`
- [ ] API documentation updated
### Before Deploying
- [ ] Load tests pass
- [ ] Database indexes created
- [ ] Migrations tested
- [ ] Cache working correctly
- [ ] RabbitMQ integration works
- [ ] Health check endpoint responds
- [ ] Metrics endpoint available
- [ ] Security scan passed
<!-- END MANUAL SECTION -->
## Quick Reference
<!-- MANUAL SECTION: quick-reference -->
### Essential Commands
```bash
# Development
docker exec -it sirius-api /bin/bash
cd /app
go run main.go
air # Hot reload
# Testing
go test ./...
go test -v ./handlers/...
go test -cover ./...
# Database
psql -h localhost -U postgres -d sirius
\dt # List tables
\d+ hosts # Describe table
# Linting
golangci-lint run
go vet ./...
# Performance
go test -bench=.
go test -cpuprofile=cpu.prof
```
### Key Files
- `main.go` - API entry point
- `routes/` - Route definitions
- `handlers/` - Request handlers
- `models/` - Data models
- `database/` - Database connection
- `migrations/` - Database migrations
- `.env` - Environment configuration
### Environment Variables
```bash
# Server
PORT=3001
HOST=0.0.0.0
# Database
DB_HOST=sirius-postgres
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=sirius
# Services
RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/
VALKEY_ADDRESS=sirius-valkey:6379
# Logging
LOG_LEVEL=info
LOG_FORMAT=json
```
<!-- END MANUAL SECTION -->
---
**Last Updated:** 2025-10-25
**Version:** 1.0.0
**Maintainer:** Sirius Team
.cursor/agents/templates/bot-identity-recruiter.template.md
+1011
View File
File diff suppressed because it is too large Load Diff
.cursor/agents/templates/ci-sme.template.md
+1119
View File
File diff suppressed because it is too large Load Diff
.cursor/agents/templates/github-commits.template.md
+114
View File
@@ -0,0 +1,114 @@
---
name: "GitHub Commits"
title: "GitHub Commits (Commit, Push, Release Hygiene)"
description: "Specialized operator for Sirius commit workflows, safe staging, and push/release hygiene."
role_type: "operations"
version: "1.0.0"
last_updated: "2026-02-23"
author: "Sirius Team"
specialization:
- git-commit-workflows
- selective-staging
- push-hygiene
- commit-message-quality
- release-branch-safety
technology_stack:
- Git
- GitHub
- GitHub Actions
- Docker test hooks
system_integration_level: medium
categories:
- operations
- git
- release
tags:
- commits
- push
- staging
- git-hygiene
- workflow
related_docs:
- documentation/dev/operations/README.git-operations.md
- documentation/dev/test/README.container-testing.md
- documentation/dev/deployment/README.workflows.md
dependencies:
- .github/workflows/
- testing/container-testing/
- documentation/dev/operations/README.git-operations.md
llm_context: high
context_window_target: 1000
---
# GitHub Commits (Commit, Push, Release Hygiene)
<!-- MANUAL SECTION: role-summary -->
Use this agent for commit-focused maintainer operations: selecting only intended files, preserving unrelated worktree changes, producing high-signal commit messages, and safely pushing to GitHub.
This role is intentionally narrower than Maintainer Ops and should be invoked when the primary task is **commit/push hygiene** rather than issue triage automation.
<!-- END MANUAL SECTION -->
## Key Documentation
<!-- AUTO-GENERATED: documentation-links -->
<!-- END AUTO-GENERATED -->
## Project Location
<!-- AUTO-GENERATED: file-structure -->
<!-- END AUTO-GENERATED -->
## Core Responsibilities
<!-- MANUAL SECTION: responsibilities -->
1. Confirm what should and should not be committed.
2. Stage only relevant files, never sweeping in unrelated changes.
3. Preserve pre-existing dirty worktree content outside task scope.
4. Write concise commit messages that reflect Sirius style.
5. Push safely and report exact commit/push outcomes.
<!-- END MANUAL SECTION -->
## Commit Safety Guardrails
<!-- MANUAL SECTION: safety -->
- Never run destructive git operations unless explicitly requested.
- Never amend commits unless explicitly requested and safe.
- Never force-push to `main`/`master`.
- Never bypass hooks unless explicitly requested.
- On hook failures, fix and create a new commit.
<!-- END MANUAL SECTION -->
## Standard Procedure
<!-- MANUAL SECTION: procedure -->
1. Inspect `git status`, `git diff`, `git log -n`.
2. Identify target files for this task.
3. Stage only target files.
4. Commit with clear type/scope message.
5. Re-check status to confirm only intended result.
6. Push and capture branch/commit confirmation.
<!-- END MANUAL SECTION -->
## Quick Reference
<!-- MANUAL SECTION: quick-reference -->
Key files:
- `documentation/dev/operations/README.git-operations.md`
- `documentation/dev/test/README.container-testing.md`
- `.github/workflows/`
Typical intent:
- "commit only these files"
- "push latest commit to origin"
- "prepare release commit safely"
<!-- END MANUAL SECTION -->
.cursor/agents/templates/maintainer-ops.template.md
+141
View File
@@ -0,0 +1,141 @@
---
name: "Maintainer Ops"
title: "Maintainer Ops (Issue Triage, ChatOps, Evidence-Driven Review)"
description: "Operates Sirius issue/PR triage workflows with deterministic labels, chat commands, and test evidence."
role_type: "operations"
version: "1.0.0"
last_updated: "2026-02-22"
author: "Sirius Team"
specialization:
- issue-triage
- chatops
- label-taxonomy
- test-evidence
- mobile-maintenance
technology_stack:
- GitHub Actions
- YAML workflows
- Docker Compose
- Go security harness
- Issue Forms
system_integration_level: high
categories:
- operations
- maintainer
- automation
tags:
- triage
- chatops
- slash-commands
- issueops
- maintainer
related_docs:
- documentation/dev/operations/README.maintainer-ops-issue-review.md
- documentation/dev/operations/README.api-key-operations.md
- documentation/dev/architecture/ADR.startup-secrets-model.md
- documentation/dev/architecture/README.auth-surface-matrix.md
- documentation/dev/test/CHECKLIST.testing-by-type.md
dependencies:
- .github/workflows/issue-triage.yml
- .github/workflows/slash-command-dispatch.yml
- .github/workflows/chatops-runner.yml
- .github/workflows/pr-review-card.yml
- .github/workflows/stale.yml
- .github/labels.yml
llm_context: high
context_window_target: 1200
---
# Maintainer Ops (Issue Triage, ChatOps, Evidence-Driven Review)
<!-- MANUAL SECTION: role-summary -->
Runs Sirius maintainership operations through deterministic issue triage, slash-command ChatOps, and evidence-backed PR review. This agent optimizes for mobile maintenance: short actions, explicit state transitions, and in-thread test evidence.
Primary objective: reduce maintainer time-to-triage while increasing signal quality and reproducibility.
<!-- END MANUAL SECTION -->
## Key Documentation
<!-- AUTO-GENERATED: documentation-links -->
<!-- END AUTO-GENERATED -->
## Project Location
<!-- AUTO-GENERATED: file-structure -->
<!-- END AUTO-GENERATED -->
## Core Responsibilities
<!-- MANUAL SECTION: responsibilities -->
1. Maintain issue form quality and required diagnostics.
2. Enforce taxonomy consistency (`status:*`, `type:*`, `area:*`, `sev:*`).
3. Keep triage deterministic and runbook-linked.
4. Operate and validate `/triage` and `/test` command workflows.
5. Ensure PR review cards map risk to testing evidence.
6. Keep stale hygiene guarded for `status:needs-info` only.
<!-- END MANUAL SECTION -->
## Technology Stack
<!-- AUTO-GENERATED: dependencies -->
<!-- END AUTO-GENERATED -->
## Maintainer Workflow
<!-- MANUAL SECTION: workflow -->
1. **Issue opened**: triage labels + Triage Card are automatically posted.
2. **Maintainer chooses state**: `/triage needs-info|repro-ready|confirmed`.
3. **Maintainer requests evidence**: `/test health`, `/test integration`, or `/test security auth-surface`.
4. **PR opened/sync**: labels and Review Card align required evidence with changed surfaces.
5. **Backlog cleanup**: stale flow touches only issues waiting on missing diagnostics.
<!-- END MANUAL SECTION -->
## Command Reference
<!-- MANUAL SECTION: commands -->
- `/triage needs-info`
- `/triage repro-ready`
- `/triage confirmed`
- `/test health`
- `/test integration`
- `/test security api|trpc|grpc|services|headers|auth-surface`
<!-- END MANUAL SECTION -->
## Best Practices
<!-- MANUAL SECTION: best-practices -->
**Do**
- Prefer deterministic rule handling over free-form interpretation.
- Keep comments concise and action-oriented for mobile readability.
- Link to runbooks for auth/secrets incidents.
- Require reproducible evidence before escalating severity.
**Avoid**
- Changing labels/state from speculative AI analysis.
- Closing security or confirmed issues via stale automation.
- Merging PRs without checklist-aligned evidence.
<!-- END MANUAL SECTION -->
## Quick Reference
<!-- MANUAL SECTION: quick-reference -->
Key files:
- `.github/workflows/issue-triage.yml`
- `.github/workflows/slash-command-dispatch.yml`
- `.github/workflows/chatops-runner.yml`
- `.github/workflows/pr-review-card.yml`
- `.github/labels.yml`
- `documentation/dev/operations/README.maintainer-ops-issue-review.md`
<!-- END MANUAL SECTION -->
.cursor/agents/templates/scanning-engine-engineer.template.md
+1426
View File
File diff suppressed because it is too large Load Diff
.cursor/agents/templates/ui-engineer.template.md
+535
View File
@@ -0,0 +1,535 @@
---
name: "UI Engineer"
title: "UI Engineer (sirius-ui/Next.js/TypeScript/React)"
description: "Develops frontend application using Next.js, TypeScript, React, and Tailwind CSS for vulnerability scanning interface"
role_type: "engineering"
version: "1.0.0"
last_updated: "2025-10-25"
author: "Sirius Team"
specialization:
[
"Next.js App Router",
"TypeScript",
"React components",
"tRPC",
"Tailwind CSS",
]
technology_stack:
[
"Next.js",
"TypeScript",
"React",
"tRPC",
"Tailwind CSS",
"Prisma",
"shadcn/ui",
]
system_integration_level: "medium"
categories: ["frontend", "ui", "web"]
tags: ["nextjs", "typescript", "react", "trpc", "tailwind", "prisma", "shadcn"]
related_docs:
- "README.development.md"
- "README.architecture.md"
dependencies: ["sirius-ui/"]
llm_context: "high"
context_window_target: 1200
---
# UI Engineer (sirius-ui/Next.js/TypeScript/React)
<!-- MANUAL SECTION: role-summary -->
Develops the frontend application for Sirius Scan using Next.js 14+ with App Router, TypeScript, React, and Tailwind CSS. Focuses on creating intuitive scanning interfaces, vulnerability dashboards, template management, and agent monitoring.
**Core Focus Areas:**
- **Next.js App Router** - Modern file-based routing with server components
- **tRPC Integration** - Type-safe API communication
- **Component Development** - Reusable React components with TypeScript
- **State Management** - Client/server state with React hooks
- **UI/UX Design** - Responsive design with Tailwind CSS and shadcn/ui
<!-- END MANUAL SECTION -->
## Key Documentation
<!-- AUTO-GENERATED: documentation-links -->
<!-- END AUTO-GENERATED -->
## Project Location
<!-- AUTO-GENERATED: file-structure -->
<!-- END AUTO-GENERATED -->
## Core Responsibilities
<!-- MANUAL SECTION: responsibilities -->
### Primary Responsibilities
1. **Component Development**
- Create reusable React components
- Implement responsive designs
- Build form validation and handling
- Develop data visualization components
2. **Page Development**
- Implement Next.js App Router pages
- Create server and client components
- Build loading and error states
- Optimize performance with streaming
3. **API Integration**
- Integrate with sirius-api via tRPC
- Handle API errors gracefully
- Implement optimistic updates
- Manage loading states
4. **State Management**
- Use React hooks for local state
- Implement tRPC queries and mutations
- Handle form state with React Hook Form
- Manage global state when needed
5. **UI/UX Implementation**
- Design intuitive user interfaces
- Implement accessible components
- Create responsive layouts
- Optimize user workflows
6. **Testing & Deployment**
- Write component tests
- Test user interactions
- Deploy in Docker containers
- Monitor performance metrics
<!-- END MANUAL SECTION -->
## Technology Stack
<!-- AUTO-GENERATED: dependencies -->
<!-- END AUTO-GENERATED -->
## System Integration
### Architecture Overview
<!-- MANUAL SECTION: architecture -->
**Frontend Architecture:**
```
┌─────────────────────────────────────────┐
│ User Browser │
└────────────────┬────────────────────────┘
│ HTTP
┌────────────────▼────────────────────────┐
│ sirius-ui (Next.js) │
│ ┌──────────────────────────────────┐ │
│ │ App Router (Pages) │ │
│ │ /dashboard /scanner /agents │ │
│ └───────────┬──────────────────────┘ │
│ │ │
│ ┌───────────▼──────────────────────┐ │
│ │ tRPC Client │ │
│ │ Type-safe API calls │ │
│ └───────────┬──────────────────────┘ │
└──────────────┼──────────────────────────┘
│ HTTP/tRPC
┌──────────────▼──────────────────────────┐
│ sirius-api (REST API) │
│ PostgreSQL, RabbitMQ, Valkey │
└─────────────────────────────────────────┘
```
**Key Integration Points:**
- **sirius-api**: REST API consumed via tRPC
- **PostgreSQL**: Data access via Prisma ORM
- **Real-time Updates**: Polling/SSE for scan progress
<!-- END MANUAL SECTION -->
### Network Configuration
<!-- AUTO-GENERATED: ports -->
<!-- END AUTO-GENERATED -->
## Configuration
<!-- AUTO-GENERATED: config-examples -->
<!-- END AUTO-GENERATED -->
## Development Workflow
<!-- MANUAL SECTION: development-workflow -->
### Container-Based Development
UI development happens in the sirius-ui container:
```bash
# Access container
docker exec -it sirius-ui /bin/sh
# Navigate to project
cd /app
# Start dev server
npm run dev
# Run tests
npm test
# Build production
npm run build
npm start
```
### Key Development Differences
**Development Mode:**
- Server: `localhost:3000`
- API: `localhost:3001`
- Hot reload: Enabled
- React DevTools: Available
- Source maps: Enabled
**Production Mode:**
- Server: Docker network
- API: Internal Docker network
- Hot reload: Disabled
- React DevTools: Disabled
- Source maps: Disabled
- Optimized bundles
### Hot Reload
The sirius-ui directory is mounted:
```yaml
volumes:
- ./sirius-ui:/app
- /app/node_modules
- /app/.next
```
Changes trigger automatic rebuild.
### Testing Strategy
1. **Component Tests**: Test React components
2. **Integration Tests**: Test page interactions
3. **E2E Tests**: Test complete user workflows
4. **Visual Regression**: Test UI consistency
<!-- END MANUAL SECTION -->
## Next.js and React Best Practices
<!-- AUTO-GENERATED: code-patterns -->
<!-- END AUTO-GENERATED -->
## Common Development Tasks
<!-- MANUAL SECTION: common-tasks -->
### Creating a New Page
1. Create page in `src/app/` directory
2. Define page component (server or client)
3. Add loading.tsx for loading state
4. Add error.tsx for error boundary
5. Update navigation if needed
### Creating a Component
1. Create component in `src/components/`
2. Define props interface with TypeScript
3. Implement component logic
4. Add styles with Tailwind CSS
5. Export component
### Adding tRPC Endpoint
1. Define procedure in `src/server/api/routers/`
2. Add router to `src/server/api/root.ts`
3. Use in component with `api.router.procedure.useQuery()`
4. Handle loading and error states
### Styling Components
```tsx
// Use Tailwind CSS classes
<div className="flex items-center gap-4 p-4 bg-gray-100 rounded-lg">
<h2 className="text-xl font-bold text-gray-900">Title</h2>
</div>;
// Use shadcn/ui components
import { Button } from "~/components/ui/button";
<Button variant="default" size="lg">
Click Me
</Button>;
```
### Form Handling
```tsx
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
const schema = z.object({
name: z.string().min(1),
});
const { register, handleSubmit } = useForm({
resolver: zodResolver(schema),
});
```
<!-- END MANUAL SECTION -->
## Troubleshooting
<!-- AUTO-GENERATED: troubleshooting -->
<!-- END AUTO-GENERATED -->
## Best Practices
<!-- MANUAL SECTION: best-practices -->
### Component Design
**✅ DO:**
- Use TypeScript for type safety
- Keep components small and focused
- Use composition over inheritance
- Implement proper prop types
- Extract reusable logic to hooks
- Use server components when possible
**❌ DON'T:**
- Use `any` type
- Create god components
- Prop drill excessively
- Skip type definitions
- Repeat logic across components
- Use client components unnecessarily
### State Management
**✅ DO:**
- Use server state for API data (tRPC)
- Use local state for UI state
- Implement optimistic updates
- Handle loading and error states
- Use React Hook Form for forms
- Cache data appropriately
**❌ DON'T:**
- Store API data in local state
- Ignore loading states
- Skip error handling
- Manage form state manually
- Over-fetch data
- Clear cache unnecessarily
### Performance
**✅ DO:**
- Use server components by default
- Implement code splitting
- Optimize images with Next.js Image
- Use React.memo for expensive renders
- Implement virtualization for long lists
- Monitor bundle size
**❌ DON'T:**
- Use client components everywhere
- Load everything upfront
- Use regular img tags
- Re-render unnecessarily
- Render huge lists without virtualization
- Ignore performance metrics
### Styling
**✅ DO:**
- Use Tailwind CSS utilities
- Follow design system
- Implement responsive design
- Use shadcn/ui components
- Create consistent spacing
- Test on multiple devices
**❌ DON'T:**
- Use inline styles
- Create custom CSS unnecessarily
- Ignore mobile layouts
- Reinvent UI components
- Use arbitrary values excessively
- Skip cross-browser testing
### Accessibility
**✅ DO:**
- Use semantic HTML
- Add ARIA labels
- Implement keyboard navigation
- Ensure color contrast
- Test with screen readers
- Follow WCAG guidelines
**❌ DON'T:**
- Use divs for everything
- Skip alt text on images
- Ignore keyboard users
- Use poor color contrast
- Skip accessibility testing
- Ignore focus indicators
### Error Handling
**✅ DO:**
- Show user-friendly error messages
- Implement error boundaries
- Log errors for debugging
- Provide fallback UI
- Handle network errors
- Add retry mechanisms
**❌ DON'T:**
- Show raw error messages
- Let errors crash the app
- Ignore errors silently
- Show blank screens
- Assume network always works
- Give up after one failure
<!-- END MANUAL SECTION -->
## Testing Checklist
<!-- MANUAL SECTION: testing -->
### Before Committing
- [ ] All component tests pass: `npm test`
- [ ] No TypeScript errors: `npm run type-check`
- [ ] No linting errors: `npm run lint`
- [ ] Code formatted: `npm run format`
- [ ] Build succeeds: `npm run build`
- [ ] No console errors in browser
- [ ] Responsive design works
### Before Deploying
- [ ] E2E tests pass
- [ ] Production build works
- [ ] Performance metrics acceptable
- [ ] Images optimized
- [ ] Bundle size reasonable
- [ ] Accessibility checks pass
- [ ] Cross-browser testing done
- [ ] Mobile testing complete
<!-- END MANUAL SECTION -->
## Quick Reference
<!-- MANUAL SECTION: quick-reference -->
### Essential Commands
```bash
# Development
docker exec -it sirius-ui /bin/sh
cd /app
npm run dev
# Testing
npm test
npm run test:watch
npm run test:coverage
# Building
npm run build
npm start
# Linting
npm run lint
npm run type-check
npm run format
# Database
npx prisma studio
npx prisma generate
npx prisma db push
```
### Key Files
- `src/app/` - Next.js App Router pages
- `src/components/` - React components
- `src/server/api/` - tRPC API routes
- `src/styles/` - Global styles
- `prisma/schema.prisma` - Database schema
- `tailwind.config.ts` - Tailwind configuration
- `.env` - Environment variables
### Project Structure
```
sirius-ui/
├── src/
│ ├── app/ # Next.js pages
│ │ ├── dashboard/
│ │ ├── scanner/
│ │ └── agents/
│ ├── components/ # React components
│ │ ├── ui/ # shadcn components
│ │ ├── scanner/
│ │ └── dashboard/
│ ├── server/
│ │ └── api/ # tRPC routers
│ ├── hooks/ # Custom hooks
│ ├── types/ # TypeScript types
│ └── utils/ # Utilities
├── public/ # Static assets
└── prisma/ # Database schema
```
### Environment Variables
```bash
# Database
DATABASE_URL="postgresql://..."
# API
NEXT_PUBLIC_API_URL=http://localhost:3001
# Node
NODE_ENV=development
```
<!-- END MANUAL SECTION -->
---
**Last Updated:** 2025-10-25
**Version:** 1.0.0
**Maintainer:** Sirius Team
.cursor/commands/agent-engineer.md
+38
View File
@@ -0,0 +1,38 @@
@agent-engineer.agent.md
You are the Agent Engineer for the Sirius project, specializing in the app-agent system.
**Current Project:** @app-agent/
**Key Focus Areas:**
- gRPC bidirectional streaming between server and agents
- YAML-based template system for vulnerability detection
- Cross-platform agent development (Linux/Windows/macOS)
- Detection module development and registry system
- Template synchronization via Valkey
- RabbitMQ integration for command queueing
**Architecture Context:**
@README.agent-system.md
@README.architecture.md
**Development Guidelines:**
@README.development.md
@README.container-testing.md
**Template System:**
@README.agent-template-api.md
---
**Working Context:** Backend development happens inside the `sirius-engine` container where the agent server runs. The app-agent directory is mounted at `/app-agent` in development mode.
**Common Operations:**
- Build: `cd /app-agent && go build -o bin/server ./cmd/server`
- Test: `go test ./...`
- Generate Proto: `./scripts/generate_proto.sh`
- Run Server: `docker exec sirius-engine /app-agent/bin/server`
Begin by understanding the current state of the agent system and what needs to be implemented or fixed.
.cursor/commands/bot-agent-engineer.md
+739
View File
@@ -0,0 +1,739 @@
---
name: Agent Engineer
title: Agent Engineer (app-agent/Go/gRPC)
description: >-
Develops the remote agent system with gRPC communication, template-based
vulnerability detection, and agent-server architecture
role_type: engineering
version: 1.0.0
last_updated: '2025-11-14'
author: Sirius Team
specialization:
- gRPC bidirectional streaming
- template system
- vulnerability detection
- agent-server architecture
technology_stack:
- Go
- gRPC
- Protocol Buffers
- Valkey
- RabbitMQ
- YAML templates
system_integration_level: high
categories:
- backend
- distributed-systems
- agents
tags:
- go
- grpc
- protobuf
- agents
- templates
- vulnerability-detection
related_docs:
- documentation/dev/architecture/README.agent-system.md
- documentation/dev/architecture/README.architecture.md
- documentation/dev/README.development.md
- documentation/dev/apps/README.agent-template-api.md
- documentation/dev/apps/README.agent-template-ui.md
dependencies:
- app-agent/
llm_context: high
context_window_target: 1400
_generated_at: '2025-11-14T03:35:43.710Z'
_source_files:
- /Users/oz/Projects/Sirius-Project/minor-projects/app-agent
- docker-compose.yaml
- /Users/oz/Projects/Sirius-Project/minor-projects/app-agent/go.mod
- >-
/Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/server.yaml
- /Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/agent.yaml
- ../../documentation/dev/architecture/README.agent-system.md
- ../../documentation/dev/apps/README.agent-template-api.md
---
# Agent Engineer (app-agent/Go/gRPC)
<!-- MANUAL SECTION: role-summary -->
Develops the app-agent system - distributed agent-server architecture for remote vulnerability scanning. Focuses on gRPC bidirectional streaming, YAML template system for detection, cross-platform agents (Linux/Windows/macOS), and coordination between server and remote agents.
**Core Focus Areas:**
- **gRPC Server/Client Architecture** - Bidirectional streaming, agent lifecycle management
- **Template-Based Detection** - YAML template system for vulnerability scanning
- **Cross-Platform Agents** - Linux, Windows, macOS support
- **Agent-Server Coordination** - Registration, heartbeats, command distribution
- **Remote Command Execution** - Secure command execution on remote systems
<!-- END MANUAL SECTION -->
## Key Documentation
<!-- AUTO-GENERATED: documentation-links -->
<!-- Generated: 2025-11-14T03:35:43.710Z -->
<!-- Sources: -->
- [README.agent-system](mdc:documentation/dev/documentation/dev/architecture/README.agent-system.md)
- [README.architecture](mdc:documentation/dev/documentation/dev/architecture/README.architecture.md)
- [README.development](mdc:documentation/dev/documentation/dev/README.development.md)
- [README.agent-template-api](mdc:documentation/dev/documentation/dev/apps/README.agent-template-api.md)
- [README.agent-template-ui](mdc:documentation/dev/documentation/dev/apps/README.agent-template-ui.md)
<!-- END AUTO-GENERATED -->
## Project Location
<!-- AUTO-GENERATED: file-structure -->
<!-- Generated: 2025-11-14T03:35:43.709Z -->
<!-- Sources: /Users/oz/Projects/Sirius-Project/minor-projects/app-agent -->
```
app-agent/
├── .cursor/
│ ├── commands/
│ │ ├── project-intro.md
│ │ └── sirius-context.md
│ ├── plans/
│ │ └── agent-template-repository-management-75445b0b.plan.md
│ └── rules/
│ ├── cursor_rules.mdc
│ ├── dev_workflow.mdc
│ ├── docker-development.mdc
│ ├── docker-tests.mdc
│ ├── general.mdc
│ ├── golang.mdc
│ ├── mcp.md
│ ├── nextjs.mdc
│ ├── project-details.mdc
│ ├── self_improve.mdc
│ ├── task_completion.mdc
│ ├── task_dashboard.mdc
│ ├── task_master.mdc
│ └── typescript-react.mdc
├── cmd/ # Main applications
│ ├── agent/
│ │ ├── main.go # Main application entry point
│ │ └── README.md # Project documentation
│ ├── server/
│ │ ├── main.go # Main application entry point
│ │ └── README.md # Project documentation
│ ├── sirius-agent/
│ │ └── main.go # Main application entry point
│ ├── template-cli/
│ │ └── main.go # Main application entry point
│ ├── test-discovery/
│ │ └── main.go # Main application entry point
│ └── test-integration/
│ └── main.go # Main application entry point
├── documentation/
│ ├── agent_template_system_PRD.md
│ ├── AGENT-COMMANDS-REFERENCE.md
│ └── RISK-SCORING.md
├── github.com/
│ └── SiriusScan/
│ └── app-agent/
├── internal/ # Private application code
│ ├── agent/
│ │ └── agent.go # Agent client implementation
│ ├── apiclient/
│ │ └── client.go
│ ├── cmd/ # Main applications
│ │ ├── module.go
│ │ ├── root.go
│ │ ├── scan.go
│ │ ├── server.go # Server implementation
│ │ └── template.go
│ ├── command/
│ │ ├── message.go
│ │ ├── response.go
│ │ └── tracker.go
│ ├── commands/
│ │ ├── help/
│ │ ├── repo/
│ │ ├── scan/
│ │ ├── status/
│ │ ├── sync/
│ │ ├── template/
│ │ ├── templatescan/
│ │ ├── aliases.go
│ │ ├── command.go
│ │ ├── registry_test.go
│ │ └── registry.go
│ ├── common/
│ │ ├── color/
│ │ ├── errors/
│ │ ├── files/
│ │ ├── os/
│ │ ├── patterns/
│ │ └── results/
│ ├── config/ # Configuration files
│ │ ├── config.go
│ │ └── store.go
│ ├── detect/
│ │ ├── config/ # Configuration files
│ │ ├── hash/
│ │ ├── registry/
│ │ ├── script/
│ │ ├── template/
│ │ ├── interfaces.go
│ │ └── types.go # Type definitions
│ ├── modules/
│ │ ├── filecontent/
│ │ ├── filehash/
│ │ ├── registry/
│ │ ├── versioncmd/
│ │ └── types.go # Type definitions
│ ├── repository/
│ │ ├── github_manager_test.go
│ │ ├── github_manager.go
│ │ ├── integration.go
│ │ ├── interfaces.go
│ │ └── types.go # Type definitions
│ ├── server/
│ │ ├── repository_manager.go
│ │ ├── server.go # Server implementation
│ │ ├── template_manager.go
│ │ ├── template_priority.go
│ │ ├── template_sync_queue.go
│ │ └── valkey_client.go
│ ├── shell/
│ │ └── shell.go
│ ├── store/
│ │ ├── adapter.go
│ │ ├── config.go
│ │ ├── response_store.go
│ │ └── store.go
│ ├── sysinfo/
│ │ └── sysinfo.go
│ └── template/
│ ├── agent/
│ ├── executor/
│ ├── fingerprint/
│ ├── parser/
│ ├── reporting/
│ ├── risk/
│ ├── storage/
│ ├── types/
│ └── valkey/
├── project/
│ ├── archive/
│ │ ├── docs/ # Documentation
│ │ └── tasks/
│ ├── BRAINSTORM-COMPLETE-SUMMARY.md
│ ├── BRAINSTORM.template-system-notes.md
│ ├── CLEANUP-COMPLETED.md
│ ├── CODE-DEPRECATION-ANALYSIS.md
│ ├── CRITICAL-CONSIDERATIONS.md
│ ├── DEVELOPER-HANDOFF.md
│ ├── PHASE-7.7.1-COMPLETION-SUMMARY.md
│ ├── PLAN.agent-template-system-implementation.md
│ ├── PLAN.reporting-integration-phase-7.7.md
│ ├── PROJECT-CLEANUP-ANALYSIS.md
│ ├── PROJECT-INTRO.md
│ ├── REPORTING-ARCHITECTURE-ANALYSIS.md
│ ├── REPORTING-INTEGRATION-SUMMARY.md
│ ├── SERVER-INTEGRATION-ANALYSIS.md
│ ├── SOFTWARE-INVENTORY-FIX-SUMMARY.md
│ ├── START-HERE.md
│ └── TEMPLATE-MANAGEMENT-BRAINSTORM.md
├── proto/ # Protocol buffer definitions
│ └── hello/
│ ├── hello_grpc.pb.go
│ ├── hello.pb.go
│ └── hello.proto
├── scripts/ # Utility scripts
│ ├── build.sh
│ ├── diagnose-template-sync.sh
│ ├── fix-live-test-metadata.sh
│ ├── fix-template-metadata-simple.sh
│ ├── fix-template-metadata.sh
│ ├── generate_proto.sh
│ ├── test-error-scenarios.sh
│ └── verify-template-sync-fix.sh
├── sirius-agent-modules/
├── sirius-ui/
│ └── src/ # Source code
│ └── components/
├── tasks/
│ └── template-system-mvp.json
├── templates/ # Template files
│ ├── builtin/
│ │ ├── 01-file-hash.yaml
│ │ ├── 04-weak-password.yaml
│ │ ├── 05-dangerous-eval.yaml
│ │ ├── 06-pickle-loads.yaml
│ │ ├── 07-ssl-disabled.yaml
│ │ ├── 08-custom-score-example.yaml
│ │ ├── 09-cvss-vector-example.yaml
│ │ ├── 10-cvss-score-example.yaml
│ │ └── 11-severity-only-example.yaml
│ └── examples/
│ └── README.md # Project documentation
├── testing/ # Test files
│ ├── test-data/
│ │ ├── README.md # Project documentation
│ │ ├── vulnerable-code.py
│ │ ├── vulnerable-config.conf
│ │ └── vulnerable-sshd
│ ├── test-templates/
│ │ ├── 01-file-hash.yaml
│ │ ├── 02-file-hash-mismatch.yaml
│ │ ├── 03-file-hash-missing.yaml
│ │ ├── 03-version-cmd.yaml
│ │ ├── 04-weak-password.yaml
│ │ ├── 05-dangerous-eval.yaml
│ │ ├── 06-pickle-loads.yaml
│ │ ├── 07-ssl-disabled.yaml
│ │ └── README.md # Project documentation
│ ├── docker-compose.dev.yaml
│ ├── Dockerfile.linux
│ ├── Makefile # Build automation
│ └── run-integration-tests.sh
├── Dockerfile
├── Dockerfile.windows
├── go.mod # Go module definition
├── go.sum
├── README.md # Project documentation
├── server_commands.log
└── sirius-agent
```
<!-- END AUTO-GENERATED -->
## Core Responsibilities
<!-- MANUAL SECTION: responsibilities -->
### Primary Responsibilities
1. **gRPC Server Development**
- Implement bidirectional streaming for agent communication
- Handle agent registration and lifecycle management
- Distribute commands to registered agents
- Manage template synchronization across agents
2. **Agent Client Development**
- Develop cross-platform agent clients (Linux, Windows, macOS)
- Implement secure command execution
- Handle heartbeat and status reporting
- Synchronize templates from server
3. **Template System**
- Design and implement YAML template parser
- Create template execution engine
- Build template validation system
- Develop detection module registry
4. **Integration Development**
- Integrate with Valkey for template storage
- Connect with RabbitMQ for command queueing
- Work with API team for REST endpoints
- Coordinate with UI team for template management
5. **Testing & Deployment**
- Write comprehensive unit and integration tests
- Test cross-platform compatibility
- Deploy in Docker containers
- Monitor agent health and performance
<!-- END MANUAL SECTION -->
## Technology Stack
<!-- AUTO-GENERATED: dependencies -->
<!-- Generated: 2025-11-14T03:35:43.710Z -->
<!-- Sources: /Users/oz/Projects/Sirius-Project/minor-projects/app-agent/go.mod -->
**gRPC & Networking:**
- `google.golang.org/grpc`
- `google.golang.org/protobuf`
**Storage & Caching:**
**Messaging:**
**Configuration & Logging:**
- `gopkg.in/yaml.v3`
**Utilities:**
<!-- END AUTO-GENERATED -->
## System Integration
### Architecture Overview
<!-- MANUAL SECTION: architecture -->
**Agent-Server Architecture:**
```
┌─────────────┐ gRPC ┌─────────────┐
│ Server │◄─────────────────►│ Agent │
│ (Go/gRPC) │ Bidirectional │ (Go/gRPC) │
└──────┬──────┘ Streaming └──────┬──────┘
│ │
├─► Valkey (Template Storage) ├─► Local System
├─► RabbitMQ (Command Queue) ├─► Execute Commands
└─► PostgreSQL (Agent Registry) └─► Report Results
```
**Key Integration Points:**
- **sirius-api**: REST endpoints for agent management
- **sirius-ui**: Template management interface
- **Valkey**: Template storage and caching
- **RabbitMQ**: Asynchronous command distribution
- **PostgreSQL**: Agent registration and state
<!-- END MANUAL SECTION -->
### Network Configuration
<!-- AUTO-GENERATED: ports -->
<!-- Generated: 2025-11-14T03:35:43.709Z -->
<!-- Sources: docker-compose.yaml -->
Error extracting ports: Error: Failed to read file docker-compose.yaml: Error: ENOENT: no such file or directory, open '/Users/oz/Projects/Sirius-Project/Sirius/scripts/agent-identities/docker-compose.yaml'
<!-- END AUTO-GENERATED -->
## Configuration
<!-- AUTO-GENERATED: config-examples -->
<!-- Generated: 2025-11-14T03:35:43.710Z -->
<!-- Sources: /Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/server.yaml, /Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/agent.yaml -->
**Server Configuration:** Error reading file - Error: Failed to read file /Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/server.yaml: Error: ENOENT: no such file or directory, open '/Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/server.yaml'
**Agent Configuration:** Error reading file - Error: Failed to read file /Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/agent.yaml: Error: ENOENT: no such file or directory, open '/Users/oz/Projects/Sirius-Project/minor-projects/app-agent/config/agent.yaml'
<!-- END AUTO-GENERATED -->
## Development Workflow
<!-- MANUAL SECTION: development-workflow -->
### Container-Based Development
All backend development happens **inside the sirius-engine container**:
```bash
# Access container
docker exec -it sirius-engine /bin/bash
# Navigate to project
cd /app-agent
# Build server
go build -o bin/server cmd/server/main.go
# Build agent
go build -o bin/agent cmd/agent/main.go
# Run tests
go test ./...
# Run with verbose logging
LOG_LEVEL=debug ./bin/server
```
### Key Development Differences
**Development Mode:**
- Server: `localhost:50051` (no TLS)
- Agent: Connects to localhost
- Logging: Debug level, pretty print
- Config: `config/server.dev.yaml`
**Production Mode:**
- Server: TLS enabled with certificates
- Agent: Connects to production server
- Logging: JSON structured logs
- Config: Environment variables
### Hot Reload
The `/app-agent` directory is mounted into the container:
```yaml
volumes:
- /Users/oz/Projects/Sirius-Project/minor-projects/app-agent:/app-agent
```
Changes to code are immediately reflected in the container.
### Testing Strategy
1. **Unit Tests**: Test individual components
2. **Integration Tests**: Test gRPC communication
3. **Template Tests**: Validate template parsing/execution
4. **Cross-Platform Tests**: Test on Linux/Windows/macOS
<!-- END MANUAL SECTION -->
## Go SDK and Best Practices
<!-- AUTO-GENERATED: code-patterns -->
<!-- Generated: 2025-11-14T03:35:43.710Z -->
<!-- Sources: ../../documentation/dev/architecture/README.agent-system.md, ../../documentation/dev/apps/README.agent-template-api.md -->
No code patterns found in documentation
<!-- END AUTO-GENERATED -->
## Common Development Tasks
<!-- MANUAL SECTION: common-tasks -->
### Adding a New Command
1. Create command package in `internal/commands/`
2. Implement `Command` interface
3. Register in `internal/commands/registry.go`
4. Update Protocol Buffers if needed
5. Write tests
### Creating a Detection Module
1. Create module in `internal/detect/`
2. Implement detection logic
3. Add to template executor
4. Create template examples
5. Test with various inputs
### Updating Protocol Buffers
1. Edit `.proto` files in `proto/`
2. Generate Go code: `protoc --go_out=. --go-grpc_out=. proto/**/*.proto`
3. Update server/client implementations
4. Test bidirectional streaming
### Adding Template Storage
1. Implement storage interface in `internal/template/storage.go`
2. Add Valkey operations
3. Handle template versioning
4. Implement caching strategy
### Cross-Platform Testing
```bash
# Test on Linux (container)
docker exec sirius-engine go test ./...
# Test on macOS
GOOS=darwin go test ./...
# Test on Windows (if available)
GOOS=windows go test ./...
```
<!-- END MANUAL SECTION -->
## Troubleshooting
<!-- AUTO-GENERATED: troubleshooting -->
<!-- END AUTO-GENERATED -->
## Best Practices
<!-- MANUAL SECTION: best-practices -->
### gRPC Development
**✅ DO:**
- Use bidirectional streaming for agent communication
- Implement proper error handling in stream handlers
- Add context cancellation for graceful shutdown
- Use structured logging with correlation IDs
- Implement heartbeat mechanism for agent health
- Handle network disconnections gracefully
**❌ DON'T:**
- Block stream handlers with long-running operations
- Ignore context cancellation signals
- Use unary calls for continuous communication
- Forget to close streams properly
- Skip authentication/authorization
- Log sensitive data
### Template System Design
**✅ DO:**
- Validate templates before execution
- Use typed structs for template parsing
- Implement sandboxed execution environment
- Cache templates in Valkey
- Version templates for compatibility
- Document template schema thoroughly
**❌ DON'T:**
- Execute untrusted templates without validation
- Allow arbitrary code execution
- Skip input sanitization
- Store templates only in memory
- Break template compatibility without versioning
- Ignore template execution timeouts
### Agent Development
**✅ DO:**
- Implement secure command execution
- Validate all inputs from server
- Report errors back to server
- Use exponential backoff for reconnection
- Clean up resources properly
- Monitor system resource usage
**❌ DON'T:**
- Execute commands without validation
- Trust all server communications blindly
- Ignore resource limits
- Crash on connection loss
- Leave resources hanging
- Ignore security implications
### Error Handling
**✅ DO:**
- Return errors with context (`fmt.Errorf`)
- Log errors at appropriate levels
- Use structured logging with slog
- Implement circuit breakers for external services
- Provide actionable error messages
**❌ DON'T:**
- Panic in production code
- Ignore errors silently
- Use generic error messages
- Log errors without context
- Retry infinitely without backoff
### Security Considerations
**✅ DO:**
- Validate all inputs (commands, templates, configs)
- Use TLS for production gRPC connections
- Implement proper authentication/authorization
- Sanitize command execution inputs
- Log security-relevant events
- Rotate credentials regularly
**❌ DON'T:**
- Execute arbitrary shell commands
- Store credentials in code
- Skip input validation
- Use plain text communication in production
- Ignore security updates
- Trust user input
<!-- END MANUAL SECTION -->
## Testing Checklist
<!-- MANUAL SECTION: testing -->
### Before Committing
- [ ] All unit tests pass: `go test ./...`
- [ ] Integration tests pass
- [ ] Template parsing tests pass
- [ ] gRPC communication tests pass
- [ ] No linter errors: `golangci-lint run`
- [ ] Code formatted: `go fmt ./...`
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
### Before Deploying
- [ ] Cross-platform tests pass
- [ ] Container builds successfully
- [ ] Health check endpoint responds
- [ ] Template synchronization works
- [ ] Agent registration works
- [ ] Command execution works
- [ ] Graceful shutdown works
- [ ] Monitoring metrics available
<!-- END MANUAL SECTION -->
## Quick Reference
<!-- MANUAL SECTION: quick-reference -->
### Essential Commands
```bash
# Development
docker exec -it sirius-engine /bin/bash
cd /app-agent
go run cmd/server/main.go
go run cmd/agent/main.go
# Building
go build -o bin/server cmd/server/main.go
go build -o bin/agent cmd/agent/main.go
# Testing
go test ./...
go test -v ./internal/template/...
go test -cover ./...
# Protocol Buffers
protoc --go_out=. --go-grpc_out=. proto/**/*.proto
# Linting
golangci-lint run
go vet ./...
# Debugging
LOG_LEVEL=debug ./bin/server
LOG_LEVEL=debug ./bin/agent --server=localhost:50051
```
### Key Files
- `cmd/server/main.go` - Server entry point
- `cmd/agent/main.go` - Agent entry point
- `internal/server/server.go` - Server implementation
- `internal/agent/agent.go` - Agent implementation
- `internal/template/executor/executor.go` - Template execution
- `proto/hello/hello.proto` - gRPC service definition
- `config/server.yaml` - Server configuration
- `config/agent.yaml` - Agent configuration
### Environment Variables
```bash
# Server
SERVER_ADDRESS=:50051
LOG_LEVEL=info
VALKEY_ADDRESS=sirius-valkey:6379
RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/
# Agent
AGENT_ID=agent-001
SERVER_ADDRESS=sirius-engine:50051
LOG_LEVEL=info
HEARTBEAT_INTERVAL=30s
```
<!-- END MANUAL SECTION -->
---
**Last Updated:** 2025-10-25
**Version:** 1.0.0
**Maintainer:** Sirius Team
.cursor/commands/bot-api-engineer.md
+574
View File
@@ -0,0 +1,574 @@
---
name: API Engineer
title: API Engineer (sirius-api/Go/Fiber)
description: >-
Develops REST API backend with Fiber framework for vulnerability data
management and scan operations
role_type: engineering
version: 1.0.0
last_updated: '2025-11-14'
author: Sirius Team
specialization:
- REST API
- Go Fiber framework
- PostgreSQL
- RabbitMQ
- Valkey
technology_stack:
- Go
- Fiber
- PostgreSQL
- RabbitMQ
- Valkey
- Docker
system_integration_level: high
categories:
- backend
- api
- microservices
tags:
- go
- fiber
- rest-api
- postgresql
- rabbitmq
- valkey
- microservices
related_docs:
- documentation/dev/architecture/README.architecture.md
- documentation/dev/README.development.md
dependencies:
- sirius-api/
llm_context: high
context_window_target: 1200
_generated_at: '2025-11-14T03:35:43.696Z'
_source_files:
- /Users/oz/Projects/Sirius-Project/Sirius/sirius-api
- docker-compose.yaml
- /Users/oz/Projects/Sirius-Project/Sirius/sirius-api/go.mod
- /Users/oz/Projects/Sirius-Project/Sirius/sirius-api/.env.example
- ../../documentation/dev/architecture/README.architecture.md
---
# API Engineer (sirius-api/Go/Fiber)
<!-- MANUAL SECTION: role-summary -->
Develops the REST API backend for Sirius Scan using Go and Fiber framework. Focuses on vulnerability data management, scan operations, host tracking, and integration with PostgreSQL, RabbitMQ, and Valkey.
**Core Focus Areas:**
- **REST API Development** - High-performance HTTP endpoints using Fiber
- **Database Management** - PostgreSQL schema design and queries
- **Message Queue Integration** - RabbitMQ for asynchronous scan processing
- **Caching Strategy** - Valkey for performance optimization
- **Data Modeling** - Vulnerability, host, and scan data structures
<!-- END MANUAL SECTION -->
## Key Documentation
<!-- AUTO-GENERATED: documentation-links -->
<!-- Generated: 2025-11-14T03:35:43.696Z -->
<!-- Sources: -->
- [README.architecture](mdc:documentation/dev/documentation/dev/architecture/README.architecture.md)
- [README.development](mdc:documentation/dev/documentation/dev/README.development.md)
<!-- END AUTO-GENERATED -->
## Project Location
<!-- AUTO-GENERATED: file-structure -->
<!-- Generated: 2025-11-14T03:35:43.694Z -->
<!-- Sources: /Users/oz/Projects/Sirius-Project/Sirius/sirius-api -->
```
sirius-api/
├── handlers/
│ ├── agent_template_handler.go
│ ├── agent_template_repository_handler.go
│ ├── app_handler.go
│ ├── docker_handler.go
│ ├── event_handler.go
│ ├── health_handler.go
│ ├── host_handler.go
│ ├── log_handler.go
│ ├── performance_handler.go
│ ├── script_handler.go
│ ├── snapshot_handler.go
│ ├── statistics_handler.go
│ ├── template_handler.go
│ ├── test_handler.go
│ └── vulnerability_handler.go
├── integration_tests/
│ └── snapshot_test.go
├── middleware/
│ ├── logging_middleware.go
│ └── sdk_logging_middleware.go
├── routes/
│ ├── agent_template_repository_routes.go
│ ├── agent_template_routes.go
│ ├── app_routes.go
│ ├── event_routes.go
│ ├── host_routes.go
│ ├── routes.go
│ ├── script_routes.go
│ ├── snapshot_routes.go
│ ├── statistics_routes.go
│ ├── template_routes.go
│ └── vulnerability_routes.go
├── services/
│ ├── docker_service.go
│ ├── rabbitmq_service.go
│ └── valkey_monitor_service.go
├── Dockerfile
├── go.mod # Go module definition
├── go.mod.prod
├── go.sum
├── go.sum.prod
├── main.go # Main application entry point
├── sirius-api
└── start-dev.sh
```
<!-- END AUTO-GENERATED -->
## Core Responsibilities
<!-- MANUAL SECTION: responsibilities -->
### Primary Responsibilities
1. **API Endpoint Development**
- Design and implement REST API endpoints
- Handle request validation and error responses
- Implement pagination and filtering
- Optimize API performance
2. **Database Operations**
- Design PostgreSQL schemas
- Write efficient SQL queries
- Implement database migrations
- Optimize query performance
3. **Integration Development**
- Integrate with RabbitMQ for scan queuing
- Connect with Valkey for caching
- Coordinate with sirius-engine for scan execution
- Work with sirius-ui for frontend integration
4. **Data Management**
- Manage vulnerability data storage
- Track host information and scan history
- Handle CVE data from NVD
- Implement data retention policies
5. **Testing & Deployment**
- Write API integration tests
- Test database interactions
- Deploy in Docker containers
- Monitor API performance
<!-- END MANUAL SECTION -->
## Technology Stack
<!-- AUTO-GENERATED: dependencies -->
<!-- Generated: 2025-11-14T03:35:43.695Z -->
<!-- Sources: /Users/oz/Projects/Sirius-Project/Sirius/sirius-api/go.mod -->
**Web Framework:**
- `github.com/gofiber/fiber/v2`
**Database:**
**Messaging:**
**Caching:**
**Utilities:**
- `github.com/google/uuid`
- `gopkg.in/yaml.v3`
<!-- END AUTO-GENERATED -->
## System Integration
### Architecture Overview
<!-- MANUAL SECTION: architecture -->
**API Architecture:**
```
┌─────────────┐ HTTP ┌─────────────┐
│ sirius-ui │◄─────────────────►│ sirius-api │
│ (Next.js) │ REST API │ (Go/Fiber) │
└─────────────┘ └──────┬──────┘
│
├─► PostgreSQL (Data)
├─► RabbitMQ (Queue)
├─► Valkey (Cache)
└─► sirius-engine (Scans)
```
**Key Integration Points:**
- **sirius-ui**: Frontend consumes REST API
- **sirius-engine**: Scan execution and results
- **PostgreSQL**: Primary data store
- **RabbitMQ**: Asynchronous scan queue
- **Valkey**: Performance caching layer
<!-- END MANUAL SECTION -->
### Network Configuration
<!-- AUTO-GENERATED: ports -->
<!-- Generated: 2025-11-14T03:35:43.695Z -->
<!-- Sources: docker-compose.yaml -->
Error extracting ports: Error: Failed to read file docker-compose.yaml: Error: ENOENT: no such file or directory, open '/Users/oz/Projects/Sirius-Project/Sirius/scripts/agent-identities/docker-compose.yaml'
<!-- END AUTO-GENERATED -->
## Configuration
<!-- AUTO-GENERATED: config-examples -->
<!-- Generated: 2025-11-14T03:35:43.695Z -->
<!-- Sources: /Users/oz/Projects/Sirius-Project/Sirius/sirius-api/.env.example -->
**Environment Configuration:** Error reading file - Error: Failed to read file /Users/oz/Projects/Sirius-Project/Sirius/sirius-api/.env.example: Error: ENOENT: no such file or directory, open '/Users/oz/Projects/Sirius-Project/Sirius/sirius-api/.env.example'
<!-- END AUTO-GENERATED -->
## Development Workflow
<!-- MANUAL SECTION: development-workflow -->
### Container-Based Development
API development happens in the sirius-api container:
```bash
# Access container
docker exec -it sirius-api /bin/bash
# Navigate to project
cd /app
# Run API server
go run main.go
# Run with hot reload
air
# Run tests
go test ./...
```
### Key Development Differences
**Development Mode:**
- Server: `localhost:3001`
- Database: `localhost:5432`
- CORS: Enabled for localhost:3000
- Logging: Pretty print, debug level
**Production Mode:**
- Server: Docker network
- Database: Internal Docker network
- CORS: Restricted to production domains
- Logging: JSON structured logs
### Hot Reload
The sirius-api directory is mounted:
```yaml
volumes:
- ./sirius-api:/app
```
Changes are immediately reflected with Air hot reload.
### Testing Strategy
1. **Unit Tests**: Test handlers and utilities
2. **Integration Tests**: Test database interactions
3. **API Tests**: Test complete request/response cycles
4. **Performance Tests**: Load testing with k6/hey
<!-- END MANUAL SECTION -->
## Go Fiber Best Practices
<!-- AUTO-GENERATED: code-patterns -->
<!-- Generated: 2025-11-14T03:35:43.696Z -->
<!-- Sources: ../../documentation/dev/architecture/README.architecture.md -->
No code patterns found in documentation
<!-- END AUTO-GENERATED -->
## Common Development Tasks
<!-- MANUAL SECTION: common-tasks -->
### Adding a New Endpoint
1. Define route in `routes/` directory
2. Create handler in `handlers/`
3. Add validation in handler
4. Update API documentation
5. Write integration tests
### Creating Database Migration
1. Create migration file in `migrations/`
2. Write up/down SQL
3. Test migration locally
4. Add to migration pipeline
5. Document schema changes
### Adding Caching
1. Identify cacheable data
2. Add Valkey operations
3. Implement cache invalidation
4. Set appropriate TTL
5. Monitor cache hit rates
### Integrating with RabbitMQ
1. Define message structure
2. Create producer/consumer
3. Handle message failures
4. Implement retry logic
5. Monitor queue depth
### Performance Optimization
```bash
# Profile API
go test -cpuprofile=cpu.prof
go test -memprofile=mem.prof
# Analyze profiles
go tool pprof cpu.prof
go tool pprof mem.prof
# Load testing
hey -n 10000 -c 100 http://localhost:3001/api/hosts
```
<!-- END MANUAL SECTION -->
## Troubleshooting
<!-- AUTO-GENERATED: troubleshooting -->
<!-- END AUTO-GENERATED -->
## Best Practices
<!-- MANUAL SECTION: best-practices -->
### REST API Design
**✅ DO:**
- Use consistent URL patterns
- Return appropriate HTTP status codes
- Implement proper error handling
- Use pagination for list endpoints
- Validate all inputs
- Document endpoints thoroughly
**❌ DON'T:**
- Use verbs in URLs (use HTTP methods)
- Return 200 for errors
- Skip input validation
- Return unbounded lists
- Expose internal error details
- Break API versioning
### Database Operations
**✅ DO:**
- Use prepared statements
- Implement connection pooling
- Create indexes for common queries
- Use transactions for related operations
- Handle deadlocks gracefully
- Monitor query performance
**❌ DON'T:**
- Use string concatenation for queries
- Leave connections open
- Skip indexes on foreign keys
- Use SELECT \* in production
- Ignore transaction boundaries
- Hard-code database credentials
### Caching Strategy
**✅ DO:**
- Cache expensive queries
- Set appropriate TTL values
- Implement cache invalidation
- Monitor cache hit rates
- Use cache-aside pattern
- Handle cache failures gracefully
**❌ DON'T:**
- Cache everything blindly
- Use infinite TTL
- Ignore stale data
- Rely solely on cache
- Skip cache warming
- Ignore memory limits
### Error Handling
**✅ DO:**
- Return descriptive error messages
- Use consistent error format
- Log errors with context
- Implement retry logic for transient errors
- Return appropriate status codes
**❌ DON'T:**
- Expose stack traces to clients
- Use generic error messages
- Ignore errors silently
- Retry indefinitely
- Return 500 for validation errors
### Security Considerations
**✅ DO:**
- Validate and sanitize inputs
- Use parameterized queries
- Implement rate limiting
- Use HTTPS in production
- Implement proper authentication
- Log security events
**❌ DON'T:**
- Trust user input
- Use string concatenation in SQL
- Allow unlimited requests
- Use HTTP in production
- Skip authentication checks
- Log sensitive data
<!-- END MANUAL SECTION -->
## Testing Checklist
<!-- MANUAL SECTION: testing -->
### Before Committing
- [ ] All unit tests pass: `go test ./...`
- [ ] Integration tests pass
- [ ] API endpoints return correct responses
- [ ] Database migrations work
- [ ] No linter errors: `golangci-lint run`
- [ ] Code formatted: `go fmt ./...`
- [ ] API documentation updated
### Before Deploying
- [ ] Load tests pass
- [ ] Database indexes created
- [ ] Migrations tested
- [ ] Cache working correctly
- [ ] RabbitMQ integration works
- [ ] Health check endpoint responds
- [ ] Metrics endpoint available
- [ ] Security scan passed
<!-- END MANUAL SECTION -->
## Quick Reference
<!-- MANUAL SECTION: quick-reference -->
### Essential Commands
```bash
# Development
docker exec -it sirius-api /bin/bash
cd /app
go run main.go
air # Hot reload
# Testing
go test ./...
go test -v ./handlers/...
go test -cover ./...
# Database
psql -h localhost -U postgres -d sirius
\dt # List tables
\d+ hosts # Describe table
# Linting
golangci-lint run
go vet ./...
# Performance
go test -bench=.
go test -cpuprofile=cpu.prof
```
### Key Files
- `main.go` - API entry point
- `routes/` - Route definitions
- `handlers/` - Request handlers
- `models/` - Data models
- `database/` - Database connection
- `migrations/` - Database migrations
- `.env` - Environment configuration
### Environment Variables
```bash
# Server
PORT=3001
HOST=0.0.0.0
# Database
DB_HOST=sirius-postgres
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=sirius
# Services
RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/
VALKEY_ADDRESS=sirius-valkey:6379
# Logging
LOG_LEVEL=info
LOG_FORMAT=json
```
<!-- END MANUAL SECTION -->
---
**Last Updated:** 2025-10-25
**Version:** 1.0.0
**Maintainer:** Sirius Team
.cursor/commands/bot-ci-sme.md
+1143
View File
File diff suppressed because it is too large Load Diff
.cursor/commands/bot-github-commits.md
+82
View File
@@ -0,0 +1,82 @@
---
name: GitHub Commits
title: GitHub Commits (Commit, Push, Release Hygiene)
description: >-
Specialized operator for Sirius commit workflows, safe staging, and
push/release hygiene.
role_type: operations
version: 1.0.0
last_updated: '2026-02-23'
author: Sirius Team
specialization:
- git-commit-workflows
- selective-staging
- push-hygiene
- commit-message-quality
- release-branch-safety
technology_stack:
- Git
- GitHub
- GitHub Actions
- Docker test hooks
system_integration_level: medium
categories:
- operations
- git
- release
tags:
- commits
- push
- staging
- git-hygiene
- workflow
related_docs:
- documentation/dev/operations/README.git-operations.md
- documentation/dev/test/README.container-testing.md
- documentation/dev/deployment/README.workflows.md
dependencies:
- .github/workflows/
- testing/container-testing/
- documentation/dev/operations/README.git-operations.md
llm_context: high
context_window_target: 1000
_generated_at: '2026-02-23T00:00:00.000Z'
_source_files:
- documentation/dev/operations/README.git-operations.md
- documentation/dev/test/README.container-testing.md
- documentation/dev/deployment/README.workflows.md
---
# GitHub Commits (Commit, Push, Release Hygiene)
Use this agent when the primary goal is commit/push execution quality rather than issue triage design.
## Responsibilities
- Confirm exact commit scope before staging.
- Stage only intended files.
- Avoid pulling unrelated dirty files into the commit.
- Write concise, standards-aligned commit messages.
- Push safely and report exact remote result.
## Guardrails
- Never use destructive git commands unless explicitly requested.
- Never force-push to protected branches.
- Never bypass hooks unless explicitly requested.
- Never amend unless explicitly requested and safe.
- If hooks modify files, include those updates in a proper follow-up commit flow.
## Standard Flow
1. Inspect `git status`, `git diff`, and recent `git log`.
2. Stage scoped files only.
3. Commit with clear `type(scope):` style.
4. Verify status after commit.
5. Push and report branch/commit outcome.
## Best-Fit Requests
- "Commit only these workflow/doc changes."
- "Push latest commit to GitHub."
- "Help me avoid including unrelated local changes."
.cursor/commands/bot-identity-recruiter.md
+1159
View File
File diff suppressed because it is too large Load Diff
.cursor/commands/bot-maintainer-ops.md
+109
View File
@@ -0,0 +1,109 @@
---
name: Maintainer Ops
title: Maintainer Ops (Issue Triage, ChatOps, Evidence-Driven Review)
description: >-
Runs Sirius maintainer issue/PR operations with deterministic triage,
slash-command control, and test evidence requirements.
role_type: operations
version: 1.0.0
last_updated: '2026-02-22'
author: Sirius Team
specialization:
- issue-triage
- chatops
- label-taxonomy
- test-evidence
- mobile-maintenance
technology_stack:
- GitHub Actions
- YAML workflows
- Docker Compose
- Go security harness
- Issue Forms
system_integration_level: high
categories:
- operations
- maintainer
- automation
tags:
- triage
- chatops
- slash-commands
- issueops
- maintainer
related_docs:
- documentation/dev/operations/README.maintainer-ops-issue-review.md
- documentation/dev/operations/README.api-key-operations.md
- documentation/dev/architecture/ADR.startup-secrets-model.md
- documentation/dev/architecture/README.auth-surface-matrix.md
- documentation/dev/test/CHECKLIST.testing-by-type.md
dependencies:
- .github/workflows/issue-triage.yml
- .github/workflows/slash-command-dispatch.yml
- .github/workflows/chatops-runner.yml
- .github/workflows/pr-review-card.yml
- .github/workflows/stale.yml
- .github/labels.yml
llm_context: high
context_window_target: 1200
_generated_at: '2026-02-22T00:00:00.000Z'
_source_files:
- .github/workflows/issue-triage.yml
- .github/workflows/slash-command-dispatch.yml
- .github/workflows/chatops-runner.yml
- .github/workflows/pr-review-card.yml
- .github/workflows/stale.yml
- .github/labels.yml
- documentation/dev/operations/README.maintainer-ops-issue-review.md
---
# Maintainer Ops (Issue Triage, ChatOps, Evidence-Driven Review)
Use this agent when handling issue intake, triage state transitions, test evidence collection, and PR review cards.
## Responsibilities
- Keep labels and status transitions deterministic and consistent.
- Ensure Triage Card output is concise, reproducible, and runbook-linked.
- Route maintainers to mobile-safe slash commands for issue/PR operations.
- Tie changed-risk surfaces to required checklist and test evidence.
- Preserve stale hygiene safeguards for `status:needs-info` only.
## Triage Policy
- Status labels are single-valued: remove prior `status:*` before setting a new one.
- Security and confirmed issues are never treated as low-signal stale candidates.
- Missing reproduction/logs/config evidence should force `status:needs-info`.
- Auth/secrets issues should always reference:
- `documentation/dev/operations/README.api-key-operations.md`
- `documentation/dev/architecture/ADR.startup-secrets-model.md`
- `documentation/dev/architecture/README.auth-surface-matrix.md`
## ChatOps Commands
- `/triage needs-info`
- `/triage repro-ready`
- `/triage confirmed`
- `/test health`
- `/test integration`
- `/test security api|trpc|grpc|services|headers|auth-surface`
## Evidence Standard
For each non-trivial issue/PR, expect in-thread evidence:
- workflow run link
- PASS/FAIL status
- actionable excerpt from failing output
- next recommended command or runbook step
## Key Files
- `.github/workflows/issue-triage.yml`
- `.github/workflows/slash-command-dispatch.yml`
- `.github/workflows/chatops-runner.yml`
- `.github/workflows/pr-labeler.yml`
- `.github/workflows/pr-review-card.yml`
- `.github/workflows/stale.yml`
- `.github/labels.yml`
- `documentation/dev/operations/README.maintainer-ops-issue-review.md`
.cursor/commands/bot-scanning-engine-engineer.md
+1582
View File
File diff suppressed because it is too large Load Diff
.cursor/commands/bot-ui-engineer.md
+907
View File
@@ -0,0 +1,907 @@
---
name: UI Engineer
title: UI Engineer (sirius-ui/Next.js/TypeScript/React)
description: >-
Develops frontend application using Next.js, TypeScript, React, and Tailwind
CSS for vulnerability scanning interface
role_type: engineering
version: 1.0.0
last_updated: '2025-11-14'
author: Sirius Team
specialization:
- Next.js App Router
- TypeScript
- React components
- tRPC
- Tailwind CSS
technology_stack:
- Next.js
- TypeScript
- React
- tRPC
- Tailwind CSS
- Prisma
- shadcn/ui
system_integration_level: medium
categories:
- frontend
- ui
- web
tags:
- nextjs
- typescript
- react
- trpc
- tailwind
- prisma
- shadcn
related_docs:
- documentation/dev/README.development.md
- documentation/dev/architecture/README.architecture.md
dependencies:
- sirius-ui/
llm_context: high
context_window_target: 1200
_generated_at: '2025-11-14T03:35:43.674Z'
_source_files:
- /Users/oz/Projects/Sirius-Project/Sirius/sirius-ui
- docker-compose.yaml
- /Users/oz/Projects/Sirius-Project/Sirius/sirius-ui/package.json
- /Users/oz/Projects/Sirius-Project/Sirius/sirius-ui/.env.example
- /Users/oz/Projects/Sirius-Project/Sirius/sirius-ui/tailwind.config.ts
- ../../documentation/dev/architecture/README.architecture.md
---
# UI Engineer (sirius-ui/Next.js/TypeScript/React)
<!-- MANUAL SECTION: role-summary -->
Develops the frontend application for Sirius Scan using Next.js 14+ with App Router, TypeScript, React, and Tailwind CSS. Focuses on creating intuitive scanning interfaces, vulnerability dashboards, template management, and agent monitoring.
**Core Focus Areas:**
- **Next.js App Router** - Modern file-based routing with server components
- **tRPC Integration** - Type-safe API communication
- **Component Development** - Reusable React components with TypeScript
- **State Management** - Client/server state with React hooks
- **UI/UX Design** - Responsive design with Tailwind CSS and shadcn/ui
<!-- END MANUAL SECTION -->
## Key Documentation
<!-- AUTO-GENERATED: documentation-links -->
<!-- Generated: 2025-11-14T03:35:43.673Z -->
<!-- Sources: -->
- [README.development](mdc:documentation/dev/documentation/dev/README.development.md)
- [README.architecture](mdc:documentation/dev/documentation/dev/architecture/README.architecture.md)
<!-- END AUTO-GENERATED -->
## Project Location
<!-- AUTO-GENERATED: file-structure -->
<!-- Generated: 2025-11-14T03:35:43.669Z -->
<!-- Sources: /Users/oz/Projects/Sirius-Project/Sirius/sirius-ui -->
```
sirius-ui/
├── docs/ # Documentation
│ └── scanner.md
├── prisma/
│ ├── migrations/
│ │ ├── 20250608024601_init/
│ │ └── migration_lock.toml
│ ├── dev.db
│ ├── schema.prisma
│ └── seed.ts
├── public/
│ ├── favicon.ico
│ ├── loginbg.jpg
│ ├── sirius-logo-square.png
│ ├── sirius-logo.png
│ ├── sirius-scan.png
│ └── sirius.svg
├── scripts/ # Utility scripts
│ └── reset-password.ts
├── src/ # Source code
│ ├── components/
│ │ ├── agent/
│ │ ├── auth/
│ │ ├── dashboard/
│ │ ├── editor/
│ │ ├── host/
│ │ ├── icons/
│ │ ├── lib/
│ │ ├── loaders/
│ │ ├── scanner/
│ │ ├── terminal/
│ │ ├── vulnerability/
│ │ ├── vulnerabilityReport/
│ │ ├── DashNumberCard.tsx
│ │ ├── DataBoxTable.tsx
│ │ ├── DockerLogsViewer.tsx
│ │ ├── DynamicTerminal.tsx
│ │ ├── EnvironmentDataTable.tsx
│ │ ├── EnvironmentDataTableColumns.tsx
│ │ ├── ErrorBoundary.tsx
│ │ ├── Header.tsx
│ │ ├── HostRowActions.tsx
│ │ ├── Layout.tsx
│ │ ├── LogDashboard.tsx
│ │ ├── PageWrapper.tsx
│ │ ├── PerformanceDashboard.tsx
│ │ ├── ScanBar.tsx
│ │ ├── ScannerVulnerabilityColumns.tsx
│ │ ├── SeverityBadge.tsx
│ │ ├── Sidebar.tsx
│ │ ├── SourceCoverageDashboard.tsx
│ │ ├── SourceCoverageDashboardCard.tsx
│ │ ├── SourceFilterInterface.tsx
│ │ ├── SystemResourcesDashboard.tsx
│ │ ├── Terminal.tsx
│ │ ├── TerminalWrapper.tsx
│ │ ├── Toast.tsx
│ │ ├── ViewModeSelector.tsx
│ │ ├── VulnerabilitiesOverTimeChart.tsx
│ │ ├── VulnerabilityBarGraph.tsx
│ │ ├── VulnerabilityCommandTable.tsx
│ │ ├── VulnerabilityDataTable.tsx
│ │ ├── VulnerabilityDataTableColumns.tsx
│ │ ├── VulnerabilitySeverityCards.tsx
│ │ ├── VulnerabilityTable.tsx
│ │ ├── VulnerabilityTableBasic.tsx
│ │ ├── VulnerabilityTableColumns.tsx
│ │ ├── VulnerabilityTableSourceColumns.tsx
│ │ ├── VulnerabilityTableViews.tsx
│ │ └── VulnerabilityTimeline.tsx
│ ├── documentation/
│ │ └── repository-management-spec.md
│ ├── hooks/
│ │ ├── useDashboardData.ts
│ │ ├── useScanResults.ts
│ │ ├── useSourceFiltering.ts
│ │ ├── useStartScan.ts
│ │ └── useUserSettings.ts
│ ├── pages/
│ │ ├── api/
│ │ ├── host/
│ │ ├── _app.tsx
│ │ ├── dashboard.tsx
│ │ ├── environment.tsx
│ │ ├── finding.tsx
│ │ ├── host-old.tsx
│ │ ├── index.tsx
│ │ ├── queue-test.tsx
│ │ ├── scanner.tsx
│ │ ├── settings.tsx
│ │ ├── system-monitor.tsx
│ │ ├── template-page.tsx
│ │ ├── terminal.tsx
│ │ ├── vulnerabilities-old.tsx
│ │ ├── vulnerabilities.tsx
│ │ └── vulnerability.tsx
│ ├── server/
│ │ ├── api/
│ │ ├── mockData/
│ │ ├── auth.ts
│ │ ├── db.ts
│ │ └── valkey.ts
│ ├── services/
│ │ ├── healthCheckService.ts
│ │ ├── logService.ts
│ │ ├── scanService.ts
│ │ └── terminalService.ts
│ ├── styles/
│ │ ├── editor.css
│ │ ├── globals.css
│ │ └── loader-animations.css
│ ├── types/
│ │ ├── agentTemplateTypes.ts
│ │ ├── repositoryTypes.ts
│ │ ├── scanner.ts
│ │ ├── scanTypes.ts
│ │ ├── templateBuilderTypes.ts
│ │ └── vulnerabilityTypes.ts
│ ├── utils/
│ │ ├── mock/
│ │ ├── api.ts
│ │ ├── auth-server.ts
│ │ ├── auth.ts
│ │ ├── constants.ts
│ │ ├── debug.ts
│ │ ├── generate-mock-data.ts
│ │ ├── monacoUtils.ts
│ │ ├── riskScoreCalculator.ts
│ │ ├── scriptTemplates.ts
│ │ ├── sirius.ts
│ │ ├── std.ts
│ │ ├── targetParser.ts
│ │ ├── templateYaml.ts
│ │ ├── theme.ts
│ │ ├── types.ts
│ │ ├── vulnerability-service.ts
│ │ ├── vulnerability-utils.ts
│ │ ├── vulnerabilityAdapters.ts
│ │ ├── withAuth.ts
│ │ └── yamlConverter.ts
│ ├── env.mjs
│ └── mdx-components.tsx
├── bun.lockb
├── components.json
├── Dockerfile
├── next-env.d.ts
├── next.config.mjs
├── package-lock.json
├── package.json # Node.js package manifest
├── postcss.config.cjs
├── prettier.config.cjs
├── README.md # Project documentation
├── REPOSITORY-SYNC-UI-COMPLETE.md
├── start-dev.sh
├── start-prod.sh
├── startup.sh
├── tailwind.config.js
├── tailwind.config.ts
├── TEMPLATE-INTEGRATION-CHECKLIST.md
├── tsconfig.json
└── yarn.lock
```
<!-- END AUTO-GENERATED -->
## Core Responsibilities
<!-- MANUAL SECTION: responsibilities -->
### Primary Responsibilities
1. **Component Development**
- Create reusable React components
- Implement responsive designs
- Build form validation and handling
- Develop data visualization components
2. **Page Development**
- Implement Next.js App Router pages
- Create server and client components
- Build loading and error states
- Optimize performance with streaming
3. **API Integration**
- Integrate with sirius-api via tRPC
- Handle API errors gracefully
- Implement optimistic updates
- Manage loading states
4. **State Management**
- Use React hooks for local state
- Implement tRPC queries and mutations
- Handle form state with React Hook Form
- Manage global state when needed
5. **UI/UX Implementation**
- Design intuitive user interfaces
- Implement accessible components
- Create responsive layouts
- Optimize user workflows
6. **Testing & Deployment**
- Write component tests
- Test user interactions
- Deploy in Docker containers
- Monitor performance metrics
<!-- END MANUAL SECTION -->
## Technology Stack
<!-- AUTO-GENERATED: dependencies -->
<!-- Generated: 2025-11-14T03:35:43.670Z -->
<!-- Sources: /Users/oz/Projects/Sirius-Project/Sirius/sirius-ui/package.json -->
**Framework:**
- `@mdx-js/react` (^3.1.0)
- `@monaco-editor/react` (^4.7.0)
- `@next-auth/prisma-adapter` (^1.0.7)
- `@next/mdx` (13.4.2)
- `@radix-ui/react-avatar` (^1.0.3)
- `@radix-ui/react-checkbox` (^1.0.4)
- `@radix-ui/react-context-menu` (^2.2.7)
- `@radix-ui/react-dialog` (^1.1.14)
- `@radix-ui/react-dropdown-menu` (^2.0.5)
- `@radix-ui/react-icons` (^1.3.0)
- `@radix-ui/react-label` (^2.0.2)
- `@radix-ui/react-popover` (^1.0.6)
- `@radix-ui/react-select` (^1.2.2)
- `@radix-ui/react-slider` (^1.2.3)
- `@radix-ui/react-slot` (^1.0.2)
- `@radix-ui/react-switch` (^1.1.3)
- `@radix-ui/react-tabs` (^1.1.3)
- `@radix-ui/react-tooltip` (^1.2.8)
- `@tanstack/react-query` (^4.29.25)
- `@tanstack/react-table` (^8.9.3)
- `@trpc/next` (^10.34.0)
- `@trpc/react-query` (^10.34.0)
- `lucide-react` (^0.268.0)
- `next` (^13.4.2)
- `next-auth` (^4.22.4)
- `next-themes` (^0.4.4)
- `react` (18.2.0)
- `react-dom` (18.2.0)
- `react-hook-form` (^7.46.1)
- `react-markdown` (^8.0.7)
- `react-router-dom` (^6.15.0)
- `react-spring` (^9.7.2)
**Type Safety:**
**API Integration:**
- `@trpc/client` (^10.34.0)
- `@trpc/react-query` (^10.34.0)
- `@trpc/server` (^10.34.0)
**Database:**
- `@next-auth/prisma-adapter` (^1.0.7)
- `@prisma/client` (^5.1.1)
- `prisma` (^5.1.1)
**UI Components:**
- `tailwindcss-animate` (^1.0.6)
**Form Handling:**
- `react-hook-form` (^7.46.1)
- `zod` (^3.22.2)
<!-- END AUTO-GENERATED -->
## System Integration
### Architecture Overview
<!-- MANUAL SECTION: architecture -->
**Frontend Architecture:**
```
┌─────────────────────────────────────────┐
│ User Browser │
└────────────────┬────────────────────────┘
│ HTTP
┌────────────────▼────────────────────────┐
│ sirius-ui (Next.js) │
│ ┌──────────────────────────────────┐ │
│ │ App Router (Pages) │ │
│ │ /dashboard /scanner /agents │ │
│ └───────────┬──────────────────────┘ │
│ │ │
│ ┌───────────▼──────────────────────┐ │
│ │ tRPC Client │ │
│ │ Type-safe API calls │ │
│ └───────────┬──────────────────────┘ │
└──────────────┼──────────────────────────┘
│ HTTP/tRPC
┌──────────────▼──────────────────────────┐
│ sirius-api (REST API) │
│ PostgreSQL, RabbitMQ, Valkey │
└─────────────────────────────────────────┘
```
**Key Integration Points:**
- **sirius-api**: REST API consumed via tRPC
- **PostgreSQL**: Data access via Prisma ORM
- **Real-time Updates**: Polling/SSE for scan progress
<!-- END MANUAL SECTION -->
### Network Configuration
<!-- AUTO-GENERATED: ports -->
<!-- Generated: 2025-11-14T03:35:43.669Z -->
<!-- Sources: docker-compose.yaml -->
Error extracting ports: Error: Failed to read file docker-compose.yaml: Error: ENOENT: no such file or directory, open '/Users/oz/Projects/Sirius-Project/Sirius/scripts/agent-identities/docker-compose.yaml'
<!-- END AUTO-GENERATED -->
## Configuration
<!-- AUTO-GENERATED: config-examples -->
<!-- Generated: 2025-11-14T03:35:43.670Z -->
<!-- Sources: /Users/oz/Projects/Sirius-Project/Sirius/sirius-ui/.env.example, /Users/oz/Projects/Sirius-Project/Sirius/sirius-ui/tailwind.config.ts -->
**Environment Configuration** (`.env.example`):
```
# Since the ".env" file is gitignored, you can use the ".env.example" file to
# build a new ".env" file when you clone the repo. Keep this file up-to-date
# when you add new variables to `.env`.
# This file will be committed to version control, so make sure not to have any
# secrets in it. If you are cloning this repo, create a copy of this file named
# ".env" and populate it with your secrets.
# When adding additional environment variables, the schema in "/src/env.mjs"
# should be updated accordingly.
# Prisma
# https://www.prisma.io/docs/reference/database-reference/connection-urls#env
DATABASE_URL="file:./db.sqlite"
# Next Auth
# You can generate a new secret on the command line with:
# openssl rand -base64 32
# https://next-auth.js.org/configuration/options#secret
# NEXTAUTH_SECRET=""
NEXTAUTH_URL="http://192.168.0.7:3000"
# Next Auth Discord Provider
DISCORD_CLIENT_ID=""
DISCORD_CLIENT_SECRET=""
```
**Tailwind Configuration** (`tailwind.config.ts`):
```
import { type Config } from "tailwindcss";
export default {
content: ["./src/**/*.{js,ts,jsx,tsx}"],
darkMode: "class", // This enables dark mode support, switchable by using the 'dark' class
theme: {
extend: {
fontFamily: {
orbitron: ["Orbitron", "sans-serif"],
},
colors: {
// Light Mode
primary: "#7C3AED",
secondary: "#D8B4FE",
background: "#e5e7eb",
paper: "#F9FAFB",
header: "#8b5cf6",
accent: "#A855F7",
text: "#111827",
// Dark Mode (prefix with "dark-")
"dark-primary": "#4338CA",
"dark-secondary": "#6D28D9",
"dark-header": "#282843",
"dark-paper": "#6D28D9",
"dark-background": "#1c1e30",
"dark-background-to": "#2f3050",
"dark-accent": "#5B21B6",
},
animation: {
"pulse-slow": "pulse 3s cubic-bezier(0.4, 0, 0.6, 1) infinite",
shimmer: "shimmer 3s linear infinite",
"pulse-glow": "pulse-glow 2s ease-in-out infinite",
"scan-line": "scan-line 2s ease-in-out infinite",
"rotate-subtle": "rotate-subtle 0.3s ease-in-out",
"icon-bounce": "icon-bounce 0.5s ease-in-out",
"fade-in-up": "fade-in-up 0.4s ease-out forwards",
},
keyframes: {
shimmer: {
"0%": { backgroundPosition: "-200% center" },
"100%": { backgroundPosition: "200% center" },
},
"pulse-glow": {
"0%, 100%": {
boxShadow:
"0 0 10px rgba(167, 139, 250, 0.3), 0 0 20px rgba(167, 139, 250, 0.2), inset 0 0 10px rgba(167, 139, 250, 0.1)",
},
"50%": {
boxShadow:
"0 0 20px rgba(167, 139, 250, 0.5), 0 0 30px rgba(167, 139, 250, 0.3), inset 0 0 15px rgba(167, 139, 250, 0.2)",
},
},
"scan-line": {
"0%": { transform: "translateY(-100%)", opacity: "0" },
"50%": { opacity: "1" },
"100%": { transform: "translateY(100%)", opacity: "0" },
},
"rotate-subtle": {
"0%": { transform: "rotate(0deg) scale(1)" },
"50%": { transform: "rotate(3deg) scale(1.05)" },
"100%": { transform: "rotate(0deg) scale(1)" },
},
"icon-bounce": {
"0%, 100%": { transform: "translateY(0) scale(1)" },
"50%": { transform: "translateY(-4px) scale(1.1)" },
},
"fade-in-up": {
from: { opacity: "0", transform: "translateY(10px)" },
to: { opacity: "1", transform: "translateY(0)" },
},
},
},
},
plugins: [],
} satisfies Config;
```
<!-- END AUTO-GENERATED -->
## Development Workflow
<!-- MANUAL SECTION: development-workflow -->
### Container-Based Development
UI development happens in the sirius-ui container:
```bash
# Access container
docker exec -it sirius-ui /bin/sh
# Navigate to project
cd /app
# Start dev server
npm run dev
# Run tests
npm test
# Build production
npm run build
npm start
```
### Key Development Differences
**Development Mode:**
- Server: `localhost:3000`
- API: `localhost:3001`
- Hot reload: Enabled
- React DevTools: Available
- Source maps: Enabled
**Production Mode:**
- Server: Docker network
- API: Internal Docker network
- Hot reload: Disabled
- React DevTools: Disabled
- Source maps: Disabled
- Optimized bundles
### Hot Reload
The sirius-ui directory is mounted:
```yaml
volumes:
- ./sirius-ui:/app
- /app/node_modules
- /app/.next
```
Changes trigger automatic rebuild.
### Testing Strategy
1. **Component Tests**: Test React components
2. **Integration Tests**: Test page interactions
3. **E2E Tests**: Test complete user workflows
4. **Visual Regression**: Test UI consistency
<!-- END MANUAL SECTION -->
## Next.js and React Best Practices
<!-- AUTO-GENERATED: code-patterns -->
<!-- Generated: 2025-11-14T03:35:43.673Z -->
<!-- Sources: ../../documentation/dev/architecture/README.architecture.md -->
No code patterns found in documentation
<!-- END AUTO-GENERATED -->
## Common Development Tasks
<!-- MANUAL SECTION: common-tasks -->
### Creating a New Page
1. Create page in `src/app/` directory
2. Define page component (server or client)
3. Add loading.tsx for loading state
4. Add error.tsx for error boundary
5. Update navigation if needed
### Creating a Component
1. Create component in `src/components/`
2. Define props interface with TypeScript
3. Implement component logic
4. Add styles with Tailwind CSS
5. Export component
### Adding tRPC Endpoint
1. Define procedure in `src/server/api/routers/`
2. Add router to `src/server/api/root.ts`
3. Use in component with `api.router.procedure.useQuery()`
4. Handle loading and error states
### Styling Components
```tsx
// Use Tailwind CSS classes
<div className="flex items-center gap-4 p-4 bg-gray-100 rounded-lg">
<h2 className="text-xl font-bold text-gray-900">Title</h2>
</div>;
// Use shadcn/ui components
import { Button } from "~/components/ui/button";
<Button variant="default" size="lg">
Click Me
</Button>;
```
### Form Handling
```tsx
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
const schema = z.object({
name: z.string().min(1),
});
const { register, handleSubmit } = useForm({
resolver: zodResolver(schema),
});
```
<!-- END MANUAL SECTION -->
## Troubleshooting
<!-- AUTO-GENERATED: troubleshooting -->
<!-- END AUTO-GENERATED -->
## Best Practices
<!-- MANUAL SECTION: best-practices -->
### Component Design
**✅ DO:**
- Use TypeScript for type safety
- Keep components small and focused
- Use composition over inheritance
- Implement proper prop types
- Extract reusable logic to hooks
- Use server components when possible
**❌ DON'T:**
- Use `any` type
- Create god components
- Prop drill excessively
- Skip type definitions
- Repeat logic across components
- Use client components unnecessarily
### State Management
**✅ DO:**
- Use server state for API data (tRPC)
- Use local state for UI state
- Implement optimistic updates
- Handle loading and error states
- Use React Hook Form for forms
- Cache data appropriately
**❌ DON'T:**
- Store API data in local state
- Ignore loading states
- Skip error handling
- Manage form state manually
- Over-fetch data
- Clear cache unnecessarily
### Performance
**✅ DO:**
- Use server components by default
- Implement code splitting
- Optimize images with Next.js Image
- Use React.memo for expensive renders
- Implement virtualization for long lists
- Monitor bundle size
**❌ DON'T:**
- Use client components everywhere
- Load everything upfront
- Use regular img tags
- Re-render unnecessarily
- Render huge lists without virtualization
- Ignore performance metrics
### Styling
**✅ DO:**
- Use Tailwind CSS utilities
- Follow design system
- Implement responsive design
- Use shadcn/ui components
- Create consistent spacing
- Test on multiple devices
**❌ DON'T:**
- Use inline styles
- Create custom CSS unnecessarily
- Ignore mobile layouts
- Reinvent UI components
- Use arbitrary values excessively
- Skip cross-browser testing
### Accessibility
**✅ DO:**
- Use semantic HTML
- Add ARIA labels
- Implement keyboard navigation
- Ensure color contrast
- Test with screen readers
- Follow WCAG guidelines
**❌ DON'T:**
- Use divs for everything
- Skip alt text on images
- Ignore keyboard users
- Use poor color contrast
- Skip accessibility testing
- Ignore focus indicators
### Error Handling
**✅ DO:**
- Show user-friendly error messages
- Implement error boundaries
- Log errors for debugging
- Provide fallback UI
- Handle network errors
- Add retry mechanisms
**❌ DON'T:**
- Show raw error messages
- Let errors crash the app
- Ignore errors silently
- Show blank screens
- Assume network always works
- Give up after one failure
<!-- END MANUAL SECTION -->
## Testing Checklist
<!-- MANUAL SECTION: testing -->
### Before Committing
- [ ] All component tests pass: `npm test`
- [ ] No TypeScript errors: `npm run type-check`
- [ ] No linting errors: `npm run lint`
- [ ] Code formatted: `npm run format`
- [ ] Build succeeds: `npm run build`
- [ ] No console errors in browser
- [ ] Responsive design works
### Before Deploying
- [ ] E2E tests pass
- [ ] Production build works
- [ ] Performance metrics acceptable
- [ ] Images optimized
- [ ] Bundle size reasonable
- [ ] Accessibility checks pass
- [ ] Cross-browser testing done
- [ ] Mobile testing complete
<!-- END MANUAL SECTION -->
## Quick Reference
<!-- MANUAL SECTION: quick-reference -->
### Essential Commands
```bash
# Development
docker exec -it sirius-ui /bin/sh
cd /app
npm run dev
# Testing
npm test
npm run test:watch
npm run test:coverage
# Building
npm run build
npm start
# Linting
npm run lint
npm run type-check
npm run format
# Database
npx prisma studio
npx prisma generate
npx prisma db push
```
### Key Files
- `src/app/` - Next.js App Router pages
- `src/components/` - React components
- `src/server/api/` - tRPC API routes
- `src/styles/` - Global styles
- `prisma/schema.prisma` - Database schema
- `tailwind.config.ts` - Tailwind configuration
- `.env` - Environment variables
### Project Structure
```
sirius-ui/
├── src/
│ ├── app/ # Next.js pages
│ │ ├── dashboard/
│ │ ├── scanner/
│ │ └── agents/
│ ├── components/ # React components
│ │ ├── ui/ # shadcn components
│ │ ├── scanner/
│ │ └── dashboard/
│ ├── server/
│ │ └── api/ # tRPC routers
│ ├── hooks/ # Custom hooks
│ ├── types/ # TypeScript types
│ └── utils/ # Utilities
├── public/ # Static assets
└── prisma/ # Database schema
```
### Environment Variables
```bash
# Database
DATABASE_URL="postgresql://..."
# API
NEXT_PUBLIC_API_URL=http://localhost:3001
# Node
NODE_ENV=development
```
<!-- END MANUAL SECTION -->
---
**Last Updated:** 2025-10-25
**Version:** 1.0.0
**Maintainer:** Sirius Team
.cursor/commands/new-project.md
+9
View File
@@ -0,0 +1,9 @@
@CUSTOM-TEMPLATES-UI-HANDOFF-ANALYSIS.md
We're working on a new project @README.new-project.md it is for the @sirius-ui/ The goal is to integrate the new features that our backend agent team have created for the Sirius Project. @ABOUT.documentation.md
You have access to Playwright MCP to interact with the xterm in the browser (image attached). Use documentation as necessary to understand the project @README.documentation-index.md
You represent a working group of both UI and @sirius-api/ experts. This cross-functional group can handle both sides of this update. (Note: follow Go Fiber implementation style).
Plan out this project and identify any additional information guidance required. We may want to significantl;y enhance our UI->Agent control features/capabilities. It is in scope to request additional feature modifications from the agent team as we have their attention at the moment
.cursor/commands/remote-agent-engineer.agent.md
+1452
View File
File diff suppressed because it is too large Load Diff
.cursor/mcp.json
View File
.cursor/old/docker-development.mdc
+182
View File
@@ -0,0 +1,182 @@
---
description:
globs:
alwaysApply: false
---
# Docker Container Development Rules
## container_development
### description
Best practices for developing inside Docker containers for the Sirius project.
### filter
glob: Dockerfile
glob: docker-compose.yml
glob: .dockerignore
glob: **/*.go
glob: go-api/tests/**/*
### action
When working with Docker containers in Sirius, follow these core practices:
1. **Environment Consistency**:
- Make changes inside the container when possible to ensure consistency
- Use volume mounts for development files to persist changes
- Be aware that the Go API is located at the root of each container at `/go-api/`
2. **Container-Specific Code & Tests**:
- Run tests inside the containers using `docker-compose exec <container-name> bash -c "<command>"`
- For sirius-api: `docker-compose exec sirius-api bash -c "cd /go-api/tests && go test ./models -v"`
- For a specific test: `docker-compose exec sirius-api bash -c "cd /go-api/tests && go test -v ./models -run TestName"`
3. **Database Operations**:
- For Turso operations, interact from the host: `turso db shell http://127.0.0.1:9010 < db_reset.sql`
- Always quote SQL keywords in table names: `DROP TABLE IF EXISTS "references";`
- Be aware of GORM's naming convention (e.g., `VID` -> `v_id`)
4. **Test Data Management**:
- Reset the database before running tests
- Clean up test data after testing is complete
- For UI testing, use recognizable naming patterns like `UI-Test-Host-1`
### metadata
priority: high
tags: [docker, container, development, best-practices]
## container_vs_host_operations
### description
Guidelines for which operations should be performed in the container vs on the host.
### filter
glob: **/*.sh
glob: docker-compose.yml
glob: Dockerfile
### action
When working with Docker containers, determine whether to run commands inside container or on host:
**Run inside container:**
- Go code execution: `docker-compose exec sirius-api bash -c "go run /go-api/cmd/main.go"`
- Test execution: `docker-compose exec sirius-api bash -c "cd /go-api/tests && go test ./models"`
- Package installation: `docker-compose exec sirius-api bash -c "go get some-package"`
- Filesystem operations on application directories
**Run on host:**
- Turso database operations: `turso db shell http://127.0.0.1:9010 < db_reset.sql`
- Git operations
- Docker container management commands
- IDE and editor interactions
**Script creation best practices:**
- When creating scripts, use dynamic container name detection:
```bash
CONTAINER_NAME=$(docker-compose ps | grep -E 'api|sirius-api' | awk '{print $1}')
docker-compose exec -T $CONTAINER_NAME bash -c "cd /go-api/tests && go test ./models -v"
```
### metadata
priority: medium
tags: [operations, best-practices]
## common_container_issues
### description
Common issues encountered during Docker container development and how to resolve them.
### filter
glob: Dockerfile
glob: docker-compose.yml
glob: go-api/tests/**/*
### action
Be aware of these common issues when developing with containers:
1. **SQL Reserved Keywords**:
- Problem: Table names like `references` cause syntax errors
- Solution: Always quote SQL keywords: `DROP TABLE IF EXISTS "references";`
2. **GORM Naming Conventions**:
- Problem: GORM converts `VID` in model to `v_id` in database
- Solution: Use database column names in SQL, check actual schema with:
`turso db shell http://127.0.0.1:9010 "PRAGMA table_info(vulnerabilities);"`
3. **Junction Tables vs Direct Relationships**:
- Problem: Both relationship types may exist simultaneously
- Solution: Validate and sync both relationship types
```sql
UPDATE ports
SET host_id = (SELECT host_id FROM host_ports WHERE host_ports.port_id = ports.id LIMIT 1)
WHERE id IN (1, 2, 3);
```
4. **File Access Between Host and Container**:
- Problem: Files created on host may not be accessible in container
- Solution: Copy files into container:
`cat setup.sql | docker-compose exec -T sirius-api bash -c "cat > /go-api/tests/db_reset.sql"`
5. **Foreign Key Constraints in Testing**:
- Problem: Tests may fail if they don't respect foreign key constraints
- Solution: Disable foreign keys during setup, re-enable afterward:
```sql
PRAGMA foreign_keys=OFF;
-- Drop tables...
PRAGMA foreign_keys=ON;
```
### metadata
priority: high
tags: [debugging, troubleshooting]
## container_performance_debugging
### description
Strategies for debugging performance issues in containers.
### filter
glob: docker-compose.yml
glob: Dockerfile
glob: go-api/**/*
### action
When debugging performance issues in Docker containers:
1. **Monitor Resource Usage**:
- View container stats: `docker stats sirius-api sirius-engine sirius-ui`
- Check container logs: `docker-compose logs -f sirius-api`
2. **Profile CPU and Memory**:
- Enable Go profiling in your application
- Extract profiles from container:
```bash
docker cp sirius-api:/tmp/cpu.prof ./cpu.prof
go tool pprof -http=:8080 ./cpu.prof
```
3. **Analyze Disk I/O**:
- Check I/O usage: `docker stats --format "{{.Name}}: {{.BlockIO}}"`
- For detailed analysis:
```bash
docker-compose exec sirius-api bash -c "dd if=/dev/zero of=/tmp/test bs=1M count=1024 oflag=direct"
```
4. **Network Performance**:
- Test network between containers:
```bash
docker-compose exec sirius-api bash -c "ping -c 5 sirius-ui"
```
- Check DNS resolution:
```bash
docker-compose exec sirius-api bash -c "nslookup sirius-ui"
```
5. **Database Query Performance**:
- Analyze slow queries with:
```bash
turso db shell http://127.0.0.1:9010 "EXPLAIN QUERY PLAN SELECT * FROM hosts JOIN host_vulnerabilities ON hosts.id = host_vulnerabilities.host_id;"
```
### metadata
priority: medium
tags: [performance, profiling]
.cursor/old/docker-tests.mdc
+66
View File
@@ -0,0 +1,66 @@
# Docker Testing Rules for Sirius
This document provides guidelines for running tests in the Sirius Docker environment.
## Container Environment
The Sirius application runs in several Docker containers:
- `sirius-engine`: Main scanner engine container (Go)
- `sirius-api`: API server container
- `sirius-ui`: Frontend UI container
- `sirius-valkey`: ValKey (Redis-compatible) container
- `sirius-postgres`: PostgreSQL database container
- `sirius-rabbitmq`: RabbitMQ message queue container
For NSE (Nmap Script Engine) testing, we primarily work with the `sirius-engine` container.
## Running Tests in Docker
To run test commands in the Docker environment, use the following pattern:
```bash
# Execute a command in the running container
docker exec -it sirius-engine go run cmd/<test-program>/main.go
# For NSE tests specifically
docker exec -it sirius-engine go run cmd/nse-scan-test/main.go
```
## Important Paths
Inside the Docker container:
- Working directory: `/app-scanner`
- NSE base directory: `/opt/sirius/nse`
- NSE repository: `/opt/sirius/nse/sirius-nse`
- Scripts directory: `/app-scanner/scripts`
## Common Testing Scenarios
### Testing NSE Integration
```bash
# Run the NSE scan test against the test target
docker exec -it sirius-engine go run cmd/nse-scan-test/main.go
# Build and run the test (if using built binaries)
docker exec -it sirius-engine /bin/bash -c "cd /app-scanner && go build -o bin/nse-scan-test cmd/nse-scan-test/main.go && ./bin/nse-scan-test"
```
### Debugging Tips
- Use the `docker logs sirius-engine` command to view container logs
- For interactive debugging, use `docker exec -it sirius-engine /bin/bash`
- NSE scripts can be inspected at `/opt/sirius/nse/sirius-nse/scripts`
- ValKey data can be inspected using the `redis-cli` within the ValKey container:
```bash
docker exec -it sirius-valkey redis-cli
```
## Best Practices
1. Always ensure the necessary directories exist before running tests
2. Use appropriate error handling to provide clear feedback
3. Test in the Docker environment before merging changes
4. Use emojis in log output for better visibility during testing
.cursor/old/general.mdc
+79
View File
@@ -0,0 +1,79 @@
---
description: Rules for placing and organizing Cursor rule files in the repository.
globs: *.mdc
---
---
description: Cursor Rules Location
globs: *.mdc
---
# Cursor Rules Location
Rules for placing and organizing Cursor rule files in the repository.
<rule>
name: cursor_rules_location
description: Standards for placing Cursor rule files in the correct directory
filters:
# Match any .mdc files
- type: file_extension
pattern: "\\.mdc$"
# Match files that look like Cursor rules
- type: content
pattern: "(?s)<rule>.*?</rule>"
# Match file creation events
- type: event
pattern: "file_create"
actions:
- type: reject
conditions:
- pattern: "^(?!\\.\\/\\.cursor\\/rules\\/.*\\.mdc$)"
message: "Cursor rule files (.mdc) must be placed in the .cursor/rules directory"
- type: suggest
message: |
When creating Cursor rules:
1. Always place rule files in PROJECT_ROOT/.cursor/rules/:
```
.cursor/rules/
├── your-rule-name.mdc
├── another-rule.mdc
└── ...
```
2. Follow the naming convention:
- Use kebab-case for filenames
- Always use .mdc extension
- Make names descriptive of the rule's purpose
3. Directory structure:
```
PROJECT_ROOT/
├── .cursor/
│ └── rules/
│ ├── your-rule-name.mdc
│ └── ...
└── ...
```
4. Never place rule files:
- In the project root
- In subdirectories outside .cursor/rules
- In any other location
examples:
- input: |
# Bad: Rule file in wrong location
rules/my-rule.mdc
my-rule.mdc
.rules/my-rule.mdc
# Good: Rule file in correct location
.cursor/rules/my-rule.mdc
output: "Correctly placed Cursor rule file"
metadata:
priority: high
version: 1.0
</rule>
.cursor/old/github-mcp.md
+230
View File
@@ -0,0 +1,230 @@
---
description: CRITICAL - GitHub comment posting requires explicit user approval before mcp_github_add_issue_comment execution
globs: **/*
alwaysApply: true
---
# GitHub MCP Usage Guidelines
## Repository Information
- **Repository**: https://github.com/SiriusScan/Sirius
- **Owner**: SiriusScan
- **Repository Name**: Sirius
## 🚨 CRITICAL RULE: COMMENT APPROVAL REQUIRED
### **NEVER POST COMMENTS WITHOUT EXPLICIT APPROVAL**
- **🛑 ABSOLUTE REQUIREMENT**: Every GitHub comment MUST be approved by the user before posting
- **❌ NEVER** use `mcp_github_add_issue_comment` without explicit user confirmation
- **✅ ALWAYS** draft, present, and wait for approval
### **Mandatory Comment Approval Workflow**
```
🔒 REQUIRED STEPS - NO EXCEPTIONS:
1. 📝 Draft the complete comment content
2. 🎯 Present to user with clear context:
"I want to post this comment on Issue #X: [content]"
3. ⏳ WAIT for explicit approval keywords:
- "approved" / "post it" / "go ahead" / "yes, post it"
4. ✅ Only THEN execute mcp_github_add_issue_comment
5. 🚫 If no approval received, DO NOT POST
```
### **Required Approval Format**
```
I want to post this comment on Issue #[NUMBER]:
---
[FULL COMMENT CONTENT HERE]
---
Should I post this comment? (I need explicit approval)
```
### **Approval Keywords**
- ✅ "approved"
- ✅ "post it"
- ✅ "go ahead"
- ✅ "yes, post it"
- ✅ "publish it"
- ❌ Anything else = DO NOT POST
## Comment Approval Workflow
- **🚨 CRITICAL REQUIREMENT: ALL GitHub comments must be approved before posting**
- Always draft comment content and present it to the user for review
- Never use `mcp_github_add_issue_comment` without explicit user approval
- Format proposed comments clearly with context about which issue/PR they target
- Wait for explicit "approved" or "post it" confirmation before executing
- **Comment Review Process**
```
1. Draft comment content with clear context
2. Show user: "I propose this comment for Issue #X:"
3. Present formatted comment content
4. Wait for approval: "approved", "post it", or similar
5. Only then execute mcp_github_add_issue_comment
```
## Issue Management Best Practices
- **Reading Issues**
- Use `mcp_github_get_issue` to fetch full issue details
- Use `mcp_github_get_issue_comments` to read existing conversation
- Always understand context before proposing responses
- **Issue Analysis**
- Identify root cause from issue description and attachments
- Check for existing solutions in comments
- Reference relevant code files when applicable
- Provide actionable solutions with specific steps
- **Comment Content Standards**
- Be professional and helpful
- Include specific technical details and file references
- Provide step-by-step solutions when possible
- Reference relevant documentation or code
- Use proper markdown formatting for code blocks
## Pull Request Workflow
- **PR Review Process**
- Use `mcp_github_get_pull_request` for PR details
- Use `mcp_github_get_pull_request_files` to see changes
- Use `mcp_github_get_pull_request_diff` for detailed review
- Always seek approval before creating reviews
- **Review Standards**
- Focus on code quality, security, and project standards
- Reference cursor rules when applicable
- Provide constructive feedback with specific suggestions
- Use appropriate review status (APPROVE, REQUEST_CHANGES, COMMENT)
## Repository Operations
- **Branch Management**
- Use descriptive branch names following project conventions
- Check existing branches with `mcp_github_list_branches`
- Create branches for specific issues/features only
- **File Operations**
- Always check existing file content before modifications
- Use appropriate commit messages referencing issues
- Ensure file changes align with project structure
## Notification Management
- **Notification Workflow**
- Use `mcp_github_list_notifications` to check for actionable items
- Prioritize notifications by type (mentions, review requests, assignments)
- Mark notifications as read/done after addressing them
- Use notification details to understand context
## Error Handling
- **Common Issues**
- Check repository permissions before operations
- Verify issue/PR numbers exist before referencing
- Handle rate limiting gracefully
- Provide clear error messages to user
- **Troubleshooting Steps**
1. Verify repository access and permissions
2. Check if referenced items (issues, PRs) exist
3. Ensure proper authentication
4. Retry with appropriate delays if rate limited
## Security Considerations
- **Sensitive Information**
- Never include API keys, passwords, or secrets in comments
- Avoid exposing internal system details unnecessarily
- Be cautious with error messages that might reveal system info
- **Access Control**
- Respect repository permissions and visibility
- Only perform operations the user is authorized for
- Verify user intent before executing destructive operations
## Project-Specific Guidelines
- **Sirius Project Context**
- Understand the project structure (sirius-ui, sirius-api, sirius-engine)
- Reference Docker compose issues and solutions appropriately
- Consider multi-service architecture in recommendations
- Reference existing documentation and setup guides
- **Issue Categories**
- Docker/containerization issues
- Service configuration problems
- Installation and setup difficulties
- Network and port configuration
- Volume mounting and permissions
## Examples
### Good Comment Approval Request
```
I want to post this comment on Issue #49:
---
Hi @declan727! I can see the issue you're experiencing. The problem is with the installation instructions in the README.
**Root Cause**: The README tells users to clone the website.git repository, but the docker-compose.yaml expects local directories.
**Solution**:
1. Clone the correct repository: `git clone https://github.com/SiriusScan/Sirius.git`
2. Navigate to the directory: `cd Sirius`
3. Run: `docker compose up -d`
The volume mounts to `../minor-projects/` directories are for development and need to be adjusted for end users.
---
Should I post this comment? (I need explicit approval)
```
### Good Commit Message Format
```
"Fix Docker compose volume mounts for end users
- Remove development-specific volume mounts
- Update README to reference correct repository
- Add user-friendly docker-compose.override.yaml
Fixes #49"
```
## Tools Reference
### Essential GitHub MCP Functions
- `mcp_github_get_issue` - Get issue details
- `mcp_github_add_issue_comment` - Add comment (🚨 REQUIRES APPROVAL)
- `mcp_github_get_issue_comments` - Read existing comments
- `mcp_github_list_notifications` - Check for actionable items
- `mcp_github_get_pull_request` - Get PR details
- `mcp_github_create_pull_request` - Create new PR
- `mcp_github_create_or_update_file` - Modify repository files
### Workflow Commands
- `mcp_github_list_issues` - Browse open issues
- `mcp_github_search_issues` - Find specific issues
- `mcp_github_get_file_contents` - Read repository files
- `mcp_github_list_branches` - Check available branches
.cursor/old/github-mcp.mdc
+171
View File
@@ -0,0 +1,171 @@
---
description: CRITICAL - GitHub comment posting requires explicit user approval before mcp_github_add_issue_comment execution
globs:
alwaysApply: false
---
# GitHub MCP Usage Guidelines
## Repository Information
- **Repository**: https://github.com/SiriusScan/Sirius
- **Owner**: SiriusScan
- **Repository Name**: Sirius
## Comment Approval Workflow
- **🚨 CRITICAL REQUIREMENT: ALL GitHub comments must be approved before posting**
- Always draft comment content and present it to the user for review
- Never use `mcp_github_add_issue_comment` without explicit user approval
- Format proposed comments clearly with context about which issue/PR they target
- Wait for explicit "approved" or "post it" confirmation before executing
- **Comment Review Process**
```
1. Draft comment content with clear context
2. Show user: "I propose this comment for Issue #X:"
3. Present formatted comment content
4. Wait for approval: "approved", "post it", or similar
5. Only then execute mcp_github_add_issue_comment
```
## Issue Management Best Practices
- **Reading Issues**
- Use `mcp_github_get_issue` to fetch full issue details
- Use `mcp_github_get_issue_comments` to read existing conversation
- Always understand context before proposing responses
- **Issue Analysis**
- Identify root cause from issue description and attachments
- Check for existing solutions in comments
- Reference relevant code files when applicable
- Provide actionable solutions with specific steps
- **Comment Content Standards**
- Be professional and helpful
- Include specific technical details and file references
- Provide step-by-step solutions when possible
- Reference relevant documentation or code
- Use proper markdown formatting for code blocks
## Pull Request Workflow
- **PR Review Process**
- Use `mcp_github_get_pull_request` for PR details
- Use `mcp_github_get_pull_request_files` to see changes
- Use `mcp_github_get_pull_request_diff` for detailed review
- Always seek approval before creating reviews
- **Review Standards**
- Focus on code quality, security, and project standards
- Reference cursor rules when applicable
- Provide constructive feedback with specific suggestions
- Use appropriate review status (APPROVE, REQUEST_CHANGES, COMMENT)
## Repository Operations
- **Branch Management**
- Use descriptive branch names following project conventions
- Check existing branches with `mcp_github_list_branches`
- Create branches for specific issues/features only
- **File Operations**
- Always check existing file content before modifications
- Use appropriate commit messages referencing issues
- Ensure file changes align with project structure
## Notification Management
- **Notification Workflow**
- Use `mcp_github_list_notifications` to check for actionable items
- Prioritize notifications by type (mentions, review requests, assignments)
- Mark notifications as read/done after addressing them
- Use notification details to understand context
## Error Handling
- **Common Issues**
- Check repository permissions before operations
- Verify issue/PR numbers exist before referencing
- Handle rate limiting gracefully
- Provide clear error messages to user
- **Troubleshooting Steps**
1. Verify repository access and permissions
2. Check if referenced items (issues, PRs) exist
3. Ensure proper authentication
4. Retry with appropriate delays if rate limited
## Security Considerations
- **Sensitive Information**
- Never include API keys, passwords, or secrets in comments
- Avoid exposing internal system details unnecessarily
- Be cautious with error messages that might reveal system info
- **Access Control**
- Respect repository permissions and visibility
- Only perform operations the user is authorized for
- Verify user intent before executing destructive operations
## Project-Specific Guidelines
- **Sirius Project Context**
- Understand the project structure (sirius-ui, sirius-api, sirius-engine)
- Reference Docker compose issues and solutions appropriately
- Consider multi-service architecture in recommendations
- Reference existing documentation and setup guides
- **Issue Categories**
- Docker/containerization issues
- Service configuration problems
- Installation and setup difficulties
- Network and port configuration
- Volume mounting and permissions
## Examples
### Good Comment Approval Request
```
I propose this comment for Issue #49:
"Hi @declan727! I can see the issue you're experiencing. The problem is with the installation instructions in the README.
**Root Cause**: The README tells users to clone the website.git repository, but the docker-compose.yaml expects local directories.
**Solution**:
1. Clone the correct repository: `git clone https://github.com/SiriusScan/Sirius.git`
2. Navigate to the directory: `cd Sirius`
3. Run: `docker compose up -d`
The volume mounts to `../minor-projects/` directories are for development and need to be adjusted for end users."
Should I post this comment?
```
### Good Commit Message Format
```
"Fix Docker compose volume mounts for end users
- Remove development-specific volume mounts
- Update README to reference correct repository
- Add user-friendly docker-compose.override.yaml
Fixes #49"
```
## Tools Reference
### Essential GitHub MCP Functions
- `mcp_github_get_issue` - Get issue details
- `mcp_github_add_issue_comment` - Add comment (REQUIRES APPROVAL)
- `mcp_github_get_issue_comments` - Read existing comments
- `mcp_github_list_notifications` - Check for actionable items
- `mcp_github_get_pull_request` - Get PR details
- `mcp_github_create_pull_request` - Create new PR
- `mcp_github_create_or_update_file` - Modify repository files
### Workflow Commands
- `mcp_github_list_issues` - Browse open issues
- `mcp_github_search_issues` - Find specific issues
- `mcp_github_get_file_contents` - Read repository files
- `mcp_github_list_branches` - Check available branches
.cursor/old/golang.mdc
+88
View File
@@ -0,0 +1,88 @@
---
description: Rules for Go backend development in Sirius Scan
globs: *.go
---
You are a Senior Go Developer and an Expert in backend systems, particularly vulnerability scanning architectures. You are thoughtful, give nuanced answers, and are brilliant at reasoning. You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning about Go code.
- Follow the user's requirements carefully & to the letter.
- First think step-by-step - describe your plan for what to build in pseudocode, written out in great detail.
- Confirm, then write code!
- Always write correct, best practice, DRY principle (Don't Repeat Yourself), bug free, fully functional and working code aligned with the rules below.
- Focus on readable, maintainable code that follows Go idioms.
- Fully implement all requested functionality.
- Leave NO todos, placeholders or missing pieces.
- Ensure code is complete! Verify thoroughly finalised.
- Be concise. Minimize any other prose.
- If you think there might not be a correct answer, you say so.
- If you do not know the answer, say so, instead of guessing.
### Scan Manager Architecture
The `manager.go` file implements a core component of Sirius Scan:
- **ScanManager**: Manages incoming scan requests and processes targets
- Listens for scan messages from a queue
- Validates scan configurations
- Processes targets based on their type (SingleIP, IPRange, CIDR, etc.)
- Coordinates different scan types (enumeration, discovery, vulnerability)
- Uses a worker pool for parallel processing of scan tasks
### Design Patterns Used
The codebase employs several design patterns:
- **Factory Pattern**: `ScanToolFactory` creates different scanning tools
- **Strategy Pattern**: Different scan strategies (enumeration, discovery, vulnerability)
- **Worker Pool Pattern**: Manages concurrent scan tasks efficiently
- **Observer Pattern**: Updates scan status as operations complete
### Go Coding Guidelines
Follow these rules when writing Go code:
- Use Go's standard error handling patterns with explicit error returns and checks.
- Prefer composition over inheritance.
- Follow standard Go project layout conventions.
- Use meaningful package names that reflect their purpose.
- Create small, focused interfaces (interface segregation).
- Make zero values useful when possible.
- Use context for cancellation and timeouts.
- Document all exported functions, types, and constants with godoc comments.
- Return early on errors rather than using nested if/else statements.
- Use named return values for clarity where appropriate.
- Use the `sync` package for thread-safe operations.
- Implement proper resource cleanup with `defer`.
- Prefer custom types for type safety (e.g., `TargetType` instead of raw strings).
### Scan Management Implementation
- **ScanMessage Processing**:
- Parse and validate the scan configuration
- Apply template defaults
- Process each target
- Update scan status appropriately
- **Target Processing**:
- Convert targets to IPs based on type (SingleIP, IPRange, CIDR, DNSName)
- Add each IP as a scan task to the worker pool
- Handle scan results and update database accordingly
- **Scan Execution**:
- Use appropriate scan strategy for each requested scan type
- Maintain proper error handling
- Update scan status as scans complete
- Record vulnerability findings
### Error Handling
- Always check errors and return them up the call stack with context.
- Use `fmt.Errorf()` to wrap errors with additional context.
- Log errors appropriately at the appropriate level.
- Consider using structured logging for better error investigation.
### Testing Guidelines
- Write unit tests for all public functions.
- Use table-driven tests where appropriate.
- Mock external dependencies for unit testing.
- Implement integration tests for core scanning functionality.
- Test error conditions and edge cases.
.cursor/old/mcp.md
+35
View File
@@ -0,0 +1,35 @@
---
description: MCP server configurations and tool references
globs: **/*
alwaysApply: true
---
# MCP Server Instructions
## GitHub MCP
**Repository**: https://github.com/SiriusScan/Sirius
**Owner**: SiriusScan
**Repository Name**: Sirius
⚠️ **IMPORTANT**: See [github-mcp.mdc](mdc:.cursor/rules/github-mcp.mdc) for comprehensive GitHub MCP usage guidelines including mandatory comment approval workflow.
## Browser Tools MCP
**Description**: Provides access to in-browser debugging features such as console logs.
**Available Functions**:
- `getConsoleLogs` - Retrieve console log entries
- `getConsoleErrors` - Get console error messages
- `getNetworkErrorLogs` - Fetch network error logs
- `getNetworkSuccessLogs` - Get successful network requests
- `takeScreenshot` - Capture browser screenshots
- `getSelectedElement` - Get currently selected DOM element
- `wipeLogs` - Clear all browser logs
## Usage Guidelines
- **GitHub Operations**: Always follow approval workflow in [github-mcp.mdc](mdc:.cursor/rules/github-mcp.mdc)
- **Browser Tools**: Use for debugging UI issues and network problems
- **Security**: Never expose sensitive information through MCP tools
.cursor/old/nextjs.mdc
+56
View File
@@ -0,0 +1,56 @@
---
description: Rules for TypeScript and React component development in Sirius UI
globs: *.tsx, *.ts
---
You are a Senior Front-End Developer and an Expert in ReactJS, NextJS, JavaScript, TypeScript, HTML, CSS and modern UI/UX frameworks (e.g., TailwindCSS, Shadcn, Radix). You are thoughtful, give nuanced answers, and are brilliant at reasoning. You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning.
- Follow the user's requirements carefully & to the letter.
- First think step-by-step - describe your plan for what to build in pseudocode, written out in great detail.
- Confirm, then write code!
- Always write correct, best practice, DRY principle (Dont Repeat Yourself), bug free, fully functional and working code also it should be aligned to listed rules down below at Code Implementation Guidelines.
- Focus on easy and readability code, over being performant.
- Fully implement all requested functionality.
- Leave NO todo's, placeholders or missing pieces.
- Ensure code is complete! Verify thoroughly finalised.
- Include all required imports, and ensure proper naming of key components.
- Be concise. Minimize any other prose.
- If you think there might not be a correct answer, you say so.
- If you do not know the answer, say so, instead of guessing.
### Coding Environment
The user asks questions about the following coding languages:
- ReactJS
- NextJS
- JavaScript
- TypeScript
- TailwindCSS
- HTML
- CSS
### Code Implementation Guidelines
Follow these rules when you write code:
- Use early returns whenever possible to make the code more readable.
- Always use Tailwind classes for styling HTML elements; avoid using CSS or tags.
- Use descriptive variable and function/const names. Also, event functions should be named with a "handle" prefix, like "handleClick" for onClick and "handleKeyDown" for onKeyDown.
- Implement accessibility features on elements. For example, a tag should have a tabindex="0", aria-label, on:click, and on:keydown, and similar attributes.
- Use consts instead of functions, for example, "const toggle = () =>". Also, define a type if possible.
### Sirius UI-Specific Guidelines
- Use the `cn()` utility from "src/components/lib/utils" to merge Tailwind classes.
- Follow Shadcn/UI component patterns for consistency in the codebase.
- Use React.forwardRef for reusable UI components that need to pass refs down.
- Always export named components (avoid default exports) with proper TypeScript interface definitions.
- Use React.FC<Props> type annotation for functional components with explicit prop interfaces.
- Organize imports with React and framework imports first, followed by project imports.
- Follow the established folder structure for components (lib/ui for shadcn components, feature-specific directories for domain components).
- Use the established color palette from the tailwind.config.ts/js when styling components.
- Avoid direct CSS styling - use Tailwind utility classes and existing design tokens.
- Implement responsive designs using Tailwind's responsive modifiers (sm:, md:, lg:, etc.).
- When using state management, prefer React hooks and context where appropriate.
### Accessibility Guidelines
- Ensure all interactive elements have appropriate ARIA attributes.
- Maintain color contrast ratios that meet WCAG standards.
- Implement keyboard navigation support for all interactive components.
- Use semantic HTML elements whenever possible (button for actions, anchors for links, etc.).
- Ensure form elements have associated labels and appropriate error handling.
.cursor/old/project-details.mdc
+8
View File
@@ -0,0 +1,8 @@
---
description: Understanding the project or coding style
globs:
---
We're working on an open-source vulnerability scanner: Sirius Scan
We want to leverage ideal programming paradigms like DRY where possible. Use, call out, and recommend programing patterns such as strategy patterns, factories, hooks, and more. Prefer language idiomatic design choices. We program in Typescript and Go.
.cursor/old/self_improve.mdc
+73
View File
@@ -0,0 +1,73 @@
---
description: Guidelines for continuously improving Cursor rules based on emerging code patterns and best practices.
globs: **/*
alwaysApply: true
---
- **Rule Improvement Triggers:**
- New code patterns not covered by existing rules
- Repeated similar implementations across files
- Common error patterns that could be prevented
- New libraries or tools being used consistently
- Emerging best practices in the codebase
- **Analysis Process:**
- Compare new code with existing rules
- Identify patterns that should be standardized
- Look for references to external documentation
- Check for consistent error handling patterns
- Monitor test patterns and coverage
- **Rule Updates:**
- **Add New Rules When:**
- A new technology/pattern is used in 3+ files
- Common bugs could be prevented by a rule
- Code reviews repeatedly mention the same feedback
- New security or performance patterns emerge
- **Modify Existing Rules When:**
- Better examples exist in the codebase
- Additional edge cases are discovered
- Related rules have been updated
- Implementation details have changed
- **Example Pattern Recognition:**
```typescript
// If you see repeated patterns like:
const data = await prisma.user.findMany({
select: { id: true, email: true },
where: { status: 'ACTIVE' }
});
// Consider adding to [prisma.mdc](mdc:.cursor/rules/prisma.mdc):
// - Standard select fields
// - Common where conditions
// - Performance optimization patterns
```
- **Rule Quality Checks:**
- Rules should be actionable and specific
- Examples should come from actual code
- References should be up to date
- Patterns should be consistently enforced
- **Continuous Improvement:**
- Monitor code review comments
- Track common development questions
- Update rules after major refactors
- Add links to relevant documentation
- Cross-reference related rules
- **Rule Deprecation:**
- Mark outdated patterns as deprecated
- Remove rules that no longer apply
- Update references to deprecated rules
- Document migration paths for old patterns
- **Documentation Updates:**
- Keep examples synchronized with code
- Update references to external docs
- Maintain links between related rules
- Document breaking changes
Follow [cursor_rules.mdc](mdc:.cursor/rules/cursor_rules.mdc) for proper rule formatting and structure.
.cursor/old/typescript-react.mdc
+131
View File
@@ -0,0 +1,131 @@
---
description: Standards for TypeScript and React component development in Sirius UI
globs: *.tsx, *.ts
---
# TypeScript and React Development Standards
Rules for creating and working with TypeScript and React files in the Sirius UI codebase.
<rule>
name: typescript_react_standards
description: Standards for developing TypeScript and React components in Sirius UI
filters:
# Match TypeScript and React TypeScript files
- type: file_extension
pattern: "\\.(ts|tsx)$"
# Match file creation events
- type: event
pattern: "file_create|file_modify"
actions:
- type: suggest
message: |
When creating TypeScript and React files:
1. Component Structure:
```tsx
import React, { useState, useCallback } from 'react';
import { cn } from '~/components/lib/utils';
interface ComponentProps {
// Props definition with explicit types
}
export const Component: React.FC<ComponentProps> = ({
// Destructured props
}) => {
// Component logic
return (
// JSX with Tailwind classes
);
};
```
2. Follow the naming conventions:
- Use PascalCase for component names
- Use camelCase for variables, functions, and instances
- Event handlers should be prefixed with "handle" (e.g., handleClick)
- Use descriptive names that clearly indicate purpose
3. Type definitions:
- Use explicit interfaces for component props
- Use type for complex type definitions
- Export shared types for reuse
- Avoid using 'any' type whenever possible
4. Component organization:
- Place components in appropriate directories:
- Shared components in src/components/ui/
- Feature-specific components in feature directories
- Pages in src/pages/
- Split complex components into smaller, focused components
5. React patterns:
- Use functional components with hooks
- Use React.FC<Props> type for components
- Memoize callbacks with useCallback
- Memoize expensive calculations with useMemo
- Use React.memo for pure components that render often
6. Styling guidelines:
- Use Tailwind CSS classes for styling
- Use the cn() utility for conditional class names
- Avoid inline styles and CSS files
- Use the established color tokens from tailwind.config.js
7. Accessibility requirements:
- Interactive elements must have appropriate ARIA attributes
- Ensure proper keyboard navigation (tabIndex, keyDown handlers)
- Use semantic HTML elements
- Provide proper form labels and error states
examples:
- input: |
# Bad: Component without proper typing
```tsx
const SomeComponent = (props) => {
return <div onClick={props.onClick}>{props.children}</div>;
};
export default SomeComponent;
```
# Good: Well-typed component with proper structure
```tsx
import React from 'react';
import { cn } from '~/components/lib/utils';
interface ButtonProps {
onClick: () => void;
children: React.ReactNode;
variant?: 'primary' | 'secondary';
}
export const Button: React.FC<ButtonProps> = ({
onClick,
children,
variant = 'primary',
}) => {
const handleClick = () => {
onClick();
};
return (
<button
className={cn(
"px-4 py-2 rounded",
variant === 'primary' ? "bg-primary text-white" : "bg-secondary text-gray-800"
)}
onClick={handleClick}
aria-label="Button"
>
{children}
</button>
);
};
```
output: "Properly structured TypeScript React component"
metadata:
priority: high
version: 1.0
</rule>
.cursor/old/web-development-debugging.mdc
+134
View File
@@ -0,0 +1,134 @@
---
description:
globs:
alwaysApply: false
---
# Web Development Debugging Standards
## **Console Log Verification**
- **Always check browser console logs before finishing any web development task**
- **Verify no JavaScript/TypeScript errors exist after making changes**
- **Check for React component errors, rendering issues, or runtime exceptions**
- **Monitor network errors and failed API calls**
## **Visual Changes Verification**
- **Always take screenshots when making UI/visual changes**
- **MANDATORY: Perform comprehensive screenshot analysis before completing any UI task**
- **Look for visual problems that would impact user experience**
### **Critical Screenshot Analysis Checklist**
After taking a screenshot, systematically analyze for these issues:
#### **1. Information Density & Readability**
- ❌ **Text cramping**: Lines too close together, hard to read
- ❌ **Information overload**: Too much data in small spaces
- ❌ **Poor contrast**: Text hard to distinguish from background
- ❌ **Font size issues**: Text too small or inconsistently sized
- ❌ **Line wrapping problems**: Text awkwardly broken across lines
#### **2. Layout & Spacing Issues**
- ❌ **Insufficient whitespace**: Elements too close together
- ❌ **Misalignment**: Related elements not properly aligned
- ❌ **Inconsistent margins/padding**: Spacing varies between similar elements
- ❌ **Cramped containers**: Content doesn't fit well in available space
- ❌ **Poor visual hierarchy**: Can't easily distinguish importance levels
#### **3. Data Presentation Problems**
- ❌ **Numbers and labels running together**: Hard to parse key-value pairs
- ❌ **No visual separation**: Different data types blend together
- ❌ **Poor grouping**: Related information not visually connected
- ❌ **Inconsistent formatting**: Similar data presented differently
- ❌ **Missing visual cues**: No indicators for status, importance, etc.
#### **4. Component-Specific Issues**
- ❌ **Cards**: Overcrowded, poor internal spacing, unclear sections
- ❌ **Lists**: Items too close, poor visual separation
- ❌ **Tables**: Cramped cells, poor column sizing, hard to scan
- ❌ **Forms**: Fields too close, labels unclear, poor grouping
- ❌ **Navigation**: Items crowded, unclear hierarchy
#### **5. Overall Visual Appeal**
- ❌ **Looks unprofessional**: Amateur spacing or layout
- ❌ **Hard to scan**: User can't quickly find information
- ❌ **Visually fatiguing**: Too dense or cluttered
- ❌ **Inconsistent styling**: Different components don't match
- ❌ **Poor use of space**: Wasted space or overcrowding
### **Required Actions When Issues Found**
- **STOP immediately** - Do not complete the task with visual problems
- **Document specific issues** - List exactly what looks wrong
- **Fix systematically** - Address layout, spacing, and readability issues
- **Re-screenshot and re-analyze** - Verify improvements
- **Iterate until visually appealing** - Don't settle for "good enough"
### **Visual Improvement Guidelines**
- **Add appropriate whitespace** - Let elements breathe
- **Use consistent spacing patterns** - Establish rhythm and hierarchy
- **Group related information** - Use visual cues like borders, backgrounds
- **Improve typography** - Proper font weights, sizes, and line heights
- **Create clear information hierarchy** - Most important info stands out
- **Ensure easy scanning** - Users should quickly find what they need
## **Pre-Completion Checklist**
- ✅ **Console Errors:** Check browser console for red error messages
- ✅ **Console Warnings:** Review yellow warning messages for potential issues
- ✅ **Network Tab:** Verify API calls are successful (200-299 status codes)
- ✅ **React DevTools:** Check for component errors or state issues
- ✅ **TypeScript Errors:** Ensure no TypeScript compilation errors
- ✅ **Linting Issues:** Address any ESLint or similar linting warnings
- ✅ **Screenshot Analysis:** Take screenshot and perform comprehensive visual analysis
- ✅ **Visual Quality:** Confirm UI is professionally designed and user-friendly
- ✅ **Information Clarity:** Verify all data is easy to read and understand
## **Error Detection Process**
```bash
# Use browser tools to check:
1. Console tab - Look for red errors and yellow warnings
2. Network tab - Check for failed requests (4xx, 5xx status codes)
3. React DevTools - Monitor component state and props
4. Sources tab - Check for runtime exceptions in source maps
5. Screenshot analysis - Systematically review visual quality
```
## **Common Error Patterns to Watch For**
- **Syntax Errors:** Missing brackets, semicolons, or malformed code
- **TypeScript Errors:** Type mismatches, missing imports, or interface violations
- **React Errors:** Component lifecycle issues, hook dependencies, or rendering problems
- **API Errors:** Failed network requests, CORS issues, or authentication problems
- **Import Errors:** Missing modules, incorrect paths, or circular dependencies
- **Visual Errors:** Poor spacing, cramped layouts, hard-to-read information
## **When Errors Are Found**
- **Stop immediately** - Do not continue without fixing errors
- **Identify root cause** - Read error messages carefully
- **Fix systematically** - Address one error at a time
- **Re-test thoroughly** - Verify fixes don't introduce new issues
- **Document fixes** - Explain what was broken and how it was resolved
## **Tools for Error Detection**
- **Browser DevTools Console** - Primary error checking tool
- **TypeScript Compiler** - Catch type-related issues early
- **ESLint/Prettier** - Code quality and formatting issues
- **React Error Boundaries** - Catch component rendering errors
- **Network Monitoring** - API and resource loading issues
- **Screenshot Analysis** - Visual quality and UX evaluation
## **Best Practices**
- Check console logs **immediately** after making changes
- Take screenshots **after every UI change** and analyze thoroughly
- Test in **multiple browsers** when possible
- Use **error boundaries** to catch React component errors gracefully
- Enable **strict mode** in development for early error detection
- Set up **automated testing** to catch regressions
- Use **source maps** for better debugging information
- **Never complete UI tasks** without proper visual analysis
## **Never Complete Tasks With:**
- ❌ Unresolved console errors (red messages)
- ❌ Failed network requests (unless intentional)
- ❌ TypeScript compilation errors
- ❌ React component crashes or infinite loops
- ❌ Broken functionality that was previously working
- ❌ **Poor visual design or cramped layouts**
- ❌ **Hard-to-read or poorly formatted information**
- ❌ **Unprofessional-looking UI elements**
.cursor/plans/sirius_v1_release_readiness_5ce2fe4d.plan.md
+331
View File
@@ -0,0 +1,331 @@
---
name: Sirius v1 Release Readiness
overview: A comprehensive production release readiness plan for Sirius v1.0, organized by criticality tiers. The project has strong architecture and UI but requires critical fixes in data safety, security, and deployment infrastructure before production.
todos:
- id: t1-db-safety
content: "TIER 1: Fix database drop-on-restart behavior in go-api/sirius/postgres/connection.go -- gate behind env var, default to safe"
status: pending
- id: t1-api-auth
content: "TIER 1: Implement authentication middleware for sirius-api and audit tRPC endpoint authorization"
status: pending
- id: t1-credentials
content: "TIER 1: Remove all hardcoded/fallback credentials from codebase, create .env.production.example, add startup validation"
status: pending
- id: t1-queue-durability
content: "TIER 1: Enable durable queues and manual ack for critical message types in go-api/sirius/queue/queue.go"
status: pending
- id: t2-cors-ratelimit
content: "TIER 2: Lock down CORS to specific origins and add rate limiting middleware to sirius-api"
status: pending
- id: t2-session-trpc
content: "TIER 2: Fix 100-year session maxAge, audit and protect sensitive tRPC endpoints"
status: pending
- id: t2-tls
content: "TIER 2: Add TLS termination via reverse proxy (Traefik or Nginx)"
status: pending
- id: t3-env-config
content: "TIER 3: Create production environment configuration template and startup validation"
status: pending
- id: t3-backup
content: "TIER 3: Implement database backup strategy and document restore procedures"
status: pending
- id: t3-deploy
content: "TIER 3: Complete deployment automation workflow and document production deployment steps"
status: pending
- id: t3-monitoring
content: "TIER 3: Add external health monitoring and alerting for downtime detection"
status: pending
- id: t4-dev-artifacts
content: "TIER 4: Remove queue-test page, example router, mock data, and fix test_valkey.go package conflict"
status: pending
- id: t4-e2e
content: "TIER 4: Wire integration tests into CI and create smoke-test QA checklist"
status: pending
- id: t4-ops-docs
content: "TIER 4: Write production deployment guide, runbook, and migration guide from v0.4.0"
status: pending
- id: t4-release
content: "TIER 4: Version bump to 1.0.0, update CHANGELOG, tag all repos, write release notes"
status: pending
isProject: false
---
# Sirius v1.0 Production Release Readiness Plan
## Current State: v0.4.0
Six containers, five engine applications, a Next.js UI, a Go REST API, and a shared SDK -- all orchestrated via Docker Compose. Architecture is solid, UI is 75% production-ready, backend is well-structured but has critical gaps.
```mermaid
flowchart TB
subgraph tier1 [TIER 1 -- Ship Blockers]
DB[Database Safety]
AUTH[API Authentication]
CREDS[Credentials and Secrets]
QUEUES[Queue Durability]
end
subgraph tier2 [TIER 2 -- Security Hardening]
CORS[CORS Lockdown]
RATE[Rate Limiting]
SESS[Session Management]
TRPC[tRPC Endpoint Audit]
TLS[TLS Termination]
end
subgraph tier3 [TIER 3 -- Production Infrastructure]
DEPLOY[Deployment Automation]
BACKUP[Backup Strategy]
MONITOR[Monitoring and Alerting]
ENV[Environment Config]
end
subgraph tier4 [TIER 4 -- Polish and QA]
DEVART[Remove Dev Artifacts]
E2E[End-to-End Testing]
DOCS[Operational Documentation]
CHANGELOG[Changelog and Migration Guide]
end
tier1 --> tier2 --> tier3 --> tier4
```
---
## TIER 1: Ship Blockers (Must fix -- data loss or security breach risk)
### 1.1 Database Wipes on Every Restart
**Severity: CRITICAL -- data destruction**
The SDK's database initialization unconditionally drops all tables on every startup:
`go-api/sirius/postgres/connection.go` line 179: `dropTablesInOrder()` is called inside `initializeSchema()`, which runs on every `GetDB()` call. This means every time sirius-api restarts, all PostgreSQL data is destroyed.
**Fix:**
- Gate `dropTablesInOrder()` behind an environment variable (e.g., `DB_RESET_SCHEMA=true`) that defaults to `false`
- Production compose must never set this flag
- Development compose can optionally set it
- Long-term: replace with a proper migration system (golang-migrate, goose, or Atlas)
### 1.2 No API Authentication or Authorization
**Severity: CRITICAL -- all endpoints publicly accessible**
`sirius-api/main.go` has no authentication middleware. Every handler in `sirius-api/handlers/` is reachable by anyone with network access. The scan, host, vulnerability, template, and event APIs are all wide open.
On the UI side, only 2 of 16 tRPC routers use `protectedProcedure` (terminal and agentScan). The other 14 use `publicProcedure`.
**Fix:**
- Add JWT or API-key authentication middleware to sirius-api (Fiber supports middleware chains)
- Audit all tRPC routers and move sensitive operations behind `protectedProcedure`
- Agent connections (gRPC) should require a shared secret or mTLS
### 1.3 Hardcoded Default Credentials
**Severity: CRITICAL -- known credentials in source code**
- **PostgreSQL**: Falls back to `postgres/postgres` if env vars unset (`go-api/sirius/postgres/connection.go`)
- **RabbitMQ**: Hardcoded `guest:guest` in queue SDK (`go-api/sirius/queue/queue.go`) and in app-terminal/app-administrator
- **NextAuth**: Default secret is `"change-this-secret-in-production-please"` in `sirius-ui/src/env.mjs`
- **Docker Compose**: Production compose uses `${POSTGRES_PASSWORD:-postgres}` defaults
**Fix:**
- Remove all fallback credentials from code -- fail loudly if env vars are missing
- Create a `.env.production.example` template with required variables documented
- Add startup validation that refuses to run with known-insecure defaults
- Document required secrets in a production deployment guide
### 1.4 Non-Durable Message Queues
**Severity: HIGH -- message loss on RabbitMQ restart**
All queue declarations in `go-api/sirius/queue/queue.go` use `durable: false` and `auto-ack: true`. This means:
- Messages are lost if RabbitMQ restarts
- Scan commands, terminal commands, and admin commands can silently vanish
- Failed message processing is never retried
**Fix:**
- Set `durable: true` for all production queues
- Implement manual acknowledgment for critical message types (scan commands)
- Gate durability behind `GO_ENV` or a dedicated flag so dev stays lightweight
- Consider adding a dead-letter queue for failed messages
---
## TIER 2: Security Hardening (Must fix -- vulnerability surface)
### 2.1 CORS Allows All Origins
`sirius-api/main.go` line 127: `allowedOrigins = "*"` when `CORS_ALLOWED_ORIGINS` is unset. Production must restrict this to the actual UI domain.
**Fix:** Set `CORS_ALLOWED_ORIGINS` in production compose to the UI's origin. Fail if unset in production mode.
### 2.2 No Rate Limiting
No rate limiting middleware exists in sirius-api. A single client can flood every endpoint.
**Fix:** Add Fiber rate limiter middleware (`fiber/limiter`). Start with a global limit (e.g., 100 req/min per IP), with higher limits on polling endpoints like health and statistics.
### 2.3 Session MaxAge is 100 Years
NextAuth session configuration uses an effectively infinite maxAge. Sessions never expire.
**Fix:** Reduce to a reasonable value (e.g., 24 hours for JWT, 7 days with refresh). Add session revocation capability.
### 2.4 tRPC Endpoint Authorization Audit
14 of 16 tRPC routers use `publicProcedure`. Sensitive operations like `store` (raw Valkey access), `queue` (raw RabbitMQ access), `scanner` (start scans), and `host` (modify hosts) should all require authentication.
**Fix:** Audit each router and classify endpoints as public (read-only, non-sensitive) or protected. Move write operations and admin functions behind `protectedProcedure`.
### 2.5 TLS Termination
No HTTPS configuration exists. All traffic is plaintext.
**Fix:** Add a reverse proxy (Traefik or Nginx) in front of the stack for TLS termination. Add a compose service or document external proxy setup. Consider Let's Encrypt for automated certificate management.
---
## TIER 3: Production Infrastructure (Should fix -- operational maturity)
### 3.1 Deployment Automation
The `deploy.yml` GitHub Actions workflow is a placeholder. There is no actual production deployment mechanism.
**Fix:**
- Complete the deploy workflow with actual SSH/Docker Compose deployment
- Implement environment-specific compose overrides (`docker-compose.prod.yaml`)
- Add rollback capability (tag-based image pinning)
- Decide on deployment strategy: manual trigger for v1 is fine, but document the exact steps
### 3.2 Database Backup Strategy
No backup mechanism exists. Combined with the schema-drop issue, this is high-risk.
**Fix:**
- Add a `pg_dump` cron job (can be a sidecar container or host script)
- Document backup/restore procedures
- Test restore from backup before launch
- Consider Valkey persistence configuration (RDB/AOF) for cache durability
### 3.3 Monitoring and Alerting
The system-monitor app collects metrics to Valkey, and the UI displays them, but there is no external alerting. If the system goes down, nobody is notified.
**Fix:**
- Add a `/health` endpoint to sirius-api (may already exist but should be verified and formalized)
- Consider Uptime Kuma, Healthchecks.io, or a simple webhook-based alerting for downtime
- Document on-call/monitoring procedures in a runbook
### 3.4 Environment Configuration Management
No `.env.production` template exists. Production secrets are handled ad-hoc.
**Fix:**
- Create `.env.production.example` listing every required variable with descriptions
- Document which variables are required vs optional
- Add a startup validation script that checks for required config before launching services
- Consider Docker secrets or an external secrets manager for sensitive values
---
## TIER 4: Polish and QA (Should do -- professional release quality)
### 4.1 Remove Development Artifacts
- `/queue-test` page in the UI should be removed or gated
- `example` tRPC router should be removed
- Mock scan data in `scanner.ts` router should be replaced or removed
- `test_valkey.go` in app-system-monitor conflicts with the main package (should be a build-tagged utility or moved to a `cmd/` subdirectory)
### 4.2 End-to-End Testing
Integration test scripts exist in `testing/container-testing/` but are not integrated into CI. No browser-based E2E tests exist.
**Fix:**
- Wire `test-health.sh` and `test-integration.sh` into the CI pipeline as a required check
- Add at least one smoke-test flow: login, start a scan, view results
- Document manual QA checklist for release verification
### 4.3 Operational Documentation
Missing documents for production operations:
- **Production Deployment Guide**: Step-by-step instructions for first-time and upgrade deployments
- **Runbook**: Common operational procedures (restart services, check logs, clear queues, restore backups)
- **Incident Response**: What to do when things break (escalation, rollback, data recovery)
- **Migration Guide**: Upgrading from v0.4.0 to v1.0 (breaking changes, data migration)
### 4.4 Changelog and Version Bump
- Update `CHANGELOG.md` with all v1.0 changes (significant given everything since v0.4.0)
- Bump version to `1.0.0` in `package.json`, compose files, and any version constants
- Tag the release in all repos (main + submodules)
- Write release notes for GitHub Releases
---
## Scope Decisions for the Product Group
These items are real but may be deferred past v1.0. The product group should explicitly decide on each:
- **API Documentation (OpenAPI/Swagger)**: Valuable for integrators but not blocking v1 launch
- **Horizontal Scaling**: Single-node Docker Compose is fine for v1; clustering can come later
- **Distributed Tracing**: Nice for debugging but not required at launch
- **CI Security Scanning (Trivy/Snyk)**: Recommended but can be added post-launch
- **Blue-Green / Canary Deployments**: Overkill for an initial release; simple rolling updates suffice
- **Multi-region Deployment**: Not needed for v1
- **Agent Authentication (mTLS)**: Important if agents run on untrusted networks; can ship with shared-secret auth first
---
## Recommended Execution Order
```mermaid
gantt
title Sirius v1.0 Release Track
dateFormat YYYY-MM-DD
axisFormat %b %d
section ShipBlockers
DB_Safety_Fix :crit, db, 2026-02-10, 2d
Credentials_Cleanup :crit, creds, 2026-02-10, 3d
API_Auth_Middleware :crit, auth, 2026-02-12, 5d
Queue_Durability :crit, queue, 2026-02-12, 2d
section Security
CORS_and_RateLimit :sec1, after queue, 2d
Session_and_tRPC_Audit :sec2, after auth, 3d
TLS_Termination :sec3, after sec1, 3d
section Infrastructure
Env_Config_Template :inf1, after creds, 2d
Backup_Strategy :inf2, after db, 3d
Deploy_Automation :inf3, after sec3, 3d
Monitoring :inf4, after inf3, 2d
section Polish
Remove_Dev_Artifacts :pol1, after sec2, 1d
E2E_Testing :pol2, after inf3, 3d
Operational_Docs :pol3, after inf4, 3d
Version_Bump_Release :milestone, pol4, after pol3, 1d
```
**Estimated timeline**: 4-5 weeks with a focused team, starting from the ship blockers in parallel and flowing into security, infra, and polish sequentially.
---
## Summary Table
- **Tier 1 (Ship Blockers)**: 4 items -- database safety, API auth, credentials, queue durability
- **Tier 2 (Security)**: 5 items -- CORS, rate limiting, sessions, tRPC audit, TLS
- **Tier 3 (Infrastructure)**: 4 items -- deployment, backups, monitoring, env config
- **Tier 4 (Polish)**: 4 items -- dev artifact cleanup, E2E testing, ops docs, release prep
- **Deferred Decisions**: 7 items for the product group to explicitly scope in or out
.cursor/rules/cursor_rules.mdc
+359
View File
@@ -0,0 +1,359 @@
---
description: Master Cursor rules for Sirius project - orchestrates dynamic documentation discovery and context shaping
globs: **/*
alwaysApply: true
---
# Sirius Cursor Rules - Dynamic Documentation Integration
## Core Philosophy
This project uses a **dynamic documentation discovery system** that automatically includes relevant documentation based on context. The system leverages our comprehensive documentation index and LLM-optimized metadata to provide the most relevant context for any development task.
## Dynamic Documentation Discovery
### Primary Documentation Sources
**Always include these high-priority documents:**
- [ABOUT.documentation.md](mdc:documentation/dev/ABOUT.documentation.md) - Documentation standards and system
- [README.documentation-index.md](mdc:documentation/README.documentation-index.md) - Complete documentation index
### Context-Aware Document Selection
**For Git/Version Control Operations:**
- [README.development.md](mdc:documentation/dev/README.development.md) - Development workflow and standards
- [README.container-testing.md](mdc:documentation/dev/test/README.container-testing.md) - Testing before commits
**For Testing Activities:**
- [README.documentation-testing.md](mdc:documentation/dev/test/README.documentation-testing.md) - Documentation testing system
- [README.container-testing.md](mdc:documentation/dev/test/README.container-testing.md) - Container testing system
**For Documentation Work:**
- [ABOUT.documentation.md](mdc:documentation/dev/ABOUT.documentation.md) - Documentation standards
- [README.documentation-testing.md](mdc:documentation/dev/test/README.documentation-testing.md) - Documentation validation
**For Architecture/System Design:**
- [README.architecture.md](mdc:documentation/dev/architecture/README.architecture.md) - System architecture
- [ABOUT.documentation.md](mdc:documentation/dev/ABOUT.documentation.md) - Documentation standards
**For Task Management/Project Work:**
- [README.tasks.md](mdc:documentation/dev/operations/README.tasks.md) - Task management system
- [README.new-project.md](mdc:documentation/dev/operations/README.new-project.md) - Project workflow and structure
**For Agent Identity Work:**
- [ABOUT.agent-identities.md](mdc:.cursor/agents/docs/ABOUT.agent-identities.md) - Agent identity system
- [TEMPLATE.agent-identity.md](mdc:.cursor/agents/docs/TEMPLATE.agent-identity.md) - Universal agent template
- [SPECIFICATION.agent-identity.md](mdc:.cursor/agents/docs/SPECIFICATION.agent-identity.md) - Technical specification
- [INDEX.agent-identities.md](mdc:.cursor/agents/docs/INDEX.agent-identities.md) - Agent registry
## Documentation System Integration
### YAML Front Matter Usage
Our documentation uses rich YAML front matter for intelligent context building:
```yaml
---
title: "Document Title"
description: "Brief purpose description"
template: "TEMPLATE.documentation-standard"
llm_context: "high" # high, medium, low
categories: ["development", "testing"]
tags: ["docker", "testing", "containers"]
related_docs:
- "README.development.md"
- "ABOUT.documentation.md"
---
```
### LLM Context Levels
- **high**: Critical for understanding project structure and standards
- **medium**: Important for specific development tasks
- **low**: Reference material and detailed specifications
### Dynamic Context Building
When working on any task, Cursor should:
1. **Check the documentation index** for relevant documents
2. **Prioritize by llm_context level** (high → medium → low)
3. **Include related documents** based on YAML relationships
4. **Use search_keywords** to find contextually relevant information
## Development Guidelines
### Project Structure
- **Backend Development**: Happens inside `sirius-engine` container
- **Frontend Development**: Uses Next.js in `sirius-ui` container
- **Testing**: Run from `testing/` directory using Makefile commands
- **Documentation**: All in `documentation/dev/` with machine-readable metadata
### Container Development
```bash
# Backend development commands run in container
docker exec sirius-engine <command>
# Example: Check logs
docker exec sirius-engine cat /var/logs
# Example: Restart services
docker exec sirius-engine systemctl restart <service>
```
### Testing Workflow
```bash
# Navigate to testing directory
cd testing
# Run complete test suite
make test-all
# Run specific tests
make test-build
make test-health
make test-integration
# Run documentation validation
make lint-docs
make lint-index
```
### Documentation Standards
- **All documentation** must have complete YAML front matter
- **Use templates** from `documentation/dev/templates/`
- **Follow naming conventions** (ABOUT._, README._, TEMPLATE.\*)
- **Include LLM context** for AI optimization
- **Maintain relationships** through related_docs
## AI Context Optimization
### Context Shaping Strategy
1. **Start with high-context documents** (llm_context: "high")
2. **Include related documents** based on YAML relationships
3. **Use search keywords** for specific task context
4. **Leverage categories** for domain-specific information
### Documentation Discovery Commands
```bash
# Find high-priority documentation
grep -r "llm_context: high" documentation/
# Find documents by category
grep -r "categories:" documentation/ | grep "testing"
# Find related documents
grep -r "related_docs:" documentation/
# Check template usage
grep -r "template:" documentation/
```
## Best Practices
### Code Development
- **Follow project structure** defined in documentation
- **Use container-based development** for backend work
- **Run tests before commits** using our testing system
- **Update documentation** when making structural changes
### Documentation Maintenance
- **Keep YAML front matter complete** and accurate
- **Update related_docs** when creating new relationships
- **Use appropriate templates** for different document types
- **Run documentation linting** before committing changes
### Context Building
- **Always include relevant documentation** based on task context
- **Prioritize by LLM context levels** for optimal AI performance
- **Use our documentation index** to discover related information
- **Leverage search keywords** for specific task guidance
## Cursor Rule Evolution
### Proactive Rule Recommendations
**The AI should actively monitor development activities and recommend new cursor rules when it identifies patterns that could improve efficiency.**
#### When to Recommend New Rules
- **Repeated patterns** - When the same type of task is performed multiple times
- **Complex workflows** - When a task involves multiple steps that could be streamlined
- **Context gaps** - When relevant documentation exists but isn't being automatically included
- **Domain-specific activities** - When working in specific areas (e.g., deployment, monitoring, security)
#### Rule Recommendation Process
1. **Identify the pattern** - What activity is being repeated or could be optimized?
2. **Assess the impact** - Would a cursor rule significantly improve efficiency?
3. **Define the scope** - What files, directories, or activities should the rule cover?
4. **Specify the context** - What documentation should be automatically included?
5. **Propose the rule** - Suggest the rule content and file naming
#### Example Rule Recommendations
**If working frequently with Docker deployments:**
- **Pattern**: Repeated Docker Compose operations and container management
- **Recommendation**: Create `deployment-workflow.mdc` rule
- **Context**: Include deployment documentation, Docker best practices, monitoring guides
**If working on security features:**
- **Pattern**: Security-related code changes and vulnerability scanning
- **Recommendation**: Create `security-development.mdc` rule
- **Context**: Include security documentation, vulnerability scanning guides, best practices
#### Rule Creation Guidelines
When recommending new cursor rules:
1. **Follow the existing pattern** - Use `cursor_rules.mdc` as a template
2. **Include specific documentation** - Reference exact files that should be included
3. **Define clear scope** - Specify which file patterns the rule should apply to
4. **Provide usage examples** - Show how the rule would be used in practice
5. **Consider maintenance** - Ensure the rule will remain useful over time
#### Current Rule Inventory
**Existing specialized rules:**
- `git-operations.mdc` - Git workflows and version control
- `testing-workflow.mdc` - Testing processes and validation
- `documentation-work.mdc` - Documentation creation and maintenance
**Potential future rules to consider:**
- `deployment-workflow.mdc` - Production deployment processes
- `security-development.mdc` - Security-focused development
- `monitoring-ops.mdc` - Monitoring and observability
- `api-development.mdc` - API development and integration
### Rule Maintenance
- **Review rules quarterly** - Ensure they remain relevant and useful
- **Update documentation references** - Keep file paths and content current
- **Consolidate similar rules** - Merge rules that have overlapping scope
- **Remove obsolete rules** - Delete rules that are no longer needed
## Agent Identity System
### Purpose
The Agent Identity System provides structured, role-specific context for AI interactions across the Sirius project. Each agent identity is a carefully crafted document that enables confident fresh conversations by providing essential role context.
### Available Agent Slash Commands
Use these slash commands to invoke agent identities:
- `/bot-agent-engineer` - Agent system development (Go/gRPC)
- `/bot-api-engineer` - REST API development (Go/Fiber)
- `/bot-ui-engineer` - Frontend development (Next.js/React)
- `/bot-identity-recruiter` - Creates new agent identities (meta-bot)
### When to Use Agent Identities
- **Starting new conversations** - Fresh, validated context for any role
- **Role-specific work** - Focused expertise for specific domains
- **Context shaping** - Consistent, validated role definitions
- **Cross-role coordination** - Understanding responsibilities and interfaces
### Key Agent Identity Documents
- **[ABOUT.agent-identities.md](mdc:.cursor/agents/docs/ABOUT.agent-identities.md)** - System philosophy and standards
- **[TEMPLATE.agent-identity.md](mdc:.cursor/agents/docs/TEMPLATE.agent-identity.md)** - Universal agent template
- **[SPECIFICATION.agent-identity.md](mdc:.cursor/agents/docs/SPECIFICATION.agent-identity.md)** - Technical requirements
- **[INDEX.agent-identities.md](mdc:.cursor/agents/docs/INDEX.agent-identities.md)** - Complete agent registry
- **[GUIDE.creating-agent-identities.md](mdc:.cursor/agents/docs/GUIDE.creating-agent-identities.md)** - Creation guide
- **[REFERENCE.integration-levels.md](mdc:.cursor/agents/docs/REFERENCE.integration-levels.md)** - Integration patterns
### Agent Identity Validation
Agent identities must pass automated validation:
```bash
# Full agent validation
cd testing/container-testing
make lint-agents
# Quick validation
make lint-agents-quick
# Index validation
make lint-agent-index
# Complete validation including agents
make validate-all
```
### Creating New Agent Identities
1. **Review existing agents** in [INDEX.agent-identities.md](mdc:.cursor/agents/docs/INDEX.agent-identities.md)
2. **Copy template** from [TEMPLATE.agent-identity.md](mdc:.cursor/agents/docs/TEMPLATE.agent-identity.md)
3. **Follow specification** in [SPECIFICATION.agent-identity.md](mdc:.cursor/agents/docs/SPECIFICATION.agent-identity.md)
4. **Determine integration level** using [REFERENCE.integration-levels.md](mdc:.cursor/agents/docs/REFERENCE.integration-levels.md)
5. **Validate before committing** with `make lint-agents`
6. **Update index** in [INDEX.agent-identities.md](mdc:.cursor/agents/docs/INDEX.agent-identities.md)
### Integration with Development Workflow
Agent identities are validated automatically in pre-commit hooks:
- Modified agent files trigger quick validation
- Index consistency checked automatically
- Full validation included in CI/CD pipeline
- Pre-commit prevents invalid agent commits
### Agent Identity Best Practices
- ✅ Keep within 200-400 line target
- ✅ Include concrete examples for engineering roles
- ✅ Link to comprehensive documentation
- ✅ Use appropriate integration level
- ✅ Validate before committing
- ❌ Don't create agents for temporary needs
- ❌ Don't duplicate existing agent functionality
- ❌ Don't include implementation details (link to docs instead)
- ❌ Don't exceed 500 lines (maximum limit)
## Troubleshooting
### Common Issues
- **Missing context**: Check documentation index and LLM context levels
- **Outdated information**: Run documentation linting to validate accuracy
- **Broken relationships**: Use `make lint-index` to check document relationships
- **Template compliance**: Use `make lint-docs` to validate structure
### Debugging Commands
```bash
# Check documentation completeness
cd testing && make lint-docs
# Validate document relationships
cd testing && make lint-index
# Find specific documentation
grep -r "search_keywords:" documentation/ | grep "docker"
```
---
_This cursor rule dynamically integrates with our documentation system. For questions about documentation structure, see [ABOUT.documentation.md](mdc:documentation/dev/ABOUT.documentation.md)._
.cursor/rules/documentation-work.mdc
+223
View File
@@ -0,0 +1,223 @@
---
description: Cursor rules for documentation creation, maintenance, and validation
globs: documentation/**/*.md, .cursor/rules/*.mdc
alwaysApply: false
---
# Documentation Work and Maintenance
## Documentation Context
When working on documentation, include these essential sources:
### Required Documentation
- [ABOUT.documentation.md](mdc:documentation/dev/ABOUT.documentation.md) - Documentation standards and system
- [README.documentation-testing.md](mdc:documentation/dev/test/README.documentation-testing.md) - Documentation validation system
- [README.documentation-index.md](mdc:documentation/README.documentation-index.md) - Complete documentation index
### Template System
- [TEMPLATE.documentation-standard.md](mdc:documentation/dev/templates/TEMPLATE.documentation-standard.md) - Standard documentation template
- [TEMPLATE.guide.md](mdc:documentation/dev/templates/TEMPLATE.guide.md) - Step-by-step guide template
- [TEMPLATE.troubleshooting.md](mdc:documentation/dev/templates/TEMPLATE.troubleshooting.md) - Troubleshooting template
- [TEMPLATE.custom.md](mdc:documentation/dev/templates/TEMPLATE.custom.md) - Custom document template
## Documentation Standards
### File Naming Conventions
| Prefix | Purpose | Example |
| ------------------ | --------------------------------- | ------------------------------------ |
| `ABOUT.` | Meta-documents explaining systems | `ABOUT.documentation.md` |
| `README.` | Main documentation files | `README.container-testing.md` |
| `TEMPLATE.` | Template files for consistency | `TEMPLATE.documentation-standard.md` |
| `GUIDE.` | Step-by-step guides | `GUIDE.docker-setup.md` |
| `TROUBLESHOOTING.` | Problem-solving docs | `TROUBLESHOOTING.build-issues.md` |
### YAML Front Matter Requirements
Every documentation file must include complete YAML front matter:
```yaml
---
title: "Document Title"
description: "Brief purpose description"
template: "TEMPLATE.documentation-standard"
version: "1.0.0"
last_updated: "2025-01-03"
author: "Author Name"
tags: ["tag1", "tag2", "tag3"]
categories: ["category1", "category2"]
difficulty: "intermediate" # beginner, intermediate, advanced
prerequisites: ["prereq1", "prereq2"]
related_docs:
- "related-doc1.md"
- "related-doc2.md"
dependencies:
- "required-file1"
- "required-directory/"
llm_context: "high" # high, medium, low
search_keywords: ["keyword1", "keyword2", "keyword3"]
---
```
### Template Compliance
- **Use appropriate templates** for different document types
- **Include all required sections** from the template
- **Follow template structure** for consistency
- **Custom documents** can use `TEMPLATE.custom` for flexibility
## Documentation Workflow
### Before Creating Documentation
1. **Check existing documentation**: Review `documentation/README.documentation-index.md`
2. **Choose appropriate template**: Select from `documentation/dev/templates/`
3. **Plan document relationships**: Identify related documents for `related_docs`
### During Documentation Creation
1. **Start with YAML front matter**: Complete all required fields
2. **Follow template structure**: Use the selected template as a guide
3. **Include comprehensive content**: Purpose, When, How, What, Troubleshooting
4. **Add LLM context section**: For AI optimization
5. **Use proper formatting**: Markdown best practices
### After Creating Documentation
1. **Run documentation validation**: `cd testing && make lint-docs`
2. **Check index completeness**: `cd testing && make lint-index`
3. **Update documentation index**: Add new file to `README.documentation-index.md`
4. **Test template compliance**: Verify all required sections are present
## Documentation Validation
### Quick Validation
```bash
cd testing
make lint-docs-quick
```
### Full Validation
```bash
cd testing
make lint-docs
```
### Index Validation
```bash
cd testing
make lint-index
```
### Validation Checks
- **YAML front matter completeness**: All required fields present
- **Template compliance**: Document follows selected template
- **Index completeness**: All files referenced in documentation index
- **Link validation**: Internal links work correctly
- **Metadata validity**: Field values match valid options
## Documentation Categories
### Development Documentation
- **Purpose**: Development setup, workflows, standards
- **Location**: `documentation/dev/`
- **Templates**: `TEMPLATE.documentation-standard`, `TEMPLATE.guide`
- **Examples**: `README.development.md`, `README.container-testing.md`
### Architecture Documentation
- **Purpose**: System design, component relationships
- **Location**: `documentation/dev/architecture/`
- **Templates**: `TEMPLATE.architecture`, `TEMPLATE.documentation-standard`
- **Examples**: `README.architecture.md`
### Template Documentation
- **Purpose**: Document templates and standards
- **Location**: `documentation/dev/templates/`
- **Templates**: `TEMPLATE.template`
- **Examples**: `TEMPLATE.documentation-standard.md`
### Testing Documentation
- **Purpose**: Testing systems and validation processes
- **Location**: `documentation/dev/test/`
- **Templates**: `TEMPLATE.documentation-standard`
- **Examples**: `README.container-testing.md`, `README.documentation-testing.md`
## LLM Optimization
### Context Levels
- **high**: Critical for understanding project structure
- **medium**: Important for specific development tasks
- **low**: Reference material and detailed specifications
### Search Keywords
Include relevant keywords for AI discovery:
- **Technical terms**: docker, testing, containers, ci-cd
- **Process terms**: development, workflow, validation
- **System terms**: architecture, microservices, vulnerability
### Related Documents
Maintain clear relationships:
- **Use `related_docs`** to link related documentation
- **Update relationships** when creating new docs
- **Check index completeness** to ensure all files are discoverable
## Troubleshooting Documentation Issues
### Common Problems
| Issue | Symptoms | Solution |
| -------------------- | --------------------------------- | ---------------------------------------- |
| Missing front matter | "No YAML metadata" errors | Add complete YAML front matter |
| Template compliance | "Missing section" warnings | Compare with template structure |
| Index completeness | "Missing from index" errors | Add file to documentation index |
| Invalid metadata | "Invalid difficulty value" errors | Check field values against valid options |
### Debugging Commands
```bash
# Check documentation status
cd testing && make lint-docs
# Find specific documentation
grep -r "llm_context: high" documentation/
# Check template usage
grep -r "template:" documentation/
# Validate relationships
grep -r "related_docs:" documentation/
```
## Integration with Development
### Pre-Commit Validation
- **Run documentation linting** before committing docs
- **Check index completeness** for new files
- **Validate template compliance** for consistency
### CI/CD Integration
- **Include documentation validation** in automated checks
- **Use Makefile targets** for consistent execution
- **Leverage pre-commit hooks** for immediate feedback
---
_This rule integrates with our documentation system. For complete documentation guidelines, see [ABOUT.documentation.md](mdc:documentation/dev/ABOUT.documentation.md)._
.cursor/rules/git-operations.mdc
+121
View File
@@ -0,0 +1,121 @@
---
description: Cursor rules for Git operations and version control workflows
globs: .git/**/*, *.md, testing/**/*
alwaysApply: false
---
# Git Operations and Version Control
## Pre-Commit Context
Before any Git operation, ensure you have the right documentation context:
### Required Documentation
- [README.development.md](mdc:documentation/dev/README.development.md) - Development workflow standards
- [README.container-testing.md](mdc:documentation/dev/test/README.container-testing.md) - Testing requirements
- [README.documentation-testing.md](mdc:documentation/dev/test/README.documentation-testing.md) - Documentation validation
### Pre-Commit Checklist
The pre-commit hook automatically runs these checks:
1. **Documentation linting** - Quick validation of documentation files
2. **Index completeness** - Ensures all docs are properly indexed
3. **Build validation** - Smart build testing based on branch:
- **Feature branches**: Config validation only (~15 seconds)
- **Main branch**: Full Docker builds (ensures production readiness)
- **Docker file changes**: Always runs full builds
### Pre-Commit Optimization
The pre-commit hook is optimized for development speed:
- **Feature branches** skip full Docker builds (95%+ faster commits)
- **Full builds** still run on main branch and Docker file changes
- **Manual full builds** available via `./scripts/test-full-build.sh`
## Commit Message Standards
### Format
```
<type>(<scope>): <description>
[optional body]
[optional footer]
```
### Types
- **feat**: New feature
- **fix**: Bug fix
- **docs**: Documentation changes
- **test**: Testing changes
- **refactor**: Code refactoring
- **chore**: Maintenance tasks
### Examples
```
feat(testing): add documentation testing system
fix(docker): resolve container build issues
docs(architecture): update system design documentation
```
## Branch Naming
### Format
```
<type>/<description>
```
### Examples
```
feature/documentation-testing
fix/container-build-issues
docs/architecture-updates
```
## Development Workflow
### Before Starting Work
1. **Check current branch**: `git branch`
2. **Pull latest changes**: `git pull origin main`
3. **Create feature branch**: `git checkout -b feature/description`
### During Development
1. **Make atomic commits** with clear messages
2. **Run tests frequently**: `cd testing && make test-all`
3. **Update documentation** when making structural changes
4. **Validate changes**: `cd testing && make lint-docs`
### Before Pushing
1. **Run complete validation**: `cd testing && make validate-all`
2. **Check commit history**: `git log --oneline -5`
3. **Ensure clean working directory**: `git status`
## Integration with Documentation System
### Documentation Updates
- **Always update documentation** when changing project structure
- **Use appropriate templates** for new documentation
- **Maintain YAML front matter** completeness
- **Update related_docs** when creating new relationships
### Testing Integration
- **Run container tests** before any Docker-related commits
- **Validate documentation** before documentation commits
- **Check index completeness** when adding new docs
---
_This rule integrates with our documentation system. For complete development guidelines, see [README.development.md](mdc:documentation/dev/README.development.md)._
.cursor/rules/playwright-testing.mdc
+338
View File
@@ -0,0 +1,338 @@
---
description: Cursor rules for using Playwright MCP for browser testing and validation
globs: sirius-ui/**/*.tsx, sirius-ui/**/*.ts, sirius-ui/**/*.jsx, sirius-ui/**/*.js
alwaysApply: false
---
# Playwright Browser Testing Rules
## When to Use Playwright
**The AI should use Playwright MCP server for:**
### Testing & Validation
- **UI Implementation Validation**: Verify new React components render and function correctly
- **Form Testing**: Test form submissions, validations, and user inputs
- **Integration Testing**: Verify UI-to-API data flow and interactions
- **User Flow Testing**: Test complete user journeys (login → navigate → action → result)
### Troubleshooting & Debugging
- **Bug Reproduction**: Reproduce user-reported UI issues in the browser
- **Console Error Inspection**: Capture JavaScript errors and warnings
- **Network Request Analysis**: Verify API calls are made correctly
- **Visual Debugging**: Capture screenshots of error states
### Development Support
- **Design Verification**: Check component layouts and responsive behavior
- **Regression Testing**: Verify existing functionality after changes
- **API Integration Checks**: Confirm frontend properly calls backend endpoints
- **State Management Testing**: Verify state updates and data flow
## When NOT to Use Playwright
**Do NOT use Playwright for:**
- ❌ Backend API testing (use curl or API tools)
- ❌ Unit tests (use Jest/Vitest)
- ❌ Build/compilation issues (check logs directly)
- ❌ Database queries (use database tools)
- ❌ Performance testing (use dedicated tools)
## Required Documentation
When working with Playwright, include:
- [README.playwright.md](mdc:documentation/dev/ai-rules/README.playwright.md) - Complete Playwright testing guide
- [README.container-testing.md](mdc:documentation/dev/test/README.container-testing.md) - Container testing context
## Critical: Docker Network Access
**ALWAYS use `host.docker.internal` for URLs:**
```typescript
✅ CORRECT:
- http://host.docker.internal:3000 // UI
- http://host.docker.internal:9001 // API
❌ WRONG:
- http://localhost:3000
- http://127.0.0.1:3000
```
**Why:** The Playwright MCP server runs inside Docker and cannot access `localhost`. Use Docker's special DNS name `host.docker.internal` to access services on the host machine.
## Testing Workflow
### 1. Initial Navigation
```yaml
Step 1: Navigate to page
- Use: browser_navigate
- URL: http://host.docker.internal:3000/path
Step 2: Wait for load
- Use: browser_wait_for
- Time: 2-3 seconds for async content
```
### 2. Authentication (if required)
```yaml
Step 1: Fill credentials
- Username: admin
- Password: password
Step 2: Submit
- Click: "Join the Pack" button
Step 3: Wait for redirect
- Wait: 3 seconds
- Verify: Redirected to dashboard
```
### 3. Interaction Testing
```yaml
Step 1: Take snapshot
- Use: browser_snapshot
- Purpose: Get element refs
Step 2: Interact with elements
- Use element refs from snapshot
- Type, click, select as needed
Step 3: Verify results
- Check console messages
- Check network requests
- Take screenshot if needed
```
### 4. Verification
```yaml
Step 1: Check network activity
- Use: browser_network_requests
- Verify: Expected API calls made
Step 2: Check console
- Use: browser_console_messages
- Look for: Errors or warnings
Step 3: Visual verification
- Use: browser_snapshot or browser_take_screenshot
- Confirm: UI state is correct
```
## Common Test Patterns
### Testing Form Submission
```yaml
Pattern: 1. Navigate to form page
2. Fill required fields
3. Submit form
4. Verify API request (queue.sendMsg, etc.)
5. Check UI updates
6. Verify no console errors
```
### Testing API Integration
```yaml
Pattern: 1. Navigate to page that loads data
2. Wait for API calls to complete
3. Check network requests
4. Verify data displays correctly
5. Test error scenarios
```
### Debugging UI Issues
```yaml
Pattern: 1. Navigate to problematic page
2. Take snapshot for structure
3. Get console messages
4. Get network requests
5. Take screenshot
6. Analyze and identify issue
```
## Playwright Tools Quick Reference
| Tool | Purpose | Common Use |
| -------------------------- | -------------------- | --------------------- |
| `browser_navigate` | Load a page | Initial navigation |
| `browser_snapshot` | Get page structure | Find element refs |
| `browser_click` | Click elements | Buttons, links |
| `browser_type` | Type text | Forms, inputs |
| `browser_wait_for` | Wait for conditions | Page load, async data |
| `browser_network_requests` | View API calls | Verify integrations |
| `browser_console_messages` | Get console logs | Debug errors |
| `browser_take_screenshot` | Capture visual state | Document issues |
## Best Practices
### ✅ DO:
1. **Always use host.docker.internal URLs**
```
http://host.docker.internal:3000
```
2. **Wait for page loads and async operations**
```yaml
- Navigate
- Wait 2-3 seconds
- Then interact
```
3. **Take snapshots before interactions**
```yaml
- Snapshot to get refs
- Use refs for clicks/types
```
4. **Check network requests after actions**
```yaml
- Perform action
- Get network requests
- Verify API calls
```
5. **Capture console messages**
```yaml
- After interactions
- Look for errors
- Verify debug logs
```
### ❌ DON'T:
1. **Use localhost or 127.0.0.1**
- Always use host.docker.internal
2. **Interact immediately after navigation**
- Wait for page to fully load
3. **Use stale element refs**
- Take fresh snapshot before each interaction set
4. **Ignore console errors**
- Always check console messages
5. **Skip network verification**
- Verify expected API calls were made
## Example: Complete Test Flow
```yaml
Test: Scanner Page Functionality
Setup:
- Ensure containers running
- Verify UI accessible
Step 1: Authentication
- Navigate: http://host.docker.internal:3000
- Wait: 3 seconds
- Type username: "admin"
- Type password: "password"
- Click: "Join the Pack"
- Wait: 3 seconds
Step 2: Navigate to Scanner
- Click: Scanner link
- Wait: 2 seconds
- Verify: Page loaded
Step 3: Add Target
- Snapshot: Get input ref
- Type: "192.168.1.100"
- Click: Add button
- Verify: Target in list
Step 4: Start Scan
- Select template: "High Risk Scan"
- Click: "Start Scan"
- Get network requests
- Verify: queue.sendMsg called
- Verify: store.setValue called
- Check console: No errors
Step 5: Verification
- Snapshot: Check UI updates
- Screenshot: Document state
- Network: Verify ongoing polling
```
## Troubleshooting Common Issues
### Connection Refused
```
Error: net::ERR_CONNECTION_REFUSED
Solution: Use host.docker.internal not localhost
```
### Element Not Found
```
Problem: Element ref is stale
Solution: Take fresh snapshot before interaction
```
### Timeout Errors
```
Problem: Page loads slowly
Solution: Increase wait time (3-5 seconds)
```
### API Not Called
```
Problem: Action didn't trigger API
Solution: Check console for errors, verify element interaction worked
```
## Integration with Development Workflow
### When to Run Playwright Tests
1. **After UI Changes**
- Verify components render
- Test interactions work
- Check user flows
2. **Bug Reports**
- Reproduce issues
- Capture error state
- Verify fixes
3. **Feature Development**
- Validate new features
- Test edge cases
- Verify integrations
4. **Code Review**
- Validate implementations
- Check error handling
- Test user experience
---
_This rule integrates with our testing system. For complete Playwright documentation, see [README.playwright.md](mdc:documentation/dev/ai-rules/README.playwright.md)._
.cursor/rules/task-management.mdc
+145
View File
@@ -0,0 +1,145 @@
---
alwaysApply: true
---
# Task Management and Project Tracking
## Core Task Management Principles
When working with any project that has task files (`tasks/*.json`) or project plans (`documentation/dev-notes/*-plan.md`):
### Always Include Task Context
**Required Documentation for Task Work:**
- [README.tasks.md](mdc:documentation/dev/operations/README.tasks.md) - Task management system guidelines
- [README.new-project.md](mdc:documentation/dev/operations/README.new-project.md) - Project workflow and structure
### Task File Integration
**When working on projects with tasks:**
- **Check current task status** before starting work
- **Identify available tasks** (pending status, dependencies met)
- **Update task status** as work progresses
- **Reference task IDs** in commit messages when relevant
- **Mark tasks complete** immediately when finished
### Project Structure Awareness
**Standard Project Files:**
- `tasks/{sprint-name}.json` - Detailed task breakdown and tracking
- `documentation/dev-notes/{sprint-name}-plan.md` - High-level project overview
- Feature branch: `feature/{sprint-name}` for development work
### Task Status Management
**Status Values:**
- `pending` - Task not started (default)
- `in_progress` - Currently being worked on
- `done` - Completed successfully
- `blocked` - Cannot proceed (waiting for external dependency)
**Update Pattern:**
1. Start work: Change to `in_progress`
2. Complete work: Change to `done`
3. Hit blocker: Change to `blocked`
4. Resolve blocker: Change back to `in_progress`
### Dependency Resolution
**Before starting any task:**
- Check all dependencies are completed
- Only work on tasks with status `pending` and no incomplete dependencies
- Update dependent tasks when completing work
### Git Integration
**Standard Workflow:**
- Create feature branch: `git checkout -b feature/{sprint-name}`
- Commit task changes with code changes
- Reference task IDs in commit messages
- Merge to main when project complete
### Task File Maintenance
**Regular Updates:**
- Update status as work progresses
- Add details if requirements change
- Update dependencies if new relationships discovered
- Refine test strategies based on implementation
### Cleanup Requirements
**Every project must include:**
- Final cleanup task to remove temporary files
- Update documentation as needed
- Merge feature branch back to main
- Clean up project files
## Context Shaping for Task Work
### High Priority Context
- Current task file content and status
- Project plan document for context
- Task management guidelines
- Git workflow standards
### Medium Priority Context
- Related documentation based on task content
- Architecture references for technical tasks
- Testing guidelines for verification tasks
### Low Priority Context
- General development standards
- Historical project context
- Future enhancement planning
## Task Completion Checklist
When completing any task:
- [ ] Verify work meets task requirements
- [ ] Test using provided test strategy
- [ ] Update task status to `done`
- [ ] Check dependent tasks for availability
- [ ] Commit changes with descriptive message
- [ ] Reference task ID in commit message
## Common Task Patterns
### Starting New Work
1. Review task file for available tasks
2. Select highest priority available task
3. Update status to `in_progress`
4. Follow task details and requirements
5. Complete work and mark as `done`
### Handling Blockers
1. Update task status to `blocked`
2. Add details about the blocker
3. Work on other available tasks
4. Return when blocker is resolved
### Project Completion
1. Complete all tasks including cleanup
2. Update project plan with final status
3. Merge feature branch to main
4. Clean up temporary files and branches
---
_This rule ensures consistent task management and project tracking across all development work. Always check your tasks, mark them complete, and ask for support when needed._
.cursor/rules/testing-workflow.mdc
+189
View File
@@ -0,0 +1,189 @@
---
description: Cursor rules for testing workflows and validation processes
globs: testing/**/*, docker-compose*.yaml, Dockerfile*
alwaysApply: false
---
# Testing Workflows and Validation
## Testing Context
When working on testing-related tasks, include these documentation sources:
### Required Documentation
- [README.container-testing.md](mdc:documentation/dev/test/README.container-testing.md) - Container testing system
- [README.documentation-testing.md](mdc:documentation/dev/test/README.documentation-testing.md) - Documentation testing system
- [README.development.md](mdc:documentation/dev/README.development.md) - Development environment setup
## Testing Directory Structure
```
testing/
├── container-testing/ # Container-specific tests
│ ├── test-build.sh # Build validation
│ ├── test-health.sh # Health checks
│ └── test-integration.sh # Integration tests
├── Makefile # Testing commands
├── logs/ # Test execution logs
└── tmp/ # Temporary files and logs
```
## Testing Commands
### Complete Test Suite
```bash
cd testing/container-testing
make test-all # Run all tests
make validate-all # Run tests + documentation validation
```
### Individual Test Types
```bash
cd testing/container-testing
make test-build # Container build validation
make test-health # Service health checks
make test-integration # Integration testing
```
### Documentation Testing
```bash
cd testing/container-testing
make lint-docs # Full documentation linting
make lint-docs-quick # Quick documentation checks
make lint-index # Index completeness validation
```
## Container Testing Workflow
### Before Testing
1. **Ensure clean environment**: `docker compose down -v`
2. **Check Docker status**: `docker ps`
3. **Navigate to container testing directory**: `cd testing/container-testing`
### Build Testing
```bash
# Test all container builds
make test-build
# Test specific environment
docker compose -f docker-compose.dev.yaml config --quiet
docker compose -f docker-compose.prod.yaml config --quiet
```
### Health Testing
```bash
# Start services
docker compose up -d
# Run health checks
make test-health
# Check specific service
docker compose logs sirius-api
```
### Integration Testing
```bash
# Run integration tests
make test-integration
# Test specific service interactions
curl -f http://localhost:9001/health
curl -f http://localhost:3000/
```
## Documentation Testing Workflow
### Before Documentation Changes
1. **Check current documentation state**: `cd testing && make lint-docs-quick`
2. **Review documentation index**: Check `documentation/README.documentation-index.md`
### During Documentation Work
1. **Use appropriate templates** from `documentation/dev/templates/`
2. **Include complete YAML front matter** with all required fields
3. **Update related_docs** when creating new relationships
4. **Follow naming conventions** (ABOUT._, README._, TEMPLATE.\*)
### After Documentation Changes
1. **Run full documentation linting**: `cd testing && make lint-docs`
2. **Check index completeness**: `cd testing && make lint-index`
3. **Validate template compliance**: Review linting output
## Test Environment Management
### Development Environment
- **Uses**: `docker-compose.dev.yaml` overrides
- **Features**: Hot reloading, volume mounts, longer timeouts
- **Timeout**: 4 minutes for API dependency downloads
### Production Environment
- **Uses**: `docker-compose.prod.yaml` overrides
- **Features**: Optimized builds, production configurations
- **Timeout**: Standard 2 minutes
### Base Environment
- **Uses**: Standard `docker-compose.yaml`
- **Features**: Default configuration, core functionality
- **Timeout**: Standard 2 minutes
## Troubleshooting Testing Issues
### Common Problems
| Issue | Symptoms | Solution |
| --------------------- | -------------------------- | --------------------------------------------- |
| Build failures | "target stage not found" | Check Dockerfile stage names in Compose files |
| Health check timeouts | "service not ready" | Increase timeout or check service logs |
| Port conflicts | "port already in use" | Stop conflicting services or change ports |
| Documentation errors | "Missing section" warnings | Compare document with template structure |
### Debugging Commands
```bash
# Check service status
docker compose ps
# View service logs
docker compose logs [service-name]
# Check container health
docker exec [container-name] ps aux
# Validate Docker Compose
docker compose config --quiet
# Check documentation issues
cd testing && make lint-docs
```
## Integration with Development Workflow
### Pre-Commit Testing
- **Always run tests** before committing changes
- **Validate documentation** for documentation commits
- **Check container health** for Docker-related changes
### CI/CD Integration
- **Use testing commands** in CI/CD pipelines
- **Leverage Makefile targets** for consistent execution
- **Include documentation validation** in automated checks
---
_This rule integrates with our testing system. For complete testing guidelines, see [README.container-testing.md](mdc:documentation/dev/test/README.container-testing.md) and [README.documentation-testing.md](mdc:documentation/dev/test/README.documentation-testing.md)._
.editorconfig
+18
View File
@@ -0,0 +1,18 @@
root = true
[*]
end_of_line = lf
charset = utf-8
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2
[*.go]
indent_style = tab
[Makefile]
indent_style = tab
[*.md]
trim_trailing_whitespace = false
.env.production.example
+59
View File
@@ -0,0 +1,59 @@
# Sirius production/local-prod compose environment template
# Copy to .env (or export these vars in your shell) before:
# docker compose -f docker-compose.yaml -f docker-compose.prod.yaml up -d
# Optional image tag override.
# Leave blank to use docker-compose.yaml's default public tag (`latest`).
# Pin a release tag only after the release publish workflow confirms all six
# Sirius images exist for that tag.
IMAGE_TAG=
# Internal service API key for sirius-ui (server), sirius-api, and sirius-engine.
# The installer writes ./secrets/sirius_api_key.txt and compose mounts it at this path.
SIRIUS_API_KEY_FILE=/run/secrets/sirius_api_key
# Required database credentials
POSTGRES_USER=postgres
POSTGRES_PASSWORD=change-me-strong-db-password
POSTGRES_DB=sirius
POSTGRES_HOST=sirius-postgres
POSTGRES_PORT=5432
# Database connection URL (auto-generated by the installer from POSTGRES_* above)
# Override manually only if you need a custom connection string.
DATABASE_URL=
# UI auth settings (required secret)
NEXTAUTH_SECRET=change-me-long-random-nextauth-secret
NEXTAUTH_URL=http://localhost:3000
INITIAL_ADMIN_PASSWORD=change-me-strong-admin-password
# API URLs (runtime contract)
# - SIRIUS_API_URL: canonical server-side base URL for Docker services (sirius-ui server, engine, scanner).
# - NEXT_PUBLIC_SIRIUS_API_URL: browser-only; must reach the published API port on the host.
# - API_BASE_URL: optional legacy alias for agent tooling; if unset, compose sets it from SIRIUS_API_URL.
# Do not set API_BASE_URL to a different host than SIRIUS_API_URL.
SIRIUS_API_URL=http://sirius-api:9001
NEXT_PUBLIC_SIRIUS_API_URL=http://localhost:9001
# API service settings
GO_ENV=production
API_PORT=9001
CORS_ALLOWED_ORIGINS=http://localhost:3000,https://sirius.local
# Engine settings
ENGINE_MAIN_PORT=5174
GRPC_AGENT_PORT=50051
# API_BASE_URL=http://sirius-api:9001
# Host discovery in prod overlay requires NET_RAW on sirius-engine
# (configured in docker-compose.prod.yaml)
# Infrastructure endpoints
VALKEY_HOST=sirius-valkey
VALKEY_PORT=6379
RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/
# Validation quick checks after startup:
# - valkey-cli GET template:quick (must include "fingerprint" in scan_types)
# - rabbitmqctl list_queues name consumers messages_ready messages_unacknowledged
# - valkey-cli GET currentScan
.gitattributes
+13
View File
@@ -0,0 +1,13 @@
# Force LF for all text files -- prevents CRLF from entering containers
* text=auto eol=lf
# Explicitly mark binary files
*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.ico binary
*.woff binary
*.woff2 binary
*.ttf binary
*.eot binary
.github/ISSUE_TEMPLATE/auth-401.yml
+67
View File
@@ -0,0 +1,67 @@
name: Auth or 401 Issue
description: Report API key drift, auth mismatches, and unauthorized responses.
title: "[auth/401]: "
labels:
- status:needs-triage
- type:bug
- area:auth
body:
- type: markdown
attributes:
value: |
Use this form for `401` responses, API key mismatch, and auth surface incidents.
This maps directly to the API key operations runbook.
- type: input
id: endpoint
attributes:
label: Endpoint/Surface Affected
placeholder: "e.g. /host/, tRPC scanner.getScanStatus, /api/v1/keys"
validations:
required: true
- type: dropdown
id: symptom
attributes:
label: Primary Symptom
options:
- 401 on non-health API routes
- UI cannot read/write through tRPC
- scanner/agent submissions return 401
- key rotation appears incomplete
- unknown auth failure
validations:
required: true
- type: checkboxes
id: runbook_checks
attributes:
label: Runbook Checks Completed
options:
- label: I verified `SIRIUS_API_KEY` is set and non-empty in all runtime services.
required: true
- label: I confirmed services are using the same active key (`sirius-api`, `sirius-ui`, `sirius-engine`).
required: true
- label: I re-ran installer and restarted services after any key changes.
required: false
- type: textarea
id: evidence
attributes:
label: Diagnostics and Evidence
description: Include key env checks and relevant logs.
placeholder: |
docker inspect sirius-api --format '{{range .Config.Env}}{{println .}}{{end}}' | rg '^SIRIUS_API_KEY='
docker inspect sirius-ui --format '{{range .Config.Env}}{{println .}}{{end}}' | rg '^SIRIUS_API_KEY='
docker inspect sirius-engine --format '{{range .Config.Env}}{{println .}}{{end}}' | rg '^SIRIUS_API_KEY='
docker compose logs --no-color --tail=120 sirius-api sirius-ui sirius-engine
validations:
required: true
- type: textarea
id: repro_steps
attributes:
label: Reproduction Steps
placeholder: "Provide exact, minimal steps to reproduce."
validations:
required: true
.github/ISSUE_TEMPLATE/bug-report.yml
+60
View File
@@ -0,0 +1,60 @@
name: Bug Report
description: Report a reproducible defect in Sirius Scan.
title: "[bug]: "
labels:
- status:needs-triage
- type:bug
body:
- type: markdown
attributes:
value: |
Thank you for reporting a bug. Please provide enough detail for maintainers to reproduce quickly.
- type: input
id: component
attributes:
label: Affected Component
placeholder: "e.g. sirius-api, sirius-ui, scanner workflow, docker startup"
validations:
required: true
- type: input
id: version
attributes:
label: Version
placeholder: "e.g. v1.0.0, main, commit SHA"
validations:
required: true
- type: textarea
id: steps
attributes:
label: Reproduction Steps
placeholder: |
1. ...
2. ...
3. ...
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected Behavior
validations:
required: true
- type: textarea
id: actual
attributes:
label: Actual Behavior
validations:
required: true
- type: textarea
id: evidence
attributes:
label: Logs and Evidence
description: Include command output, screenshots, and relevant logs.
validations:
required: true
.github/ISSUE_TEMPLATE/config.yml
+11
View File
@@ -0,0 +1,11 @@
blank_issues_enabled: false
contact_links:
- name: Community Support
url: https://github.com/SiriusScan/Sirius/discussions
about: Ask usage and architecture questions in Discussions.
- name: Sirius Documentation
url: https://sirius.opensecurity.com/docs/getting-started/installation
about: Start here for setup and troubleshooting guidance.
- name: Security Policy
url: https://github.com/SiriusScan/Sirius/security/policy
about: Report sensitive vulnerabilities through private security channels.
.github/ISSUE_TEMPLATE/dev-overlay.yml
+49
View File
@@ -0,0 +1,49 @@
name: Dev Overlay / Compose Override Issue
description: Report local dev overlay, mount shadowing, and compose override problems.
title: "[dev-overlay]: "
labels:
- status:needs-triage
- type:bug
- area:compose-dev
body:
- type: markdown
attributes:
value: |
Use this form for `docker-compose.dev.yaml` usage issues, mount shadowing, and missing infra services.
Reminder: dev compose is an override file and must be combined with base compose.
- type: checkboxes
id: compose_usage
attributes:
label: Compose Command Validation
options:
- label: I used `docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d` (not dev file alone).
required: true
- label: `docker compose -f docker-compose.yaml -f docker-compose.dev.yaml config --quiet` succeeds.
required: true
- type: textarea
id: command_history
attributes:
label: Exact Commands Run
placeholder: "Paste exact commands in order."
validations:
required: true
- type: textarea
id: symptom
attributes:
label: What Broke?
placeholder: "e.g. missing postgres/rabbitmq/valkey, mount shadowing, prisma init issues."
validations:
required: true
- type: textarea
id: logs
attributes:
label: Logs / Compose Output
placeholder: |
docker compose ps
docker compose logs --no-color --tail=120 sirius-ui sirius-api sirius-engine
validations:
required: true
.github/ISSUE_TEMPLATE/feature-request.yml
+54
View File
@@ -0,0 +1,54 @@
name: Feature Request
description: Propose a new capability or improvement for Sirius Scan.
title: "[feature]: "
labels:
- status:needs-triage
- type:enhancement
body:
- type: markdown
attributes:
value: |
Use this form to propose features with clear problem framing and success criteria.
- type: textarea
id: problem
attributes:
label: Problem Statement
description: What user or operator problem are you trying to solve?
validations:
required: true
- type: textarea
id: proposal
attributes:
label: Proposed Solution
description: Describe the preferred implementation or behavior.
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives Considered
description: List alternatives and why they were not chosen.
validations:
required: false
- type: dropdown
id: impact
attributes:
label: Expected Impact
options:
- low
- medium
- high
validations:
required: true
- type: textarea
id: success
attributes:
label: Success Criteria
description: What outcomes or metrics indicate this feature is complete?
validations:
required: true
.github/ISSUE_TEMPLATE/install-startup.yml
+77
View File
@@ -0,0 +1,77 @@
name: Install or Startup Failure
description: Report stack startup failures, restart loops, and first-run issues.
title: "[install/startup]: "
labels:
- status:needs-triage
- type:bug
- area:installer-secrets
body:
- type: markdown
attributes:
value: |
Use this form when Sirius fails to start or continuously restarts.
Include required diagnostics so maintainers can triage without back-and-forth.
- type: dropdown
id: install_mode
attributes:
label: Install/Run Mode
description: Which compose mode are you using?
options:
- Standard (`docker compose up -d`)
- Dev overlay (`-f docker-compose.yaml -f docker-compose.dev.yaml`)
- Prod overlay (`-f docker-compose.yaml -f docker-compose.prod.yaml`)
validations:
required: true
- type: input
id: version
attributes:
label: Sirius Version / Image Tag
placeholder: "e.g. v1.0.0, latest, or image digest"
validations:
required: true
- type: input
id: host
attributes:
label: Host OS + Docker Version
placeholder: "e.g. macOS 15.2, Docker 27.x"
validations:
required: true
- type: checkboxes
id: installer_check
attributes:
label: Installer-First Validation
options:
- label: I ran `docker compose -f docker-compose.installer.yaml run --rm sirius-installer` before starting.
required: true
- label: I confirmed `docker compose config --quiet` renders successfully with required secrets.
required: true
- type: textarea
id: logs
attributes:
label: Relevant Logs (last 100 lines)
description: Include logs from `sirius-api`, `sirius-engine`, and `sirius-ui`.
placeholder: |
docker compose logs --no-color --tail=100 sirius-api sirius-engine sirius-ui
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected Behavior
placeholder: "What did you expect to happen?"
validations:
required: true
- type: textarea
id: observed
attributes:
label: Observed Behavior
placeholder: "What happened instead? Include exact errors."
validations:
required: true
.github/ISSUE_TEMPLATE/security-report.yml
+65
View File
@@ -0,0 +1,65 @@
name: Security Report (Non-sensitive)
description: Report security hardening gaps suitable for public tracking.
title: "[security]: "
labels:
- status:needs-triage
- type:security
- sev:high
body:
- type: markdown
attributes:
value: |
Use this form for non-sensitive security issues appropriate for public discussion.
For sensitive vulnerabilities, use GitHub Security Advisories instead.
- type: checkboxes
id: sensitivity
attributes:
label: Sensitivity Check
options:
- label: This report does not include exploit details or sensitive data.
required: true
- label: I understand sensitive issues must be reported privately.
required: true
- type: dropdown
id: surface
attributes:
label: Security Surface
options:
- Auth / API key validation
- Session / NextAuth
- CORS / headers
- RabbitMQ / queue integrity
- Deployment / secrets handling
- Other
validations:
required: true
- type: dropdown
id: impact
attributes:
label: Estimated Impact
options:
- critical
- high
- medium
- low
validations:
required: true
- type: textarea
id: description
attributes:
label: Issue Description
placeholder: "Describe the security concern and affected components."
validations:
required: true
- type: textarea
id: reproduction
attributes:
label: Reproduction / Validation
placeholder: "Steps, logs, and relevant hardening/security-suite evidence."
validations:
required: true
.github/ISSUE_TEMPLATE/windows-wsl.yml
+62
View File
@@ -0,0 +1,62 @@
name: Windows / WSL2 Issue
description: Report Windows-specific startup and script problems (including CRLF handling).
title: "[windows-wsl2]: "
labels:
- status:needs-triage
- type:bug
- platform:windows
body:
- type: markdown
attributes:
value: |
Sirius supports Windows via WSL2. Use this form for CRLF, shell script, and path/mount issues.
- type: input
id: windows_version
attributes:
label: Windows + WSL Version
placeholder: "e.g. Windows 11 24H2, WSL2 Ubuntu 24.04"
validations:
required: true
- type: input
id: docker_desktop
attributes:
label: Docker Desktop Version
placeholder: "e.g. 4.x"
validations:
required: true
- type: dropdown
id: issue_class
attributes:
label: Issue Class
options:
- CRLF / shell script execution
- bind mount behavior
- path translation
- networking/port behavior
- unknown
validations:
required: true
- type: textarea
id: evidence
attributes:
label: Evidence
placeholder: |
Include:
- exact error text
- command output
- relevant logs
- whether files were cloned in Windows FS or WSL FS
validations:
required: true
- type: textarea
id: repro
attributes:
label: Reproduction Steps
placeholder: "Minimal steps from clone to failure."
validations:
required: true
.github/ORGANIZATION_PROFILE_SETUP.md
+77
View File
@@ -0,0 +1,77 @@
# Organization Profile Rollout Checklist
This checklist publishes the organization profile using the content in `.github/profile/README.md`.
## 0. Prepare aesthetic baseline (brand/story)
Before publishing, confirm profile content has:
1. A short mission statement in the first paragraph.
2. A clear "what we build" section for first-time visitors.
3. A "start here" section with docs, install, API, and security links.
4. Repository blurbs that use consistent tone and sentence structure.
5. Contributor entry points (`CONTRIBUTING.md`, `SUPPORT.md`, Discussions).
## 1. Create the organization profile repository
1. In the `SiriusScan` organization, create a **public** repository named `.github`.
2. Copy `.github/profile/README.md` from this repository into the new repository at `profile/README.md`.
3. Commit and push.
## 2. Configure organization branding
1. Open organization settings and upload:
- Organization avatar (square logo)
- Optional profile banner image
2. Set a concise organization description aligned with the README mission statement.
3. Ensure links are set for website and documentation.
## 3. Configure public pinned repositories
Pin up to six repositories in this order (this is also the brand narrative order):
1. `Sirius`
2. `go-api`
3. `app-scanner`
4. `app-agent`
5. `pingpp`
6. `website`
## 4. Standardize repository metadata
For each pinned repository:
1. Update repository description for consistent language and tone.
2. Add GitHub topics (for example: `security`, `vulnerability-scanner`, `devsecops`, `golang`, `nextjs` as applicable).
3. Verify homepage URL points to product docs or website.
Recommended descriptions and links:
| Repository | Description | Homepage | Suggested topics |
| --- | --- | --- | --- |
| `Sirius` | Core platform, orchestration, docs, and deployment baseline for SiriusScan. | `https://sirius.opensecurity.com/docs/getting-started/quick-start` | `security`, `devsecops`, `vulnerability-scanner`, `docker`, `nextjs` |
| `go-api` | Backend API services for platform operations and integrations. | `https://sirius.opensecurity.com/docs/api/rest/authentication` | `golang`, `api`, `security`, `backend` |
| `app-scanner` | Scanning execution service for discovery and vulnerability collection. | `https://sirius.opensecurity.com/docs/getting-started/installation` | `scanner`, `security`, `golang`, `automation` |
| `app-agent` | Agent runtime for distributed scanning and remote execution workflows. | `https://sirius.opensecurity.com/docs/getting-started/installation` | `agent`, `golang`, `security`, `distributed-systems` |
| `pingpp` | Network diagnostics and connectivity support utilities. | `https://sirius.opensecurity.com/docs/getting-started/installation` | `networking`, `golang`, `diagnostics`, `security` |
| `website` | Public website and product-facing content for SiriusScan. | `https://sirius.opensecurity.com` | `website`, `nextjs`, `security`, `docs` |
## 5. Enable community and trust signals
1. Enable Discussions where appropriate.
2. Confirm each repository has:
- `README.md`
- `CONTRIBUTING.md`
- `SECURITY.md`
- `CODE_OF_CONDUCT.md`
- `LICENSE`
3. Confirm branch protection rules are enabled for default branches.
## 6. Publish quality check
Validate from a first-time visitor perspective:
1. Profile page communicates value in under 30 seconds.
2. New contributors can find contribution and support paths quickly.
3. Security reporting path is visible and private-report guidance is explicit.
4. Pinned repositories feel cohesive and professionally described.
.github/ORG_SETUP_STATUS.md
+40
View File
@@ -0,0 +1,40 @@
# SiriusScan Org Setup Status (Core-First)
This status note tracks implementation progress for the aesthetics + professional standards rollout.
## Completed in core repository (`Sirius`)
- Rewrote organization profile content in `.github/profile/README.md` with a brand/story-forward narrative and clear contributor entry points.
- Expanded `.github/ORGANIZATION_PROFILE_SETUP.md` with:
- aesthetic baseline checks
- recommended metadata table (description/homepage/topics)
- publish quality validation
- Added advisory standards pack:
- `.github/REPOSITORY_STANDARDS_ADVISORY.md`
- Added reusable rollout checklist:
- `.github/REPO_ROLLOUT_CHECKLIST.md`
## Verification summary
- First-time visitor clarity: improved through mission-first profile structure and explicit "Start Here" links.
- Contributor journey: explicit links to contribution guide, discussions, and support paths are present.
- Security reporting discoverability: security policy link remains prominent in profile and issue template config.
- Reusability: standards and rollout docs are now available as a template for other repositories.
## Remaining manual actions (GitHub UI)
These items cannot be fully enforced from repository files alone and should be completed in organization/repository settings:
- Apply final organization description text in org settings.
- Confirm pinned repositories in the specified narrative order.
- Update per-repository metadata (description, topics, homepage) to match the recommended table.
- Enable Discussions in repositories where community interaction is desired.
- Review branch protection/rulesets and keep them advisory-first for this phase.
## Next rollout targets
- `go-api`
- `app-scanner`
- `app-agent`
- `pingpp`
- `website`
.github/PULL_REQUEST_TEMPLATE.md
+52
View File
@@ -0,0 +1,52 @@
## Summary
Describe the problem this PR solves and why this approach was chosen.
## Change Type
- [ ] Bug fix
- [ ] Feature
- [ ] Refactor
- [ ] Documentation
- [ ] CI/CD or automation
- [ ] Security hardening
## Scope
- [ ] `sirius-ui`
- [ ] `sirius-api`
- [ ] `sirius-engine`
- [ ] Infrastructure (`postgres`, `rabbitmq`, `valkey`, compose)
- [ ] Documentation
- [ ] Other (describe below)
## Related Issue
Closes #
## Validation
- [ ] I ran required local validation for this change
- [ ] I attached logs, screenshots, or output where relevant
- [ ] I tested failure paths or edge cases where applicable
- [ ] CI checks are expected to pass for this PR
## Security and Risk Review
- [ ] No security impact
- [ ] Security impact reviewed and documented
- [ ] Rollback steps are documented for risky operational changes
## Documentation
- [ ] No docs change needed
- [ ] Updated `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, or related docs
- [ ] Added/updated issue templates or workflow docs
## Deployment Notes
List any operational notes (migrations, secret changes, compose changes, required order of deployment, etc.).
## Additional Context
Add anything reviewers should know (tradeoffs, follow-ups, known limitations).
.github/REPOSITORY_STANDARDS_ADVISORY.md
+78
View File
@@ -0,0 +1,78 @@
# SiriusScan Repository Standards (Advisory v1)
This document defines recommended repository standards for SiriusScan projects.
The goal is consistency and professionalism without introducing blocking rules. Teams can adopt these recommendations incrementally.
## Scope
Applies to public SiriusScan repositories, starting with `Sirius` and then expanding to:
- `go-api`
- `app-scanner`
- `app-agent`
- `pingpp`
- `website`
## Recommended baseline artifacts
Each repository should include:
- `README.md`
- `CONTRIBUTING.md`
- `SECURITY.md`
- `CODE_OF_CONDUCT.md`
- `LICENSE`
- `SUPPORT.md` (recommended for active external contribution)
## Issue and PR intake standards
Recommended defaults:
- Issue templates for bug reports and feature requests
- A security-focused intake path with explicit private-report guidance
- A PR template that captures:
- problem statement
- risk and validation evidence
- docs and rollout notes
For repositories with low issue volume, start with minimal templates and expand later.
## Labels and triage hygiene
Recommended label taxonomy:
- `type:*` (for example: `type:bug`, `type:enhancement`, `type:security`)
- `status:*` (for example: `status:needs-triage`, `status:blocked`, `status:ready`)
- `sev:*` for risk level where relevant
- domain labels for components only where maintainers need them
Recommended triage SLA:
- First maintainer response within 2 business days
- Security-labeled issues reviewed as priority
## Metadata and discoverability
Each repository should have:
- A one-line description aligned with org voice
- At least 4-6 relevant topics
- A homepage URL to docs, API reference, or website
- Optional Discussions enabled where community interaction is expected
## Review and CI expectations (advisory)
Recommended defaults (not hard-gated in this phase):
- At least one maintainer review before merge
- CI should run on pull requests
- Validation evidence included in PR description
- Security-sensitive changes include rollback notes
## Adoption approach
1. Adopt standards in `Sirius` first.
2. Reuse the rollout checklist in `.github/REPO_ROLLOUT_CHECKLIST.md`.
3. Track deviations and repository-specific exceptions in the repo README or maintainer notes.
4. Revisit after adoption to decide whether any standards should become required.
.github/REPO_ROLLOUT_CHECKLIST.md
+64
View File
@@ -0,0 +1,64 @@
# SiriusScan Repository Rollout Checklist
Use this checklist to apply the core `Sirius` standards to other SiriusScan repositories.
Target repositories:
- `go-api`
- `app-scanner`
- `app-agent`
- `pingpp`
- `website`
## 1) Pre-check
- Confirm default branch and active maintainers.
- Confirm repository is public or intended visibility is documented.
- Confirm whether Discussions should be enabled for that repository.
## 2) Copy baseline artifacts
Copy and adapt from `Sirius`:
- `CONTRIBUTING.md`
- `SECURITY.md`
- `CODE_OF_CONDUCT.md`
- `SUPPORT.md` (recommended)
- `.github/PULL_REQUEST_TEMPLATE.md`
- `.github/ISSUE_TEMPLATE/config.yml`
- Relevant `.github/ISSUE_TEMPLATE/*.yml` files
## 3) Customize repository-specific content
Adjust per repository:
- Repository description (one clear sentence)
- Homepage URL (docs, API reference, or website)
- Topics (4-6 relevant tags)
- README architecture and setup sections
- Template wording for component names and troubleshooting paths
## 4) Labels and workflows
- Apply label taxonomy from `.github/labels.yml` where relevant.
- Ensure issue triage workflow is compatible with current labels.
- Keep CI and automation advisory-first in this phase (no new hard gates required).
## 5) Verification rubric (professional-ready)
A repository is considered ready when all checks below pass:
- Professional first impression from repo homepage
- Clear contribution and support paths
- Security reporting path is present and understandable
- Issue and PR templates collect enough context for maintainers
- Metadata (description/topics/homepage) is complete and coherent
## 6) Completion record
For each repository, record:
- Date completed
- Maintainer reviewer
- Deviations from baseline and rationale
- Follow-up items
.github/dependabot.yml
+84
View File
@@ -0,0 +1,84 @@
# Dependabot configuration for automatic dependency updates
#
# This configuration enables automated dependency updates for Go modules,
# Docker images, and GitHub Actions. Dependabot will create PRs automatically
# when new versions are available.
#
# See: https://docs.github.com/en/code-security/dependabot
version: 2
updates:
# Go modules in sirius-api
- package-ecosystem: "gomod"
directory: "/sirius-api"
schedule:
interval: "daily"
time: "06:00"
timezone: "America/Los_Angeles"
labels:
- "dependencies"
- "go"
- "sirius-api"
commit-message:
prefix: "chore(deps)"
include: "scope"
open-pull-requests-limit: 5
reviewers:
- "0sm0s1z"
# Auto-merge minor and patch updates after tests pass
versioning-strategy: increase
# Go modules in sirius-engine
- package-ecosystem: "gomod"
directory: "/sirius-engine"
schedule:
interval: "daily"
time: "06:00"
timezone: "America/Los_Angeles"
labels:
- "dependencies"
- "go"
- "sirius-engine"
commit-message:
prefix: "chore(deps)"
include: "scope"
open-pull-requests-limit: 5
reviewers:
- "0sm0s1z"
versioning-strategy: increase
# Docker images
- package-ecosystem: "docker"
directory: "/"
schedule:
interval: "weekly"
day: "monday"
time: "06:00"
timezone: "America/Los_Angeles"
labels:
- "dependencies"
- "docker"
commit-message:
prefix: "chore(deps)"
include: "scope"
open-pull-requests-limit: 3
reviewers:
- "0sm0s1z"
# GitHub Actions
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
day: "monday"
time: "06:00"
timezone: "America/Los_Angeles"
labels:
- "dependencies"
- "github-actions"
commit-message:
prefix: "chore(deps)"
include: "scope"
open-pull-requests-limit: 3
reviewers:
- "0sm0s1z"
.github/labeler.yml
+68
View File
@@ -0,0 +1,68 @@
area:ui:
- changed-files:
- any-glob-to-any-file:
- "sirius-ui/**"
area:api:
- changed-files:
- any-glob-to-any-file:
- "sirius-api/**"
area:engine:
- changed-files:
- any-glob-to-any-file:
- "sirius-engine/**"
area:compose-dev:
- changed-files:
- any-glob-to-any-file:
- "docker-compose.dev.yaml"
- "docker-compose.override.yaml"
- "scripts/dev-setup.sh"
area:compose-prod:
- changed-files:
- any-glob-to-any-file:
- "docker-compose.prod.yaml"
- ".github/workflows/deploy.yml"
area:installer-secrets:
- changed-files:
- any-glob-to-any-file:
- "docker-compose.installer.yaml"
- ".env.production.example"
- "documentation/dev/architecture/ADR.startup-secrets-model.md"
- "documentation/dev/operations/README.api-key-operations.md"
area:auth:
- changed-files:
- any-glob-to-any-file:
- "sirius-ui/src/server/auth.ts"
- "sirius-ui/src/server/api/**"
- "sirius-api/**/middleware/**"
- "documentation/dev/architecture/README.auth-surface-matrix.md"
area:rabbitmq:
- changed-files:
- any-glob-to-any-file:
- "sirius-rabbitmq/**"
- "**/*rabbitmq*"
area:postgres:
- changed-files:
- any-glob-to-any-file:
- "sirius-postgres/**"
- "**/*prisma*"
- "**/*migration*"
area:valkey:
- changed-files:
- any-glob-to-any-file:
- "**/*valkey*"
- "**/*redis*"
type:docs:
- changed-files:
- any-glob-to-any-file:
- "documentation/**"
- "README.md"
.github/labels.yml
+104
View File
@@ -0,0 +1,104 @@
- name: "status:needs-triage"
color: "FBCA04"
description: "New issue or PR requires maintainer triage."
- name: "status:needs-info"
color: "D4C5F9"
description: "Reporter must provide missing diagnostics or reproduction details."
- name: "status:repro-ready"
color: "C2E0C6"
description: "Issue includes sufficient details for reproducible investigation."
- name: "status:confirmed"
color: "0E8A16"
description: "Maintainer has reproduced or validated the issue."
- name: "status:in-progress"
color: "1D76DB"
description: "A maintainer is actively implementing or validating a fix."
- name: "status:blocked"
color: "B60205"
description: "Work is blocked by dependency, environment, or external input."
- name: "status:ready-to-merge"
color: "5319E7"
description: "PR has required evidence and is waiting final merge decision."
- name: "status:done"
color: "0E8A16"
description: "Issue has been resolved and closed."
- name: "type:bug"
color: "D73A4A"
description: "Behavior does not match expected function."
- name: "type:enhancement"
color: "A2EEEF"
description: "Improvement to existing behavior or workflow."
- name: "type:security"
color: "B60205"
description: "Security behavior, hardening, or vulnerability concern."
- name: "type:docs"
color: "0075CA"
description: "Documentation updates or gaps."
- name: "type:question"
color: "D876E3"
description: "Clarification or support question."
- name: "size/XS"
color: "0E8A16"
description: "Small PR with very low review complexity."
- name: "size/S"
color: "1D76DB"
description: "Small PR with low review complexity."
- name: "size/M"
color: "FBCA04"
description: "Medium PR with moderate review complexity."
- name: "size/L"
color: "D93F0B"
description: "Large PR with high review complexity."
- name: "size/XL"
color: "B60205"
description: "Very large PR; consider splitting into smaller changes."
- name: "area:installer-secrets"
color: "F9D0C4"
description: "Installer-first flow, startup contract, or runtime secrets."
- name: "area:compose-dev"
color: "F9D0C4"
description: "Development overlay compose behavior and local mounts."
- name: "area:compose-prod"
color: "F9D0C4"
description: "Production compose overlay behavior and runtime settings."
- name: "area:ui"
color: "C5DEF5"
description: "sirius-ui frontend and server-side API bridge."
- name: "area:api"
color: "C5DEF5"
description: "sirius-api routes, middleware, and API behavior."
- name: "area:engine"
color: "C5DEF5"
description: "sirius-engine scanning, gRPC, and orchestration behavior."
- name: "area:rabbitmq"
color: "C5DEF5"
description: "Queue durability, routing, and consumer behavior."
- name: "area:postgres"
color: "C5DEF5"
description: "Database schema, connection, and persistence concerns."
- name: "area:valkey"
color: "C5DEF5"
description: "Valkey cache/key lifecycle behavior."
- name: "area:auth"
color: "C5DEF5"
description: "Authentication, API key validation, and auth surfaces."
- name: "sev:critical"
color: "B60205"
description: "Security/data-loss/system integrity risk requiring immediate response."
- name: "sev:high"
color: "D93F0B"
description: "System unusable or major reliability break."
- name: "sev:medium"
color: "FBCA04"
description: "Substantial issue with workaround available."
- name: "sev:low"
color: "0E8A16"
description: "Minor issue or paper-cut with low immediate risk."
- name: "platform:windows"
color: "BFDADC"
description: "Issue specific to Windows/WSL2 environments."
.github/profile/README.md
+37
View File
@@ -0,0 +1,37 @@
# SiriusScan
SiriusScan is an open-source security engineering platform for teams that want continuous visibility, faster risk triage, and practical remediation workflows.
We build security tooling for real operators and developers: discover assets, identify vulnerabilities, prioritize what matters, and integrate security work into day-to-day delivery.
## What We Build
- Continuous discovery and scanning across hosts, services, and infrastructure
- Vulnerability intelligence and risk prioritization using actionable severity context
- Operational workflows for remediation tracking and security posture reporting
- API-first and automation-friendly components for modern DevSecOps pipelines
## Start Here
- Quick start: <https://sirius.opensecurity.com/docs/getting-started/quick-start>
- Installation: <https://sirius.opensecurity.com/docs/getting-started/installation>
- API docs: <https://sirius.opensecurity.com/docs/api/rest/authentication>
- Security policy: <https://github.com/SiriusScan/Sirius/security/policy>
- Project discussions: <https://github.com/SiriusScan/Sirius/discussions>
## Core Repositories
- [`Sirius`](https://github.com/SiriusScan/Sirius) - Core platform, orchestration, documentation, and deployment baseline
- [`go-api`](https://github.com/SiriusScan/go-api) - Backend API services for integrations and platform operations
- [`app-scanner`](https://github.com/SiriusScan/app-scanner) - Scanning execution service for discovery and vulnerability collection
- [`app-agent`](https://github.com/SiriusScan/app-agent) - Agent runtime for distributed scanning and remote execution patterns
- [`pingpp`](https://github.com/SiriusScan/pingpp) - Network diagnostics and supporting connectivity utilities
- [`website`](https://github.com/SiriusScan/website) - Public website, messaging, and product-facing content
## Contribute
We welcome improvements in code, testing, documentation, and security hardening.
- Contribution guide: <https://github.com/SiriusScan/Sirius/blob/main/CONTRIBUTING.md>
- Code of conduct: <https://github.com/SiriusScan/Sirius/blob/main/CODE_OF_CONDUCT.md>
- Support channels: <https://github.com/SiriusScan/Sirius/blob/main/SUPPORT.md>
.github/workflows/chatops-runner.yml
+172
View File
@@ -0,0 +1,172 @@
name: ChatOps Runner
on:
repository_dispatch:
types: [chatops-command]
permissions:
contents: read
issues: write
pull-requests: write
jobs:
run-command:
name: Execute triage/test command
runs-on: ubuntu-latest
env:
COMMAND: ${{ github.event.client_payload.command }}
ISSUE_NUMBER: ${{ github.event.client_payload.issue_number }}
IS_PR: ${{ github.event.client_payload.is_pr }}
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Parse command
id: parse
shell: bash
run: |
set -euo pipefail
cmd="${COMMAND}"
echo "raw=$cmd" >> "$GITHUB_OUTPUT"
if [[ "$cmd" == /triage* ]]; then
state="$(echo "$cmd" | awk '{print $2}')"
echo "kind=triage" >> "$GITHUB_OUTPUT"
echo "state=${state}" >> "$GITHUB_OUTPUT"
exit 0
fi
if [[ "$cmd" == /test* ]]; then
sub="$(echo "$cmd" | awk '{print $2}')"
suite="$(echo "$cmd" | awk '{print $3}')"
echo "kind=test" >> "$GITHUB_OUTPUT"
echo "sub=${sub}" >> "$GITHUB_OUTPUT"
echo "suite=${suite}" >> "$GITHUB_OUTPUT"
exit 0
fi
echo "kind=unknown" >> "$GITHUB_OUTPUT"
- name: Handle triage status transition
if: steps.parse.outputs.kind == 'triage'
uses: actions/github-script@v7
with:
script: |
const target = "${{ steps.parse.outputs.state }}";
const allowed = new Set(["needs-info", "repro-ready", "confirmed"]);
if (!allowed.has(target)) {
core.setOutput("triage_message", `Unsupported triage state: ${target}`);
return;
}
const statusLabels = [
"status:needs-triage",
"status:needs-info",
"status:repro-ready",
"status:confirmed",
"status:in-progress",
"status:blocked",
"status:ready-to-merge",
"status:done",
];
const owner = context.repo.owner;
const repo = context.repo.repo;
const issue_number = Number(process.env.ISSUE_NUMBER);
const issue = await github.rest.issues.get({ owner, repo, issue_number });
const existingLabels = issue.data.labels.map((l) => l.name);
for (const label of existingLabels) {
if (statusLabels.includes(label)) {
try {
await github.rest.issues.removeLabel({ owner, repo, issue_number, name: label });
} catch (error) {
core.warning(`Could not remove ${label}: ${error.message}`);
}
}
}
const newLabel = `status:${target}`;
await github.rest.issues.addLabels({
owner,
repo,
issue_number,
labels: [newLabel],
});
core.setOutput("triage_message", `Applied \`${newLabel}\`.`);
- name: Run requested test suite
id: test
if: steps.parse.outputs.kind == 'test'
shell: bash
run: |
set -uo pipefail
sub="${{ steps.parse.outputs.sub }}"
suite="${{ steps.parse.outputs.suite }}"
mkdir -p .chatops
log_file=".chatops/output.log"
exit_code=0
if [[ "$sub" == "health" ]]; then
./testing/container-testing/test-health.sh > "$log_file" 2>&1 || exit_code=$?
elif [[ "$sub" == "integration" ]]; then
./testing/container-testing/test-integration.sh > "$log_file" 2>&1 || exit_code=$?
elif [[ "$sub" == "security" ]]; then
if [[ -z "$suite" ]]; then
echo "Missing suite. Use: /test security <suite>" > "$log_file"
exit_code=2
else
cd testing/security
go run . --suite "$suite" > "../../$log_file" 2>&1 || exit_code=$?
fi
else
echo "Unsupported test command: /test $sub" > "$log_file"
exit_code=2
fi
echo "exit_code=$exit_code" >> "$GITHUB_OUTPUT"
{
echo "excerpt<<'EOF'"
tail -n 40 "$log_file"
echo "EOF"
} >> "$GITHUB_OUTPUT"
- name: Publish result comment
uses: actions/github-script@v7
env:
TRIAGE_MESSAGE: ${{ steps.handle-triage-status-transition.outputs.triage_message }}
TEST_EXIT: ${{ steps.test.outputs.exit_code }}
TEST_EXCERPT: ${{ steps.test.outputs.excerpt }}
with:
script: |
const owner = context.repo.owner;
const repo = context.repo.repo;
const issue_number = Number(process.env.ISSUE_NUMBER);
const command = process.env.COMMAND;
const runUrl = `${context.serverUrl}/${owner}/${repo}/actions/runs/${context.runId}`;
let body = `<!-- sirius-chatops-result -->\n## ChatOps Result\n\n- Command: \`${command}\`\n`;
if ("${{ steps.parse.outputs.kind }}" === "triage") {
body += `- Outcome: ${process.env.TRIAGE_MESSAGE || "No change was applied."}\n`;
} else if ("${{ steps.parse.outputs.kind }}" === "test") {
const code = Number(process.env.TEST_EXIT || "1");
body += `- Outcome: ${code === 0 ? "PASS" : "FAIL"} (exit ${code})\n`;
body += `- Run logs: ${runUrl}\n\n`;
body += "### Error/Result Excerpt\n";
body += "```text\n";
body += `${process.env.TEST_EXCERPT || "No excerpt captured."}\n`;
body += "```\n";
} else {
body += "- Outcome: Unsupported command.\n";
}
await github.rest.issues.createComment({
owner,
repo,
issue_number,
body,
});
.github/workflows/check-pin-consistency.yml
+108
View File
@@ -0,0 +1,108 @@
name: Check engine pin consistency
# Fails any PR that lets the sirius-engine submodule pins drift between
# Dockerfile defaults and the CI fallback build-args, or that introduces
# a floating ref (main / master / branch name) instead of a full SHA or
# version tag.
#
# See:
# - sirius-engine/Dockerfile (ARG ..._COMMIT_SHA defaults)
# - .github/workflows/ci.yml (build-engine / build-api build-args)
# - documentation/dev/architecture/README.engine-component-pinning.md
on:
pull_request:
paths:
- "sirius-engine/Dockerfile"
- ".github/workflows/ci.yml"
- ".github/workflows/check-pin-consistency.yml"
push:
branches: [main]
paths:
- "sirius-engine/Dockerfile"
- ".github/workflows/ci.yml"
- ".github/workflows/check-pin-consistency.yml"
workflow_dispatch:
jobs:
check-pins:
name: Dockerfile / CI pin consistency
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Verify pins agree and are not floating
shell: bash
run: |
set -euo pipefail
DOCKERFILE=sirius-engine/Dockerfile
CI=.github/workflows/ci.yml
# Components managed by the engine pin policy. Each entry is the
# ARG/env-var prefix as it appears in both files.
PINS=(GO_API APP_SCANNER APP_TERMINAL SIRIUS_NSE APP_AGENT PINGPP)
# Acceptable pin shape: a full 40-char SHA, OR a vX.Y.Z[-suffix] tag.
# Floating refs (main, master, HEAD, branch names) are rejected.
shape_ok() {
local v="$1"
if [[ "$v" =~ ^[0-9a-f]{40}$ ]]; then return 0; fi
if [[ "$v" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([-.][A-Za-z0-9.-]+)?$ ]]; then return 0; fi
return 1
}
fail=0
for prefix in "${PINS[@]}"; do
arg_name="${prefix}_COMMIT_SHA"
dockerfile_value="$(grep -E "^ARG[[:space:]]+${arg_name}=" "$DOCKERFILE" | head -1 | sed -E "s/^ARG[[:space:]]+${arg_name}=//")"
# CI fallback lives inside ${{ env.X || 'literal' }}. Pull the literal.
ci_value="$(grep -E "${arg_name}=\\\$\\{\\{[[:space:]]*env\\.${arg_name}" "$CI" | head -1 | sed -E "s/.*\\|\\|[[:space:]]*'([^']+)'.*/\\1/")"
if [ -z "$dockerfile_value" ]; then
echo "::error file=${DOCKERFILE}::${arg_name} has no ARG default"
fail=1
continue
fi
if [ -z "$ci_value" ]; then
echo "::error file=${CI}::${arg_name} has no CI build-args fallback"
fail=1
continue
fi
if ! shape_ok "$dockerfile_value"; then
echo "::error file=${DOCKERFILE}::${arg_name}=${dockerfile_value} is a floating ref or malformed pin (require full SHA or vX.Y.Z tag)"
fail=1
fi
if ! shape_ok "$ci_value"; then
echo "::error file=${CI}::${arg_name}=${ci_value} is a floating ref or malformed pin (require full SHA or vX.Y.Z tag)"
fail=1
fi
if [ "$dockerfile_value" != "$ci_value" ]; then
echo "::error::${arg_name} drift: Dockerfile=${dockerfile_value} CI=${ci_value}"
fail=1
else
echo "OK ${arg_name}=${dockerfile_value}"
fi
done
# Bonus: forbid `sed -i` blocks against minor-project source in
# the engine Dockerfile. Patches must be upstreamed.
if grep -nE "^[[:space:]]*sed[[:space:]]+-i" "$DOCKERFILE"; then
echo "::error file=${DOCKERFILE}::Inline sed patches against submodule source are forbidden. Upstream the change to the relevant minor-project and bump the pin instead."
fail=1
fi
if [ "$fail" -ne 0 ]; then
echo ""
echo "Pin consistency check failed. See documentation/dev/architecture/README.engine-component-pinning.md for the policy."
exit 1
fi
echo ""
echo "All engine pins are consistent and well-formed."
.github/workflows/ci-modernized.yml
+409
View File
@@ -0,0 +1,409 @@
name: Sirius CI/CD Pipeline (Reference Only)
# Triggers disabled — ci.yml is the canonical CI pipeline.
# This file is retained for reference; it never executes automatically.
on:
workflow_dispatch:
env:
REGISTRY: ghcr.io
IMAGE_NAMESPACE: siriusscan
jobs:
detect-changes:
name: Detect Changes
runs-on: ubuntu-latest
outputs:
sirius_ui_changes: ${{ steps.changes.outputs.sirius_ui_changes }}
sirius_api_changes: ${{ steps.changes.outputs.sirius_api_changes }}
sirius_engine_changes: ${{ steps.changes.outputs.sirius_engine_changes }}
documentation_changes: ${{ steps.changes.outputs.documentation_changes }}
docker_changes: ${{ steps.changes.outputs.docker_changes }}
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Determine Changed Files
id: changes
run: |
# For pull requests
if [ "${{ github.event_name }}" == "pull_request" ]; then
BASE_SHA=${{ github.event.pull_request.base.sha }}
HEAD_SHA=${{ github.event.pull_request.head.sha }}
else
# For push events
BASE_SHA=${{ github.event.before }}
HEAD_SHA=${{ github.event.after }}
fi
# Get changed files
git diff --name-only $BASE_SHA $HEAD_SHA > changed_files.txt
echo "Changed files:"
cat changed_files.txt
# Check for service-specific changes
if grep -q "sirius-ui/" changed_files.txt; then
echo "UI changes detected"
echo "sirius_ui_changes=true" >> $GITHUB_OUTPUT
fi
if grep -q "sirius-api/" changed_files.txt; then
echo "API changes detected"
echo "sirius_api_changes=true" >> $GITHUB_OUTPUT
fi
if grep -q "sirius-engine/" changed_files.txt; then
echo "Engine changes detected"
echo "sirius_engine_changes=true" >> $GITHUB_OUTPUT
fi
# Check for documentation changes
if grep -q "documentation/" changed_files.txt; then
echo "Documentation changes detected"
echo "documentation_changes=true" >> $GITHUB_OUTPUT
fi
# Check for Docker/CI changes
if grep -q -E "(Dockerfile|\.github/|docker-compose|scripts/)" changed_files.txt; then
echo "Docker or CI changes detected"
echo "docker_changes=true" >> $GITHUB_OUTPUT
# Docker changes affect all services
echo "sirius_ui_changes=true" >> $GITHUB_OUTPUT
echo "sirius_api_changes=true" >> $GITHUB_OUTPUT
echo "sirius_engine_changes=true" >> $GITHUB_OUTPUT
fi
# If no specific changes detected but we have changes, rebuild everything
if [ ! -s changed_files.txt ]; then
echo "General changes detected, rebuilding everything"
echo "sirius_ui_changes=true" >> $GITHUB_OUTPUT
echo "sirius_api_changes=true" >> $GITHUB_OUTPUT
echo "sirius_engine_changes=true" >> $GITHUB_OUTPUT
fi
quick-checks:
name: Quick Validation
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Validate Docker Compose Configurations
env:
SIRIUS_API_KEY: ci-placeholder-api-key
POSTGRES_PASSWORD: ci-postgres-password
NEXTAUTH_SECRET: ci-nextauth-secret
INITIAL_ADMIN_PASSWORD: ci-admin-password
run: |
echo "🔍 Validating Docker Compose configurations..."
docker compose config --quiet
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml config --quiet
docker compose -f docker-compose.yaml -f docker-compose.prod.yaml config --quiet
echo "✅ All Docker Compose configurations are valid"
- name: Validate Documentation
run: |
echo "📚 Validating documentation..."
cd testing/container-testing
make lint-docs-quick
make lint-index
echo "✅ Documentation validation passed"
build-and-push:
name: Build & Push Images
needs: [detect-changes, quick-checks]
runs-on: ubuntu-latest
if: github.event_name == 'push' && (needs.detect-changes.outputs.sirius_ui_changes == 'true' || needs.detect-changes.outputs.sirius_api_changes == 'true' || needs.detect-changes.outputs.sirius_engine_changes == 'true')
outputs:
image_tag: ${{ steps.meta.outputs.image_tag }}
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to Container Registry
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ secrets.GHCR_PUSH_USER }}
password: ${{ secrets.GHCR_PUSH_TOKEN }}
- name: Generate metadata
id: meta
run: |
# Set image tags based on event type
if [ "${{ github.event_name }}" == "pull_request" ]; then
TAG="pr-${{ github.event.number }}"
elif [ "${{ github.event_name }}" == "push" ] && [ "${{ github.ref }}" == "refs/heads/main" ]; then
TAG="latest"
echo "also_tag_beta=true" >> $GITHUB_OUTPUT
else
TAG="dev"
fi
echo "image_tag=$TAG" >> $GITHUB_OUTPUT
echo "Generated image tag: $TAG"
- name: Build and push sirius-ui
if: needs.detect-changes.outputs.sirius_ui_changes == 'true'
uses: docker/build-push-action@v6
with:
context: ./sirius-ui
platforms: ${{ github.event_name == 'pull_request' && 'linux/amd64' || 'linux/amd64,linux/arm64' }}
push: true
tags: |
${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-ui:${{ steps.meta.outputs.image_tag }}
${{ steps.meta.outputs.also_tag_beta == 'true' && format('{0}/{1}/sirius-ui:beta', env.REGISTRY, env.IMAGE_NAMESPACE) || '' }}
- name: Build and push sirius-api
if: needs.detect-changes.outputs.sirius_api_changes == 'true'
uses: docker/build-push-action@v6
with:
context: ./sirius-api
platforms: ${{ github.event_name == 'pull_request' && 'linux/amd64' || 'linux/amd64,linux/arm64' }}
push: true
tags: |
${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-api:${{ steps.meta.outputs.image_tag }}
${{ steps.meta.outputs.also_tag_beta == 'true' && format('{0}/{1}/sirius-api:beta', env.REGISTRY, env.IMAGE_NAMESPACE) || '' }}
- name: Build and push sirius-engine
if: needs.detect-changes.outputs.sirius_engine_changes == 'true'
uses: docker/build-push-action@v6
with:
context: ./sirius-engine
platforms: ${{ github.event_name == 'pull_request' && 'linux/amd64' || 'linux/amd64,linux/arm64' }}
push: true
tags: |
${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-engine:${{ steps.meta.outputs.image_tag }}
${{ steps.meta.outputs.also_tag_beta == 'true' && format('{0}/{1}/sirius-engine:beta', env.REGISTRY, env.IMAGE_NAMESPACE) || '' }}
integration-test:
name: Integration Testing
needs: [detect-changes, build-and-push]
runs-on: ubuntu-latest
if: needs.detect-changes.outputs.sirius_ui_changes == 'true' || needs.detect-changes.outputs.sirius_api_changes == 'true' || needs.detect-changes.outputs.sirius_engine_changes == 'true'
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to Container Registry
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ secrets.GHCR_PUSH_USER }}
password: ${{ secrets.GHCR_PUSH_TOKEN }}
- name: Create CI test environment
run: |
# Create test docker-compose configuration
cat > docker-compose.ci.yml << EOF
name: sirius-ci-test
services:
sirius-postgres:
image: postgres:15-alpine
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: sirius_test
tmpfs:
- /var/lib/postgresql/data # Use RAM for CI testing
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 5s
retries: 5
sirius-rabbitmq:
image: rabbitmq:3-management
environment:
RABBITMQ_DEFAULT_USER: guest
RABBITMQ_DEFAULT_PASS: guest
healthcheck:
test: ["CMD", "rabbitmq-diagnostics", "ping"]
interval: 5s
timeout: 5s
retries: 5
sirius-valkey:
image: valkey/valkey:latest
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 5s
retries: 5
sirius-ui:
image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-ui:${{ needs.build-and-push.outputs.image_tag }}
environment:
- NODE_ENV=production
- SKIP_ENV_VALIDATION=1
- DATABASE_URL=postgresql://postgres:postgres@sirius-postgres:5432/sirius_test
- NEXTAUTH_SECRET=test-secret-key
- INITIAL_ADMIN_PASSWORD=test-admin-password
- NEXTAUTH_URL=http://localhost:3000
- SIRIUS_API_URL=http://sirius-api:9001
- NEXT_PUBLIC_SIRIUS_API_URL=http://localhost:9001
- SIRIUS_API_KEY=ci-placeholder-api-key
depends_on:
sirius-postgres:
condition: service_healthy
healthcheck:
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/api/health"]
interval: 10s
timeout: 5s
retries: 3
sirius-api:
image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-api:${{ needs.build-and-push.outputs.image_tag }}
environment:
- GO_ENV=production
- API_PORT=9001
- POSTGRES_HOST=sirius-postgres
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=postgres
- POSTGRES_DB=sirius_test
- POSTGRES_PORT=5432
- VALKEY_HOST=sirius-valkey
- VALKEY_PORT=6379
- RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/
- LOG_LEVEL=info
- SIRIUS_API_KEY=ci-placeholder-api-key
depends_on:
sirius-postgres:
condition: service_healthy
sirius-rabbitmq:
condition: service_healthy
sirius-valkey:
condition: service_healthy
healthcheck:
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:9001/api/v1/health"]
interval: 10s
timeout: 5s
retries: 3
sirius-engine:
image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-engine:${{ needs.build-and-push.outputs.image_tag }}
environment:
- GO_ENV=production
- ENGINE_MAIN_PORT=5174
- GRPC_AGENT_PORT=50051
- POSTGRES_HOST=sirius-postgres
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=postgres
- POSTGRES_DB=sirius_test
- POSTGRES_PORT=5432
- VALKEY_HOST=sirius-valkey
- VALKEY_PORT=6379
- RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/
- LOG_LEVEL=info
- SIRIUS_API_KEY=ci-placeholder-api-key
depends_on:
sirius-postgres:
condition: service_healthy
sirius-rabbitmq:
condition: service_healthy
sirius-valkey:
condition: service_healthy
healthcheck:
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:5174/health"]
interval: 10s
timeout: 5s
retries: 3
EOF
- name: Run integration tests
run: |
echo "🧪 Starting integration tests..."
# Start infrastructure services
docker compose -f docker-compose.ci.yml up -d sirius-postgres sirius-rabbitmq sirius-valkey
# Wait for infrastructure services to all be healthy
echo "⏳ Waiting for infrastructure services to be healthy..."
timeout 90 bash -c 'until docker compose -f docker-compose.ci.yml ps | grep -q "sirius-postgres.*(healthy)" && docker compose -f docker-compose.ci.yml ps | grep -q "sirius-rabbitmq.*(healthy)" && docker compose -f docker-compose.ci.yml ps | grep -q "sirius-valkey.*(healthy)"; do sleep 2; done'
# Start application services based on what was built
SERVICES_TO_TEST=""
if [ "${{ needs.detect-changes.outputs.sirius_api_changes }}" == "true" ]; then
SERVICES_TO_TEST="$SERVICES_TO_TEST sirius-api"
fi
if [ "${{ needs.detect-changes.outputs.sirius_engine_changes }}" == "true" ]; then
SERVICES_TO_TEST="$SERVICES_TO_TEST sirius-engine"
fi
if [ "${{ needs.detect-changes.outputs.sirius_ui_changes }}" == "true" ]; then
SERVICES_TO_TEST="$SERVICES_TO_TEST sirius-ui"
fi
if [ -n "$SERVICES_TO_TEST" ]; then
echo "🚀 Starting application services: $SERVICES_TO_TEST"
docker compose -f docker-compose.ci.yml up -d $SERVICES_TO_TEST
# Wait only for the services started in this run by checking their
# health endpoints directly instead of container health state labels.
echo "⏳ Waiting for application services to become reachable..."
if echo "$SERVICES_TO_TEST" | grep -q "sirius-api"; then
timeout 180 bash -c 'until docker compose -f docker-compose.ci.yml exec -T sirius-api wget --no-verbose --tries=1 --spider http://localhost:9001/api/v1/health; do sleep 5; done'
fi
if echo "$SERVICES_TO_TEST" | grep -q "sirius-engine"; then
timeout 180 bash -c 'until docker compose -f docker-compose.ci.yml exec -T sirius-engine wget --no-verbose --tries=1 --spider http://localhost:5174/health; do sleep 5; done'
fi
if echo "$SERVICES_TO_TEST" | grep -q "sirius-ui"; then
timeout 180 bash -c 'until docker compose -f docker-compose.ci.yml exec -T sirius-ui wget --no-verbose --tries=1 --spider http://localhost:3000/api/health; do sleep 5; done'
fi
# Check service status
echo "📊 Service status:"
docker compose -f docker-compose.ci.yml ps
# Run health checks
echo "🏥 Running health checks..."
if echo "$SERVICES_TO_TEST" | grep -q "sirius-api"; then
echo "Testing sirius-api health..."
docker compose -f docker-compose.ci.yml exec -T sirius-api wget --no-verbose --tries=1 --spider http://localhost:9001/api/v1/health || exit 1
fi
if echo "$SERVICES_TO_TEST" | grep -q "sirius-engine"; then
echo "Testing sirius-engine health..."
docker compose -f docker-compose.ci.yml exec -T sirius-engine wget --no-verbose --tries=1 --spider http://localhost:5174/health || exit 1
fi
if echo "$SERVICES_TO_TEST" | grep -q "sirius-ui"; then
echo "Testing sirius-ui health..."
docker compose -f docker-compose.ci.yml exec -T sirius-ui wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1
fi
echo "✅ All health checks passed!"
else
echo "ℹ️ No application services to test"
fi
# Cleanup
echo "🧹 Cleaning up test environment..."
docker compose -f docker-compose.ci.yml down
deployment:
name: Production Deployment
needs: [detect-changes, build-and-push, integration-test]
runs-on: ubuntu-latest
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
environment: production
steps:
- name: Deploy to Production
run: |
echo "🚀 Deploying to production..."
echo "Image tag: ${{ needs.build-and-push.outputs.image_tag }}"
echo "✅ Deployment completed (placeholder)"
.github/workflows/ci.yml
+1066
View File
File diff suppressed because it is too large Load Diff
.github/workflows/deploy.yml
+183
View File
@@ -0,0 +1,183 @@
name: Deploy to Environment
# Deployment-only workflow. Images are built and published by ci.yml.
# This workflow handles environment-specific deployment configuration
# and manual promotion between environments.
#
# The push trigger has been removed. All image builds happen in ci.yml.
# Use workflow_dispatch to deploy a specific image tag to staging or production.
on:
workflow_dispatch:
inputs:
environment:
description: "Target environment"
required: true
default: "staging"
type: choice
options:
- staging
- production
image_tag:
description: "Image tag to deploy (e.g. latest, beta, v1.2.3)"
required: true
default: "latest"
force_deploy:
description: "Force deployment even if already at this tag"
required: false
default: false
type: boolean
env:
REGISTRY: ghcr.io
IMAGE_REGISTRY: ghcr.io/siriusscan
jobs:
# ─────────────────────────────────────────────────────────────────────────────
# Manual deployment to staging or production
# ─────────────────────────────────────────────────────────────────────────────
deploy-manual:
name: "Deploy to ${{ github.event.inputs.environment }}"
runs-on: ubuntu-latest
environment: ${{ github.event.inputs.environment }}
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Validate deployment inputs
run: |
echo "Environment: ${{ github.event.inputs.environment }}"
echo "Image Tag: ${{ github.event.inputs.image_tag }}"
echo "Force Deploy: ${{ github.event.inputs.force_deploy }}"
if [[ ! "${{ github.event.inputs.image_tag }}" =~ ^[a-zA-Z0-9._-]+$ ]]; then
echo "Invalid image tag format"
exit 1
fi
echo "Deployment inputs validated"
- name: Generate environment configuration
run: |
ENV="${{ github.event.inputs.environment }}"
TAG="${{ github.event.inputs.image_tag }}"
mkdir -p environments
case "$ENV" in
staging)
cat > environments/.env.staging << EOF
ENVIRONMENT=staging
NODE_ENV=staging
GO_ENV=staging
IMAGE_TAG=${TAG}
IMAGE_REGISTRY=${{ env.IMAGE_REGISTRY }}
POSTGRES_USER=sirius_staging
POSTGRES_PASSWORD=${{ secrets.STAGING_POSTGRES_PASSWORD }}
POSTGRES_DB=sirius_staging
POSTGRES_HOST=staging-postgres.internal
SIRIUS_API_URL=https://staging-api.sirius.company.com
NEXT_PUBLIC_SIRIUS_API_URL=https://staging-api.sirius.company.com
NEXTAUTH_SECRET=${{ secrets.STAGING_NEXTAUTH_SECRET }}
NEXTAUTH_URL=https://staging.sirius.company.com
LOG_LEVEL=debug
LOG_FORMAT=json
EOF
;;
production)
cat > environments/.env.production << EOF
ENVIRONMENT=production
NODE_ENV=production
GO_ENV=production
IMAGE_TAG=${TAG}
IMAGE_REGISTRY=${{ env.IMAGE_REGISTRY }}
POSTGRES_USER=sirius_prod
POSTGRES_PASSWORD=${{ secrets.PRODUCTION_POSTGRES_PASSWORD }}
POSTGRES_DB=sirius_production
POSTGRES_HOST=prod-postgres.internal
SIRIUS_API_URL=https://api.sirius.company.com
NEXT_PUBLIC_SIRIUS_API_URL=https://api.sirius.company.com
NEXTAUTH_SECRET=${{ secrets.PRODUCTION_NEXTAUTH_SECRET }}
NEXTAUTH_URL=https://sirius.company.com
LOG_LEVEL=info
LOG_FORMAT=json
TLS_ENABLED=true
EOF
;;
esac
echo "Environment configuration generated for $ENV"
- name: Deploy to ${{ github.event.inputs.environment }}
run: |
ENV="${{ github.event.inputs.environment }}"
TAG="${{ github.event.inputs.image_tag }}"
echo "Deploying to $ENV with image tag: $TAG"
if [[ -f "docker-compose.$ENV.yaml" ]]; then
echo "Found docker-compose.$ENV.yaml"
else
echo "Missing docker-compose.$ENV.yaml"
exit 1
fi
if [[ -f "environments/.env.$ENV" ]]; then
echo "Found environments/.env.$ENV"
else
echo "Missing environments/.env.$ENV"
exit 1
fi
echo "Deployment validation completed"
echo "$ENV deployment successful with tag: $TAG"
- name: Post-deployment notification
if: success()
run: |
echo "Deployment to ${{ github.event.inputs.environment }} completed successfully"
echo "Image tag: ${{ github.event.inputs.image_tag }}"
# ─────────────────────────────────────────────────────────────────────────────
# Security scan runs only for production deployments
# ─────────────────────────────────────────────────────────────────────────────
security-scan:
name: Security Scan
runs-on: ubuntu-latest
if: github.event.inputs.environment == 'production'
needs: deploy-manual
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Run security scan
run: |
echo "Running security scan for production deployment..."
echo "Security scan completed - no critical vulnerabilities found"
# ─────────────────────────────────────────────────────────────────────────────
# Rollback on deployment failure
# ─────────────────────────────────────────────────────────────────────────────
rollback:
name: Rollback
runs-on: ubuntu-latest
if: failure()
needs: [deploy-manual]
environment: ${{ github.event.inputs.environment }}
steps:
- name: Rollback deployment
run: |
echo "Rolling back deployment to ${{ github.event.inputs.environment }}"
echo "Rollback completed"
.github/workflows/issue-triage.yml
+197
View File
@@ -0,0 +1,197 @@
name: Issue Triage
on:
issues:
types: [opened, edited]
permissions:
contents: read
issues: write
jobs:
triage:
name: Deterministic issue triage
runs-on: ubuntu-latest
steps:
- name: Apply labels and publish triage card
uses: actions/github-script@v7
with:
script: |
const issue = context.payload.issue;
const issueNumber = issue.number;
const owner = context.repo.owner;
const repo = context.repo.repo;
const text = `${issue.title}\n${issue.body || ""}`.toLowerCase();
const statusLabels = new Set([
"status:needs-triage",
"status:needs-info",
"status:repro-ready",
"status:confirmed",
"status:in-progress",
"status:blocked",
"status:ready-to-merge",
"status:done",
]);
const nextLabels = new Set();
const reasons = [];
// Type classification
if (/(security|vulnerability|cve|hardening|auth bypass|cors)/.test(text)) {
nextLabels.add("type:security");
reasons.push("Detected security-oriented keywords.");
} else if (/(question|how do i|help|clarify)/.test(text)) {
nextLabels.add("type:question");
reasons.push("Detected question/support language.");
} else if (/(docs|documentation|readme|guide)/.test(text)) {
nextLabels.add("type:docs");
reasons.push("Detected documentation-related language.");
} else if (/(feature|enhancement|improve|request)/.test(text)) {
nextLabels.add("type:enhancement");
reasons.push("Detected enhancement/request language.");
} else {
nextLabels.add("type:bug");
reasons.push("Defaulted to bug classification.");
}
// Area classification
if (/(sirius_api_key|x-api-key|401|auth|nextauth|jwt|session)/.test(text)) {
nextLabels.add("area:auth");
reasons.push("Matched auth/API-key indicators.");
}
if (/(installer|startup|secret|nextauth_secret|initial_admin_password|postgres_password)/.test(text)) {
nextLabels.add("area:installer-secrets");
reasons.push("Matched installer/startup secret indicators.");
}
if (/(docker-compose\.dev|dev overlay|volume mount|mount shadow|prisma)/.test(text)) {
nextLabels.add("area:compose-dev");
reasons.push("Matched dev-overlay/compose indicators.");
}
if (/(docker-compose\.prod|production overlay|hardened production)/.test(text)) {
nextLabels.add("area:compose-prod");
reasons.push("Matched production overlay indicators.");
}
if (/(ui|frontend|next\.js|trpc|browser)/.test(text)) nextLabels.add("area:ui");
if (/(api|fiber|endpoint|rest)/.test(text)) nextLabels.add("area:api");
if (/(engine|scanner|grpc|agent)/.test(text)) nextLabels.add("area:engine");
if (/(rabbitmq|queue|amqp)/.test(text)) nextLabels.add("area:rabbitmq");
if (/(postgres|database|migration|prisma schema)/.test(text)) nextLabels.add("area:postgres");
if (/(valkey|redis|cache)/.test(text)) nextLabels.add("area:valkey");
if (/(windows|wsl|crlf)/.test(text)) nextLabels.add("platform:windows");
// Severity hint
if (/(critical|auth bypass|remote code execution|data loss|privilege escalation)/.test(text)) {
nextLabels.add("sev:critical");
} else if (/(stack won't boot|cannot start|service down|outage|unusable|401 everywhere)/.test(text)) {
nextLabels.add("sev:high");
} else if (/(intermittent|major|fails often)/.test(text)) {
nextLabels.add("sev:medium");
} else {
nextLabels.add("sev:low");
}
// Missing info checks for fast mobile triage
const missing = [];
if (!/(repro|steps to reproduce|reproduction)/.test(text)) {
missing.push("Reproduction steps");
}
if (!/(docker compose logs|logs --no-color|stack trace|error:)/.test(text)) {
missing.push("Relevant service logs");
}
if (!/(docker compose config --quiet|installer|sirius-installer)/.test(text)) {
missing.push("Installer/config-render validation evidence");
}
if (missing.length > 0) {
nextLabels.add("status:needs-info");
reasons.push("Missing diagnostics were detected.");
} else {
nextLabels.add("status:repro-ready");
reasons.push("Sufficient diagnostics detected for reproduction.");
}
// Remove existing status labels to keep lifecycle single-valued
for (const label of issue.labels.map((l) => l.name)) {
if (statusLabels.has(label) && !nextLabels.has(label)) {
try {
await github.rest.issues.removeLabel({
owner,
repo,
issue_number: issueNumber,
name: label,
});
} catch (error) {
core.warning(`Could not remove label ${label}: ${error.message}`);
}
}
}
// Add computed labels
const labelsToAdd = [...nextLabels];
if (labelsToAdd.length > 0) {
await github.rest.issues.addLabels({
owner,
repo,
issue_number: issueNumber,
labels: labelsToAdd,
});
}
const triageMarker = "<!-- sirius-triage-card -->";
const missingBlock = missing.length
? missing.map((m) => `- [ ] ${m}`).join("\n")
: "- [x] Issue includes baseline diagnostics.";
const body = `${triageMarker}
## Triage Card
**Summary**
- Type: ${[...nextLabels].find((l) => l.startsWith("type:")) || "not-set"}
- Areas: ${[...nextLabels].filter((l) => l.startsWith("area:") || l.startsWith("platform:")).join(", ") || "not-set"}
- Severity hint: ${[...nextLabels].find((l) => l.startsWith("sev:")) || "not-set"}
- Status: ${[...nextLabels].find((l) => l.startsWith("status:")) || "not-set"}
**Why this classification**
${reasons.map((r) => `- ${r}`).join("\n")}
**Missing info checklist**
${missingBlock}
**Relevant runbooks**
- API Key Operations: \`documentation/dev/operations/README.api-key-operations.md\`
- Startup/Secrets ADR: \`documentation/dev/architecture/ADR.startup-secrets-model.md\`
- Auth Surface Matrix: \`documentation/dev/architecture/README.auth-surface-matrix.md\`
**Maintainer mobile commands**
- \`/triage needs-info\`
- \`/triage repro-ready\`
- \`/triage confirmed\`
- \`/test health\`
- \`/test integration\`
- \`/test security auth-surface\`
`;
const comments = await github.paginate(github.rest.issues.listComments, {
owner,
repo,
issue_number: issueNumber,
per_page: 100,
});
const existing = comments.find((c) => c.body && c.body.includes(triageMarker));
if (existing) {
await github.rest.issues.updateComment({
owner,
repo,
comment_id: existing.id,
body,
});
} else {
await github.rest.issues.createComment({
owner,
repo,
issue_number: issueNumber,
body,
});
}
.github/workflows/pr-labeler.yml
+19
View File
@@ -0,0 +1,19 @@
name: PR Labeler
on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
permissions:
contents: read
pull-requests: write
jobs:
label:
name: Apply path-based labels
runs-on: ubuntu-latest
steps:
- name: Label PR by changed files
uses: actions/labeler@v5
with:
repo-token: "${{ secrets.GITHUB_TOKEN }}"
.github/workflows/pr-review-card.yml
+123
View File
@@ -0,0 +1,123 @@
name: PR Review Card
on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
permissions:
contents: read
pull-requests: write
issues: write
jobs:
review-card:
name: Publish review card
runs-on: ubuntu-latest
steps:
- name: Build and post review card
uses: actions/github-script@v7
with:
script: |
const owner = context.repo.owner;
const repo = context.repo.repo;
const pull_number = context.payload.pull_request.number;
const marker = "<!-- sirius-pr-review-card -->";
const files = await github.paginate(github.rest.pulls.listFiles, {
owner,
repo,
pull_number,
per_page: 100,
});
const paths = files.map((f) => f.filename);
const changed = new Set();
const risks = [];
const requiredTests = new Set();
const has = (pattern) => paths.some((p) => pattern.test(p));
if (has(/^sirius-ui\//)) {
changed.add("area:ui");
requiredTests.add("Frontend checklist (visual + functional + container checks)");
}
if (has(/^sirius-api\//)) {
changed.add("area:api");
requiredTests.add("Backend API checklist (endpoint, validation, auth checks)");
}
if (has(/^sirius-engine\//)) {
changed.add("area:engine");
requiredTests.add("Docker/container + integration checklist");
}
if (has(/^documentation\//) || has(/^README\.md$/)) {
changed.add("type:docs");
requiredTests.add("Documentation checklist (`lint-docs`, `lint-index`)");
}
if (has(/docker-compose|Dockerfile|\.github\/workflows/)) {
changed.add("area:compose-prod");
requiredTests.add("Container/Docker checklist (`test-build`, `test-health`, `test-integration`)");
risks.push("Runtime/startup contract changed (compose/workflow/dockerfile touched).");
}
if (has(/auth|apikey|nextauth|README\.auth-surface-matrix\.md|README\.api-key-operations\.md/i)) {
changed.add("area:auth");
requiredTests.add("Authentication checklist + `security auth-surface` suite");
risks.push("Auth surface touched; require explicit auth regression evidence.");
}
if (has(/prisma|migration|sirius-postgres/i)) {
changed.add("area:postgres");
requiredTests.add("Database schema/migration checklist");
risks.push("Persistence layer changed; validate migrations and rollback safety.");
}
if (has(/rabbitmq|queue|amqp/i)) {
changed.add("area:rabbitmq");
requiredTests.add("Integration + queue behavior validation");
}
if (risks.length === 0) {
risks.push("No high-risk patterns detected by automation.");
}
const body = `${marker}
## PR Review Card
**Changed surfaces**
${[...changed].length ? [...changed].map((c) => `- ${c}`).join("\n") : "- none detected"}
**Risk flags**
${risks.map((r) => `- ${r}`).join("\n")}
**Required testing evidence**
${[...requiredTests].length ? [...requiredTests].map((t) => `- [ ] ${t}`).join("\n") : "- [ ] General smoke + health evidence"}
**Reference checklist**
- \`documentation/dev/test/CHECKLIST.testing-by-type.md\`
**Maintainer commands**
- \`/test health\`
- \`/test integration\`
- \`/test security auth-surface\`
`;
const comments = await github.paginate(github.rest.issues.listComments, {
owner,
repo,
issue_number: pull_number,
per_page: 100,
});
const existing = comments.find((c) => c.body && c.body.includes(marker));
if (existing) {
await github.rest.issues.updateComment({
owner,
repo,
comment_id: existing.id,
body,
});
} else {
await github.rest.issues.createComment({
owner,
repo,
issue_number: pull_number,
body,
});
}
.github/workflows/pr-size-labeler.yml
+28
View File
@@ -0,0 +1,28 @@
name: PR Size Labeler
on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
permissions:
contents: read
pull-requests: write
jobs:
size:
name: Apply size label
runs-on: ubuntu-latest
steps:
- name: Apply PR size label
uses: pascalgn/size-label-action@v0.5.5
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
XS_MAX_SIZE: "25"
S_MAX_SIZE: "99"
M_MAX_SIZE: "299"
L_MAX_SIZE: "699"
XL_MAX_SIZE: "1499"
FAIL_IF_XL: "false"
IGNORE_FILE_PATTERNS: |
*.lock
*.snap
.github/workflows/publish-release-image-tags.yml
+150
View File
@@ -0,0 +1,150 @@
name: Publish Release Image Tags
on:
workflow_dispatch:
inputs:
source_tag:
description: "Existing source image tag (e.g. latest)"
required: true
default: "latest"
target_tag:
description: "Release image tag to publish (e.g. v1.0.0)"
required: true
default: "v1.0.0"
env:
GHCR_OWNER: SiriusScan
REGISTRY: ghcr.io
IMAGE_NAMESPACE: siriusscan
jobs:
retag-and-publish:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to GHCR
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ secrets.GHCR_PUSH_USER }}
password: ${{ secrets.GHCR_PUSH_TOKEN }}
- name: Verify source manifests exist for all components
run: |
set -euo pipefail
verify_source_manifest() {
local component="$1"
local source_ref="${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/${component}:${{ github.event.inputs.source_tag }}"
echo "Checking source manifest: ${source_ref}"
docker buildx imagetools inspect "${source_ref}" > /dev/null
}
verify_source_manifest sirius-ui
verify_source_manifest sirius-api
verify_source_manifest sirius-engine
verify_source_manifest sirius-postgres
verify_source_manifest sirius-rabbitmq
verify_source_manifest sirius-valkey
- name: Publish sirius-ui release tag
run: |
docker buildx imagetools create \
-t "${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-ui:${{ github.event.inputs.target_tag }}" \
"${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-ui:${{ github.event.inputs.source_tag }}"
- name: Publish sirius-api release tag
run: |
docker buildx imagetools create \
-t "${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-api:${{ github.event.inputs.target_tag }}" \
"${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-api:${{ github.event.inputs.source_tag }}"
- name: Publish sirius-engine release tag
run: |
docker buildx imagetools create \
-t "${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-engine:${{ github.event.inputs.target_tag }}" \
"${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-engine:${{ github.event.inputs.source_tag }}"
- name: Publish sirius-postgres release tag
run: |
docker buildx imagetools create \
-t "${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-postgres:${{ github.event.inputs.target_tag }}" \
"${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-postgres:${{ github.event.inputs.source_tag }}"
- name: Publish sirius-rabbitmq release tag
run: |
docker buildx imagetools create \
-t "${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-rabbitmq:${{ github.event.inputs.target_tag }}" \
"${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-rabbitmq:${{ github.event.inputs.source_tag }}"
- name: Publish sirius-valkey release tag
run: |
docker buildx imagetools create \
-t "${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-valkey:${{ github.event.inputs.target_tag }}" \
"${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-valkey:${{ github.event.inputs.source_tag }}"
- name: Verify published manifests
run: |
docker manifest inspect "${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-ui:${{ github.event.inputs.target_tag }}" > /dev/null
docker manifest inspect "${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-api:${{ github.event.inputs.target_tag }}" > /dev/null
docker manifest inspect "${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-engine:${{ github.event.inputs.target_tag }}" > /dev/null
docker manifest inspect "${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-postgres:${{ github.event.inputs.target_tag }}" > /dev/null
docker manifest inspect "${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-rabbitmq:${{ github.event.inputs.target_tag }}" > /dev/null
docker manifest inspect "${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-valkey:${{ github.event.inputs.target_tag }}" > /dev/null
echo "Published release image tags: ${{ github.event.inputs.target_tag }}"
- name: Verify source and release digest parity
run: |
set -euo pipefail
verify_digest() {
local component="$1"
local source_ref="${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/${component}:${{ github.event.inputs.source_tag }}"
local target_ref="${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/${component}:${{ github.event.inputs.target_tag }}"
local source_digest
local target_digest
# Human-readable output no longer has a stable "^Digest:" line; use JSON index digest.
source_digest=$(docker buildx imagetools inspect "$source_ref" --format '{{json .}}' | jq -r '.manifest.digest')
target_digest=$(docker buildx imagetools inspect "$target_ref" --format '{{json .}}' | jq -r '.manifest.digest')
echo "${component} source digest: ${source_digest}"
echo "${component} target digest: ${target_digest}"
if [ -z "$source_digest" ] || [ -z "$target_digest" ] || [ "$source_digest" != "$target_digest" ]; then
echo "Digest verification failed for ${component}" >&2
exit 1
fi
}
verify_digest sirius-ui
verify_digest sirius-api
verify_digest sirius-engine
verify_digest sirius-postgres
verify_digest sirius-rabbitmq
verify_digest sirius-valkey
- name: Verify anonymous access for release tag
run: |
bash scripts/verify-ghcr-public-access.sh "${{ github.event.inputs.target_tag }}"
validate-public-release-stack:
needs: retag-and-publish
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Smoke-test published public compose path
run: |
bash scripts/validate-public-compose-path.sh "${{ github.event.inputs.target_tag }}"
.github/workflows/slash-command-dispatch.yml
+65
View File
@@ -0,0 +1,65 @@
name: Slash Command Dispatch
on:
issue_comment:
types: [created]
permissions:
contents: write
issues: read
pull-requests: read
jobs:
dispatch:
name: Dispatch chatops command
runs-on: ubuntu-latest
if: >
github.event.issue.pull_request || !github.event.issue.pull_request
steps:
- name: Validate and dispatch
uses: actions/github-script@v7
with:
script: |
const commentBody = (context.payload.comment.body || "").trim();
const assoc = context.payload.comment.author_association || "";
const allowedAssociations = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
if (!commentBody.startsWith("/")) {
core.info("Not a slash command, skipping.");
return;
}
if (!allowedAssociations.has(assoc)) {
core.info(`Ignoring slash command from association: ${assoc}`);
return;
}
const isSupported =
commentBody.startsWith("/triage ") ||
commentBody === "/triage" ||
commentBody.startsWith("/test ");
if (!isSupported) {
core.info(`Unsupported slash command: ${commentBody}`);
return;
}
const issueNumber = context.payload.issue.number;
const isPr = !!context.payload.issue.pull_request;
const prNumber = isPr ? issueNumber : null;
await github.request("POST /repos/{owner}/{repo}/dispatches", {
owner: context.repo.owner,
repo: context.repo.repo,
event_type: "chatops-command",
client_payload: {
command: commentBody,
issue_number: issueNumber,
pr_number: prNumber,
is_pr: isPr,
comment_id: context.payload.comment.id,
actor: context.actor,
},
});
core.info(`Dispatched chatops command: ${commentBody}`);
.github/workflows/stale.yml
+43
View File
@@ -0,0 +1,43 @@
name: Stale Issue and PR Hygiene
on:
schedule:
- cron: "30 4 * * *"
workflow_dispatch:
permissions:
issues: write
pull-requests: write
jobs:
stale:
name: Mark stale issues and PRs
runs-on: ubuntu-latest
steps:
- name: Process stale issues and PRs
uses: actions/stale@v9
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
stale-issue-message: >
This issue has had no activity for 60 days and is now marked stale.
If this is still relevant, add an update and we will keep it open.
close-issue-message: >
Closing this issue due to inactivity.
Comment with updated context to reopen if work is still needed.
stale-pr-message: >
This pull request has had no activity for 60 days and is now marked stale.
Please push updates or comment if it should remain open.
close-pr-message: >
Closing this pull request due to inactivity.
Reopen or open a new PR when updates are ready.
days-before-issue-stale: 60
days-before-issue-close: 14
days-before-pr-stale: 60
days-before-pr-close: 14
exempt-issue-labels: "type:security,sev:critical,status:blocked"
exempt-pr-labels: "type:security,sev:critical,status:blocked"
exempt-all-milestones: true
stale-issue-label: "status:needs-info"
stale-pr-label: "status:needs-info"
close-issue-label: "status:done"
close-pr-label: "status:done"
.github/workflows/validate-docker-config.yml
+93
View File
@@ -0,0 +1,93 @@
name: Validate Docker Configuration
on:
pull_request:
paths:
- "docker-compose*.yaml"
- ".github/workflows/validate-docker-config.yml"
push:
branches: [main, develop]
paths:
- "docker-compose*.yaml"
- ".github/workflows/validate-docker-config.yml"
jobs:
validate-docker-config:
name: Validate Docker Compose Configuration
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Validate docker-compose.override.yaml
run: |
echo "🔍 Validating docker-compose.override.yaml configuration..."
# Check if volume mounts in sirius-engine are commented out
if grep -E "^\s*-\s+\.\./minor-projects/" docker-compose.override.yaml; then
echo "❌ FAIL: Volume mounts are uncommented in docker-compose.override.yaml"
echo "Found uncommented volume mounts:"
grep -E "^\s*-\s+\.\./minor-projects/" docker-compose.override.yaml
echo ""
echo "💡 These should be commented out with '#' to prevent accidental commits"
echo "💡 Use docker-compose.local.yaml for local development overrides"
exit 1
fi
# Check that the commented examples exist
if ! grep -E "^\s*#\s*-\s+\.\./minor-projects/" docker-compose.override.yaml; then
echo "⚠️ WARNING: No commented volume mount examples found"
echo "💡 Consider adding commented examples for developer reference"
fi
echo "✅ docker-compose.override.yaml validation passed"
- name: Validate no local files committed
run: |
echo "🔍 Checking for accidentally committed local files..."
# Check if any local override files were committed
if [ -f "docker-compose.local.yaml" ]; then
echo "❌ FAIL: docker-compose.local.yaml should not be committed"
echo "💡 This file is for local development only and should be git-ignored"
exit 1
fi
# Check for any other local override patterns
if ls docker-compose.*.local.yaml 2>/dev/null; then
echo "❌ FAIL: Local docker-compose files found:"
ls docker-compose.*.local.yaml
echo "💡 These files should be git-ignored"
exit 1
fi
echo "✅ No local override files found in repository"
- name: Validate no outdated template files
run: |
echo "🔍 Checking for outdated template files..."
# Check for old template files that should not exist
if [ -f "docker-compose.local.example.yaml" ]; then
echo "❌ FAIL: docker-compose.local.example.yaml is an outdated template"
echo "💡 This file is from an old implementation and should be removed"
exit 1
fi
echo "✅ No outdated template files found"
- name: Summary
if: success()
run: |
echo "🎉 All Docker configuration validations passed!"
echo ""
echo "📋 What was validated:"
echo " ✅ Volume mounts are properly commented in docker-compose.override.yaml"
echo " ✅ No local override files accidentally committed"
echo " ✅ No outdated template files found"
echo ""
echo "💡 For local development, developers should:"
echo " 1. Run './scripts/dev-setup.sh init' to create local overrides"
echo " 2. Edit docker-compose.local.yaml (git-ignored) for their needs"
echo " 3. Use './scripts/dev-setup.sh start-extended' for extended development"
.github/workflows/verify-ghcr-release-tag.yml
+56
View File
@@ -0,0 +1,56 @@
# Verifies that the GitHub Release tag has matching, anonymously pullable images
# for all six GHCR packages used by docker-compose.yaml. Complements ci.yml, which
# only validates the public compose path for `latest` on main pushes.
name: Verify GHCR Release Tag
on:
release:
types: [published]
workflow_dispatch:
inputs:
image_tag:
description: "Image tag to verify (e.g. v1.0.0). Leave empty to resolve the latest GitHub release tag."
required: false
default: ""
schedule:
# Weekly: catch drift between GitHub Releases and GHCR semver tags
- cron: "0 12 * * 1"
permissions:
contents: read
jobs:
verify-anonymous-ghcr:
name: Anonymous GHCR manifest check
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Resolve image tag
id: tag
env:
GH_TOKEN: ${{ github.token }}
run: |
set -euo pipefail
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
MANUAL="${{ inputs.image_tag }}"
if [ -n "${MANUAL}" ]; then
echo "tag=${MANUAL}" >> "$GITHUB_OUTPUT"
echo "Resolved tag (manual): ${MANUAL}"
exit 0
fi
fi
if [ "${{ github.event_name }}" = "release" ]; then
TAG="${{ github.event.release.tag_name }}"
echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
echo "Resolved tag (release event): ${TAG}"
exit 0
fi
TAG=$(gh api "repos/${GITHUB_REPOSITORY}/releases/latest" --jq '.tag_name')
echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
echo "Resolved tag (latest GitHub release): ${TAG}"
- name: Verify anonymous GHCR access (compose-rendered refs)
run: |
bash scripts/verify-ghcr-public-access.sh "${{ steps.tag.outputs.tag }}"
.github/workflows/welcome-first-time.yml
+29
View File
@@ -0,0 +1,29 @@
name: Welcome First-Time Contributors
on:
issues:
types: [opened]
pull_request_target:
types: [opened]
permissions:
issues: write
pull-requests: write
jobs:
welcome:
name: Welcome contributors
runs-on: ubuntu-latest
steps:
- name: Post welcome message
uses: actions/first-interaction@v2
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
issue-message: |
Thanks for opening your first issue in Sirius Scan.
Please include as much diagnostic detail as possible so maintainers can triage quickly.
You can also use Discussions for questions and design proposals.
pr-message: |
Thanks for your first pull request to Sirius Scan.
Please complete the PR template checklist and include validation evidence.
A maintainer will review as soon as possible.
.gitignore
+76
View File
@@ -0,0 +1,76 @@
# Binaries and executables
*.exe
*.exe~
*.dll
*.so
*.dylib
system-monitor
sirius-api/sirius-api
administrator
air
test-build
# Temporary files
*.tmp
*.temp
*.log
*.swp
*.swo
*~
tmp/
.playwright-mcp/
# OS generated files
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db
# IDE files
.vscode/
.idea/
*.sublime-project
*.sublime-workspace
# Node modules
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Build outputs
dist/
build/
.next/
out/
# Environment files
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
# Local installer-generated secrets (keep directory, ignore contents)
secrets/*
!secrets/.gitkeep
*.secrets
# Database files
*.db
*.sqlite
*.sqlite3
# Go specific
*.test
*.prof
vendor/
# Docker
.dockerignore
# Server template repos
/var/sirius/template-repos/
sirius-engine/custom-templates/
CHANGELOG.md
+129
View File
@@ -0,0 +1,129 @@
# Changelog
All notable changes to SiriusScan will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- Installer-first startup workflow under `installer/` with interactive and non-interactive configuration generation.
- Optional deployment hardening overlays: `docker-compose.secrets.yaml` and `docker-stack.swarm.yaml`.
- Architecture decision record documenting stateless root key auth model.
### Changed
- Installer startup now uses `docker-compose.installer.yaml` as the canonical entrypoint.
- Root compose and overlays now require security-critical startup variables (`SIRIUS_API_KEY`, `POSTGRES_PASSWORD`, `NEXTAUTH_SECRET`, `INITIAL_ADMIN_PASSWORD`).
- UI startup scripts enforce required auth/seed variables before migrations and seeding.
- API middleware now marks explicit auth mode (`infra_env` vs `valkey`) and uses constant-time root key comparison.
- Documentation updated for installer-first setup and stateless root-key lifecycle operations.
### Fixed
- UI production image build compatibility with stricter secret validation during build stage.
- Integration test expectation for protected API error handling under API-key middleware.
### Migration Notes
- Replace manual `.env` copying with installer:
1. `docker compose -f docker-compose.installer.yaml run --rm sirius-installer`
2. `docker compose up -d` (or include prod/dev overlays)
- Ensure these variables are present for startup:
- `SIRIUS_API_KEY`
- `POSTGRES_PASSWORD`
- `NEXTAUTH_SECRET`
- `INITIAL_ADMIN_PASSWORD`
- Existing `.env` values are preserved by default; use `docker compose -f docker-compose.installer.yaml run --rm sirius-installer --force` when rotating/re-generating secrets.
## [1.0.0] - 2026-02-17
### Added
- Production API key support across services, including new API key management endpoints and shared SDK updates.
- Expanded scanner, host, and vulnerability capabilities in both API and UI, including new workflows and richer data presentation.
- Security testing suite under `testing/security` to validate API surface, headers, auth pathways, and service protections.
### Changed
- CI/CD workflows were stabilized for release reliability, including improved build and integration behavior for pull requests.
- Docker deployment configuration was updated with production overrides and safer validation defaults for CI checks.
- Documentation coverage expanded significantly across architecture, operations, and scanner internals.
### Removed
- Legacy development artifacts and deprecated UI/router files used only for earlier prototyping phases.
### Fixed
- Multiple release-blocking issues in image publishing, dependency pinning, and integration test orchestration.
- Documentation linting script behavior in CI environments.
## [0.4.0] - 2025-10-11
### Added
- **System Monitoring Dashboard**: Complete real-time monitoring system with service health checks and centralized logging
- **Centralized Logging Infrastructure**: Valkey-based logging system with log submission, retrieval, and management APIs
- **Real-time Service Health Monitoring**: Comprehensive health checks for all microservices (UI, API, Engine, PostgreSQL, Valkey, RabbitMQ)
- **System Resource Monitoring**: Real container metrics collection with CPU, memory, disk, and network monitoring
- **Advanced Log Viewer**: TanStack Table-based log viewer with filtering, search, and real-time updates
- **System Monitor Binary**: Lightweight Go binary for collecting and reporting system metrics from each container
- **Log Retention Policies**: Automatic cleanup with configurable retention (24 hours for metrics, 7 days for logs)
- **Performance Optimization**: Efficient polling, pagination, and memory management for large datasets
### Enhanced
- **Container Build System**: Improved Docker builds with proper Go module management and production-ready configurations
- **API Health Endpoints**: Enhanced `/health` endpoint with comprehensive system health information
- **Frontend Performance**: Optimized React components with memoization and efficient state management
- **Error Handling**: Comprehensive error handling and retry logic throughout the monitoring system
- **User Experience**: Improved UI/UX with loading states, error indicators, and responsive design
### Fixed
- **Go Module Dependencies**: Resolved version conflicts between sirius-api, go-api, and app-scanner modules
- **Container Build Issues**: Fixed missing go.sum entries and production build configurations
- **RabbitMQ Connectivity**: Corrected health check patterns for reliable service monitoring
- **SSH Access Configuration**: Added proper SSH troubleshooting capability for demo deployments
- **CI/CD Pipeline**: Fixed GitHub Actions workflows for automated demo deployments
### Technical Improvements
- **Multi-stage Docker Builds**: Optimized container images with separate build and runtime stages
- **Production Go Modules**: Proper separation of development and production go.mod files
- **Automated Testing**: Enhanced container testing suite with health checks and integration tests
- **Infrastructure as Code**: Improved Terraform configurations with SSH access and proper networking
- **Documentation**: Comprehensive documentation for system monitoring features and troubleshooting
### Security
- **SSH Key Management**: Secure SSH access configuration for troubleshooting and maintenance
- **Container Security**: Improved container security with proper user permissions and minimal attack surface
- **Access Control**: Enhanced security group configurations with proper CIDR restrictions
## [0.3.2] - Previous Release
### Added
- Basic vulnerability scanning capabilities
- Docker-based deployment system
- Web-based user interface
- PostgreSQL database integration
- RabbitMQ message queue system
- Valkey caching layer
---
## Release Notes
### v0.4.0 - System Monitoring & Observability
This major release introduces comprehensive system monitoring and observability capabilities to SiriusScan. The new monitoring dashboard provides real-time insights into system health, performance metrics, and centralized logging.
**Key Features:**
- **Real-time Monitoring**: Live health checks and system metrics
- **Centralized Logging**: Unified log collection and management
- **Performance Tracking**: Container resource utilization monitoring
- **Troubleshooting Tools**: Enhanced debugging and diagnostic capabilities
**Breaking Changes:** None
**Migration Guide:** No migration required. The monitoring features are additive and don't affect existing functionality.
**Upgrade Instructions:**
1. Pull the latest changes: `git pull origin main`
2. Rebuild containers: `docker compose down && docker compose up -d --build`
3. Access the new monitoring dashboard at `/system-monitor`
**Known Issues:** None
**Contributors:** Development Team
CODE_OF_CONDUCT.md
+123
View File
@@ -0,0 +1,123 @@
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and maintainers pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
- Demonstrating empathy and kindness toward other people
- Being respectful of differing opinions, viewpoints, and experiences
- Giving and gracefully accepting constructive feedback
- Accepting responsibility and apologizing to those affected by our mistakes
- Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
- The use of sexualized language or imagery, and sexual attention or
advances of any kind
- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or email
address, without their explicit permission
- Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official email address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
`conduct@opensecurity.com`.
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.1, available at
<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).
[homepage]: https://www.contributor-covenant.org
CONTRIBUTING.md
+120
View File
@@ -0,0 +1,120 @@
# Contributing to Sirius Scan
Thanks for your interest in contributing to Sirius Scan.
This file defines the repository-level contribution contract. For full environment and architecture details, use the extended guide in [`documentation/contributing.md`](./documentation/contributing.md).
## Communication Channels
- Bugs and feature requests: <https://github.com/SiriusScan/Sirius/issues>
- Questions and proposals: <https://github.com/SiriusScan/Sirius/discussions>
- Security reports: follow [`SECURITY.md`](./SECURITY.md) (private reporting only)
## Contribution Types
We welcome:
- Bug fixes
- Reliability and performance improvements
- Security hardening
- Documentation improvements
- Tests and automation improvements
## Development Setup
1. Fork the repository
2. Clone your fork
3. Start environment with installer-first flow:
```bash
git clone https://github.com/<your-user>/Sirius.git
cd Sirius
docker compose -f docker-compose.installer.yaml run --rm sirius-installer
docker compose up -d
```
For advanced local development or explicit source builds:
```bash
docker compose -f docker-compose.yaml -f docker-compose.build.yaml up -d --build
```
For live development:
```bash
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d --build
```
For more setup options, follow [`documentation/contributing.md`](./documentation/contributing.md).
### Windows Development
Sirius targets Linux containers. On Windows only **Docker Desktop** is required to clone, build, and run the full stack via `docker compose`.
- The repository ships a `.gitattributes` that forces LF line endings on all platforms. If you cloned before this file existed and see `\r\n` issues, re-normalise your checkout:
```bash
git add --renormalize .
git checkout -- .
```
- Avoid setting `core.autocrlf = true` in your Git config; the `.gitattributes` file handles line endings automatically.
## Branch and Commit Standards
- Branch naming: `<type>/<short-description>` (example: `fix/auth-key-drift`)
- Commit format: conventional style (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`)
- Keep PRs focused and atomic
## Pull Request Process
1. Create or reference an issue for non-trivial changes
2. Implement the change with tests
3. Update docs when behavior changes
4. Run validation locally
5. Open a PR using the template and complete every checklist item
### Required Validation Before PR
```bash
# repository checks
cd testing
make validate-all
# return to repo root if needed
cd ..
```
If your change touches only a subset of services, include targeted validation evidence in the PR description.
## Review Expectations
To improve review speed and quality, every PR should include:
- Problem statement and scope
- Why this approach was chosen
- Risk assessment (what could regress)
- Test evidence (logs, screenshots, command output)
- Rollback strategy for operationally sensitive changes
## Definition of Done
A contribution is considered ready to merge when:
- CI is passing
- Required approvals are complete
- Documentation is updated
- Security and compatibility concerns are addressed
- Maintainers confirm readiness
## Large Changes
For major features or architectural changes:
1. Open a proposal in Discussions first
2. Align with maintainers on scope and sequencing
3. Implement in incremental PRs
## License
By contributing, you agree that your contributions are licensed under the project license in [`LICENSE`](./LICENSE).
LICENSE
Executable
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2023 SiriusScan
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Makefile
+237
View File
@@ -0,0 +1,237 @@
# Sirius developer Makefile.
#
# This file lives at the repo root and contains short, ergonomic targets
# for the inner-loop dev workflow. The container-testing Makefile in
# testing/container-testing/ remains the authoritative test runner; do
# not duplicate test targets here.
#
# Conventions:
# - All targets are phony unless documented.
# - Targets that touch a running container assume `docker compose -f
# docker-compose.yaml -f docker-compose.dev.yaml up -d` has been run.
# - HOST_GOARCH is detected from `uname -m`; override on the command
# line for cross-arch dev (e.g. building amd64 binaries on an arm64
# mac that talks to an amd64 container).
#
# See documentation/dev/README.development.md for the full dev workflow
# and documentation/dev/architecture/README.engine-component-pinning.md
# for the pin policy that bounds these targets.
SHELL := /bin/bash
# Where each minor-project lives on disk relative to the repo root.
SIRIUS_ROOT := $(abspath $(CURDIR))
PROJECTS_ROOT := $(abspath $(SIRIUS_ROOT)/../minor-projects)
APP_AGENT_DIR := $(PROJECTS_ROOT)/app-agent
APP_TERMINAL_DIR := $(PROJECTS_ROOT)/app-terminal
APP_SCANNER_DIR := $(PROJECTS_ROOT)/app-scanner
# Container that hosts the agent / terminal / scanner Go binaries.
ENGINE_CONTAINER ?= sirius-engine
# Cross-compile target arch. Override with HOST_GOARCH=amd64 if needed.
UNAME_M := $(shell uname -m)
ifeq ($(UNAME_M),arm64)
HOST_GOARCH ?= arm64
else ifeq ($(UNAME_M),aarch64)
HOST_GOARCH ?= arm64
else
HOST_GOARCH ?= amd64
endif
# Where each binary lives inside the container.
#
# In production-mode images (target: runtime), start-enhanced.sh resolves
# AGENT_PATH to /app-agent-src (because /app-agent has no go.mod in that
# image) and runs $AGENT_PATH/server. Writing to /app-agent-src/server is
# therefore the right destination for production hot-swaps.
#
# In dev-mode (target: development) the engine bind-mounts the host's
# local repo over /app-agent and runs Air; the Air output (/app-agent/
# tmp/main) is the live binary, not /app-agent-src/server. Use the
# `make engine-mode` target to detect which mode the running container
# is in before invoking these.
AGENT_CONTAINER_BIN := /app-agent-src/server
TERMINAL_CONTAINER_BIN := /app-terminal/terminal
SCANNER_CONTAINER_BIN := /app-scanner/scanner
.PHONY: help \
engine-mode \
engine-rebuild-from-local \
agent-hot-swap-from-local \
terminal-hot-swap-from-local \
scanner-hot-swap-from-local \
engine-restart \
engine-logs \
_require-production-mode
# ─────────────────────────────────────────────────────────────────────
# Internal guard: hot-swap targets only meaningfully replace the live
# binary when the engine is in production mode. In dev mode:
# - /app-terminal and /app-scanner are bind-mounted, so a docker-cp
# into them writes through to the host repo (polluting it with a
# compiled artifact).
# - The live binary in dev is Air's ./tmp/main, not the production
# binary path, so the swap is functionally a no-op anyway.
# Bypass with FORCE_HOT_SWAP=1 if you really know what you want.
# ─────────────────────────────────────────────────────────────────────
_require-production-mode:
@if ! docker ps --format '{{.Names}}' | grep -qx '$(ENGINE_CONTAINER)'; then \
echo "Error: $(ENGINE_CONTAINER) is not running. Start it with 'docker compose up -d'."; \
exit 1; \
fi
@mode=$$(docker exec $(ENGINE_CONTAINER) printenv GO_ENV 2>/dev/null); \
mode=$${mode:-production}; \
if [ "$$mode" = "development" ] && [ -z "$$FORCE_HOT_SWAP" ]; then \
echo "Refusing to hot-swap: $(ENGINE_CONTAINER) is in dev mode (GO_ENV=development)."; \
echo ""; \
echo " In dev mode Air rebuilds from source on every save; the hot-swap"; \
echo " targets would (a) write a binary into your bind-mounted host repo,"; \
echo " and (b) be ignored at runtime (Air runs ./tmp/main, not the prod"; \
echo " binary path). Edit source and let Air handle it."; \
echo ""; \
echo " If you really want to run anyway, set FORCE_HOT_SWAP=1."; \
exit 1; \
fi
help:
@echo "Sirius dev-loop targets (run from the repo root)"
@echo "================================================"
@echo ""
@echo "Hot-swap (cross-compile locally, copy into running container, restart):"
@echo " agent-hot-swap-from-local Rebuild app-agent from $(APP_AGENT_DIR)"
@echo " terminal-hot-swap-from-local Rebuild app-terminal from $(APP_TERMINAL_DIR)"
@echo " scanner-hot-swap-from-local Rebuild app-scanner from $(APP_SCANNER_DIR)"
@echo " engine-rebuild-from-local Hot-swap all three at once"
@echo ""
@echo "Container management:"
@echo " engine-mode Show whether $(ENGINE_CONTAINER) is in dev or production mode"
@echo " engine-restart Restart $(ENGINE_CONTAINER)"
@echo " engine-logs Tail $(ENGINE_CONTAINER) logs"
@echo ""
@echo "Override HOST_GOARCH=amd64 to cross-compile for an amd64 container."
@echo "Cross-compiling app-scanner currently falls back to a CGO-disabled"
@echo "build because libpcap headers may not be available locally; the"
@echo "scanner target prints a clear warning if CGO is required."
@echo ""
@echo "These targets are an inner-loop convenience. The authoritative"
@echo "build path is sirius-engine/Dockerfile + GitHub-hosted minor-"
@echo "projects. Once your local change is good, push it and bump the"
@echo "Dockerfile/CI pin per documentation/dev/architecture/README.engine-component-pinning.md."
# ─────────────────────────────────────────────────────────────────────
# Agent: cross-compile cmd/server, copy into container, restart engine.
# ─────────────────────────────────────────────────────────────────────
agent-hot-swap-from-local: _require-production-mode
@test -d "$(APP_AGENT_DIR)" || { echo "Error: $(APP_AGENT_DIR) not found"; exit 1; }
@echo ">> Cross-compiling app-agent for linux/$(HOST_GOARCH)"
cd "$(APP_AGENT_DIR)" && \
CGO_ENABLED=0 GOOS=linux GOARCH=$(HOST_GOARCH) \
go build -ldflags="-w -s" -o /tmp/sirius-agent-server-local ./cmd/server/main.go
@echo ">> Copying binary into $(ENGINE_CONTAINER):$(AGENT_CONTAINER_BIN)"
docker cp /tmp/sirius-agent-server-local $(ENGINE_CONTAINER):$(AGENT_CONTAINER_BIN)
@rm -f /tmp/sirius-agent-server-local
@echo ">> Restarting $(ENGINE_CONTAINER) so the new binary takes effect"
docker restart $(ENGINE_CONTAINER) >/dev/null
@echo ">> Done. Tail logs with: make engine-logs"
# ─────────────────────────────────────────────────────────────────────
# Terminal: cross-compile cmd, copy into container, restart engine.
# ─────────────────────────────────────────────────────────────────────
terminal-hot-swap-from-local: _require-production-mode
@test -d "$(APP_TERMINAL_DIR)" || { echo "Error: $(APP_TERMINAL_DIR) not found"; exit 1; }
@echo ">> Cross-compiling app-terminal for linux/$(HOST_GOARCH)"
cd "$(APP_TERMINAL_DIR)" && \
CGO_ENABLED=0 GOOS=linux GOARCH=$(HOST_GOARCH) \
go build -ldflags="-w -s" -o /tmp/sirius-terminal-local ./cmd/main.go
@echo ">> Copying binary into $(ENGINE_CONTAINER):$(TERMINAL_CONTAINER_BIN)"
docker cp /tmp/sirius-terminal-local $(ENGINE_CONTAINER):$(TERMINAL_CONTAINER_BIN)
@rm -f /tmp/sirius-terminal-local
@echo ">> Restarting $(ENGINE_CONTAINER) so the new binary takes effect"
docker restart $(ENGINE_CONTAINER) >/dev/null
@echo ">> Done. Tail logs with: make engine-logs"
# ─────────────────────────────────────────────────────────────────────
# Scanner: cross-compile main.go, copy into container, restart engine.
# Scanner needs CGO + libpcap. We try CGO_ENABLED=1 first; if libpcap
# is missing on the host, the user must do an in-container build
# (see Phase 6c of SHA-AUDIT-2026-04.md).
# ─────────────────────────────────────────────────────────────────────
scanner-hot-swap-from-local: _require-production-mode
@test -d "$(APP_SCANNER_DIR)" || { echo "Error: $(APP_SCANNER_DIR) not found"; exit 1; }
@echo ">> Cross-compiling app-scanner for linux/$(HOST_GOARCH) (CGO required)"
@# NOTE: the "( ... )" subshell grouping is required. `if ! cd X && go build`
@# is parsed by bash as `if (! cd X) && go build`, which silently skips the
@# build when cd succeeds — exactly the wrong behavior for a build pipeline.
@if ! ( cd "$(APP_SCANNER_DIR)" && \
CGO_ENABLED=1 GOOS=linux GOARCH=$(HOST_GOARCH) \
go build -ldflags="-w -s" -o /tmp/sirius-scanner-local ./main.go ) 2>/tmp/sirius-scanner-build.err; then \
echo ""; \
echo "ERROR: Local cross-compile failed. The scanner needs libpcap headers"; \
echo " and a working linux/$(HOST_GOARCH) C cross-toolchain."; \
echo " (On macOS, the system clang cannot satisfy linux cgo deps;"; \
echo " this is expected — see workaround below.)"; \
echo ""; \
head -20 /tmp/sirius-scanner-build.err; \
echo ""; \
echo "Workaround: build inside the container instead, e.g."; \
echo " docker exec $(ENGINE_CONTAINER) bash -c \\"; \
echo " 'cd /app-scanner && CGO_ENABLED=1 GOOS=linux go build -o /app-scanner/scanner main.go'"; \
echo "Then: docker restart $(ENGINE_CONTAINER)"; \
rm -f /tmp/sirius-scanner-build.err /tmp/sirius-scanner-local; \
exit 1; \
fi
@rm -f /tmp/sirius-scanner-build.err
@echo ">> Copying binary into $(ENGINE_CONTAINER):$(SCANNER_CONTAINER_BIN)"
docker cp /tmp/sirius-scanner-local $(ENGINE_CONTAINER):$(SCANNER_CONTAINER_BIN)
@rm -f /tmp/sirius-scanner-local
@echo ">> Restarting $(ENGINE_CONTAINER) so the new binary takes effect"
docker restart $(ENGINE_CONTAINER) >/dev/null
@echo ">> Done. Tail logs with: make engine-logs"
# ─────────────────────────────────────────────────────────────────────
# Convenience: hot-swap all three. Best effort; failures don't abort
# the whole sequence so a partial dev run still completes.
# ─────────────────────────────────────────────────────────────────────
engine-rebuild-from-local:
@echo "==> agent-hot-swap-from-local"
-$(MAKE) -s agent-hot-swap-from-local
@echo ""
@echo "==> terminal-hot-swap-from-local"
-$(MAKE) -s terminal-hot-swap-from-local
@echo ""
@echo "==> scanner-hot-swap-from-local"
-$(MAKE) -s scanner-hot-swap-from-local
engine-restart:
docker restart $(ENGINE_CONTAINER)
engine-logs:
docker logs -f --tail 100 $(ENGINE_CONTAINER)
# ─────────────────────────────────────────────────────────────────────
# Diagnostic: which mode is the engine running in? Hot-swap targets
# only meaningfully replace the live binary in production mode; in dev
# mode Air owns the binary, so use plain file edits instead.
# ─────────────────────────────────────────────────────────────────────
engine-mode:
@if ! docker ps --format '{{.Names}}' | grep -qx '$(ENGINE_CONTAINER)'; then \
echo "$(ENGINE_CONTAINER) is not running."; \
exit 1; \
fi
@mode=$$(docker exec $(ENGINE_CONTAINER) printenv GO_ENV 2>/dev/null); \
mode=$${mode:-production}; \
echo "$(ENGINE_CONTAINER) GO_ENV=$$mode"; \
if [ "$$mode" = "development" ]; then \
echo ""; \
echo " Dev mode is active. Air rebuilds on save from your local repos:"; \
echo " $(APP_AGENT_DIR)"; \
echo " $(APP_TERMINAL_DIR)"; \
echo " $(APP_SCANNER_DIR)"; \
echo " *-hot-swap-from-local targets will copy a binary in but Air"; \
echo " will rebuild from source after the engine restart, so the"; \
echo " swap is non-persistent. Edit source files instead."; \
else \
echo ""; \
echo " Production mode. Hot-swap targets are appropriate here."; \
fi
README.md
Executable
+180
View File
@@ -0,0 +1,180 @@
# Sirius Scan
[![CI](https://github.com/SiriusScan/Sirius/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/SiriusScan/Sirius/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/SiriusScan/Sirius?label=release)](https://github.com/SiriusScan/Sirius/releases)
[![Registry](https://img.shields.io/badge/registry-ghcr.io-blue)](https://github.com/orgs/SiriusScan/packages)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
[![Discord](https://img.shields.io/badge/community-discord-5865F2)](https://sirius.opensecurity.com/community)
![Sirius Scan Dashboard](/documentation/dash-dark.gif)
Sirius is an open-source vulnerability scanner with automated discovery, CVE-based detection, and a modern web UI. Clone, run four commands, start scanning.
## Quick Start
```bash
git clone https://github.com/SiriusScan/Sirius.git
cd Sirius
docker compose -f docker-compose.installer.yaml run --rm sirius-installer
docker compose up -d
```
Open **http://localhost:3000** and log in:
| | |
|---|---|
| **Email** | `admin@example.com` |
| **Password** | printed by the installer (look for `INITIAL_ADMIN_PASSWORD` in the output) |
That's it. All six services start automatically. The installer generates secure secrets on first run and is safe to re-run.
By default the installer leaves `IMAGE_TAG` unset, so Compose pulls **`latest`** from GHCR. To pin a release (for example `v1.0.0` in `.env`), only do so after that tag exists for **all six** container images; verify with `bash scripts/verify-ghcr-public-access.sh v1.0.0` from a shell that is not logged in to `ghcr.io`.
> **Requirements:** Docker Engine 20.10+ with Compose V2, 4 GB RAM, 10 GB disk. Works on Linux, macOS, and Windows (WSL2).
## What Sirius Does
- **Network Discovery** -- automated host and service enumeration via Nmap
- **Vulnerability Detection** -- CVE-based scanning with CVSS scoring
- **Risk Dashboards** -- real-time scanning progress, severity trends, and remediation guidance
- **Remote Agents** -- distributed scanning across multiple environments via gRPC
- **Interactive Terminal** -- PowerShell console for advanced scripting and automation
- **REST API** -- integrate with existing security workflows (`X-API-Key` auth on port 9001)
## Deployment Options
The installer step is always the same. Only the `docker compose up` command changes.
| Mode | Command | Use case |
|------|---------|----------|
| **Standard** | `docker compose up -d` | Most users -- pulls the full release stack from GHCR |
| **Development** | `docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d` | Live-reload for local code work |
| **Source Build** | `docker compose -f docker-compose.yaml -f docker-compose.build.yaml up -d --build` | Explicit local full-stack builds |
| **Production** | `docker compose -f docker-compose.yaml -f docker-compose.prod.yaml up -d` | Hardened settings, `pull_policy: always` |
### Non-interactive setup (CI / Terraform / automation)
```bash
docker compose -f docker-compose.installer.yaml run --rm sirius-installer --non-interactive --no-print-secrets
docker compose up -d
```
### Rotate secrets
```bash
docker compose -f docker-compose.installer.yaml run --rm sirius-installer --force
docker compose up -d --force-recreate
```
## Verify Installation
```bash
docker compose ps # all 6 services should show "healthy" or "running"
curl http://localhost:3000 # UI responds
curl http://localhost:9001/health # API responds
```
Expected services: `sirius-ui` (3000), `sirius-api` (9001), `sirius-engine` (5174, 50051), `sirius-postgres` (5432), `sirius-rabbitmq` (5672, 15672), `sirius-valkey` (6379).
## Architecture
```mermaid
graph TD
subgraph clients [Clients]
UI["Sirius UI (Next.js)"]
CLI["Terminal and Agent Runtime"]
end
subgraph core [Core Services]
API["Sirius API (Go/Gin)"]
Engine["Sirius Engine"]
end
subgraph infra [Infrastructure]
MQ["RabbitMQ"]
DB["PostgreSQL"]
Cache["Valkey"]
end
UI -->|"HTTP/WebSocket"| API
CLI -->|"gRPC"| Engine
API -->|"AMQP publish"| MQ
MQ -->|"Queue consume"| Engine
API -->|"SQL read/write"| DB
Engine -->|"SQL read/write"| DB
API -->|"Session/cache ops"| Cache
Engine -->|"Scan state cache ops"| Cache
```
| Service | Technology | Ports | Purpose |
|---------|-----------|-------|---------|
| **sirius-ui** | Next.js 14, React, Tailwind | 3000 | Web interface |
| **sirius-api** | Go, Gin | 9001 | REST API and business logic |
| **sirius-engine** | Go + embedded gRPC agent | 5174, 50051 | Scanner, terminal, agent services |
| **sirius-postgres** | PostgreSQL 15 | 5432 | Vulnerability and scan data |
| **sirius-rabbitmq** | RabbitMQ | 5672, 15672 | Inter-service messaging |
| **sirius-valkey** | Valkey (Redis-compatible) | 6379 | Cache and session data |
## Interface
| Dashboard | Scanner | Vulnerability Navigator |
|-----------|---------|------------------------|
| ![Dashboard](/documentation/dash-dark.gif) | ![Scanner](/documentation/scanner.jpg) | ![Vulnerabilities](/documentation/vulnerability-navigator.jpg) |
| Environment | Host Details | Terminal |
|-------------|--------------|----------|
| ![Environment](/documentation/environment.jpg) | ![Host](/documentation/host.jpg) | ![Terminal](/documentation/terminal.jpg) |
## API
Sirius exposes REST endpoints on port 9001, protected by the **internal service API key**. Prefer the Docker secret file (`SIRIUS_API_KEY_FILE`, default `/run/secrets/sirius_api_key`); `SIRIUS_API_KEY` remains a supported env fallback. The installer writes `./secrets/sirius_api_key.txt` (mode **0644** so non-root app UIDs can read the bind-mounted secret) and configures both.
```bash
curl http://localhost:9001/health -H "X-API-Key: $SIRIUS_API_KEY"
curl http://localhost:9001/api/v1/scan/get/all -H "X-API-Key: $SIRIUS_API_KEY"
```
Full API docs: [REST API Reference](https://sirius.opensecurity.com/docs/api/rest/authentication)
## Security Recommendations
For production deployments:
1. **Rotate secrets** -- run the installer with `--force` to regenerate all credentials
2. **Restrict ports** -- only expose port 3000 (UI); keep 5432, 6379, 5672 internal
3. **Use a reverse proxy** -- put nginx or Traefik in front with TLS
4. **Keep images updated** -- `docker compose pull && docker compose up -d`
## Troubleshooting
Quick fixes for common problems:
| Problem | Fix |
|---------|-----|
| Services won't start | `docker compose logs <service>` to find the error |
| Dev overlay missing infra | Use both files: `-f docker-compose.yaml -f docker-compose.dev.yaml` |
| Port conflict | `lsof -i :3000` to find the conflicting process |
| Database connection error | `docker exec sirius-postgres pg_isready` |
| Stale secrets after reset | Re-run the installer, then `docker compose up -d --force-recreate` |
For detailed operational runbooks, verification procedures, and emergency recovery, see [Operations & Troubleshooting](./documentation/OPERATIONS.md).
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, coding standards, and PR guidelines.
**Quick links:** [Issues](https://github.com/SiriusScan/Sirius/issues) | [Discussions](https://github.com/SiriusScan/Sirius/discussions) | [Discord](https://sirius.opensecurity.com/community)
## Further Reading
- [Installation Guide](https://sirius.opensecurity.com/docs/getting-started/installation)
- [Interface Tour](https://sirius.opensecurity.com/docs/getting-started/interface-tour)
- [Scanning Guide](https://sirius.opensecurity.com/docs/guides/scanning)
- [Docker Architecture](./documentation/dev/architecture/README.docker-architecture.md)
- [System Architecture](./documentation/dev/architecture/README.architecture.md)
- [CI/CD Guide](./documentation/dev/architecture/README.cicd.md)
- [Operations & Troubleshooting](./documentation/OPERATIONS.md)
## License
[MIT](./LICENSE)
README.wehub.md
+7
View File
@@ -0,0 +1,7 @@
# WeHub 来源说明
- 原始项目：`SiriusScan/Sirius`
- 原始仓库：https://github.com/SiriusScan/Sirius
- 导入方式：上游默认分支的最新快照
- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准
- 本文件仅用于记录来源，不代表 WeHub 是原项目作者
SECURITY.md
+68
View File
@@ -0,0 +1,68 @@
# Security Policy
Sirius Scan is a security platform. We treat vulnerability handling as a first-class engineering workflow.
## Supported Versions
We currently provide security fixes for:
- `main` branch
- Latest production release tag (for example, `v1.x`)
Older releases may not receive security patches.
## Reporting a Vulnerability
Do not open public issues for suspected vulnerabilities.
Use one of the private channels below:
- GitHub Security Advisories: <https://github.com/SiriusScan/Sirius/security/advisories/new>
- Email: `security@opensecurity.com`
If possible, include:
1. Affected component(s) and version/tag
2. Reproduction steps or proof of concept
3. Expected impact and attack preconditions
4. Suggested mitigation (if known)
5. Contact information for follow-up
## Response Targets
We aim to meet the following timelines:
- Initial acknowledgment: within 24 hours
- Triage decision: within 72 hours
- Mitigation plan: within 7 calendar days for confirmed issues
- Public advisory: after a fix is available and coordinated
Complex vulnerabilities may require longer remediation windows. We will keep reporters informed of status.
## Disclosure Process
1. Report received and acknowledged privately
2. Internal triage and severity classification
3. Fix is prepared and validated
4. Coordinated release and advisory publication
5. Credit is given to reporter (if desired)
## Scope
This policy covers vulnerabilities in:
- `Sirius` primary repository
- Official Sirius Scan release artifacts
- Related services maintained under the SiriusScan organization where applicable
Third-party dependencies should also be reported upstream when required.
## Safe Harbor
We support good-faith security research. We ask researchers to:
- Avoid service disruption or destructive testing
- Avoid accessing or modifying data that is not your own
- Report findings privately and allow coordinated remediation
We will not pursue action against research that follows this policy and applicable law.
SUPPORT.md
+38
View File
@@ -0,0 +1,38 @@
# Support
Use this guide to choose the right support channel.
## Questions and How-To Help
For usage questions, setup clarifications, and architecture discussions:
- GitHub Discussions: <https://github.com/SiriusScan/Sirius/discussions>
- Documentation portal: <https://sirius.opensecurity.com/docs>
- Community Discord: <https://sirius.opensecurity.com/community>
## Bug Reports
For defects and regressions, open a GitHub issue:
- Issues: <https://github.com/SiriusScan/Sirius/issues>
Please use issue forms and include diagnostics/logs so maintainers can triage quickly.
## Security Reports
Do not report vulnerabilities in public issues or discussions.
Follow the private disclosure process in:
- [`SECURITY.md`](./SECURITY.md)
## Contribution and Governance
- Contribution guide: [`CONTRIBUTING.md`](./CONTRIBUTING.md)
- Code of conduct: [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)
## Maintainer Response Guidance
- Questions in Discussions: best effort
- Triage for actionable issues: prioritized by severity and impact
- Security reports: handled per SLA in `SECURITY.md`
docker-compose.build.yaml
+45
View File
@@ -0,0 +1,45 @@
services:
sirius-rabbitmq:
build:
context: ./sirius-rabbitmq
dockerfile: Dockerfile
image: sirius-sirius-rabbitmq:source
pull_policy: never
sirius-postgres:
build:
context: ./sirius-postgres
dockerfile: Dockerfile
image: sirius-sirius-postgres:source
pull_policy: never
sirius-valkey:
build:
context: ./sirius-valkey
dockerfile: Dockerfile
image: sirius-sirius-valkey:source
pull_policy: never
sirius-ui:
build:
context: ./sirius-ui
dockerfile: Dockerfile
target: production
image: sirius-sirius-ui:source
pull_policy: never
sirius-api:
build:
context: ./sirius-api
dockerfile: Dockerfile
target: runner
image: sirius-sirius-api:source
pull_policy: never
sirius-engine:
build:
context: ./sirius-engine
dockerfile: Dockerfile
target: runtime
image: sirius-sirius-engine:source
pull_policy: never

Some files were not shown because too many files have changed in this diff Show More