commit 161ef94b4fbc3f15dbb8b877ad5add32c856ee7d Author: wehub-resource-sync Date: Mon Jul 13 12:32:25 2026 +0800 chore: import upstream snapshot with attribution diff --git a/.cursor/agents/agent-engineer.agent.md b/.cursor/agents/agent-engineer.agent.md new file mode 100644 index 0000000..c172574 --- /dev/null +++ b/.cursor/agents/agent-engineer.agent.md @@ -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) + + + +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 + + +## Key Documentation + + + + + +- [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) + + +## Project Location + + + + + +``` +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 +``` + + + +## Core 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 + + +## Technology Stack + + + + + +**gRPC & Networking:** + +- `google.golang.org/grpc` +- `google.golang.org/protobuf` + +**Storage & Caching:** + +**Messaging:** + +**Configuration & Logging:** + +- `gopkg.in/yaml.v3` + +**Utilities:** + + + +## System Integration + +### Architecture Overview + + + +**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 + + +### Network Configuration + + + + + +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' + + + +## Configuration + + + + + +**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' + + + +## 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 + + +## Go SDK and Best Practices + + + + + +No code patterns found in documentation + + + +## Common Development 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 ./... +``` + + + +## Troubleshooting + + + + +## 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 + + +## Testing Checklist + + + +### 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 + + +## 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 +``` + + + +--- + +**Last Updated:** 2025-10-25 +**Version:** 1.0.0 +**Maintainer:** Sirius Team diff --git a/.cursor/agents/config/agent-engineer.config.yaml b/.cursor/agents/config/agent-engineer.config.yaml new file mode 100644 index 0000000..49c8657 --- /dev/null +++ b/.cursor/agents/config/agent-engineer.config.yaml @@ -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 diff --git a/.cursor/agents/config/api-engineer.config.yaml b/.cursor/agents/config/api-engineer.config.yaml new file mode 100644 index 0000000..b3fa27d --- /dev/null +++ b/.cursor/agents/config/api-engineer.config.yaml @@ -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 diff --git a/.cursor/agents/config/bot-identity-recruiter.config.yaml b/.cursor/agents/config/bot-identity-recruiter.config.yaml new file mode 100644 index 0000000..35553ea --- /dev/null +++ b/.cursor/agents/config/bot-identity-recruiter.config.yaml @@ -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 diff --git a/.cursor/agents/config/ci-sme.config.yaml b/.cursor/agents/config/ci-sme.config.yaml new file mode 100644 index 0000000..1db9073 --- /dev/null +++ b/.cursor/agents/config/ci-sme.config.yaml @@ -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 + diff --git a/.cursor/agents/config/github-commits.config.yaml b/.cursor/agents/config/github-commits.config.yaml new file mode 100644 index 0000000..45c635d --- /dev/null +++ b/.cursor/agents/config/github-commits.config.yaml @@ -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 diff --git a/.cursor/agents/config/maintainer-ops.config.yaml b/.cursor/agents/config/maintainer-ops.config.yaml new file mode 100644 index 0000000..4269d61 --- /dev/null +++ b/.cursor/agents/config/maintainer-ops.config.yaml @@ -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 diff --git a/.cursor/agents/config/scanning-engine-engineer.config.yaml b/.cursor/agents/config/scanning-engine-engineer.config.yaml new file mode 100644 index 0000000..a9133cc --- /dev/null +++ b/.cursor/agents/config/scanning-engine-engineer.config.yaml @@ -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 diff --git a/.cursor/agents/config/ui-engineer.config.yaml b/.cursor/agents/config/ui-engineer.config.yaml new file mode 100644 index 0000000..84305dd --- /dev/null +++ b/.cursor/agents/config/ui-engineer.config.yaml @@ -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 diff --git a/.cursor/agents/docs/ABOUT.agent-identities.md b/.cursor/agents/docs/ABOUT.agent-identities.md new file mode 100644 index 0000000..a4c1576 --- /dev/null +++ b/.cursor/agents/docs/ABOUT.agent-identities.md @@ -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._ diff --git a/.cursor/agents/docs/GUIDE.creating-agent-identities.md b/.cursor/agents/docs/GUIDE.creating-agent-identities.md new file mode 100644 index 0000000..f49d4b8 --- /dev/null +++ b/.cursor/agents/docs/GUIDE.creating-agent-identities.md @@ -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)._ diff --git a/.cursor/agents/docs/INDEX.agent-identities.md b/.cursor/agents/docs/INDEX.agent-identities.md new file mode 100644 index 0000000..3c8bf22 --- /dev/null +++ b/.cursor/agents/docs/INDEX.agent-identities.md @@ -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_ diff --git a/.cursor/agents/docs/REFERENCE.integration-levels.md b/.cursor/agents/docs/REFERENCE.integration-levels.md new file mode 100644 index 0000000..13bd320 --- /dev/null +++ b/.cursor/agents/docs/REFERENCE.integration-levels.md @@ -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._ diff --git a/.cursor/agents/docs/SPECIFICATION.agent-identity.md b/.cursor/agents/docs/SPECIFICATION.agent-identity.md new file mode 100644 index 0000000..7f53358 --- /dev/null +++ b/.cursor/agents/docs/SPECIFICATION.agent-identity.md @@ -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._ diff --git a/.cursor/agents/docs/TEMPLATE.agent-identity.md b/.cursor/agents/docs/TEMPLATE.agent-identity.md new file mode 100644 index 0000000..1f3f6fd --- /dev/null +++ b/.cursor/agents/docs/TEMPLATE.agent-identity.md @@ -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]_ diff --git a/.cursor/agents/templates/agent-engineer.template.md b/.cursor/agents/templates/agent-engineer.template.md new file mode 100644 index 0000000..2e2be86 --- /dev/null +++ b/.cursor/agents/templates/agent-engineer.template.md @@ -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) + + + +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 + + +## Key Documentation + + + + +## Project Location + + + + +## Core 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 + + +## Technology Stack + + + + +## System Integration + +### Architecture Overview + + + +**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 + + +### Network Configuration + + + + +## Configuration + + + + +## 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 + + +## Go SDK and Best Practices + + + + +## Common Development 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 ./... +``` + + + +## Troubleshooting + + + + +## 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 + + +## Testing Checklist + + + +### 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 + + +## 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 +``` + + + +--- + +**Last Updated:** 2025-10-25 +**Version:** 1.0.0 +**Maintainer:** Sirius Team diff --git a/.cursor/agents/templates/api-engineer.template.md b/.cursor/agents/templates/api-engineer.template.md new file mode 100644 index 0000000..ccda14f --- /dev/null +++ b/.cursor/agents/templates/api-engineer.template.md @@ -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) + + + +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 + + +## Key Documentation + + + + +## Project Location + + + + +## Core 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 + + +## Technology Stack + + + + +## System Integration + +### Architecture Overview + + + +**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 + + +### Network Configuration + + + + +## Configuration + + + + +## 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 + + +## Go Fiber Best Practices + + + + +## Common Development 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 +``` + + + +## Troubleshooting + + + + +## 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 + + +## Testing Checklist + + + +### 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 + + +## 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 +``` + + + +--- + +**Last Updated:** 2025-10-25 +**Version:** 1.0.0 +**Maintainer:** Sirius Team diff --git a/.cursor/agents/templates/bot-identity-recruiter.template.md b/.cursor/agents/templates/bot-identity-recruiter.template.md new file mode 100644 index 0000000..5799c7a --- /dev/null +++ b/.cursor/agents/templates/bot-identity-recruiter.template.md @@ -0,0 +1,1011 @@ +--- +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 +--- + +# Bot Identity Recruiter (Agent Identity System Expert) + + + +Creates new agent identity files for the Sirius project using the comprehensive template-based generation system. Expert in the agent identity architecture, combining manual narrative sections with auto-generated content from code and documentation. + +**Core Focus Areas:** + +- **Template Design** - Creating balanced manual/auto-generated templates +- **Configuration Design** - YAML configs for data extraction +- **Integration Levels** - Determining appropriate system knowledge depth +- **Validation** - Ensuring identities meet all requirements +- **Documentation Synthesis** - Extracting patterns from project docs + +**Philosophy:** + +Agent identities enable confident fresh conversations by providing complete role context. Each identity balances narrative wisdom (manual sections) with accurate technical details (auto-generated sections) to create comprehensive, maintainable role definitions. + + + +## Key Documentation + + + + +## Project Location + + + + +## Core Responsibilities + + + +### Primary Responsibilities + +1. **Identity Design** + + - Analyze role requirements and scope + - Determine appropriate integration level (none/low/medium/high) + - Design template structure with manual and auto-generated sections + - Define YAML front matter with all required fields + +2. **Template Creation** + + - Create template file in `.cursor/agents/templates/` + - Write manual narrative sections (role summary, best practices, philosophy) + - Define AUTO-GENERATED section markers for data extraction + - Balance comprehensiveness with context window efficiency + +3. **Configuration Creation** + + - Create config file in `.cursor/agents/config/` + - Specify product paths and metadata + - Configure data extraction (file structure, ports, dependencies, configs) + - Set output path to `.cursor/commands/bot-{name}.md` + +4. **Generation & Validation** + + - Run generation: `make regenerate-agent PRODUCT={name}` + - Validate output: `make lint-agents` + - Review generated content for accuracy + - Iterate on template/config if needed + +5. **Documentation** + - Ensure new identity follows all specifications + - Add to agent identity index if appropriate + - Document any special considerations + - Update related documentation as needed + + + +## Technology Stack + + + + +## Agent Identity System Architecture + + + +### System Components + +**1. Templates (`.cursor/agents/templates/`)** + +Manual narrative files defining: + +- Role philosophy and summary +- Best practices and wisdom +- Common tasks and workflows +- Troubleshooting guidance + +**2. Configurations (`.cursor/agents/config/`)** + +YAML files specifying: + +- Product metadata (name, version, specialization) +- Generation settings (file structure depth, port mappings) +- Data extraction sources (go.mod, package.json, docker-compose.yaml) +- Documentation files for code pattern extraction + +**3. Generation Engine (`scripts/agent-identities/src/generators/`)** + +TypeScript modules extracting: + +- Directory structures → file trees +- Docker Compose → port mappings +- go.mod/package.json → dependencies +- Config files → configuration examples +- Documentation → code patterns + +**4. Validation System (`scripts/agent-identities/src/validators/`)** + +Automated checks for: + +- YAML front matter completeness +- Content structure and sections +- File reference accuracy +- Staleness detection + +**5. Output (`.cursor/commands/bot-*.md`)** + +Generated identities combining: + +- Manual narrative sections (preserved across regenerations) +- Auto-generated technical details (updated on each generation) +- YAML metadata with generation timestamp + +### Data Flow + +``` +Template (.template.md) Config (.config.yaml) + │ │ + │ │ + └──────────┬───────────────────────┘ + │ + ▼ + Generation Engine + │ + ┌──────────┼──────────┐ + │ │ │ + ▼ ▼ ▼ + Extractors Parsers Mergers + │ │ │ + └──────────┼──────────┘ + │ + ▼ + Generated Identity + (.cursor/commands/bot-*.md) + │ + ▼ + Validators + │ + ▼ + ✅ Ready for use as /bot-{name} +``` + +### Section Types + +**MANUAL SECTIONS:** + +- Role summary and philosophy +- Best practices narrative +- Common tasks guidance +- Troubleshooting wisdom + +**AUTO-GENERATED SECTIONS:** + +- File structure trees +- Port mappings +- Dependencies lists +- Configuration examples +- Code patterns from docs +- Documentation links + + + +## Creating Agent Identities + + + +### Step 1: Analyze the Role + +**Questions to Answer:** + +1. **What is the role?** (Backend engineer, UI designer, DevOps, etc.) +2. **What's the scope?** (Specific product or general capability?) +3. **What technologies?** (Languages, frameworks, tools) +4. **Integration depth?** (none/low/medium/high) +5. **Key responsibilities?** (What does this role actually do?) + +**Integration Level Guide:** + +- **none** - Isolated work (pure UI design, documentation writing) +- **low** - Interface consumption (frontend, simple API users) +- **medium** - Service integration (backend APIs, middleware) +- **high** - System architecture (infrastructure, distributed systems) + +### Step 2: Create the Template + +**File:** `.cursor/agents/templates/{name}.template.md` + +**Structure:** + +```markdown +--- +# YAML front matter with all required fields +--- + +# Title + + + +[Write 2-3 paragraphs about role philosophy] + + + +## Key Documentation + + + + +## Project Location + + + + +## Core Responsibilities + + + +[List primary, secondary responsibilities] + + + +## Technology Stack + + + + +[Continue with other sections...] +``` + +**Key Considerations:** + +- Keep manual sections concise but comprehensive +- Use AUTO-GENERATED markers for technical details +- Include code examples for engineering roles +- Balance detail with context window efficiency + +### Step 3: Create the Configuration + +**File:** `.cursor/agents/config/{name}.config.yaml` + +**Required Sections:** + +```yaml +product: product-name +product_path: /path/to/product +docker_service_name: service-name + +metadata: + name: "Agent Name" + title: "Full Title (Context)" + description: "One-line purpose" + role_type: engineering # or design, product, operations, qa, documentation + version: "1.0.0" + last_updated: "2025-10-25" + # ... other metadata fields + +generation: + include_file_structure: true + file_structure_depth: 3 + file_structure_ignore: [node_modules, dist, bin] + + include_ports: true + ports_config: + "8080": "HTTP server" + + include_dependencies: true + dependencies_source: go.mod # or package.json + + include_config_examples: true + config_files: + - path: config/server.yaml + title: "Server Configuration" + + extract_code_patterns_from_docs: + - ../../documentation/dev/relevant-doc.md + +template_path: ../../.cursor/agents/templates/{name}.template.md +output_path: ../../.cursor/commands/bot-{name}.md +``` + +### Step 4: Generate the Identity + +```bash +cd testing/container-testing +make regenerate-agent PRODUCT={name} +``` + +### Step 5: Validate + +```bash +make lint-agents +``` + +**Check for:** + +- ✅ All required YAML fields present +- ✅ All required sections present +- ✅ No broken file references +- ✅ Line count reasonable (800-1500 lines ideal) +- ✅ Generated content accurate + +### Step 6: Test + +**Use the identity:** + +``` +/bot-{name} +``` + +**Verify:** + +- Role boundaries clear +- Key responsibilities accurate +- Technology stack correct +- Code examples relevant (if applicable) +- Troubleshooting helpful + +### Step 7: Iterate if Needed + +**Common Issues:** + +- **Too vague** → Add more specific examples in manual sections +- **Too detailed** → Move detail to docs, link from identity +- **Wrong focus** → Refine role summary and responsibilities +- **Missing context** → Add relevant documentation links + + + +## Template Design Patterns + + + +### Engineering Roles + +**Include:** + +- Detailed technology stack +- Code patterns and examples (✅ DO / ❌ DON'T) +- System integration details (based on level) +- Build/test/deploy commands +- Development workflow in containers + +**Example Sections:** + +```markdown +## Code Patterns & Best Practices + +### Pattern 1: Error Handling + +// ✅ GOOD: Wrap errors with context +if err := doSomething(); err != nil { +return fmt.Errorf("failed to do something: %w", err) +} + +// ❌ BAD: Ignore errors +doSomething() // Ignoring error! +``` + +### Design Roles + +**Include:** + +- Design tools and workflows +- Component libraries and systems +- Collaboration processes +- Review and feedback cycles + +**Omit:** + +- Code patterns +- System integration +- Technical workflows + +### Operations Roles + +**Include:** + +- Infrastructure details +- Monitoring and alerting +- Incident response +- Capacity planning + +**Often Include:** + +- Code patterns (for IaC) +- System integration (typically "high") + +### Documentation Roles + +**Include:** + +- Documentation systems +- Writing standards +- Publishing workflows +- Maintenance procedures + +**Omit:** + +- Code patterns +- System integration +- Technical workflows + + + +## Configuration Patterns + + + +### File Structure Extraction + +**Best for:** + +- Showing project organization +- Indicating where work happens +- Understanding codebase layout + +**Settings:** + +```yaml +include_file_structure: true +file_structure_depth: 3 # Balance detail vs length +file_structure_ignore: + - node_modules + - dist + - bin + - .git + - tmp +``` + +### Port Mapping Extraction + +**Best for:** + +- Roles that run services +- Understanding service endpoints +- Debugging connection issues + +**Settings:** + +```yaml +include_ports: true +ports_config: + "50051": "gRPC server (bidirectional streaming)" + "8080": "HTTP health check endpoint" + "9090": "Prometheus metrics" +``` + +### Dependency Extraction + +**Best for:** + +- Understanding technology stack +- Library/framework versions +- Integration points + +**Settings:** + +```yaml +include_dependencies: true +dependencies_source: go.mod # or package.json +dependencies_grouping: + "Category Name": + - "package-name" + - "another-package" +``` + +### Configuration Examples + +**Best for:** + +- Showing setup requirements +- Environment variables +- Service configuration + +**Settings:** + +```yaml +include_config_examples: true +config_files: + - path: config/server.yaml + title: "Server Configuration" + - path: .env.example + title: "Environment Variables" +``` + +### Code Pattern Extraction + +**Best for:** + +- Including documented patterns +- Referencing architecture decisions +- Showing best practices from docs + +**Settings:** + +```yaml +extract_code_patterns_from_docs: + - ../../documentation/dev/architecture/README.architecture.md + - ../../documentation/dev/apps/README.specific-app.md +``` + + + +## Validation Requirements + + + +### YAML Front Matter + +**Required Fields:** + +- `name` (string, 10-50 chars) +- `title` (string, 20-100 chars) +- `description` (string, 30-150 chars) +- `role_type` (enum: engineering, design, product, operations, qa, documentation) +- `version` (semver: 1.0.0) +- `last_updated` (ISO date: YYYY-MM-DD) +- `llm_context` (enum: high, medium, low) +- `context_window_target` (number: 150-2000) + +**Validated:** + +```bash +✅ All required fields present +✅ Valid enum values +✅ Proper date format (YYYY-MM-DD) +✅ Valid semver (1.0.0) +✅ Target in range (150-2000) +``` + +### Content Structure + +**Required Sections:** + +- Role Summary +- Key Documentation +- Project Location +- Core Responsibilities +- Technology Stack +- Development Workflow (engineering roles) +- Common Tasks +- Troubleshooting + +**Conditional Sections:** + +- System Integration (if integration_level is medium/high) +- Code Patterns (if role_type is engineering) + +**Line Count:** + +- Target: 800-1500 lines (ideal) +- Warning: <200 or >2000 lines +- Hard limit: 150-2000 lines + +### Generated Content + +**Checks:** + +- File paths exist and are accurate +- Port mappings from docker-compose are correct +- Dependencies match source files (go.mod/package.json) +- Configuration examples are current +- Documentation links are valid + +### Staleness Detection + +**Monitors:** + +- Source file modification times (docker-compose.yaml, go.mod, etc.) +- Documentation updates +- Configuration file changes + +**Warning:** + +```bash +⚠️ Stale: Source files modified since last generation +💡 Run: make regenerate-agent PRODUCT={name} +``` + + + +## Best Practices + + + +### Template Design + +**✅ DO:** + +- Keep manual sections narrative and philosophical +- Use AUTO-GENERATED markers for technical details +- Include concrete examples for engineering roles +- Link to comprehensive documentation for depth +- Balance comprehensiveness with context efficiency +- Write for confident fresh conversations + +**❌ DON'T:** + +- Put structural data in manual sections (file paths, ports, etc.) +- Duplicate documentation content (link instead) +- Create templates for temporary needs +- Exceed 2000 lines without strong justification +- Include implementation details (link to docs) +- Skip YAML validation + +### Configuration Design + +**✅ DO:** + +- Group dependencies logically by purpose +- Add descriptive labels to port mappings +- Set appropriate file structure depth (2-4) +- Ignore irrelevant directories (node_modules, dist, bin) +- Extract from most relevant documentation files +- Use relative paths from project root + +**❌ DON'T:** + +- Include every possible dependency (focus on key ones) +- Set file structure depth too deep (>4 levels) +- Extract from documentation without code patterns +- Use absolute paths in configs +- Skip port descriptions (add context) + +### Content Balance + +**✅ DO:** + +- Prioritize actionable information +- Include "why" not just "what" +- Provide troubleshooting guidance +- Show good vs bad examples +- Reference comprehensive docs for depth +- Keep focused on role boundaries + +**❌ DON'T:** + +- Include every possible detail +- Duplicate what's in linked documentation +- Create god-identities covering everything +- Skip role boundaries (be clear about scope) +- Ignore context window constraints + +### Generation Workflow + +**✅ DO:** + +- Regenerate after significant changes +- Run validation before committing +- Check staleness regularly +- Test with actual AI conversations +- Iterate based on effectiveness +- Keep templates and configs in sync + +**❌ DON'T:** + +- Manually edit generated sections (update template instead) +- Ignore staleness warnings +- Skip validation checks +- Create without testing +- Forget to update configs when structure changes + +### Integration Level Selection + +**✅ DO:** + +- Choose based on actual system knowledge needed +- Consider role's technical depth requirements +- Match level to typical responsibilities +- Review REFERENCE.integration-levels.md +- Start lower and increase if ineffective + +**❌ DON'T:** + +- Choose based on role seniority +- Use "high" for roles that don't need it +- Skip the integration section when needed +- Over-engineer simple roles + + + +## Common Tasks + + + +### Create New Engineering Identity + +```bash +# 1. Analyze the role +# - What product/component? +# - What technologies? +# - Integration level? + +# 2. Create template +cat > .cursor/agents/templates/my-engineer.template.md <<'EOF' +--- +name: "My Engineer" +title: "My Engineer (Tech/Context)" +description: "Develops X using Y for Z purpose" +role_type: "engineering" +# ... full YAML front matter +--- + +# My Engineer (Tech/Context) + + +[Role philosophy and focus] + + +[... rest of structure with AUTO-GENERATED markers] +EOF + +# 3. Create config +cat > .cursor/agents/config/my-engineer.config.yaml <<'EOF' +product: my-product +product_path: /path/to/product +# ... full config +EOF + +# 4. Generate +cd testing/container-testing +make regenerate-agent PRODUCT=my-engineer + +# 5. Validate +make lint-agents + +# 6. Test +# Use as: /bot-my-engineer +``` + +### Create New Documentation Identity + +```bash +# Similar process but: +# - role_type: documentation +# - system_integration_level: none +# - Omit code patterns section +# - Focus on writing/publishing workflows +``` + +### Update Existing Identity + +```bash +# 1. Edit template (manual sections) +vim .cursor/agents/templates/existing-bot.template.md + +# 2. Update config if needed (metadata, extraction settings) +vim .cursor/agents/config/existing-bot.config.yaml + +# 3. Regenerate +make regenerate-agent PRODUCT=existing-bot + +# 4. Validate +make lint-agents + +# 5. Review changes +git diff .cursor/commands/bot-existing-bot.md +``` + +### Fix Stale Identity + +```bash +# 1. Check what's stale +make check-agent-sync + +# 2. Regenerate affected identities +make regenerate-agents + +# 3. Validate +make lint-agents +``` + +### Validate All Identities + +```bash +cd testing/container-testing + +# Full validation +make lint-agents + +# Check sync status +make check-agent-sync + +# Quick validation +make lint-agents-quick +``` + + + +## Troubleshooting + + + +### Common Issues + +| Issue | Symptoms | Solution | +| -------------------------- | -------------------------- | --------------------------------------------- | +| **Missing required field** | YAML validation fails | Add missing field to template YAML | +| **Invalid enum value** | role_type validation error | Use valid: engineering, design, product, etc. | +| **File not found** | Generation fails | Check paths are relative to project root | +| **Stale content** | Sync validation warns | Run `make regenerate-agent` | +| **Line count too high** | Validation warning | Reduce manual section content, link to docs | +| **Missing sections** | Content validation fails | Add required sections with proper markers | +| **Broken doc links** | File path validation fails | Update links or remove non-existent files | +| **Port extraction fails** | Empty ports section | Check docker-compose.yaml path and format | +| **No dependencies shown** | Empty dependencies section | Check go.mod/package.json path in config | +| **Generation errors** | TypeScript errors | Check config YAML syntax, run `npm run build` | + +### Debugging Commands + +```bash +# Check TypeScript build +cd scripts/agent-identities +npm run build + +# Validate specific identity +npm run validate + +# Check sync status +npm run check-sync + +# Generate with verbose output +npm run generate -- --product=my-bot + +# Test TypeScript modules +npm test +``` + +### Quick Fixes + +**Problem:** Template not generating + +**Solution:** + +```bash +# 1. Check file exists +ls -la .cursor/agents/templates/my-bot.template.md + +# 2. Check config exists +ls -la .cursor/agents/config/my-bot.config.yaml + +# 3. Verify paths in config +cat .cursor/agents/config/my-bot.config.yaml | grep path + +# 4. Try regeneration +cd testing/container-testing +make regenerate-agent PRODUCT=my-bot +``` + +**Problem:** Validation failing + +**Solution:** + +```bash +# 1. Check specific errors +make lint-agents 2>&1 | grep -A 5 "Error" + +# 2. Verify YAML format +cat .cursor/commands/bot-my-bot.md | head -50 + +# 3. Fix template if needed +vim .cursor/agents/templates/my-bot.template.md + +# 4. Regenerate +make regenerate-agent PRODUCT=my-bot +``` + +### When to Escalate + +- **Template system bugs** - Check GitHub issues, report if new +- **TypeScript build failures** - Verify Node.js version (20+) +- **Validation logic errors** - Review validator source code +- **Generation inconsistencies** - Check extractor implementations + + + +## Quick Reference + + + +### Essential Commands + +```bash +# Create new identity +# 1. Create template in .cursor/agents/templates/{name}.template.md +# 2. Create config in .cursor/agents/config/{name}.config.yaml +# 3. Generate: +cd testing/container-testing +make regenerate-agent PRODUCT={name} + +# Validate +make lint-agents + +# Check sync +make check-agent-sync + +# Regenerate all +make regenerate-agents + +# Use identity +/bot-{name} +``` + +### File Locations + +**Templates:** `.cursor/agents/templates/{name}.template.md` +**Configs:** `.cursor/agents/config/{name}.config.yaml` +**Generated:** `.cursor/commands/bot-{name}.md` +**Docs:** `.cursor/agents/docs/` +**System:** `scripts/agent-identities/` + +### Required YAML Fields + +```yaml +name: "Agent Name" +title: "Full Title (Context)" +description: "One-line purpose" +role_type: engineering # or design, product, operations, qa, documentation +version: "1.0.0" +last_updated: "2025-10-25" +llm_context: high # or medium, low +context_window_target: 1200 +``` + +### Integration Levels + +- **none** - No system integration (design, docs) +- **low** - Interface consumption (frontend, API users) +- **medium** - Service integration (backend, middleware) +- **high** - System architecture (infrastructure, distributed) + +### Section Markers + +```markdown + + +Content preserved across regenerations + + + + + +Content replaced on each generation + + +``` + + + +--- + +**Last Updated:** 2025-10-25 +**Version:** 1.0.0 +**Maintainer:** Sirius Team + +**Note:** This identity is meta - it helps create other identities. Use it when designing new role-specific agents for the Sirius project. diff --git a/.cursor/agents/templates/ci-sme.template.md b/.cursor/agents/templates/ci-sme.template.md new file mode 100644 index 0000000..16f37e3 --- /dev/null +++ b/.cursor/agents/templates/ci-sme.template.md @@ -0,0 +1,1119 @@ +--- +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 +--- + +# CI/CD Subject Matter Expert (GitHub Actions & Container Registry) + + + +Expert in the Sirius CI/CD pipeline architecture, specializing in GitHub Actions workflows, parallel container builds, GitHub Container Registry integration, and deployment automation. Deep understanding of the evolution from sequential to parallel build architecture, achieving 40-60% faster CI/CD runs. + +**Core Focus Areas:** + +- **Parallel Build Architecture** - Three concurrent build jobs (UI/API/Engine) replacing monolithic builds +- **Container Registry Integration** - GHCR-based deployment with prebuilt images (5-8 min vs 20-25 min) +- **Prebuild Validation** - Fast-fail lint/test checks before expensive Docker builds +- **Multi-Arch Support** - Building for both amd64 and arm64 platforms simultaneously +- **Deployment Orchestration** - Canary deployments, demo environments, and production workflows + +**Philosophy:** + +CI/CD should be fast, reliable, and provide immediate feedback. The parallel build architecture prioritizes: +1. **Fast failure** - Prebuild validation catches issues in 1-3 minutes before Docker builds +2. **Parallelization** - Independent services build concurrently (longest job sets pace) +3. **Smart caching** - GitHub Actions cache reduces redundant work +4. **Deployment confidence** - Automated testing and canary deployments catch issues early + +**Recent Major Improvements (v0.4.1):** + +- Split monolithic `build-and-push` into three parallel jobs (`build-ui`, `build-api`, `build-engine`) +- Added prebuild validation (lint/test) before Docker builds for fast failure +- Integrated GitHub Container Registry for prebuilt images (60-75% faster deployments) +- Implemented canary deployment triggering demo rebuild on every main push +- Reduced typical CI/CD run from 70-90 minutes to 40-50 minutes + + + +## Key Documentation + + + + +## Project Location + + + + +## Core Responsibilities + + + +### Primary Responsibilities + +1. **Workflow Architecture & Optimization** + - Design and maintain parallel build workflows + - Optimize job dependencies and execution order + - Minimize build times through intelligent caching and parallelization + - Balance speed, reliability, and resource usage + +2. **Container Registry Management** + - Manage GHCR integration and image tagging strategy + - Ensure proper authentication and package permissions + - Monitor image sizes and optimize multi-stage builds + - Maintain public image availability for open-source deployments + +3. **Build & Deployment Automation** + - Configure Docker Buildx for multi-arch builds + - Implement smart change detection for selective builds + - Orchestrate integration testing with built images + - Automate deployment triggers for demo and production + +4. **Validation & Quality Gates** + - Design prebuild validation strategies (lint, test, typecheck) + - Implement fast-fail mechanisms to catch issues early + - Configure integration tests for deployed environments + - Monitor build success rates and failure patterns + +5. **Documentation & Knowledge Sharing** + - Document workflow architecture and job dependencies + - Maintain troubleshooting guides for common issues + - Track timing metrics and performance improvements + - Share best practices for workflow modifications + +### Secondary Responsibilities + +- Monitor GitHub Actions usage and optimize costs +- Investigate and resolve workflow failures +- Update workflows for new services or changes +- Collaborate with security on image scanning +- Support demo environment deployments + + + +## Technology Stack + + + + +## System Integration + + + +### High Integration Level + +As CI/CD SME, you have **high system integration** - comprehensive understanding of how all system components interact through the build and deployment pipeline. + +**Integration Points:** + +1. **Source Code → CI/CD Pipeline** + - Git branches and tags trigger workflow runs + - Change detection determines which services rebuild + - Pre-commit hooks validate before CI runs + +2. **CI/CD Pipeline → Container Registry** + - Docker Buildx builds multi-arch images + - GHCR receives pushed images with tags (latest, beta, version-specific) + - Images are publicly accessible for deployments + +3. **Container Registry → Deployment** + - Terraform user_data scripts pull prebuilt images + - Docker Compose uses registry images by default + - Demo environment automatically rebuilds on main pushes (canary) + +4. **Deployment → Feedback** + - Health checks validate service startup + - Monitoring tracks deployment success/failure + - Failed deployments trigger alerts and investigation + +**System Knowledge:** + +- All three application services (UI, API, Engine) and their build requirements +- Infrastructure services (Postgres, RabbitMQ, Valkey) and dependencies +- Docker Compose configuration (production and development overlays) +- AWS infrastructure (EC2, Terraform) for demo deployments +- Git workflow (main, sirius-demo, feature branches) + + + +## Workflow Architecture + + + +### Parallel Build Architecture + +``` +┌─────────────────┐ +│ detect-changes │ ← Analyzes git diff, sets build flags +└────────┬────────┘ + │ + ├──────────┬──────────┬──────────┐ + ▼ ▼ ▼ ▼ + ┌────────┐ ┌────────┐ ┌──────────┐ │ + │build-ui│ │build-api│ │build-engine│ │ ← Run in parallel + └───┬────┘ └───┬────┘ └─────┬────┘ │ + │ │ │ │ + │ (2-3min) │ (1-2min) │ (1-2min)│ ← Prebuild validation + │ │ │ │ + │ (15-20m) │ (20-25m) │ (30-40m)│ ← Docker builds (parallel) + │ │ │ │ + └──────────┴────────────┴─────────┘ + │ + ▼ + ┌────────┐ + │ test │ ← Integration test with built images + └───┬────┘ + │ (5min) + ┬─────────┴─────────┬ + ▼ ▼ +┌───────────────┐ ┌──────────────┐ +│dispatch-demo- │ │dispatch-demo-│ +│ deployment │ │ canary │ ← Trigger deployments +└───────────────┘ └──────────────┘ +``` + +**Key Characteristics:** + +- **Parallel execution**: Longest job (Engine ~30-40m) sets total build time +- **Smart dependencies**: Test job waits for all builds, uses `always()` with result checks +- **Isolated validation**: Each build job has its own prebuild validation step +- **Flexible outputs**: Each job outputs `image_tag`, test job determines which to use + +### Job Descriptions + +**1. detect-changes** +- Analyzes git diff to determine which services changed +- Sets output flags: `sirius_ui_changes`, `sirius_api_changes`, `sirius_engine_changes` +- Triggers on: push to main/sirius-demo, PRs to main, repository_dispatch (submodule updates) +- Duration: ~30 seconds + +**2. build-ui (Parallel)** +- Validates UI code: `npm ci && npm run lint` (2-3 min) +- Builds Next.js container with Docker Buildx (15-20 min) +- Pushes to GHCR with tags: `latest`, `beta`, `pr-{number}`, version-specific +- Platforms: linux/amd64, linux/arm64 +- Output: `image_tag` + +**3. build-api (Parallel)** +- Validates API code: `go mod download && go test ./...` (1-2 min) +- Builds Go API container with submodule refs (20-25 min) +- Pushes to GHCR with same tagging strategy +- Build args: `GO_API_COMMIT_SHA` for go-api submodule +- Output: `image_tag` + +**4. build-engine (Parallel)** +- Validates Engine code: `go mod download && go test ./...` (1-2 min) +- Builds Go Engine container with all submodule refs (30-40 min) +- Pushes to GHCR with same tagging strategy +- Build args: GO_API, APP_SCANNER, APP_TERMINAL, SIRIUS_NSE, APP_AGENT commit SHAs +- Output: `image_tag` + +**5. test** +- Determines image tag from whichever build job succeeded +- Creates isolated test environment with docker-compose.test.yml +- Starts infrastructure (Postgres tmpfs, RabbitMQ, Valkey) +- Launches application services that were built +- Runs smoke tests and verifies health +- Cleans up test environment +- Duration: ~5 minutes + +**6. dispatch-demo-deployment** +- Triggers on push to `sirius-demo` branch after successful builds/tests +- Sends `repository_dispatch` event to `SiriusScan/sirius-demo` +- Event type: `sirius-demo-updated` +- Includes source repo/branch/SHA, actor, commit message + +**7. dispatch-demo-canary** +- Triggers on push to `main` branch after successful builds/tests +- Sends `repository_dispatch` event to `SiriusScan/sirius-demo` +- Event type: `sirius-main-updated` +- **Canary purpose**: Catches bad commits to main by immediately deploying to demo + +### Timing Analysis + +| Phase | Before (Sequential) | After (Parallel) | Improvement | +|-------|-------------------|-----------------|-------------| +| Change detection | ~30s | ~30s | - | +| Prebuild validation | N/A | ~2-3 min (all parallel) | New | +| Build UI | ~15-20 min | ~15-20 min | - | +| Build API | ~20-25 min | ~20-25 min | - | +| Build Engine | ~30-40 min | ~30-40 min | - | +| **Total build time** | **~65-85 min (serial)** | **~30-40 min (longest wins)** | **40-60% faster** | +| Integration test | ~5 min | ~5 min | - | +| **Total CI/CD** | **~70-90 min** | **~40-50 min** | **~30-40 min saved** | + + + +## Container Registry Integration + + + +### GitHub Container Registry (GHCR) + +**Registry URL**: `ghcr.io/siriusscan/` + +**Images:** +- `ghcr.io/siriusscan/sirius-ui:{tag}` +- `ghcr.io/siriusscan/sirius-api:{tag}` +- `ghcr.io/siriusscan/sirius-engine:{tag}` + +**Visibility**: Public (no authentication required for pulls) + +**Architecture**: Multi-arch (linux/amd64, linux/arm64) + +### Image Tagging Strategy + +**Production Tags:** +- `latest` - Latest stable build from main branch +- `beta` - Alias for latest (same image, different label) +- `v0.4.1` - Version-specific releases (semantic versioning) + +**Development Tags:** +- `pr-123` - Pull request builds (isolated testing) +- `dev` - Other branch builds + +**Tag Determination Logic:** +```yaml +if: github.event_name == 'pull_request' + TAG = "pr-${PR_NUMBER}" +elif: github.ref == 'refs/heads/main' + TAG = "latest" + ALSO_TAG_BETA = true +elif: github.event_name == 'repository_dispatch' + TAG = "latest" + ALSO_TAG_BETA = true +else: + TAG = "dev" +``` + +### Authentication + +**Build Pipeline Authentication:** +```yaml +- name: Log in to Container Registry + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ secrets.GHCR_PUSH_USER }} + password: ${{ secrets.GHCR_PUSH_TOKEN }} +``` + +**Required Secrets:** +- `GHCR_PUSH_USER`: GitHub username that generated the PAT +- `GHCR_PUSH_TOKEN`: Personal Access Token with scopes: + - `write:packages` (push images) + - `read:packages` (pull existing layers) + - `repo` (access repository context) + +**Why PAT?** Default `GITHUB_TOKEN` has read-only package permissions and cannot create new packages. PAT-based auth bypasses this limitation. + +### Deployment Integration + +**Production (Registry Images):** +```yaml +# docker-compose.yaml +services: + sirius-ui: + image: ghcr.io/siriusscan/sirius-ui:${IMAGE_TAG:-latest} + pull_policy: always +``` + +**Development (Local Builds):** +```yaml +# docker-compose.dev.yaml +services: + sirius-ui: + build: + context: ./sirius-ui/ + target: development + image: sirius-sirius-ui:dev # Override registry image +``` + +**Deployment Speed Comparison:** +| Method | Time | Use Case | +|--------|------|----------| +| Registry images | 5-8 min | Production, demo, staging | +| Local builds | 20-25 min | Development with code changes | + + + +## Code Patterns & Best Practices + + + +### Workflow Design Patterns + +#### ✅ GOOD: Parallel Independent Jobs + +```yaml +build-ui: + name: Build & Push UI + needs: detect-changes + runs-on: ubuntu-latest + if: needs.detect-changes.outputs.sirius_ui_changes == 'true' + outputs: + image_tag: ${{ steps.meta.outputs.image_tag }} + steps: + - name: Validate UI code + run: | + cd sirius-ui + npm ci + npm run lint + + - name: Build and push + uses: docker/build-push-action@v5 + with: + context: ./sirius-ui + platforms: linux/amd64,linux/arm64 + push: true + tags: ghcr.io/siriusscan/sirius-ui:${{ steps.meta.outputs.image_tag }} +``` + +**Why this works:** +- Independent of other build jobs (runs in parallel) +- Fast-fail validation before expensive Docker build +- Outputs `image_tag` for downstream jobs +- Uses conditional execution based on change detection + +#### ❌ BAD: Sequential Builds + +```yaml +# DON'T DO THIS - builds run serially +build-and-push: + steps: + - name: Build UI + run: docker build ./sirius-ui + + - name: Build API + run: docker build ./sirius-api + + - name: Build Engine + run: docker build ./sirius-engine +``` + +**Why this fails:** +- Builds run sequentially (total = sum of all builds) +- No early validation (fails late) +- Single failure blocks everything +- No parallelization benefits + +#### ✅ GOOD: Downstream Job Dependencies + +```yaml +test: + name: Integration Test + needs: [detect-changes, build-ui, build-api, build-engine] + runs-on: ubuntu-latest + if: always() && (needs.build-ui.result == 'success' || needs.build-api.result == 'success' || needs.build-engine.result == 'success') + steps: + - name: Determine image tag + id: tag + run: | + if [ "${{ needs.build-ui.result }}" == "success" ]; then + TAG="${{ needs.build-ui.outputs.image_tag }}" + elif [ "${{ needs.build-api.result }}" == "success" ]; then + TAG="${{ needs.build-api.outputs.image_tag }}" + else + TAG="${{ needs.build-engine.outputs.image_tag }}" + fi + echo "image_tag=$TAG" >> $GITHUB_OUTPUT +``` + +**Why this works:** +- Uses `always()` to run even if some builds skip +- Checks specific job results for success +- Flexible tag determination from whichever job ran +- Tests only what was actually built + +#### ❌ BAD: Hardcoded Dependencies + +```yaml +# DON'T DO THIS - assumes specific job output +test: + needs: build-and-push + steps: + - run: docker compose -f test.yml up + env: + IMAGE_TAG: latest # Hardcoded! +``` + +**Why this fails:** +- Doesn't use actual build outputs +- Can test wrong images (stale cache) +- No flexibility for PR builds or versions +- Breaks change detection optimization + +### Docker Buildx Patterns + +#### ✅ GOOD: Multi-Arch with Caching + +```yaml +- name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + +- name: Build and push + uses: docker/build-push-action@v5 + with: + context: ./sirius-ui + platforms: linux/amd64,linux/arm64 + push: true + tags: | + ghcr.io/siriusscan/sirius-ui:${{ steps.meta.outputs.image_tag }} + ${{ steps.meta.outputs.also_tag_beta == 'true' && 'ghcr.io/siriusscan/sirius-ui:beta' || '' }} + cache-from: type=gha + cache-to: type=gha,mode=max +``` + +**Why this works:** +- Builds for multiple architectures in single step +- Uses GitHub Actions cache to speed up builds +- Conditional tagging (beta only for main branch) +- Efficient layer caching across runs + +#### ❌ BAD: Separate Builds per Arch + +```yaml +# DON'T DO THIS - duplicates work +- name: Build amd64 + run: docker buildx build --platform linux/amd64 -t ui:amd64 . + +- name: Build arm64 + run: docker buildx build --platform linux/arm64 -t ui:arm64 . + +- name: Create manifest + run: docker manifest create ui:latest ui:amd64 ui:arm64 +``` + +**Why this fails:** +- Doubles build time (serial architecture builds) +- Complex manifest management +- No cache sharing between architectures +- More steps to maintain and debug + +### Change Detection Patterns + +#### ✅ GOOD: Smart Path Detection + +```yaml +- name: Determine Changed Files + id: changes + run: | + git diff --name-only $BASE_SHA $HEAD_SHA > changed_files.txt + + if grep -q "sirius-ui/" changed_files.txt; then + echo "sirius_ui_changes=true" >> $GITHUB_OUTPUT + fi + + if grep -q "sirius-api/" changed_files.txt; then + echo "sirius_api_changes=true" >> $GITHUB_OUTPUT + fi + + # Global changes rebuild everything + if grep -q -E "(Dockerfile|docker-compose|\.github/)" changed_files.txt; then + echo "sirius_ui_changes=true" >> $GITHUB_OUTPUT + echo "sirius_api_changes=true" >> $GITHUB_OUTPUT + echo "sirius_engine_changes=true" >> $GITHUB_OUTPUT + fi +``` + +**Why this works:** +- Selective builds save time (only changed services) +- Global changes (Docker, CI) trigger full rebuild +- Explicit output flags for downstream jobs +- Easy to debug with changed_files.txt + +#### ❌ BAD: Always Build Everything + +```yaml +# DON'T DO THIS - no optimization +jobs: + build: + steps: + - name: Build all services + run: docker compose build +``` + +**Why this fails:** +- Wastes time rebuilding unchanged services +- No benefit from parallelization +- Slower feedback loops +- Higher resource usage + +### Prebuild Validation Patterns + +#### ✅ GOOD: Fast-Fail Before Docker + +```yaml +- name: Validate UI code + run: | + cd sirius-ui + echo "Running UI validation..." + npm ci + npm run lint || echo "⚠️ Lint warnings present" + echo "✅ UI validation complete" + +- name: Build and push sirius-ui + uses: docker/build-push-action@v5 + # Only runs if validation succeeded +``` + +**Why this works:** +- Catches issues in 2-3 minutes vs 15-20 for full build +- Clear output with emojis for quick scanning +- Non-fatal warnings (continues to build) +- Saves expensive Docker build time on failures + +#### ❌ BAD: No Validation + +```yaml +# DON'T DO THIS - builds blindly +- name: Build and push + uses: docker/build-push-action@v5 + # Fails 15 minutes later on lint error +``` + +**Why this fails:** +- Long feedback loop (15-20 min to discover lint errors) +- Wastes CI minutes on preventable failures +- Docker layer cache pollution from failed builds +- Frustrating developer experience + + + +## Common Tasks + + + +### Add New Service to Parallel Builds + +```bash +# 1. Create build job in .github/workflows/ci.yml +``` + +```yaml +build-newservice: + name: Build & Push NewService + needs: detect-changes + runs-on: ubuntu-latest + if: needs.detect-changes.outputs.newservice_changes == 'true' + outputs: + image_tag: ${{ steps.meta.outputs.image_tag }} + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Generate metadata + id: meta + run: | + # Copy metadata logic from existing build jobs + # [tag determination logic] + echo "image_tag=$TAG" >> $GITHUB_OUTPUT + + - name: Validate code + run: | + cd newservice + # Add validation commands + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to GHCR + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ secrets.GHCR_PUSH_USER }} + password: ${{ secrets.GHCR_PUSH_TOKEN }} + + - name: Build and push + uses: docker/build-push-action@v5 + with: + context: ./newservice + platforms: linux/amd64,linux/arm64 + push: true + tags: ghcr.io/siriusscan/newservice:${{ steps.meta.outputs.image_tag }} + cache-from: type=gha + cache-to: type=gha,mode=max +``` + +```bash +# 2. Update detect-changes job +``` + +```yaml +- name: Determine Changed Files + id: changes + run: | + # ... existing logic ... + + if grep -q "newservice/" changed_files.txt; then + echo "newservice_changes=true" >> $GITHUB_OUTPUT + fi +``` + +```bash +# 3. Update test job dependencies +``` + +```yaml +test: + needs: [detect-changes, build-ui, build-api, build-engine, build-newservice] + if: always() && (needs.build-ui.result == 'success' || needs.build-api.result == 'success' || needs.build-engine.result == 'success' || needs.build-newservice.result == 'success') +``` + +```bash +# 4. Update dispatch job dependencies (both) +``` + +```yaml +dispatch-demo-deployment: + needs: [detect-changes, build-ui, build-api, build-engine, build-newservice, test] + if: github.ref == 'refs/heads/sirius-demo' && github.event_name == 'push' && always() && (needs.detect-changes.result == 'success' || needs.detect-changes.result == 'skipped') && (needs.build-ui.result == 'success' || needs.build-ui.result == 'skipped') && (needs.build-api.result == 'success' || needs.build-api.result == 'skipped') && (needs.build-engine.result == 'success' || needs.build-engine.result == 'skipped') && (needs.build-newservice.result == 'success' || needs.build-newservice.result == 'skipped') && (needs.test.result == 'success' || needs.test.result == 'skipped') +``` + +### Optimize Build Times + +```bash +# 1. Audit current timing +gh run list --workflow=ci.yml --limit 10 --json databaseId,status,conclusion,createdAt + +# 2. View specific run timing +gh run view --log | grep "took" + +# 3. Identify bottlenecks +# - Longest Docker build (typically Engine: 30-40 min) +# - Validation time (should be <3 min) +# - Cache effectiveness (check cache hits) + +# 4. Optimize strategies: + +# A. Improve Docker layer caching +# - Order Dockerfile commands from least to most frequently changed +# - Copy package files before source code +# - Use multi-stage builds to reduce final image size + +# B. Optimize validation +# - Run only essential checks (lint, not full test suite) +# - Cache dependencies (npm/go mod) +# - Use --prefer-offline for npm + +# C. Parallelize further +# - Split large services into smaller containers +# - Run tests in parallel with builds (if safe) +# - Use matrix builds for multiple versions +``` + +### Troubleshoot Build Failures + +```bash +# 1. Check recent runs +gh run list --workflow=ci.yml --limit 5 + +# 2. View failed run +gh run view + +# 3. Get detailed logs +gh run view --log > failure.log + +# 4. Common failure patterns: + +# A. "denied: installation not allowed" +# Fix: Use PAT authentication (GHCR_PUSH_USER/TOKEN) + +# B. "403 Forbidden" during push +# Fix: Check PAT has write:packages scope +# Fix: Verify package is public + +# C. "manifest unknown" +# Fix: Check image tag exists in GHCR +# Fix: Ensure build job completed successfully + +# D. Test job fails to pull images +# Fix: Check build job outputs match test job inputs +# Fix: Verify GHCR authentication in test job + +# E. Prebuild validation fails +# Fix: Run locally: cd sirius-ui && npm ci && npm run lint +# Fix: Update code to pass validation + +# 5. Manual testing +# Run workflow manually with specific branch/tag +gh workflow run ci.yml --ref feature-branch +``` + +### Update Image Tags for Deployment + +```bash +# 1. Tag new version +git tag -a v0.4.2 -m "Release v0.4.2" +git push origin v0.4.2 + +# 2. Wait for CI to build +gh run watch --interval 30 + +# 3. Verify images exist +docker pull ghcr.io/siriusscan/sirius-ui:v0.4.2 +docker pull ghcr.io/siriusscan/sirius-api:v0.4.2 +docker pull ghcr.io/siriusscan/sirius-engine:v0.4.2 + +# 4. Deploy with specific version +IMAGE_TAG=v0.4.2 docker compose pull +IMAGE_TAG=v0.4.2 docker compose up -d + +# 5. Verify deployment +docker compose ps +curl http://localhost:9001/health +curl http://localhost:3000/api/health +``` + +### Monitor CI/CD Performance + +```bash +# 1. Track build times over time +gh run list --workflow=ci.yml --json databaseId,status,conclusion,createdAt,updatedAt \ + | jq -r '.[] | [.databaseId, .status, (.updatedAt | fromdateiso8601 - (.createdAt | fromdateiso8601))] | @tsv' + +# 2. Check cache hit rates +gh run view --log | grep "cache hit" + +# 3. Monitor failure rates +gh run list --workflow=ci.yml --limit 50 --json status,conclusion \ + | jq '[.[] | .conclusion] | group_by(.) | map({key: .[0], count: length})' + +# 4. Identify most expensive steps +gh run view --log | grep "took" | sort -t: -k2 -n +``` + + + +## Troubleshooting + + + +### Build Performance Issues + +| Issue | Symptoms | Solution | +|-------|----------|----------| +| **Builds slower than expected** | Total time >50 min | Check if jobs running parallel (should see concurrent execution in Actions UI) | +| **Validation taking too long** | Prebuild >5 min | Optimize lint/test commands, use --prefer-offline for npm | +| **Docker builds slow** | Individual build >45 min | Check cache effectiveness, optimize Dockerfile layer ordering | +| **Test job slow** | Integration test >10 min | Use tmpfs for Postgres, reduce wait times, parallel service tests | + +### Authentication & Registry Issues + +| Issue | Symptoms | Solution | +|-------|----------|----------| +| **"denied: installation not allowed"** | Push fails at start | Use PAT auth (GHCR_PUSH_USER/TOKEN), not default GITHUB_TOKEN | +| **"403 Forbidden" during push** | Push fails mid-stream | Verify PAT has `write:packages` and `read:packages` scopes | +| **"manifest unknown" locally** | `docker pull` fails | Check image exists in GHCR UI, verify tag name matches | +| **Can't pull images** | Deployment fails | For public repos, should work without auth; check network/DNS | + +### Workflow Logic Errors + +| Issue | Symptoms | Solution | +|-------|----------|----------| +| **Jobs not running** | Expected jobs skip | Check `if` conditions and `needs` dependencies | +| **Test uses wrong images** | Old code deployed | Verify test job uses build outputs, not hardcoded tags | +| **Dispatch doesn't trigger** | Demo not updating | Check `repository_dispatch` event types match in both repos | +| **Build runs on unchanged service** | Unnecessary builds | Review change detection logic, check git diff paths | + +### Common Errors + +**Error:** `Error: buildx failed with: ERROR: failed to solve: failed to push` + +**Cause:** Buildx failed to push to GHCR, typically auth or permissions + +**Fix:** +```bash +# 1. Verify secrets exist +gh secret list + +# 2. Check PAT scopes +# Visit https://github.com/settings/tokens +# Ensure write:packages, read:packages, repo checked + +# 3. Test local authentication +echo "$PAT" | docker login ghcr.io -u USERNAME --password-stdin +docker pull ghcr.io/siriusscan/sirius-ui:latest + +# 4. Regenerate secrets if needed +# Create new PAT, update GHCR_PUSH_TOKEN secret +``` + +**Error:** `Error: Unable to locate executable file: act` + +**Cause:** GitHub Actions local runner (`act`) not installed + +**Fix:** +```bash +# Install act (macOS) +brew install act + +# Install act (Linux) +curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash + +# Test workflow locally (optional) +act push --secret-file .secrets -W .github/workflows/ci.yml +``` + +**Error:** Test job fails with `Error response from daemon: manifest unknown` + +**Cause:** Build job didn't push images or test job using wrong tag + +**Fix:** +```bash +# 1. Check build job succeeded and outputs exist +gh run view --log | grep "image_tag=" + +# 2. Verify test job is using correct output +# Should see: TAG="${{ needs.build-ui.outputs.image_tag }}" + +# 3. Check images exist in GHCR +curl -H "Authorization: Bearer $TOKEN" \ + https://ghcr.io/v2/siriusscan/sirius-ui/tags/list + +# 4. Verify test job authentication +# Should have docker login step with GHCR_PUSH credentials +``` + +### Debugging Commands + +```bash +# View workflow run details +gh run view + +# Get specific job logs +gh run view --log --job= + +# List workflow runs +gh run list --workflow=ci.yml --limit 20 + +# Watch workflow execution +gh run watch --interval 10 + +# Re-run failed jobs +gh run rerun --failed + +# Download workflow artifacts +gh run download + +# Check workflow syntax locally +actionlint .github/workflows/ci.yml +``` + + + +## Best Practices + + + +### Workflow Design + +✅ **DO:** +- Use parallel jobs for independent services (UI/API/Engine) +- Add prebuild validation before expensive Docker builds (lint/test) +- Use `always()` with specific result checks for flexible dependencies +- Output consistent metadata (`image_tag`) from all build jobs +- Implement smart change detection to skip unnecessary builds +- Cache Docker layers and dependencies (GitHub Actions cache) +- Use multi-stage Dockerfiles to reduce final image sizes + +❌ **DON'T:** +- Build services sequentially when they're independent +- Skip prebuild validation to "save time" (costs more later) +- Use hardcoded tags/values (breaks version deployments) +- Build without change detection (wastes resources) +- Ignore cache strategies (longer builds every time) +- Create monolithic workflows (hard to maintain/debug) + +### Container Registry + +✅ **DO:** +- Use specific version tags for production deployments (`v0.4.1`) +- Tag `latest` and `beta` on main branch pushes +- Build multi-arch images (amd64, arm64) in single step +- Make packages public for open-source projects +- Use PAT auth for pushing (not default GITHUB_TOKEN) +- Monitor image sizes and optimize regularly + +❌ **DON'T:** +- Use `latest` in production (hard to rollback) +- Build architectures separately (doubles time) +- Forget to set package visibility (blocks deployments) +- Rely on default GITHUB_TOKEN (lacks package create permission) +- Let images grow unbounded (slow pulls, wasted storage) + +### Performance Optimization + +✅ **DO:** +- Profile builds regularly to identify bottlenecks +- Optimize Docker layer caching (least→most frequently changed) +- Use GitHub Actions cache for dependencies and layers +- Run only essential validation before builds (full tests after) +- Consider splitting large services into smaller containers +- Monitor CI minutes usage and adjust strategies + +❌ **DON'T:** +- Optimize prematurely (profile first) +- Skip validation to "save time" (false economy) +- Run full test suites before builds (slow feedback) +- Ignore cache hit rates (free speedups) +- Over-parallelize (resource contention hurts) + +### Debugging & Monitoring + +✅ **DO:** +- Include clear step names and emojis for quick scanning +- Log key decisions and values (`echo` in workflow steps) +- Use structured logging with timestamps +- Monitor success/failure rates over time +- Track build timing trends to catch regressions +- Document common issues and solutions + +❌ **DON'T:** +- Use cryptic step names ("Step 1", "Build", etc.) +- Skip logging important values (hard to debug) +- Ignore workflow failures as "transient" (may indicate issues) +- Let build times gradually increase (death by a thousand cuts) +- Repeat troubleshooting from scratch (document once) + +### Security + +✅ **DO:** +- Scan images for vulnerabilities regularly +- Use minimal base images (Alpine, distroless) +- Pin dependency versions for reproducibility +- Rotate PATs regularly (at least annually) +- Limit PAT scopes to minimum required +- Use GitHub's Dependabot for dependency updates + +❌ **DON'T:** +- Skip vulnerability scanning (catch issues early) +- Use full OS images when minimal would work +- Use `latest` tags for base images (non-reproducible) +- Share PATs or commit them to code +- Grant excessive PAT permissions ("just in case") +- Ignore security alerts on dependencies + + + +## Quick Reference + + + +### Essential Commands + +```bash +# Monitor CI/CD +gh run list --workflow=ci.yml --limit 5 +gh run watch --interval 30 +gh run view --log + +# Trigger builds +git push origin main # Auto-trigger +gh workflow run ci.yml --ref main # Manual trigger + +# Container registry +docker pull ghcr.io/siriusscan/sirius-ui:latest +IMAGE_TAG=v0.4.1 docker compose pull +docker login ghcr.io -u USERNAME + +# Validation +actionlint .github/workflows/ci.yml # Workflow syntax +make validate-docker-compose # Compose files + +# Debug +gh run rerun --failed # Retry failed jobs +gh run download # Download artifacts +``` + +### Key File Locations + +**Workflows:** `.github/workflows/ci.yml` +**Compose (prod):** `docker-compose.yaml` +**Compose (dev):** `docker-compose.dev.yaml` +**Documentation:** `documentation/dev/deployment/README.workflows.md` +**Registry:** `https://ghcr.io/siriusscan/` + +### Timing Targets + +| Phase | Target | Actual | Status | +|-------|--------|--------|--------| +| Change detection | <1 min | ~30s | ✅ | +| Prebuild validation | <3 min | 1-3 min | ✅ | +| Parallel builds | <45 min | 30-40 min | ✅ | +| Integration test | <7 min | ~5 min | ✅ | +| **Total CI/CD** | **<50 min** | **40-50 min** | ✅ | + +### Image Tags Reference + +| Tag | When Created | Use Case | +|-----|-------------|----------| +| `latest` | Every main push | Default production | +| `beta` | Every main push | Beta testing | +| `v0.4.1` | Version tag | Specific release | +| `pr-123` | Pull request | PR testing | +| `dev` | Other branches | Development | + +### Workflow Job Graph + +``` +detect-changes → [build-ui, build-api, build-engine] → test → [dispatch-demo-deployment, dispatch-demo-canary] +``` + +**Parallel:** build-ui, build-api, build-engine +**Sequential:** detect-changes → builds → test → dispatch +**Total parallelism:** 3x (three build jobs concurrent) + + + +--- + +**Last Updated:** 2025-11-14 +**Version:** 1.0.0 +**Maintainer:** Sirius Team + +**Note:** This identity represents deep expertise in the Sirius CI/CD pipeline, reflecting the recent architectural improvements that achieved 40-60% faster build times through parallelization and container registry integration. + diff --git a/.cursor/agents/templates/github-commits.template.md b/.cursor/agents/templates/github-commits.template.md new file mode 100644 index 0000000..9e75083 --- /dev/null +++ b/.cursor/agents/templates/github-commits.template.md @@ -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) + + + +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. + + + +## Key Documentation + + + + +## Project Location + + + + +## Core 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. + + + +## Commit Safety Guardrails + + + +- 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. + + + +## Standard 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. + + + +## 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" + + diff --git a/.cursor/agents/templates/maintainer-ops.template.md b/.cursor/agents/templates/maintainer-ops.template.md new file mode 100644 index 0000000..bb0e35a --- /dev/null +++ b/.cursor/agents/templates/maintainer-ops.template.md @@ -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) + + + +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. + + + +## Key Documentation + + + + +## Project Location + + + + +## Core 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. + + + +## Technology Stack + + + + +## Maintainer 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. + + + +## Command Reference + + + +- `/triage needs-info` +- `/triage repro-ready` +- `/triage confirmed` +- `/test health` +- `/test integration` +- `/test security api|trpc|grpc|services|headers|auth-surface` + + + +## 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. + + + +## 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` + + diff --git a/.cursor/agents/templates/scanning-engine-engineer.template.md b/.cursor/agents/templates/scanning-engine-engineer.template.md new file mode 100644 index 0000000..551f156 --- /dev/null +++ b/.cursor/agents/templates/scanning-engine-engineer.template.md @@ -0,0 +1,1426 @@ +--- +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" + - "documentation/dev/architecture/ARCHITECTURE.nse-repository-management.md" +dependencies: + - "../minor-projects/app-scanner" + - "../minor-projects/go-api" + - "../minor-projects/sirius-nse" +llm_context: "high" +context_window_target: 1400 +--- + +# Scanning Engine Engineer (Go/Nmap/NSE) + + + +Develops and maintains Sirius Scanner, a sophisticated vulnerability scanning engine that orchestrates security tools (Nmap, RustScan, Naabu) through a message-driven architecture. This role combines security research expertise with distributed systems engineering to deliver accurate, scalable vulnerability assessments. + +**Core Focus Areas:** + +- **Vulnerability Scanning**: Deep understanding of CVE detection, NSE script execution, and vulnerability enrichment via NVD API +- **Tool Orchestration**: Integrating and optimizing security scanning tools (Nmap, RustScan, Naabu) for maximum effectiveness +- **Distributed Processing**: Worker pool patterns, concurrent scanning, message queue coordination +- **Security Research**: NSE script curation, vulnerability pattern recognition, false positive reduction + +**Philosophy:** + +Effective vulnerability scanning requires balancing thoroughness with performance, accuracy with speed. Every scan must be traceable (source attribution), respectful (rate limiting), and actionable (enriched CVE data). The scanner is a precision instrument, not a blunt weapon. + +**System Integration (High Level):** + +The scanner operates as the core security assessment engine within Sirius, consuming scan requests from RabbitMQ, coordinating with ValKey for real-time state, submitting enriched results to PostgreSQL via the API, and maintaining a curated NSE script repository. Understanding the entire scan lifecycle—from message receipt to result persistence—is essential. + + + +## Key Documentation + + + + +## Project Location + + + + +## Core Responsibilities + + + +### Primary Responsibilities + +1. **Scanner Development** + + - Implement and optimize multi-phase scanning workflow (enumeration → discovery → vulnerability) + - Develop new scan strategies following the Strategy pattern + - Integrate additional security scanning tools + - Maintain worker pool concurrency for efficient parallel scanning + +2. **NSE Script Management** + + - Curate and maintain sirius-nse repository with validated scripts + - Implement script selection logic (protocol-based and template-based) + - Manage script blacklist to exclude problematic/slow scripts + - Synchronize script repository via Git automation + +3. **Template System** + + - Design and implement system templates (quick, high-risk, comprehensive) + - Enable custom template creation and management + - Optimize template script combinations for effectiveness vs performance + - Validate template configurations for security and accuracy + +4. **Source Attribution** + + - Track comprehensive scan metadata (tool versions, configurations, system info) + - Implement source-aware API integration for result submission + - Ensure complete audit trails for compliance requirements + - Enable analytics on scan effectiveness and tool performance + +5. **State Management** + + - Maintain real-time scan progress in ValKey for UI updates + - Implement structured logging to RabbitMQ for audit trails + - Coordinate distributed state across message queue and KV store + - Handle graceful shutdown and context cancellation + +6. **NSE Repository Management Architecture** + + > **Critical**: The scanner is the SOLE owner of NSE repository management. NO other components should manage repositories. + + **Runtime Repository Management:** + + - `RepoManager` (`internal/nse/repo.go`) - Clones Git repositories dynamically at runtime + - `SyncManager` (`internal/nse/sync.go`) - Synchronizes repository contents to ValKey (source of truth) + - Manages repositories at `/opt/sirius/nse/` + - Configured via `manifest.json` (supports arbitrary number of repositories) + + **ValKey Integration:** + + - `nse:repo-manifest` - Repository list configuration + - `nse:manifest` - Complete script manifest (612+ scripts) + - `nse:script:` - Individual script content + + **Integration Boundaries:** + + - **Scanner**: Manages repos, syncs to ValKey (file system + ValKey write) + - **ValKey**: Source of truth for scripts (storage) + - **UI/API**: Display scripts, manage profiles (ValKey READ-ONLY) + + **Anti-Patterns to AVOID:** + + - ❌ NEVER clone repositories in Dockerfiles (breaks dynamic management) + - ❌ NEVER have UI/API read from `/opt/sirius/nse/` file system + - ❌ NEVER have non-scanner components populate ValKey script data + - ❌ NEVER create Docker volume mounts to sirius-nse for UI/API + + **Best Practices:** + + - ✅ ALWAYS read scripts from ValKey in UI/API components + - ✅ ALWAYS let scanner manage repository lifecycle + - ✅ ALWAYS use ValKey as the integration point + + **See**: [ARCHITECTURE.nse-repository-management.md](../documentation/dev/architecture/ARCHITECTURE.nse-repository-management.md) for complete architectural details + +### Secondary Responsibilities + +- Performance optimization (scan speed, memory usage, network efficiency) +- Error handling and resilience (network failures, tool crashes, timeout management) +- Security considerations (rate limiting, responsible scanning practices) +- Documentation and knowledge sharing (code comments, architecture docs) + + + +## Technology Stack + + + + +## Development Workflow + + + +### Container-Based Development + +**Development Mode:** + +All scanner development happens inside the `sirius-engine` container with live reload: + +```bash +# Start development environment +docker compose -f docker-compose.dev.yaml up -d sirius-engine + +# View scanner logs +docker logs -f sirius-engine | grep scanner + +# Access container shell +docker exec -it sirius-engine /bin/bash + +# Code changes in ../minor-projects/app-scanner automatically trigger rebuild (Air) +``` + +**File Structure:** + +- **Local Editing**: `../minor-projects/app-scanner/` (volume-mounted to `/app-scanner`) +- **Container Build**: Air watches for changes and rebuilds to `/tmp/scanner` +- **Production Binary**: Pre-compiled at `/app-scanner-src/scanner` (fallback) + +### Testing Workflow + +**Unit Tests:** + +```bash +docker exec sirius-engine bash -c "cd /app-scanner && go test ./internal/scan/... -v" +``` + +**Integration Tests:** + +```bash +docker exec sirius-engine bash -c "cd /app-scanner && go run cmd/scan-full-test/main.go" +``` + +**Manual Tool Testing:** + +```bash +# Test Nmap directly +docker exec sirius-engine nmap -sV --script vulners 192.168.1.100 + +# Test NSE script availability +docker exec sirius-engine nmap --script-help smb-vuln-ms17-010 + +# Test RustScan +docker exec sirius-engine rustscan -a 192.168.1.100 +``` + +### NSE Script Development + +**Repository Location:** `../minor-projects/sirius-nse/` + +**Workflow:** + +1. Add/modify scripts in `sirius-nse/scripts/` +2. Update manifest in `sirius-nse/manifest.json` +3. Test script manually: `nmap --script ` +4. Commit and push to sirius-nse repository +5. Scanner syncs automatically on next startup + +**Script Validation:** + +```bash +# Validate script syntax +nmap --script-help + +# Test script output parsing +nmap -sV --script -oX - | xmllint --format - +``` + +### Adding New Scan Strategies + +**1. Implement Strategy Interface:** + +```go +// internal/scan/strategies.go +type MyToolStrategy struct { + Config MyToolConfig +} + +func (s *MyToolStrategy) Execute(target string) (sirius.Host, error) { + // Call external tool via exec.Command + cmd := exec.Command("mytool", "--scan", target) + output, err := cmd.Output() + if err != nil { + return sirius.Host{}, err + } + + // Parse output into sirius.Host format + host := parseMyToolOutput(output) + return host, nil +} +``` + +**2. Update Factory:** + +```go +// internal/scan/factory.go +func (f *ScanToolFactory) CreateTool(toolType string) ScanStrategy { + switch toolType { + case "mytool": + return &MyToolStrategy{ + Config: f.currentOptions.MyToolConfig, + } + // ... existing cases + } +} +``` + +**3. Write Tests:** + +```go +// internal/scan/strategies_test.go +func TestMyToolStrategy_Execute(t *testing.T) { + strategy := &MyToolStrategy{Config: defaultConfig} + host, err := strategy.Execute("192.168.1.100") + + assert.NoError(t, err) + assert.Equal(t, "192.168.1.100", host.IP) + assert.NotEmpty(t, host.Ports) +} +``` + +**4. Install Tool in Dockerfile:** + +```dockerfile +# sirius-engine/Dockerfile +RUN apt-get install -y mytool +``` + + + +## Code Patterns & Best Practices + + + +### Strategy Pattern for Scanning Tools + +**✅ DO: Implement clean strategy interface** + +```go +// Good: Clean interface, single responsibility +type ScanStrategy interface { + Execute(target string) (sirius.Host, error) +} + +type NmapStrategy struct { + ScriptList []string +} + +func (n *NmapStrategy) Execute(target string) (sirius.Host, error) { + // Execute Nmap scan + // Parse results + // Return structured data + return host, nil +} +``` + +**❌ DON'T: Tightly couple strategy implementations** + +```go +// Bad: Direct dependency on other strategies +type VulnStrategy struct { + discoveryTool *RustScanStrategy // Tight coupling +} +``` + +### Worker Pool Concurrency + +**✅ DO: Use channels for task distribution** + +```go +// Good: Channel-based worker pool +type WorkerPool struct { + taskQueue chan ScanTask + workers []*Worker +} + +func (wp *WorkerPool) worker(ctx context.Context) { + for { + select { + case task := <-wp.taskQueue: + wp.processTask(task) + case <-ctx.Done(): + return // Graceful shutdown + } + } +} +``` + +**❌ DON'T: Create unbounded goroutines** + +```go +// Bad: Goroutine per task without limits +for _, ip := range ips { + go scanIP(ip) // Can create thousands of goroutines +} +``` + +### Error Handling in Scanning + +**✅ DO: Wrap errors with context** + +```go +// Good: Contextual error wrapping +func (s *NmapStrategy) Execute(target string) (sirius.Host, error) { + output, err := executeNmap(target) + if err != nil { + return sirius.Host{}, fmt.Errorf("nmap execution failed for %s: %w", target, err) + } + + host, err := parseNmapOutput(output) + if err != nil { + return sirius.Host{}, fmt.Errorf("failed to parse nmap output for %s: %w", target, err) + } + + return host, nil +} +``` + +**❌ DON'T: Swallow errors silently** + +```go +// Bad: Silent error suppression +output, _ := executeNmap(target) // Error ignored! +if output == "" { + return sirius.Host{}, nil // Wrong: doesn't indicate error occurred +} +``` + +### NSE Script Selection + +**✅ DO: Use manifest-based selection** + +```go +// Good: Manifest-driven script selection +func (ss *ScriptSelector) BuildNmapScriptFlag(protocols ...string) (string, error) { + scripts := []string{} + + for _, script := range ss.manifest.Scripts { + if ss.matchesProtocol(script, protocols) && !ss.isBlacklisted(script.Name) { + scripts = append(scripts, script.Name) + } + } + + return strings.Join(scripts, ","), nil +} +``` + +**❌ DON'T: Hardcode script lists** + +```go +// Bad: Hardcoded scripts, no flexibility +func getScripts() []string { + return []string{"vulners", "smb-vuln-ms17-010", "http-enum"} // Inflexible +} +``` + +### Source Attribution + +**✅ DO: Capture comprehensive metadata** + +```go +// Good: Rich source attribution +func (sm *ScanManager) createScanSource(toolName string) models.ScanSource { + version := sm.detectScannerVersion(toolName) + systemInfo := sm.getSystemInfo() + + config := buildConfigString( + sm.currentScanOptions, + systemInfo, + sm.currentScanID, + ) + + return models.ScanSource{ + Name: toolName, + Version: version, + Config: config, + } +} +``` + +**❌ DON'T: Use minimal attribution** + +```go +// Bad: Insufficient source tracking +func createSource(tool string) models.ScanSource { + return models.ScanSource{ + Name: tool, // No version, no config, no context + } +} +``` + +### ValKey State Updates + +**✅ DO: Use atomic update functions** + +```go +// Good: Atomic state updates +func (su *ScanUpdater) Update(ctx context.Context, updateFn func(*ScanResult) error) error { + // Read current state + current, _ := su.kvStore.GetValue(ctx, su.scanKey) + + // Apply update function + var scan ScanResult + json.Unmarshal([]byte(current.Message.Value), &scan) + if err := updateFn(&scan); err != nil { + return err + } + + // Write updated state + updated, _ := json.Marshal(scan) + return su.kvStore.SetValue(ctx, su.scanKey, string(updated)) +} +``` + +**❌ DON'T: Perform non-atomic updates** + +```go +// Bad: Race condition potential +func updateScan() { + scan := getScan() // Read + scan.HostsCompleted++ // Modify + time.Sleep(100 * time.Millisecond) // Another goroutine could update here + saveScan(scan) // Write (could overwrite other updates) +} +``` + +### Vulnerability Enrichment + +**✅ DO: Enrich CVEs with NVD data** + +```go +// Good: NVD enrichment with fallback +func expandVulnerability(vuln sirius.Vulnerability) sirius.Vulnerability { + cveDetails, err := nvd.GetCVE(vuln.VID) + if err != nil { + log.Printf("Warning: NVD lookup failed for %s: %v", vuln.VID, err) + // Set defaults + vuln.RiskScore = 5.0 + vuln.Description = fmt.Sprintf("No description available for %s", vuln.VID) + return vuln + } + + // Use NVD data + vuln.Description = cveDetails.Descriptions[0].Value + vuln.RiskScore = cveDetails.Metrics.CvssMetricV31[0].CvssData.BaseScore + return vuln +} +``` + +**❌ DON'T: Leave CVEs unenriched** + +```go +// Bad: Raw CVE IDs without context +func extractCVEs(output string) []sirius.Vulnerability { + vulns := []sirius.Vulnerability{} + for _, cve := range findCVEs(output) { + vulns = append(vulns, sirius.Vulnerability{ + VID: cve, // Only ID, no description/score + }) + } + return vulns +} +``` + +### Rate Limiting & Respectful Scanning + +**✅ DO: Implement scanning best practices** + +```go +// Good: Reasonable defaults +const ( + DEFAULT_WORKERS = 10 // Limit concurrent scans + DEFAULT_NMAP_TIMING = "-T4" // Balanced timing (not aggressive -T5) + DEFAULT_TIMEOUT = 5 * time.Minute +) + +// Use worker pool to naturally rate limit +sm.workerPool = NewWorkerPool(DEFAULT_WORKERS, sm) +``` + +**❌ DON'T: Scan aggressively without limits** + +```go +// Bad: Unlimited concurrency, aggressive timing +for _, ip := range allIPs { + go func(ip string) { + exec.Command("nmap", "-T5", "-sS", "-p-", ip).Run() // DoS risk + }(ip) +} +``` + + + +## Critical: Canonical Scan Types + + + +**The scanner ONLY accepts three canonical scan type names. This is non-negotiable.** + +| Scan Type | Tool | Purpose | +| --------------- | ---------- | ------------------------------- | +| `enumeration` | NAABU | Fast port enumeration | +| `discovery` | RustScan | Host/service discovery | +| `vulnerability` | Nmap + NSE | Security vulnerability scanning | + +**❌ INVALID NAMES (will silently fail):** + +- `service-detection` → Use `discovery` +- `vuln-scan` → Use `vulnerability` +- `port-scan` → Use `enumeration` +- Tool names (`nmap`, `rustscan`, `naabu`) + +**Why strict naming?** + +- Ensures consistent tool routing +- Prevents silent scan failures +- Makes logs clear and searchable +- Enables proper validation + +**Warning signs of incorrect scan types:** + +``` +⚠️ Unknown scan type 'service-detection' for 192.168.1.100 +✅ All scan phases completed (0 seconds) <-- No actual scanning! +``` + +**Correct template format:** + +```json +{ + "scan_options": { + "scan_types": ["discovery", "vulnerability"], + "port_range": "1-10000" + } +} +``` + +**See:** `../minor-projects/app-scanner/SCAN-TYPES.md` for complete documentation. + + + +## Port Range Configuration + + + +**Every scan type respects the `port_range` setting from templates.** + +The port range flows through the entire scanning pipeline: + +``` +Template → ScanOptions → Factory → Strategy → Tool +``` + +**Supported formats:** + +- Single port: `"80"` +- Range: `"1-1000"` +- List: `"80,443,8080,8443"` +- Top ports: `"top500"` (for quick template) + +**Common port ranges:** + +- **Quick scans:** `"1-1000"` or `"top500"` +- **Balanced:** `"1-10000"` +- **Comprehensive:** `"1-65535"` +- **Targeted:** `"80,443,445,3389"` (specific services) + +**All tools respect port range:** + +- NAABU (`enumeration`) - Scans specified ports +- RustScan (`discovery`) - Scans specified ports +- Nmap (`vulnerability`) - Scans specified ports with NSE scripts + +**If missing:** Tools fall back to defaults (often wrong for your use case) + +**Best practice:** Always specify explicit port ranges in templates. + + + +## Configuration Examples + + + + +## Common Tasks + + + +### Send a Scan Request + +**Via RabbitMQ CLI:** + +```bash +# Quick scan of single IP +rabbitmqadmin publish exchange=amq.default routing_key=scan \ + payload='{"id":"scan-001","targets":[{"value":"192.168.1.100","type":"single_ip"}],"options":{"template_id":"quick"},"priority":3}' + +# High-risk scan of subnet +rabbitmqadmin publish exchange=amq.default routing_key=scan \ + payload='{"id":"scan-002","targets":[{"value":"192.168.1.0/24","type":"cidr"}],"options":{"template_id":"high-risk","parallel":true},"priority":4}' +``` + +**Via Go Code:** + +```go +import "github.com/SiriusScan/go-api/sirius/queue" + +scanMsg := map[string]interface{}{ + "id": uuid.New().String(), + "targets": []map[string]string{ + {"value": "192.168.1.100", "type": "single_ip"}, + }, + "options": map[string]interface{}{ + "template_id": "high-risk", + "scan_types": []string{"discovery", "vulnerability"}, + }, + "priority": 4, +} + +msgBytes, _ := json.Marshal(scanMsg) +queue.Publish("scan", string(msgBytes)) +``` + +### Monitor Scan Progress + +**Check ValKey State:** + +```bash +# View current scan state +docker exec sirius-valkey valkey-cli GET scan:scan-001 + +# Monitor in real-time +watch -n 1 'docker exec sirius-valkey valkey-cli GET scan:scan-001 | jq .' +``` + +**View Scanner Logs:** + +```bash +# Follow scanner logs +docker logs -f sirius-engine | grep scanner + +# Filter for specific scan +docker logs sirius-engine | grep "scan-001" + +# View RabbitMQ logs queue +docker exec sirius-rabbitmq rabbitmqctl list_queues name messages +``` + +### Create Custom Template + +**Define Template:** + +```go +template := &Template{ + ID: "web-vuln", + Name: "Web Vulnerability Scan", + Description: "Focused web application security assessment", + Type: CustomTemplate, + EnabledScripts: []string{ + "vulners", + "http-enum", + "http-shellshock", + "http-sql-injection", + "http-csrf", + "ssl-cert", + "ssl-heartbleed", + }, + ScanOptions: TemplateOptions{ + ScanTypes: []string{"discovery", "vulnerability"}, + PortRange: "80,443,8080,8443", + Aggressive: false, + MaxRetries: 2, + Parallel: true, + ExcludePorts: []string{}, + }, +} + +// Save to ValKey via TemplateManager +tm.CreateTemplate(ctx, template) +``` + +**Test Template:** + +```bash +rabbitmqadmin publish exchange=amq.default routing_key=scan \ + payload='{"id":"test-web","targets":[{"value":"example.com","type":"dns_name"}],"options":{"template_id":"web-vuln"},"priority":3}' +``` + +### Debug NSE Script Issues + +**Check Script Availability:** + +```bash +# List all available scripts +docker exec sirius-engine ls /opt/sirius/nse/sirius-nse/scripts/ + +# Check if specific script exists +docker exec sirius-engine ls /opt/sirius/nse/sirius-nse/scripts/ | grep vulners + +# Verify script syntax +docker exec sirius-engine nmap --script-help vulners +``` + +**Test Script Manually:** + +```bash +# Run script against target +docker exec sirius-engine nmap -sV --script vulners 192.168.1.100 -oX - + +# Run with debug output +docker exec sirius-engine nmap -sV --script vulners --script-trace 192.168.1.100 +``` + +**Check Symlink:** + +```bash +# Verify Nmap sees sirius-nse scripts +docker exec sirius-engine ls -la /usr/local/share/nmap/scripts +# Should point to: /opt/sirius/nse/sirius-nse/scripts +``` + +**Force Repository Sync:** + +```bash +# Remove cached repo +docker exec sirius-engine rm -rf /opt/sirius/nse/sirius-nse + +# Restart container (will re-clone on startup) +docker restart sirius-engine +``` + +### Optimize Scan Performance + +**Adjust Worker Count:** + +```go +// internal/scan/manager.go +const DEFAULT_WORKERS = 20 // Increase for faster subnet scans +``` + +**Use Quick Template:** + +```json +{ + "options": { + "template_id": "quick", + "port_range": "80,443,22,3389" + } +} +``` + +**Enable Parallel Processing:** + +```json +{ + "options": { + "parallel": true, + "scan_types": ["vulnerability"] + } +} +``` + +**Profile Memory Usage:** + +```bash +# Monitor resource usage +docker stats sirius-engine + +# Generate Go profiling data +docker exec sirius-engine curl http://localhost:6060/debug/pprof/heap > heap.prof +go tool pprof heap.prof +``` + +### Add Script to Blacklist + +**Edit Blacklist:** + +```go +// internal/nse/script_blacklist.go +var DefaultBlacklist = map[string]bool{ + "broadcast-dhcp-discover": true, + "firewalk": true, + "http-slowloris-check": true, + "my-problematic-script": true, // Add new entry +} +``` + +**Rebuild Scanner:** + +```bash +# Development mode: Air rebuilds automatically +# Production mode: rebuild and restart container +docker compose up -d --build sirius-engine +``` + + + +## System Integration + + + +The scanner operates as a **central security assessment engine** with deep integration across the Sirius platform: + +### Message Queue Integration (RabbitMQ) + +**Input Queue: `scan`** + +- Receives `ScanMessage` JSON from UI/API +- Supports priority-based processing (1-5) +- Handles target expansion (IPs, ranges, CIDRs, DNS) +- Validates message format and parameters + +**Output Queue: `scanner_logs`** + +- Publishes structured JSON logs for audit trail +- Event types: scan_initiated, host_discovered, vulnerability_found, scan_completed +- Consumed by logging infrastructure (Elasticsearch, file storage) + +**Error Handling:** + +- Failed scans logged but don't block queue +- Automatic retry logic (configurable via `MaxRetries`) +- Dead letter queue for unprocessable messages (future) + +### Key-Value Store (ValKey) + +**Real-Time State:** + +- Key pattern: `scan:` +- Stores: status, progress, hosts, vulnerabilities +- Updates: Atomic via `ScanUpdater.Update()` pattern +- Expiration: 24 hours after scan completion + +**Template Storage:** + +- Key pattern: `template:` +- System templates initialized on startup +- Custom templates persisted indefinitely +- Template list at `templates:list` and `templates:system` + +**Access Pattern:** + +```go +// Get scan state +scanResult, _ := kvStore.GetValue(ctx, "scan:scan-001") + +// Update scan state atomically +scanUpdater.Update(ctx, func(scan *ScanResult) error { + scan.HostsCompleted++ + return nil +}) +``` + +### Database Integration (PostgreSQL via API) + +**Source-Aware Submission:** + +- Endpoint: `POST /host/with-source` +- Includes: Host data + ScanSource metadata +- Schema: `hosts` table with `scan_source_id` foreign key +- Enables: Tool version tracking, config auditing, performance analytics + +**Request Format:** + +```json +{ + "host": { + "ip": "192.168.1.100", + "ports": [...], + "services": [...], + "vulnerabilities": [...] + }, + "source": { + "name": "nmap", + "version": "7.94", + "config": "ports:1-10000;aggressive:true;template:high-risk;..." + } +} +``` + +**Data Flow:** + +``` +Scanner → API (REST) → PostgreSQL + ↓ + ValKey (state) +``` + +### External API Integration (NVD) + +**CVE Enrichment:** + +- API: `nvd.GetCVE(cveID string)` +- Fetches: Descriptions, CVSS scores, references +- Rate Limiting: Respects NVD API limits +- Caching: Future enhancement (reduce API calls) + +**Enrichment Process:** + +1. Extract CVE-YYYY-NNNNN from NSE script output +2. Query NVD API for full CVE details +3. Parse descriptions (prefer English) +4. Extract CVSS scores (v3.1 > v3.0 > v2) +5. Merge into vulnerability record + +### NSE Repository (Git) + +**Synchronization:** + +- Repository: `https://github.com/SiriusScan/sirius-nse.git` +- Local Path: `/opt/sirius/nse/sirius-nse` +- Sync Timing: Startup, pre-scan (with cooldown) +- Operation: `git fetch && git reset --hard origin/main` + +**Script Discovery:** + +- Manifest: `manifest.json` in repository root +- Symlink: `/usr/local/share/nmap/scripts` → sirius-nse scripts +- Blacklist: In-memory map of excluded scripts + +### Container Coordination (Docker) + +**Service Dependencies:** + +```yaml +# docker-compose.yaml +sirius-engine: + depends_on: + - sirius-rabbitmq # Message queue + - sirius-valkey # State store + - sirius-api # Result submission +``` + +**Volume Mounts (Dev):** + +- `/app-scanner`: Live code (volume mount from `../minor-projects/app-scanner`) +- `/go-api`: Shared Go library (volume mount) +- `/sirius-nse`: NSE scripts (volume mount) + +**Health Checks:** + +- RabbitMQ: Queue availability check +- ValKey: Ping response +- API: HTTP health endpoint + + + +## Troubleshooting + + + +### Common Issues + +| Issue | Symptoms | Solution | +| ---------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------- | +| **NSE Script Not Found** | "NSE: failed to initialize" error | Check script exists in `/opt/sirius/nse/sirius-nse/scripts/`, verify symlink, check blacklist | +| **Scan Timeout** | Hosts stuck in "running" status | Reduce port range, enable aggressive mode, check network connectivity | +| **Memory Overflow** | Scanner crashes with OOM | Reduce worker count, scan smaller ranges, increase Docker memory limit | +| **RabbitMQ Disconnect** | "Connection closed" errors | Check RabbitMQ status, verify connection string, restart RabbitMQ | +| **NVD API Failure** | Empty vulnerability descriptions | Check internet connectivity, verify NVD API status, implement retry logic | +| **No Vulnerabilities Found** | Zero CVEs despite vulnerable services | Check NSE scripts ran, verify script output parsing, test manually with Nmap | + +### Debugging Commands + +**Check Scanner Status:** + +```bash +# View scanner logs +docker logs sirius-engine | grep scanner + +# Check if scanner is running +docker exec sirius-engine ps aux | grep scanner + +# View RabbitMQ queue depth +docker exec sirius-rabbitmq rabbitmqctl list_queues name messages +``` + +**Inspect NSE Scripts:** + +```bash +# List available scripts +docker exec sirius-engine ls /opt/sirius/nse/sirius-nse/scripts/ + +# Check script symlink +docker exec sirius-engine ls -la /usr/local/share/nmap/scripts + +# View manifest +docker exec sirius-engine cat /opt/sirius/nse/sirius-nse/manifest.json +``` + +**Test Scanning Tools:** + +```bash +# Test Nmap +docker exec sirius-engine nmap -sV 192.168.1.100 + +# Test RustScan +docker exec sirius-engine rustscan -a 192.168.1.100 + +# Test Naabu +docker exec sirius-engine echo "192.168.1.100" | naabu -p 80,443 +``` + +**Inspect ValKey State:** + +```bash +# Get scan state +docker exec sirius-valkey valkey-cli GET scan:scan-001 + +# List all scan keys +docker exec sirius-valkey valkey-cli KEYS "scan:*" + +# View template +docker exec sirius-valkey valkey-cli GET template:high-risk +``` + +**Network Debugging:** + +```bash +# Test network connectivity from container +docker exec sirius-engine ping 192.168.1.100 + +# Check DNS resolution +docker exec sirius-engine nslookup example.com + +# Test API connectivity +docker exec sirius-engine curl http://sirius-api:9001/health +``` + +### Performance Troubleshooting + +**Slow Scans:** + +1. **Check Port Range:** + +```bash +# View current options +docker exec sirius-valkey valkey-cli GET scan:scan-001 | jq '.options.port_range' + +# Recommendation: Use "1-1000" instead of "1-65535" +``` + +2. **Verify Worker Pool Utilization:** + +```bash +# Check Go runtime metrics +docker exec sirius-engine curl http://localhost:6060/debug/pprof/goroutine?debug=1 +``` + +3. **Analyze Network Latency:** + +```bash +# Ping targets +docker exec sirius-engine ping -c 5 192.168.1.100 +``` + +**High Memory Usage:** + +1. **Monitor Resource Usage:** + +```bash +docker stats sirius-engine --no-stream +``` + +2. **Reduce Concurrent Scans:** + +```go +// internal/scan/manager.go +const DEFAULT_WORKERS = 5 // Reduce from 10 +``` + +3. **Limit Target Range:** + +```bash +# Scan in smaller batches +# Instead of /24 (254 hosts), scan /26 (62 hosts) +``` + +### Script-Specific Issues + +**Vulners Script Failures:** + +```bash +# Test vulners script +docker exec sirius-engine nmap -sV --script vulners 192.168.1.100 -oX - + +# Check vulners API key (if configured) +docker exec sirius-engine cat /app-scanner/nmap-args/args.txt | grep vulners +``` + +**SMB Script Errors:** + +```bash +# Test SMB connectivity +docker exec sirius-engine nmap -p 445 192.168.1.100 + +# Run SMB scripts with debug +docker exec sirius-engine nmap --script smb-vuln-ms17-010 --script-trace 192.168.1.100 +``` + +**HTTP Script Timeouts:** + +```bash +# Increase timeout in args file +echo "timeout=60000" | docker exec -i sirius-engine tee -a /app-scanner/nmap-args/args.txt +``` + +### Emergency Recovery + +**Scanner Not Responding:** + +```bash +# Restart scanner +docker restart sirius-engine + +# Check for zombie processes +docker exec sirius-engine ps aux | grep defunct + +# Force kill and restart +docker compose down +docker compose up -d sirius-engine +``` + +**Corrupted ValKey State:** + +```bash +# Clear scan state +docker exec sirius-valkey valkey-cli DEL scan:scan-001 + +# Clear all scans (use with caution) +docker exec sirius-valkey valkey-cli KEYS "scan:*" | xargs docker exec sirius-valkey valkey-cli DEL +``` + +**NSE Repository Corruption:** + +```bash +# Remove and re-clone +docker exec sirius-engine rm -rf /opt/sirius/nse/sirius-nse +docker restart sirius-engine # Will re-clone on startup +``` + + + +## Best Practices + + + +### Scanning Ethics & Compliance + +**✅ DO:** + +- Get written authorization before scanning any systems +- Respect rate limits and avoid causing service degradation +- Document all scanning activities with timestamps and scope +- Use appropriate scan intensity based on target criticality +- Notify system owners of critical vulnerabilities promptly +- Store vulnerability data securely with access controls + +**❌ DON'T:** + +- Scan production systems during business hours without approval +- Use aggressive timing (`-T5`) on critical infrastructure +- Share vulnerability data with unauthorized personnel +- Scan IP ranges outside your authorized scope +- Ignore firewall/IDS alerts that indicate scanning is disruptive + +### Performance Optimization + +**✅ DO:** + +- Use templates to avoid full NSE script scans unnecessarily +- Scan top 1000 ports first, then full range if needed +- Enable parallel processing for large IP ranges +- Monitor and adjust worker pool size based on system resources +- Cache NVD API results to reduce external calls (future enhancement) + +**❌ DON'T:** + +- Run "all scripts" (`*`) unless absolutely necessary +- Scan entire /8 networks without batching +- Ignore memory/CPU limits in Docker configuration +- Skip rate limiting considerations + +### Code Quality + +**✅ DO:** + +- Write unit tests for all scan strategies +- Use context for cancellation and timeouts +- Wrap errors with context for debugging +- Log important events (scan start, completion, errors) +- Document complex logic with inline comments +- Follow Go idioms and best practices + +**❌ DON'T:** + +- Ignore errors (always check and handle) +- Use bare `panic()` (use error returns) +- Create goroutines without context cancellation +- Hardcode values that should be configurable + +### Security Considerations + +**✅ DO:** + +- Validate all scan message inputs +- Sanitize target values (prevent injection) +- Use prepared statements for database operations +- Implement proper authentication for scan requests (future) +- Encrypt sensitive data (credentials, API keys) +- Rotate API keys regularly + +**❌ DON'T:** + +- Trust user input without validation +- Log sensitive data (passwords, keys) +- Execute arbitrary commands from user input +- Store credentials in code or version control + +### Template Design + +**✅ DO:** + +- Name templates descriptively (purpose, not just speed) +- Document expected scan duration and resource usage +- Test templates on diverse targets before deploying +- Balance completeness with performance +- Include essential scripts (vulners, banner, http-title) + +**❌ DON'T:** + +- Create templates with conflicting options +- Use templates as a dump for all available scripts +- Forget to update templates when adding new scripts +- Make system templates too narrow or too broad + +### NSE Script Curation + +**✅ DO:** + +- Test new scripts thoroughly before adding to repository +- Document script purpose and expected output format +- Categorize scripts by protocol and function +- Maintain blacklist for problematic scripts +- Version the manifest file with meaningful commits + +**❌ DON'T:** + +- Add scripts without understanding their behavior +- Include scripts with known false positives +- Skip testing script compatibility with our parser +- Forget to update manifest.json when adding scripts + + + +## Quick Reference + + + +### Essential Commands + +```bash +# Start development environment +docker compose -f docker-compose.dev.yaml up -d sirius-engine + +# View scanner logs +docker logs -f sirius-engine | grep scanner + +# Run unit tests +docker exec sirius-engine bash -c "cd /app-scanner && go test ./internal/scan/... -v" + +# Send scan request +rabbitmqadmin publish exchange=amq.default routing_key=scan \ + payload='{"id":"scan-001","targets":[{"value":"192.168.1.100","type":"single_ip"}],"options":{"template_id":"quick"},"priority":3}' + +# Check scan progress +docker exec sirius-valkey valkey-cli GET scan:scan-001 + +# Test Nmap manually +docker exec sirius-engine nmap -sV --script vulners 192.168.1.100 +``` + +### File Locations + +**Scanner Code:** `../minor-projects/app-scanner/` +**NSE Scripts:** `../minor-projects/sirius-nse/scripts/` +**Container Binary:** `/app-scanner-src/scanner` +**NSE Repository:** `/opt/sirius/nse/sirius-nse` +**Nmap Scripts Symlink:** `/usr/local/share/nmap/scripts` +**Args File:** `/app-scanner/nmap-args/args.txt` + +### Key Data Structures + +```go +// Scan message +type ScanMessage struct { + ID string + Targets []Target + Options ScanOptions + Priority int + CallbackURL string +} + +// Scan strategy interface +type ScanStrategy interface { + Execute(target string) (sirius.Host, error) +} + +// Template structure +type Template struct { + ID string + Name string + EnabledScripts []string + ScanOptions TemplateOptions +} +``` + +### Scan Types + +- `enumeration`: Naabu port enumeration +- `discovery`: RustScan host/port discovery +- `vulnerability`: Nmap + NSE vulnerability scanning + +### System Templates + +- `quick`: Top 500 ports, 3 scripts, fast +- `high-risk`: Top 10000 ports, 10 scripts, balanced +- `all`: All ports, all scripts, comprehensive (slow) + +### Integration Points + +- **Input:** RabbitMQ `scan` queue +- **State:** ValKey `scan:` keys +- **Results:** API `POST /host/with-source` +- **Logs:** RabbitMQ `scanner_logs` queue +- **CVE Data:** NVD API `nvd.GetCVE()` + + + +--- + +**Last Updated:** 2025-10-25 +**Version:** 1.0.0 +**Maintainer:** Sirius Team + +**Note:** This identity provides comprehensive context for developing and maintaining the Sirius vulnerability scanning engine. For complete technical details, see [README.scanner.md](mdc:documentation/dev/apps/scanner/README.scanner.md). diff --git a/.cursor/agents/templates/ui-engineer.template.md b/.cursor/agents/templates/ui-engineer.template.md new file mode 100644 index 0000000..96d788d --- /dev/null +++ b/.cursor/agents/templates/ui-engineer.template.md @@ -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) + + + +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 + + +## Key Documentation + + + + +## Project Location + + + + +## Core 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 + + +## Technology Stack + + + + +## System Integration + +### Architecture Overview + + + +**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 + + +### Network Configuration + + + + +## Configuration + + + + +## 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 + + +## Next.js and React Best Practices + + + + +## Common Development 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 +
+

Title

+
; + +// Use shadcn/ui components +import { Button } from "~/components/ui/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), +}); +``` + + + +## Troubleshooting + + + + +## 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 + + +## Testing Checklist + + + +### 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 + + +## 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 +``` + + + +--- + +**Last Updated:** 2025-10-25 +**Version:** 1.0.0 +**Maintainer:** Sirius Team diff --git a/.cursor/commands/agent-engineer.md b/.cursor/commands/agent-engineer.md new file mode 100644 index 0000000..a2ebb8e --- /dev/null +++ b/.cursor/commands/agent-engineer.md @@ -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. diff --git a/.cursor/commands/bot-agent-engineer.md b/.cursor/commands/bot-agent-engineer.md new file mode 100644 index 0000000..8ebd241 --- /dev/null +++ b/.cursor/commands/bot-agent-engineer.md @@ -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) + + + +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 + + +## Key Documentation + + + + + +- [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) + + +## Project Location + + + + + +``` +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 +``` + + +## Core 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 + + +## Technology Stack + + + + + +**gRPC & Networking:** + +- `google.golang.org/grpc` +- `google.golang.org/protobuf` + +**Storage & Caching:** + + +**Messaging:** + + +**Configuration & Logging:** + +- `gopkg.in/yaml.v3` + +**Utilities:** + + +## System Integration + +### Architecture Overview + + + +**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 + + +### Network Configuration + + + + + +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' + + +## Configuration + + + + + +**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' + + +## 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 + + +## Go SDK and Best Practices + + + + + +No code patterns found in documentation + + +## Common Development 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 ./... +``` + + + +## Troubleshooting + + + + +## 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 + + +## Testing Checklist + + + +### 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 + + +## 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 +``` + + + +--- + +**Last Updated:** 2025-10-25 +**Version:** 1.0.0 +**Maintainer:** Sirius Team diff --git a/.cursor/commands/bot-api-engineer.md b/.cursor/commands/bot-api-engineer.md new file mode 100644 index 0000000..14c3ad0 --- /dev/null +++ b/.cursor/commands/bot-api-engineer.md @@ -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) + + + +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 + + +## Key Documentation + + + + + +- [README.architecture](mdc:documentation/dev/documentation/dev/architecture/README.architecture.md) +- [README.development](mdc:documentation/dev/documentation/dev/README.development.md) + + +## Project Location + + + + + +``` +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 +``` + + +## Core 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 + + +## Technology Stack + + + + + +**Web Framework:** + +- `github.com/gofiber/fiber/v2` + +**Database:** + + +**Messaging:** + + +**Caching:** + + +**Utilities:** + +- `github.com/google/uuid` +- `gopkg.in/yaml.v3` + + +## System Integration + +### Architecture Overview + + + +**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 + + +### Network Configuration + + + + + +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' + + +## Configuration + + + + + +**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' + + +## 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 + + +## Go Fiber Best Practices + + + + + +No code patterns found in documentation + + +## Common Development 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 +``` + + + +## Troubleshooting + + + + +## 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 + + +## Testing Checklist + + + +### 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 + + +## 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 +``` + + + +--- + +**Last Updated:** 2025-10-25 +**Version:** 1.0.0 +**Maintainer:** Sirius Team diff --git a/.cursor/commands/bot-ci-sme.md b/.cursor/commands/bot-ci-sme.md new file mode 100644 index 0000000..948640a --- /dev/null +++ b/.cursor/commands/bot-ci-sme.md @@ -0,0 +1,1143 @@ +--- +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 +_generated_at: '2025-11-14T03:35:43.687Z' +_source_files: + - /.github/workflows + - /.github/workflows/.github/workflows/ci.yml + - /.github/workflows/docker-compose.yaml + - /.github/workflows/docker-compose.dev.yaml + - documentation/dev/deployment/README.workflows.md + - documentation/dev/deployment/README.docker-container-deployment.md +--- + +# CI/CD Subject Matter Expert (GitHub Actions & Container Registry) + + + +Expert in the Sirius CI/CD pipeline architecture, specializing in GitHub Actions workflows, parallel container builds, GitHub Container Registry integration, and deployment automation. Deep understanding of the evolution from sequential to parallel build architecture, achieving 40-60% faster CI/CD runs. + +**Core Focus Areas:** + +- **Parallel Build Architecture** - Three concurrent build jobs (UI/API/Engine) replacing monolithic builds +- **Container Registry Integration** - GHCR-based deployment with prebuilt images (5-8 min vs 20-25 min) +- **Prebuild Validation** - Fast-fail lint/test checks before expensive Docker builds +- **Multi-Arch Support** - Building for both amd64 and arm64 platforms simultaneously +- **Deployment Orchestration** - Canary deployments, demo environments, and production workflows + +**Philosophy:** + +CI/CD should be fast, reliable, and provide immediate feedback. The parallel build architecture prioritizes: +1. **Fast failure** - Prebuild validation catches issues in 1-3 minutes before Docker builds +2. **Parallelization** - Independent services build concurrently (longest job sets pace) +3. **Smart caching** - GitHub Actions cache reduces redundant work +4. **Deployment confidence** - Automated testing and canary deployments catch issues early + +**Recent Major Improvements (v0.4.1):** + +- Split monolithic `build-and-push` into three parallel jobs (`build-ui`, `build-api`, `build-engine`) +- Added prebuild validation (lint/test) before Docker builds for fast failure +- Integrated GitHub Container Registry for prebuilt images (60-75% faster deployments) +- Implemented canary deployment triggering demo rebuild on every main push +- Reduced typical CI/CD run from 70-90 minutes to 40-50 minutes + + + +## Key Documentation + + + + + +- [README.workflows](mdc:documentation/dev/documentation/dev/deployment/README.workflows.md) +- [README.docker-container-deployment](mdc:documentation/dev/documentation/dev/deployment/README.docker-container-deployment.md) +- [README.terraform-deployment](mdc:documentation/dev/documentation/dev/operations/README.terraform-deployment.md) +- [README.cicd](mdc:documentation/dev/documentation/dev/architecture/README.cicd.md) +- [README.docker-architecture](mdc:documentation/dev/documentation/dev/architecture/README.docker-architecture.md) + + +## Project Location + + + + + +``` +workflows/ +``` + + +## Core Responsibilities + + + +### Primary Responsibilities + +1. **Workflow Architecture & Optimization** + - Design and maintain parallel build workflows + - Optimize job dependencies and execution order + - Minimize build times through intelligent caching and parallelization + - Balance speed, reliability, and resource usage + +2. **Container Registry Management** + - Manage GHCR integration and image tagging strategy + - Ensure proper authentication and package permissions + - Monitor image sizes and optimize multi-stage builds + - Maintain public image availability for open-source deployments + +3. **Build & Deployment Automation** + - Configure Docker Buildx for multi-arch builds + - Implement smart change detection for selective builds + - Orchestrate integration testing with built images + - Automate deployment triggers for demo and production + +4. **Validation & Quality Gates** + - Design prebuild validation strategies (lint, test, typecheck) + - Implement fast-fail mechanisms to catch issues early + - Configure integration tests for deployed environments + - Monitor build success rates and failure patterns + +5. **Documentation & Knowledge Sharing** + - Document workflow architecture and job dependencies + - Maintain troubleshooting guides for common issues + - Track timing metrics and performance improvements + - Share best practices for workflow modifications + +### Secondary Responsibilities + +- Monitor GitHub Actions usage and optimize costs +- Investigate and resolve workflow failures +- Update workflows for new services or changes +- Collaborate with security on image scanning +- Support demo environment deployments + + + +## Technology Stack + + + + +## System Integration + + + +### High Integration Level + +As CI/CD SME, you have **high system integration** - comprehensive understanding of how all system components interact through the build and deployment pipeline. + +**Integration Points:** + +1. **Source Code → CI/CD Pipeline** + - Git branches and tags trigger workflow runs + - Change detection determines which services rebuild + - Pre-commit hooks validate before CI runs + +2. **CI/CD Pipeline → Container Registry** + - Docker Buildx builds multi-arch images + - GHCR receives pushed images with tags (latest, beta, version-specific) + - Images are publicly accessible for deployments + +3. **Container Registry → Deployment** + - Terraform user_data scripts pull prebuilt images + - Docker Compose uses registry images by default + - Demo environment automatically rebuilds on main pushes (canary) + +4. **Deployment → Feedback** + - Health checks validate service startup + - Monitoring tracks deployment success/failure + - Failed deployments trigger alerts and investigation + +**System Knowledge:** + +- All three application services (UI, API, Engine) and their build requirements +- Infrastructure services (Postgres, RabbitMQ, Valkey) and dependencies +- Docker Compose configuration (production and development overlays) +- AWS infrastructure (EC2, Terraform) for demo deployments +- Git workflow (main, sirius-demo, feature branches) + + + +## Workflow Architecture + + + +### Parallel Build Architecture + +``` +┌─────────────────┐ +│ detect-changes │ ← Analyzes git diff, sets build flags +└────────┬────────┘ + │ + ├──────────┬──────────┬──────────┐ + ▼ ▼ ▼ ▼ + ┌────────┐ ┌────────┐ ┌──────────┐ │ + │build-ui│ │build-api│ │build-engine│ │ ← Run in parallel + └───┬────┘ └───┬────┘ └─────┬────┘ │ + │ │ │ │ + │ (2-3min) │ (1-2min) │ (1-2min)│ ← Prebuild validation + │ │ │ │ + │ (15-20m) │ (20-25m) │ (30-40m)│ ← Docker builds (parallel) + │ │ │ │ + └──────────┴────────────┴─────────┘ + │ + ▼ + ┌────────┐ + │ test │ ← Integration test with built images + └───┬────┘ + │ (5min) + ┬─────────┴─────────┬ + ▼ ▼ +┌───────────────┐ ┌──────────────┐ +│dispatch-demo- │ │dispatch-demo-│ +│ deployment │ │ canary │ ← Trigger deployments +└───────────────┘ └──────────────┘ +``` + +**Key Characteristics:** + +- **Parallel execution**: Longest job (Engine ~30-40m) sets total build time +- **Smart dependencies**: Test job waits for all builds, uses `always()` with result checks +- **Isolated validation**: Each build job has its own prebuild validation step +- **Flexible outputs**: Each job outputs `image_tag`, test job determines which to use + +### Job Descriptions + +**1. detect-changes** +- Analyzes git diff to determine which services changed +- Sets output flags: `sirius_ui_changes`, `sirius_api_changes`, `sirius_engine_changes` +- Triggers on: push to main/sirius-demo, PRs to main, repository_dispatch (submodule updates) +- Duration: ~30 seconds + +**2. build-ui (Parallel)** +- Validates UI code: `npm ci && npm run lint` (2-3 min) +- Builds Next.js container with Docker Buildx (15-20 min) +- Pushes to GHCR with tags: `latest`, `beta`, `pr-{number}`, version-specific +- Platforms: linux/amd64, linux/arm64 +- Output: `image_tag` + +**3. build-api (Parallel)** +- Validates API code: `go mod download && go test ./...` (1-2 min) +- Builds Go API container with submodule refs (20-25 min) +- Pushes to GHCR with same tagging strategy +- Build args: `GO_API_COMMIT_SHA` for go-api submodule +- Output: `image_tag` + +**4. build-engine (Parallel)** +- Validates Engine code: `go mod download && go test ./...` (1-2 min) +- Builds Go Engine container with all submodule refs (30-40 min) +- Pushes to GHCR with same tagging strategy +- Build args: GO_API, APP_SCANNER, APP_TERMINAL, SIRIUS_NSE, APP_AGENT commit SHAs +- Output: `image_tag` + +**5. test** +- Determines image tag from whichever build job succeeded +- Creates isolated test environment with docker-compose.test.yml +- Starts infrastructure (Postgres tmpfs, RabbitMQ, Valkey) +- Launches application services that were built +- Runs smoke tests and verifies health +- Cleans up test environment +- Duration: ~5 minutes + +**6. dispatch-demo-deployment** +- Triggers on push to `sirius-demo` branch after successful builds/tests +- Sends `repository_dispatch` event to `SiriusScan/sirius-demo` +- Event type: `sirius-demo-updated` +- Includes source repo/branch/SHA, actor, commit message + +**7. dispatch-demo-canary** +- Triggers on push to `main` branch after successful builds/tests +- Sends `repository_dispatch` event to `SiriusScan/sirius-demo` +- Event type: `sirius-main-updated` +- **Canary purpose**: Catches bad commits to main by immediately deploying to demo + +### Timing Analysis + +| Phase | Before (Sequential) | After (Parallel) | Improvement | +|-------|-------------------|-----------------|-------------| +| Change detection | ~30s | ~30s | - | +| Prebuild validation | N/A | ~2-3 min (all parallel) | New | +| Build UI | ~15-20 min | ~15-20 min | - | +| Build API | ~20-25 min | ~20-25 min | - | +| Build Engine | ~30-40 min | ~30-40 min | - | +| **Total build time** | **~65-85 min (serial)** | **~30-40 min (longest wins)** | **40-60% faster** | +| Integration test | ~5 min | ~5 min | - | +| **Total CI/CD** | **~70-90 min** | **~40-50 min** | **~30-40 min saved** | + + + +## Container Registry Integration + + + +### GitHub Container Registry (GHCR) + +**Registry URL**: `ghcr.io/siriusscan/` + +**Images:** +- `ghcr.io/siriusscan/sirius-ui:{tag}` +- `ghcr.io/siriusscan/sirius-api:{tag}` +- `ghcr.io/siriusscan/sirius-engine:{tag}` + +**Visibility**: Public (no authentication required for pulls) + +**Architecture**: Multi-arch (linux/amd64, linux/arm64) + +### Image Tagging Strategy + +**Production Tags:** +- `latest` - Latest stable build from main branch +- `beta` - Alias for latest (same image, different label) +- `v0.4.1` - Version-specific releases (semantic versioning) + +**Development Tags:** +- `pr-123` - Pull request builds (isolated testing) +- `dev` - Other branch builds + +**Tag Determination Logic:** +```yaml +if: github.event_name == 'pull_request' + TAG = "pr-${PR_NUMBER}" +elif: github.ref == 'refs/heads/main' + TAG = "latest" + ALSO_TAG_BETA = true +elif: github.event_name == 'repository_dispatch' + TAG = "latest" + ALSO_TAG_BETA = true +else: + TAG = "dev" +``` + +### Authentication + +**Build Pipeline Authentication:** +```yaml +- name: Log in to Container Registry + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ secrets.GHCR_PUSH_USER }} + password: ${{ secrets.GHCR_PUSH_TOKEN }} +``` + +**Required Secrets:** +- `GHCR_PUSH_USER`: GitHub username that generated the PAT +- `GHCR_PUSH_TOKEN`: Personal Access Token with scopes: + - `write:packages` (push images) + - `read:packages` (pull existing layers) + - `repo` (access repository context) + +**Why PAT?** Default `GITHUB_TOKEN` has read-only package permissions and cannot create new packages. PAT-based auth bypasses this limitation. + +### Deployment Integration + +**Production (Registry Images):** +```yaml +# docker-compose.yaml +services: + sirius-ui: + image: ghcr.io/siriusscan/sirius-ui:${IMAGE_TAG:-latest} + pull_policy: always +``` + +**Development (Local Builds):** +```yaml +# docker-compose.dev.yaml +services: + sirius-ui: + build: + context: ./sirius-ui/ + target: development + image: sirius-sirius-ui:dev # Override registry image +``` + +**Deployment Speed Comparison:** +| Method | Time | Use Case | +|--------|------|----------| +| Registry images | 5-8 min | Production, demo, staging | +| Local builds | 20-25 min | Development with code changes | + + + +## Code Patterns & Best Practices + + + +### Workflow Design Patterns + +#### ✅ GOOD: Parallel Independent Jobs + +```yaml +build-ui: + name: Build & Push UI + needs: detect-changes + runs-on: ubuntu-latest + if: needs.detect-changes.outputs.sirius_ui_changes == 'true' + outputs: + image_tag: ${{ steps.meta.outputs.image_tag }} + steps: + - name: Validate UI code + run: | + cd sirius-ui + npm ci + npm run lint + + - name: Build and push + uses: docker/build-push-action@v5 + with: + context: ./sirius-ui + platforms: linux/amd64,linux/arm64 + push: true + tags: ghcr.io/siriusscan/sirius-ui:${{ steps.meta.outputs.image_tag }} +``` + +**Why this works:** +- Independent of other build jobs (runs in parallel) +- Fast-fail validation before expensive Docker build +- Outputs `image_tag` for downstream jobs +- Uses conditional execution based on change detection + +#### ❌ BAD: Sequential Builds + +```yaml +# DON'T DO THIS - builds run serially +build-and-push: + steps: + - name: Build UI + run: docker build ./sirius-ui + + - name: Build API + run: docker build ./sirius-api + + - name: Build Engine + run: docker build ./sirius-engine +``` + +**Why this fails:** +- Builds run sequentially (total = sum of all builds) +- No early validation (fails late) +- Single failure blocks everything +- No parallelization benefits + +#### ✅ GOOD: Downstream Job Dependencies + +```yaml +test: + name: Integration Test + needs: [detect-changes, build-ui, build-api, build-engine] + runs-on: ubuntu-latest + if: always() && (needs.build-ui.result == 'success' || needs.build-api.result == 'success' || needs.build-engine.result == 'success') + steps: + - name: Determine image tag + id: tag + run: | + if [ "${{ needs.build-ui.result }}" == "success" ]; then + TAG="${{ needs.build-ui.outputs.image_tag }}" + elif [ "${{ needs.build-api.result }}" == "success" ]; then + TAG="${{ needs.build-api.outputs.image_tag }}" + else + TAG="${{ needs.build-engine.outputs.image_tag }}" + fi + echo "image_tag=$TAG" >> $GITHUB_OUTPUT +``` + +**Why this works:** +- Uses `always()` to run even if some builds skip +- Checks specific job results for success +- Flexible tag determination from whichever job ran +- Tests only what was actually built + +#### ❌ BAD: Hardcoded Dependencies + +```yaml +# DON'T DO THIS - assumes specific job output +test: + needs: build-and-push + steps: + - run: docker compose -f test.yml up + env: + IMAGE_TAG: latest # Hardcoded! +``` + +**Why this fails:** +- Doesn't use actual build outputs +- Can test wrong images (stale cache) +- No flexibility for PR builds or versions +- Breaks change detection optimization + +### Docker Buildx Patterns + +#### ✅ GOOD: Multi-Arch with Caching + +```yaml +- name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + +- name: Build and push + uses: docker/build-push-action@v5 + with: + context: ./sirius-ui + platforms: linux/amd64,linux/arm64 + push: true + tags: | + ghcr.io/siriusscan/sirius-ui:${{ steps.meta.outputs.image_tag }} + ${{ steps.meta.outputs.also_tag_beta == 'true' && 'ghcr.io/siriusscan/sirius-ui:beta' || '' }} + cache-from: type=gha + cache-to: type=gha,mode=max +``` + +**Why this works:** +- Builds for multiple architectures in single step +- Uses GitHub Actions cache to speed up builds +- Conditional tagging (beta only for main branch) +- Efficient layer caching across runs + +#### ❌ BAD: Separate Builds per Arch + +```yaml +# DON'T DO THIS - duplicates work +- name: Build amd64 + run: docker buildx build --platform linux/amd64 -t ui:amd64 . + +- name: Build arm64 + run: docker buildx build --platform linux/arm64 -t ui:arm64 . + +- name: Create manifest + run: docker manifest create ui:latest ui:amd64 ui:arm64 +``` + +**Why this fails:** +- Doubles build time (serial architecture builds) +- Complex manifest management +- No cache sharing between architectures +- More steps to maintain and debug + +### Change Detection Patterns + +#### ✅ GOOD: Smart Path Detection + +```yaml +- name: Determine Changed Files + id: changes + run: | + git diff --name-only $BASE_SHA $HEAD_SHA > changed_files.txt + + if grep -q "sirius-ui/" changed_files.txt; then + echo "sirius_ui_changes=true" >> $GITHUB_OUTPUT + fi + + if grep -q "sirius-api/" changed_files.txt; then + echo "sirius_api_changes=true" >> $GITHUB_OUTPUT + fi + + # Global changes rebuild everything + if grep -q -E "(Dockerfile|docker-compose|\.github/)" changed_files.txt; then + echo "sirius_ui_changes=true" >> $GITHUB_OUTPUT + echo "sirius_api_changes=true" >> $GITHUB_OUTPUT + echo "sirius_engine_changes=true" >> $GITHUB_OUTPUT + fi +``` + +**Why this works:** +- Selective builds save time (only changed services) +- Global changes (Docker, CI) trigger full rebuild +- Explicit output flags for downstream jobs +- Easy to debug with changed_files.txt + +#### ❌ BAD: Always Build Everything + +```yaml +# DON'T DO THIS - no optimization +jobs: + build: + steps: + - name: Build all services + run: docker compose build +``` + +**Why this fails:** +- Wastes time rebuilding unchanged services +- No benefit from parallelization +- Slower feedback loops +- Higher resource usage + +### Prebuild Validation Patterns + +#### ✅ GOOD: Fast-Fail Before Docker + +```yaml +- name: Validate UI code + run: | + cd sirius-ui + echo "Running UI validation..." + npm ci + npm run lint || echo "⚠️ Lint warnings present" + echo "✅ UI validation complete" + +- name: Build and push sirius-ui + uses: docker/build-push-action@v5 + # Only runs if validation succeeded +``` + +**Why this works:** +- Catches issues in 2-3 minutes vs 15-20 for full build +- Clear output with emojis for quick scanning +- Non-fatal warnings (continues to build) +- Saves expensive Docker build time on failures + +#### ❌ BAD: No Validation + +```yaml +# DON'T DO THIS - builds blindly +- name: Build and push + uses: docker/build-push-action@v5 + # Fails 15 minutes later on lint error +``` + +**Why this fails:** +- Long feedback loop (15-20 min to discover lint errors) +- Wastes CI minutes on preventable failures +- Docker layer cache pollution from failed builds +- Frustrating developer experience + + + +## Common Tasks + + + +### Add New Service to Parallel Builds + +```bash +# 1. Create build job in .github/workflows/ci.yml +``` + +```yaml +build-newservice: + name: Build & Push NewService + needs: detect-changes + runs-on: ubuntu-latest + if: needs.detect-changes.outputs.newservice_changes == 'true' + outputs: + image_tag: ${{ steps.meta.outputs.image_tag }} + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Generate metadata + id: meta + run: | + # Copy metadata logic from existing build jobs + # [tag determination logic] + echo "image_tag=$TAG" >> $GITHUB_OUTPUT + + - name: Validate code + run: | + cd newservice + # Add validation commands + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to GHCR + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ secrets.GHCR_PUSH_USER }} + password: ${{ secrets.GHCR_PUSH_TOKEN }} + + - name: Build and push + uses: docker/build-push-action@v5 + with: + context: ./newservice + platforms: linux/amd64,linux/arm64 + push: true + tags: ghcr.io/siriusscan/newservice:${{ steps.meta.outputs.image_tag }} + cache-from: type=gha + cache-to: type=gha,mode=max +``` + +```bash +# 2. Update detect-changes job +``` + +```yaml +- name: Determine Changed Files + id: changes + run: | + # ... existing logic ... + + if grep -q "newservice/" changed_files.txt; then + echo "newservice_changes=true" >> $GITHUB_OUTPUT + fi +``` + +```bash +# 3. Update test job dependencies +``` + +```yaml +test: + needs: [detect-changes, build-ui, build-api, build-engine, build-newservice] + if: always() && (needs.build-ui.result == 'success' || needs.build-api.result == 'success' || needs.build-engine.result == 'success' || needs.build-newservice.result == 'success') +``` + +```bash +# 4. Update dispatch job dependencies (both) +``` + +```yaml +dispatch-demo-deployment: + needs: [detect-changes, build-ui, build-api, build-engine, build-newservice, test] + if: github.ref == 'refs/heads/sirius-demo' && github.event_name == 'push' && always() && (needs.detect-changes.result == 'success' || needs.detect-changes.result == 'skipped') && (needs.build-ui.result == 'success' || needs.build-ui.result == 'skipped') && (needs.build-api.result == 'success' || needs.build-api.result == 'skipped') && (needs.build-engine.result == 'success' || needs.build-engine.result == 'skipped') && (needs.build-newservice.result == 'success' || needs.build-newservice.result == 'skipped') && (needs.test.result == 'success' || needs.test.result == 'skipped') +``` + +### Optimize Build Times + +```bash +# 1. Audit current timing +gh run list --workflow=ci.yml --limit 10 --json databaseId,status,conclusion,createdAt + +# 2. View specific run timing +gh run view --log | grep "took" + +# 3. Identify bottlenecks +# - Longest Docker build (typically Engine: 30-40 min) +# - Validation time (should be <3 min) +# - Cache effectiveness (check cache hits) + +# 4. Optimize strategies: + +# A. Improve Docker layer caching +# - Order Dockerfile commands from least to most frequently changed +# - Copy package files before source code +# - Use multi-stage builds to reduce final image size + +# B. Optimize validation +# - Run only essential checks (lint, not full test suite) +# - Cache dependencies (npm/go mod) +# - Use --prefer-offline for npm + +# C. Parallelize further +# - Split large services into smaller containers +# - Run tests in parallel with builds (if safe) +# - Use matrix builds for multiple versions +``` + +### Troubleshoot Build Failures + +```bash +# 1. Check recent runs +gh run list --workflow=ci.yml --limit 5 + +# 2. View failed run +gh run view + +# 3. Get detailed logs +gh run view --log > failure.log + +# 4. Common failure patterns: + +# A. "denied: installation not allowed" +# Fix: Use PAT authentication (GHCR_PUSH_USER/TOKEN) + +# B. "403 Forbidden" during push +# Fix: Check PAT has write:packages scope +# Fix: Verify package is public + +# C. "manifest unknown" +# Fix: Check image tag exists in GHCR +# Fix: Ensure build job completed successfully + +# D. Test job fails to pull images +# Fix: Check build job outputs match test job inputs +# Fix: Verify GHCR authentication in test job + +# E. Prebuild validation fails +# Fix: Run locally: cd sirius-ui && npm ci && npm run lint +# Fix: Update code to pass validation + +# 5. Manual testing +# Run workflow manually with specific branch/tag +gh workflow run ci.yml --ref feature-branch +``` + +### Update Image Tags for Deployment + +```bash +# 1. Tag new version +git tag -a v0.4.2 -m "Release v0.4.2" +git push origin v0.4.2 + +# 2. Wait for CI to build +gh run watch --interval 30 + +# 3. Verify images exist +docker pull ghcr.io/siriusscan/sirius-ui:v0.4.2 +docker pull ghcr.io/siriusscan/sirius-api:v0.4.2 +docker pull ghcr.io/siriusscan/sirius-engine:v0.4.2 + +# 4. Deploy with specific version +IMAGE_TAG=v0.4.2 docker compose pull +IMAGE_TAG=v0.4.2 docker compose up -d + +# 5. Verify deployment +docker compose ps +curl http://localhost:9001/health +curl http://localhost:3000/api/health +``` + +### Monitor CI/CD Performance + +```bash +# 1. Track build times over time +gh run list --workflow=ci.yml --json databaseId,status,conclusion,createdAt,updatedAt \ + | jq -r '.[] | [.databaseId, .status, (.updatedAt | fromdateiso8601 - (.createdAt | fromdateiso8601))] | @tsv' + +# 2. Check cache hit rates +gh run view --log | grep "cache hit" + +# 3. Monitor failure rates +gh run list --workflow=ci.yml --limit 50 --json status,conclusion \ + | jq '[.[] | .conclusion] | group_by(.) | map({key: .[0], count: length})' + +# 4. Identify most expensive steps +gh run view --log | grep "took" | sort -t: -k2 -n +``` + + + +## Troubleshooting + + + +### Build Performance Issues + +| Issue | Symptoms | Solution | +|-------|----------|----------| +| **Builds slower than expected** | Total time >50 min | Check if jobs running parallel (should see concurrent execution in Actions UI) | +| **Validation taking too long** | Prebuild >5 min | Optimize lint/test commands, use --prefer-offline for npm | +| **Docker builds slow** | Individual build >45 min | Check cache effectiveness, optimize Dockerfile layer ordering | +| **Test job slow** | Integration test >10 min | Use tmpfs for Postgres, reduce wait times, parallel service tests | + +### Authentication & Registry Issues + +| Issue | Symptoms | Solution | +|-------|----------|----------| +| **"denied: installation not allowed"** | Push fails at start | Use PAT auth (GHCR_PUSH_USER/TOKEN), not default GITHUB_TOKEN | +| **"403 Forbidden" during push** | Push fails mid-stream | Verify PAT has `write:packages` and `read:packages` scopes | +| **"manifest unknown" locally** | `docker pull` fails | Check image exists in GHCR UI, verify tag name matches | +| **Can't pull images** | Deployment fails | For public repos, should work without auth; check network/DNS | + +### Workflow Logic Errors + +| Issue | Symptoms | Solution | +|-------|----------|----------| +| **Jobs not running** | Expected jobs skip | Check `if` conditions and `needs` dependencies | +| **Test uses wrong images** | Old code deployed | Verify test job uses build outputs, not hardcoded tags | +| **Dispatch doesn't trigger** | Demo not updating | Check `repository_dispatch` event types match in both repos | +| **Build runs on unchanged service** | Unnecessary builds | Review change detection logic, check git diff paths | + +### Common Errors + +**Error:** `Error: buildx failed with: ERROR: failed to solve: failed to push` + +**Cause:** Buildx failed to push to GHCR, typically auth or permissions + +**Fix:** +```bash +# 1. Verify secrets exist +gh secret list + +# 2. Check PAT scopes +# Visit https://github.com/settings/tokens +# Ensure write:packages, read:packages, repo checked + +# 3. Test local authentication +echo "$PAT" | docker login ghcr.io -u USERNAME --password-stdin +docker pull ghcr.io/siriusscan/sirius-ui:latest + +# 4. Regenerate secrets if needed +# Create new PAT, update GHCR_PUSH_TOKEN secret +``` + +**Error:** `Error: Unable to locate executable file: act` + +**Cause:** GitHub Actions local runner (`act`) not installed + +**Fix:** +```bash +# Install act (macOS) +brew install act + +# Install act (Linux) +curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash + +# Test workflow locally (optional) +act push --secret-file .secrets -W .github/workflows/ci.yml +``` + +**Error:** Test job fails with `Error response from daemon: manifest unknown` + +**Cause:** Build job didn't push images or test job using wrong tag + +**Fix:** +```bash +# 1. Check build job succeeded and outputs exist +gh run view --log | grep "image_tag=" + +# 2. Verify test job is using correct output +# Should see: TAG="${{ needs.build-ui.outputs.image_tag }}" + +# 3. Check images exist in GHCR +curl -H "Authorization: Bearer $TOKEN" \ + https://ghcr.io/v2/siriusscan/sirius-ui/tags/list + +# 4. Verify test job authentication +# Should have docker login step with GHCR_PUSH credentials +``` + +### Debugging Commands + +```bash +# View workflow run details +gh run view + +# Get specific job logs +gh run view --log --job= + +# List workflow runs +gh run list --workflow=ci.yml --limit 20 + +# Watch workflow execution +gh run watch --interval 10 + +# Re-run failed jobs +gh run rerun --failed + +# Download workflow artifacts +gh run download + +# Check workflow syntax locally +actionlint .github/workflows/ci.yml +``` + + + +## Best Practices + + + +### Workflow Design + +✅ **DO:** +- Use parallel jobs for independent services (UI/API/Engine) +- Add prebuild validation before expensive Docker builds (lint/test) +- Use `always()` with specific result checks for flexible dependencies +- Output consistent metadata (`image_tag`) from all build jobs +- Implement smart change detection to skip unnecessary builds +- Cache Docker layers and dependencies (GitHub Actions cache) +- Use multi-stage Dockerfiles to reduce final image sizes + +❌ **DON'T:** +- Build services sequentially when they're independent +- Skip prebuild validation to "save time" (costs more later) +- Use hardcoded tags/values (breaks version deployments) +- Build without change detection (wastes resources) +- Ignore cache strategies (longer builds every time) +- Create monolithic workflows (hard to maintain/debug) + +### Container Registry + +✅ **DO:** +- Use specific version tags for production deployments (`v0.4.1`) +- Tag `latest` and `beta` on main branch pushes +- Build multi-arch images (amd64, arm64) in single step +- Make packages public for open-source projects +- Use PAT auth for pushing (not default GITHUB_TOKEN) +- Monitor image sizes and optimize regularly + +❌ **DON'T:** +- Use `latest` in production (hard to rollback) +- Build architectures separately (doubles time) +- Forget to set package visibility (blocks deployments) +- Rely on default GITHUB_TOKEN (lacks package create permission) +- Let images grow unbounded (slow pulls, wasted storage) + +### Performance Optimization + +✅ **DO:** +- Profile builds regularly to identify bottlenecks +- Optimize Docker layer caching (least→most frequently changed) +- Use GitHub Actions cache for dependencies and layers +- Run only essential validation before builds (full tests after) +- Consider splitting large services into smaller containers +- Monitor CI minutes usage and adjust strategies + +❌ **DON'T:** +- Optimize prematurely (profile first) +- Skip validation to "save time" (false economy) +- Run full test suites before builds (slow feedback) +- Ignore cache hit rates (free speedups) +- Over-parallelize (resource contention hurts) + +### Debugging & Monitoring + +✅ **DO:** +- Include clear step names and emojis for quick scanning +- Log key decisions and values (`echo` in workflow steps) +- Use structured logging with timestamps +- Monitor success/failure rates over time +- Track build timing trends to catch regressions +- Document common issues and solutions + +❌ **DON'T:** +- Use cryptic step names ("Step 1", "Build", etc.) +- Skip logging important values (hard to debug) +- Ignore workflow failures as "transient" (may indicate issues) +- Let build times gradually increase (death by a thousand cuts) +- Repeat troubleshooting from scratch (document once) + +### Security + +✅ **DO:** +- Scan images for vulnerabilities regularly +- Use minimal base images (Alpine, distroless) +- Pin dependency versions for reproducibility +- Rotate PATs regularly (at least annually) +- Limit PAT scopes to minimum required +- Use GitHub's Dependabot for dependency updates + +❌ **DON'T:** +- Skip vulnerability scanning (catch issues early) +- Use full OS images when minimal would work +- Use `latest` tags for base images (non-reproducible) +- Share PATs or commit them to code +- Grant excessive PAT permissions ("just in case") +- Ignore security alerts on dependencies + + + +## Quick Reference + + + +### Essential Commands + +```bash +# Monitor CI/CD +gh run list --workflow=ci.yml --limit 5 +gh run watch --interval 30 +gh run view --log + +# Trigger builds +git push origin main # Auto-trigger +gh workflow run ci.yml --ref main # Manual trigger + +# Container registry +docker pull ghcr.io/siriusscan/sirius-ui:latest +IMAGE_TAG=v0.4.1 docker compose pull +docker login ghcr.io -u USERNAME + +# Validation +actionlint .github/workflows/ci.yml # Workflow syntax +make validate-docker-compose # Compose files + +# Debug +gh run rerun --failed # Retry failed jobs +gh run download # Download artifacts +``` + +### Key File Locations + +**Workflows:** `.github/workflows/ci.yml` +**Compose (prod):** `docker-compose.yaml` +**Compose (dev):** `docker-compose.dev.yaml` +**Documentation:** `documentation/dev/deployment/README.workflows.md` +**Registry:** `https://ghcr.io/siriusscan/` + +### Timing Targets + +| Phase | Target | Actual | Status | +|-------|--------|--------|--------| +| Change detection | <1 min | ~30s | ✅ | +| Prebuild validation | <3 min | 1-3 min | ✅ | +| Parallel builds | <45 min | 30-40 min | ✅ | +| Integration test | <7 min | ~5 min | ✅ | +| **Total CI/CD** | **<50 min** | **40-50 min** | ✅ | + +### Image Tags Reference + +| Tag | When Created | Use Case | +|-----|-------------|----------| +| `latest` | Every main push | Default production | +| `beta` | Every main push | Beta testing | +| `v0.4.1` | Version tag | Specific release | +| `pr-123` | Pull request | PR testing | +| `dev` | Other branches | Development | + +### Workflow Job Graph + +``` +detect-changes → [build-ui, build-api, build-engine] → test → [dispatch-demo-deployment, dispatch-demo-canary] +``` + +**Parallel:** build-ui, build-api, build-engine +**Sequential:** detect-changes → builds → test → dispatch +**Total parallelism:** 3x (three build jobs concurrent) + + + +--- + +**Last Updated:** 2025-11-14 +**Version:** 1.0.0 +**Maintainer:** Sirius Team + +**Note:** This identity represents deep expertise in the Sirius CI/CD pipeline, reflecting the recent architectural improvements that achieved 40-60% faster build times through parallelization and container registry integration. + diff --git a/.cursor/commands/bot-github-commits.md b/.cursor/commands/bot-github-commits.md new file mode 100644 index 0000000..388d059 --- /dev/null +++ b/.cursor/commands/bot-github-commits.md @@ -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." diff --git a/.cursor/commands/bot-identity-recruiter.md b/.cursor/commands/bot-identity-recruiter.md new file mode 100644 index 0000000..7144e8e --- /dev/null +++ b/.cursor/commands/bot-identity-recruiter.md @@ -0,0 +1,1159 @@ +--- +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-11-14' +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 +_generated_at: '2025-11-14T03:35:43.692Z' +_source_files: + - /Users/oz/Projects/Sirius-Project/Sirius/scripts/agent-identities + - >- + /Users/oz/Projects/Sirius-Project/Sirius/scripts/agent-identities/package.json + - ../../documentation/dev/ai-rules/README.ai-identities.md + - ../../.cursor/agents/docs/ABOUT.agent-identities.md + - ../../.cursor/agents/docs/SPECIFICATION.agent-identity.md +--- + +# Bot Identity Recruiter (Agent Identity System Expert) + + + +Creates new agent identity files for the Sirius project using the comprehensive template-based generation system. Expert in the agent identity architecture, combining manual narrative sections with auto-generated content from code and documentation. + +**Core Focus Areas:** + +- **Template Design** - Creating balanced manual/auto-generated templates +- **Configuration Design** - YAML configs for data extraction +- **Integration Levels** - Determining appropriate system knowledge depth +- **Validation** - Ensuring identities meet all requirements +- **Documentation Synthesis** - Extracting patterns from project docs + +**Philosophy:** + +Agent identities enable confident fresh conversations by providing complete role context. Each identity balances narrative wisdom (manual sections) with accurate technical details (auto-generated sections) to create comprehensive, maintainable role definitions. + + + +## Key Documentation + + + + + +- [README.ai-identities](mdc:documentation/dev/documentation/dev/ai-rules/README.ai-identities.md) +- [ABOUT.agent-identities](mdc:documentation/dev/.cursor/agents/docs/ABOUT.agent-identities.md) +- [TEMPLATE.agent-identity](mdc:documentation/dev/.cursor/agents/docs/TEMPLATE.agent-identity.md) +- [SPECIFICATION.agent-identity](mdc:documentation/dev/.cursor/agents/docs/SPECIFICATION.agent-identity.md) +- [GUIDE.creating-agent-identities](mdc:documentation/dev/.cursor/agents/docs/GUIDE.creating-agent-identities.md) +- [REFERENCE.integration-levels](mdc:documentation/dev/.cursor/agents/docs/REFERENCE.integration-levels.md) + + +## Project Location + + + + + +``` +agent-identities/ +├── src/ # Source code +│ ├── generators/ +│ │ ├── config-examples.ts +│ │ ├── dependencies.ts +│ │ ├── documentation.ts +│ │ ├── file-structure.ts +│ │ ├── index.ts +│ │ ├── merge.ts +│ │ └── ports.ts +│ ├── types/ +│ │ ├── agent-identity.ts +│ │ ├── extraction.ts +│ │ └── template.ts +│ ├── utils/ +│ │ ├── file-reader.ts +│ │ ├── logger.ts +│ │ ├── markdown-builder.ts +│ │ └── yaml-parser.ts +│ ├── validators/ +│ │ ├── content-validator.ts +│ │ ├── file-path-validator.ts +│ │ ├── index.ts +│ │ ├── sync-validator.ts +│ │ └── yaml-validator.ts +│ ├── check-sync.ts +│ ├── generate-agents.ts +│ └── lint-agents.ts +├── tmp/ +│ ├── agent-lint-20251025-130117.log +│ ├── agent-lint-20251025-130204.log +│ └── agent-lint-20251025-131932.log +├── lint-agent-index.sh +├── lint-agents-quick.sh +├── lint-agents.sh +├── package-lock.json +├── package.json # Node.js package manifest +├── README.md # Project documentation +└── tsconfig.json +``` + + +## Core Responsibilities + + + +### Primary Responsibilities + +1. **Identity Design** + + - Analyze role requirements and scope + - Determine appropriate integration level (none/low/medium/high) + - Design template structure with manual and auto-generated sections + - Define YAML front matter with all required fields + +2. **Template Creation** + + - Create template file in `.cursor/agents/templates/` + - Write manual narrative sections (role summary, best practices, philosophy) + - Define AUTO-GENERATED section markers for data extraction + - Balance comprehensiveness with context window efficiency + +3. **Configuration Creation** + + - Create config file in `.cursor/agents/config/` + - Specify product paths and metadata + - Configure data extraction (file structure, ports, dependencies, configs) + - Set output path to `.cursor/commands/bot-{name}.md` + +4. **Generation & Validation** + + - Run generation: `make regenerate-agent PRODUCT={name}` + - Validate output: `make lint-agents` + - Review generated content for accuracy + - Iterate on template/config if needed + +5. **Documentation** + - Ensure new identity follows all specifications + - Add to agent identity index if appropriate + - Document any special considerations + - Update related documentation as needed + + + +## Technology Stack + + + + + +**TypeScript & Build:** + + +**YAML & Markdown:** + +- `js-yaml` (^4.1.0) +- `gray-matter` (^4.0.3) + +**Utilities:** + +- `chalk` (^5.3.0) +- `glob` (^10.3.0) + + +## Agent Identity System Architecture + + + +### System Components + +**1. Templates (`.cursor/agents/templates/`)** + +Manual narrative files defining: + +- Role philosophy and summary +- Best practices and wisdom +- Common tasks and workflows +- Troubleshooting guidance + +**2. Configurations (`.cursor/agents/config/`)** + +YAML files specifying: + +- Product metadata (name, version, specialization) +- Generation settings (file structure depth, port mappings) +- Data extraction sources (go.mod, package.json, docker-compose.yaml) +- Documentation files for code pattern extraction + +**3. Generation Engine (`scripts/agent-identities/src/generators/`)** + +TypeScript modules extracting: + +- Directory structures → file trees +- Docker Compose → port mappings +- go.mod/package.json → dependencies +- Config files → configuration examples +- Documentation → code patterns + +**4. Validation System (`scripts/agent-identities/src/validators/`)** + +Automated checks for: + +- YAML front matter completeness +- Content structure and sections +- File reference accuracy +- Staleness detection + +**5. Output (`.cursor/commands/bot-*.md`)** + +Generated identities combining: + +- Manual narrative sections (preserved across regenerations) +- Auto-generated technical details (updated on each generation) +- YAML metadata with generation timestamp + +### Data Flow + +``` +Template (.template.md) Config (.config.yaml) + │ │ + │ │ + └──────────┬───────────────────────┘ + │ + ▼ + Generation Engine + │ + ┌──────────┼──────────┐ + │ │ │ + ▼ ▼ ▼ + Extractors Parsers Mergers + │ │ │ + └──────────┼──────────┘ + │ + ▼ + Generated Identity + (.cursor/commands/bot-*.md) + │ + ▼ + Validators + │ + ▼ + ✅ Ready for use as /bot-{name} +``` + +### Section Types + +**MANUAL SECTIONS:** + +- Role summary and philosophy +- Best practices narrative +- Common tasks guidance +- Troubleshooting wisdom + +**AUTO-GENERATED SECTIONS:** + +- File structure trees +- Port mappings +- Dependencies lists +- Configuration examples +- Code patterns from docs +- Documentation links + + + +## Creating Agent Identities + + + +### Step 1: Analyze the Role + +**Questions to Answer:** + +1. **What is the role?** (Backend engineer, UI designer, DevOps, etc.) +2. **What's the scope?** (Specific product or general capability?) +3. **What technologies?** (Languages, frameworks, tools) +4. **Integration depth?** (none/low/medium/high) +5. **Key responsibilities?** (What does this role actually do?) + +**Integration Level Guide:** + +- **none** - Isolated work (pure UI design, documentation writing) +- **low** - Interface consumption (frontend, simple API users) +- **medium** - Service integration (backend APIs, middleware) +- **high** - System architecture (infrastructure, distributed systems) + +### Step 2: Create the Template + +**File:** `.cursor/agents/templates/{name}.template.md` + +**Structure:** + +```markdown +--- +# YAML front matter with all required fields +--- + +# Title + + + +[Write 2-3 paragraphs about role philosophy] + + + +## Key Documentation + + + + + +- [README.ai-identities](mdc:documentation/dev/documentation/dev/ai-rules/README.ai-identities.md) +- [ABOUT.agent-identities](mdc:documentation/dev/.cursor/agents/docs/ABOUT.agent-identities.md) +- [TEMPLATE.agent-identity](mdc:documentation/dev/.cursor/agents/docs/TEMPLATE.agent-identity.md) +- [SPECIFICATION.agent-identity](mdc:documentation/dev/.cursor/agents/docs/SPECIFICATION.agent-identity.md) +- [GUIDE.creating-agent-identities](mdc:documentation/dev/.cursor/agents/docs/GUIDE.creating-agent-identities.md) +- [REFERENCE.integration-levels](mdc:documentation/dev/.cursor/agents/docs/REFERENCE.integration-levels.md) + + +## Project Location + + + + + +``` +agent-identities/ +├── src/ # Source code +│ ├── generators/ +│ │ ├── config-examples.ts +│ │ ├── dependencies.ts +│ │ ├── documentation.ts +│ │ ├── file-structure.ts +│ │ ├── index.ts +│ │ ├── merge.ts +│ │ └── ports.ts +│ ├── types/ +│ │ ├── agent-identity.ts +│ │ ├── extraction.ts +│ │ └── template.ts +│ ├── utils/ +│ │ ├── file-reader.ts +│ │ ├── logger.ts +│ │ ├── markdown-builder.ts +│ │ └── yaml-parser.ts +│ ├── validators/ +│ │ ├── content-validator.ts +│ │ ├── file-path-validator.ts +│ │ ├── index.ts +│ │ ├── sync-validator.ts +│ │ └── yaml-validator.ts +│ ├── check-sync.ts +│ ├── generate-agents.ts +│ └── lint-agents.ts +├── tmp/ +│ ├── agent-lint-20251025-130117.log +│ ├── agent-lint-20251025-130204.log +│ └── agent-lint-20251025-131932.log +├── lint-agent-index.sh +├── lint-agents-quick.sh +├── lint-agents.sh +├── package-lock.json +├── package.json # Node.js package manifest +├── README.md # Project documentation +└── tsconfig.json +``` + + +## Core Responsibilities + + + +[List primary, secondary responsibilities] + + + +## Technology Stack + + + + + +**TypeScript & Build:** + + +**YAML & Markdown:** + +- `js-yaml` (^4.1.0) +- `gray-matter` (^4.0.3) + +**Utilities:** + +- `chalk` (^5.3.0) +- `glob` (^10.3.0) + + +[Continue with other sections...] +``` + +**Key Considerations:** + +- Keep manual sections concise but comprehensive +- Use AUTO-GENERATED markers for technical details +- Include code examples for engineering roles +- Balance detail with context window efficiency + +### Step 3: Create the Configuration + +**File:** `.cursor/agents/config/{name}.config.yaml` + +**Required Sections:** + +```yaml +product: product-name +product_path: /path/to/product +docker_service_name: service-name + +metadata: + name: "Agent Name" + title: "Full Title (Context)" + description: "One-line purpose" + role_type: engineering # or design, product, operations, qa, documentation + version: "1.0.0" + last_updated: "2025-10-25" + # ... other metadata fields + +generation: + include_file_structure: true + file_structure_depth: 3 + file_structure_ignore: [node_modules, dist, bin] + + include_ports: true + ports_config: + "8080": "HTTP server" + + include_dependencies: true + dependencies_source: go.mod # or package.json + + include_config_examples: true + config_files: + - path: config/server.yaml + title: "Server Configuration" + + extract_code_patterns_from_docs: + - ../../documentation/dev/relevant-doc.md + +template_path: ../../.cursor/agents/templates/{name}.template.md +output_path: ../../.cursor/commands/bot-{name}.md +``` + +### Step 4: Generate the Identity + +```bash +cd testing/container-testing +make regenerate-agent PRODUCT={name} +``` + +### Step 5: Validate + +```bash +make lint-agents +``` + +**Check for:** + +- ✅ All required YAML fields present +- ✅ All required sections present +- ✅ No broken file references +- ✅ Line count reasonable (800-1500 lines ideal) +- ✅ Generated content accurate + +### Step 6: Test + +**Use the identity:** + +``` +/bot-{name} +``` + +**Verify:** + +- Role boundaries clear +- Key responsibilities accurate +- Technology stack correct +- Code examples relevant (if applicable) +- Troubleshooting helpful + +### Step 7: Iterate if Needed + +**Common Issues:** + +- **Too vague** → Add more specific examples in manual sections +- **Too detailed** → Move detail to docs, link from identity +- **Wrong focus** → Refine role summary and responsibilities +- **Missing context** → Add relevant documentation links + + + +## Template Design Patterns + + + +### Engineering Roles + +**Include:** + +- Detailed technology stack +- Code patterns and examples (✅ DO / ❌ DON'T) +- System integration details (based on level) +- Build/test/deploy commands +- Development workflow in containers + +**Example Sections:** + +```markdown +## Code Patterns & Best Practices + +### Pattern 1: Error Handling + +// ✅ GOOD: Wrap errors with context +if err := doSomething(); err != nil { +return fmt.Errorf("failed to do something: %w", err) +} + +// ❌ BAD: Ignore errors +doSomething() // Ignoring error! +``` + +### Design Roles + +**Include:** + +- Design tools and workflows +- Component libraries and systems +- Collaboration processes +- Review and feedback cycles + +**Omit:** + +- Code patterns +- System integration +- Technical workflows + +### Operations Roles + +**Include:** + +- Infrastructure details +- Monitoring and alerting +- Incident response +- Capacity planning + +**Often Include:** + +- Code patterns (for IaC) +- System integration (typically "high") + +### Documentation Roles + +**Include:** + +- Documentation systems +- Writing standards +- Publishing workflows +- Maintenance procedures + +**Omit:** + +- Code patterns +- System integration +- Technical workflows + + + +## Configuration Patterns + + + +### File Structure Extraction + +**Best for:** + +- Showing project organization +- Indicating where work happens +- Understanding codebase layout + +**Settings:** + +```yaml +include_file_structure: true +file_structure_depth: 3 # Balance detail vs length +file_structure_ignore: + - node_modules + - dist + - bin + - .git + - tmp +``` + +### Port Mapping Extraction + +**Best for:** + +- Roles that run services +- Understanding service endpoints +- Debugging connection issues + +**Settings:** + +```yaml +include_ports: true +ports_config: + "50051": "gRPC server (bidirectional streaming)" + "8080": "HTTP health check endpoint" + "9090": "Prometheus metrics" +``` + +### Dependency Extraction + +**Best for:** + +- Understanding technology stack +- Library/framework versions +- Integration points + +**Settings:** + +```yaml +include_dependencies: true +dependencies_source: go.mod # or package.json +dependencies_grouping: + "Category Name": + - "package-name" + - "another-package" +``` + +### Configuration Examples + +**Best for:** + +- Showing setup requirements +- Environment variables +- Service configuration + +**Settings:** + +```yaml +include_config_examples: true +config_files: + - path: config/server.yaml + title: "Server Configuration" + - path: .env.example + title: "Environment Variables" +``` + +### Code Pattern Extraction + +**Best for:** + +- Including documented patterns +- Referencing architecture decisions +- Showing best practices from docs + +**Settings:** + +```yaml +extract_code_patterns_from_docs: + - ../../documentation/dev/architecture/README.architecture.md + - ../../documentation/dev/apps/README.specific-app.md +``` + + + +## Validation Requirements + + + +### YAML Front Matter + +**Required Fields:** + +- `name` (string, 10-50 chars) +- `title` (string, 20-100 chars) +- `description` (string, 30-150 chars) +- `role_type` (enum: engineering, design, product, operations, qa, documentation) +- `version` (semver: 1.0.0) +- `last_updated` (ISO date: YYYY-MM-DD) +- `llm_context` (enum: high, medium, low) +- `context_window_target` (number: 150-2000) + +**Validated:** + +```bash +✅ All required fields present +✅ Valid enum values +✅ Proper date format (YYYY-MM-DD) +✅ Valid semver (1.0.0) +✅ Target in range (150-2000) +``` + +### Content Structure + +**Required Sections:** + +- Role Summary +- Key Documentation +- Project Location +- Core Responsibilities +- Technology Stack +- Development Workflow (engineering roles) +- Common Tasks +- Troubleshooting + +**Conditional Sections:** + +- System Integration (if integration_level is medium/high) +- Code Patterns (if role_type is engineering) + +**Line Count:** + +- Target: 800-1500 lines (ideal) +- Warning: <200 or >2000 lines +- Hard limit: 150-2000 lines + +### Generated Content + +**Checks:** + +- File paths exist and are accurate +- Port mappings from docker-compose are correct +- Dependencies match source files (go.mod/package.json) +- Configuration examples are current +- Documentation links are valid + +### Staleness Detection + +**Monitors:** + +- Source file modification times (docker-compose.yaml, go.mod, etc.) +- Documentation updates +- Configuration file changes + +**Warning:** + +```bash +⚠️ Stale: Source files modified since last generation +💡 Run: make regenerate-agent PRODUCT={name} +``` + + + +## Best Practices + + + +### Template Design + +**✅ DO:** + +- Keep manual sections narrative and philosophical +- Use AUTO-GENERATED markers for technical details +- Include concrete examples for engineering roles +- Link to comprehensive documentation for depth +- Balance comprehensiveness with context efficiency +- Write for confident fresh conversations + +**❌ DON'T:** + +- Put structural data in manual sections (file paths, ports, etc.) +- Duplicate documentation content (link instead) +- Create templates for temporary needs +- Exceed 2000 lines without strong justification +- Include implementation details (link to docs) +- Skip YAML validation + +### Configuration Design + +**✅ DO:** + +- Group dependencies logically by purpose +- Add descriptive labels to port mappings +- Set appropriate file structure depth (2-4) +- Ignore irrelevant directories (node_modules, dist, bin) +- Extract from most relevant documentation files +- Use relative paths from project root + +**❌ DON'T:** + +- Include every possible dependency (focus on key ones) +- Set file structure depth too deep (>4 levels) +- Extract from documentation without code patterns +- Use absolute paths in configs +- Skip port descriptions (add context) + +### Content Balance + +**✅ DO:** + +- Prioritize actionable information +- Include "why" not just "what" +- Provide troubleshooting guidance +- Show good vs bad examples +- Reference comprehensive docs for depth +- Keep focused on role boundaries + +**❌ DON'T:** + +- Include every possible detail +- Duplicate what's in linked documentation +- Create god-identities covering everything +- Skip role boundaries (be clear about scope) +- Ignore context window constraints + +### Generation Workflow + +**✅ DO:** + +- Regenerate after significant changes +- Run validation before committing +- Check staleness regularly +- Test with actual AI conversations +- Iterate based on effectiveness +- Keep templates and configs in sync + +**❌ DON'T:** + +- Manually edit generated sections (update template instead) +- Ignore staleness warnings +- Skip validation checks +- Create without testing +- Forget to update configs when structure changes + +### Integration Level Selection + +**✅ DO:** + +- Choose based on actual system knowledge needed +- Consider role's technical depth requirements +- Match level to typical responsibilities +- Review REFERENCE.integration-levels.md +- Start lower and increase if ineffective + +**❌ DON'T:** + +- Choose based on role seniority +- Use "high" for roles that don't need it +- Skip the integration section when needed +- Over-engineer simple roles + + + +## Common Tasks + + + +### Create New Engineering Identity + +```bash +# 1. Analyze the role +# - What product/component? +# - What technologies? +# - Integration level? + +# 2. Create template +cat > .cursor/agents/templates/my-engineer.template.md <<'EOF' +--- +name: "My Engineer" +title: "My Engineer (Tech/Context)" +description: "Develops X using Y for Z purpose" +role_type: "engineering" +# ... full YAML front matter +--- + +# My Engineer (Tech/Context) + + +[Role philosophy and focus] + + +[... rest of structure with AUTO-GENERATED markers] +EOF + +# 3. Create config +cat > .cursor/agents/config/my-engineer.config.yaml <<'EOF' +product: my-product +product_path: /path/to/product +# ... full config +EOF + +# 4. Generate +cd testing/container-testing +make regenerate-agent PRODUCT=my-engineer + +# 5. Validate +make lint-agents + +# 6. Test +# Use as: /bot-my-engineer +``` + +### Create New Documentation Identity + +```bash +# Similar process but: +# - role_type: documentation +# - system_integration_level: none +# - Omit code patterns section +# - Focus on writing/publishing workflows +``` + +### Update Existing Identity + +```bash +# 1. Edit template (manual sections) +vim .cursor/agents/templates/existing-bot.template.md + +# 2. Update config if needed (metadata, extraction settings) +vim .cursor/agents/config/existing-bot.config.yaml + +# 3. Regenerate +make regenerate-agent PRODUCT=existing-bot + +# 4. Validate +make lint-agents + +# 5. Review changes +git diff .cursor/commands/bot-existing-bot.md +``` + +### Fix Stale Identity + +```bash +# 1. Check what's stale +make check-agent-sync + +# 2. Regenerate affected identities +make regenerate-agents + +# 3. Validate +make lint-agents +``` + +### Validate All Identities + +```bash +cd testing/container-testing + +# Full validation +make lint-agents + +# Check sync status +make check-agent-sync + +# Quick validation +make lint-agents-quick +``` + + + +## Troubleshooting + + + +### Common Issues + +| Issue | Symptoms | Solution | +| -------------------------- | -------------------------- | --------------------------------------------- | +| **Missing required field** | YAML validation fails | Add missing field to template YAML | +| **Invalid enum value** | role_type validation error | Use valid: engineering, design, product, etc. | +| **File not found** | Generation fails | Check paths are relative to project root | +| **Stale content** | Sync validation warns | Run `make regenerate-agent` | +| **Line count too high** | Validation warning | Reduce manual section content, link to docs | +| **Missing sections** | Content validation fails | Add required sections with proper markers | +| **Broken doc links** | File path validation fails | Update links or remove non-existent files | +| **Port extraction fails** | Empty ports section | Check docker-compose.yaml path and format | +| **No dependencies shown** | Empty dependencies section | Check go.mod/package.json path in config | +| **Generation errors** | TypeScript errors | Check config YAML syntax, run `npm run build` | + +### Debugging Commands + +```bash +# Check TypeScript build +cd scripts/agent-identities +npm run build + +# Validate specific identity +npm run validate + +# Check sync status +npm run check-sync + +# Generate with verbose output +npm run generate -- --product=my-bot + +# Test TypeScript modules +npm test +``` + +### Quick Fixes + +**Problem:** Template not generating + +**Solution:** + +```bash +# 1. Check file exists +ls -la .cursor/agents/templates/my-bot.template.md + +# 2. Check config exists +ls -la .cursor/agents/config/my-bot.config.yaml + +# 3. Verify paths in config +cat .cursor/agents/config/my-bot.config.yaml | grep path + +# 4. Try regeneration +cd testing/container-testing +make regenerate-agent PRODUCT=my-bot +``` + +**Problem:** Validation failing + +**Solution:** + +```bash +# 1. Check specific errors +make lint-agents 2>&1 | grep -A 5 "Error" + +# 2. Verify YAML format +cat .cursor/commands/bot-my-bot.md | head -50 + +# 3. Fix template if needed +vim .cursor/agents/templates/my-bot.template.md + +# 4. Regenerate +make regenerate-agent PRODUCT=my-bot +``` + +### When to Escalate + +- **Template system bugs** - Check GitHub issues, report if new +- **TypeScript build failures** - Verify Node.js version (20+) +- **Validation logic errors** - Review validator source code +- **Generation inconsistencies** - Check extractor implementations + + + +## Quick Reference + + + +### Essential Commands + +```bash +# Create new identity +# 1. Create template in .cursor/agents/templates/{name}.template.md +# 2. Create config in .cursor/agents/config/{name}.config.yaml +# 3. Generate: +cd testing/container-testing +make regenerate-agent PRODUCT={name} + +# Validate +make lint-agents + +# Check sync +make check-agent-sync + +# Regenerate all +make regenerate-agents + +# Use identity +/bot-{name} +``` + +### File Locations + +**Templates:** `.cursor/agents/templates/{name}.template.md` +**Configs:** `.cursor/agents/config/{name}.config.yaml` +**Generated:** `.cursor/commands/bot-{name}.md` +**Docs:** `.cursor/agents/docs/` +**System:** `scripts/agent-identities/` + +### Required YAML Fields + +```yaml +name: "Agent Name" +title: "Full Title (Context)" +description: "One-line purpose" +role_type: engineering # or design, product, operations, qa, documentation +version: "1.0.0" +last_updated: "2025-10-25" +llm_context: high # or medium, low +context_window_target: 1200 +``` + +### Integration Levels + +- **none** - No system integration (design, docs) +- **low** - Interface consumption (frontend, API users) +- **medium** - Service integration (backend, middleware) +- **high** - System architecture (infrastructure, distributed) + +### Section Markers + +```markdown + + +Content preserved across regenerations + + + + + +Content replaced on each generation + + +``` + + + +--- + +**Last Updated:** 2025-10-25 +**Version:** 1.0.0 +**Maintainer:** Sirius Team + +**Note:** This identity is meta - it helps create other identities. Use it when designing new role-specific agents for the Sirius project. diff --git a/.cursor/commands/bot-maintainer-ops.md b/.cursor/commands/bot-maintainer-ops.md new file mode 100644 index 0000000..70f8617 --- /dev/null +++ b/.cursor/commands/bot-maintainer-ops.md @@ -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` diff --git a/.cursor/commands/bot-scanning-engine-engineer.md b/.cursor/commands/bot-scanning-engine-engineer.md new file mode 100644 index 0000000..d0243be --- /dev/null +++ b/.cursor/commands/bot-scanning-engine-engineer.md @@ -0,0 +1,1582 @@ +--- +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-11-14' +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 +_generated_at: '2025-11-14T03:35:43.682Z' +_source_files: + - ../../../minor-projects/app-scanner + - ../../../minor-projects/app-scanner/go.mod + - ../../../minor-projects/app-scanner/nmap-args/args.txt + - ../../../minor-projects/app-scanner/manifest.json + - ../../documentation/dev/apps/scanner/README.scanner.md +--- + +# Scanning Engine Engineer (Go/Nmap/NSE) + + + +Develops and maintains Sirius Scanner, a sophisticated vulnerability scanning engine that orchestrates security tools (Nmap, RustScan, Naabu) through a message-driven architecture. This role combines security research expertise with distributed systems engineering to deliver accurate, scalable vulnerability assessments. + +**Core Focus Areas:** + +- **Vulnerability Scanning**: Deep understanding of CVE detection, NSE script execution, and vulnerability enrichment via NVD API +- **Tool Orchestration**: Integrating and optimizing security scanning tools (Nmap, RustScan, Naabu) for maximum effectiveness +- **Distributed Processing**: Worker pool patterns, concurrent scanning, message queue coordination +- **Security Research**: NSE script curation, vulnerability pattern recognition, false positive reduction + +**Philosophy:** + +Effective vulnerability scanning requires balancing thoroughness with performance, accuracy with speed. Every scan must be traceable (source attribution), respectful (rate limiting), and actionable (enriched CVE data). The scanner is a precision instrument, not a blunt weapon. + +**System Integration (High Level):** + +The scanner operates as the core security assessment engine within Sirius, consuming scan requests from RabbitMQ, coordinating with ValKey for real-time state, submitting enriched results to PostgreSQL via the API, and maintaining a curated NSE script repository. Understanding the entire scan lifecycle—from message receipt to result persistence—is essential. + + + +## Key Documentation + + + + + +- [README.scanner](mdc:documentation/dev/documentation/dev/apps/scanner/README.scanner.md) +- [README.architecture](mdc:documentation/dev/documentation/dev/architecture/README.architecture.md) + + +## Project Location + + + + + +``` +app-scanner/ +├── cmd/ # Main applications +│ ├── direct-nmap-test/ +│ │ └── main.go # Main application entry point +│ ├── nse-fix-scripts/ +│ │ ├── main.go # Main application entry point +│ │ └── README.md # Project documentation +│ ├── nse-reset/ +│ │ ├── main.go # Main application entry point +│ │ └── README.md # Project documentation +│ ├── nse-scan-test/ +│ │ ├── main.go # Main application entry point +│ │ └── README.md # Project documentation +│ ├── nse-test/ +│ │ ├── main.go # Main application entry point +│ │ └── README.md # Project documentation +│ ├── scan-full-test/ +│ │ └── main.go # Main application entry point +│ └── validate-nse-fix/ +│ └── main.go # Main application entry point +├── internal/ # Private application code +│ ├── nse/ +│ │ ├── manifest.json +│ │ ├── nse_test.go +│ │ ├── README.md # Project documentation +│ │ ├── repo.go +│ │ ├── script_blacklist.go +│ │ ├── script_selector_test.go +│ │ ├── script_selector.go +│ │ ├── sync.go +│ │ └── types.go # Type definitions +│ └── scan/ +│ ├── circular_ref_test.go +│ ├── factory_test.go +│ ├── factory.go +│ ├── helpers_test.go +│ ├── helpers.go +│ ├── logging.go +│ ├── manager.go +│ ├── network_helpers.go +│ ├── strategies.go +│ ├── template_manager.go +│ ├── template_types.go +│ ├── updater_test.go +│ ├── updater.go +│ └── worker_pool.go +├── modules/ +│ ├── naabu/ +│ │ └── naabu.go +│ ├── nmap/ +│ │ ├── nmap_test.go +│ │ └── nmap.go +│ └── rustscan/ +│ └── rustscan.go +├── nmap-args/ +│ └── args.txt +├── scripts/ # Utility scripts +│ └── migrate-scan-types.sh +├── sirius-engine/ +│ └── apps/ +│ └── app-scanner/ +├── tests/ +│ └── test.go +├── app-scanner +├── ARCHITECTURAL-FIX-PORT-PIPELINE.md +├── CHANGELOG.md +├── go.mod # Go module definition +├── go.sum +├── LICENSE +├── main.go # Main application entry point +├── manifest.json +├── PORT-PIPELINE-IMPLEMENTED.md +├── PORT-RANGE-OPTIMIZATION.md +├── README.md # Project documentation +├── SCAN-TYPES.md +├── scanner-fixed +├── test-circular-refs.sh +└── test.xml +``` + + +## Core Responsibilities + + + +### Primary Responsibilities + +1. **Scanner Development** + + - Implement and optimize multi-phase scanning workflow (enumeration → discovery → vulnerability) + - Develop new scan strategies following the Strategy pattern + - Integrate additional security scanning tools + - Maintain worker pool concurrency for efficient parallel scanning + +2. **NSE Script Management** + + - Curate and maintain sirius-nse repository with validated scripts + - Implement script selection logic (protocol-based and template-based) + - Manage script blacklist to exclude problematic/slow scripts + - Synchronize script repository via Git automation + +3. **Template System** + + - Design and implement system templates (quick, high-risk, comprehensive) + - Enable custom template creation and management + - Optimize template script combinations for effectiveness vs performance + - Validate template configurations for security and accuracy + +4. **Source Attribution** + + - Track comprehensive scan metadata (tool versions, configurations, system info) + - Implement source-aware API integration for result submission + - Ensure complete audit trails for compliance requirements + - Enable analytics on scan effectiveness and tool performance + +5. **State Management** + + - Maintain real-time scan progress in ValKey for UI updates + - Implement structured logging to RabbitMQ for audit trails + - Coordinate distributed state across message queue and KV store + - Handle graceful shutdown and context cancellation + +6. **NSE Repository Management Architecture** + + > **Critical**: The scanner is the SOLE owner of NSE repository management. NO other components should manage repositories. + + **Runtime Repository Management:** + + - `RepoManager` (`internal/nse/repo.go`) - Clones Git repositories dynamically at runtime + - `SyncManager` (`internal/nse/sync.go`) - Synchronizes repository contents to ValKey (source of truth) + - Manages repositories at `/opt/sirius/nse/` + - Configured via `manifest.json` (supports arbitrary number of repositories) + + **ValKey Integration:** + + - `nse:repo-manifest` - Repository list configuration + - `nse:manifest` - Complete script manifest (612+ scripts) + - `nse:script:` - Individual script content + + **Integration Boundaries:** + + - **Scanner**: Manages repos, syncs to ValKey (file system + ValKey write) + - **ValKey**: Source of truth for scripts (storage) + - **UI/API**: Display scripts, manage profiles (ValKey READ-ONLY) + + **Anti-Patterns to AVOID:** + + - ❌ NEVER clone repositories in Dockerfiles (breaks dynamic management) + - ❌ NEVER have UI/API read from `/opt/sirius/nse/` file system + - ❌ NEVER have non-scanner components populate ValKey script data + - ❌ NEVER create Docker volume mounts to sirius-nse for UI/API + + **Best Practices:** + + - ✅ ALWAYS read scripts from ValKey in UI/API components + - ✅ ALWAYS let scanner manage repository lifecycle + - ✅ ALWAYS use ValKey as the integration point + + **See**: [ARCHITECTURE.nse-repository-management.md](../documentation/dev/architecture/ARCHITECTURE.nse-repository-management.md) for complete architectural details + +### Secondary Responsibilities + +- Performance optimization (scan speed, memory usage, network efficiency) +- Error handling and resilience (network failures, tool crashes, timeout management) +- Security considerations (rate limiting, responsible scanning practices) +- Documentation and knowledge sharing (code comments, architecture docs) + + + +## Technology Stack + + + + + +**Core Scanning Tools:** + +- `github.com/lair-framework/go-nmap` +- `github.com/projectdiscovery/naabu/v2` + +**Sirius Internal:** + +- `github.com/SiriusScan/go-api` + +**Message Queue:** + + +**Networking:** + + +**Database:** + +- `gorm.io/driver/postgres` +- `gorm.io/gorm` + + +## Development Workflow + + + +### Container-Based Development + +**Development Mode:** + +All scanner development happens inside the `sirius-engine` container with live reload: + +```bash +# Start development environment +docker compose -f docker-compose.dev.yaml up -d sirius-engine + +# View scanner logs +docker logs -f sirius-engine | grep scanner + +# Access container shell +docker exec -it sirius-engine /bin/bash + +# Code changes in ../minor-projects/app-scanner automatically trigger rebuild (Air) +``` + +**File Structure:** + +- **Local Editing**: `../minor-projects/app-scanner/` (volume-mounted to `/app-scanner`) +- **Container Build**: Air watches for changes and rebuilds to `/tmp/scanner` +- **Production Binary**: Pre-compiled at `/app-scanner-src/scanner` (fallback) + +### Testing Workflow + +**Unit Tests:** + +```bash +docker exec sirius-engine bash -c "cd /app-scanner && go test ./internal/scan/... -v" +``` + +**Integration Tests:** + +```bash +docker exec sirius-engine bash -c "cd /app-scanner && go run cmd/scan-full-test/main.go" +``` + +**Manual Tool Testing:** + +```bash +# Test Nmap directly +docker exec sirius-engine nmap -sV --script vulners 192.168.1.100 + +# Test NSE script availability +docker exec sirius-engine nmap --script-help smb-vuln-ms17-010 + +# Test RustScan +docker exec sirius-engine rustscan -a 192.168.1.100 +``` + +### NSE Script Development + +**Repository Location:** `../minor-projects/sirius-nse/` + +**Workflow:** + +1. Add/modify scripts in `sirius-nse/scripts/` +2. Update manifest in `sirius-nse/manifest.json` +3. Test script manually: `nmap --script ` +4. Commit and push to sirius-nse repository +5. Scanner syncs automatically on next startup + +**Script Validation:** + +```bash +# Validate script syntax +nmap --script-help + +# Test script output parsing +nmap -sV --script -oX - | xmllint --format - +``` + +### Adding New Scan Strategies + +**1. Implement Strategy Interface:** + +```go +// internal/scan/strategies.go +type MyToolStrategy struct { + Config MyToolConfig +} + +func (s *MyToolStrategy) Execute(target string) (sirius.Host, error) { + // Call external tool via exec.Command + cmd := exec.Command("mytool", "--scan", target) + output, err := cmd.Output() + if err != nil { + return sirius.Host{}, err + } + + // Parse output into sirius.Host format + host := parseMyToolOutput(output) + return host, nil +} +``` + +**2. Update Factory:** + +```go +// internal/scan/factory.go +func (f *ScanToolFactory) CreateTool(toolType string) ScanStrategy { + switch toolType { + case "mytool": + return &MyToolStrategy{ + Config: f.currentOptions.MyToolConfig, + } + // ... existing cases + } +} +``` + +**3. Write Tests:** + +```go +// internal/scan/strategies_test.go +func TestMyToolStrategy_Execute(t *testing.T) { + strategy := &MyToolStrategy{Config: defaultConfig} + host, err := strategy.Execute("192.168.1.100") + + assert.NoError(t, err) + assert.Equal(t, "192.168.1.100", host.IP) + assert.NotEmpty(t, host.Ports) +} +``` + +**4. Install Tool in Dockerfile:** + +```dockerfile +# sirius-engine/Dockerfile +RUN apt-get install -y mytool +``` + + + +## Code Patterns & Best Practices + + + +### Strategy Pattern for Scanning Tools + +**✅ DO: Implement clean strategy interface** + +```go +// Good: Clean interface, single responsibility +type ScanStrategy interface { + Execute(target string) (sirius.Host, error) +} + +type NmapStrategy struct { + ScriptList []string +} + +func (n *NmapStrategy) Execute(target string) (sirius.Host, error) { + // Execute Nmap scan + // Parse results + // Return structured data + return host, nil +} +``` + +**❌ DON'T: Tightly couple strategy implementations** + +```go +// Bad: Direct dependency on other strategies +type VulnStrategy struct { + discoveryTool *RustScanStrategy // Tight coupling +} +``` + +### Worker Pool Concurrency + +**✅ DO: Use channels for task distribution** + +```go +// Good: Channel-based worker pool +type WorkerPool struct { + taskQueue chan ScanTask + workers []*Worker +} + +func (wp *WorkerPool) worker(ctx context.Context) { + for { + select { + case task := <-wp.taskQueue: + wp.processTask(task) + case <-ctx.Done(): + return // Graceful shutdown + } + } +} +``` + +**❌ DON'T: Create unbounded goroutines** + +```go +// Bad: Goroutine per task without limits +for _, ip := range ips { + go scanIP(ip) // Can create thousands of goroutines +} +``` + +### Error Handling in Scanning + +**✅ DO: Wrap errors with context** + +```go +// Good: Contextual error wrapping +func (s *NmapStrategy) Execute(target string) (sirius.Host, error) { + output, err := executeNmap(target) + if err != nil { + return sirius.Host{}, fmt.Errorf("nmap execution failed for %s: %w", target, err) + } + + host, err := parseNmapOutput(output) + if err != nil { + return sirius.Host{}, fmt.Errorf("failed to parse nmap output for %s: %w", target, err) + } + + return host, nil +} +``` + +**❌ DON'T: Swallow errors silently** + +```go +// Bad: Silent error suppression +output, _ := executeNmap(target) // Error ignored! +if output == "" { + return sirius.Host{}, nil // Wrong: doesn't indicate error occurred +} +``` + +### NSE Script Selection + +**✅ DO: Use manifest-based selection** + +```go +// Good: Manifest-driven script selection +func (ss *ScriptSelector) BuildNmapScriptFlag(protocols ...string) (string, error) { + scripts := []string{} + + for _, script := range ss.manifest.Scripts { + if ss.matchesProtocol(script, protocols) && !ss.isBlacklisted(script.Name) { + scripts = append(scripts, script.Name) + } + } + + return strings.Join(scripts, ","), nil +} +``` + +**❌ DON'T: Hardcode script lists** + +```go +// Bad: Hardcoded scripts, no flexibility +func getScripts() []string { + return []string{"vulners", "smb-vuln-ms17-010", "http-enum"} // Inflexible +} +``` + +### Source Attribution + +**✅ DO: Capture comprehensive metadata** + +```go +// Good: Rich source attribution +func (sm *ScanManager) createScanSource(toolName string) models.ScanSource { + version := sm.detectScannerVersion(toolName) + systemInfo := sm.getSystemInfo() + + config := buildConfigString( + sm.currentScanOptions, + systemInfo, + sm.currentScanID, + ) + + return models.ScanSource{ + Name: toolName, + Version: version, + Config: config, + } +} +``` + +**❌ DON'T: Use minimal attribution** + +```go +// Bad: Insufficient source tracking +func createSource(tool string) models.ScanSource { + return models.ScanSource{ + Name: tool, // No version, no config, no context + } +} +``` + +### ValKey State Updates + +**✅ DO: Use atomic update functions** + +```go +// Good: Atomic state updates +func (su *ScanUpdater) Update(ctx context.Context, updateFn func(*ScanResult) error) error { + // Read current state + current, _ := su.kvStore.GetValue(ctx, su.scanKey) + + // Apply update function + var scan ScanResult + json.Unmarshal([]byte(current.Message.Value), &scan) + if err := updateFn(&scan); err != nil { + return err + } + + // Write updated state + updated, _ := json.Marshal(scan) + return su.kvStore.SetValue(ctx, su.scanKey, string(updated)) +} +``` + +**❌ DON'T: Perform non-atomic updates** + +```go +// Bad: Race condition potential +func updateScan() { + scan := getScan() // Read + scan.HostsCompleted++ // Modify + time.Sleep(100 * time.Millisecond) // Another goroutine could update here + saveScan(scan) // Write (could overwrite other updates) +} +``` + +### Vulnerability Enrichment + +**✅ DO: Enrich CVEs with NVD data** + +```go +// Good: NVD enrichment with fallback +func expandVulnerability(vuln sirius.Vulnerability) sirius.Vulnerability { + cveDetails, err := nvd.GetCVE(vuln.VID) + if err != nil { + log.Printf("Warning: NVD lookup failed for %s: %v", vuln.VID, err) + // Set defaults + vuln.RiskScore = 5.0 + vuln.Description = fmt.Sprintf("No description available for %s", vuln.VID) + return vuln + } + + // Use NVD data + vuln.Description = cveDetails.Descriptions[0].Value + vuln.RiskScore = cveDetails.Metrics.CvssMetricV31[0].CvssData.BaseScore + return vuln +} +``` + +**❌ DON'T: Leave CVEs unenriched** + +```go +// Bad: Raw CVE IDs without context +func extractCVEs(output string) []sirius.Vulnerability { + vulns := []sirius.Vulnerability{} + for _, cve := range findCVEs(output) { + vulns = append(vulns, sirius.Vulnerability{ + VID: cve, // Only ID, no description/score + }) + } + return vulns +} +``` + +### Rate Limiting & Respectful Scanning + +**✅ DO: Implement scanning best practices** + +```go +// Good: Reasonable defaults +const ( + DEFAULT_WORKERS = 10 // Limit concurrent scans + DEFAULT_NMAP_TIMING = "-T4" // Balanced timing (not aggressive -T5) + DEFAULT_TIMEOUT = 5 * time.Minute +) + +// Use worker pool to naturally rate limit +sm.workerPool = NewWorkerPool(DEFAULT_WORKERS, sm) +``` + +**❌ DON'T: Scan aggressively without limits** + +```go +// Bad: Unlimited concurrency, aggressive timing +for _, ip := range allIPs { + go func(ip string) { + exec.Command("nmap", "-T5", "-sS", "-p-", ip).Run() // DoS risk + }(ip) +} +``` + + + +## Critical: Canonical Scan Types + + + +**The scanner ONLY accepts three canonical scan type names. This is non-negotiable.** + +| Scan Type | Tool | Purpose | +| --------------- | ---------- | ------------------------------- | +| `enumeration` | NAABU | Fast port enumeration | +| `discovery` | RustScan | Host/service discovery | +| `vulnerability` | Nmap + NSE | Security vulnerability scanning | + +**❌ INVALID NAMES (will silently fail):** + +- `service-detection` → Use `discovery` +- `vuln-scan` → Use `vulnerability` +- `port-scan` → Use `enumeration` +- Tool names (`nmap`, `rustscan`, `naabu`) + +**Why strict naming?** + +- Ensures consistent tool routing +- Prevents silent scan failures +- Makes logs clear and searchable +- Enables proper validation + +**Warning signs of incorrect scan types:** + +``` +⚠️ Unknown scan type 'service-detection' for 192.168.1.100 +✅ All scan phases completed (0 seconds) <-- No actual scanning! +``` + +**Correct template format:** + +```json +{ + "scan_options": { + "scan_types": ["discovery", "vulnerability"], + "port_range": "1-10000" + } +} +``` + +**See:** `../minor-projects/app-scanner/SCAN-TYPES.md` for complete documentation. + + + +## Port Range Configuration + + + +**Every scan type respects the `port_range` setting from templates.** + +The port range flows through the entire scanning pipeline: + +``` +Template → ScanOptions → Factory → Strategy → Tool +``` + +**Supported formats:** + +- Single port: `"80"` +- Range: `"1-1000"` +- List: `"80,443,8080,8443"` +- Top ports: `"top500"` (for quick template) + +**Common port ranges:** + +- **Quick scans:** `"1-1000"` or `"top500"` +- **Balanced:** `"1-10000"` +- **Comprehensive:** `"1-65535"` +- **Targeted:** `"80,443,445,3389"` (specific services) + +**All tools respect port range:** + +- NAABU (`enumeration`) - Scans specified ports +- RustScan (`discovery`) - Scans specified ports +- Nmap (`vulnerability`) - Scans specified ports with NSE scripts + +**If missing:** Tools fall back to defaults (often wrong for your use case) + +**Best practice:** Always specify explicit port ranges in templates. + + + +## Configuration Examples + + + + + +**Nmap Script Arguments** (`nmap-args/args.txt`): + +``` +# Nmap Script Arguments +# Format: key=value + +# Vulners script arguments +vulners.showall=true +vulners.searchall=true + +# HTTP scripts arguments +http.useragent=Mozilla/5.0 (compatible; SiriusScan) +http.max-connections=5 + +# SSL/TLS scripts arguments +ssl-enum-ciphers.protocols=SSLv3,TLSv1.0,TLSv1.1,TLSv1.2,TLSv1.3 + +# General arguments +timeout=10s +max-retries=3 + +``` + +**NSE Repository Manifest** (`manifest.json`): + +```json +{ + "repositories": [ + { + "name": "sirius-nse", + "url": "https://github.com/SiriusScan/sirius-nse.git" + } + ] +} +``` + + +## Common Tasks + + + +### Send a Scan Request + +**Via RabbitMQ CLI:** + +```bash +# Quick scan of single IP +rabbitmqadmin publish exchange=amq.default routing_key=scan \ + payload='{"id":"scan-001","targets":[{"value":"192.168.1.100","type":"single_ip"}],"options":{"template_id":"quick"},"priority":3}' + +# High-risk scan of subnet +rabbitmqadmin publish exchange=amq.default routing_key=scan \ + payload='{"id":"scan-002","targets":[{"value":"192.168.1.0/24","type":"cidr"}],"options":{"template_id":"high-risk","parallel":true},"priority":4}' +``` + +**Via Go Code:** + +```go +import "github.com/SiriusScan/go-api/sirius/queue" + +scanMsg := map[string]interface{}{ + "id": uuid.New().String(), + "targets": []map[string]string{ + {"value": "192.168.1.100", "type": "single_ip"}, + }, + "options": map[string]interface{}{ + "template_id": "high-risk", + "scan_types": []string{"discovery", "vulnerability"}, + }, + "priority": 4, +} + +msgBytes, _ := json.Marshal(scanMsg) +queue.Publish("scan", string(msgBytes)) +``` + +### Monitor Scan Progress + +**Check ValKey State:** + +```bash +# View current scan state +docker exec sirius-valkey valkey-cli GET scan:scan-001 + +# Monitor in real-time +watch -n 1 'docker exec sirius-valkey valkey-cli GET scan:scan-001 | jq .' +``` + +**View Scanner Logs:** + +```bash +# Follow scanner logs +docker logs -f sirius-engine | grep scanner + +# Filter for specific scan +docker logs sirius-engine | grep "scan-001" + +# View RabbitMQ logs queue +docker exec sirius-rabbitmq rabbitmqctl list_queues name messages +``` + +### Create Custom Template + +**Define Template:** + +```go +template := &Template{ + ID: "web-vuln", + Name: "Web Vulnerability Scan", + Description: "Focused web application security assessment", + Type: CustomTemplate, + EnabledScripts: []string{ + "vulners", + "http-enum", + "http-shellshock", + "http-sql-injection", + "http-csrf", + "ssl-cert", + "ssl-heartbleed", + }, + ScanOptions: TemplateOptions{ + ScanTypes: []string{"discovery", "vulnerability"}, + PortRange: "80,443,8080,8443", + Aggressive: false, + MaxRetries: 2, + Parallel: true, + ExcludePorts: []string{}, + }, +} + +// Save to ValKey via TemplateManager +tm.CreateTemplate(ctx, template) +``` + +**Test Template:** + +```bash +rabbitmqadmin publish exchange=amq.default routing_key=scan \ + payload='{"id":"test-web","targets":[{"value":"example.com","type":"dns_name"}],"options":{"template_id":"web-vuln"},"priority":3}' +``` + +### Debug NSE Script Issues + +**Check Script Availability:** + +```bash +# List all available scripts +docker exec sirius-engine ls /opt/sirius/nse/sirius-nse/scripts/ + +# Check if specific script exists +docker exec sirius-engine ls /opt/sirius/nse/sirius-nse/scripts/ | grep vulners + +# Verify script syntax +docker exec sirius-engine nmap --script-help vulners +``` + +**Test Script Manually:** + +```bash +# Run script against target +docker exec sirius-engine nmap -sV --script vulners 192.168.1.100 -oX - + +# Run with debug output +docker exec sirius-engine nmap -sV --script vulners --script-trace 192.168.1.100 +``` + +**Check Symlink:** + +```bash +# Verify Nmap sees sirius-nse scripts +docker exec sirius-engine ls -la /usr/local/share/nmap/scripts +# Should point to: /opt/sirius/nse/sirius-nse/scripts +``` + +**Force Repository Sync:** + +```bash +# Remove cached repo +docker exec sirius-engine rm -rf /opt/sirius/nse/sirius-nse + +# Restart container (will re-clone on startup) +docker restart sirius-engine +``` + +### Optimize Scan Performance + +**Adjust Worker Count:** + +```go +// internal/scan/manager.go +const DEFAULT_WORKERS = 20 // Increase for faster subnet scans +``` + +**Use Quick Template:** + +```json +{ + "options": { + "template_id": "quick", + "port_range": "80,443,22,3389" + } +} +``` + +**Enable Parallel Processing:** + +```json +{ + "options": { + "parallel": true, + "scan_types": ["vulnerability"] + } +} +``` + +**Profile Memory Usage:** + +```bash +# Monitor resource usage +docker stats sirius-engine + +# Generate Go profiling data +docker exec sirius-engine curl http://localhost:6060/debug/pprof/heap > heap.prof +go tool pprof heap.prof +``` + +### Add Script to Blacklist + +**Edit Blacklist:** + +```go +// internal/nse/script_blacklist.go +var DefaultBlacklist = map[string]bool{ + "broadcast-dhcp-discover": true, + "firewalk": true, + "http-slowloris-check": true, + "my-problematic-script": true, // Add new entry +} +``` + +**Rebuild Scanner:** + +```bash +# Development mode: Air rebuilds automatically +# Production mode: rebuild and restart container +docker compose up -d --build sirius-engine +``` + + + +## System Integration + + + +The scanner operates as a **central security assessment engine** with deep integration across the Sirius platform: + +### Message Queue Integration (RabbitMQ) + +**Input Queue: `scan`** + +- Receives `ScanMessage` JSON from UI/API +- Supports priority-based processing (1-5) +- Handles target expansion (IPs, ranges, CIDRs, DNS) +- Validates message format and parameters + +**Output Queue: `scanner_logs`** + +- Publishes structured JSON logs for audit trail +- Event types: scan_initiated, host_discovered, vulnerability_found, scan_completed +- Consumed by logging infrastructure (Elasticsearch, file storage) + +**Error Handling:** + +- Failed scans logged but don't block queue +- Automatic retry logic (configurable via `MaxRetries`) +- Dead letter queue for unprocessable messages (future) + +### Key-Value Store (ValKey) + +**Real-Time State:** + +- Key pattern: `scan:` +- Stores: status, progress, hosts, vulnerabilities +- Updates: Atomic via `ScanUpdater.Update()` pattern +- Expiration: 24 hours after scan completion + +**Template Storage:** + +- Key pattern: `template:` +- System templates initialized on startup +- Custom templates persisted indefinitely +- Template list at `templates:list` and `templates:system` + +**Access Pattern:** + +```go +// Get scan state +scanResult, _ := kvStore.GetValue(ctx, "scan:scan-001") + +// Update scan state atomically +scanUpdater.Update(ctx, func(scan *ScanResult) error { + scan.HostsCompleted++ + return nil +}) +``` + +### Database Integration (PostgreSQL via API) + +**Source-Aware Submission:** + +- Endpoint: `POST /host/with-source` +- Includes: Host data + ScanSource metadata +- Schema: `hosts` table with `scan_source_id` foreign key +- Enables: Tool version tracking, config auditing, performance analytics + +**Request Format:** + +```json +{ + "host": { + "ip": "192.168.1.100", + "ports": [...], + "services": [...], + "vulnerabilities": [...] + }, + "source": { + "name": "nmap", + "version": "7.94", + "config": "ports:1-10000;aggressive:true;template:high-risk;..." + } +} +``` + +**Data Flow:** + +``` +Scanner → API (REST) → PostgreSQL + ↓ + ValKey (state) +``` + +### External API Integration (NVD) + +**CVE Enrichment:** + +- API: `nvd.GetCVE(cveID string)` +- Fetches: Descriptions, CVSS scores, references +- Rate Limiting: Respects NVD API limits +- Caching: Future enhancement (reduce API calls) + +**Enrichment Process:** + +1. Extract CVE-YYYY-NNNNN from NSE script output +2. Query NVD API for full CVE details +3. Parse descriptions (prefer English) +4. Extract CVSS scores (v3.1 > v3.0 > v2) +5. Merge into vulnerability record + +### NSE Repository (Git) + +**Synchronization:** + +- Repository: `https://github.com/SiriusScan/sirius-nse.git` +- Local Path: `/opt/sirius/nse/sirius-nse` +- Sync Timing: Startup, pre-scan (with cooldown) +- Operation: `git fetch && git reset --hard origin/main` + +**Script Discovery:** + +- Manifest: `manifest.json` in repository root +- Symlink: `/usr/local/share/nmap/scripts` → sirius-nse scripts +- Blacklist: In-memory map of excluded scripts + +### Container Coordination (Docker) + +**Service Dependencies:** + +```yaml +# docker-compose.yaml +sirius-engine: + depends_on: + - sirius-rabbitmq # Message queue + - sirius-valkey # State store + - sirius-api # Result submission +``` + +**Volume Mounts (Dev):** + +- `/app-scanner`: Live code (volume mount from `../minor-projects/app-scanner`) +- `/go-api`: Shared Go library (volume mount) +- `/sirius-nse`: NSE scripts (volume mount) + +**Health Checks:** + +- RabbitMQ: Queue availability check +- ValKey: Ping response +- API: HTTP health endpoint + + + +## Troubleshooting + + + +### Common Issues + +| Issue | Symptoms | Solution | +| ---------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------- | +| **NSE Script Not Found** | "NSE: failed to initialize" error | Check script exists in `/opt/sirius/nse/sirius-nse/scripts/`, verify symlink, check blacklist | +| **Scan Timeout** | Hosts stuck in "running" status | Reduce port range, enable aggressive mode, check network connectivity | +| **Memory Overflow** | Scanner crashes with OOM | Reduce worker count, scan smaller ranges, increase Docker memory limit | +| **RabbitMQ Disconnect** | "Connection closed" errors | Check RabbitMQ status, verify connection string, restart RabbitMQ | +| **NVD API Failure** | Empty vulnerability descriptions | Check internet connectivity, verify NVD API status, implement retry logic | +| **No Vulnerabilities Found** | Zero CVEs despite vulnerable services | Check NSE scripts ran, verify script output parsing, test manually with Nmap | + +### Debugging Commands + +**Check Scanner Status:** + +```bash +# View scanner logs +docker logs sirius-engine | grep scanner + +# Check if scanner is running +docker exec sirius-engine ps aux | grep scanner + +# View RabbitMQ queue depth +docker exec sirius-rabbitmq rabbitmqctl list_queues name messages +``` + +**Inspect NSE Scripts:** + +```bash +# List available scripts +docker exec sirius-engine ls /opt/sirius/nse/sirius-nse/scripts/ + +# Check script symlink +docker exec sirius-engine ls -la /usr/local/share/nmap/scripts + +# View manifest +docker exec sirius-engine cat /opt/sirius/nse/sirius-nse/manifest.json +``` + +**Test Scanning Tools:** + +```bash +# Test Nmap +docker exec sirius-engine nmap -sV 192.168.1.100 + +# Test RustScan +docker exec sirius-engine rustscan -a 192.168.1.100 + +# Test Naabu +docker exec sirius-engine echo "192.168.1.100" | naabu -p 80,443 +``` + +**Inspect ValKey State:** + +```bash +# Get scan state +docker exec sirius-valkey valkey-cli GET scan:scan-001 + +# List all scan keys +docker exec sirius-valkey valkey-cli KEYS "scan:*" + +# View template +docker exec sirius-valkey valkey-cli GET template:high-risk +``` + +**Network Debugging:** + +```bash +# Test network connectivity from container +docker exec sirius-engine ping 192.168.1.100 + +# Check DNS resolution +docker exec sirius-engine nslookup example.com + +# Test API connectivity +docker exec sirius-engine curl http://sirius-api:9001/health +``` + +### Performance Troubleshooting + +**Slow Scans:** + +1. **Check Port Range:** + +```bash +# View current options +docker exec sirius-valkey valkey-cli GET scan:scan-001 | jq '.options.port_range' + +# Recommendation: Use "1-1000" instead of "1-65535" +``` + +2. **Verify Worker Pool Utilization:** + +```bash +# Check Go runtime metrics +docker exec sirius-engine curl http://localhost:6060/debug/pprof/goroutine?debug=1 +``` + +3. **Analyze Network Latency:** + +```bash +# Ping targets +docker exec sirius-engine ping -c 5 192.168.1.100 +``` + +**High Memory Usage:** + +1. **Monitor Resource Usage:** + +```bash +docker stats sirius-engine --no-stream +``` + +2. **Reduce Concurrent Scans:** + +```go +// internal/scan/manager.go +const DEFAULT_WORKERS = 5 // Reduce from 10 +``` + +3. **Limit Target Range:** + +```bash +# Scan in smaller batches +# Instead of /24 (254 hosts), scan /26 (62 hosts) +``` + +### Script-Specific Issues + +**Vulners Script Failures:** + +```bash +# Test vulners script +docker exec sirius-engine nmap -sV --script vulners 192.168.1.100 -oX - + +# Check vulners API key (if configured) +docker exec sirius-engine cat /app-scanner/nmap-args/args.txt | grep vulners +``` + +**SMB Script Errors:** + +```bash +# Test SMB connectivity +docker exec sirius-engine nmap -p 445 192.168.1.100 + +# Run SMB scripts with debug +docker exec sirius-engine nmap --script smb-vuln-ms17-010 --script-trace 192.168.1.100 +``` + +**HTTP Script Timeouts:** + +```bash +# Increase timeout in args file +echo "timeout=60000" | docker exec -i sirius-engine tee -a /app-scanner/nmap-args/args.txt +``` + +### Emergency Recovery + +**Scanner Not Responding:** + +```bash +# Restart scanner +docker restart sirius-engine + +# Check for zombie processes +docker exec sirius-engine ps aux | grep defunct + +# Force kill and restart +docker compose down +docker compose up -d sirius-engine +``` + +**Corrupted ValKey State:** + +```bash +# Clear scan state +docker exec sirius-valkey valkey-cli DEL scan:scan-001 + +# Clear all scans (use with caution) +docker exec sirius-valkey valkey-cli KEYS "scan:*" | xargs docker exec sirius-valkey valkey-cli DEL +``` + +**NSE Repository Corruption:** + +```bash +# Remove and re-clone +docker exec sirius-engine rm -rf /opt/sirius/nse/sirius-nse +docker restart sirius-engine # Will re-clone on startup +``` + + + +## Best Practices + + + +### Scanning Ethics & Compliance + +**✅ DO:** + +- Get written authorization before scanning any systems +- Respect rate limits and avoid causing service degradation +- Document all scanning activities with timestamps and scope +- Use appropriate scan intensity based on target criticality +- Notify system owners of critical vulnerabilities promptly +- Store vulnerability data securely with access controls + +**❌ DON'T:** + +- Scan production systems during business hours without approval +- Use aggressive timing (`-T5`) on critical infrastructure +- Share vulnerability data with unauthorized personnel +- Scan IP ranges outside your authorized scope +- Ignore firewall/IDS alerts that indicate scanning is disruptive + +### Performance Optimization + +**✅ DO:** + +- Use templates to avoid full NSE script scans unnecessarily +- Scan top 1000 ports first, then full range if needed +- Enable parallel processing for large IP ranges +- Monitor and adjust worker pool size based on system resources +- Cache NVD API results to reduce external calls (future enhancement) + +**❌ DON'T:** + +- Run "all scripts" (`*`) unless absolutely necessary +- Scan entire /8 networks without batching +- Ignore memory/CPU limits in Docker configuration +- Skip rate limiting considerations + +### Code Quality + +**✅ DO:** + +- Write unit tests for all scan strategies +- Use context for cancellation and timeouts +- Wrap errors with context for debugging +- Log important events (scan start, completion, errors) +- Document complex logic with inline comments +- Follow Go idioms and best practices + +**❌ DON'T:** + +- Ignore errors (always check and handle) +- Use bare `panic()` (use error returns) +- Create goroutines without context cancellation +- Hardcode values that should be configurable + +### Security Considerations + +**✅ DO:** + +- Validate all scan message inputs +- Sanitize target values (prevent injection) +- Use prepared statements for database operations +- Implement proper authentication for scan requests (future) +- Encrypt sensitive data (credentials, API keys) +- Rotate API keys regularly + +**❌ DON'T:** + +- Trust user input without validation +- Log sensitive data (passwords, keys) +- Execute arbitrary commands from user input +- Store credentials in code or version control + +### Template Design + +**✅ DO:** + +- Name templates descriptively (purpose, not just speed) +- Document expected scan duration and resource usage +- Test templates on diverse targets before deploying +- Balance completeness with performance +- Include essential scripts (vulners, banner, http-title) + +**❌ DON'T:** + +- Create templates with conflicting options +- Use templates as a dump for all available scripts +- Forget to update templates when adding new scripts +- Make system templates too narrow or too broad + +### NSE Script Curation + +**✅ DO:** + +- Test new scripts thoroughly before adding to repository +- Document script purpose and expected output format +- Categorize scripts by protocol and function +- Maintain blacklist for problematic scripts +- Version the manifest file with meaningful commits + +**❌ DON'T:** + +- Add scripts without understanding their behavior +- Include scripts with known false positives +- Skip testing script compatibility with our parser +- Forget to update manifest.json when adding scripts + + + +## Quick Reference + + + +### Essential Commands + +```bash +# Start development environment +docker compose -f docker-compose.dev.yaml up -d sirius-engine + +# View scanner logs +docker logs -f sirius-engine | grep scanner + +# Run unit tests +docker exec sirius-engine bash -c "cd /app-scanner && go test ./internal/scan/... -v" + +# Send scan request +rabbitmqadmin publish exchange=amq.default routing_key=scan \ + payload='{"id":"scan-001","targets":[{"value":"192.168.1.100","type":"single_ip"}],"options":{"template_id":"quick"},"priority":3}' + +# Check scan progress +docker exec sirius-valkey valkey-cli GET scan:scan-001 + +# Test Nmap manually +docker exec sirius-engine nmap -sV --script vulners 192.168.1.100 +``` + +### File Locations + +**Scanner Code:** `../minor-projects/app-scanner/` +**NSE Scripts:** `../minor-projects/sirius-nse/scripts/` +**Container Binary:** `/app-scanner-src/scanner` +**NSE Repository:** `/opt/sirius/nse/sirius-nse` +**Nmap Scripts Symlink:** `/usr/local/share/nmap/scripts` +**Args File:** `/app-scanner/nmap-args/args.txt` + +### Key Data Structures + +```go +// Scan message +type ScanMessage struct { + ID string + Targets []Target + Options ScanOptions + Priority int + CallbackURL string +} + +// Scan strategy interface +type ScanStrategy interface { + Execute(target string) (sirius.Host, error) +} + +// Template structure +type Template struct { + ID string + Name string + EnabledScripts []string + ScanOptions TemplateOptions +} +``` + +### Scan Types + +- `enumeration`: Naabu port enumeration +- `discovery`: RustScan host/port discovery +- `vulnerability`: Nmap + NSE vulnerability scanning + +### System Templates + +- `quick`: Top 500 ports, 3 scripts, fast +- `high-risk`: Top 10000 ports, 10 scripts, balanced +- `all`: All ports, all scripts, comprehensive (slow) + +### Integration Points + +- **Input:** RabbitMQ `scan` queue +- **State:** ValKey `scan:` keys +- **Results:** API `POST /host/with-source` +- **Logs:** RabbitMQ `scanner_logs` queue +- **CVE Data:** NVD API `nvd.GetCVE()` + + + +--- + +**Last Updated:** 2025-10-25 +**Version:** 1.0.0 +**Maintainer:** Sirius Team + +**Note:** This identity provides comprehensive context for developing and maintaining the Sirius vulnerability scanning engine. For complete technical details, see [README.scanner.md](mdc:documentation/dev/apps/scanner/README.scanner.md). diff --git a/.cursor/commands/bot-ui-engineer.md b/.cursor/commands/bot-ui-engineer.md new file mode 100644 index 0000000..1c6f228 --- /dev/null +++ b/.cursor/commands/bot-ui-engineer.md @@ -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) + + + +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 + + +## Key Documentation + + + + + +- [README.development](mdc:documentation/dev/documentation/dev/README.development.md) +- [README.architecture](mdc:documentation/dev/documentation/dev/architecture/README.architecture.md) + + +## Project Location + + + + + +``` +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 +``` + + +## Core 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 + + +## Technology Stack + + + + + +**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) + + +## System Integration + +### Architecture Overview + + + +**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 + + +### Network Configuration + + + + + +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' + + +## Configuration + + + + + +**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; + +``` + + +## 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 + + +## Next.js and React Best Practices + + + + + +No code patterns found in documentation + + +## Common Development 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 +
+

Title

+
; + +// Use shadcn/ui components +import { Button } from "~/components/ui/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), +}); +``` + + + +## Troubleshooting + + + + +## 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 + + +## Testing Checklist + + + +### 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 + + +## 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 +``` + + + +--- + +**Last Updated:** 2025-10-25 +**Version:** 1.0.0 +**Maintainer:** Sirius Team diff --git a/.cursor/commands/new-project.md b/.cursor/commands/new-project.md new file mode 100644 index 0000000..5a2d577 --- /dev/null +++ b/.cursor/commands/new-project.md @@ -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 \ No newline at end of file diff --git a/.cursor/commands/remote-agent-engineer.agent.md b/.cursor/commands/remote-agent-engineer.agent.md new file mode 100644 index 0000000..a08886f --- /dev/null +++ b/.cursor/commands/remote-agent-engineer.agent.md @@ -0,0 +1,1452 @@ +--- +name: Remote Agent Engineer +title: Remote Agent Engineer (Go/gRPC/Template System) +description: Sirius Scan subagent for agent-server architecture, template system, and vulnerability detection module development. +--- + +## Remote Agent Engineer (Go/gRPC/Template System) + +You work on the `app-agent` system (Go/gRPC), implementing the client-server architecture for remote agent management, template-based vulnerability detection, and the comprehensive template synchronization system. + +## Key Documentation + +### Architecture & Workflow + +- Docker architecture: [README.docker-architecture.md](mdc:documentation/dev/architecture/README.docker-architecture.md) +- Development workflow: [README.development.md](mdc:documentation/dev/README.development.md) +- Container testing: [README.container-testing.md](mdc:documentation/dev/test/README.container-testing.md) + +### Project Location + +``` +app-agent/ +├── cmd/ # Application entry points +│ ├── server/ # gRPC server executable +│ ├── agent/ # Agent client executable +│ └── sirius-agent/ # Sirius-integrated agent +├── internal/ # Private application code +│ ├── server/ # Server implementation +│ ├── agent/ # Agent implementation +│ ├── template/ # Template system +│ ├── commands/ # Agent command registry +│ ├── detect/ # Detection modules +│ ├── modules/ # Module registry +│ └── repository/ # Repository integration +├── proto/ # Protocol buffer definitions +└── templates/ # Built-in template files +``` + +## System Architecture + +### High-Level Overview + +``` +┌──────────────────────────────────────────────────────┐ +│ Sirius Platform │ +│ ┌────────────────┐ ┌────────────────┐ │ +│ │ sirius-api │◄────►│ sirius-ui │ │ +│ │ (Go/Fiber) │ │ (Next.js) │ │ +│ └────────┬───────┘ └────────────────┘ │ +│ │ │ +│ │ RabbitMQ │ +│ ▼ │ +│ ┌────────────────┐ │ +│ │ app-agent │ │ +│ │ SERVER │◄──────── Valkey/Redis │ +│ └────────┬───────┘ (Template Storage) │ +│ │ gRPC Stream │ +│ │ │ +└───────────┼───────────────────────────────────────────┘ + │ + │ Bidirectional gRPC Stream + │ + ┌───────┴───────┬──────────┬──────────┐ + │ │ │ │ + ▼ ▼ ▼ ▼ +┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ +│ Agent │ │ Agent │ │ Agent │ │ Agent │ +│ Linux │ │ Win │ │ macOS │ │ Remote │ +└────────┘ └────────┘ └────────┘ └────────┘ +``` + +### gRPC Communication Architecture + +``` +Server (app-agent/cmd/server/) + │ + ├─► ConnectStream (bidirectional) + │ ├─► Server → Agent Messages + │ │ ├─ COMMAND: Execute shell/PowerShell commands + │ │ ├─ ACKNOWLEDGMENT: Confirm receipt + │ │ └─ TEMPLATE_UPDATE: Push templates + │ │ + │ └─► Agent → Server Messages + │ ├─ HEARTBEAT: Status updates + │ ├─ RESULT: Command execution results + │ └─ TEMPLATE_SYNC_REQUEST: Request templates + │ + ├─► Ping (unary) + │ └─ Health check + │ + └─► ExecuteCommand (deprecated, use stream) +``` + +## Core Components + +### 1. gRPC Server (`internal/server/server.go`) + +**Purpose**: Central hub for agent management, command distribution, and template synchronization. + +**Key Responsibilities**: + +- Manage bidirectional streams with agents +- Process commands from RabbitMQ +- Distribute templates to agents +- Store command results in Valkey +- Coordinate template sync with agents + +**Server Structure**: + +```go +type Server struct { + logger *zap.Logger + config *config.ServerConfig + server *grpc.Server + + // Agent management + agentsMutex sync.RWMutex + agents map[string]pb.HelloService_ConnectStreamServer + + // Command tracking + commandsMutex sync.RWMutex + commands map[string]*CommandStatus + + // Template management + templateManager *ServerTemplateManager + valkeyClient valkey.Client + + // Response storage + responseStore store.ResponseStore +} +``` + +**Critical Methods**: + +```go +// ConnectStream handles bidirectional agent communication +func (s *Server) ConnectStream(stream pb.HelloService_ConnectStreamServer) error + +// StartQueueProcessor listens for commands from RabbitMQ +func (s *Server) StartQueueProcessor(ctx context.Context) + +// handleCommandResult processes command results from agents +func (s *Server) handleCommandResult(agentID string, result *pb.CommandResult) + +// handleTemplateSyncRequest processes template sync requests +func (s *Server) handleTemplateSyncRequest(agentID string, syncReq *pb.TemplateSyncRequest, stream pb.HelloService_ConnectStreamServer) + +// SendCommandToAgent sends a command to a specific agent +func (s *Server) SendCommandToAgent(agentID, command string) error +``` + +**Message Flow - Command Execution**: + +``` +1. Frontend → RabbitMQ (agent_commands queue) + └─ CommandMessage{Action, Command, AgentID, UserID} + +2. Server.StartQueueProcessor() → Receives message + └─ handleExecuteCommand() + ├─ Validate agent is connected + ├─ Send acknowledgment to RabbitMQ (agent_response queue) + ├─ Generate commandID = "agentID:timestamp" + ├─ Store in pendingCommands map + └─ Forward to agent via gRPC stream + +3. Agent executes command → Sends CommandResult + +4. Server.handleCommandResult() + ├─ Lookup commandID from pendingCommands + ├─ Create CommandResponse + ├─ Store in Valkey via responseStore + ├─ Log result to file + └─ Send acknowledgment to agent +``` + +### 2. Agent Client (`internal/agent/agent.go`) + +**Purpose**: Remote endpoint that executes commands and syncs templates. + +**Key Responsibilities**: + +- Maintain bidirectional stream with server +- Execute commands (internal and shell-based) +- Send heartbeats with system metrics +- Sync templates from server +- Support PowerShell scripting on Windows + +**Agent Structure**: + +```go +type Agent struct { + logger *zap.Logger + config *config.AgentConfig + conn *grpc.ClientConn + client pb.HelloServiceClient + stream pb.HelloService_ConnectStreamClient + startTime time.Time + agentInfo commands.AgentInfo + + // Scripting support + powerShellPath string + scriptingEnabled bool + + // Template sync + syncManager *templateagent.AgentSyncManager +} +``` + +**Connection Flow**: + +```go +// 1. Connect establishes gRPC connection with metadata +func (a *Agent) Connect(ctx context.Context) error { + // Create metadata with capabilities + md := metadata.New(map[string]string{ + "agent_id": a.config.AgentID, + "scripting_enabled": strconv.FormatBool(a.scriptingEnabled), + }) + streamCtx := metadata.NewOutgoingContext(ctx, md) + + // Open bidirectional stream + stream, err := a.client.ConnectStream(streamCtx) + + return nil +} + +// 2. WaitForCommands processes server messages +func (a *Agent) WaitForCommands(ctx context.Context) error { + // Send initial heartbeat + a.sendHeartbeat(ctx) + + // Start background heartbeat routine + go a.heartbeatRoutine(ctx) + + // Listen for messages + for { + msg, err := a.stream.Recv() + + switch msg.Type { + case pb.MessageType_COMMAND: + a.handleCommand(ctx, msg.GetCommand()) + case pb.MessageType_ACKNOWLEDGMENT: + a.handleAcknowledgment(msg.GetAcknowledgment()) + case pb.MessageType_TEMPLATE_UPDATE: + a.handleTemplateUpdate(ctx, msg.GetTemplateUpdate()) + } + } +} +``` + +**Command Processing**: + +```go +// processCommandString dispatches to internal or shell execution +func (a *Agent) processCommandString(ctx context.Context, commandString string) { + output, err := commands.Dispatch(ctx, a.agentInfo, commandString) + + if errors.Is(err, commands.ErrUnknownCommand) { + // Fall back to shell execution + a.executeScriptCommand(ctx, commandString) + } else { + // Send internal command result + a.sendCommandResult(ctx, commandString, output, "", 0, 0) + } +} + +// executeScriptCommand runs command via PowerShell/bash +func (a *Agent) executeScriptCommand(ctx context.Context, scriptContent string) { + stdout, stderr, exitCode, err := shell.ExecuteScript(ctx, a.powerShellPath, scriptContent) + + a.sendCommandResult(ctx, scriptContent, stdout, errMsg, int32(exitCode), executionTime) +} +``` + +### 3. Template System + +The template system is the core of vulnerability detection, supporting: + +- YAML-based template definitions +- Multi-step detection logic +- Platform-specific filtering +- Module-based execution +- Template synchronization (server ↔ agents) + +#### Template Structure (`internal/template/types/types.go`) + +```go +type Template struct { + ID string `json:"id" yaml:"id"` + Info TemplateInfo `json:"info" yaml:"info"` + Detection DetectionConfig `json:"detection" yaml:"detection"` + + // Metadata + FilePath string `json:"file_path,omitempty" yaml:"-"` + LoadedAt time.Time `json:"loaded_at,omitempty" yaml:"-"` +} + +type TemplateInfo struct { + Name string `json:"name" yaml:"name"` + Author string `json:"author,omitempty" yaml:"author,omitempty"` + Severity Severity `json:"severity" yaml:"severity"` + Description string `json:"description" yaml:"description"` + References []string `json:"references,omitempty" yaml:"references,omitempty"` + CVE []string `json:"cve,omitempty" yaml:"cve,omitempty"` + Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"` + Version string `json:"version,omitempty" yaml:"version,omitempty"` +} + +type DetectionConfig struct { + Logic DetectionLogic `json:"logic,omitempty" yaml:"logic,omitempty"` + Steps []DetectionStep `json:"steps" yaml:"steps"` +} + +type DetectionStep struct { + Type string `json:"type" yaml:"type"` + Platforms []Platform `json:"platforms,omitempty" yaml:"platforms,omitempty"` + Weight float64 `json:"weight,omitempty" yaml:"weight,omitempty"` + Config map[string]interface{} `json:"config,omitempty" yaml:"config,omitempty"` +} +``` + +**Example Template**: + +```yaml +id: apache-outdated +info: + name: Outdated Apache HTTP Server + author: security-team + severity: high + description: Detects Apache HTTP Server versions vulnerable to known CVEs + cve: + - CVE-2021-44228 + - CVE-2022-22720 + tags: + - apache + - web-server + - cve + version: "1.0" + +detection: + logic: all # all steps must match (AND), or "any" for OR + steps: + - type: version-cmd + platforms: [linux, darwin] + weight: 1.0 + config: + command: "httpd -v" + version_regex: "Apache/(\\d+\\.\\d+\\.\\d+)" + vulnerable_versions: + - "< 2.4.52" + + - type: file-content + platforms: [linux, darwin] + weight: 0.8 + config: + path: "/etc/apache2/apache2.conf" + patterns: + - "ServerTokens.*Full" +``` + +#### Template Execution (`internal/template/executor/executor.go`) + +**Executor Flow**: + +```go +type Executor struct { + stepTimeout time.Duration +} + +// ExecuteTemplate runs all detection steps and evaluates logic +func (e *Executor) ExecuteTemplate(ctx context.Context, template *types.Template) (*types.Result, error) { + // 1. Filter steps by current platform + currentPlatform := types.Platform(runtime.GOOS) + applicableSteps := e.filterStepsByPlatform(template.Detection.Steps, currentPlatform) + + // 2. Execute steps sequentially + stepResults := make([]types.StepResult, 0, len(applicableSteps)) + for i, step := range applicableSteps { + stepResult := e.executeStep(ctx, step, i) + stepResults = append(stepResults, stepResult) + } + + // 3. Evaluate detection logic (all/any) + matched := e.evaluateLogic(template.Detection.Logic, stepResults) + + // 4. Calculate confidence based on weights + confidence := e.calculateConfidence(template.Detection.Logic, stepResults, applicableSteps) + + // 5. Build result + result := &types.Result{ + TemplateID: template.ID, + TemplateName: template.Info.Name, + Severity: template.Info.Severity, + Matched: matched, + Confidence: confidence, + Steps: stepResults, + Timestamp: time.Now(), + Host: hostname, + } + + return result, nil +} +``` + +**Step Execution**: + +```go +func (e *Executor) executeStep(ctx context.Context, step types.DetectionStep, index int) types.StepResult { + // Get module from registry + module := registry.Get(step.Type) + + // Create context with timeout + stepCtx, cancel := context.WithTimeout(ctx, e.stepTimeout) + defer cancel() + + // Execute module + moduleResult, err := module.Execute(stepCtx, step.Config) + + // Build step result + stepResult := types.StepResult{ + Step: index, + Type: step.Type, + Matched: moduleResult.Matched, + Evidence: moduleResult.Evidence, + Error: err.Error(), + Duration: time.Since(startTime), + } + + return stepResult +} +``` + +**Logic Evaluation**: + +```go +func (e *Executor) evaluateLogic(logic types.DetectionLogic, steps []types.StepResult) bool { + switch logic { + case types.LogicAll: // AND + // All steps must match + for _, step := range steps { + if step.Error == "" && !step.Matched { + return false + } + } + return true + + case types.LogicAny: // OR + // At least one step must match + for _, step := range steps { + if step.Error == "" && step.Matched { + return true + } + } + return false + } +} +``` + +#### Detection Modules + +Detection modules implement specific detection mechanisms. All modules implement the `Module` interface: + +```go +// internal/modules/registry/types.go +type Module interface { + Name() string + Execute(ctx context.Context, config map[string]interface{}) (*ModuleResult, error) +} + +type ModuleResult struct { + Matched bool + Evidence map[string]interface{} + Error string +} +``` + +**Available Module Types**: + +1. **version-cmd**: Execute command and parse version +2. **file-hash**: Check file SHA256 hash +3. **file-content**: Search file content for patterns +4. **registry-key**: Windows registry check (Windows only) +5. **service-check**: System service detection + +**Module Registration**: + +```go +// internal/modules/registry/registry.go +var ( + moduleMu sync.RWMutex + modules = make(map[string]Module) +) + +func Register(module Module) { + moduleMu.Lock() + defer moduleMu.Unlock() + modules[module.Name()] = module +} + +func Get(name string) Module { + moduleMu.RLock() + defer moduleMu.RUnlock() + return modules[name] +} +``` + +**Example Module - file-hash**: + +```go +// internal/detect/hash/calculator.go +type FileHashModule struct{} + +func (m *FileHashModule) Name() string { + return "file-hash" +} + +func (m *FileHashModule) Execute(ctx context.Context, config map[string]interface{}) (*ModuleResult, error) { + // Parse config + filePath, _ := config["path"].(string) + expectedHash, _ := config["hash"].(string) + + // Calculate SHA256 + file, err := os.Open(filePath) + if err != nil { + return &ModuleResult{Matched: false}, err + } + defer file.Close() + + hasher := sha256.New() + if _, err := io.Copy(hasher, file); err != nil { + return &ModuleResult{Matched: false}, err + } + + actualHash := hex.EncodeToString(hasher.Sum(nil)) + + // Compare hashes + matched := actualHash == expectedHash + + return &ModuleResult{ + Matched: matched, + Evidence: map[string]interface{}{ + "path": filePath, + "expected": expectedHash, + "actual": actualHash, + }, + }, nil +} +``` + +### 4. Template Synchronization System + +The template sync system coordinates template distribution from GitHub → Server → Agents. + +#### Server-Side Template Manager (`internal/server/template_manager.go`) + +```go +type ServerTemplateManager struct { + valkeyClient valkey.Client + storage *templatevalkey.ValKeyTemplateStorage + githubSync *templatevalkey.GitHubSyncManager + logger *zap.Logger + config *TemplateConfig + server *Server // Reference for agent communication +} +``` + +**Key Methods**: + +```go +// SyncFromGitHub pulls templates from sirius-agent-modules +func (tm *ServerTemplateManager) SyncFromGitHub(ctx context.Context) error { + return tm.githubSync.SyncFromGitHub(ctx) +} + +// GetTemplatesForSync retrieves manifest and templates for agent sync +func (tm *ServerTemplateManager) GetTemplatesForSync(ctx context.Context, lastSync int64) (*pb.TemplateManifest, []*pb.TemplateUpdate, error) { + // Get all template metadata from ValKey + metaKeys := valkeyClient.Keys("template:meta:*") + + // Build manifest + protoManifest := &pb.TemplateManifest{ + Version: "2.0.0", + Updated: time.Now().Unix(), + Templates: make(map[string]*pb.TemplateMetadata), + } + + // Fetch each template's content + var templates []*pb.TemplateUpdate + for _, metaKey := range metaKeys { + // Get metadata and content + // Calculate checksum + // Create TemplateUpdate message + templates = append(templates, templateUpdate) + } + + return protoManifest, templates, nil +} + +// StoreCustomTemplate stores user-uploaded templates +func (tm *ServerTemplateManager) StoreCustomTemplate(ctx context.Context, template *types.Template, content []byte) error { + // Validate template + if err := tm.storage.ValidateTemplate(template, content); err != nil { + return err + } + + // Store in ValKey + if err := tm.storage.StoreTemplate(ctx, template, content, true); err != nil { + return err + } + + // Push to online agents + if err := tm.pushToAgents(ctx, template, content); err != nil { + tm.logger.Warn("Failed to push template to agents", zap.Error(err)) + } + + return nil +} +``` + +**Template Storage in ValKey**: + +``` +Keys Pattern: + template:manifest → Global manifest JSON + template:meta: → Template metadata JSON + template:standard: → Standard template YAML content + template:custom: → Custom template YAML content +``` + +#### Agent-Side Sync Manager (`internal/template/agent/sync_manager.go`) + +```go +type AgentSyncManager struct { + cacheDir string + logger *zap.Logger + serverURL string + agentID string + grpcStream pb.HelloService_ConnectStreamClient +} +``` + +**Sync Flow**: + +```go +// 1. Agent sends sync request via gRPC stream +func (asm *AgentSyncManager) SyncFromServer(ctx context.Context) error { + // Load local manifest for last sync time + localManifest, _ := asm.loadCacheManifest() + + // Create sync request + syncRequest := &pb.TemplateSyncRequest{ + AgentId: asm.agentID, + LastSync: localManifest.LastSync.Unix(), + } + + // Send via stream + msg := &pb.AgentMessage{ + AgentId: asm.agentID, + Type: pb.MessageType_TEMPLATE_SYNC_REQUEST, + Payload: &pb.AgentMessage_SyncRequest{ + SyncRequest: syncRequest, + }, + } + + return asm.grpcStream.Send(msg) +} + +// 2. Server sends manifest first, then templates +// Handled in agent.handleTemplateUpdate() + +// 3. Process template update +func (asm *AgentSyncManager) HandleTemplateUpdate(ctx context.Context, update *pb.TemplateUpdate) error { + // Determine cache path + var cachePath string + if update.IsCustom { + cachePath = filepath.Join(GetCustomTemplatesPath(), update.TemplateId+".yaml") + } else { + cachePath = filepath.Join(GetStandardTemplatesPath(), update.TemplateId+".yaml") + } + + // Write template atomically + tempPath := cachePath + ".tmp" + os.WriteFile(tempPath, []byte(update.Content), 0644) + os.Rename(tempPath, cachePath) + + // Verify checksum + hash := sha256.Sum256([]byte(update.Content)) + actualChecksum := "sha256:" + hex.EncodeToString(hash[:]) + + // Update local manifest + localManifest, _ := asm.loadCacheManifest() + localManifest.Templates[update.TemplateId] = &CacheTemplateInfo{ + ID: update.TemplateId, + Version: update.Version, + Checksum: update.Checksum, + FilePath: cachePath, + IsCustom: update.IsCustom, + } + + asm.saveCacheManifest(localManifest) + + return nil +} +``` + +**Cache Directory Structure**: + +``` +Windows: C:\ProgramData\Sirius\templates\ +Linux: /var/lib/sirius/templates/ +macOS: /Library/Application Support/Sirius/templates/ + +Structure: + ├── cache-manifest.json # Local cache metadata + ├── standard/ # Standard templates from GitHub + │ ├── apache-outdated.yaml + │ └── nginx-vuln.yaml + └── custom/ # User-uploaded custom templates + └── org-custom-check.yaml +``` + +### 5. Command System + +Agents support both internal commands and shell execution via a command registry. + +#### Command Registration (`internal/commands/registry.go`) + +```go +var ( + commandsMutex sync.RWMutex + commands = make(map[string]CommandHandler) + aliases = make(map[string]string) +) + +type CommandHandler func(ctx context.Context, info AgentInfo, args []string) (string, error) + +func Register(name string, handler CommandHandler) { + commandsMutex.Lock() + defer commandsMutex.Unlock() + commands[name] = handler +} + +func Dispatch(ctx context.Context, info AgentInfo, commandString string) (string, error) { + // Parse command line + cmdName, args := parseCommandLine(commandString) + + // Check for alias + if alias, ok := aliases[cmdName]; ok { + cmdName = alias + } + + // Get handler + handler, exists := commands[cmdName] + if !exists { + return "", ErrUnknownCommand + } + + // Execute + return handler(ctx, info, args) +} +``` + +**Built-in Commands**: + +1. **help**: Show available commands +2. **status**: Agent status and capabilities +3. **scan**: Execute vulnerability scan +4. **template list**: List cached templates +5. **template sync**: Trigger template sync +6. **templatescan**: Run scan using specific template + +**Example Command - status**: + +```go +// internal/commands/status/status.go +func init() { + commands.Register("status", statusHandler) +} + +func statusHandler(ctx context.Context, info commands.AgentInfo, args []string) (string, error) { + hostname, _ := os.Hostname() + uptime := time.Since(info.StartTime).Round(time.Second) + + var memStats runtime.MemStats + runtime.ReadMemStats(&memStats) + + output := fmt.Sprintf(`Agent Status: + Hostname: %s + Agent ID: %s + Platform: %s + Uptime: %s + Memory: %.2f MB + Scripting: %v +`, hostname, info.Config.AgentID, runtime.GOOS, uptime, + float64(memStats.Alloc)/1024/1024, info.ScriptingEnabled) + + return output, nil +} +``` + +### 6. Protocol Buffers (`proto/hello/hello.proto`) + +**Service Definition**: + +```protobuf +service HelloService { + rpc Ping(PingRequest) returns (PingResponse) {} + rpc ConnectStream(stream AgentMessage) returns (stream ServerMessage) {} +} + +enum MessageType { + UNKNOWN = 0; + HEARTBEAT = 1; + COMMAND = 2; + RESULT = 3; + ACKNOWLEDGMENT = 4; + TEMPLATE_UPDATE = 5; + TEMPLATE_SYNC_REQUEST = 6; +} + +message ServerMessage { + string id = 1; + MessageType type = 2; + oneof payload { + CommandRequest command = 3; + Acknowledgment acknowledgment = 4; + TemplateUpdate template_update = 5; + } +} + +message AgentMessage { + string agent_id = 1; + MessageType type = 2; + oneof payload { + HeartbeatMessage heartbeat = 3; + CommandResult result = 4; + TemplateSyncRequest sync_request = 5; + } +} + +message TemplateUpdate { + string template_id = 1; + string version = 2; + string checksum = 3; + string content = 4; + bool is_custom = 5; + int64 timestamp = 6; + TemplateManifest manifest = 7; +} +``` + +## Programming Paradigms & Best Practices + +### Go Code Organization + +#### 1. Package Structure + +```go +// ✅ GOOD: Clear, focused packages +internal/ + ├── agent/ # Agent client logic + ├── server/ # Server logic + ├── template/ # Template system + │ ├── types/ # Type definitions + │ ├── parser/ # Template parsing + │ ├── executor/ # Template execution + │ └── agent/ # Agent-side sync + ├── commands/ # Command handlers + └── modules/ # Detection modules + +// ❌ BAD: Monolithic packages +internal/ + └── everything/ # All code in one package +``` + +#### 2. Dependency Injection + +```go +// ✅ GOOD: Constructor with dependencies +func NewServer(cfg *config.ServerConfig, logger *zap.Logger) (*Server, error) { + valkeyClient, err := NewValkeyClient(logger) + responseStore, err := store.NewResponseStore() + + server := &Server{ + logger: logger, + config: cfg, + valkeyClient: valkeyClient, + responseStore: responseStore, + } + + return server, nil +} + +// ❌ BAD: Global state +var globalLogger *zap.Logger +var globalDB *sql.DB +``` + +#### 3. Error Handling + +```go +// ✅ GOOD: Wrap errors with context +func (s *Server) SendCommandToAgent(agentID, command string) error { + stream, ok := s.agents[agentID] + if !ok { + return fmt.Errorf("agent %s not connected", agentID) + } + + if err := stream.Send(cmdMsg); err != nil { + return fmt.Errorf("failed to send command to agent %s: %w", agentID, err) + } + + return nil +} + +// ❌ BAD: Swallow errors or use panic +func (s *Server) SendCommandToAgent(agentID, command string) error { + stream, ok := s.agents[agentID] + if !ok { + panic("agent not found") // Don't panic! + } + + stream.Send(cmdMsg) // Ignoring error! + return nil +} +``` + +#### 4. Concurrent Access + +```go +// ✅ GOOD: Use mutexes for shared state +type Server struct { + agentsMutex sync.RWMutex + agents map[string]pb.HelloService_ConnectStreamServer +} + +func (s *Server) GetAgent(agentID string) (pb.HelloService_ConnectStreamServer, bool) { + s.agentsMutex.RLock() + defer s.agentsMutex.RUnlock() + stream, ok := s.agents[agentID] + return stream, ok +} + +// ❌ BAD: Unsafe concurrent access +type Server struct { + agents map[string]pb.HelloService_ConnectStreamServer +} + +func (s *Server) GetAgent(agentID string) (pb.HelloService_ConnectStreamServer, bool) { + return s.agents[agentID], true // Race condition! +} +``` + +#### 5. Context Usage + +```go +// ✅ GOOD: Pass context, respect cancellation +func (e *Executor) executeStep(ctx context.Context, step types.DetectionStep, index int) types.StepResult { + stepCtx, cancel := context.WithTimeout(ctx, e.stepTimeout) + defer cancel() + + moduleResult, err := module.Execute(stepCtx, step.Config) + + return stepResult +} + +// ❌ BAD: Ignore context +func (e *Executor) executeStep(ctx context.Context, step types.DetectionStep, index int) types.StepResult { + // Not using context at all! + moduleResult, err := module.Execute(nil, step.Config) + + return stepResult +} +``` + +### Template System Best Practices + +#### 1. Module Development + +```go +// ✅ GOOD: Implement Module interface +type MyDetectionModule struct { + logger *zap.Logger +} + +func (m *MyDetectionModule) Name() string { + return "my-detection" +} + +func (m *MyDetectionModule) Execute(ctx context.Context, config map[string]interface{}) (*ModuleResult, error) { + // Validate config + requiredField, ok := config["required"].(string) + if !ok { + return nil, fmt.Errorf("required config field 'required' missing or invalid") + } + + // Check context cancellation + select { + case <-ctx.Done(): + return nil, ctx.Err() + default: + } + + // Perform detection + matched := false + evidence := make(map[string]interface{}) + + // ... detection logic ... + + return &ModuleResult{ + Matched: matched, + Evidence: evidence, + }, nil +} + +// Register in init() +func init() { + registry.Register(&MyDetectionModule{}) +} +``` + +#### 2. Template Design + +```yaml +# ✅ GOOD: Well-structured template +id: descriptive-id-with-vendor-product +info: + name: Clear, Descriptive Name + author: team-or-person + severity: high # critical, high, medium, low, info + description: > + Detailed description of what this template detects, + why it's important, and what the vulnerability means. + references: + - https://nvd.nist.gov/vuln/detail/CVE-2021-12345 + cve: + - CVE-2021-12345 + tags: + - product-name + - vulnerability-type + version: "1.0" + +detection: + logic: all # Explicit logic + steps: + - type: version-cmd + platforms: [linux, darwin, windows] + weight: 1.0 + config: + command: "product --version" + version_regex: "Product/(\\d+\\.\\d+\\.\\d+)" + vulnerable_versions: + - "< 2.0.0" + +# ❌ BAD: Vague or incomplete +id: template1 +info: + name: Check thing + severity: medium + description: Checks for bad thing +detection: + steps: + - type: file-content + config: + path: "/some/file" +``` + +### gRPC Streaming Best Practices + +#### 1. Stream Lifecycle Management + +```go +// ✅ GOOD: Proper stream setup and cleanup +func (s *Server) ConnectStream(stream pb.HelloService_ConnectStreamServer) error { + // Wait for initial message with agent ID + msg, err := stream.Recv() + if err != nil { + return fmt.Errorf("failed to receive initial message: %w", err) + } + + agentID := msg.AgentId + + // Register agent + s.agentsMutex.Lock() + s.agents[agentID] = stream + s.agentsMutex.Unlock() + + // Cleanup when stream closes + defer func() { + s.agentsMutex.Lock() + delete(s.agents, agentID) + s.agentsMutex.Unlock() + s.logger.Info("Agent disconnected", zap.String("agent_id", agentID)) + }() + + // Process messages + for { + msg, err := stream.Recv() + if err != nil { + return fmt.Errorf("error receiving message: %w", err) + } + + // Handle message... + } +} + +// ❌ BAD: No cleanup, no error handling +func (s *Server) ConnectStream(stream pb.HelloService_ConnectStreamServer) error { + msg, _ := stream.Recv() + agentID := msg.AgentId + s.agents[agentID] = stream // No mutex! + + for { + msg, _ := stream.Recv() // Ignoring errors! + // ... + } +} +``` + +#### 2. Message Type Handling + +```go +// ✅ GOOD: Use type switch with oneof payloads +func (a *Agent) WaitForCommands(ctx context.Context) error { + for { + msg, err := a.stream.Recv() + if err != nil { + return fmt.Errorf("error receiving message: %w", err) + } + + switch msg.Type { + case pb.MessageType_COMMAND: + if cmd := msg.GetCommand(); cmd != nil { + a.handleCommand(ctx, cmd) + } + case pb.MessageType_ACKNOWLEDGMENT: + if ack := msg.GetAcknowledgment(); ack != nil { + a.handleAcknowledgment(ack) + } + case pb.MessageType_TEMPLATE_UPDATE: + if update := msg.GetTemplateUpdate(); update != nil { + a.handleTemplateUpdate(ctx, update) + } + default: + a.logger.Warn("Unknown message type", zap.Int32("type", int32(msg.Type))) + } + } +} +``` + +## Development Workflow + +### Building the Project + +```bash +# Navigate to app-agent directory +cd /path/to/app-agent + +# Generate protobuf code +./scripts/generate_proto.sh + +# Build server +go build -o bin/server ./cmd/server + +# Build agent +go build -o bin/agent ./cmd/agent + +# Build sirius-integrated agent +go build -o bin/sirius-agent ./cmd/sirius-agent +``` + +### Running Tests + +```bash +# Run all tests +go test ./... + +# Run specific package tests +go test ./internal/template/executor/... + +# Run with coverage +go test -cover ./... + +# Run integration tests +go test -tags=integration ./... +``` + +### Docker Development + +```bash +# Build Docker image +docker build -t sirius-agent -f Dockerfile . + +# Run server in container +docker run -p 50051:50051 sirius-agent server + +# Run agent in container +docker run sirius-agent agent --server-address=server:50051 +``` + +### Testing Template System + +```bash +# Create test template +cat > test-template.yaml < KEYS template:* +> GET template:manifest + +// Check agent cache +ls -la /var/lib/sirius/templates/ +cat /var/lib/sirius/templates/cache-manifest.json +``` + +#### 3. Module Not Found + +```go +// Verify module registration +// Add logging to module init() +func init() { + log.Printf("Registering module: my-module") + registry.Register(&MyModule{}) +} + +// Check registry +// In agent code +modules := registry.List() +for _, name := range modules { + log.Printf("Registered module: %s", name) +} +``` + +## Configuration + +### Server Configuration (`config/server.yaml`) + +```yaml +server: + address: "0.0.0.0:50051" + +valkey: + address: "valkey:6379" + password: "" + db: 0 + +rabbitmq: + url: "amqp://guest:guest@rabbitmq:5672/" + command_queue: "agent_commands" + response_queue: "agent_response" + +templates: + repo_url: "https://github.com/SiriusScan/sirius-agent-modules" + repo_path: "/var/sirius/template-repos/sirius-agent-modules" + sync_interval: "24h" + max_template_size: 1048576 +``` + +### Agent Configuration (Environment Variables) + +```bash +# Required +AGENT_ID="agent-001" +SERVER_ADDRESS="server:50051" + +# Optional +ENABLE_SCRIPTING="true" +POWERSHELL_PATH="/usr/bin/pwsh" +LOG_LEVEL="info" +``` + +## Responsibilities Summary + +As the Remote Agent Engineer, you are responsible for: + +### Primary + +1. **Agent-Server Communication**: Maintain gRPC bidirectional streaming +2. **Template System**: Develop, execute, and synchronize vulnerability templates +3. **Detection Modules**: Implement platform-specific detection mechanisms +4. **Command System**: Build internal agent commands and shell integration + +### Secondary + +1. **Performance Optimization**: Efficient template execution and module caching +2. **Error Handling**: Robust error recovery in distributed system +3. **Testing**: Unit, integration, and end-to-end testing +4. **Documentation**: Update templates, modules, and API docs + +### Collaboration + +1. **Backend API Engineer**: Coordinate on RabbitMQ message formats and Valkey storage +2. **Scanner UI Engineer**: Align on template metadata and scan result formats +3. **DevOps**: Ensure containerized deployment and agent distribution + +## Additional Resources + +### Go Resources + +- Go Documentation: https://golang.org/doc/ +- gRPC Go: https://grpc.io/docs/languages/go/ +- Protocol Buffers Go: https://developers.google.com/protocol-buffers/docs/gotutorial + +### Project-Specific + +- sirius-agent-modules repository: https://github.com/SiriusScan/sirius-agent-modules +- go-api library: Used for RabbitMQ and Valkey integration + +--- + +**Last Updated**: October 25, 2025 +**Version**: 2.0.0 +**Maintainer**: Remote Agent Team diff --git a/.cursor/mcp.json b/.cursor/mcp.json new file mode 100644 index 0000000..e69de29 diff --git a/.cursor/old/docker-development.mdc b/.cursor/old/docker-development.mdc new file mode 100644 index 0000000..06ecd9b --- /dev/null +++ b/.cursor/old/docker-development.mdc @@ -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 bash -c ""` + - 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] \ No newline at end of file diff --git a/.cursor/old/docker-tests.mdc b/.cursor/old/docker-tests.mdc new file mode 100644 index 0000000..00285d1 --- /dev/null +++ b/.cursor/old/docker-tests.mdc @@ -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//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 \ No newline at end of file diff --git a/.cursor/old/general.mdc b/.cursor/old/general.mdc new file mode 100644 index 0000000..9915da4 --- /dev/null +++ b/.cursor/old/general.mdc @@ -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. + + +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).*?" + # 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 + \ No newline at end of file diff --git a/.cursor/old/github-mcp.md b/.cursor/old/github-mcp.md new file mode 100644 index 0000000..3b6690e --- /dev/null +++ b/.cursor/old/github-mcp.md @@ -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 diff --git a/.cursor/old/github-mcp.mdc b/.cursor/old/github-mcp.mdc new file mode 100644 index 0000000..e739485 --- /dev/null +++ b/.cursor/old/github-mcp.mdc @@ -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 diff --git a/.cursor/old/golang.mdc b/.cursor/old/golang.mdc new file mode 100644 index 0000000..82e6e96 --- /dev/null +++ b/.cursor/old/golang.mdc @@ -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. \ No newline at end of file diff --git a/.cursor/old/mcp.md b/.cursor/old/mcp.md new file mode 100644 index 0000000..bd511bc --- /dev/null +++ b/.cursor/old/mcp.md @@ -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 diff --git a/.cursor/old/nextjs.mdc b/.cursor/old/nextjs.mdc new file mode 100644 index 0000000..cbcf41a --- /dev/null +++ b/.cursor/old/nextjs.mdc @@ -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 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. \ No newline at end of file diff --git a/.cursor/old/project-details.mdc b/.cursor/old/project-details.mdc new file mode 100644 index 0000000..95059e9 --- /dev/null +++ b/.cursor/old/project-details.mdc @@ -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. \ No newline at end of file diff --git a/.cursor/old/self_improve.mdc b/.cursor/old/self_improve.mdc new file mode 100644 index 0000000..a7ea8f2 --- /dev/null +++ b/.cursor/old/self_improve.mdc @@ -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. \ No newline at end of file diff --git a/.cursor/old/typescript-react.mdc b/.cursor/old/typescript-react.mdc new file mode 100644 index 0000000..b8b7efe --- /dev/null +++ b/.cursor/old/typescript-react.mdc @@ -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. + + +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 = ({ + // 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 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
{props.children}
; + }; + 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 = ({ + onClick, + children, + variant = 'primary', + }) => { + const handleClick = () => { + onClick(); + }; + + return ( + + ); + }; + ``` + output: "Properly structured TypeScript React component" + +metadata: + priority: high + version: 1.0 + \ No newline at end of file diff --git a/.cursor/old/web-development-debugging.mdc b/.cursor/old/web-development-debugging.mdc new file mode 100644 index 0000000..ca9ce15 --- /dev/null +++ b/.cursor/old/web-development-debugging.mdc @@ -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** diff --git a/.cursor/plans/sirius_v1_release_readiness_5ce2fe4d.plan.md b/.cursor/plans/sirius_v1_release_readiness_5ce2fe4d.plan.md new file mode 100644 index 0000000..45eb93c --- /dev/null +++ b/.cursor/plans/sirius_v1_release_readiness_5ce2fe4d.plan.md @@ -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 diff --git a/.cursor/rules/cursor_rules.mdc b/.cursor/rules/cursor_rules.mdc new file mode 100644 index 0000000..789e2c1 --- /dev/null +++ b/.cursor/rules/cursor_rules.mdc @@ -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 + +# Example: Check logs +docker exec sirius-engine cat /var/logs + +# Example: Restart services +docker exec sirius-engine systemctl restart +``` + +### 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)._ diff --git a/.cursor/rules/documentation-work.mdc b/.cursor/rules/documentation-work.mdc new file mode 100644 index 0000000..87d95fc --- /dev/null +++ b/.cursor/rules/documentation-work.mdc @@ -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)._ diff --git a/.cursor/rules/git-operations.mdc b/.cursor/rules/git-operations.mdc new file mode 100644 index 0000000..10c9b3f --- /dev/null +++ b/.cursor/rules/git-operations.mdc @@ -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 + +``` +(): + +[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 + +``` +/ +``` + +### 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)._ diff --git a/.cursor/rules/playwright-testing.mdc b/.cursor/rules/playwright-testing.mdc new file mode 100644 index 0000000..ea6d454 --- /dev/null +++ b/.cursor/rules/playwright-testing.mdc @@ -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)._ diff --git a/.cursor/rules/task-management.mdc b/.cursor/rules/task-management.mdc new file mode 100644 index 0000000..0e8b84d --- /dev/null +++ b/.cursor/rules/task-management.mdc @@ -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._ diff --git a/.cursor/rules/testing-workflow.mdc b/.cursor/rules/testing-workflow.mdc new file mode 100644 index 0000000..26b9f20 --- /dev/null +++ b/.cursor/rules/testing-workflow.mdc @@ -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)._ diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..2a8a42a --- /dev/null +++ b/.editorconfig @@ -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 diff --git a/.env.production.example b/.env.production.example new file mode 100644 index 0000000..f3adfaf --- /dev/null +++ b/.env.production.example @@ -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 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..eb1e209 --- /dev/null +++ b/.gitattributes @@ -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 diff --git a/.github/ISSUE_TEMPLATE/auth-401.yml b/.github/ISSUE_TEMPLATE/auth-401.yml new file mode 100644 index 0000000..66c2b7c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/auth-401.yml @@ -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 diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 0000000..30e7632 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -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 diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..2c88286 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -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. diff --git a/.github/ISSUE_TEMPLATE/dev-overlay.yml b/.github/ISSUE_TEMPLATE/dev-overlay.yml new file mode 100644 index 0000000..629b028 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/dev-overlay.yml @@ -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 diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml new file mode 100644 index 0000000..4567242 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -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 diff --git a/.github/ISSUE_TEMPLATE/install-startup.yml b/.github/ISSUE_TEMPLATE/install-startup.yml new file mode 100644 index 0000000..c5ce5d9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/install-startup.yml @@ -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 diff --git a/.github/ISSUE_TEMPLATE/security-report.yml b/.github/ISSUE_TEMPLATE/security-report.yml new file mode 100644 index 0000000..6903ecf --- /dev/null +++ b/.github/ISSUE_TEMPLATE/security-report.yml @@ -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 diff --git a/.github/ISSUE_TEMPLATE/windows-wsl.yml b/.github/ISSUE_TEMPLATE/windows-wsl.yml new file mode 100644 index 0000000..fabc370 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/windows-wsl.yml @@ -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 diff --git a/.github/ORGANIZATION_PROFILE_SETUP.md b/.github/ORGANIZATION_PROFILE_SETUP.md new file mode 100644 index 0000000..aa37c08 --- /dev/null +++ b/.github/ORGANIZATION_PROFILE_SETUP.md @@ -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. diff --git a/.github/ORG_SETUP_STATUS.md b/.github/ORG_SETUP_STATUS.md new file mode 100644 index 0000000..46edf25 --- /dev/null +++ b/.github/ORG_SETUP_STATUS.md @@ -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` diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..02ebc08 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -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). diff --git a/.github/REPOSITORY_STANDARDS_ADVISORY.md b/.github/REPOSITORY_STANDARDS_ADVISORY.md new file mode 100644 index 0000000..e8d2b35 --- /dev/null +++ b/.github/REPOSITORY_STANDARDS_ADVISORY.md @@ -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. diff --git a/.github/REPO_ROLLOUT_CHECKLIST.md b/.github/REPO_ROLLOUT_CHECKLIST.md new file mode 100644 index 0000000..d4d87c0 --- /dev/null +++ b/.github/REPO_ROLLOUT_CHECKLIST.md @@ -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 diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..b2b0b93 --- /dev/null +++ b/.github/dependabot.yml @@ -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" diff --git a/.github/labeler.yml b/.github/labeler.yml new file mode 100644 index 0000000..9c2fba8 --- /dev/null +++ b/.github/labeler.yml @@ -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" diff --git a/.github/labels.yml b/.github/labels.yml new file mode 100644 index 0000000..f571508 --- /dev/null +++ b/.github/labels.yml @@ -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." diff --git a/.github/profile/README.md b/.github/profile/README.md new file mode 100644 index 0000000..20bf4f5 --- /dev/null +++ b/.github/profile/README.md @@ -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: +- Installation: +- API docs: +- Security policy: +- Project 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: +- Code of conduct: +- Support channels: diff --git a/.github/workflows/chatops-runner.yml b/.github/workflows/chatops-runner.yml new file mode 100644 index 0000000..5665b1c --- /dev/null +++ b/.github/workflows/chatops-runner.yml @@ -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 " > "$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 = `\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, + }); diff --git a/.github/workflows/check-pin-consistency.yml b/.github/workflows/check-pin-consistency.yml new file mode 100644 index 0000000..7f44395 --- /dev/null +++ b/.github/workflows/check-pin-consistency.yml @@ -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." diff --git a/.github/workflows/ci-modernized.yml b/.github/workflows/ci-modernized.yml new file mode 100644 index 0000000..ea97f37 --- /dev/null +++ b/.github/workflows/ci-modernized.yml @@ -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)" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..e1c034f --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,1066 @@ +name: Sirius CI/CD Pipeline + +# Canonical CI pipeline. Handles all builds, tests, and canary dispatch. +# deploy.yml is now deployment-only (workflow_dispatch) and does not build images. +# +# Multi-arch strategy: each container is built per-platform (amd64 native, +# arm64 via QEMU) on GitHub-hosted runners. After both arch builds succeed, +# arch-specific tags are merged into a single multi-arch manifest. + +on: + push: + branches: [main, sirius-demo] + pull_request: + branches: [main] + repository_dispatch: + types: [submodule-update] + +env: + REGISTRY: ghcr.io + IMAGE_NAMESPACE: siriusscan + +jobs: + # ───────────────────────────────────────────────────────────────────────────── + # Detect which services actually changed so we only build what's needed + # ───────────────────────────────────────────────────────────────────────────── + 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 }} + sirius_infra_changes: ${{ steps.changes.outputs.sirius_infra_changes }} + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Determine Changed Files + id: changes + run: | + if [ "${{ github.event_name }}" == "repository_dispatch" ]; then + SUBMODULE="${{ github.event.client_payload.submodule }}" + echo "submodule_changes=true" >> $GITHUB_OUTPUT + echo "Submodule update detected: $SUBMODULE" + + REPO_NAME=$(echo $SUBMODULE | awk -F'/' '{print $NF}') + + case $REPO_NAME in + "go-api") + echo "Affects both sirius-api and sirius-engine" + echo "sirius_api_changes=true" >> $GITHUB_OUTPUT + echo "sirius_engine_changes=true" >> $GITHUB_OUTPUT + ;; + "app-scanner"|"app-terminal"|"sirius-nse"|"app-agent") + echo "Affects sirius-engine" + echo "sirius_engine_changes=true" >> $GITHUB_OUTPUT + ;; + *) + echo "Unknown submodule, rebuilding everything" + echo "sirius_ui_changes=true" >> $GITHUB_OUTPUT + echo "sirius_api_changes=true" >> $GITHUB_OUTPUT + echo "sirius_engine_changes=true" >> $GITHUB_OUTPUT + echo "sirius_infra_changes=true" >> $GITHUB_OUTPUT + ;; + esac + else + if [ "${{ github.event_name }}" == "pull_request" ]; then + BASE_SHA=${{ github.event.pull_request.base.sha }} + HEAD_SHA=${{ github.event.pull_request.head.sha }} + else + BASE_SHA=${{ github.event.before }} + HEAD_SHA=${{ github.event.after }} + fi + + git diff --name-only $BASE_SHA $HEAD_SHA > changed_files.txt + + 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 || grep -q "rabbitmq/" changed_files.txt; then + echo "Engine or RabbitMQ changes detected" + echo "sirius_engine_changes=true" >> $GITHUB_OUTPUT + fi + + if grep -q -E "^(sirius-postgres/|sirius-rabbitmq/|sirius-valkey/|rabbitmq/)" changed_files.txt; then + echo "Infrastructure changes detected" + echo "sirius_infra_changes=true" >> $GITHUB_OUTPUT + fi + + # Dockerfile or CI changes trigger a full rebuild + if grep -q -E "(Dockerfile|\.github/|docker-compose)" changed_files.txt; then + echo "Docker or CI 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 + echo "sirius_infra_changes=true" >> $GITHUB_OUTPUT + fi + + # No specific changes but something did change: full rebuild + 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 + echo "sirius_infra_changes=true" >> $GITHUB_OUTPUT + fi + fi + + # ───────────────────────────────────────────────────────────────────────────── + # Guard against accidental image namespace typos in CI/build paths. + # ───────────────────────────────────────────────────────────────────────────── + guard-registry-namespace: + name: "Guard Registry Namespace" + needs: detect-changes + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Fail on typoed GHCR namespace + run: | + set -e + TARGETS=".github/workflows docker-compose.yaml docker-stack.swarm.yaml scripts sirius-api sirius-engine sirius-postgres sirius-rabbitmq sirius-ui sirius-valkey" + BAD_NAMESPACE="${{ env.REGISTRY }}/sirius""cam/" + if grep -R --line-number "$BAD_NAMESPACE" $TARGETS; then + echo "::error::Found typoed GHCR namespace '${BAD_NAMESPACE}'. Use '${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/'." + exit 1 + fi + echo "Registry namespace guard passed." + + # ───────────────────────────────────────────────────────────────────────────── + # Build sirius-ui + # PRs build amd64 only; main/dispatch builds both arches (arm64 via QEMU). + # ───────────────────────────────────────────────────────────────────────────── + build-ui: + name: "Build UI (${{ matrix.platform }})" + needs: [detect-changes, guard-registry-namespace] + if: needs.detect-changes.outputs.sirius_ui_changes == 'true' + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + platform: ${{ github.event_name == 'pull_request' && fromJSON('["amd64"]') || fromJSON('["amd64","arm64"]') }} + + steps: + - name: Checkout Sirius repository + uses: actions/checkout@v4 + + - name: Generate image tag + id: meta + run: | + 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 + elif [ "${{ github.event_name }}" == "repository_dispatch" ]; then + TAG="latest" + echo "also_tag_beta=true" >> $GITHUB_OUTPUT + else + TAG="dev" + fi + echo "image_tag=$TAG" >> $GITHUB_OUTPUT + + - name: Install UI dependencies + run: npm ci + working-directory: sirius-ui + + - name: Lint UI code + continue-on-error: true + run: npm run lint + working-directory: sirius-ui + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + + - 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: Build and push sirius-ui (${{ matrix.platform }}) + uses: docker/build-push-action@v6 + with: + context: ./sirius-ui + platforms: linux/${{ matrix.platform }} + push: true + tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-ui:${{ steps.meta.outputs.image_tag }}-${{ matrix.platform }} + + # Merge arch-specific UI images into a single multi-arch manifest + merge-ui: + name: "Merge UI Manifest" + needs: build-ui + if: needs.detect-changes.outputs.sirius_ui_changes == 'true' && github.event_name != 'pull_request' + runs-on: ubuntu-latest + outputs: + image_tag: ${{ steps.meta.outputs.image_tag }} + steps: + - name: Generate image tag + id: meta + run: | + if [ "${{ github.event_name }}" == "push" ] && [ "${{ github.ref }}" == "refs/heads/main" ]; then + echo "image_tag=latest" >> $GITHUB_OUTPUT + echo "also_tag_beta=true" >> $GITHUB_OUTPUT + elif [ "${{ github.event_name }}" == "repository_dispatch" ]; then + echo "image_tag=latest" >> $GITHUB_OUTPUT + echo "also_tag_beta=true" >> $GITHUB_OUTPUT + else + echo "image_tag=dev" >> $GITHUB_OUTPUT + fi + + - 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 and push multi-arch manifest for sirius-ui + run: | + TAG="${{ steps.meta.outputs.image_tag }}" + BASE="${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-ui" + + docker buildx imagetools create -t ${BASE}:${TAG} \ + ${BASE}:${TAG}-amd64 \ + ${BASE}:${TAG}-arm64 + + if [ "${{ steps.meta.outputs.also_tag_beta }}" == "true" ]; then + docker buildx imagetools create -t ${BASE}:beta \ + ${BASE}:${TAG}-amd64 \ + ${BASE}:${TAG}-arm64 + fi + + echo "Published ${BASE}:${TAG} (amd64 + arm64)" + + # ───────────────────────────────────────────────────────────────────────────── + # Build sirius-api + # ───────────────────────────────────────────────────────────────────────────── + build-api: + name: "Build API (${{ matrix.platform }})" + needs: [detect-changes, guard-registry-namespace] + if: needs.detect-changes.outputs.sirius_api_changes == 'true' + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + platform: ${{ github.event_name == 'pull_request' && fromJSON('["amd64"]') || fromJSON('["amd64","arm64"]') }} + + steps: + - name: Checkout Sirius repository + uses: actions/checkout@v4 + + - name: Generate image tag + id: meta + run: | + if [ "${{ github.event_name }}" == "repository_dispatch" ]; then + SUBMODULE="${{ github.event.client_payload.submodule }}" + REPO_NAME=$(echo $SUBMODULE | awk -F'/' '{print $NF}') + COMMIT_SHA="${{ github.event.client_payload.commit_sha }}" + if [ "$REPO_NAME" == "go-api" ]; then + echo "GO_API_COMMIT_SHA=$COMMIT_SHA" >> $GITHUB_ENV + fi + fi + + 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 + elif [ "${{ github.event_name }}" == "repository_dispatch" ]; then + TAG="latest" + echo "also_tag_beta=true" >> $GITHUB_OUTPUT + else + TAG="dev" + fi + echo "image_tag=$TAG" >> $GITHUB_OUTPUT + + - name: Set up Go + uses: actions/setup-go@v5 + with: + go-version: '1.24' + + - name: Compile-check API code + run: | + go mod download + go vet ./... + working-directory: sirius-api + + - name: Run API tests (non-blocking) + continue-on-error: true + run: go test ./... -short -count=1 + working-directory: sirius-api + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + + - 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: Build and push sirius-api (${{ matrix.platform }}) + uses: docker/build-push-action@v6 + with: + context: ./sirius-api + platforms: linux/${{ matrix.platform }} + push: true + # Fallback SHAs MUST match sirius-engine/Dockerfile ARG defaults. + # Enforced by .github/workflows/check-pin-consistency.yml. + build-args: | + GO_API_COMMIT_SHA=${{ env.GO_API_COMMIT_SHA || 'v0.0.18' }} + tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-api:${{ steps.meta.outputs.image_tag }}-${{ matrix.platform }} + + # Merge arch-specific API images into a single multi-arch manifest + merge-api: + name: "Merge API Manifest" + needs: build-api + if: needs.detect-changes.outputs.sirius_api_changes == 'true' && github.event_name != 'pull_request' + runs-on: ubuntu-latest + outputs: + image_tag: ${{ steps.meta.outputs.image_tag }} + steps: + - name: Generate image tag + id: meta + run: | + if [ "${{ github.event_name }}" == "push" ] && [ "${{ github.ref }}" == "refs/heads/main" ]; then + echo "image_tag=latest" >> $GITHUB_OUTPUT + echo "also_tag_beta=true" >> $GITHUB_OUTPUT + elif [ "${{ github.event_name }}" == "repository_dispatch" ]; then + echo "image_tag=latest" >> $GITHUB_OUTPUT + echo "also_tag_beta=true" >> $GITHUB_OUTPUT + else + echo "image_tag=dev" >> $GITHUB_OUTPUT + fi + + - 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 and push multi-arch manifest for sirius-api + run: | + TAG="${{ steps.meta.outputs.image_tag }}" + BASE="${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-api" + + docker buildx imagetools create -t ${BASE}:${TAG} \ + ${BASE}:${TAG}-amd64 \ + ${BASE}:${TAG}-arm64 + + if [ "${{ steps.meta.outputs.also_tag_beta }}" == "true" ]; then + docker buildx imagetools create -t ${BASE}:beta \ + ${BASE}:${TAG}-amd64 \ + ${BASE}:${TAG}-arm64 + fi + + echo "Published ${BASE}:${TAG} (amd64 + arm64)" + + # ───────────────────────────────────────────────────────────────────────────── + # Build sirius-engine + # ───────────────────────────────────────────────────────────────────────────── + build-engine: + name: "Build Engine (${{ matrix.platform }})" + needs: [detect-changes, guard-registry-namespace] + if: needs.detect-changes.outputs.sirius_engine_changes == 'true' + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + platform: ${{ github.event_name == 'pull_request' && fromJSON('["amd64"]') || fromJSON('["amd64","arm64"]') }} + + steps: + - name: Checkout Sirius repository + uses: actions/checkout@v4 + + - name: Generate image tag and submodule SHAs + id: meta + run: | + if [ "${{ github.event_name }}" == "repository_dispatch" ]; then + SUBMODULE="${{ github.event.client_payload.submodule }}" + REPO_NAME=$(echo $SUBMODULE | awk -F'/' '{print $NF}') + COMMIT_SHA="${{ github.event.client_payload.commit_sha }}" + REPO_NAME_UPPER=$(echo $REPO_NAME | tr '-' '_' | tr 'a-z' 'A-Z') + echo "${REPO_NAME_UPPER}_COMMIT_SHA=$COMMIT_SHA" >> $GITHUB_ENV + fi + + 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 + elif [ "${{ github.event_name }}" == "repository_dispatch" ]; then + TAG="latest" + echo "also_tag_beta=true" >> $GITHUB_OUTPUT + else + TAG="dev" + fi + echo "image_tag=$TAG" >> $GITHUB_OUTPUT + + - name: Set up Go + uses: actions/setup-go@v5 + with: + go-version: '1.24' + + - name: Compile-check Engine code + run: | + go mod download + go vet ./... + working-directory: sirius-engine + + - name: Run Engine tests (non-blocking) + continue-on-error: true + run: go test ./... -short -count=1 + working-directory: sirius-engine + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + + - 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: Build and push sirius-engine (${{ matrix.platform }}) + uses: docker/build-push-action@v6 + with: + context: ./sirius-engine + platforms: linux/${{ matrix.platform }} + push: true + # Fallback SHAs MUST match sirius-engine/Dockerfile ARG defaults. + # Floating refs (main/master) are forbidden; use a full SHA or a tag. + # Enforced by .github/workflows/check-pin-consistency.yml. + # See documentation/dev/architecture/README.engine-component-pinning.md. + build-args: | + GO_API_COMMIT_SHA=${{ env.GO_API_COMMIT_SHA || 'v0.0.18' }} + APP_SCANNER_COMMIT_SHA=${{ env.APP_SCANNER_COMMIT_SHA || 'a031480cc7e0dc4a1cb09bdcfafedd89fbc61dfd' }} + APP_TERMINAL_COMMIT_SHA=${{ env.APP_TERMINAL_COMMIT_SHA || '5745e43ca1f2ad3936a02a51cc77bfcf33ee95c1' }} + SIRIUS_NSE_COMMIT_SHA=${{ env.SIRIUS_NSE_COMMIT_SHA || 'a58e8c5330b49bd8f4e93c27e340c43c1fa89fa9' }} + APP_AGENT_COMMIT_SHA=${{ env.APP_AGENT_COMMIT_SHA || '9311f3805db9cc08740f1b588b6f3bff9191c9dd' }} + PINGPP_COMMIT_SHA=${{ env.PINGPP_COMMIT_SHA || '9508a16c40a49746feb7cab4b8c1c358246169b0' }} + tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-engine:${{ steps.meta.outputs.image_tag }}-${{ matrix.platform }} + + # Merge arch-specific Engine images into a single multi-arch manifest + merge-engine: + name: "Merge Engine Manifest" + needs: build-engine + if: needs.detect-changes.outputs.sirius_engine_changes == 'true' && github.event_name != 'pull_request' + runs-on: ubuntu-latest + outputs: + image_tag: ${{ steps.meta.outputs.image_tag }} + steps: + - name: Generate image tag + id: meta + run: | + if [ "${{ github.event_name }}" == "push" ] && [ "${{ github.ref }}" == "refs/heads/main" ]; then + echo "image_tag=latest" >> $GITHUB_OUTPUT + echo "also_tag_beta=true" >> $GITHUB_OUTPUT + elif [ "${{ github.event_name }}" == "repository_dispatch" ]; then + echo "image_tag=latest" >> $GITHUB_OUTPUT + echo "also_tag_beta=true" >> $GITHUB_OUTPUT + else + echo "image_tag=dev" >> $GITHUB_OUTPUT + fi + + - 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 and push multi-arch manifest for sirius-engine + run: | + TAG="${{ steps.meta.outputs.image_tag }}" + BASE="${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-engine" + + docker buildx imagetools create -t ${BASE}:${TAG} \ + ${BASE}:${TAG}-amd64 \ + ${BASE}:${TAG}-arm64 + + if [ "${{ steps.meta.outputs.also_tag_beta }}" == "true" ]; then + docker buildx imagetools create -t ${BASE}:beta \ + ${BASE}:${TAG}-amd64 \ + ${BASE}:${TAG}-arm64 + fi + + echo "Published ${BASE}:${TAG} (amd64 + arm64)" + + # ───────────────────────────────────────────────────────────────────────────── + # Build infrastructure images used by the default public stack. + # ───────────────────────────────────────────────────────────────────────────── + build-infra: + name: "Build Infra (${{ matrix.service }}, ${{ matrix.platform }})" + needs: [detect-changes, guard-registry-namespace] + if: > + needs.detect-changes.outputs.sirius_infra_changes == 'true' || + github.event_name == 'repository_dispatch' || + (github.event_name == 'push' && github.ref == 'refs/heads/main') + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + strategy: + fail-fast: false + matrix: + service: [sirius-postgres, sirius-rabbitmq, sirius-valkey] + platform: ${{ github.event_name == 'pull_request' && fromJSON('["amd64"]') || fromJSON('["amd64","arm64"]') }} + + steps: + - name: Checkout Sirius repository + uses: actions/checkout@v4 + + - name: Generate image tag + id: meta + run: | + 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 + elif [ "${{ github.event_name }}" == "repository_dispatch" ]; then + TAG="latest" + echo "also_tag_beta=true" >> $GITHUB_OUTPUT + else + TAG="dev" + fi + echo "image_tag=$TAG" >> $GITHUB_OUTPUT + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + + - 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: Build and push infra image (${{ matrix.service }}, ${{ matrix.platform }}) + uses: docker/build-push-action@v6 + with: + context: ./${{ matrix.service }} + platforms: linux/${{ matrix.platform }} + push: true + tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/${{ matrix.service }}:${{ steps.meta.outputs.image_tag }}-${{ matrix.platform }} + + merge-infra: + name: "Merge Infra Manifest (${{ matrix.service }})" + needs: [detect-changes, build-infra] + if: > + github.event_name != 'pull_request' && + ( + needs.detect-changes.outputs.sirius_infra_changes == 'true' || + github.event_name == 'repository_dispatch' || + (github.event_name == 'push' && github.ref == 'refs/heads/main') + ) + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + strategy: + fail-fast: false + matrix: + service: [sirius-postgres, sirius-rabbitmq, sirius-valkey] + steps: + - name: Generate image tag + id: meta + run: | + if [ "${{ github.event_name }}" == "push" ] && [ "${{ github.ref }}" == "refs/heads/main" ]; then + echo "image_tag=latest" >> $GITHUB_OUTPUT + echo "also_tag_beta=true" >> $GITHUB_OUTPUT + elif [ "${{ github.event_name }}" == "repository_dispatch" ]; then + echo "image_tag=latest" >> $GITHUB_OUTPUT + echo "also_tag_beta=true" >> $GITHUB_OUTPUT + else + echo "image_tag=dev" >> $GITHUB_OUTPUT + fi + + - 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 and push multi-arch manifest for infra image + run: | + TAG="${{ steps.meta.outputs.image_tag }}" + BASE="${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/${{ matrix.service }}" + + docker buildx imagetools create -t ${BASE}:${TAG} \ + ${BASE}:${TAG}-amd64 \ + ${BASE}:${TAG}-arm64 + + if [ "${{ steps.meta.outputs.also_tag_beta }}" == "true" ]; then + docker buildx imagetools create -t ${BASE}:beta \ + ${BASE}:${TAG}-amd64 \ + ${BASE}:${TAG}-arm64 + fi + + echo "Published ${BASE}:${TAG} (amd64 + arm64)" + + # ───────────────────────────────────────────────────────────────────────────── + # Integration Test + # + # Runs after at least one service build (or merge for multi-arch) succeeds. + # Key fixes vs the previous version: + # 1. sirius-api is ALWAYS started when sirius-engine is tested, because + # start-enhanced.sh validates the API key contract at startup. + # 2. sirius-engine depends_on sirius-api in the test compose config. + # 3. The health-wait loop covers sirius-api even when only engine changed. + # ───────────────────────────────────────────────────────────────────────────── + test: + name: Integration Test + needs: + - detect-changes + - build-ui + - build-api + - build-engine + runs-on: ubuntu-latest + if: > + always() && + ( + needs.build-ui.result == 'success' || + needs.build-api.result == 'success' || + needs.build-engine.result == 'success' + ) + 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: Determine image tag + id: tag + run: | + # Compute the tag the same way build jobs do (from event context). + # build-* are matrix jobs with no job-level outputs, so we cannot + # use needs.build-ui.outputs.image_tag — it is always empty. + 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" + elif [ "${{ github.event_name }}" == "push" ] && [ "${{ github.ref }}" == "refs/heads/sirius-demo" ]; then + TAG="dev" + elif [ "${{ github.event_name }}" == "repository_dispatch" ]; then + TAG="latest" + else + TAG="latest" + fi + # Integration tests always use the amd64 arch-specific image tag + echo "image_tag=${TAG}-amd64" >> $GITHUB_OUTPUT + echo "Using image tag: ${TAG}-amd64" + + - name: Create test environment + run: | + cat > docker-compose.test.yml << 'EOF' + name: sirius-test + services: + sirius-postgres: + image: postgres:15-alpine + environment: + POSTGRES_USER: postgres + POSTGRES_PASSWORD: postgres + POSTGRES_DB: sirius_test + tmpfs: + - /var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U postgres"] + interval: 5s + timeout: 5s + retries: 10 + + 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: 10 + + sirius-valkey: + image: valkey/valkey:latest + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 5s + timeout: 5s + retries: 10 + + sirius-ui: + image: ${SIRIUS_UI_IMAGE} + environment: + - NODE_ENV=production + - SKIP_ENV_VALIDATION=1 + - DATABASE_URL=postgresql://postgres:postgres@sirius-postgres:5432/sirius_test + - NEXTAUTH_SECRET=test-secret + - 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_FILE=/run/secrets/sirius_api_key + secrets: + - sirius_api_key + depends_on: + sirius-postgres: + condition: service_healthy + healthcheck: + test: ["CMD-SHELL", "wget -q --tries=1 -O /dev/null http://127.0.0.1:3000/"] + interval: 10s + timeout: 5s + retries: 12 + start_period: 15s + + sirius-api: + image: ${SIRIUS_API_IMAGE} + 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_FILE=/run/secrets/sirius_api_key + secrets: + - sirius_api_key + depends_on: + sirius-postgres: + condition: service_healthy + sirius-rabbitmq: + condition: service_healthy + sirius-valkey: + condition: service_healthy + healthcheck: + test: ["CMD-SHELL", "KEY=$(tr -d '\\r\\n' < /run/secrets/sirius_api_key); STATUS=$(curl -s -o /dev/null -w '%{http_code}' -H \"X-API-Key: $$KEY\" http://127.0.0.1:9001/host/); echo \"API health probe: $$STATUS\"; [ -n \"$$STATUS\" ] && [ \"$$STATUS\" != '000' ] && echo \"$$STATUS\" | grep -qvE '^5'"] + interval: 10s + timeout: 10s + retries: 24 + start_period: 30s + + sirius-engine: + image: ${SIRIUS_ENGINE_IMAGE} + 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_FILE=/run/secrets/sirius_api_key + - SIRIUS_API_URL=http://sirius-api:9001 + - API_BASE_URL=http://sirius-api:9001 + secrets: + - sirius_api_key + depends_on: + sirius-postgres: + condition: service_healthy + sirius-rabbitmq: + condition: service_healthy + sirius-valkey: + condition: service_healthy + sirius-api: + condition: service_healthy + healthcheck: + test: ["CMD", "bash", "-c", "echo > /dev/tcp/127.0.0.1/50051"] + interval: 10s + timeout: 5s + retries: 12 + start_period: 30s + + secrets: + sirius_api_key: + file: ./secrets/sirius_api_key.txt + EOF + + mkdir -p secrets + printf '%s\n' 'ci-placeholder-api-key' > secrets/sirius_api_key.txt + chmod 644 secrets/sirius_api_key.txt + + IMAGE_TAG="${{ steps.tag.outputs.image_tag }}" + export SIRIUS_UI_IMAGE="${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-ui:${IMAGE_TAG}" + export SIRIUS_API_IMAGE="${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-api:${IMAGE_TAG}" + export SIRIUS_ENGINE_IMAGE="${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/sirius-engine:${IMAGE_TAG}" + echo "SIRIUS_UI_IMAGE=$SIRIUS_UI_IMAGE" >> $GITHUB_ENV + echo "SIRIUS_API_IMAGE=$SIRIUS_API_IMAGE" >> $GITHUB_ENV + echo "SIRIUS_ENGINE_IMAGE=$SIRIUS_ENGINE_IMAGE" >> $GITHUB_ENV + + - name: Run integration test + run: | + echo "Starting integration test..." + + # 1. Infrastructure services + docker compose -f docker-compose.test.yml up -d sirius-postgres sirius-rabbitmq sirius-valkey + + echo "Waiting for infrastructure services to become healthy..." + timeout 90 bash -c ' + until docker compose -f docker-compose.test.yml ps --format json | \ + python3 -c " + import sys, json + svcs = [json.loads(l) for l in sys.stdin if l.strip()] + infra = [s for s in svcs if s[\"Service\"] in (\"sirius-postgres\",\"sirius-rabbitmq\",\"sirius-valkey\")] + healthy = [s for s in infra if s.get(\"Health\",\"\") == \"healthy\"] + sys.exit(0 if len(healthy) == 3 else 1) + "; do sleep 3; done + ' + echo "Infrastructure healthy" + + # 2. Determine which application services to test. + # IMPORTANT: sirius-api must always be started alongside sirius-engine + # because start-enhanced.sh validates the API key contract at startup. + SERVICES_TO_TEST="" + API_REQUIRED=false + + if [ "${{ needs.detect-changes.outputs.sirius_api_changes }}" == "true" ]; then + SERVICES_TO_TEST="$SERVICES_TO_TEST sirius-api" + API_REQUIRED=true + fi + + if [ "${{ needs.detect-changes.outputs.sirius_engine_changes }}" == "true" ]; then + SERVICES_TO_TEST="$SERVICES_TO_TEST sirius-engine" + # Engine requires the API to be running for its startup preflight check + if [ "$API_REQUIRED" != "true" ]; then + SERVICES_TO_TEST="sirius-api$SERVICES_TO_TEST" + API_REQUIRED=true + echo "Adding sirius-api as required dependency for sirius-engine" + fi + fi + + if [ "${{ needs.detect-changes.outputs.sirius_ui_changes }}" == "true" ]; then + SERVICES_TO_TEST="$SERVICES_TO_TEST sirius-ui" + fi + + if [ -z "$SERVICES_TO_TEST" ]; then + echo "No application services to test" + exit 0 + fi + + echo "Starting application services:$SERVICES_TO_TEST" + docker compose -f docker-compose.test.yml up -d $SERVICES_TO_TEST + + # 3. Wait for each service to become healthy using Docker's built-in health status. + # This avoids exec-into-container quoting issues (e.g. the engine uses + # /dev/tcp which requires bash and breaks sh -c quoting). + for SVC in $SERVICES_TO_TEST; do + CONTAINER="sirius-test-${SVC}-1" + echo "Waiting for $SVC..." + timeout 180 bash -c "until [ \"\$(docker inspect --format '{{.State.Health.Status}}' ${CONTAINER} 2>/dev/null)\" = 'healthy' ]; do sleep 5; done" \ + || { echo "::error::Timeout waiting for ${SVC} to become healthy"; exit 1; } + echo "$SVC is healthy" + done + + # 4. Final health assertions + echo "Service status:" + docker compose -f docker-compose.test.yml ps + + echo "Running final health assertions..." + FAILED=0 + for SVC in $SERVICES_TO_TEST; do + CONTAINER="sirius-test-${SVC}-1" + HEALTH=$(docker inspect --format '{{.State.Health.Status}}' "$CONTAINER" 2>/dev/null) + if [ "$HEALTH" = "healthy" ]; then + echo " $SVC passed (healthy)" + else + echo " $SVC FAILED (status: ${HEALTH:-unknown})" + FAILED=1 + fi + done + + if [ "$FAILED" -eq 1 ]; then + echo "::error::One or more services failed their health check" + exit 1 + fi + echo "All health checks passed" + + - name: Capture diagnostics on failure + if: failure() + run: | + mkdir -p ci-diagnostics + echo "=== docker compose ps ===" > ci-diagnostics/compose-status.txt + docker compose -f docker-compose.test.yml ps --format "table {{.Name}}\t{{.Service}}\t{{.Status}}\t{{.Health}}" \ + >> ci-diagnostics/compose-status.txt 2>&1 || true + + echo "=== sirius-engine inspect ===" > ci-diagnostics/engine-inspect.json + docker inspect sirius-test-sirius-engine-1 >> ci-diagnostics/engine-inspect.json 2>&1 || true + + for SVC in sirius-engine sirius-api sirius-ui sirius-postgres sirius-rabbitmq sirius-valkey; do + echo "--- $SVC logs (last 200 lines) ---" > "ci-diagnostics/${SVC}.log" + docker compose -f docker-compose.test.yml logs --tail=200 "$SVC" \ + >> "ci-diagnostics/${SVC}.log" 2>&1 || true + done + + echo "::group::Compose Status" + cat ci-diagnostics/compose-status.txt + echo "::endgroup::" + echo "::group::sirius-engine logs" + cat ci-diagnostics/sirius-engine.log + echo "::endgroup::" + echo "::group::sirius-api logs" + cat ci-diagnostics/sirius-api.log + echo "::endgroup::" + + - name: Upload diagnostic artifacts + if: failure() + uses: actions/upload-artifact@v4 + with: + name: integration-test-diagnostics + path: ci-diagnostics/ + retention-days: 7 + + - name: Cleanup test environment + if: always() + run: | + docker compose -f docker-compose.test.yml down --volumes --remove-orphans 2>/dev/null || true + + public-stack-contract: + name: Public Stack Contract + needs: + - build-ui + - build-api + - build-engine + - build-infra + - merge-ui + - merge-api + - merge-engine + - merge-infra + - test + runs-on: ubuntu-latest + if: > + always() && + ( + github.event_name == 'repository_dispatch' || + (github.event_name == 'push' && github.ref == 'refs/heads/main') + ) && + (needs.build-ui.result == 'success' || needs.build-ui.result == 'skipped') && + (needs.build-api.result == 'success' || needs.build-api.result == 'skipped') && + (needs.build-engine.result == 'success' || needs.build-engine.result == 'skipped') && + (needs.build-infra.result == 'success' || needs.build-infra.result == 'skipped') && + (needs.merge-ui.result == 'success' || needs.merge-ui.result == 'skipped') && + (needs.merge-api.result == 'success' || needs.merge-api.result == 'skipped') && + (needs.merge-engine.result == 'success' || needs.merge-engine.result == 'skipped') && + (needs.merge-infra.result == 'success' || needs.merge-infra.result == 'skipped') && + (needs.test.result == 'success' || needs.test.result == 'skipped') + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Validate public latest compose path + run: | + bash scripts/validate-public-compose-path.sh latest + + # ───────────────────────────────────────────────────────────────────────────── + # Dispatch to sirius-demo when sirius-demo branch is pushed + # ───────────────────────────────────────────────────────────────────────────── + dispatch-demo-deployment: + name: Dispatch Demo Deployment (sirius-demo branch) + runs-on: ubuntu-latest + needs: [detect-changes, build-ui, build-api, build-engine, test] + if: > + github.ref == 'refs/heads/sirius-demo' && + github.event_name == 'push' && + always() && + (needs.detect-changes.result == 'success' || needs.detect-changes.result == 'skipped') && + (needs.build-ui.result == 'success' || needs.build-ui.result == 'skipped') && + (needs.build-api.result == 'success' || needs.build-api.result == 'skipped') && + (needs.build-engine.result == 'success' || needs.build-engine.result == 'skipped') && + (needs.test.result == 'success' || needs.test.result == 'skipped') + steps: + - name: Dispatch to sirius-demo repository + uses: peter-evans/repository-dispatch@v3 + with: + token: ${{ secrets.DEMO_DISPATCH_TOKEN }} + repository: SiriusScan/sirius-demo + event-type: sirius-demo-updated + client-payload: | + { + "source_repo": "${{ github.repository }}", + "source_branch": "${{ github.ref_name }}", + "source_sha": "${{ github.sha }}", + "triggered_by": "${{ github.actor }}" + } + + # ───────────────────────────────────────────────────────────────────────────── + # Canary dispatch to sirius-demo on every main branch push. + # Fixed: commit messages with newlines are sanitized before injection into JSON + # by using `gh api -f` flags which handle escaping correctly. + # ───────────────────────────────────────────────────────────────────────────── + dispatch-demo-canary: + name: Dispatch Demo Canary (main branch) + runs-on: ubuntu-latest + needs: [detect-changes, build-ui, build-api, build-engine, test] + if: > + github.ref == 'refs/heads/main' && + github.event_name == 'push' && + always() && + (needs.detect-changes.result == 'success' || needs.detect-changes.result == 'skipped') && + (needs.build-ui.result == 'success' || needs.build-ui.result == 'skipped') && + (needs.build-api.result == 'success' || needs.build-api.result == 'skipped') && + (needs.build-engine.result == 'success' || needs.build-engine.result == 'skipped') && + (needs.test.result == 'success' || needs.test.result == 'skipped') + steps: + - name: Dispatch to sirius-demo repository (canary trigger) + env: + GH_TOKEN: ${{ secrets.DEMO_DISPATCH_TOKEN }} + COMMIT_MSG: ${{ github.event.head_commit.message }} + run: | + # Sanitize: take first line only and strip characters that break JSON + SAFE_MSG=$(printf '%s' "$COMMIT_MSG" | head -1 | tr -d '"\\' | cut -c1-200) + + gh api repos/SiriusScan/sirius-demo/dispatches \ + --method POST \ + -f event_type=sirius-main-updated \ + -f "client_payload[source_repo]=${{ github.repository }}" \ + -f "client_payload[source_branch]=${{ github.ref_name }}" \ + -f "client_payload[source_sha]=${{ github.sha }}" \ + -f "client_payload[triggered_by]=${{ github.actor }}" \ + -f "client_payload[commit_message]=$SAFE_MSG" \ + -f "client_payload[canary]=true" diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..4197d9f --- /dev/null +++ b/.github/workflows/deploy.yml @@ -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" diff --git a/.github/workflows/issue-triage.yml b/.github/workflows/issue-triage.yml new file mode 100644 index 0000000..a175a38 --- /dev/null +++ b/.github/workflows/issue-triage.yml @@ -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 = ""; + 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, + }); + } diff --git a/.github/workflows/pr-labeler.yml b/.github/workflows/pr-labeler.yml new file mode 100644 index 0000000..2329b96 --- /dev/null +++ b/.github/workflows/pr-labeler.yml @@ -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 }}" diff --git a/.github/workflows/pr-review-card.yml b/.github/workflows/pr-review-card.yml new file mode 100644 index 0000000..ea3dd9a --- /dev/null +++ b/.github/workflows/pr-review-card.yml @@ -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 = ""; + + 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, + }); + } diff --git a/.github/workflows/pr-size-labeler.yml b/.github/workflows/pr-size-labeler.yml new file mode 100644 index 0000000..4b20ed3 --- /dev/null +++ b/.github/workflows/pr-size-labeler.yml @@ -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 diff --git a/.github/workflows/publish-release-image-tags.yml b/.github/workflows/publish-release-image-tags.yml new file mode 100644 index 0000000..619b8ea --- /dev/null +++ b/.github/workflows/publish-release-image-tags.yml @@ -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 }}" diff --git a/.github/workflows/slash-command-dispatch.yml b/.github/workflows/slash-command-dispatch.yml new file mode 100644 index 0000000..bb0a63c --- /dev/null +++ b/.github/workflows/slash-command-dispatch.yml @@ -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}`); diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml new file mode 100644 index 0000000..1365864 --- /dev/null +++ b/.github/workflows/stale.yml @@ -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" diff --git a/.github/workflows/validate-docker-config.yml b/.github/workflows/validate-docker-config.yml new file mode 100644 index 0000000..ade1e92 --- /dev/null +++ b/.github/workflows/validate-docker-config.yml @@ -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" diff --git a/.github/workflows/verify-ghcr-release-tag.yml b/.github/workflows/verify-ghcr-release-tag.yml new file mode 100644 index 0000000..f298f05 --- /dev/null +++ b/.github/workflows/verify-ghcr-release-tag.yml @@ -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 }}" diff --git a/.github/workflows/welcome-first-time.yml b/.github/workflows/welcome-first-time.yml new file mode 100644 index 0000000..885cea7 --- /dev/null +++ b/.github/workflows/welcome-first-time.yml @@ -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. diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..4b1fabc --- /dev/null +++ b/.gitignore @@ -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/ \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..690010f --- /dev/null +++ b/CHANGELOG.md @@ -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 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..3b4b13b --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -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 +. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8b3d96c --- /dev/null +++ b/CONTRIBUTING.md @@ -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: +- Questions and proposals: +- 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//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: `/` (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). diff --git a/LICENSE b/LICENSE new file mode 100755 index 0000000..46d594d --- /dev/null +++ b/LICENSE @@ -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. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..81b160a --- /dev/null +++ b/Makefile @@ -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 diff --git a/README.md b/README.md new file mode 100755 index 0000000..facaeb9 --- /dev/null +++ b/README.md @@ -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 ` 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) diff --git a/README.wehub.md b/README.wehub.md new file mode 100644 index 0000000..0e42346 --- /dev/null +++ b/README.wehub.md @@ -0,0 +1,7 @@ +# WeHub 来源说明 + +- 原始项目：`SiriusScan/Sirius` +- 原始仓库：https://github.com/SiriusScan/Sirius +- 导入方式：上游默认分支的最新快照 +- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准 +- 本文件仅用于记录来源，不代表 WeHub 是原项目作者 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..d21f4c9 --- /dev/null +++ b/SECURITY.md @@ -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: +- 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. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..b7ccb88 --- /dev/null +++ b/SUPPORT.md @@ -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: +- Documentation portal: +- Community Discord: + +## Bug Reports + +For defects and regressions, open a GitHub issue: + +- 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` diff --git a/docker-compose.build.yaml b/docker-compose.build.yaml new file mode 100644 index 0000000..e9b68c7 --- /dev/null +++ b/docker-compose.build.yaml @@ -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 diff --git a/docker-compose.dev.yaml b/docker-compose.dev.yaml new file mode 100644 index 0000000..90fa1ea --- /dev/null +++ b/docker-compose.dev.yaml @@ -0,0 +1,195 @@ +# SiriusScan Development Docker Compose Override +# Use with: docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up --build +# +# Builds Postgres, Valkey, and RabbitMQ from ./sirius-* Dockerfiles (no GHCR pull). +# sirius-ui / sirius-api / sirius-engine use local dev images with pull_policy: never. +# For registry-based infra instead, use docker-compose.yaml alone or add IMAGE_TAG + ghcr login. +# +# Linux "Permission denied" on bind mounts: sirius-ui and sirius-api run as UID/GID 1001 by +# default. If the repo is owned by root (e.g. /opt/Sirius), webpack/go cannot write into mounts. +# Fix either: +# • chown -R 1001:1001 sirius-ui sirius-api (and optional minor-projects paths you mount), or +# • Add to .env: SIRIUS_DEV_CONTAINER_UID=0 SIRIUS_DEV_CONTAINER_GID=0 (dev-only; runs as root in those containers). + +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: development # Use development stage + args: + NEXT_PUBLIC_CLIENTVAR: "clientvar" + # Override registry image with local dev build + image: sirius-sirius-ui:dev + pull_policy: never + user: "${SIRIUS_DEV_CONTAINER_UID:-1001}:${SIRIUS_DEV_CONTAINER_GID:-1001}" + volumes: + # Mount source code for live reloading + - ./sirius-ui/src:/app/src + - ./sirius-ui/public:/app/public + - ./sirius-ui/prisma:/app/prisma + - ./sirius-ui/next.config.mjs:/app/next.config.mjs + - ./sirius-ui/tailwind.config.ts:/app/tailwind.config.ts + - ./sirius-ui/package.json:/app/package.json + - ./sirius-ui/postcss.config.cjs:/app/postcss.config.cjs + # Mount startup scripts for live updates + - ./sirius-ui/start-dev.sh:/app/start-dev.sh + - ./sirius-ui/start-prod.sh:/app/start-prod.sh + # Preserve node_modules from container to avoid architecture conflicts + - node_modules:/app/node_modules + # Add system monitor from separate repository + - ../minor-projects/app-system-monitor:/system-monitor + # Add app administrator from separate repository + - ../minor-projects/app-administrator:/app-administrator + # Note: UI reads NSE scripts from ValKey (populated by scanner) + # No sirius-nse volume mount needed - scanner manages repos independently + environment: + - NODE_ENV=development + - NEXT_TELEMETRY_DISABLED=1 + # Override to use SQLite for authentication as defined in schema.prisma + - DATABASE_URL=file:./dev.db + - NEXTAUTH_SECRET=development-secret-key + - NEXTAUTH_URL=http://localhost:3000 + - VALKEY_HOST=sirius-valkey + - VALKEY_PORT=6379 + - RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/ + - SIRIUS_API_URL=http://sirius-api:9001 + - NEXT_PUBLIC_SIRIUS_API_URL=http://localhost:9001 + - CONTAINER_NAME=sirius-ui + # Internal API auth (file mount from base compose) + - SIRIUS_API_KEY_FILE=${SIRIUS_API_KEY_FILE:-/run/secrets/sirius_api_key} + # Performance: increase Node.js heap for faster webpack compilation + - NODE_OPTIONS=--max-old-space-size=4096 + # Performance: enable filesystem polling for reliable hot reload on Docker bind mounts + - WATCHPACK_POLLING=true + ports: + - "3000:3000" + - "3001:3001" # Development port + # Remove PostgreSQL dependency - using SQLite for authentication + depends_on: [] + # Override base resource limits for development performance + # Webpack compilation needs significantly more CPU than serving a production build + deploy: + resources: + limits: + memory: 4G + cpus: "4" + reservations: + memory: 1G + cpus: "1" + + sirius-api: + build: + context: ./sirius-api/ + target: development # Use development stage + # Override image for dev builds + image: sirius-sirius-api:dev + pull_policy: never + user: "${SIRIUS_DEV_CONTAINER_UID:-1001}:${SIRIUS_DEV_CONTAINER_GID:-1001}" + volumes: + - ./sirius-api:/api + # Enable for local go-api development with source-aware functionality: + - ../minor-projects/go-api:/go-api + # Add system monitor from separate repository + - ../minor-projects/app-system-monitor:/system-monitor + # Add app administrator from separate repository + - ../minor-projects/app-administrator:/app-administrator + ports: + - "9001:9001" + environment: + - GO_ENV=development + - API_PORT=9001 + - POSTGRES_HOST=sirius-postgres + - POSTGRES_USER=postgres + - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required for development. Run installer first using docker compose -f docker-compose.installer.yaml run --rm sirius-installer} + - POSTGRES_DB=sirius + - POSTGRES_PORT=5432 + - VALKEY_HOST=sirius-valkey + - VALKEY_PORT=6379 + - RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/ + - LOG_LEVEL=info + - CONTAINER_NAME=sirius-api + - SIRIUS_API_KEY_FILE=${SIRIUS_API_KEY_FILE:-/run/secrets/sirius_api_key} + + sirius-engine: + build: + context: ./sirius-engine/ + target: development # Use development stage + # Override image for dev builds + image: sirius-sirius-engine:dev + pull_policy: never + # Uses bridge networking (from base compose) with explicit port mapping: + # 5174:5174 - Engine main port + # 50051:50051 - Agent gRPC port + # This allows native agents on the host to connect via localhost:50051 + # Required for ICMP probes in ping++ fingerprinting + cap_add: + - NET_RAW + volumes: + - ./sirius-engine:/engine + # Mount start scripts for hot reload of startup changes + - ./sirius-engine/start-enhanced.sh:/start-enhanced.sh + - ./sirius-engine/start.sh:/start.sh + # Development volume mounts (require ../minor-projects/ structure): + # Enabled for local development with source-aware functionality + - ../minor-projects/app-agent:/app-agent + - ../minor-projects/app-scanner:/app-scanner + - ../minor-projects/app-terminal:/app-terminal + - ../minor-projects/go-api:/go-api + - ../minor-projects/ping++:/ping++ + - ../minor-projects/sirius-nse:/sirius-nse + - ../minor-projects/sirius-agent-modules:/app-agent/sirius-agent-modules + # Add system monitor from separate repository + - ../minor-projects/app-system-monitor:/system-monitor + # Add app administrator from separate repository + - ../minor-projects/app-administrator:/app-administrator + environment: + - GO_ENV=development + - ENGINE_MAIN_PORT=5174 + - GRPC_AGENT_PORT=50051 + - POSTGRES_HOST=sirius-postgres + - POSTGRES_USER=postgres + - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required for development. Run installer first using docker compose -f docker-compose.installer.yaml run --rm sirius-installer} + - POSTGRES_DB=sirius + - POSTGRES_PORT=5432 + - VALKEY_HOST=sirius-valkey + - VALKEY_PORT=6379 + - RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/ + - LOG_LEVEL=info + # Scanner/agent API base (canonical SIRIUS_API_URL; API_BASE_URL mirrors it in base compose) + - SIRIUS_API_URL=${SIRIUS_API_URL:-http://sirius-api:9001} + - API_BASE_URL=${SIRIUS_API_URL:-http://sirius-api:9001} + - AGENT_ID=sirius-engine + - HOST_ID=sirius-engine + - ENABLE_SCRIPTING=true + - CONTAINER_NAME=sirius-engine + - SIRIUS_API_KEY_FILE=${SIRIUS_API_KEY_FILE:-/run/secrets/sirius_api_key} + +networks: + default: + name: sirius + driver: bridge + +volumes: + node_modules: diff --git a/docker-compose.installer.yaml b/docker-compose.installer.yaml new file mode 100644 index 0000000..6c0c4e5 --- /dev/null +++ b/docker-compose.installer.yaml @@ -0,0 +1,17 @@ +# Installer writes .env and secrets/sirius_api_key.txt (internal API key) into the repo root via the workspace mount. +services: + sirius-installer: + image: sirius-installer:local + pull_policy: never + build: + context: . + dockerfile: installer/Dockerfile + working_dir: /workspace + # Default to root so the README's `docker compose ... run sirius-installer` + # quickstart keeps working unchanged. CI (and Linux users who want host- + # owned files) can override by exporting SIRIUS_INSTALLER_UID/GID before + # invoking compose. See scripts/validate-public-compose-path.sh. + user: "${SIRIUS_INSTALLER_UID:-0}:${SIRIUS_INSTALLER_GID:-0}" + volumes: + - ./:/workspace + command: ["--template", ".env.production.example", "--output", ".env"] diff --git a/docker-compose.prod.yaml b/docker-compose.prod.yaml new file mode 100644 index 0000000..70d9690 --- /dev/null +++ b/docker-compose.prod.yaml @@ -0,0 +1,55 @@ +# SiriusScan Production Docker Compose Override +# Use with: docker compose -f docker-compose.yaml -f docker-compose.prod.yaml up -d + +services: + sirius-postgres: + environment: + - POSTGRES_USER=${POSTGRES_USER:-postgres} + - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required for production. Run installer first using docker compose -f docker-compose.installer.yaml run --rm sirius-installer} + - POSTGRES_DB=${POSTGRES_DB:-sirius} + + sirius-ui: + pull_policy: always + environment: + - NODE_ENV=production + - SKIP_ENV_VALIDATION=0 + - NEXTAUTH_SECRET=${NEXTAUTH_SECRET:?NEXTAUTH_SECRET is required for production. Run installer first using docker compose -f docker-compose.installer.yaml run --rm sirius-installer} + - INITIAL_ADMIN_PASSWORD=${INITIAL_ADMIN_PASSWORD:?INITIAL_ADMIN_PASSWORD is required for production. Run installer first using docker compose -f docker-compose.installer.yaml run --rm sirius-installer} + - NEXTAUTH_URL=${NEXTAUTH_URL:-http://localhost:3000} + - SIRIUS_API_URL=${SIRIUS_API_URL:-http://sirius-api:9001} + - NEXT_PUBLIC_SIRIUS_API_URL=${NEXT_PUBLIC_SIRIUS_API_URL:-http://localhost:9001} + - SIRIUS_API_KEY_FILE=${SIRIUS_API_KEY_FILE:-/run/secrets/sirius_api_key} + restart: unless-stopped + + sirius-api: + pull_policy: always + environment: + - GO_ENV=production + - CORS_ALLOWED_ORIGINS=${CORS_ALLOWED_ORIGINS:-http://localhost:3000,https://sirius.local} + - POSTGRES_HOST=${POSTGRES_HOST:-sirius-postgres} + - POSTGRES_USER=${POSTGRES_USER:-postgres} + - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required for production. Run installer first using docker compose -f docker-compose.installer.yaml run --rm sirius-installer} + - POSTGRES_DB=${POSTGRES_DB:-sirius} + - POSTGRES_PORT=${POSTGRES_PORT:-5432} + - VALKEY_HOST=${VALKEY_HOST:-sirius-valkey} + - VALKEY_PORT=${VALKEY_PORT:-6379} + - RABBITMQ_URL=${RABBITMQ_URL:-amqp://guest:guest@sirius-rabbitmq:5672/} + - SIRIUS_API_KEY_FILE=${SIRIUS_API_KEY_FILE:-/run/secrets/sirius_api_key} + restart: unless-stopped + + sirius-engine: + pull_policy: always + environment: + - GO_ENV=production + - POSTGRES_HOST=${POSTGRES_HOST:-sirius-postgres} + - POSTGRES_USER=${POSTGRES_USER:-postgres} + - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required for production. Run installer first using docker compose -f docker-compose.installer.yaml run --rm sirius-installer} + - POSTGRES_DB=${POSTGRES_DB:-sirius} + - POSTGRES_PORT=${POSTGRES_PORT:-5432} + - VALKEY_HOST=${VALKEY_HOST:-sirius-valkey} + - VALKEY_PORT=${VALKEY_PORT:-6379} + - RABBITMQ_URL=${RABBITMQ_URL:-amqp://guest:guest@sirius-rabbitmq:5672/} + - SIRIUS_API_URL=${SIRIUS_API_URL:-http://sirius-api:9001} + - API_BASE_URL=${SIRIUS_API_URL:-http://sirius-api:9001} + - SIRIUS_API_KEY_FILE=${SIRIUS_API_KEY_FILE:-/run/secrets/sirius_api_key} + restart: unless-stopped diff --git a/docker-compose.secrets.yaml b/docker-compose.secrets.yaml new file mode 100644 index 0000000..0b348e8 --- /dev/null +++ b/docker-compose.secrets.yaml @@ -0,0 +1,32 @@ +# Optional overlay for additional secret-backed env vars. +# Internal API key mounts live in docker-compose.yaml by default (sirius_api_key secret). +services: + sirius-postgres: + environment: + - POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password + secrets: + - postgres_password + + sirius-ui: + secrets: + - sirius_api_key + - nextauth_secret + - initial_admin_password + + sirius-api: + secrets: + - sirius_api_key + + sirius-engine: + secrets: + - sirius_api_key + +secrets: + postgres_password: + file: ./secrets/postgres_password.txt + sirius_api_key: + file: ./secrets/sirius_api_key.txt + nextauth_secret: + file: ./secrets/nextauth_secret.txt + initial_admin_password: + file: ./secrets/initial_admin_password.txt diff --git a/docker-compose.yaml b/docker-compose.yaml new file mode 100644 index 0000000..7b76df9 --- /dev/null +++ b/docker-compose.yaml @@ -0,0 +1,272 @@ +# SiriusScan Base Docker Compose Configuration +# This is the base configuration that works for most environments. +# Standard startup pulls published images for the full stack. +# Use with: docker compose up -d +# +# Runtime API URL contract (single source of truth in .env): +# - SIRIUS_API_URL: server-side base URL for sirius-api (Docker DNS, e.g. http://sirius-api:9001). +# Used by sirius-ui (server), sirius-engine preflight, and app-scanner persistence. +# - NEXT_PUBLIC_SIRIUS_API_URL: browser-facing API URL (host port, e.g. http://localhost:9001). +# - API_BASE_URL on sirius-engine: must match SIRIUS_API_URL (set from the same compose value below). +# - SIRIUS_API_KEY_FILE: compose mounts ./secrets/sirius_api_key.txt at /run/secrets/sirius_api_key. + +name: sirius + +services: + sirius-rabbitmq: + image: ghcr.io/siriusscan/sirius-rabbitmq:${IMAGE_TAG:-latest} + pull_policy: ${SIRIUS_IMAGE_PULL_POLICY:-always} + restart: unless-stopped + container_name: sirius-rabbitmq + hostname: sirius-rabbitmq + environment: + VALKEY_HOST: ${VALKEY_HOST:-sirius-valkey} + VALKEY_PORT: ${VALKEY_PORT:-6379} + ports: + - "5672:5672" + - "15672:15672" + volumes: + - ./rabbitmq/rabbitmq.conf:/etc/rabbitmq/rabbitmq.conf:ro + - rabbitmq_data:/var/lib/rabbitmq + healthcheck: + test: ["CMD", "rabbitmqctl", "status"] + interval: 30s + timeout: 15s + retries: 5 + deploy: + resources: + limits: + memory: 512M + cpus: "0.5" + reservations: + memory: 256M + cpus: "0.25" + + sirius-postgres: + image: ghcr.io/siriusscan/sirius-postgres:${IMAGE_TAG:-latest} + pull_policy: ${SIRIUS_IMAGE_PULL_POLICY:-always} + restart: unless-stopped + container_name: sirius-postgres + hostname: sirius-postgres + environment: + POSTGRES_USER: ${POSTGRES_USER:-postgres} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required. Run installer first using docker compose -f docker-compose.installer.yaml run --rm sirius-installer} + POSTGRES_DB: ${POSTGRES_DB:-sirius} + VALKEY_HOST: ${VALKEY_HOST:-sirius-valkey} + VALKEY_PORT: ${VALKEY_PORT:-6379} + ports: + - "5432:5432" + volumes: + - postgres_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD", "/usr/local/bin/pg-healthcheck.sh"] + interval: 10s + timeout: 5s + retries: 5 + deploy: + resources: + limits: + memory: 1G + cpus: "0.5" + reservations: + memory: 512M + cpus: "0.25" + + sirius-valkey: + image: ghcr.io/siriusscan/sirius-valkey:${IMAGE_TAG:-latest} + pull_policy: ${SIRIUS_IMAGE_PULL_POLICY:-always} + restart: unless-stopped + container_name: sirius-valkey + hostname: sirius-valkey + environment: + VALKEY_HOST: ${VALKEY_HOST:-sirius-valkey} + VALKEY_PORT: ${VALKEY_PORT:-6379} + ports: + - "6379:6379" + volumes: + - valkey_data:/data + healthcheck: + test: ["CMD", "valkey-cli", "ping"] + interval: 10s + timeout: 5s + retries: 5 + deploy: + resources: + limits: + memory: 256M + cpus: "0.25" + reservations: + memory: 128M + cpus: "0.1" + + sirius-ui: + # Runtime contract: + # - release mode: IMAGE_TAG= + SIRIUS_IMAGE_PULL_POLICY=always + # - source mode: add docker-compose.build.yaml with --build + image: ghcr.io/siriusscan/sirius-ui:${IMAGE_TAG:-latest} + pull_policy: ${SIRIUS_IMAGE_PULL_POLICY:-always} + container_name: sirius-ui + hostname: sirius-ui + restart: unless-stopped + ports: + - "3000:3000" + environment: + - NODE_ENV=${NODE_ENV:-production} + - SKIP_ENV_VALIDATION=${SKIP_ENV_VALIDATION:-1} + - DATABASE_URL=${DATABASE_URL:?DATABASE_URL is required. Run installer first using docker compose -f docker-compose.installer.yaml run --rm sirius-installer} + # UI auth settings + - NEXTAUTH_SECRET=${NEXTAUTH_SECRET:?NEXTAUTH_SECRET is required for sirius-ui. Run installer first using docker compose -f docker-compose.installer.yaml run --rm sirius-installer} + - NEXTAUTH_URL=${NEXTAUTH_URL:-http://localhost:3000} + - INITIAL_ADMIN_PASSWORD=${INITIAL_ADMIN_PASSWORD:?INITIAL_ADMIN_PASSWORD is required for sirius-ui. Run installer first using docker compose -f docker-compose.installer.yaml run --rm sirius-installer} + - SIRIUS_API_URL=${SIRIUS_API_URL:-http://sirius-api:9001} + - NEXT_PUBLIC_SIRIUS_API_URL=${NEXT_PUBLIC_SIRIUS_API_URL:-http://localhost:9001} + - DISCORD_CLIENT_ID=${DISCORD_CLIENT_ID:-dummy_client_id} + - DISCORD_CLIENT_SECRET=${DISCORD_CLIENT_SECRET:-dummy_client_secret} + # Internal API auth: file-backed secret mount only + - SIRIUS_API_KEY_FILE=${SIRIUS_API_KEY_FILE:-/run/secrets/sirius_api_key} + secrets: + - sirius_api_key + depends_on: + sirius-postgres: + condition: service_healthy + sirius-api: + condition: service_healthy + sirius-rabbitmq: + condition: service_healthy + healthcheck: + test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3000/"] + interval: 30s + timeout: 10s + retries: 3 + deploy: + resources: + limits: + memory: 2G + cpus: "2" + reservations: + memory: 512M + cpus: "0.5" + + sirius-api: + image: ghcr.io/siriusscan/sirius-api:${IMAGE_TAG:-latest} + pull_policy: ${SIRIUS_IMAGE_PULL_POLICY:-always} + container_name: sirius-api + hostname: sirius-api + restart: unless-stopped + ports: + - "9001:9001" + environment: + - GO_ENV=${GO_ENV:-production} + - API_PORT=${API_PORT:-9001} + - CORS_ALLOWED_ORIGINS=${CORS_ALLOWED_ORIGINS:-*} + - POSTGRES_HOST=${POSTGRES_HOST:-sirius-postgres} + - POSTGRES_USER=${POSTGRES_USER:-postgres} + - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required for sirius-api. Run installer first using docker compose -f docker-compose.installer.yaml run --rm sirius-installer} + - POSTGRES_DB=${POSTGRES_DB:-sirius} + - POSTGRES_PORT=${POSTGRES_PORT:-5432} + - VALKEY_HOST=${VALKEY_HOST:-sirius-valkey} + - VALKEY_PORT=${VALKEY_PORT:-6379} + - RABBITMQ_URL=${RABBITMQ_URL:-amqp://guest:guest@sirius-rabbitmq:5672/} + - LOG_LEVEL=${LOG_LEVEL:-error} + - SIRIUS_API_KEY_FILE=${SIRIUS_API_KEY_FILE:-/run/secrets/sirius_api_key} + secrets: + - sirius_api_key + deploy: + resources: + limits: + memory: 1G + cpus: "1.0" + reservations: + memory: 256M + cpus: "0.25" + 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://127.0.0.1:9001/health"] + interval: 30s + timeout: 10s + retries: 3 + + sirius-engine: + image: ghcr.io/siriusscan/sirius-engine:${IMAGE_TAG:-latest} + pull_policy: ${SIRIUS_IMAGE_PULL_POLICY:-always} + container_name: sirius-engine + hostname: sirius-engine + restart: unless-stopped + cap_add: + - NET_RAW + ports: + - "5174:5174" + - "50051:50051" # Agent gRPC + environment: + - GO_ENV=${GO_ENV:-production} + - ENGINE_MAIN_PORT=${ENGINE_MAIN_PORT:-5174} + - GRPC_AGENT_PORT=${GRPC_AGENT_PORT:-50051} + - POSTGRES_HOST=${POSTGRES_HOST:-sirius-postgres} + - POSTGRES_USER=${POSTGRES_USER:-postgres} + - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required for sirius-engine. Run installer first using docker compose -f docker-compose.installer.yaml run --rm sirius-installer} + - POSTGRES_DB=${POSTGRES_DB:-sirius} + - POSTGRES_PORT=${POSTGRES_PORT:-5432} + - VALKEY_HOST=${VALKEY_HOST:-sirius-valkey} + - VALKEY_PORT=${VALKEY_PORT:-6379} + - RABBITMQ_URL=${RABBITMQ_URL:-amqp://guest:guest@sirius-rabbitmq:5672/} + - SIRIUS_API_URL=${SIRIUS_API_URL:-http://sirius-api:9001} + # Agent/scanner legacy name; always mirror SIRIUS_API_URL to avoid URL/key drift + - API_BASE_URL=${SIRIUS_API_URL:-http://sirius-api:9001} + - AGENT_ID=${AGENT_ID:-sirius-engine} + - HOST_ID=${HOST_ID:-sirius-engine} + - ENABLE_SCRIPTING=${ENABLE_SCRIPTING:-true} + - LOG_LEVEL=${LOG_LEVEL:-info} + - SIRIUS_API_KEY_FILE=${SIRIUS_API_KEY_FILE:-/run/secrets/sirius_api_key} + secrets: + - sirius_api_key + depends_on: + sirius-rabbitmq: + condition: service_healthy + sirius-postgres: + condition: service_healthy + sirius-valkey: + condition: service_healthy + sirius-api: + condition: service_healthy + healthcheck: + test: + [ + "CMD", + "bash", + "-lc", + "command -v psql >/dev/null && command -v curl >/dev/null && [ -r \"${SIRIUS_API_KEY_FILE:-}\" ] && echo > /dev/tcp/127.0.0.1/50051", + ] + interval: 30s + timeout: 10s + retries: 3 + deploy: + resources: + limits: + memory: 2G + cpus: "1.0" + reservations: + memory: 1G + cpus: "0.5" + +volumes: + postgres_data: + driver: local + valkey_data: + driver: local + rabbitmq_data: + driver: local + +secrets: + sirius_api_key: + file: ./secrets/sirius_api_key.txt + +networks: + default: + name: sirius + driver: bridge \ No newline at end of file diff --git a/docker-stack.swarm.yaml b/docker-stack.swarm.yaml new file mode 100644 index 0000000..85ffca7 --- /dev/null +++ b/docker-stack.swarm.yaml @@ -0,0 +1,66 @@ +version: "3.9" + +services: + sirius-postgres: + image: postgres:15-alpine + environment: + - POSTGRES_USER=postgres + - POSTGRES_DB=sirius + - POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password + secrets: + - postgres_password + volumes: + - postgres_data:/var/lib/postgresql/data + networks: + - sirius + + sirius-valkey: + image: valkey/valkey:latest + networks: + - sirius + + sirius-rabbitmq: + image: rabbitmq:3-management + networks: + - sirius + + sirius-api: + image: ghcr.io/siriusscan/sirius-api:${IMAGE_TAG:-latest} + environment: + - SIRIUS_API_KEY_FILE=${SIRIUS_API_KEY_FILE:-} + - SIRIUS_API_KEY=${SIRIUS_API_KEY:-} + networks: + - sirius + + sirius-ui: + image: ghcr.io/siriusscan/sirius-ui:${IMAGE_TAG:-latest} + environment: + - SIRIUS_API_KEY_FILE=${SIRIUS_API_KEY_FILE:-} + - SIRIUS_API_KEY=${SIRIUS_API_KEY:-} + - NEXTAUTH_SECRET=${NEXTAUTH_SECRET} + - INITIAL_ADMIN_PASSWORD=${INITIAL_ADMIN_PASSWORD} + ports: + - "3000:3000" + networks: + - sirius + + sirius-engine: + image: ghcr.io/siriusscan/sirius-engine:${IMAGE_TAG:-latest} + cap_add: + - NET_RAW + environment: + - SIRIUS_API_KEY_FILE=${SIRIUS_API_KEY_FILE:-} + - SIRIUS_API_KEY=${SIRIUS_API_KEY:-} + networks: + - sirius + +secrets: + postgres_password: + external: true + +volumes: + postgres_data: + +networks: + sirius: + driver: overlay diff --git a/documentation/OPERATIONS.md b/documentation/OPERATIONS.md new file mode 100644 index 0000000..14db1fa --- /dev/null +++ b/documentation/OPERATIONS.md @@ -0,0 +1,283 @@ +# Sirius Operations & Troubleshooting Runbook + +This document contains operational procedures, verification runbooks, and advanced troubleshooting for Sirius maintainers and operators. For getting started, see the [README](../README.md). + +## Clean Rollout Verification (Fresh Clone) + +Use this sequence to validate a production rollout from a fresh checkout. + +```bash +# 1) Start from a clean runtime state +docker compose down -v --remove-orphans + +# 2) Generate runtime secrets/config +docker compose -f docker-compose.installer.yaml run --rm sirius-installer --non-interactive --no-print-secrets + +# 3) Build from local source deterministically +docker compose -f docker-compose.yaml -f docker-compose.build.yaml up -d --build + +# 4) Confirm all services are healthy +docker compose ps + +# 5) Validate API auth behavior +curl -i http://localhost:9001/host/ # expect 401 (no key) +# Internal key: prefer the mounted secret file path inside the container, else env. +RUNTIME_KEY=$(docker exec sirius-api sh -lc 'if [ -r "${SIRIUS_API_KEY_FILE:-}" ]; then tr -d "\r\n" < "$SIRIUS_API_KEY_FILE"; elif [ -n "${SIRIUS_API_KEY:-}" ]; then printf %s "$SIRIUS_API_KEY"; fi') +curl -i -H "X-API-Key: ${RUNTIME_KEY}" http://localhost:9001/host/ # expect 200 + +# 6) Ensure startup regressions are absent +docker compose logs --no-color sirius-ui sirius-engine | rg -i "ENOTFOUND|permission denied|Failed to open log file" +``` + +If step 6 returns any lines, capture full logs and investigate before rollout. + +### Migrating existing `.env` deployments to file-based internal key + +If `docker compose up` errors on the `sirius_api_key` secret file, create it once from your current key (same value as `SIRIUS_API_KEY` in `.env`): + +```bash +mkdir -p secrets +printf '%s\n' "$SIRIUS_API_KEY" > secrets/sirius_api_key.txt +chmod 644 secrets/sirius_api_key.txt +``` + +Use **`644` (owner read/write, world read)** on `secrets/sirius_api_key.txt`, not `600`. Compose bind-mounts that file into the container as `/run/secrets/sirius_api_key`; **sirius-api** runs as a non-root UID (1001) and must be able to open it. `600` keeps “other” from reading, so you get `permission denied` on `/run/secrets/sirius_api_key` even when `SIRIUS_API_KEY` is set in `.env` (older API builds failed before env fallback; current **sirius-api** falls back to `SIRIUS_API_KEY` if the file is unreadable when the env is set). The installer writes this file as `644` by default. + +Re-run the installer to add `SIRIUS_API_KEY_FILE=/run/secrets/sirius_api_key` to `.env` if it is missing. Services accept **either** the file or `SIRIUS_API_KEY` during transition. + +## Release Image Propagation Verification + +Use this path to validate what operators experience when running pulled release images. + +```bash +# 1) Ensure local builds are not used +docker compose down -v --remove-orphans + +# 2) Generate runtime secrets/config +docker compose -f docker-compose.installer.yaml run --rm sirius-installer --non-interactive --no-print-secrets + +# 3) Validate the public release path for a published tag +export IMAGE_TAG=v0.4.1 +bash scripts/validate-public-compose-path.sh "$IMAGE_TAG" + +# 4) Verify running container image IDs match pulled release images +bash scripts/verify-release-images.sh +``` + +Expected result: the public-stack validator passes, all checks print a pass, and no service is running an unexpected local image. + +If `verify-ghcr-public-access.sh` reports `Anonymous access denied`, treat it as a registry visibility failure and stop before rollout. If it reports `Manifest missing`, the selected release tag was not published successfully. If `validate-public-compose-path.sh` fails after pull succeeds, investigate runtime contract drift before rollout. + +## Runtime Auth Contract Verification + +Use this check any time you run `reset`, switch between source/release mode, or see `401` and DB auth errors. + +```bash +bash scripts/verify-runtime-auth-contract.sh +``` + +The script assumes default Docker Compose container names (`sirius-ui`, `sirius-api`, `sirius-engine`, `sirius-postgres`) and curls the API at `http://localhost:9001`. For a different Compose project name (non-default `container_name` pattern), set: + +- `SIRIUS_CONTRACT_CONTAINER_UI`, `SIRIUS_CONTRACT_CONTAINER_API`, `SIRIUS_CONTRACT_CONTAINER_ENGINE`, `SIRIUS_CONTRACT_CONTAINER_POSTGRES` +- `SIRIUS_API_PUBLIC_URL` if the published API port differs + +See the header comment in `scripts/verify-runtime-auth-contract.sh`. + +If this script fails, do not start new scans until the mismatch is corrected. + +If `sirius-engine` is still restarting after this passes, verify runtime preflight tooling: + +```bash +docker exec sirius-engine sh -lc 'which psql && psql --version' +``` + +Expected result: prints `/usr/bin/psql` and a PostgreSQL client version. If missing, pull the corrected release image and recreate services. + +## Scan-Stuck Troubleshooting Runbook + +If scans complete in backend logs but UI remains non-terminal, run: + +```bash +# 0) Do NOT use command-scoped secret overrides for single-service restarts. +# Bad (causes key drift): SIRIUS_API_KEY=local-dev docker compose up -d sirius-engine +# Good: keep secrets in .env and recreate dependent services together. + +# 1) Verify API key contract is consistent across services +docker inspect sirius-ui --format '{{range .Config.Env}}{{println .}}{{end}}' | rg '^SIRIUS_API_KEY=' +docker inspect sirius-api --format '{{range .Config.Env}}{{println .}}{{end}}' | rg '^SIRIUS_API_KEY=' +docker inspect sirius-engine --format '{{range .Config.Env}}{{println .}}{{end}}' | rg '^SIRIUS_API_KEY=' + +# 2) Check engine scanner warnings and terminal status persistence +docker compose logs --no-color sirius-engine | rg -i "source-aware|status|completed|failed|warning|401" + +# 3) Check UI auth/session and API bridge logs +docker compose logs --no-color sirius-ui | rg -i "JWT_SESSION_ERROR|SIRIUS_API_KEY|fetch failed|401" + +# 4) Verify DB credential consistency from runtime containers +docker compose logs --no-color sirius-postgres sirius-api sirius-engine | rg -i "password authentication failed|database connection not available" + +# 5) Run contract verifier +bash scripts/verify-runtime-auth-contract.sh + +# 6) Verify templates endpoint is populated and not in missing/empty state +API_KEY=$(docker inspect sirius-api --format '{{range .Config.Env}}{{println .}}{{end}}' | rg '^SIRIUS_API_KEY=' | sed 's/^SIRIUS_API_KEY=//') +curl -s -D - -o /tmp/sirius-templates.json -H "X-API-Key: ${API_KEY}" http://localhost:9001/templates | rg '^HTTP/|^X-Sirius-Template-State' +python3 -c 'import json; print(len(json.load(open("/tmp/sirius-templates.json"))))' +``` + +If any command surfaces key/secret mismatch, re-run installer and restart: + +```bash +docker compose -f docker-compose.installer.yaml run --rm sirius-installer --non-interactive --no-print-secrets +docker compose up -d --force-recreate +``` + +Expected result for step 6: HTTP `200` and template count `>= 1`. If `X-Sirius-Template-State: missing` or `empty` appears, `sirius-engine` has not initialized template data yet. + +## Host Discovery Validation + +```bash +# Confirm compose renders successfully and includes NET_RAW +docker compose config | rg "NET_RAW" + +# Confirm scanner system template is canonicalized on startup +docker compose exec sirius-valkey valkey-cli GET template:quick | rg '"scan_types"' + +# Run a scan from UI/API, then verify queue consumers and scan state +docker compose exec sirius-rabbitmq rabbitmqctl list_queues name consumers messages_ready messages_unacknowledged | rg "scan|scan_control" +docker compose exec sirius-valkey valkey-cli GET currentScan +``` + +## Emergency Recovery + +### Complete System Reset + +```bash +# Stop all services +docker compose down + +# Remove all data (this deletes all scan data) +docker compose down -v + +# Clean Docker system +docker system prune -a -f + +# Recreate .env using installer (required after reset) +docker compose -f docker-compose.installer.yaml run --rm sirius-installer --non-interactive --no-print-secrets + +# Fresh source rebuild +docker compose -f docker-compose.yaml -f docker-compose.build.yaml up -d --build + +# Verify auth contract before interacting with UI +bash scripts/verify-runtime-auth-contract.sh +``` + +### Backup Current Data + +```bash +# Backup database +docker exec sirius-postgres pg_dump -U postgres sirius > backup.sql + +# Backup scan results directory +docker cp sirius-engine:/opt/sirius/ ./sirius-backup/ +``` + +## Common Issues + +### Container Issues + +**Services fail to start:** + +```bash +docker compose ps # Check service status +docker compose logs # View service logs +docker system df # Check disk space +``` + +**Infrastructure services don't start (dev overlay):** + +```bash +# The dev file is an OVERRIDE file, not standalone. +# Wrong: docker compose -f docker-compose.dev.yaml up -d +# Correct: +docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d +``` + +**Port already in use:** + +```bash +lsof -i :3000 +# Stop the conflicting process, then restart +``` + +### Scanner Issues + +**Nmap errors or scanning failures:** + +```bash +docker logs sirius-engine | grep -i nmap +docker exec sirius-engine nmap --version +docker restart sirius-engine +``` + +### Database Issues + +**Connection failures:** + +```bash +docker exec sirius-postgres pg_isready +docker logs sirius-postgres +docker exec sirius-postgres psql -U postgres -d sirius -c "SELECT version();" +``` + +### Message Queue Issues + +**RabbitMQ connectivity or schema errors:** + +```bash +docker exec sirius-rabbitmq rabbitmqctl status +docker exec sirius-rabbitmq rabbitmqctl list_queues +# For schema integrity failures, remove old volumes: +docker compose down -v && docker compose up -d +``` + +### Network Issues + +**Services can't communicate:** + +```bash +docker exec sirius-ui ping sirius-api +docker network inspect sirius +``` + +### GHCR Pull Issues + +**`docker compose pull` returns `unauthorized`:** + +```bash +bash scripts/verify-ghcr-public-access.sh "${IMAGE_TAG:-latest}" +``` + +Expected result: all compose-rendered GHCR refs pass anonymously. If the script reports `Anonymous access denied`, the package visibility contract is broken and the GHCR publicization workflow or token scope needs maintenance. + +**`docker compose pull` returns `manifest unknown` or `not found`:** + +```bash +bash scripts/verify-ghcr-public-access.sh "${IMAGE_TAG:-latest}" +``` + +Expected result: the script identifies the missing tag explicitly. Re-run the publishing workflow for the missing release tag before retrying deployment. + +### Maintainer: GHCR distribution checklist (public operators) + +A Git tag and GitHub Release do **not** create container tags on GHCR. Third parties need **all six** images (`sirius-ui`, `sirius-api`, `sirius-engine`, `sirius-postgres`, `sirius-rabbitmq`, `sirius-valkey`) published under the **same** semver tag, and each package must be **public** for anonymous `docker pull`. + +1. **Package visibility (per package)** — In [SiriusScan org packages](https://github.com/orgs/SiriusScan/packages), open each container image, set **Package settings** to **Public**, and link the package to this repository if needed. Partial visibility explains “works when logged in” vs failures for everyone else (see [issue #119](https://github.com/SiriusScan/Sirius/issues/119)). +2. **Publish semver tags** — Run [Publish Release Image Tags](https://github.com/SiriusScan/Sirius/actions/workflows/publish-release-image-tags.yml) with `source_tag` = the tag that exists on GHCR for all six (usually `latest`) and `target_tag` = the release (e.g. `v1.0.0`). Confirm the workflow run succeeds end-to-end. +3. **Verify anonymously** — From a machine **not** logged in to `ghcr.io`: + +```bash +bash scripts/verify-ghcr-public-access.sh v1.0.0 +``` + +CI runs the same check on every published release and weekly via [.github/workflows/verify-ghcr-release-tag.yml](.github/workflows/verify-ghcr-release-tag.yml). diff --git a/documentation/README.documentation-index.md b/documentation/README.documentation-index.md new file mode 100644 index 0000000..6a777e4 --- /dev/null +++ b/documentation/README.documentation-index.md @@ -0,0 +1,156 @@ +--- +title: "Documentation Index" +description: "Complete index of all documentation files in the Sirius project, organized by category and purpose" +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2026-02-22" +author: "Development Team" +tags: ["documentation", "index", "reference", "organization"] +categories: ["documentation", "reference"] +difficulty: "beginner" +prerequisites: [] +related_docs: [] +dependencies: [] +llm_context: "high" +search_keywords: + ["documentation", "index", "files", "organization", "reference"] +--- + +# Documentation Index + +This document provides a complete index of all documentation files in the Sirius project, organized by category and purpose. + +## Core Documentation + +### System Documentation + +- [ABOUT.documentation.md](dev/ABOUT.documentation.md) - Documentation standards and system overview +- [README.development.md](dev/README.development.md) - Development environment setup and workflow +- [README.developer-guide.md](dev/README.developer-guide.md) - Comprehensive developer guide for Sirius project +- [QUICK-REFERENCE.md](dev/QUICK-REFERENCE.md) - Quick reference guide for common operations +- [QUICKREF.template-types.md](dev/QUICKREF.template-types.md) - Quick reference for documentation template types +- [README.logging-conventions.md](dev/development/README.logging-conventions.md) - Structured logging conventions and standards +- [README.sirius-event-log.md](dev/development/README.sirius-event-log.md) - Sirius event logging system and event management +- [README.ui-style-guide.md](dev/development/README.ui-style-guide.md) - UI style guide and design system documentation + +### Contributing + +- [contributing.md](contributing.md) - Complete guide for contributing to Sirius Scan, including development setup and workflows + +## Architecture Documentation + +### System Architecture + +- [README.architecture.md](dev/architecture/README.architecture.md) - System architecture and component relationships +- [README.architecture-quick-reference.md](dev/architecture/README.architecture-quick-reference.md) - Concise architectural overview for LLM context +- [README.system-monitor.md](dev/architecture/README.system-monitor.md) - System monitoring architecture and implementation +- [README.administrator.md](dev/architecture/README.administrator.md) - Administrator service architecture and design +- [README.cicd.md](dev/architecture/README.cicd.md) - CI/CD pipeline architecture and workflows +- [README.go-api-sdk.md](dev/architecture/README.go-api-sdk.md) - Go API SDK architecture, design patterns, and integration guide +- [README.scanner-storage.md](dev/architecture/README.scanner-storage.md) - Scanner Valkey schema contract for templates and NSE scripts +- [README.auth-surface-matrix.md](dev/architecture/README.auth-surface-matrix.md) - Authentication and authorization policy matrix across API surfaces +- [ADR.startup-secrets-model.md](dev/architecture/ADR.startup-secrets-model.md) - Architectural decision record for installer-first startup and secrets model +- [ARCHITECTURE.nse-repository-management.md](dev/architecture/ARCHITECTURE.nse-repository-management.md) - NSE repository management architecture +- [README.docker-architecture.md](dev/architecture/README.docker-architecture.md) - Comprehensive Docker setup and container architecture +- [README.engine-component-pinning.md](dev/architecture/README.engine-component-pinning.md) - Authoritative model for pinning engine submodules and CI build-arg overrides + +## Application Documentation + +### Agent System + +- [README.agent-system.md](dev/apps/agent/README.agent-system.md) - Agent system architecture and design +- [README.agent-template-api.md](dev/apps/agent/README.agent-template-api.md) - API endpoints for managing agent vulnerability detection templates +- [README.agent-template-ui.md](dev/apps/agent/README.agent-template-ui.md) - User interface workflows for managing agent templates + +### Scanner + +- [README.scanner.md](dev/apps/scanner/README.scanner.md) - Scanner application documentation +- [ARCHITECTURE.scanner-data-flow.md](dev/apps/scanner/ARCHITECTURE.scanner-data-flow.md) - End-to-end scanner data flow (UI → ValKey → persistence) +- [ARCHITECTURE.sub-scans.md](dev/apps/scanner/ARCHITECTURE.sub-scans.md) - Sub-scan architecture (network/agent, progress, cancellation) +- [ARCHITECTURE.host-deduplication.md](dev/apps/scanner/ARCHITECTURE.host-deduplication.md) - Host deduplication and multi-source attribution + +## Operations Documentation + +### Git Operations + +- [README.git-operations.md](dev/operations/README.git-operations.md) - Git workflows and version control +- [README.api-key-operations.md](dev/operations/README.api-key-operations.md) - API key lifecycle and incident recovery runbook +- [README.release-closeout-v1.0.0.md](dev/operations/README.release-closeout-v1.0.0.md) - Final push, merge, and release acceptance evidence for Sirius v1.0.0 +- [README.maintainer-ops-issue-review.md](dev/operations/README.maintainer-ops-issue-review.md) - Label taxonomy, triage lifecycle, and ChatOps issue/PR review controls + +### Project Management + +- [README.new-project.md](dev/operations/README.new-project.md) - New project development workflow and structure +- [README.tasks.md](dev/operations/README.tasks.md) - Task management system and project tracking +- [startup-secrets-redesign-plan.md](dev-notes/startup-secrets-redesign-plan.md) - Detailed implementation plan for startup and secrets redesign + +### Deployment + +- [README.terraform-deployment.md](dev/operations/README.terraform-deployment.md) - Terraform-based deployment processes +- [README.docker-container-deployment.md](dev/deployment/README.docker-container-deployment.md) - Docker container deployment using prebuilt registry images +- [README.workflows.md](dev/deployment/README.workflows.md) - GitHub Actions workflow architecture and parallel build system + +### SDK Management + +- [README.sdk-releases.md](dev/operations/README.sdk-releases.md) - SDK release process and dependency management + +## Testing Documentation + +### Testing Philosophy + +- [ABOUT.testing.md](dev/test/ABOUT.testing.md) - Testing philosophy and approach for the Sirius project + +### Container Testing + +- [README.container-testing.md](dev/test/README.container-testing.md) - Container testing system and validation + +### Documentation Testing + +- [README.documentation-testing.md](dev/test/README.documentation-testing.md) - Documentation validation and linting + +### Testing Checklists + +- [CHECKLIST.testing-by-type.md](dev/test/CHECKLIST.testing-by-type.md) - Issue-type-specific testing checklists for thorough validation + +## AI and Rules Documentation + +### AI Rules + +- [ABOUT.ai-rules.md](dev/ai-rules/ABOUT.ai-rules.md) - AI development rules and guidelines +- [README.ai-identities.md](dev/ai-rules/README.ai-identities.md) - AI identity system and agent personas +- [README.playwright.md](dev/ai-rules/README.playwright.md) - Playwright browser testing guide for automated testing and validation + +## Template Documentation + +### Documentation Templates + +- [TEMPLATE.about.md](dev/templates/TEMPLATE.about.md) - Template for ABOUT documents +- [TEMPLATE.api.md](dev/templates/TEMPLATE.api.md) - Template for API documentation +- [TEMPLATE.architecture.md](dev/templates/TEMPLATE.architecture.md) - Template for architecture documentation +- [TEMPLATE.custom.md](dev/templates/TEMPLATE.custom.md) - Template for custom documents +- [TEMPLATE.documentation-standard.md](dev/templates/TEMPLATE.documentation-standard.md) - Standard documentation template +- [TEMPLATE.guide.md](dev/templates/TEMPLATE.guide.md) - Template for step-by-step guides +- [TEMPLATE.reference.md](dev/templates/TEMPLATE.reference.md) - Template for reference documentation +- [TEMPLATE.template.md](dev/templates/TEMPLATE.template.md) - Template for template documentation +- [TEMPLATE.troubleshooting.md](dev/templates/TEMPLATE.troubleshooting.md) - Template for troubleshooting guides + +## Usage + +This index serves as the central reference for all documentation in the Sirius project. Use it to: + +- **Find specific documentation** by category or purpose +- **Understand the documentation structure** and organization +- **Navigate between related documents** using the links provided +- **Ensure documentation completeness** by checking against this index + +## Maintenance + +This index should be updated whenever: + +- New documentation files are added +- Documentation files are moved or renamed +- Documentation categories are reorganized + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](dev/ABOUT.documentation.md)._ diff --git a/documentation/archive/DEVELOPER-DEPLOYMENT-GUIDE.md b/documentation/archive/DEVELOPER-DEPLOYMENT-GUIDE.md new file mode 100644 index 0000000..112e16e --- /dev/null +++ b/documentation/archive/DEVELOPER-DEPLOYMENT-GUIDE.md @@ -0,0 +1,536 @@ +# Sirius Developer Deployment Guide + +**Status**: Updated for Terminal Rework Integration +**Version**: 2.0 +**Last Updated**: Current + +## 🎯 Overview + +This guide provides comprehensive instructions for developers working on Sirius in different environments. After the terminal rework project, our Docker setup supports multiple deployment modes with flexible volume mounting for local development. + +## 📋 Prerequisites + +- Docker Engine 20.10.0+ +- Docker Compose V2 +- 4GB RAM minimum (8GB recommended for development) +- 10GB free disk space (20GB for full development setup) +- Git 2.0+ + +## 🚀 Quick Reference + +| Use Case | Command | Description | +| ------------------------- | -------------------------------------------------- | -------------------------------------------- | +| **End User** | `docker compose -f docker-compose.user.yaml up -d` | Clean production-like experience | +| **Standard Development** | `./scripts/dev-setup.sh start` | Default development with automatic overrides | +| **Extended Development** | `./scripts/dev-setup.sh start-extended` | Development with local repository mounts | +| **Setup Local Overrides** | `./scripts/dev-setup.sh init` | Create git-ignored local configuration | +| **Staging Deployment** | `./scripts/deploy.sh staging` | Deploy to staging environment | +| **Production Deployment** | `./scripts/deploy.sh production v1.2.3` | Deploy specific version to production | + +## 🏗️ Deployment Modes + +### 1. End User Mode (Recommended for Testing) + +**Purpose**: Clean, production-like environment without development complexity + +```bash +# Clone and start +git clone https://github.com/SiriusScan/Sirius.git +cd Sirius + +# Use simplified configuration +docker compose -f docker-compose.user.yaml up -d + +# Access application +open http://localhost:3000 +``` + +**What happens:** + +- Uses built-in repositories from Docker images +- No volume mounts +- Health checks enabled +- Optimized for stability + +### 2. Standard Development Mode (Default) + +**Purpose**: Development with automatic file watching and live reload + +```bash +# Clone and start +git clone https://github.com/SiriusScan/Sirius.git +cd Sirius + +# Standard development start +docker compose up -d + +# View logs +docker compose logs -f +``` + +**What happens:** + +- `docker-compose.override.yaml` automatically loaded +- Source code mounted for live reloading +- Development environment variables +- Debug logging enabled + +### 3. Extended Development Mode + +**Purpose**: Full development access to selected repositories with local volume mounts + +```bash +# 1. Set up repository structure (optional) +mkdir -p ../minor-projects +cd ../minor-projects + +# 2. Clone repositories you want to develop on +git clone https://github.com/SiriusScan/go-api.git +git clone https://github.com/SiriusScan/app-scanner.git +git clone https://github.com/SiriusScan/app-terminal.git +git clone https://github.com/SiriusScan/app-agent.git + +# 3. Return to main directory +cd ../Sirius + +# 4. Set up local development overrides +./scripts/dev-setup.sh init + +# 5. Edit docker-compose.local.yaml to enable desired repositories +nano docker-compose.local.yaml + +# 6. Start with extended development setup +./scripts/dev-setup.sh start-extended +``` + +**What happens:** + +- Uses `docker-compose.local.yaml` (git-ignored) for local repository mounts +- Live code changes reflected immediately in mounted repositories +- Original `docker-compose.override.yaml` remains clean for commits +- Full development environment with all tools + +### 4. Local Development Configuration + +**Purpose**: Safe local customization without affecting the repository + +The new local override system prevents accidental commits of development configuration: + +- `docker-compose.override.yaml` - **Committed to Git**: Contains safe defaults with commented examples +- `docker-compose.local.yaml` - **Git-ignored**: Your personal development overrides +- `docker-compose.local.example.yaml` - **Committed to Git**: Template for creating local overrides + +**Setting up local overrides:** + +```bash +# Initialize local development configuration +./scripts/dev-setup.sh init + +# Edit your local overrides (this file is git-ignored) +nano docker-compose.local.yaml + +# Uncomment the repositories you want to mount locally +# Example: +# services: +# sirius-engine: +# volumes: +# - ../minor-projects/app-agent:/app-agent +# - ../minor-projects/app-scanner:/app-scanner + +# Start with your local overrides +./scripts/dev-setup.sh start-extended +``` + +**Benefits:** + +- ✅ Never accidentally commit local development configuration +- ✅ Each developer can have different local setups +- ✅ Clean repository with predictable CI/CD +- ✅ Easy onboarding with helper scripts + +## 📂 Repository Structure + +### Current Structure + +``` +Sirius/ # Main UI and orchestration +├── sirius-ui/ # Frontend (Next.js/React) +├── sirius-api/ # Backend API (Go) +├── sirius-engine/ # Scanning engine (Go) +├── docker-compose.yaml # Base configuration +├── docker-compose.override.yaml # Development overrides +├── docker-compose.user.yaml # Simplified user setup +├── docker-compose.staging.yaml # Staging configuration +└── docker-compose.production.yaml # Production configuration +``` + +### Extended Development Structure + +``` +Projects/ +├── Sirius/ # Main repository +└── minor-projects/ # Additional repositories (optional) + ├── go-api/ # Shared Go API library + ├── app-scanner/ # Scanning modules + ├── app-terminal/ # Terminal backend + └── app-agent/ # Agent communication +``` + +## 🔧 Service Architecture + +| Service | Purpose | Port(s) | Volume Mounts | +| ------------------- | ------------------ | ----------- | --------------------------- | +| **sirius-ui** | Frontend interface | 3000 | Source code in dev mode | +| **sirius-api** | Backend API | 9001 | Source code in dev mode | +| **sirius-engine** | Scanning engine | 5174, 50051 | Multiple repo mounts in dev | +| **sirius-postgres** | Database | 5432 | Data persistence | +| **sirius-rabbitmq** | Message queue | 5672, 15672 | Configuration | +| **sirius-valkey** | Key-value store | 6379 | Data persistence | + +## 📄 Configuration Files Deep Dive + +### docker-compose.yaml (Base Configuration) + +- Production-ready defaults +- Environment variables with fallbacks +- Resource limits and health checks +- Used by all deployment modes + +### docker-compose.override.yaml (Development) + +Automatically loaded in development mode, provides: + +```yaml +services: + sirius-ui: + target: development # Use development Docker stage + volumes: + - ./sirius-ui/src:/app/src # Live source code + - ./sirius-ui/public:/app/public # Static assets + - node_modules:/app/node_modules # Preserve container modules + environment: + - NODE_ENV=development + - NEXT_TELEMETRY_DISABLED=1 + + sirius-engine: + volumes: + # Optional: Uncomment repositories you want to develop + - ../minor-projects/app-agent:/app-agent + - ../minor-projects/app-scanner:/app-scanner + - ../minor-projects/app-terminal:/app-terminal +``` + +### docker-compose.user.yaml (Simplified) + +Clean configuration for end users: + +- No development complexity +- Built-in repositories only +- Health checks enabled +- Optimized for stability + +## 🛠️ Development Workflow + +### Starting Development Session + +1. **Check Current Status** + + ```bash + docker compose ps + docker compose logs -f sirius-ui + ``` + +2. **Choose Your Development Level** + + - **UI Only**: Standard mode is sufficient + - **Backend API**: Standard mode is sufficient + - **Engine/Scanner**: Consider extended mode + +3. **Enable Repository Mounts** (if needed) + + ```bash + # Edit override file + nano docker-compose.override.yaml + + # Uncomment desired volume mounts + # - ../minor-projects/app-scanner:/app-scanner + + # Restart to apply changes + docker compose down + docker compose up -d --build + ``` + +### Working with Terminal Features + +After the terminal rework, several new components require special attention: + +#### Key Files Modified + +- `sirius-ui/src/components/DynamicTerminal.tsx` - Main terminal interface +- `sirius-ui/src/components/agent/AgentCard.tsx` - Agent display cards +- `sirius-ui/src/server/api/routers/agent.ts` - Agent data integration + +#### Development Dependencies + +The terminal rework added `tsx` for TypeScript execution: + +```json +{ + "devDependencies": { + "tsx": "^4.19.4" + } +} +``` + +#### Database Integration + +Terminal now uses real PostgreSQL data: + +- Agent information from database +- Real-time status updates +- Enhanced command responses + +### Live Development Features + +| Component | Live Reload | Notes | +| ------------------- | ----------- | ----------------------- | +| **UI Changes** | ✅ Instant | Hot reload with Next.js | +| **API Changes** | ✅ Fast | Go air tool rebuilds | +| **Engine Changes** | ✅ Fast | Go air tool rebuilds | +| **Database Schema** | 🔄 Manual | Requires migration | + +## 🚢 Production Deployment + +### Staging Deployment + +```bash +# Deploy latest to staging +./scripts/deploy.sh staging + +# Deploy specific version +./scripts/deploy.sh staging v1.2.3 + +# Check status +docker compose -f docker-compose.yaml -f docker-compose.staging.yaml ps +``` + +### Production Deployment + +```bash +# Deploy specific version (required) +./scripts/deploy.sh production v1.2.3 + +# Check deployment +docker compose -f docker-compose.yaml -f docker-compose.production.yaml ps +``` + +### Environment Configuration + +No separate environment files needed! All environments use sensible defaults: + +```bash +# Production with defaults +./scripts/deploy.sh production v1.2.3 + +# Override specific variables +export POSTGRES_PASSWORD=secure-production-password +export NEXTAUTH_SECRET=your-production-secret +./scripts/deploy.sh production v1.2.3 + +# Check what variables you can override +grep -E '\$\{.*:-.*\}' docker-compose.production.yaml +``` + +## 🐛 Troubleshooting + +### Common Issues After Terminal Rework + +#### 1. Terminal Commands Not Working + +```bash +# Check UI container logs +docker compose logs -f sirius-ui + +# Verify database connection +docker compose exec sirius-postgres psql -U postgres -d sirius -c "\dt" + +# Check agent data +docker compose exec sirius-postgres psql -U postgres -d sirius -c "SELECT * FROM agents LIMIT 5;" +``` + +#### 2. Volume Mount Issues + +```bash +# Check what's mounted +docker compose exec sirius-engine ls -la /app-agent +docker compose exec sirius-engine ls -la /app-scanner + +# Verify mount points +docker inspect sirius-engine | grep -A 10 "Mounts" +``` + +#### 3. Build Failures + +```bash +# Clean rebuild +docker compose down -v +docker system prune -f +docker compose up -d --build --force-recreate + +# Check build logs +docker compose logs sirius-ui +docker compose logs sirius-engine +``` + +#### 4. Database Connection Issues + +```bash +# Check database status +docker compose exec sirius-postgres pg_isready -U postgres + +# Reset database (development only) +docker compose down +docker volume rm sirius_postgres_data +docker compose up -d +``` + +### Performance Optimization + +#### Development Performance + +```bash +# Use BuildKit for faster builds +export DOCKER_BUILDKIT=1 +export COMPOSE_DOCKER_CLI_BUILD=1 + +# Prune unused images +docker image prune -f + +# Monitor resource usage +docker stats +``` + +#### Memory Management + +```bash +# Check container memory usage +docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" + +# Adjust memory limits in compose files if needed +``` + +## 📊 Monitoring and Logs + +### Log Access + +```bash +# All services +docker compose logs -f + +# Specific service +docker compose logs -f sirius-ui + +# Last 100 lines +docker compose logs --tail=100 sirius-engine + +# Follow logs with timestamps +docker compose logs -f -t sirius-api +``` + +### Health Checks + +```bash +# Check service health +docker compose ps + +# Manual health checks +curl http://localhost:3000/api/health +curl http://localhost:9001/health +curl http://localhost:5174/health +``` + +### Performance Monitoring + +```bash +# Container resource usage +docker stats + +# Disk usage +docker system df + +# Network inspection +docker network ls +docker network inspect sirius +``` + +## 🔄 Migration Guide + +### From Previous Setup + +If you're upgrading from an older setup: + +1. **Backup Data** + + ```bash + docker compose exec sirius-postgres pg_dump -U postgres sirius > backup.sql + ``` + +2. **Update Configuration** + + ```bash + git pull origin main + docker compose down + docker compose up -d --build + ``` + +3. **Verify Terminal Features** + - Access http://localhost:3000 + - Test terminal commands: `help`, `agents`, `status` + - Verify agent data appears correctly + +### Breaking Changes + +- **Terminal Interface**: Complete rework requires browser refresh +- **Database Schema**: New agent tables and relationships +- **API Endpoints**: Enhanced agent data endpoints + +## 📝 Best Practices + +### Development + +- Use standard mode for UI/API development +- Only enable repository mounts for components you're actively developing +- Regularly pull latest changes from dependent repositories +- Monitor container resource usage during development + +### Deployment + +- Always use specific version tags for production +- Test in staging before production deployment +- Keep environment files secure and version controlled separately +- Monitor logs during and after deployment + +### Maintenance + +- Regularly update base images +- Prune unused Docker resources +- Backup database before major updates +- Document any custom configuration changes + +--- + +## 🚀 Getting Started Checklist + +- [ ] Clone main repository +- [ ] Choose deployment mode based on development needs +- [ ] Start with `docker compose up -d` for standard development +- [ ] Access web interface at http://localhost:3000 +- [ ] Test terminal functionality (`help`, `agents`, `status`) +- [ ] Enable additional repository mounts if needed +- [ ] Set up staging/production environments when ready + +For additional help, see: + +- [Main README](../README.md) +- [Deployment Strategy](./README.deployment-strategy.md) +- [Terminal Rework Handoff](./dev-notes/TERMINAL-REWORK-HANDOFF.md) diff --git a/documentation/archive/DOCKER-DEPLOYMENT-SUMMARY.md b/documentation/archive/DOCKER-DEPLOYMENT-SUMMARY.md new file mode 100644 index 0000000..e46ac8a --- /dev/null +++ b/documentation/archive/DOCKER-DEPLOYMENT-SUMMARY.md @@ -0,0 +1,117 @@ +# Docker Deployment Quick Reference + +**Status**: Post-Terminal Rework +**Updated**: Current + +## 🚀 TL;DR - Quick Commands + +```bash +# End User (Clean, Simple) +docker compose -f docker-compose.user.yaml up -d + +# Standard Development (Recommended) +docker compose up -d + +# Extended Development (All Repositories) +# 1. Clone repos to ../minor-projects/ +# 2. Edit docker-compose.override.yaml +# 3. docker compose up -d --build + +# Production +./scripts/deploy.sh production v1.2.3 + +# Staging +./scripts/deploy.sh staging +``` + +## 📊 Deployment Mode Matrix + +| Mode | File | Use Case | Volume Mounts | Performance | +| ---------------- | -------------------------- | ------------------ | ------------- | ----------- | +| **End User** | `docker-compose.user.yaml` | Testing, Demo | None | 🟢 Fast | +| **Standard Dev** | Default | UI/API Development | UI Source | 🟡 Medium | +| **Extended Dev** | Override Enabled | Engine Development | All Repos | 🔴 Slow | +| **Staging** | `staging.yaml` | Pre-production | None | 🟢 Fast | +| **Production** | `production.yaml` | Live Deployment | None | 🟢 Fast | + +## 🔧 Service Status Check + +```bash +# Quick health check +docker compose ps + +# Service logs +docker compose logs -f sirius-ui +docker compose logs -f sirius-engine + +# Terminal functionality test +curl http://localhost:3000 +# Then test: help, agents, status commands +``` + +## 📁 Repository Structure + +``` +📦 Your Development Setup +├── 🗂️ Sirius/ # Main repo (required) +│ ├── sirius-ui/ # Frontend +│ ├── sirius-api/ # Backend +│ ├── sirius-engine/ # Engine +│ └── docker-compose.*.yaml # All configs +└── 🗂️ minor-projects/ # Extended dev (optional) + ├── go-api/ # Shared library + ├── app-scanner/ # Scanner modules + ├── app-terminal/ # Terminal backend + └── app-agent/ # Agent system +``` + +## ⚡ Quick Troubleshooting + +```bash +# Reset everything (development) +docker compose down -v +docker system prune -f +docker compose up -d --build + +# Check terminal rework features +docker compose exec sirius-postgres psql -U postgres -d sirius -c "SELECT COUNT(*) FROM agents;" + +# Volume mount verification +docker compose exec sirius-engine ls -la /app-agent +``` + +## 🎯 Development Workflow + +1. **Choose your mode** based on what you're developing +2. **Start services** with appropriate compose file +3. **Verify functionality** - especially terminal commands +4. **Enable repo mounts** only for active development +5. **Monitor resources** - extended mode uses more CPU/memory + +## 🚨 Post-Terminal Rework Notes + +- **Database Integration**: Terminal now uses real PostgreSQL data +- **New Dependencies**: `tsx` added for TypeScript execution +- **Enhanced Commands**: `help`, `agents`, `status` with rich formatting +- **Real-time Updates**: Agent data refreshes automatically + +## 📝 Environment Variables + +All compose files have sensible defaults. Override as needed: + +```bash +# Production overrides +export POSTGRES_PASSWORD=secure-password +export NEXTAUTH_SECRET=your-secret-key +export NEXTAUTH_URL=https://yourdomain.com + +# Staging overrides +export NEXTAUTH_URL=https://staging.yourdomain.com + +# Check available variables +grep -E '\$\{.*:-.*\}' docker-compose.production.yaml +``` + +--- + +**For detailed instructions**: See [Developer Deployment Guide](./DEVELOPER-DEPLOYMENT-GUIDE.md) diff --git a/documentation/archive/DOCKER-IMPLEMENTATION-DOCUMENTATION.md b/documentation/archive/DOCKER-IMPLEMENTATION-DOCUMENTATION.md new file mode 100644 index 0000000..81fe54d --- /dev/null +++ b/documentation/archive/DOCKER-IMPLEMENTATION-DOCUMENTATION.md @@ -0,0 +1,910 @@ +# Docker Implementation Documentation + +## Table of Contents + +1. [Overview](#overview) +2. [Architecture Overview](#architecture-overview) +3. [Docker Files Structure](#docker-files-structure) +4. [Docker Compose Files](#docker-compose-files) +5. [Development vs Production Modes](#development-vs-production-modes) +6. [Essential Docker Commands](#essential-docker-commands) +7. [Environment Variables](#environment-variables) +8. [Volume Mounts and Data Persistence](#volume-mounts-and-data-persistence) +9. [Networking](#networking) +10. [Development Workflow](#development-workflow) +11. [Troubleshooting](#troubleshooting) +12. [Performance Optimization](#performance-optimization) +13. [Security Considerations](#security-considerations) +14. [Monitoring and Logging](#monitoring-and-logging) +15. [Deployment Scenarios](#deployment-scenarios) +16. [Best Practices](#best-practices) +17. [Common Development Issues and Solutions](#common-development-issues-and-solutions) +18. [Development Tips and Tricks](#development-tips-and-tricks) +19. [Performance Monitoring](#performance-monitoring) +20. [Additional Resources](#additional-resources) + +## Overview + +Sirius uses a comprehensive Docker-based development and deployment environment with multiple services orchestrated through Docker Compose. This documentation provides a complete guide to understanding and working with the Docker ecosystem. + +## Architecture Overview + +The Sirius platform consists of multiple containerized services: + +- **sirius-ui**: Next.js frontend application +- **sirius-api**: Go-based REST API server +- **sirius-engine**: Multi-service container (scanner, terminal, agent) +- **sirius-postgres**: PostgreSQL database for vulnerability data +- **sirius-valkey**: Redis-compatible cache +- **sirius-rabbitmq**: Message queue for inter-service communication + +## Docker Files Structure + +### Core Dockerfile Locations + +#### 1. `sirius-ui/Dockerfile` + +**Purpose**: Builds the Next.js frontend application with development and production stages. + +**Key Features**: + +- Multi-stage build (development/production) +- Node.js 20 Alpine base +- Hot reload support in development +- SQLite database for authentication +- Volume mounts for live code reloading + +```dockerfile +# Development stage with hot reload +FROM node:20-alpine AS development +# Production stage with optimized build +FROM node:20-alpine AS production +``` + +#### 2. `sirius-api/Dockerfile` + +**Purpose**: Builds the Go REST API server. + +**Key Features**: + +- Go 1.24 base image +- Single-stage build for simplicity +- Exposes port 9001 +- Connects to PostgreSQL and RabbitMQ + +#### 3. `sirius-engine/Dockerfile` + +**Purpose**: Multi-stage, multi-service container for scanner, terminal, and agent services. + +**Key Features**: + +- **Builder stage**: Clones and builds all Go services from GitHub +- **Development stage**: Full Go toolchain with live reloading via `air` +- **Production stage**: Optimized runtime with built binaries + +**Services Built**: + +- Scanner service (app-scanner) +- Terminal service (app-terminal) +- Agent service (app-agent) +- Go API (go-api) +- NSE scripts (sirius-nse) + +**Build Arguments**: + +```dockerfile +ARG GO_API_COMMIT_SHA=main +ARG APP_SCANNER_COMMIT_SHA=main +ARG APP_TERMINAL_COMMIT_SHA=main +ARG SIRIUS_NSE_COMMIT_SHA=main +ARG APP_AGENT_COMMIT_SHA=main +``` + +## Docker Compose Files + +### 1. `docker-compose.yaml` (Base Configuration) + +**Purpose**: Main Docker Compose configuration defining all services. + +**Services Defined**: + +- `sirius-ui`: Frontend (port 3000) +- `sirius-api`: Backend API (port 9001) +- `sirius-engine`: Multi-service engine (ports 5174, 50051) +- `sirius-postgres`: Database (port 5432) +- `sirius-valkey`: Cache (port 6379) +- `sirius-rabbitmq`: Message queue (ports 5672, 15672) + +### 2. `docker-compose.override.yaml` (Development Override) + +**Purpose**: Automatic development overrides loaded by Docker Compose. + +**Key Modifications**: + +- Targets development stages in Dockerfiles +- Volume mounts for live code reloading +- Development environment variables +- SQLite database for UI authentication + +**Important Volume Mounts** (Commented by default): + +```yaml +# Development volume mounts (require ../minor-projects/ structure): +# - ../minor-projects/app-agent:/app-agent +# - ../minor-projects/app-scanner:/app-scanner +# - ../minor-projects/app-terminal:/app-terminal +``` + +### 3. `docker-compose.production.yaml` (Production Configuration) + +**Purpose**: Production deployment with optimized settings. + +**Key Features**: + +- Production Docker image stages +- No volume mounts (immutable containers) +- Production environment variables +- Resource limits and health checks + +### 4. `docker-compose.staging.yaml` (Staging Configuration) + +**Purpose**: Staging environment for testing production-like deployments. + +### 5. `docker-compose.user.yaml` (User Customization) + +**Purpose**: User-specific overrides and customizations. + +### 6. `docker-compose.prod.yml` (Legacy Production) + +**Purpose**: Alternative production configuration (legacy). + +### 7. `docker-compose.local.example.yaml` (Example Configuration) + +**Purpose**: Example configuration template for local development. + +## Development vs Production Modes + +### Development Mode + +**Container Stages**: `development` +**Code Source**: + +- Volume mounts from local directories (when enabled) +- GitHub cloned code (fallback) + +**Features**: + +- Live code reloading with `air` +- Full Go toolchain available +- Development environment variables +- Debug logging enabled + +**Volume Mount Structure**: + +``` +Local Directory → Container Path → Purpose +./sirius-ui/src → /app/src → Live UI code +./sirius-engine → /engine → Engine scripts +../minor-projects/app-scanner → /app-scanner → Scanner code (optional) +``` + +### Production Mode + +**Container Stages**: `runtime`/`production` +**Code Source**: Pre-built binaries from GitHub + +**Features**: + +- Optimized container images +- Pre-compiled binaries +- Production environment variables +- Minimal attack surface + +## Essential Docker Commands + +### Container Management + +```bash +# Start all services +docker compose up -d + +# Start with fresh build +docker compose up -d --build + +# Stop all services +docker compose down + +# Restart specific service +docker restart sirius-engine + +# View all running containers +docker ps + +# View container logs +docker logs sirius-engine --tail 50 -f + +# Follow logs in real-time +docker logs -f sirius-engine +``` + +### Container Statistics and Monitoring + +```bash +# Real-time container resource usage +docker stats + +# Specific container stats +docker stats sirius-engine + +# Container resource usage with formatting +docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}" + +# Disk usage by Docker +docker system df + +# Clean up unused containers, networks, images +docker system prune +``` + +### Container Access and Debugging + +```bash +# Execute shell in running container +docker exec -it sirius-engine /bin/bash + +# Execute specific command +docker exec sirius-engine ps aux + +# Copy files to/from container +docker cp file.txt sirius-engine:/tmp/ +docker cp sirius-engine:/tmp/file.txt ./ + +# Inspect container configuration +docker inspect sirius-engine + +# View container filesystem changes +docker diff sirius-engine +``` + +### Service-Specific Commands + +```bash +# Check scanner service logs +docker exec sirius-engine grep -A 10 "Scanner" /engine/logs/scanner.log + +# Test Nmap in scanner container +docker exec sirius-engine nmap --version + +# Check agent server status +docker exec sirius-engine ps aux | grep agent + +# Access RabbitMQ management +open http://localhost:15672 # guest/guest + +# Check PostgreSQL connection +docker exec sirius-postgres psql -U postgres -d sirius -c "\l" +``` + +### Build and Image Management + +```bash +# Build specific service +docker compose build sirius-engine + +# Build with no cache +docker compose build --no-cache sirius-ui + +# Pull latest images +docker compose pull + +# Remove unused images +docker image prune + +# View image layers +docker history sirius-engine:latest +``` + +## Environment Variables + +### Global Environment Variables + +```bash +# Set development mode +export GO_ENV=development +export NODE_ENV=development + +# Database configuration +export POSTGRES_HOST=sirius-postgres +export POSTGRES_USER=postgres +export POSTGRES_PASSWORD=postgres +export POSTGRES_DB=sirius + +# Queue configuration +export RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/ + +# Cache configuration +export VALKEY_HOST=sirius-valkey +export VALKEY_PORT=6379 +``` + +### Service-Specific Environment Variables + +#### sirius-ui + +```bash +DATABASE_URL=file:./dev.db # SQLite for development +NEXTAUTH_SECRET=development-secret-key +NEXTAUTH_URL=http://localhost:3000 +``` + +#### sirius-engine + +```bash +ENGINE_MAIN_PORT=5174 +GRPC_AGENT_PORT=50051 +GO_ENV=development +``` + +## Volume Mounts and Data Persistence + +### Development Volume Mounts + +When `docker-compose.override.yaml` volume mounts are enabled: + +```yaml +volumes: + # UI live reloading + - ./sirius-ui/src:/app/src + - ./sirius-ui/public:/app/public + + # Engine source code (requires ../minor-projects/ structure) + - ../minor-projects/app-scanner:/app-scanner + - ../minor-projects/app-terminal:/app-terminal + - ../minor-projects/app-agent:/app-agent + + # Preserve node_modules from container + - node_modules:/app/node_modules +``` + +### Data Persistence + +```yaml +volumes: + # Database data + postgres_data:/var/lib/postgresql/data + + # RabbitMQ data + rabbitmq_data:/var/lib/rabbitmq + + # Cache data + valkey_data:/data +``` + +## Networking + +### Internal Network Communication + +Services communicate through Docker's internal network: + +``` +sirius-ui → sirius-api (http://sirius-api:9001) +sirius-api → sirius-postgres (sirius-postgres:5432) +sirius-api → sirius-rabbitmq (sirius-rabbitmq:5672) +sirius-engine → sirius-rabbitmq (sirius-rabbitmq:5672) +``` + +### External Port Mapping + +``` +Host Port → Container Port → Service +3000 → 3000 → sirius-ui (Next.js) +9001 → 9001 → sirius-api (Go API) +5174 → 5174 → sirius-engine (Engine) +50051 → 50051 → sirius-engine (gRPC Agent) +5432 → 5432 → sirius-postgres +6379 → 6379 → sirius-valkey +5672 → 5672 → sirius-rabbitmq (AMQP) +15672 → 15672 → sirius-rabbitmq (Management UI) +``` + +## Development Workflow + +### 1. Initial Setup + +```bash +# Clone repository +git clone +cd Sirius + +# Start development environment +docker compose up -d --build + +# Verify all services are running +docker ps +``` + +### 2. Development with Live Reload + +For UI development (works out of the box): + +```bash +# Edit files in sirius-ui/src/ +# Changes automatically reload in browser +``` + +For engine development (requires setup): + +```bash +# Ensure you have ../minor-projects/ structure +# Uncomment volume mounts in docker-compose.override.yaml +# Restart containers +docker compose down && docker compose up -d +``` + +### 3. Testing Changes + +```bash +# Check service logs +docker logs sirius-engine -f + +# Test specific functionality +docker exec sirius-engine nmap --version + +# Access services +open http://localhost:3000 # UI +open http://localhost:15672 # RabbitMQ Management +``` + +## Troubleshooting + +### Common Issues and Solutions + +#### 1. Container Won't Start + +```bash +# Check container logs +docker logs sirius-engine --tail 100 + +# Check if ports are available +netstat -tuln | grep 3000 + +# Restart with fresh build +docker compose down && docker compose up -d --build +``` + +#### 2. Volume Mount Issues + +```bash +# Verify volume mount paths exist +ls -la ../minor-projects/app-scanner + +# Check container filesystem +docker exec sirius-engine ls -la /app-scanner-src + +# Temporarily copy files to container +docker cp local-file.go sirius-engine:/app-scanner-src/file.go +``` + +#### 3. Network Connectivity Issues + +```bash +# Test internal network connectivity +docker exec sirius-ui ping sirius-api + +# Check exposed ports +docker port sirius-engine + +# Verify service discovery +docker exec sirius-api nslookup sirius-postgres +``` + +#### 4. Database Connection Issues + +```bash +# Check PostgreSQL status +docker exec sirius-postgres pg_isready + +# Test database connection +docker exec sirius-postgres psql -U postgres -d sirius -c "SELECT version();" + +# Check database logs +docker logs sirius-postgres --tail 50 +``` + +#### 5. RabbitMQ Queue Issues + +```bash +# Check RabbitMQ status +docker exec sirius-rabbitmq rabbitmqctl status + +# List queues +docker exec sirius-rabbitmq rabbitmqctl list_queues + +# Access management interface +open http://localhost:15672 # guest/guest +``` + +### Development Mode Specific Issues + +#### Air Live Reload Not Working + +```bash +# Check if air is installed +docker exec sirius-engine which air + +# Restart with development stage +docker compose build --target development sirius-engine +docker restart sirius-engine +``` + +#### Source Code Not Updating + +```bash +# Verify volume mounts are enabled +docker inspect sirius-engine | grep Mounts -A 20 + +# Copy files manually for testing +docker cp app-scanner/file.go sirius-engine:/app-scanner-src/ +``` + +## Performance Optimization + +### Resource Limits + +```yaml +services: + sirius-engine: + deploy: + resources: + limits: + cpus: "2.0" + memory: 2G + reservations: + memory: 1G +``` + +### Build Optimization + +```bash +# Use BuildKit for faster builds +export DOCKER_BUILDKIT=1 + +# Build with cache mount +docker compose build --progress=plain + +# Multi-platform builds +docker buildx build --platform linux/amd64,linux/arm64 . +``` + +## Security Considerations + +### Container Security + +```bash +# Run containers as non-root user (production) +USER sirius + +# Scan images for vulnerabilities +docker scout cves sirius-engine:latest + +# Limit container capabilities +security_opt: + - no-new-privileges:true +``` + +### Network Security + +```bash +# Use internal networks +networks: + internal: + driver: bridge + internal: true +``` + +### Secrets Management + +```bash +# Use Docker secrets for sensitive data +echo "sensitive_password" | docker secret create db_password - + +# Mount secrets in compose +secrets: + - db_password +``` + +## Monitoring and Logging + +### Container Health Checks + +```yaml +healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"] + interval: 30s + timeout: 10s + retries: 3 +``` + +### Centralized Logging + +```bash +# View aggregated logs +docker compose logs -f + +# Filter logs by service +docker compose logs -f sirius-engine + +# Export logs to file +docker compose logs > sirius-logs.txt +``` + +### Metrics Collection + +```bash +# Prometheus metrics endpoint +curl http://localhost:9001/metrics + +# Container metrics +docker stats --format "json" > container-metrics.json +``` + +## Deployment Scenarios + +### Local Development + +- Use `docker-compose.override.yaml` +- Volume mounts enabled +- Development image stages + +### Testing/CI + +- Use `docker-compose.yaml` only +- Fresh builds each time +- Production image stages + +### Staging + +- Use `docker-compose.staging.yaml` +- Production-like configuration +- External databases + +### Production + +- Use `docker-compose.production.yaml` +- Optimized images +- External services +- Resource limits +- Health checks + +## Best Practices + +### Development + +1. Use `.dockerignore` to exclude unnecessary files +2. Enable volume mounts only when needed +3. Use development image stages for debugging +4. Keep containers stateless +5. Use named volumes for data persistence + +### Production + +1. Use multi-stage builds for smaller images +2. Run containers as non-root users +3. Implement proper health checks +4. Use resource limits +5. Enable logging and monitoring + +### Maintenance + +1. Regularly update base images +2. Clean up unused containers and images +3. Monitor resource usage +4. Backup persistent volumes +5. Test disaster recovery procedures + +## Common Development Issues and Solutions + +### Issue 1: Development Volume Mounts Not Working + +**Problem**: Local code changes not reflected in containers during development. + +**Root Cause**: Volume mounts in `docker-compose.override.yaml` are commented out by default. + +**Solution**: + +1. Ensure `../minor-projects/` directory structure exists with individual repositories +2. Uncomment volume mounts in `docker-compose.override.yaml`: + +```yaml +# Uncomment these lines for local development: +- ../minor-projects/app-agent:/app-agent +- ../minor-projects/app-scanner:/app-scanner +- ../minor-projects/app-terminal:/app-terminal +``` + +3. Restart containers: `docker compose down && docker compose up -d` + +**Alternative**: Copy files directly to container for testing: + +```bash +docker cp local-file.go sirius-engine:/app-scanner-src/file.go +``` + +### Issue 2: Container Using Wrong Build Stage + +**Problem**: Development containers running production binaries. + +**Root Cause**: Docker not building development stage correctly. + +**Solution**: + +```bash +# Force rebuild with development stage +docker compose down +docker compose up -d --build + +# Verify correct stage is running +docker exec sirius-engine which air # Should return /root/go/bin/air +``` + +### Issue 3: Nmap Configuration Errors + +**Problem**: + +- "Duplicate port number(s) specified" warning +- "NSE: failed to initialize the script engine: no path to file/directory: scripts/args.txt" + +**Root Cause**: + +- Port specification contained overlapping ranges: `"21-25,80,135,139,443,445,3389,1-1000"` +- Development args file path missing from search locations + +**Solution Applied**: + +1. Fixed port specification to `"1-1000,3389"` +2. Added development args file path: `"/app-scanner-src/scripts/args.txt"` +3. Updated container code and restarted services + +**Verification**: + +```bash +# Test Nmap with corrected configuration +docker exec sirius-engine nmap -p 1-1000,3389 --script vulners 127.0.0.1 -T4 -sV -Pn --script-args-file /app-scanner-src/scripts/args.txt +``` + +### Issue 4: TRPC Timeout Errors in Development + +**Problem**: Frontend unable to connect to backend API with timeout errors. + +**Root Cause**: sirius-engine container in restart loop, port 50051 not properly exposed. + +**Solution**: + +1. Verify all containers are running: `docker ps` +2. Check container logs: `docker logs sirius-engine` +3. Ensure development stage builds correctly: `docker compose up -d --build` +4. Verify port exposure: `docker port sirius-engine` + +### Issue 5: "air: command not found" in Development + +**Problem**: Live reload not working, air binary missing. + +**Root Cause**: Container using production stage instead of development stage. + +**Solution**: + +```bash +# Force development stage build +docker compose build --target development sirius-engine +docker restart sirius-engine + +# Verify air is available +docker exec sirius-engine which air +``` + +### Issue 6: Go Binary Compatibility Issues + +**Problem**: `go: command not found` errors in production container. + +**Root Cause**: Alpine musl vs Debian glibc binary compatibility. + +**Solution**: Use Debian-based images for Go builds to ensure binary compatibility. + +## Development Tips and Tricks + +### Quick Container Access + +```bash +# Jump into any container quickly +alias dexec='docker exec -it' +dexec sirius-engine bash + +# Quick log viewing +alias dlogs='docker logs -f' +dlogs sirius-engine +``` + +### Development Workflow Shortcuts + +```bash +# Complete restart and rebuild +alias drestart='docker compose down && docker compose up -d --build' + +# Quick service restart +alias dre='docker restart' +dre sirius-engine + +# View all container status +alias dps='docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"' +``` + +### File Synchronization + +```bash +# Sync local changes to container (when volume mounts fail) +sync_to_container() { + local service=$1 + local local_path=$2 + local container_path=$3 + docker cp "$local_path" "$service:$container_path" +} + +# Example usage +sync_to_container sirius-engine ../minor-projects/app-scanner/modules/nmap/nmap.go /app-scanner-src/modules/nmap/nmap.go +``` + +### Debug Container Issues + +```bash +# Complete container inspection +debug_container() { + local container=$1 + echo "=== Container Status ===" + docker ps | grep $container + echo "=== Container Logs (last 20 lines) ===" + docker logs $container --tail 20 + echo "=== Container Processes ===" + docker exec $container ps aux + echo "=== Container Mounts ===" + docker inspect $container | grep -A 10 "Mounts" +} + +# Usage +debug_container sirius-engine +``` + +## Performance Monitoring + +### Container Resource Usage + +```bash +# Real-time monitoring with custom format +docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.NetIO}}\t{{.BlockIO}}" + +# Log resource usage to file +docker stats --no-stream --format "{{.Container}},{{.CPUPerc}},{{.MemUsage}}" > container-stats.csv +``` + +### Service Health Monitoring + +```bash +# Check all service endpoints +check_services() { + echo "UI: $(curl -s -o /dev/null -w '%{http_code}' http://localhost:3000)" + echo "API: $(curl -s -o /dev/null -w '%{http_code}' http://localhost:9001/health)" + echo "RabbitMQ Management: $(curl -s -o /dev/null -w '%{http_code}' http://localhost:15672)" +} +``` + +## Additional Resources + +- [Docker Compose Documentation](https://docs.docker.com/compose/) +- [Dockerfile Best Practices](https://docs.docker.com/develop/dev-best-practices/) +- [Docker Security](https://docs.docker.com/engine/security/) +- [Container Monitoring](https://docs.docker.com/config/containers/runmetrics/) +- [Multi-stage Build Guide](https://docs.docker.com/develop/dev-best-practices/#use-multi-stage-builds) +- [Docker Compose Override Files](https://docs.docker.com/compose/extends/) + +--- + +_This documentation reflects the current Docker implementation as of June 2025 and includes solutions to issues encountered during development. For the most up-to-date information, refer to the actual Docker files in the repository._ diff --git a/documentation/archive/DOCKER-SIMPLIFICATION-SUMMARY.md b/documentation/archive/DOCKER-SIMPLIFICATION-SUMMARY.md new file mode 100644 index 0000000..0b2452b --- /dev/null +++ b/documentation/archive/DOCKER-SIMPLIFICATION-SUMMARY.md @@ -0,0 +1,153 @@ +# Docker Configuration Simplification + +**Date**: Current +**Status**: ✅ Complete +**Issue**: Eliminated unnecessary `environments/` directory complexity + +## 🎯 Problem Solved + +You were absolutely right - the `environments/` directory was unnecessary complexity. We had: + +1. **Base config** with defaults: `${POSTGRES_USER:-postgres}` +2. **Environment files** requiring separate `.env.staging`, `.env.production` +3. **Compose overrides** that expected those files + +This created a confusing three-layer system where developers had to manage separate files. + +## ✅ Solution Implemented + +**Eliminated the `environments/` directory entirely.** Now we have: + +1. **Base config** with defaults: `${POSTGRES_USER:-postgres}` +2. **Override compose files** with defaults: `${POSTGRES_USER:-postgres}` +3. **Runtime overrides** via environment variables: `export POSTGRES_USER=myuser` + +## 📁 New Structure + +```bash +# ❌ Old way (complex) +environments/ +├── .env.example +├── .env.staging # Required file +└── .env.production # Required file + +# ✅ New way (simple) +# No environments/ directory needed! +# Everything uses sensible defaults +``` + +## 🚀 Usage Examples + +### Before (Complex) + +```bash +# Had to create env files first +cp environments/.env.example environments/.env.production +nano environments/.env.production # Edit values +docker compose -f docker-compose.yaml -f docker-compose.production.yaml --env-file environments/.env.production up -d +``` + +### After (Simple) + +```bash +# Works immediately with defaults +docker compose -f docker-compose.yaml -f docker-compose.production.yaml up -d + +# Override specific values +export POSTGRES_PASSWORD=secure-password +export NEXTAUTH_SECRET=production-secret +docker compose -f docker-compose.yaml -f docker-compose.production.yaml up -d + +# Or use deployment script +./scripts/deploy.sh production v1.2.3 +``` + +## 🔧 Technical Changes + +### 1. Compose Files Updated + +All production/staging compose files now have defaults: + +```yaml +# Before +environment: + - POSTGRES_HOST=${POSTGRES_HOST} # Required external env file + +# After +environment: + - POSTGRES_HOST=${POSTGRES_HOST:-sirius-postgres} # Works out of the box +``` + +### 2. Deployment Script Simplified + +- Removed environment file checking +- Removed `--env-file` parameters +- Updated help text + +### 3. Documentation Updated + +- Developer guide reflects new simple approach +- Deployment docs show override patterns +- README files updated + +## 🎯 Benefits + +✅ **Immediate startup** - no file creation required +✅ **Sensible defaults** - works out of the box +✅ **Easy overrides** - just export variables +✅ **Less confusion** - one place for config +✅ **Cleaner repo** - no environments/ directory clutter + +## 📋 Default Values + +### Database + +- `POSTGRES_HOST=sirius-postgres` +- `POSTGRES_USER=postgres` +- `POSTGRES_PASSWORD=postgres` +- `POSTGRES_DB=sirius` +- `POSTGRES_PORT=5432` + +### Services + +- `VALKEY_HOST=sirius-valkey` +- `VALKEY_PORT=6379` +- `RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/` + +### Application + +- `SIRIUS_API_URL=http://sirius-api:9001` +- `NEXT_PUBLIC_SIRIUS_API_URL=http://localhost:9001` +- `NEXTAUTH_SECRET=your-production-secret-change-this` + +## 🔐 Security Notes + +The defaults include placeholder secrets that should be overridden in production: + +```bash +# ALWAYS override these in production +export NEXTAUTH_SECRET=your-actual-secret-key +export POSTGRES_PASSWORD=secure-database-password +``` + +## 🧪 Verification + +All configurations tested and working: + +```bash +# ✅ Base config +docker compose config --quiet + +# ✅ User config +docker compose -f docker-compose.user.yaml config --quiet + +# ✅ Production config +docker compose -f docker-compose.yaml -f docker-compose.production.yaml config --quiet + +# ✅ Staging config +docker compose -f docker-compose.yaml -f docker-compose.staging.yaml config --quiet +``` + +--- + +**Result**: Docker setup is now much simpler and more intuitive. The terminal rework integration is complete and the deployment process is streamlined. diff --git a/documentation/archive/E2E-TESTING-GUIDE.md b/documentation/archive/E2E-TESTING-GUIDE.md new file mode 100644 index 0000000..1c73f67 --- /dev/null +++ b/documentation/archive/E2E-TESTING-GUIDE.md @@ -0,0 +1,393 @@ +# End-to-End Testing Guide + +## Overview + +This guide provides comprehensive instructions for running the Sirius E2E test suite, which validates the complete source attribution functionality across all scanner types and user workflows. + +## Table of Contents + +1. [Prerequisites](#prerequisites) +2. [Test Suite Architecture](#test-suite-architecture) +3. [Running the Tests](#running-the-tests) +4. [Test Descriptions](#test-descriptions) +5. [Interpreting Results](#interpreting-results) +6. [Troubleshooting](#troubleshooting) +7. [Continuous Integration](#continuous-integration) + +## Prerequisites + +### System Requirements + +- **Operating System**: Linux, macOS, or Windows with WSL +- **Dependencies**: + - bash shell + - curl + - jq (optional, for JSON parsing) +- **Network Access**: Access to API and UI services + +### Service Requirements + +**Required Services:** + +- Sirius API (default: http://localhost:9001) +- PostgreSQL Database (accessible via API) + +**Optional Services:** + +- Sirius UI (default: http://localhost:3000) +- RabbitMQ (for scanner integration tests) + +### Environment Setup + +```bash +# Set custom URLs if needed +export API_BASE_URL="http://localhost:9001" +export UI_BASE_URL="http://localhost:3000" + +# Ensure services are running +docker-compose up -d # or your preferred method +``` + +## Test Suite Architecture + +### Test Coverage + +The E2E test suite covers the following areas: + +1. **API Connectivity** - Basic service health checks +2. **Legacy Compatibility** - Backward compatibility with existing clients +3. **Source Attribution** - Proper source detection and attribution +4. **Multi-Source Integrity** - Data preservation across multiple scanner sources +5. **Performance** - Response time validation +6. **Data Consistency** - Database integrity checks + +### Test Data + +- **Test Host IPs**: 192.168.1.100, 192.168.1.101 +- **Test CVEs**: CVE-2023-E2E-LEGACY, CVE-2023-E2E-NMAP, CVE-2023-E2E-AGENT +- **Scanner Types**: nmap, rustscan, naabu, agent, manual + +## Running the Tests + +### Quick Start + +```bash +# Run the complete E2E test suite +./scripts/test-e2e-suite.sh +``` + +### Custom Configuration + +```bash +# Run with custom API URL +API_BASE_URL="http://production-api:9001" ./scripts/test-e2e-suite.sh + +# Run with custom timeout settings +TIMEOUT=30 ./scripts/test-e2e-suite.sh +``` + +### Docker Environment + +```bash +# Run tests in containerized environment +docker run --rm --network host \ + -v $(pwd):/workspace \ + -w /workspace \ + curlimages/curl:latest \ + ./scripts/test-e2e-suite.sh +``` + +## Test Descriptions + +### Test 1: API Connectivity + +**Purpose**: Verify basic API service availability +**Method**: GET /health endpoint +**Success Criteria**: HTTP 200 response + +### Test 2: Legacy Host Submission + +**Purpose**: Validate backward compatibility with existing API clients +**Method**: POST /host without source headers +**Success Criteria**: Host created with 'unknown' source attribution + +### Test 3: Network Scanner Submission + +**Purpose**: Test source-aware network scanner integration +**Method**: POST /host with nmap headers +**Success Criteria**: Host created with 'nmap' source attribution + +### Test 4: Agent Submission + +**Purpose**: Test source-aware agent scanner integration +**Method**: POST /host with agent headers +**Success Criteria**: Host created with 'agent' source attribution + +### Test 5: Multi-Source Data Integrity + +**Purpose**: Verify data preservation when multiple sources scan same host +**Method**: Sequential submissions from different sources +**Success Criteria**: Both sources preserved, no data loss + +### Test 6: Source Attribution Endpoints + +**Purpose**: Validate new source-aware API endpoints +**Method**: GET /host/{ip}/sources, /host/{ip}/history, /host/source-coverage +**Success Criteria**: All endpoints return expected data structures + +### Test 7: Database Consistency + +**Purpose**: Verify database integrity and expected data structure +**Method**: Validate host data contains required fields +**Success Criteria**: Response contains ip, vulnerabilities, ports fields + +### Test 8: Performance Baseline + +**Purpose**: Ensure acceptable response times with source attribution +**Method**: Measure API response time +**Success Criteria**: Response time < 2000ms + +### Test 9: Vulnerability Data Format + +**Purpose**: Validate vulnerability data structure includes source info +**Method**: Check vulnerability response format +**Success Criteria**: Response contains vid, description, sources fields + +### Test 10: Cross-Scanner Compatibility + +**Purpose**: Test multiple scanner types on same infrastructure +**Method**: Submit data from rustscan and naabu +**Success Criteria**: Both scanner sources tracked correctly + +## Interpreting Results + +### Success Output + +``` +🚀 Starting Sirius E2E Test Suite +================================================ +API Base URL: http://localhost:9001 +UI Base URL: http://localhost:3000 + +✅ PASS: API Connectivity +✅ PASS: Legacy Host Submission +✅ PASS: Network Scanner Submission +... +================================================ +📊 E2E Test Suite Results +================================================ +Total Tests: 10 +Passed: 10 +Failed: 0 +🎉 All tests passed! System is ready for production. +``` + +### Test Results Directory + +Each test run creates a timestamped results directory: + +``` +test-results-e2e-{timestamp}/ +├── test_1_API_Connectivity.result +├── test_2_Legacy_Host_Submission.result +├── ... +└── e2e_suite_result.txt +``` + +### Result Files + +- **Individual Test Results**: `PASS` or `FAIL` for each test +- **Overall Result**: `test-results-e2e-{timestamp}/e2e_suite_result.txt` + +## Troubleshooting + +### Common Issues + +#### Service Unavailable + +**Error**: `❌ API service not available at http://localhost:9001` +**Solution**: + +1. Verify services are running: `docker-compose ps` +2. Check service logs: `docker-compose logs sirius-api` +3. Verify network connectivity: `curl http://localhost:9001/health` + +#### Database Connection Issues + +**Error**: Tests fail with database-related errors +**Solution**: + +1. Check PostgreSQL status: `docker-compose logs postgres` +2. Verify database migrations: `docker-compose exec sirius-api ./migrate` +3. Reset database if needed: `docker-compose down -v && docker-compose up -d` + +#### Test Data Conflicts + +**Error**: Tests fail due to existing data +**Solution**: + +1. The test suite includes cleanup procedures +2. Manual cleanup: Delete test hosts via API +3. Database reset: Clear test data manually + +#### Performance Test Failures + +**Error**: `Performance baseline failed: {time}ms (should be < 2000ms)` +**Solution**: + +1. Check system load: `top` or `htop` +2. Verify database performance +3. Adjust performance thresholds if needed + +### Debug Mode + +```bash +# Run tests with verbose output +set -x +./scripts/test-e2e-suite.sh +``` + +### Manual Test Execution + +```bash +# Test individual components +curl -s http://localhost:9001/health +curl -s -X POST -H "Content-Type: application/json" \ + -d '{"ip":"192.168.1.100","hostname":"test"}' \ + http://localhost:9001/host +``` + +## Continuous Integration + +### GitHub Actions Integration + +```yaml +# .github/workflows/e2e-tests.yml +name: E2E Tests +on: [push, pull_request] + +jobs: + e2e-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Start services + run: docker-compose up -d + - name: Wait for services + run: sleep 30 + - name: Run E2E tests + run: ./scripts/test-e2e-suite.sh + - name: Archive test results + uses: actions/upload-artifact@v2 + with: + name: e2e-test-results + path: test-results-e2e-*/ +``` + +### Jenkins Integration + +```groovy +pipeline { + agent any + stages { + stage('Setup') { + steps { + sh 'docker-compose up -d' + sh 'sleep 30' + } + } + stage('E2E Tests') { + steps { + sh './scripts/test-e2e-suite.sh' + } + post { + always { + archiveArtifacts artifacts: 'test-results-e2e-*/**' + } + } + } + } +} +``` + +## Test Environment Validation + +### Pre-Test Checklist + +- [ ] All required services are running +- [ ] Database is accessible and migrated +- [ ] Network connectivity is available +- [ ] Previous test data is cleaned up +- [ ] Required environment variables are set + +### Post-Test Validation + +- [ ] All tests passed or issues documented +- [ ] Test data is cleaned up +- [ ] Results are archived +- [ ] Performance metrics are within acceptable ranges + +## Performance Benchmarks + +### Expected Performance + +| Test Type | Target Time | Acceptable Range | +| ------------------------ | ----------- | ---------------- | +| API Health Check | < 100ms | < 500ms | +| Host Submission | < 500ms | < 1000ms | +| Source Attribution Query | < 200ms | < 1000ms | +| Multi-Source Integrity | < 1000ms | < 2000ms | + +### Performance Monitoring + +```bash +# Measure individual API calls +time curl -s http://localhost:9001/health + +# Monitor during test execution +htop # or top + +# Check database performance +docker-compose exec postgres psql -U sirius -d sirius -c " + SELECT query, mean_time, calls + FROM pg_stat_statements + ORDER BY mean_time DESC + LIMIT 10;" +``` + +## Security Considerations + +### Test Data Security + +- Test data uses non-production IPs and dummy CVEs +- No sensitive information is transmitted +- Test cleanup prevents data leakage + +### Network Security + +- Tests only use localhost/internal network communication +- No external API calls or data transmission +- Firewall rules may need adjustment for containerized testing + +## Next Steps + +After successful E2E testing: + +1. **Performance Testing** (Phase 4.2) +2. **Documentation Updates** (Phase 4.3) +3. **Deployment Procedures** (Phase 4.4) +4. **User Training** (Phase 4.5) +5. **Monitoring Setup** (Phase 4.6) + +## Support + +For issues with the E2E test suite: + +1. Check this documentation for common solutions +2. Review test logs in the results directory +3. Verify service logs for underlying issues +4. Contact the development team with specific error messages and environment details + +--- + +_This document is part of the Sirius Scan Source Attribution project (Phase 4.1: End-to-End Testing)_ diff --git a/documentation/archive/README.cicd.md b/documentation/archive/README.cicd.md new file mode 100644 index 0000000..93e11cf --- /dev/null +++ b/documentation/archive/README.cicd.md @@ -0,0 +1,96 @@ +# Sirius Scan CI/CD Pipeline Overview + +This document provides an overview of the Continuous Integration and Continuous Deployment (CI/CD) pipeline for the Sirius Scan project. It outlines the structure, triggers, environment management, and key processes involved in automatically building, testing, and integrating changes across the multi-repository application. + +## 1. Repository Structure and CI + +Sirius Scan is composed of a main `Sirius` repository and several submodule repositories (e.g., `go-api`, `app-scanner`, `app-terminal`, `app-agent`, `sirius-nse`). + +- **Submodule CI**: Each submodule has its own basic CI workflow (`.github/workflows/ci.yml`) located within its respective repository. These workflows typically perform: + + - Code checkout. + - Setup of the required runtime (e.g., Go, Node.js). + - Dependency installation. + - Linting (e.g., `golangci-lint` for Go projects). + - Unit testing. + - **Crucially**, upon a successful push/merge to its main branch, the submodule CI sends a `repository_dispatch` event to the main `SiriusScan/Sirius` repository. This event signals that the submodule has been updated. + +- **Main `Sirius` Repository CI**: The primary CI/CD logic resides in `Sirius/.github/workflows/ci.yml`. This workflow orchestrates the build and integration of the entire application stack. + +## 2. CI/CD Triggers + +The main `Sirius` CI/CD pipeline (`Sirius/.github/workflows/ci.yml`) is triggered by the following events: + +1. **Push to `main` branch**: Any commit pushed directly to the `main` branch of the `Sirius` repository. +2. **Pull Request to `main` branch**: When a pull request is opened or updated targeting the `main` branch of the `Sirius` repository. +3. **`repository_dispatch` event (type: `submodule-update`)**: This custom event is sent by the CI workflows of the individual submodule repositories upon a successful update to their main branches. The payload of this event includes: + - `submodule`: The name of the submodule repository that was updated (e.g., `SiriusScan/go-api`). + - `commit_sha`: The specific commit SHA of the update in the submodule. + +## 3. Simulating Staging in CI + +While there isn't a dedicated, persistent staging server, the CI pipeline simulates a staging-like environment for integration testing: + +- **Dynamic Configuration**: The `build` job in the main CI workflow dynamically generates: + - A `docker-compose.ci.yml` file: This file defines the service stack for CI, using the Docker images built during the current workflow run. + - `.env.ci.*` files: Environment configuration files (e.g., `.env.ci.sirius-api`, `.env.ci.sirius-engine`) tailored for the CI environment. These typically use test-specific database names, disable production features, and use services like an in-memory PostgreSQL database (`tmpfs`) for speed and isolation. +- **Isolated Network**: The `docker-compose.ci.yml` defines a dedicated Docker bridge network (`sirius_network`) for the services, ensuring isolation during CI runs. +- **Smoke Tests**: After building and starting the services using `docker compose -f docker-compose.ci.yml up -d`, a smoke test is performed. This involves basic checks like ensuring services are running (`docker compose ps`) and that key services are reachable (e.g., a `wget` to the `sirius-api` health endpoint). + +This CI environment provides confidence that the built images of the services can start and communicate with each other correctly with a test configuration. + +## 4. Environment Variables, Volumes, and Mounts + +Understanding how configurations and code are handled in different contexts is key: + +- **Local Development (`docker-compose.yaml`)**: + + - **`.env` files**: Each service (e.g., `sirius-ui`, `sirius-api`) typically relies on its own `.env` file (e.g., `Sirius/sirius-ui/.env`) for local development configuration (database connection strings, API keys, ports). + - **Volume Mounts**: The main `docker-compose.yaml` heavily uses volume mounts to map your local source code directories directly into the running containers (e.g., `./sirius-ui:/app`). This enables hot reloading and immediate reflection of code changes. + - Submodule development is also supported via commented-out volume mounts in `docker-compose.yaml` for services like `sirius-engine`, allowing you to mount a local clone of `go-api` or `app-scanner`. + +- **CI Environment (`docker-compose.ci.yml` generated in workflow)**: + - **No Local `.env` Files Used**: The CI environment _does not_ use your local `.env` files. + - **Generated `.env.ci.*` files**: As mentioned above, the CI workflow creates specific `.env.ci.*` files (e.g., `.env-ci/.env.ci.sirius-api`) with configurations suitable for automated testing. These are referenced by the `env_file` directive in `docker-compose.ci.yml`. + - **No Source Code Volume Mounts**: For CI, the services run from the Docker images built during the workflow. There are no mounts of local source code. This ensures the test is against the actual built artifact. + - **Database**: PostgreSQL runs in `tmpfs` (RAM disk) for speed and to ensure a clean state for each CI run. + +## 5. Submodule Version Pinning + +To ensure reproducible and stable builds of the main `Sirius` application, specific versions of submodules are used: + +- **Commit SHA Tracking**: When a submodule's CI triggers the main `Sirius` CI via `repository_dispatch`, it sends the exact `commit_sha` of the submodule's update. +- **Build Arguments (`ARG`)**: The `Sirius` CI workflow passes these received commit SHAs as build arguments (e.g., `GO_API_COMMIT_SHA`, `APP_SCANNER_COMMIT_SHA`) to the `docker build` commands for services that depend on these submodules (primarily `sirius-engine` and `sirius-api`). +- **Dockerfile Integration**: The `Dockerfile` for services like `sirius-engine` and `sirius-api` define these `ARG`s. During the build process, when cloning submodule repositories, they use `git checkout ${SUBMODULE_COMMIT_SHA}` to check out the exact version specified by the build argument. + - For example, `sirius-engine/Dockerfile` has: + ```Dockerfile + ARG APP_SCANNER_COMMIT_SHA=main + # ... + RUN git clone https://github.com/SiriusScan/app-scanner.git && \ + cd /app-scanner && \ + git checkout ${APP_SCANNER_COMMIT_SHA} + ``` +- **Default to `main`**: If no commit SHA is explicitly passed (e.g., for a direct push/PR to `Sirius` that doesn't involve a submodule update dispatch), the Dockerfiles default to using the `main` branch of the submodules. + +This mechanism ensures that the `Sirius` application is always built against known, specific states of its constituent submodules, preventing unexpected behavior due to uncoordinated submodule updates. + +## 6. Interpreting Build Logs + +When a CI build fails, check the GitHub Actions logs for the specific job and step that failed: + +- **`detect-changes` job**: Check if it correctly identified which services need rebuilding. Incorrect logic here might skip necessary builds. +- **`build` job**: + - **`Set environment variables` step**: Verify `TAG_SUFFIX` and submodule commit SHAs (if from dispatch) are set correctly. + - **`Build sirius-xxx` steps**: Docker build errors will appear here. Examine the output for issues in `Dockerfile` commands, compilation errors, or problems fetching dependencies (including submodule checkouts). + - **`Create CI environment config` step**: Ensure `docker-compose.ci.yml` and `.env.ci.*` files are generated as expected. + - **`Smoke Test` step**: This is critical. + - `docker compose ... up -d` failures indicate issues with service startup. Logs from `docker compose ps` can show which containers are unhealthy. + - `wget` failures (or other connectivity checks) indicate a service might have started but is not responsive or configured correctly. + - Use `docker compose -f docker-compose.ci.yml logs ` (you might need to add steps to print these logs on failure) to get detailed logs from specific services during the smoke test if they fail to start or behave unexpectedly. +- **`push-images` job**: Failures here usually relate to GHCR login issues or Docker tagging/pushing problems. + +For submodule CI failures, check the logs directly in the respective submodule repository's Actions tab. + +--- + +This document provides a foundational understanding. As the CI/CD pipeline evolves, this documentation will be updated. diff --git a/documentation/archive/README.deployment-strategy.md b/documentation/archive/README.deployment-strategy.md new file mode 100644 index 0000000..d43614e --- /dev/null +++ b/documentation/archive/README.deployment-strategy.md @@ -0,0 +1,401 @@ +# Sirius Scan Production Deployment Strategy + +## Overview + +This document outlines the recommended approach for managing multiple environments (development, staging, production) without manual file modifications. + +## 🎯 Goals + +- **Zero Manual Changes**: No file modifications required for different environments +- **Environment Parity**: Consistent configuration across all environments +- **Security**: Proper secrets management for production +- **Scalability**: Easy to add new environments +- **Developer Experience**: Simple local development setup + +## 🏗️ Architecture: Multi-Environment Configuration + +### 1. Docker Compose Override Pattern + +Instead of modifying `docker-compose.yaml`, we use Docker Compose's built-in override system: + +``` +docker-compose.yaml # Base configuration (shared) +docker-compose.override.yaml # Local development (auto-loaded) +docker-compose.staging.yaml # Staging environment +docker-compose.production.yaml # Production environment +``` + +### 2. Environment Variable Management + +#### Current State + +- Hardcoded values in `docker-compose.yaml` +- Manual `.env` file management +- No centralized configuration + +#### Recommended State + +``` +environments/ +├── .env.development # Local development +├── .env.staging # Staging environment +├── .env.production # Production environment +└── .env.example # Template for new environments +``` + +### 3. Deployment Commands + +#### Development (Current) + +```bash +docker compose up --build +``` + +#### Staging + +```bash +docker compose -f docker-compose.yaml -f docker-compose.staging.yaml --env-file environments/.env.staging up -d +``` + +#### Production + +```bash +docker compose -f docker-compose.yaml -f docker-compose.production.yaml --env-file environments/.env.production up -d +``` + +## 🔧 Implementation Plan + +### Phase 1: Environment Separation + +1. **Create Environment-Specific Compose Files** + + ```yaml + # docker-compose.production.yaml + version: "3.8" + services: + sirius-ui: + image: ghcr.io/siriusscan/sirius-ui:${IMAGE_TAG:-latest} + build: null # Disable build, use pre-built images + volumes: [] # Remove development volume mounts + environment: + - NODE_ENV=production + - SKIP_ENV_VALIDATION=0 + + sirius-api: + image: ghcr.io/siriusscan/sirius-api:${IMAGE_TAG:-latest} + build: null + volumes: [] + + sirius-engine: + image: ghcr.io/siriusscan/sirius-engine:${IMAGE_TAG:-latest} + build: null + volumes: [] + ``` + +2. **Environment Variable Templates** + + ```bash + # environments/.env.production + # Database Configuration + POSTGRES_USER=sirius_prod + POSTGRES_PASSWORD=${POSTGRES_PASSWORD} # From secrets + POSTGRES_DB=sirius_production + + # Image Tags + IMAGE_TAG=v1.2.3 + + # API Configuration + NODE_ENV=production + GO_ENV=production + + # External Services + SIRIUS_API_URL=https://api.sirius.company.com + NEXT_PUBLIC_SIRIUS_API_URL=https://api.sirius.company.com + ``` + +### Phase 2: Secrets Management + +#### Option A: Docker Secrets (Recommended for Docker Swarm) + +```yaml +# docker-compose.production.yaml +services: + sirius-postgres: + environment: + POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password + secrets: + - postgres_password + +secrets: + postgres_password: + external: true +``` + +#### Option B: External Secret Management + +- **HashiCorp Vault**: Enterprise-grade secret management +- **AWS Secrets Manager**: For AWS deployments +- **Azure Key Vault**: For Azure deployments +- **Kubernetes Secrets**: For K8s deployments + +### Phase 3: CI/CD Integration + +#### GitHub Actions Workflow Enhancement + +```yaml +# .github/workflows/deploy.yml +name: Deploy to Environment + +on: + workflow_dispatch: + inputs: + environment: + description: "Target environment" + required: true + default: "staging" + type: choice + options: + - staging + - production + image_tag: + description: "Image tag to deploy" + required: true + default: "latest" + +jobs: + deploy: + runs-on: ubuntu-latest + environment: ${{ github.event.inputs.environment }} + + steps: + - name: Deploy to ${{ github.event.inputs.environment }} + run: | + # Generate environment-specific docker-compose command + docker compose \ + -f docker-compose.yaml \ + -f docker-compose.${{ github.event.inputs.environment }}.yaml \ + --env-file environments/.env.${{ github.event.inputs.environment }} \ + up -d + env: + IMAGE_TAG: ${{ github.event.inputs.image_tag }} + POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }} +``` + +## 🛠️ Technology Recommendations + +### 1. Container Orchestration + +#### Current: Docker Compose + +- **Pros**: Simple, good for single-host deployments +- **Cons**: Limited scaling, no built-in load balancing + +#### Recommended Upgrades: + +**For Small-Medium Scale:** + +- **Docker Swarm**: Native Docker clustering +- **Portainer**: Web UI for container management +- **Traefik**: Automatic service discovery and load balancing + +**For Large Scale:** + +- **Kubernetes**: Industry standard orchestration +- **Helm Charts**: Package management for K8s +- **ArgoCD**: GitOps continuous deployment + +### 2. Configuration Management + +#### Recommended: Kustomize + ConfigMaps + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +resources: + - base/ + +patchesStrategicMerge: + - environment-patches.yaml + +configMapGenerator: + - name: app-config + envs: + - .env.production +``` + +#### Alternative: Helm with Values + +```yaml +# values.production.yaml +environment: production +image: + tag: "v1.2.3" + pullPolicy: Always + +database: + host: "prod-postgres.company.com" + name: "sirius_production" + +ingress: + enabled: true + host: "sirius.company.com" + tls: true +``` + +### 3. Infrastructure as Code (IaC) + +#### Terraform for Infrastructure + +```hcl +# main.tf +module "sirius_infrastructure" { + source = "./modules/sirius" + + environment = var.environment + image_tag = var.image_tag + + database_instance_class = var.environment == "production" ? "db.r5.large" : "db.t3.micro" + + tags = { + Environment = var.environment + Project = "sirius-scan" + } +} +``` + +#### Pulumi Alternative (TypeScript/Go) + +```typescript +// infrastructure/index.ts +import * as aws from "@pulumi/aws"; +import * as docker from "@pulumi/docker"; + +const environment = pulumi.getStack(); + +const cluster = new aws.ecs.Cluster(`sirius-${environment}`); + +const service = new aws.ecs.Service(`sirius-ui-${environment}`, { + cluster: cluster.arn, + taskDefinition: taskDefinition.arn, + desiredCount: environment === "production" ? 3 : 1, +}); +``` + +### 4. Monitoring and Observability + +#### Recommended Stack: + +- **Prometheus**: Metrics collection +- **Grafana**: Visualization and alerting +- **Loki**: Log aggregation +- **Jaeger**: Distributed tracing +- **AlertManager**: Alert routing + +#### Implementation: + +```yaml +# monitoring/docker-compose.yaml +version: "3.8" +services: + prometheus: + image: prom/prometheus:latest + volumes: + - ./prometheus.yml:/etc/prometheus/prometheus.yml + - prometheus_data:/prometheus + + grafana: + image: grafana/grafana:latest + environment: + - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD} + volumes: + - grafana_data:/var/lib/grafana + - ./grafana/dashboards:/etc/grafana/provisioning/dashboards +``` + +## 🚀 Migration Strategy + +### Week 1: Environment Separation + +1. Create `docker-compose.override.yaml` for development +2. Create `docker-compose.staging.yaml` and `docker-compose.production.yaml` +3. Set up `environments/` directory with `.env` files +4. Update CI/CD to use environment-specific configurations + +### Week 2: Secrets Management + +1. Implement Docker secrets for sensitive data +2. Update deployment scripts to use external secret sources +3. Configure GitHub Actions environments with proper secrets + +### Week 3: Infrastructure as Code + +1. Create Terraform/Pulumi modules for infrastructure +2. Set up separate infrastructure for staging and production +3. Implement automated infrastructure deployment + +### Week 4: Monitoring and Optimization + +1. Deploy monitoring stack +2. Set up alerting and dashboards +3. Performance testing and optimization + +## 📋 Deployment Checklist + +### Pre-Deployment + +- [ ] Environment variables configured +- [ ] Secrets properly managed +- [ ] Database migrations ready +- [ ] Health checks configured +- [ ] Monitoring enabled + +### Deployment + +- [ ] Pull latest images +- [ ] Run database migrations +- [ ] Deploy services with zero downtime +- [ ] Verify health checks +- [ ] Run smoke tests + +### Post-Deployment + +- [ ] Monitor application metrics +- [ ] Check error rates +- [ ] Verify functionality +- [ ] Update documentation + +## 🔒 Security Best Practices + +### 1. Secrets Management + +- Never commit secrets to version control +- Use environment-specific secret stores +- Rotate secrets regularly +- Implement least-privilege access + +### 2. Container Security + +- Use non-root users in containers +- Scan images for vulnerabilities +- Keep base images updated +- Implement resource limits + +### 3. Network Security + +- Use private networks for internal communication +- Implement proper firewall rules +- Use TLS for all external communication +- Regular security audits + +## 📚 Additional Resources + +- [Docker Compose Override Documentation](https://docs.docker.com/compose/extends/) +- [Kubernetes Configuration Best Practices](https://kubernetes.io/docs/concepts/configuration/) +- [12-Factor App Methodology](https://12factor.net/) +- [GitOps Principles](https://www.gitops.tech/) + +--- + +This strategy eliminates manual file modifications while providing a robust, scalable deployment pipeline suitable for enterprise environments. diff --git a/documentation/contributing.md b/documentation/contributing.md new file mode 100644 index 0000000..ab61c3f --- /dev/null +++ b/documentation/contributing.md @@ -0,0 +1,451 @@ +--- +title: "Contributing to Sirius Scan" +description: "Developer guide for contributing to the Sirius Scan vulnerability scanning platform" +template: "TEMPLATE.guide" +version: "1.0.0" +last_updated: "2025-10-11" +author: "Sirius Development Team" +tags: ["contributing", "development", "guide", "setup"] +categories: ["development", "contribution"] +difficulty: "intermediate" +prerequisites: + - "Git version control" + - "Docker and Docker Compose" + - "Go 1.21+ for backend development" + - "Node.js 20+ for frontend development" +related_docs: + - "README.development.md" + - "README.container-testing.md" + - "README.git-operations.md" +dependencies: + - "docker" + - "git" + - "go" + - "node" +llm_context: "high" +search_keywords: ["contributing", "development", "setup", "testing", "workflow"] +--- + +# Contributing to Sirius Scan + +Welcome to the Sirius Scan development community! This guide will help you set up your development environment and contribute effectively to the project. + +## 📋 Table of Contents + +- [Getting Started](#getting-started) +- [Development Environment Setup](#development-environment-setup) +- [Development Workflow](#development-workflow) +- [Testing & Quality Assurance](#testing--quality-assurance) +- [Code Standards](#code-standards) +- [Submitting Contributions](#submitting-contributions) +- [Community Guidelines](#community-guidelines) + +## 🚀 Getting Started + +### Prerequisites for Development + +Before you begin, ensure you have the following installed: + +- **Git**: Version control system +- **Docker Engine**: 20.10.0+ with Docker Compose V2 +- **Go**: 1.21+ for backend development +- **Node.js**: 20+ for frontend development +- **System Requirements**: 8GB RAM minimum, 20GB free disk space +- **Understanding of Docker**: Multi-stage builds and volume mounting + +### Understanding the Architecture + +Sirius uses a microservices architecture with the following key components: + +| Component | Technology | Purpose | +|-----------|-----------|---------| +| **sirius-ui** | Next.js 14, React | Web frontend interface | +| **sirius-api** | Go, Gin framework | REST API backend | +| **sirius-engine** | Go, multiple services | Scanner, terminal, agent services | +| **sirius-postgres** | PostgreSQL 15 | Primary data storage | +| **sirius-rabbitmq** | RabbitMQ | Message queue | +| **sirius-valkey** | Redis-compatible | Cache layer | + +## 🔧 Development Environment Setup + +### Step 1: Clone the Main Repository + +```bash +git clone https://github.com/SiriusScan/Sirius.git +cd Sirius +``` + +### Step 2: Clone Component Repositories (Optional) + +Only clone the components you plan to develop: + +```bash +# Create development directory structure +mkdir -p ../minor-projects && cd ../minor-projects + +# Clone components you want to develop +git clone https://github.com/SiriusScan/go-api.git # REST API backend +git clone https://github.com/SiriusScan/app-scanner.git # Scanning engine +git clone https://github.com/SiriusScan/app-terminal.git # Terminal service +git clone https://github.com/SiriusScan/app-agent.git # Remote agents +git clone https://github.com/SiriusScan/sirius-nse.git # NSE scripts +git clone https://github.com/SiriusScan/app-system-monitor.git # System monitor +git clone https://github.com/SiriusScan/app-administrator.git # Administrator service + +cd ../Sirius +``` + +### Step 3: Configure Development Mode + +Edit `docker-compose.dev.yaml` and uncomment volume mounts for components you're developing: + +```yaml +services: + sirius-engine: + volumes: + # Uncomment ONLY for repositories you have cloned: + # - ../minor-projects/app-agent:/app-agent-src # Agent development + # - ../minor-projects/app-scanner:/app-scanner-src # Scanner development + # - ../minor-projects/app-terminal:/app-terminal-src # Terminal development + # - ../minor-projects/go-api:/go-api # API development + # - ../minor-projects/app-system-monitor:/system-monitor # Monitor development + # - ../minor-projects/app-administrator:/app-administrator # Admin development +``` + +### Step 4: Start Development Environment + +```bash +# Development mode requires BOTH config files +docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d --build + +# Or for a clean start +docker compose -f docker-compose.yaml -f docker-compose.dev.yaml down -v +docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d --build +``` + +**⚠️ Important**: The `docker-compose.dev.yaml` file is an override file, not a standalone configuration. You must specify both the base configuration (`docker-compose.yaml`) and the development overrides (`docker-compose.dev.yaml`) when starting services in development mode. + +### Development Features + +- **🔥 Hot Reload**: Live code reloading with Air for Go services +- **📝 Live Editing**: Frontend changes reflect immediately +- **🐛 Debug Mode**: Detailed logging and error reporting +- **🔍 Development Tools**: Access to Go toolchain and debugging utilities + +## 🔄 Development Workflow + +### Daily Development Commands + +```bash +# View real-time logs +docker compose logs -f sirius-engine + +# Access development container +docker exec -it sirius-engine bash + +# Check live reload status +docker exec sirius-engine ps aux | grep air + +# Restart specific service +docker restart sirius-engine + +# Rebuild with changes (development mode) +docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d --build + +# Stop development environment +docker compose -f docker-compose.yaml -f docker-compose.dev.yaml down + +# Clean restart (removes volumes) +docker compose -f docker-compose.yaml -f docker-compose.dev.yaml down -v +docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d +``` + +### Working with Individual Components + +#### Backend Development (Go) + +```bash +# Access the container +docker exec -it sirius-engine bash + +# Run tests +go test ./... + +# Build manually +go build -o binary main.go + +# Check dependencies +go mod tidy +``` + +#### Frontend Development (Next.js) + +```bash +# Access the UI container +docker exec -it sirius-ui bash + +# Install dependencies +npm install + +# Run development server +npm run dev + +# Build production +npm run build +``` + +## 🧪 Testing & Quality Assurance + +### Running Tests + +```bash +# Run comprehensive test suite +cd testing +make test-all + +# Run specific test categories +make test-build # Container build tests +make test-health # Health check tests +make test-integration # Integration tests + +# Run documentation validation +make lint-docs # Full documentation linting +make lint-docs-quick # Quick documentation checks +make lint-index # Index completeness check +``` + +### Manual Testing + +```bash +# Test scanner functionality +docker exec sirius-engine nmap --version +docker exec sirius-engine nmap -p 80 127.0.0.1 + +# Test API endpoints +curl http://localhost:9001/health +curl http://localhost:9001/api/v1/system/health + +# Test database connection +docker exec sirius-postgres pg_isready +docker exec sirius-postgres psql -U postgres -d sirius -c "SELECT version();" + +# Test RabbitMQ +docker exec sirius-rabbitmq rabbitmqctl status +docker exec sirius-rabbitmq rabbitmqctl list_queues +``` + +### Pre-Commit Testing + +Before committing code, always run: + +```bash +# Run all validation checks +cd testing +make validate-all + +# Or use the pre-commit hook (automatically runs on commit) +git commit -m "your commit message" +``` + +The pre-commit hook automatically runs: +- Documentation linting (quick validation) +- Index completeness check +- Build validation (smart testing based on branch) + +## 📝 Code Standards + +### Git Workflow + +We follow a structured Git workflow as documented in [README.git-operations.md](dev/operations/README.git-operations.md). + +#### Branch Naming + +``` +/ + +Examples: +feature/vulnerability-export +fix/scanner-timeout +docs/api-documentation +``` + +#### Commit Messages + +``` +(): + +[optional body] + +[optional footer] + +Types: +- feat: New feature +- fix: Bug fix +- docs: Documentation changes +- test: Testing changes +- refactor: Code refactoring +- chore: Maintenance tasks +- hotfix: Emergency production fix + +Examples: +feat(scanner): add support for custom NSE scripts +fix(api): resolve authentication token expiration +docs(architecture): update system design documentation +test(integration): add scanner workflow tests +``` + +#### GitHub Integration + +When working with GitHub issues: + +```bash +# Create issue first +gh issue create --title "Add vulnerability export feature" --body "Description" + +# Create branch linked to issue +git checkout -b feature/77-vulnerability-export + +# Commit with issue reference +git commit -m "feat(export): add PDF export functionality + +Refs #77" + +# Push and create PR +git push origin feature/77-vulnerability-export +gh pr create --fill +``` + +### Code Review Process + +1. **Create feature branch** from main +2. **Implement changes** with tests +3. **Run validation** suite locally +4. **Push branch** to GitHub +5. **Create Pull Request** with description +6. **Wait for review** and approval +7. **Address feedback** if needed +8. **Merge to main** after approval + +### Human Validation Required + +**⚠️ Important**: Before merging to main, all changes must be: +1. **Tested locally** and verified working +2. **Reviewed by maintainer** +3. **Approved explicitly** before merge + +This ensures we never push broken code to production. + +## 🤝 Submitting Contributions + +### Pull Request Guidelines + +When submitting a PR, include: + +1. **Clear description** of changes +2. **Issue reference** if applicable +3. **Testing evidence** (screenshots, logs) +4. **Documentation updates** if needed +5. **Breaking changes** clearly marked + +### PR Template + +```markdown +## Description +[Brief description of changes] + +## Related Issue +Fixes #123 + +## Type of Change +- [ ] Bug fix +- [ ] New feature +- [ ] Breaking change +- [ ] Documentation update + +## Testing +- [ ] Local testing completed +- [ ] All tests passing +- [ ] Documentation updated +- [ ] No breaking changes (or documented) + +## Screenshots/Evidence +[If applicable] + +## Additional Notes +[Any additional context] +``` + +## 👥 Community Guidelines + +### Code of Conduct + +- **Be respectful**: Treat all contributors with respect +- **Be collaborative**: Work together to solve problems +- **Be patient**: Remember everyone is learning +- **Be constructive**: Provide helpful feedback + +### Getting Help + +- **Discord Community**: Real-time chat and support +- **GitHub Issues**: Bug reports and feature requests +- **GitHub Discussions**: General questions and ideas +- **Documentation**: Comprehensive guides and references + +### Contributing Areas + +We welcome contributions in: + +- **Code**: New features, bug fixes, optimizations +- **Documentation**: Guides, tutorials, API docs +- **Testing**: Test cases, integration tests +- **Design**: UI/UX improvements +- **Community**: Support, tutorials, blog posts + +## 📚 Additional Resources + +### Essential Documentation + +- [Development Workflow](dev/README.development.md) - Complete development guide +- [Container Testing](dev/test/README.container-testing.md) - Testing system +- [Git Operations](dev/operations/README.git-operations.md) - Git workflow +- [Architecture](dev/architecture/README.architecture.md) - System design + +### Component Repositories + +- [go-api](https://github.com/SiriusScan/go-api) - REST API backend +- [app-scanner](https://github.com/SiriusScan/app-scanner) - Scanning engine +- [app-terminal](https://github.com/SiriusScan/app-terminal) - Terminal service +- [app-agent](https://github.com/SiriusScan/app-agent) - Remote agents +- [sirius-nse](https://github.com/SiriusScan/sirius-nse) - NSE scripts +- [app-system-monitor](https://github.com/SiriusScan/app-system-monitor) - System monitor +- [app-administrator](https://github.com/SiriusScan/app-administrator) - Admin service + +## 🎓 Learning Path + +### For New Contributors + +1. **Set up development environment** (this guide) +2. **Read architecture documentation** +3. **Run the test suite** to understand coverage +4. **Pick a "good first issue"** from GitHub +5. **Submit your first PR** + +### For Regular Contributors + +1. **Understand the codebase** deeply +2. **Review others' PRs** to learn +3. **Propose new features** via issues +4. **Help with documentation** +5. **Mentor new contributors** + +## 📞 Contact & Support + +- **GitHub Issues**: Bug reports and features +- **GitHub Discussions**: Questions and ideas +- **Discord**: Real-time community chat +- **Email**: support@opensecurity.com + +--- + +Thank you for contributing to Sirius Scan! Your efforts help make security scanning accessible to everyone. + diff --git a/documentation/dash-dark.gif b/documentation/dash-dark.gif new file mode 100755 index 0000000..2ac7097 Binary files /dev/null and b/documentation/dash-dark.gif differ diff --git a/documentation/dev-notes/0.4.0-issue-resolution-analysis.md b/documentation/dev-notes/0.4.0-issue-resolution-analysis.md new file mode 100644 index 0000000..b9424ca --- /dev/null +++ b/documentation/dev-notes/0.4.0-issue-resolution-analysis.md @@ -0,0 +1,359 @@ +# v0.4.0 Issue Resolution Analysis + +**Date**: October 11, 2025 +**Version**: 0.4.0 +**Purpose**: Analyze open GitHub issues and identify which have been resolved by recent updates + +## Executive Summary + +The v0.4.0 release includes significant improvements to Docker builds, Go module management, RabbitMQ connectivity, and deployment structure. This analysis identified **6 issues that should be closed** as resolved and **2 issues requiring follow-up** with users. + +--- + +## Issues Resolved by v0.4.0 + +### 1. Issue #73 - Arch Linux Build Error ✅ RESOLVED + +**Reported**: October 10, 2025 +**User**: @FX42S +**Error**: `reading ../go-api/go.mod: open /repos/go-api/go.mod: no such file or directory` + +**Root Cause**: Build order issue - app-scanner was being built before go-api was cloned + +**Resolution in v0.4.0**: + +- **CHANGELOG Entry**: "Go Module Dependencies: Resolved version conflicts between sirius-api, go-api, and app-scanner modules" +- **Fix Location**: `sirius-engine/Dockerfile` lines 28-39 +- **Change**: go-api is now cloned first (line 28-32) before app-scanner (line 34-39) + +**Verification**: + +```dockerfile +# Clone go-api first (needed by other components) +RUN git clone https://github.com/SiriusScan/go-api.git && \ + cd go-api && \ + git checkout ${GO_API_COMMIT_SHA} && \ + go mod tidy + +# Clone app-scanner +RUN git clone https://github.com/SiriusScan/app-scanner.git && \ + cd app-scanner && \ + git checkout ${APP_SCANNER_COMMIT_SHA} && \ + go mod download && \ + CGO_ENABLED=1 GOOS=linux go build -ldflags="-w -s" -o scanner main.go +``` + +**Action**: Close issue with resolution comment + +--- + +### 2. Issue #71 - Error ✅ RESOLVED + +**Reported**: October 9, 2025 +**User**: @wpf973 +**Error**: Identical to #73 - `reading ../go-api/go.mod: open /repos/go-api/go.mod: no such file or directory` + +**Resolution**: Same as Issue #73 + +**Action**: Close issue referencing #73 and v0.4.0 fix + +--- + +### 3. Issue #69 - Build Fails Due to Missing Files ✅ RESOLVED + +**Reported**: October 5, 2025 +**User**: @nicpenning +**Error**: `reading ../go-api/go.mod: open /repos/go-api/go.mod: no such file or directory` + +**Notable**: User correctly identified the fix and provided the solution in the issue description + +**Resolution**: Same build order fix as #73 and #71, now implemented in v0.4.0 + +**Action**: Close issue thanking user for the detailed report and solution + +--- + +### 4. Issue #58 - Production Setup Error ✅ RESOLVED + +**Reported**: July 16, 2025 +**User**: @ashvile-queen +**Error**: `validating /root/Sirius/docker-compose.production.yaml: services.sirius-api.build must be a string` + +**Root Cause**: User attempting to use `docker-compose.production.yaml` which had configuration issues + +**Resolution in v0.4.0**: + +- **CHANGELOG Entry**: "Improved Docker configurations" +- **Structural Change**: Deployment simplified from 3 modes to 2 modes +- **Current Structure**: + - `docker-compose.yaml` - Standard/Production mode + - `docker-compose.dev.yaml` - Development mode + - `docker-compose.production.yaml` - **REMOVED** + +**Action**: Close issue with migration instructions to use correct compose file + +--- + +### 5. Issue #55 - RabbitMQ Reboot Looping ✅ LIKELY RESOLVED + +**Reported**: July 8, 2025 +**User**: @JM2K69 +**Error**: RabbitMQ container constantly restarting with exit code 137 + +**Resolution in v0.4.0**: + +- **CHANGELOG Entry**: "RabbitMQ Connectivity: Corrected health check patterns for reliable service monitoring" +- **Fix**: Improved health check configurations and connection patterns + +**Action**: Close issue requesting user to test with v0.4.0 and report if issue persists + +--- + +### 6. Issue #54 - sirius-engine Service Restarting ✅ LIKELY RESOLVED + +**Reported**: June 25, 2025 +**User**: @brittadams +**Error**: `failed to connect to RabbitMQ dial to 172.18.0.3:5672 connection refused` + +**Resolution**: Same as Issue #55 - RabbitMQ connectivity improvements + +**Action**: Close issue requesting user to test with v0.4.0 and report if issue persists + +--- + +## Issues Requiring Follow-Up + +### 1. Issue #74 - RabbitMQ Endless Reboot ⚠️ REQUIRES USER ACTION + +**Reported**: October 10, 2025 (day before v0.4.0 release) +**User**: @easy13 (Oracle Linux Server 9.6) +**Error**: RabbitMQ container constantly restarting + +**Analysis**: + +- User is trying multiple non-existent compose files: + - `docker-compose.prod.yaml` ❌ (doesn't exist) + - `docker-compose.yaml -f docker-compose.prod.yaml` ❌ (doesn't exist) +- User environment shows older image version (likely pre-0.4.0) + +**Root Cause**: Using outdated instructions/compose files + +**Action Required**: + +1. Inform user about v0.4.0 release +2. Provide correct deployment instructions: + ```bash + git pull origin main + docker compose down + docker compose up -d --build + ``` +3. Explain new 2-mode deployment structure +4. Request user to test and report results + +**Keep Open**: Until user confirms resolution or provides additional details + +--- + +### 2. Issue #68 - Construction Problem ⚠️ NEEDS INVESTIGATION + +**Reported**: October 1, 2025 +**User**: @charis3306 +**Language**: Chinese +**Details**: Limited information, references log file attachment + +**Analysis**: Unable to determine exact issue without log file content + +**Action Required**: + +1. Review attached log file on GitHub issue page +2. Determine if related to Docker build issues fixed in v0.4.0 +3. Respond appropriately based on log analysis + +**Status**: Pending log file review + +--- + +## Deployment Structure Changes + +### Pre-v0.4.0 (Incorrect/Inconsistent) + +- `docker-compose.yaml` - Standard +- `docker-compose.user.yaml` - User-focused (may not have existed) +- `docker-compose.production.yaml` - Production (had configuration issues) + +### v0.4.0 Current Structure + +- `docker-compose.yaml` - Standard/Production mode (recommended for most users) +- `docker-compose.dev.yaml` - Development mode (for contributors) + +--- + +## Response Templates + +### For Build Order Issues (#73, #71, #69) + +````markdown +Hi @[username], + +Thank you for reporting this issue! This has been resolved in **v0.4.0** (released October 11, 2025). + +**The Problem**: The build order in the Dockerfile was incorrect - `app-scanner` was being built before `go-api` was available, causing the "no such file or directory" error. + +**The Fix**: We've corrected the build order in the `sirius-engine/Dockerfile`. The `go-api` repository is now cloned and built first (as the comment indicated it should be!), then `app-scanner` can successfully build with the required dependencies. + +**To Update**: + +```bash +git pull origin main +docker compose down +docker compose up -d --build +``` +```` + +This issue is now closed as resolved. If you continue to experience problems after updating, please feel free to reopen or create a new issue. + +**Reference**: See CHANGELOG.md - "Go Module Dependencies: Resolved version conflicts between sirius-api, go-api, and app-scanner modules" + +```` + +### For RabbitMQ Issues (#55, #54) + +```markdown +Hi @[username], + +Thank you for reporting this RabbitMQ connectivity issue! We've made significant improvements in **v0.4.0** (released October 11, 2025) that should resolve this problem. + +**The Fix**: We've corrected RabbitMQ health check patterns and improved connection reliability across all services. + +**To Update**: +```bash +git pull origin main +docker compose down +docker compose up -d --build +```` + +**Please Test**: After updating, please verify that the issue is resolved. If you continue to experience RabbitMQ connectivity problems, please reopen this issue or create a new one with: + +- Output of `docker compose ps` +- Logs from RabbitMQ: `docker compose logs sirius-rabbitmq` +- Any relevant error messages + +We're closing this as likely resolved, but we're here to help if you need further assistance! + +**Reference**: See CHANGELOG.md - "RabbitMQ Connectivity: Corrected health check patterns for reliable service monitoring" + +```` + +### For Deployment Structure Issue (#58) + +```markdown +Hi @ashvile-queen, + +Thank you for reporting this! The issue with `docker-compose.production.yaml` has been resolved in **v0.4.0** (released October 11, 2025). + +**What Changed**: We've simplified the deployment structure from 3 modes to 2 modes for better reliability and maintainability: + +**New Deployment Options**: +1. **Standard Mode** (recommended for production): + ```bash + docker compose up -d +```` + +2. **Development Mode** (for contributors with hot-reloading): + ```bash + docker compose -f docker-compose.dev.yaml up -d + ``` + +**Migration Instructions**: + +```bash +git pull origin main +docker compose down +docker compose up -d --build +``` + +The default `docker-compose.yaml` is now production-ready with optimized configurations. The old `docker-compose.production.yaml` file no longer exists. + +This issue is now closed as resolved. If you have any questions about the new deployment structure, please let us know! + +```` + +### For Issue #74 (User Action Required) + +```markdown +Hi @easy13, + +Thank you for the detailed report! I see you're experiencing RabbitMQ restart issues on Oracle Linux Server 9.6. + +**Important Update**: Sirius Scan **v0.4.0** was just released (October 11, 2025) with significant improvements to RabbitMQ connectivity and container builds. + +**Issue with Your Commands**: The compose files you're trying to use don't exist: +- ❌ `docker-compose.prod.yaml` - doesn't exist +- ❌ `docker-compose.production.yaml` - removed in v0.4.0 + +**Correct Deployment for v0.4.0**: +```bash +# Update to latest version +cd Sirius +git pull origin main + +# Clean up old containers +docker compose down -v + +# Start with correct compose file +docker compose up -d --build +```` + +**New Deployment Structure**: + +- `docker-compose.yaml` - Standard/Production mode (what you should use) +- `docker-compose.dev.yaml` - Development mode (only for contributors) + +**RabbitMQ Improvements in v0.4.0**: + +- Corrected health check patterns +- Improved connection reliability +- Better error handling + +**Please Try This** and let us know if the RabbitMQ restarting issue persists. If you continue to have problems, please provide: + +1. Output of `docker compose ps` (after update) +2. RabbitMQ logs: `docker compose logs sirius-rabbitmq` +3. Your Docker version and system info (which you helpfully already provided!) + +We're keeping this issue open until you confirm the resolution. Thank you for your patience! + +``` + +--- + +## Summary Statistics + +- **Total Open Issues Analyzed**: 8 +- **Issues Resolved**: 6 (75%) +- **Issues Requiring Follow-up**: 2 (25%) +- **Build Order Issues Fixed**: 3 (#73, #71, #69) +- **RabbitMQ Issues Fixed**: 2 (#55, #54) +- **Deployment Structure Issues Fixed**: 1 (#58) +- **Requires User Testing**: 1 (#74) +- **Requires Investigation**: 1 (#68) + +--- + +## Next Steps + +1. ✅ Post resolution comments on issues #73, #71, #69, #58, #55, #54 +2. ⚠️ Post follow-up comment on issue #74 with correct instructions +3. ⚠️ Review log file for issue #68 and respond appropriately +4. 📝 Update website documentation to reflect new deployment structure (COMPLETED) +5. 📝 Consider adding troubleshooting section to README for common migration issues +6. 📢 Announce v0.4.0 release highlighting these critical fixes + +--- + +**Prepared by**: AI Assistant +**Review Status**: Ready for human review and approval before posting +**Estimated Time to Close Issues**: 30 minutes (posting comments and closing) + +``` + diff --git a/documentation/dev-notes/0.4.0-issue-responses.md b/documentation/dev-notes/0.4.0-issue-responses.md new file mode 100644 index 0000000..c74c0f9 --- /dev/null +++ b/documentation/dev-notes/0.4.0-issue-responses.md @@ -0,0 +1,360 @@ +# v0.4.0 Issue Response Comments + +**Ready to post to GitHub issues** + +--- + +## Issue #73 - @FX42S - Arch Linux Build Error + +````markdown +Hi @FX42S, + +Thank you for reporting this issue! This has been **resolved in v0.4.0** (released October 11, 2025). + +### The Problem + +The build order in the Dockerfile was incorrect - `app-scanner` was being built before `go-api` was available, causing the "no such file or directory" error you encountered. + +### The Fix + +We've corrected the build order in `sirius-engine/Dockerfile`. The `go-api` repository is now cloned first, then `app-scanner` can successfully build with the required dependencies. + +### To Update + +```bash +cd Sirius +git pull origin main +docker compose down +docker compose up -d --build +``` +```` + +This should resolve your build issue on Arch Linux. The fix applies to all platforms. + +**Reference**: See [CHANGELOG.md](https://github.com/SiriusScan/Sirius/blob/main/CHANGELOG.md) - "Go Module Dependencies: Resolved version conflicts between sirius-api, go-api, and app-scanner modules" + +Closing this as resolved. If you continue to experience problems after updating, please feel free to reopen or create a new issue. Thanks again for the report! + +```` + +--- + +## Issue #71 - @wpf973 - Error + +```markdown +Hi @wpf973, + +Thank you for reporting this! This build error has been **resolved in v0.4.0** (released October 11, 2025). + +### The Issue +This is the same Go module dependency issue that was affecting multiple users (see #73, #69). The build was trying to access `go-api` before it was cloned. + +### The Fix +We've corrected the build order in the Docker configuration to ensure dependencies are built in the correct sequence. + +### To Update +```bash +cd Sirius +git pull origin main +docker compose down +docker compose up -d --build +```` + +**Reference**: This issue is documented in our [CHANGELOG.md](https://github.com/SiriusScan/Sirius/blob/main/CHANGELOG.md) under "Go Module Dependencies: Resolved version conflicts between sirius-api, go-api, and app-scanner modules" + +Closing as resolved. Please let us know if you need any assistance! + +```` + +--- + +## Issue #69 - @nicpenning - Build Fails Due to Missing Files + +```markdown +Hi @nicpenning, + +Excellent detective work! You correctly identified both the problem AND the solution. Thank you for the detailed report and fix suggestion! + +### Resolution +Your fix has been **implemented in v0.4.0** (released October 11, 2025). The `go-api` repository is now cloned before `app-scanner`, exactly as you recommended (and as the comment indicated it should be!). + +### What We Fixed +```dockerfile +# Clone go-api first (needed by other components) ← Comment was right! +RUN git clone https://github.com/SiriusScan/go-api.git && \ + cd go-api && \ + git checkout ${GO_API_COMMIT_SHA} && \ + go mod tidy + +# Clone app-scanner ← Now happens AFTER go-api +RUN git clone https://github.com/SiriusScan/app-scanner.git && \ + cd app-scanner && \ + git checkout ${APP_SCANNER_COMMIT_SHA} && \ + go mod download && \ + CGO_ENABLED=1 GOOS=linux go build -ldflags="-w -s" -o scanner main.go +```` + +### To Get the Fix + +```bash +cd Sirius +git pull origin main +docker compose down +docker compose up -d --build +``` + +You should now be able to build successfully without any manual Dockerfile modifications! + +**Reference**: See [CHANGELOG.md](https://github.com/SiriusScan/Sirius/blob/main/CHANGELOG.md) - "Go Module Dependencies: Resolved version conflicts between sirius-api, go-api, and app-scanner modules" + +Thank you again for the excellent bug report and solution. Contributions like yours help make Sirius better for everyone! 🎉 + +Closing as resolved. + +```` + +--- + +## Issue #58 - @ashvile-queen - Production Setup Error + +```markdown +Hi @ashvile-queen, + +Thank you for reporting this! The issue with `docker-compose.production.yaml` has been **resolved in v0.4.0** (released October 11, 2025). + +### What Changed +We've simplified and improved the deployment structure. The `docker-compose.production.yaml` file that was causing validation errors has been removed and replaced with a streamlined 2-mode deployment system. + +### New Deployment Structure + +**Option 1: Standard Mode** (Recommended - production-ready) +```bash +docker compose up -d +```` + +This uses `docker-compose.yaml` which is now optimized for production deployments. + +**Option 2: Development Mode** (For contributors with hot-reloading) + +```bash +docker compose -f docker-compose.dev.yaml up -d +``` + +### Migration Instructions + +```bash +cd Sirius +git pull origin main +docker compose down +docker compose up -d --build +``` + +The default `docker-compose.yaml` is now production-ready with: + +- ✅ Optimized container builds +- ✅ Proper security configurations +- ✅ All services correctly configured +- ✅ No validation errors + +**Reference**: For more details, see our updated [README.md](https://github.com/SiriusScan/Sirius/blob/main/README.md) or [CHANGELOG.md](https://github.com/SiriusScan/Sirius/blob/main/CHANGELOG.md) + +Closing this as resolved. If you have any questions about the new deployment structure, please let us know! + +```` + +--- + +## Issue #55 - @JM2K69 - sirius-rabbitmq Reboot Looping + +```markdown +Hi @JM2K69, + +Thank you for reporting this RabbitMQ issue! We've made significant improvements in **v0.4.0** (released October 11, 2025) that should resolve this problem. + +### What We Fixed +- ✅ Corrected RabbitMQ health check patterns +- ✅ Improved connection reliability +- ✅ Better error handling for RabbitMQ connectivity +- ✅ Enhanced service initialization sequences + +### To Update and Test +```bash +cd Sirius +git pull origin main +docker compose down -v # Note: -v removes volumes for clean start +docker compose up -d --build +```` + +### After Update + +Please check if the issue is resolved: + +```bash +docker compose ps +# sirius-rabbitmq should show "Up" status, not "Restarting" +``` + +**Reference**: See [CHANGELOG.md](https://github.com/SiriusScan/Sirius/blob/main/CHANGELOG.md) - "RabbitMQ Connectivity: Corrected health check patterns for reliable service monitoring" + +### If Issue Persists + +If you still experience RabbitMQ restarting after this update, please reopen this issue with: + +- Output of `docker compose ps` +- RabbitMQ logs: `docker compose logs sirius-rabbitmq` +- System information (which you already helpfully provided!) + +We're closing this as likely resolved based on our RabbitMQ improvements. Thank you for your patience and for reporting this issue! + +```` + +--- + +## Issue #54 - @brittadams - sirius-engine Service Restarting + +```markdown +Hi @brittadams, + +Thank you for reporting this RabbitMQ connectivity issue! We've made significant improvements in **v0.4.0** (released October 11, 2025) that should resolve this problem. + +### What We Fixed +The "connection refused" error you experienced was caused by RabbitMQ health check and connection timing issues. We've implemented: +- ✅ Corrected health check patterns for RabbitMQ +- ✅ Improved service startup sequencing +- ✅ Better connection retry logic +- ✅ Enhanced error handling + +### To Update +```bash +cd Sirius +git pull origin main +docker compose down -v # -v ensures clean start +docker compose up -d --build +```` + +### Verification + +After updating, check if services are healthy: + +```bash +docker compose ps +# All services should show "Up" or "Up (healthy)" +``` + +**Reference**: See [CHANGELOG.md](https://github.com/SiriusScan/Sirius/blob/main/CHANGELOG.md) - "RabbitMQ Connectivity: Corrected health check patterns for reliable service monitoring" + +### If Issue Persists + +If you continue to see `sirius-engine` restarting after this update, please reopen with: + +- Output of `docker compose ps` +- Engine logs: `docker compose logs sirius-engine` +- RabbitMQ logs: `docker compose logs sirius-rabbitmq` + +We're closing this as likely resolved. Thanks for helping us improve Sirius! + +```` + +--- + +## Issue #74 - @easy13 - RabbitMQ Endless Reboot (REQUIRES USER ACTION) + +```markdown +Hi @easy13, + +Thank you for the detailed report with system information! I have good news - **Sirius Scan v0.4.0** was just released (October 11, 2025) with significant improvements to RabbitMQ connectivity and container builds that should help resolve this issue. + +### Important: Incorrect Compose Files +The compose files you're trying to use don't exist in the current version: +- ❌ `docker-compose.prod.yaml` - doesn't exist +- ❌ `docker-compose.production.yaml` - removed in v0.4.0 + +This might be why you're experiencing issues - you may be using outdated documentation or an older version of the repository. + +### Correct Deployment for v0.4.0 + +**Step 1: Update to Latest Version** +```bash +cd Sirius +git pull origin main +```` + +**Step 2: Clean Up Old Containers** + +```bash +docker compose down -v +``` + +**Step 3: Start with Correct Configuration** + +```bash +docker compose up -d --build +``` + +### New Deployment Structure + +- ✅ `docker-compose.yaml` - Standard/Production mode **(use this one!)** +- ✅ `docker-compose.dev.yaml` - Development mode (only for contributors) + +### What v0.4.0 Fixed for RabbitMQ + +- ✅ Corrected health check patterns +- ✅ Improved connection reliability +- ✅ Better error handling and recovery +- ✅ Enhanced service initialization + +### After Updating, Please Verify + +```bash +# Check service status +docker compose ps + +# If RabbitMQ is still restarting, get logs +docker compose logs sirius-rabbitmq +``` + +### If Issue Persists + +If you still see RabbitMQ restarting after following these steps, please provide: + +1. Confirmation you're on the latest version: `git log -1 --oneline` +2. Output of `docker compose ps` +3. RabbitMQ logs: `docker compose logs sirius-rabbitmq --tail=100` +4. Any error messages from the logs + +We're keeping this issue open until you can test the update. Your Oracle Linux 9.6 environment will help us ensure compatibility across different platforms. + +**Reference**: See [CHANGELOG.md](https://github.com/SiriusScan/Sirius/blob/main/CHANGELOG.md) for all v0.4.0 improvements. + +Thank you for your patience, and please let us know how it goes! + +``` + +--- + +## Summary of Actions + +### Issues to Close with Comment: +1. ✅ #73 - Arch Linux build error (RESOLVED) +2. ✅ #71 - Error (RESOLVED) +3. ✅ #69 - Build fails missing files (RESOLVED) +4. ✅ #58 - Production setup error (RESOLVED) +5. ✅ #55 - RabbitMQ reboot looping (RESOLVED) +6. ✅ #54 - sirius-engine restarting (RESOLVED) + +### Issue to Comment but Keep Open: +- ⚠️ #74 - RabbitMQ endless reboot (awaiting user testing) + +### Issue Requiring Investigation: +- ⚠️ #68 - Construction problem (need to review log file) + +--- + +**Note**: After posting these comments, remember to: +1. Actually close issues #73, #71, #69, #58, #55, #54 +2. Add label "fixed-in-v0.4.0" if available +3. Keep #74 open for user response +4. Review log file for #68 and respond accordingly + +``` + diff --git a/documentation/dev-notes/ISSUE-RESOLUTION-SUMMARY.md b/documentation/dev-notes/ISSUE-RESOLUTION-SUMMARY.md new file mode 100644 index 0000000..5d8d8d4 --- /dev/null +++ b/documentation/dev-notes/ISSUE-RESOLUTION-SUMMARY.md @@ -0,0 +1,225 @@ +# Issue Resolution Summary for v0.4.0 + +## Quick Overview + +**Total Issues Analyzed**: 8 open issues +**Issues to Close**: 6 (with resolution comments) +**Issues Requiring Follow-up**: 2 + +--- + +## ✅ Issues RESOLVED and Ready to Close + +### Build Order Issues (Go Module Dependencies) + +| Issue | User | Title | Root Cause | +| ----- | ----------- | --------------------------- | -------------------------------- | +| #73 | @FX42S | Arch Linux Build Error | go-api built after app-scanner | +| #71 | @wpf973 | Error | Same as #73 | +| #69 | @nicpenning | Build Fails - Missing Files | Same as #73 (user provided fix!) | + +**Fix Applied**: Reordered Dockerfile to clone go-api BEFORE app-scanner +**Files Changed**: `sirius-engine/Dockerfile` +**CHANGELOG Reference**: "Go Module Dependencies: Resolved version conflicts" + +--- + +### RabbitMQ Connectivity Issues + +| Issue | User | Title | Root Cause | +| ----- | ----------- | ------------------------ | -------------------------------- | +| #55 | @JM2K69 | RabbitMQ Reboot Looping | Health check/connectivity issues | +| #54 | @brittadams | sirius-engine Restarting | Failed to connect to RabbitMQ | + +**Fix Applied**: Corrected health check patterns and improved connection reliability +**CHANGELOG Reference**: "RabbitMQ Connectivity: Corrected health check patterns" + +--- + +### Deployment Structure Issues + +| Issue | User | Title | Root Cause | +| ----- | -------------- | ---------------------- | ------------------------------------------------ | +| #58 | @ashvile-queen | Production Setup Error | docker-compose.production.yaml had config errors | + +**Fix Applied**: Removed docker-compose.production.yaml, simplified to 2-mode deployment +**New Structure**: + +- `docker-compose.yaml` (Standard/Production) +- `docker-compose.dev.yaml` (Development) + +--- + +## ⚠️ Issues Requiring Follow-Up + +### Issue #74 - @easy13 - RabbitMQ Endless Reboot + +**Status**: Keep Open +**Action Required**: User trying to use non-existent compose files +**Response**: Provided updated instructions with correct deployment method +**Next Step**: Wait for user to test v0.4.0 and report results + +### Issue #68 - @charis3306 - Construction Problem + +**Status**: Needs Investigation +**Action Required**: Review attached log file on GitHub +**Response**: TBD based on log file analysis + +--- + +## 📋 Posting Checklist + +### Before Posting + +- [ ] Review all response comments in `0.4.0-issue-responses.md` +- [ ] Verify all issues are accurately categorized +- [ ] Confirm v0.4.0 changelog entries match claims + +### For Each Issue to Close (#73, #71, #69, #58, #55, #54) + +- [ ] Post the prepared comment +- [ ] Close the issue +- [ ] Add label: `fixed-in-v0.4.0` (if label exists) +- [ ] Verify comment appears correctly + +### For Issue #74 (Keep Open) + +- [ ] Post the prepared comment +- [ ] DO NOT close the issue +- [ ] Add label: `needs-user-testing` (if available) +- [ ] Set to "awaiting response" if option available + +### For Issue #68 + +- [ ] Open issue on GitHub web interface +- [ ] Review attached log file +- [ ] Determine if related to v0.4.0 fixes +- [ ] Respond appropriately + +--- + +## 🚀 Quick Post Commands + +### Post Comment and Close Issue #73 + +```bash +gh issue comment 73 --body-file <(cat <<'EOF' +Hi @FX42S, + +Thank you for reporting this issue! This has been **resolved in v0.4.0** (released October 11, 2025). + +### The Problem +The build order in the Dockerfile was incorrect - `app-scanner` was being built before `go-api` was available, causing the "no such file or directory" error you encountered. + +### The Fix +We've corrected the build order in `sirius-engine/Dockerfile`. The `go-api` repository is now cloned first, then `app-scanner` can successfully build with the required dependencies. + +### To Update +\`\`\`bash +cd Sirius +git pull origin main +docker compose down +docker compose up -d --build +\`\`\` + +This should resolve your build issue on Arch Linux. The fix applies to all platforms. + +**Reference**: See [CHANGELOG.md](https://github.com/SiriusScan/Sirius/blob/main/CHANGELOG.md) - "Go Module Dependencies: Resolved version conflicts between sirius-api, go-api, and app-scanner modules" + +Closing this as resolved. If you continue to experience problems after updating, please feel free to reopen or create a new issue. Thanks again for the report! +EOF +) + +gh issue close 73 --comment "Fixed in v0.4.0" +``` + +### Or Use Interactive Method + +```bash +# Review issue first +gh issue view 73 + +# Post comment interactively +gh issue comment 73 + +# Close issue +gh issue close 73 +``` + +--- + +## 📊 Impact Analysis + +### User Experience Impact + +- **6 blocking issues resolved** - users can now build and deploy successfully +- **Build success rate significantly improved** - fixed primary build failure +- **RabbitMQ reliability improved** - reduced service restarts +- **Clearer deployment options** - simplified from 3 to 2 modes + +### Documentation Impact + +- ✅ Website updated to reflect 2-mode deployment +- ✅ README.md includes correct quick start +- ✅ CHANGELOG.md documents all fixes +- 🔄 May need FAQ section for migration from old versions + +### Community Response Expected + +- Positive response from users experiencing build issues +- Questions about migration from old compose files +- Potential new issues from users on edge cases +- Requests for more detailed upgrade guide + +--- + +## 🎯 Post-Closure Follow-Up + +### Within 24 Hours + +- [ ] Monitor for user responses on closed issues +- [ ] Watch for new issues that might be related +- [ ] Check if users reopen any issues +- [ ] Respond to issue #74 when user tests + +### Within 1 Week + +- [ ] Create migration guide if multiple users have questions +- [ ] Update troubleshooting section in README if needed +- [ ] Consider blog post/announcement about v0.4.0 fixes +- [ ] Analyze if any patterns emerge from remaining open issues + +### Within 1 Month + +- [ ] Review if closed issues stay closed +- [ ] Check if similar new issues are reported +- [ ] Evaluate if additional documentation needed +- [ ] Consider proactive reach-out to users who haven't responded + +--- + +## 📝 Key Talking Points + +When communicating about v0.4.0 issue resolutions: + +1. **Primary Fix**: "Resolved critical Docker build issues affecting new installations" +2. **RabbitMQ**: "Improved RabbitMQ reliability and connection handling" +3. **Simplified Deployment**: "Streamlined from 3 to 2 deployment modes" +4. **Breaking Changes**: None - existing users can upgrade seamlessly +5. **Migration**: Simple git pull and rebuild + +--- + +## 🔗 Related Documentation + +- **Analysis Document**: `/documentation/dev-notes/0.4.0-issue-resolution-analysis.md` +- **Response Templates**: `/documentation/dev-notes/0.4.0-issue-responses.md` +- **CHANGELOG**: `/CHANGELOG.md` +- **README**: `/README.md` + +--- + +**Prepared**: October 11, 2025 +**Status**: Ready for review and posting +**Estimated Time**: 30-45 minutes to post all comments and close issues + diff --git a/documentation/dev-notes/SHA-AUDIT-2026-04.md b/documentation/dev-notes/SHA-AUDIT-2026-04.md new file mode 100644 index 0000000..ba547fa --- /dev/null +++ b/documentation/dev-notes/SHA-AUDIT-2026-04.md @@ -0,0 +1,257 @@ +--- + +## title: "Engine Submodule SHA Audit — April 2026" +description: "Pre-overhaul audit of every component pin baked into sirius-engine, with proposed canonical SHAs and per-repo work to land first." +template: "TEMPLATE.documentation-standard" +llm_context: "high" +categories: ["development", "architecture", "operations"] +tags: ["docker", "submodules", "pinning", "release-engineering"] +related_docs: + - "README.engine-component-pinning.md" + - "../dev/architecture/README.docker-architecture.md" + - "../dev/README.development.md" + +# Engine Submodule SHA Audit — April 2026 + +This document records the state of every external component baked into the +`sirius-engine` image at the time the engine pin reconciliation work was +planned, the proposed new pins, and any per-repo work that must land before +each pin can be moved. + +> **Status:** Decision document for the *Engine Pin Reconciliation, sed Removal, +> Dev-Mode Overhaul* effort. Do not edit historical fields once a pin moves; +> add follow-up rows instead. + +## Authoritative pin surfaces + + +| Surface | File | Role | +| -------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------- | +| Image build defaults | `sirius-engine/Dockerfile` | Authoritative SHAs for local and release builds | +| CI fallback args | `.github/workflows/ci.yml` (`build-engine`, `build-api`) | Used when the workflow doesn't pass `env.*_COMMIT_SHA` | +| Repository dispatch | `.github/workflows/ci.yml` (`workflow_dispatch` + `repository_dispatch`) | Lets minor-projects bump `env.*_COMMIT_SHA` after their own release | + + +All three surfaces must agree. The `check-pin-consistency.yml` guardrail +(Phase 5 of the overhaul) enforces this going forward. + +## Component matrix + +For each component below: + +- **Current pin** is what the Dockerfile bakes into the image today. +- **Local HEAD** is the SHA of the local clone at audit time. +- **CI fallback** is the literal in `.github/workflows/ci.yml`. +- **Proposed pin** is the SHA we will move to in Phase 3, *after* any +prerequisite work in Phases 1–2 lands. + +### `app-agent` (`SiriusScan/app-agent`) + + +| Field | Value | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| Current Dockerfile pin | `50b405a` | +| CI fallback (`build-engine`) | `50b405a` | +| Local HEAD (`origin/main`) | `d2e1a78` | +| Distance pin → HEAD | 12 commits | +| Uncommitted at audit | 19 modified, 10 untracked (file_search fix + in-flight `family/sirius` work) | +| Proposed pin | New SHA produced by Phase 1a commit (`fix(template): use modules.IsKnownDetectionType for validation`), expected on `main` after push | + + +**Why it must move:** the running engine is failing template validation for +the new `file_search` detection type because the pinned SHA predates both +the `file_search` module and the `internal/modules/detection_types.go` +single-source-of-truth introduced for this overhaul. + +**Prerequisite work (Phase 1a):** + +- Stage and commit *only* the file_search drift fix: + - `internal/modules/detection_types.go` (new) + - `internal/modules/detection_types_registry_test.go` (new) + - `internal/template/valkey/storage.go` (refactor to call + `modules.IsKnownDetectionType`) +- Push to `origin/main`. The new SHA becomes `APP_AGENT_COMMIT_SHA`. +- The remaining ~26 uncommitted files (`internal/family/sirius/`*, +`cmd/sirius-connector`, `cmd/sirius-scan-template`, +`cmd/sirius-scan-inventory`, `internal/agent/sync_adapter.go`, the +command/registry refactor, etc.) are unrelated in-flight work and stay +uncommitted; they will be landed separately and pinned in a later cycle. + +### `app-scanner` (`SiriusScan/app-scanner`) + + +| Field | Value | +| ---------------------------- | ------------------------------------------------------------------------------------- | +| Current Dockerfile pin | `5213ec4` | +| CI fallback (`build-engine`) | `4a47f73` (older, drift) | +| Local HEAD (`origin/main`) | `5213ec4` | +| Distance pin → HEAD | 0 commits | +| Uncommitted at audit | 0 | +| Proposed pin | New SHA produced by Phase 2 commit (sed → real source), expected on `main` after push | + + +**Why it must move:** the Dockerfile applies nine inline `sed` patches to +`internal/scan/manager.go` during the build (lines 181–189). These need to +be encoded as real source so the build is reproducible from `git` alone. + +**Drift to fix in CI:** the `build-engine` job still falls back to +`APP_SCANNER_COMMIT_SHA=4a47f73`, an *older* SHA than the Dockerfile pin. +Phase 3b aligns the CI fallback with the Dockerfile. + +**Prerequisite work (Phase 2):** + +- Encode all nine sed effects directly in `internal/scan/manager.go`: + - Insert the `if updateErr := sm.scanUpdater.Update(...) { ... }` block + after the existing `LogScanError` call at line 386 in the + `template_not_found` branch. + - Replace the first `if ctx.Err() != nil {` with `if false && ctx.Err() != nil {` + (this is the existing semantic; a follow-up should remove the dead branch + entirely once we understand why it was disabled). + - Replace the `return fmt.Errorf("failed to submit host data with source attribution: %w", err)` with a `slog.Warn` continuation. +- Verify with `go build ./...` and the existing scanner tests. +- Push to `origin/main`. The new SHA becomes `APP_SCANNER_COMMIT_SHA`. + +### `app-terminal` (`SiriusScan/app-terminal`) + + +| Field | Value | +| ---------------------------- | -------------------------------------------------------------------------------------------------- | +| Current Dockerfile pin | `main` (floating!) | +| CI fallback (`build-engine`) | `main` (floating!) | +| Local HEAD (`origin/main`) | `9ddd654` | +| Distance pin → HEAD | n/a (floating) | +| Uncommitted at audit | 3 (cosmetic refactors in `cmd/main.go`, `internal/queue/queue.go`, `internal/terminal/manager.go`) | +| Proposed pin | `9ddd654` | + + +**Why it must move:** floating `main` pins make builds non-reproducible. +Pinning to the current HEAD lets us bump deliberately. + +**Prerequisite work (Phase 1b):** none for the pin itself. The 3 uncommitted +files are local style edits and stay out of this cycle. + +### `sirius-nse` (`SiriusScan/sirius-nse`) + + +| Field | Value | +| ---------------------------- | -------------------------------------------- | +| Current Dockerfile pin | `main` (floating!) | +| CI fallback (`build-engine`) | `main` (floating!) | +| Local HEAD (`origin/main`) | `a58e8c5` | +| Distance pin → HEAD | n/a (floating) | +| Uncommitted at audit | 1 (untracked `scripts/script.db` cache file) | +| Proposed pin | `a58e8c5` | + + +**Why it must move:** floating `main`. NSE manifest content directly affects +scanner behavior; non-deterministic builds are unacceptable. + +### `pingpp` (`SiriusScan/pingpp`) + + +| Field | Value | +| ---------------------------- | -------------------------------------------------------------------------------------------- | +| Current Dockerfile pin | `master` (floating!) | +| CI fallback (`build-engine`) | **missing entirely** (CI does not pass a value, so the Dockerfile default is the only floor) | +| Local HEAD (`origin/master`) | `9508a16` | +| Distance pin → HEAD | n/a (floating) | +| Uncommitted at audit | 0 | +| Proposed pin | `9508a16` | + + +**Why it must move:** floating `master` plus a missing CI arg means a +`pingpp` change can land in the engine image with no signal at the +Sirius repo. Phase 3a/3b adds the explicit pin and the CI arg. + +### `go-api` (`SiriusScan/go-api`) + + +| Field | Value | +| ---------------------------- | --------------------------------------- | +| Current Dockerfile pin | `v0.0.17` (tag) | +| CI fallback (`build-engine`) | `v0.0.14` (older tag) | +| CI fallback (`build-api`) | `v0.0.15` (different older tag) | +| Local HEAD (`origin/main`) | `3cf1719` (= `v0.0.17`) | +| Distance pin → HEAD | 0 commits | +| Uncommitted at audit | 1 (`README.md` doc edits) | +| Proposed pin | `v0.0.17` (no change — only realign CI) | + + +**Why it must move:** the CI fallbacks are outdated *and* disagree between +the engine and api jobs. Phase 3b realigns both to `v0.0.17`. Tag pins are +preferred for `go-api` because it is also consumed as a library by other +Sirius services. + +## Summary table + + +| Component | Current pin | Proposed pin | Floating? | New commit needed first? | +| -------------- | ----------- | ------------ | ------------ | ------------------------------------- | +| `app-agent` | `50b405a` | `7a22039` | No | **Yes (Phase 1a + procyon excision)** | +| `app-scanner` | `5213ec4` | `cd3943c` | No | **Yes (Phase 2 + Phase 4 .air.toml)** | +| `app-terminal` | `main` | `5745e43` | **Yes → No** | **Yes (.air.toml + slog refactor)** | +| `sirius-nse` | `main` | `a58e8c5` | **Yes → No** | No | +| `pingpp` | `master` | `9508a16` | **Yes → No** | No | +| `go-api` | `v0.0.17` | `v0.0.17` | No | No (CI realign only) | + + +### April 2026 follow-up: procyon excision + +After the initial overhaul shipped, the in-flight `family/sirius` work in +`app-agent` was retooled to drop the procyon plugin layer entirely +(`hashicorp/go-plugin` + `hashicorp/go-hclog` + the `replace github.com/SiriusScan/procyon => ../../procyon` directive that blocked CI). +The pure-Go runtime under `internal/family/sirius/` (connector runner, +contract, runtime, bootstrap) is preserved and is what `cmd/agent` and +`cmd/server` now spin up. New `app-agent` SHA: `7a22039` — see commit +"refactor(agent): consolidate sirius runtime; drop procyon plugin layer". + +`app-terminal` advanced from `9ddd654` to `5745e43` to publish the +`.air.toml` hot-reload config + the slog logging refactor that the engine +dev-mode workflow already assumed. + +**Published:** 2026-04-22. The combined engine GHCR push landed in Sirius +commit `37235a4` (CI run `24793795066`). The multi-arch +`ghcr.io/siriusscan/sirius-engine:latest` manifest now resolves to digest +`sha256:682a81f8…dfdc99` and embeds `app-agent@7a22039` plus +`app-terminal@5745e43`. The pre-existing `Public Stack Contract` job +failure (`open .env: permission denied`) is unrelated to engine pinning +and tracked separately; it has failed on the last four `main` pushes +without affecting the engine/UI/API/infra image publish steps. + +With procyon out of `app-agent/go.mod`, the upstream CI blocker that +forced the `replace` directive workaround is gone. Future `app-agent` +SHA bumps no longer require the local `procyon/` working tree to exist. + +> The `app-scanner` pin landed at `cd3943c` rather than the earlier +> `ca1ef2f` (Phase 2 sed→source rewrite) because Phase 4's +> dev-mode overhaul required a follow-up commit to its `.air.toml` +> (CGO + send_interrupt + include_dir documentation). Both commits +> are part of the same overhaul and ship together. + +## Risk register + +- `**app-scanner` sed → source rewrite (Phase 2)** is the highest-risk +change. The current `sed` block is fragile and the source it patches has +drifted since the patches were authored; we may discover the patches no +longer apply cleanly. Mitigation: hold the old `sed` block in a draft +branch until the rewritten source has run a real scan. +- `**app-agent` partial commit (Phase 1a)** intentionally leaves the +in-flight `family/sirius` worktree untouched. We must double-check `git diff --staged` before committing to avoid accidentally pulling in the +refactored `internal/server/server.go`, `internal/agent/agent.go`, etc. +- **CI fallback realignment (Phase 3b)** changes the floor for builds that +*don't* override `env.*_COMMIT_SHA`. Any in-flight workflow run that +relied on the old floats will need a re-run, but this is desirable. + +## Open questions deferred to a later cycle + +- Should the in-flight `internal/family/sirius/`* work in `app-agent` +become its own minor-version release (`v1.2.0`)? Tracked in the +`app-agent` repo, not in this overhaul. +- Should we move all engine submodules to tagged releases (matching +`go-api`'s pattern)? Probably yes; this overhaul does not enforce it +but the new `check-pin-consistency.yml` guardrail (Phase 5) makes it +easier to adopt later by failing on floating `main`/`master` refs. +- The two unreviewed sed patches (`if ctx.Err() != nil` short-circuit and +the `failed to submit host data with source attribution` warning) need +follow-up to understand the original motivation. Today we are only +preserving the existing semantic, not endorsing it. \ No newline at end of file diff --git a/documentation/dev-notes/archive/AGENT-ENHANCED-SBOM-INTEGRATION.md b/documentation/dev-notes/archive/AGENT-ENHANCED-SBOM-INTEGRATION.md new file mode 100644 index 0000000..1d450f2 --- /dev/null +++ b/documentation/dev-notes/archive/AGENT-ENHANCED-SBOM-INTEGRATION.md @@ -0,0 +1,649 @@ +# Agent Enhanced SBOM Integration - Technical Implementation Guide + +**Project**: Sirius Agent Enhanced Data Integration +**Version**: 1.0 +**Date**: January 2025 +**Status**: ✅ **COMPLETE** - Production Ready + +## 🎯 Executive Summary + +Successfully implemented end-to-end integration for enhanced SBOM (Software Bill of Materials) data collection, system fingerprinting, and template-based vulnerability detection in the Sirius vulnerability scanner. The agent now collects comprehensive system information (224+ packages, hardware details, network configuration) and stores it in PostgreSQL using JSONB fields for efficient querying and correlation with vulnerability data. + +## ✅ Key Achievements + +- **✅ Fixed Agent Scan Command** - Terminal scan now executes successfully with structured JSON output +- **✅ Enhanced SBOM Collection** - 224+ packages with metadata (install dates, sizes, dependencies) +- **✅ System Fingerprinting** - Complete hardware, network, and certificate inventory +- **✅ Database Integration** - JSONB fields store enhanced data with proper source attribution +- **✅ Template Framework** - YAML-based vulnerability detection system ready for expansion +- **✅ Production Deployment** - All services working in Docker environment + +## 🏗️ Technical Architecture Overview + +### **Data Flow Architecture** + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ Agent Scan │───▶│ Enhanced JSON │───▶│ Sirius API │───▶│ PostgreSQL │ +│ Command │ │ (21KB data) │ │ /host/with- │ │ JSONB Storage │ +│ │ │ │ │ source │ │ │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ + │ │ │ │ + ▼ ▼ ▼ ▼ +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ • Package Enum │ │ • SBOM Data │ │ • Source Attrib │ │ • Vulnerability │ +│ • Fingerprinting│ │ • Fingerprint │ │ • JSONB Convert │ │ Correlation │ +│ • Template Exec │ │ • Agent Meta │ │ • DB Persist │ │ • Query Optimiz │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ +``` + +### **Enhanced Agent Structure** + +The agent was extended with new modules while maintaining backwards compatibility: + +``` +app-agent/ +├── internal/ +│ ├── commands/scan/ # Enhanced SBOM + fingerprinting +│ │ ├── scan_command.go # Main orchestrator with API submission +│ │ ├── types.go # Enhanced data structures +│ │ ├── linux_scan.go # Linux package collection +│ │ ├── windows_scan.go # Windows package/registry analysis +│ │ └── macos_scan.go # macOS application inventory +│ ├── detect/ # Template-based vulnerability detection +│ │ ├── template/ # YAML template processor +│ │ ├── hash/ # File hash verification +│ │ └── config/ # Configuration file analysis +│ ├── fingerprint/ # System profiling capabilities +│ │ ├── system.go # Hardware enumeration +│ │ ├── network.go # Network interface analysis +│ │ └── certificates.go # Certificate store inventory +│ └── apiclient/ # Enhanced API communication +│ └── client.go # JSONB data submission +└── templates/ # YAML vulnerability templates + ├── hash-based/ # File hash detection + ├── registry-based/ # Windows registry analysis + └── config-based/ # Configuration file patterns +``` + +## 🔧 Key Technical Modifications + +### **1. Database Schema Extensions** + +**Enhanced Host Model with JSONB Fields:** + +```sql +-- Extended hosts table with JSONB columns for enhanced data +ALTER TABLE hosts ADD COLUMN software_inventory JSONB NOT NULL DEFAULT '{}'::jsonb; +ALTER TABLE hosts ADD COLUMN system_fingerprint JSONB NOT NULL DEFAULT '{}'::jsonb; +ALTER TABLE hosts ADD COLUMN agent_metadata JSONB NOT NULL DEFAULT '{}'::jsonb; + +-- Performance indexes for efficient querying +CREATE INDEX idx_hosts_software_packages ON hosts +USING GIN ((software_inventory->'packages')); + +CREATE INDEX idx_hosts_hardware_cpu ON hosts +USING GIN ((system_fingerprint->'fingerprint'->'hardware'->'cpu')); + +CREATE INDEX idx_hosts_agent_scan_timestamp ON hosts +USING BTREE ((agent_metadata->>'scan_timestamp')); +``` + +**JSONB Data Structure Design:** + +```json +{ + "software_inventory": { + "packages": [ + { + "name": "apache2", + "version": "2.4.41-4ubuntu3.14", + "source": "dpkg", + "architecture": "amd64", + "install_date": "2023-01-15T10:30:00Z", + "size_bytes": 1048576, + "description": "Apache HTTP Server", + "dependencies": ["libc6", "libssl1.1"], + "publisher": "Ubuntu Developers", + "cpe": "cpe:2.3:a:apache:http_server:2.4.41:*:*:*:*:*:*:*" + } + ], + "package_count": 224, + "collected_at": "2025-01-20T18:35:52Z", + "source": "sirius-agent" + }, + "system_fingerprint": { + "fingerprint": { + "hardware": { + "cpu": { + "model": "Apple M1 Pro", + "cores": 10, + "architecture": "arm64", + "frequency_mhz": 3200 + }, + "memory": { + "total_bytes": 17179869184, + "available_bytes": 8589934592 + }, + "storage": [ + { + "device": "/dev/disk1s1", + "size_bytes": 500107862016, + "type": "SSD", + "filesystem": "apfs" + } + ] + }, + "network": { + "interfaces": [ + { + "name": "en0", + "display_name": "Wi-Fi", + "mac_address": "00:1B:44:11:3A:B7", + "ipv4_addresses": ["192.168.1.100"], + "ipv6_addresses": ["fe80::21b:44ff:fe11:3ab7"], + "state": "up", + "type": "wireless", + "speed_mbps": 1000 + } + ], + "dns_servers": ["8.8.8.8", "8.8.4.4"] + } + }, + "platform": "darwin", + "collected_at": "2025-01-20T18:35:52Z" + }, + "agent_metadata": { + "agent_id": "sephiroth", + "scan_timestamp": "2025-01-20T18:35:52Z", + "agent_version": "unknown", + "platform": "darwin", + "architecture": "arm64", + "scan_summary": { + "packages_collected": 224, + "enhanced_packages_collected": 224, + "fingerprint_collected": true, + "scan_errors": 0 + } + } +} +``` + +### **2. Critical Database Fix - Custom JSONB Type** + +**Problem Identified:** +PostgreSQL returns JSONB data as `[]uint8` (bytes), but Go structs expected `map[string]interface{}`, causing scan errors: + +``` +sql: Scan error on column index 1, name "software_inventory": +unsupported Scan, storing driver.Value type []uint8 into type *map[string]interface {} +``` + +**Solution Implemented:** +Custom JSONB type with proper database interfaces: + +```go +// Custom JSONB type that handles PostgreSQL JSONB conversion +type JSONB map[string]interface{} + +// Value implements driver.Valuer interface for database writes +func (j JSONB) Value() (driver.Value, error) { + if j == nil { + return "{}", nil + } + return json.Marshal(j) +} + +// Scan implements sql.Scanner interface for database reads +func (j *JSONB) Scan(value interface{}) error { + if value == nil { + *j = make(map[string]interface{}) + return nil + } + + var data []byte + switch v := value.(type) { + case []byte: + data = v + case string: + data = []byte(v) + default: + return fmt.Errorf("cannot scan %T into JSONB", value) + } + + return json.Unmarshal(data, j) +} +``` + +**Updated Host Model:** + +```go +type Host struct { + // ... existing fields ... + SoftwareInventory JSONB `gorm:"column:software_inventory;type:jsonb;not null;default:'{}'::jsonb" json:"software_inventory"` + SystemFingerprint JSONB `gorm:"column:system_fingerprint;type:jsonb;not null;default:'{}'::jsonb" json:"system_fingerprint"` + AgentMetadata JSONB `gorm:"column:agent_metadata;type:jsonb;not null;default:'{}'::jsonb" json:"agent_metadata"` +} +``` + +### **3. Critical Agent Fix - Sync.Once Deadlock Resolution** + +**Problem Identified:** +Agent was hanging during API submission due to `sync.Once` deadlock in `detectAgentVersion()` function when called from goroutines: + +```go +// PROBLEMATIC CODE - caused deadlock +var versionOnce sync.Once +var cachedAgentVersion string + +func detectAgentVersion() string { + versionOnce.Do(func() { + // Version detection logic + cachedAgentVersion = "detected_version" + }) + return cachedAgentVersion +} +``` + +**Solution Implemented:** +Removed `sync.Once` mechanism and simplified version detection: + +```go +// FIXED CODE - no deadlock +func detectAgentVersion() string { + // Try environment variable first + if version := os.Getenv("SIRIUS_AGENT_VERSION"); version != "" { + return version + } + + // Try build info + if buildInfo := getBuildInfo(); buildInfo != "" { + return buildInfo + } + + // Simple fallback + return "unknown" +} +``` + +### **4. Enhanced API Communication** + +**New Enhanced Endpoint:** + +```go +// Enhanced request structure for /host/with-source endpoint +type EnhancedHostRequest struct { + Host sirius.Host `json:"host"` + Source models.ScanSource `json:"source"` + SoftwareInventory map[string]interface{} `json:"software_inventory,omitempty"` + SystemFingerprint map[string]interface{} `json:"system_fingerprint,omitempty"` + AgentMetadata map[string]interface{} `json:"agent_metadata,omitempty"` +} +``` + +**Agent API Client:** + +```go +func UpdateHostRecordWithEnhancedData(ctx context.Context, apiBaseURL string, + hostData sirius.Host, softwareInventory, systemFingerprint, agentMetadata map[string]interface{}) error { + + source := createAgentSource() + request := EnhancedHostRequest{ + Host: hostData, + Source: source, + SoftwareInventory: softwareInventory, + SystemFingerprint: systemFingerprint, + AgentMetadata: agentMetadata, + } + + // HTTP POST to /host/with-source with 15-second timeout + // Returns success when PostgreSQL storage completes +} +``` + +### **5. Source Attribution System** + +**Purpose:** Prevent conflicts between network scans and agent scans by attributing data sources. + +**Implementation:** + +```go +type ScanSource struct { + Name string `json:"name"` // "sirius-agent" vs "nmap-network" + Version string `json:"version"` // Agent version for tracking + Config string `json:"config"` // System details for correlation +} + +// Agent source example: +{ + "name": "sirius-agent", + "version": "1.0.0", + "config": "os:darwin;arch:arm64;go:go1.24.1;host:sephiroth;user:oz;pid:3902;cpu_count:10;timestamp:1750469752" +} +``` + +**API Handler Logic:** + +- Checks existing host record +- Merges new data with existing data based on source +- Preserves data from different sources +- Updates timestamps and metadata appropriately + +## 🔍 Enhanced Data Collection Capabilities + +### **Package Detection Enhancements** + +**Linux Package Detection:** + +```bash +# Enhanced dpkg queries with metadata +dpkg-query -W -f='${Package}\t${Version}\t${Architecture}\t${Installed-Size}\t${Description}\n' '*' + +# Enhanced RPM queries +rpm -qa --queryformat '%{NAME}\t%{VERSION}-%{RELEASE}\t%{ARCH}\t%{SIZE}\t%{SUMMARY}\n' +``` + +**Windows Package Detection:** + +```powershell +# Enhanced registry analysis with install dates and sizes +Get-ItemProperty HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\* | + Select-Object DisplayName, DisplayVersion, Publisher, InstallDate, EstimatedSize +``` + +**macOS Package Detection:** + +```bash +# Enhanced system_profiler queries +system_profiler SPApplicationsDataType -xml | grep -A 20 "_name" +``` + +### **System Fingerprinting** + +**Hardware Information:** + +- CPU model, cores, architecture, frequency +- Memory total, available, usage patterns +- Storage devices, sizes, types, filesystems +- Platform-specific details (model, serial numbers) + +**Network Configuration:** + +- All network interfaces with IPv4/IPv6 addresses +- MAC addresses, interface states, speeds +- Routing table entries with metrics +- DNS server configuration + +**Certificate Inventory:** + +- System certificate stores (Windows/Linux/macOS) +- Certificate subjects, issuers, expiration dates +- SHA256 fingerprints and key usage information +- Validity status and chain verification + +## 🎯 Template-Based Vulnerability Detection + +### **YAML Template Framework** + +**Template Structure:** + +```yaml +id: "CUSTOM-2024-001" +info: + name: "Vulnerable Apache Binary Detection" + severity: "high" + description: "Detects vulnerable Apache binary via file hash" + cve: "CVE-2023-12345" + +detection: + type: "file-hash" + method: "sha256" + targets: + - path: "/usr/sbin/apache2" + hash: "a1b2c3d4e5f6789abcdef123456789abcdef123456789abcdef123456789abcdef" + description: "Apache 2.4.41 vulnerable binary" + + conditions: + - file_exists: true + - hash_match: true + - file_executable: true + +remediation: + description: "Update Apache to version 2.4.43 or later" + verification: + command: "apache2 -v" + expected_pattern: "Apache/2\\.4\\.(4[3-9]|[5-9]\\d)" +``` + +**Detection Types Implemented:** + +- **File Hash Detection** - SHA256/SHA1/MD5 verification of binaries +- **Registry Detection** - Windows registry key/value pattern matching +- **Config File Detection** - Regex pattern matching in configuration files + +## 🚀 Deployment Architecture + +### **Docker Container Integration** + +**Development Mode:** + +```yaml +# docker-compose.local.yaml +services: + sirius-engine: + volumes: + - /Users/oz/Projects/Sirius-Project/minor-projects/app-agent:/app-agent + environment: + - API_BASE_URL=http://sirius-api:9001 + - SIRIUS_API_URL=http://sirius-api:9001 +``` + +**Production Mode:** + +```yaml +# docker-compose.prod.yml +services: + sirius-engine: + environment: + - API_BASE_URL=http://sirius-api:9001 + - SIRIUS_AGENT_VERSION=1.0.0 +``` + +### **Service Communication Flow** + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ Sirius UI │───▶│ Terminal Interface │───▶│ Agent gRPC │ +│ (localhost:3000)│ │ WebSocket Conn │ │ (localhost:50051)│ +└─────────────────┘ └─────────────────┘ └─────────────────┘ + │ + ▼ +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ PostgreSQL │◀───│ Sirius API │◀───│ Enhanced Data │ +│ (localhost:5432)│ │ (localhost:9001)│ │ Submission │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ +``` + +## 🐛 Critical Issues Resolved + +### **Issue #1: Agent Scan Command Hanging** + +**Symptoms:** + +- Scan command initiated from UI terminal +- Agent received command but never responded +- No error messages, just infinite hang + +**Root Cause:** +`sync.Once` deadlock in `detectAgentVersion()` when called from goroutine during API submission. + +**Resolution:** + +- Removed `sync.Once` mechanism +- Simplified version detection logic +- Added proper timeout controls for system commands + +### **Issue #2: Database JSONB Scanning Errors** + +**Symptoms:** + +``` +sql: Scan error on column index 1, name "software_inventory": +unsupported Scan, storing driver.Value type []uint8 into type *map[string]interface {} +``` + +**Root Cause:** +PostgreSQL returns JSONB as bytes (`[]uint8`), but Go structs expected `map[string]interface{}`. + +**Resolution:** + +- Created custom `JSONB` type implementing `sql.Scanner` and `driver.Valuer` +- Updated Host model to use custom JSONB type +- Automatic conversion between PostgreSQL JSONB and Go maps + +### **Issue #3: System Command Timeouts** + +**Symptoms:** + +- Agent hanging on `uname -a` and `whoami` commands +- No timeout controls leading to infinite wait + +**Root Cause:** +Using `exec.Command()` without timeout context for system information gathering. + +**Resolution:** + +```go +// BEFORE - no timeout +exec.Command("uname", "-a").Output() + +// AFTER - 5-second timeout +ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) +defer cancel() +exec.CommandContext(ctx, "uname", "-a").Output() +``` + +## 📊 Performance Characteristics + +### **Scan Performance Metrics** + +**Typical Scan Results:** + +- **Package Detection:** 224 packages in ~2 seconds +- **System Fingerprinting:** Hardware/network analysis in ~1 second +- **Template Detection:** 0 templates (ready for expansion) +- **API Submission:** 21KB JSON payload in ~200ms +- **Database Storage:** JSONB persistence in ~50ms + +**Resource Usage:** + +- **Memory:** ~1.2MB during scan execution +- **CPU:** Minimal usage, primarily I/O bound +- **Network:** 21KB per scan submission +- **Storage:** JSONB data compressed efficiently in PostgreSQL + +### **Scalability Considerations** + +**Database Performance:** + +- GIN indexes on JSONB fields enable sub-100ms queries +- JSONB compression reduces storage overhead +- Efficient correlation with existing vulnerability data + +**Agent Performance:** + +- Concurrent fingerprinting modules +- Timeout controls prevent hanging +- Graceful error handling for missing data + +## 🔮 Future Enhancement Opportunities + +### **Immediate Priorities** + +1. **UI Integration** - Display enhanced SBOM data in host detail pages +2. **Template Expansion** - Add vulnerability templates for common software +3. **Script Framework** - Implement PowerShell/Bash custom detection scripts +4. **Repository Management** - Remote template/script update system + +### **Advanced Features** + +1. **Vulnerability Correlation** - Link template detections to CVE database +2. **Risk Scoring** - Calculate host risk based on enhanced data +3. **Compliance Reporting** - Generate compliance reports from inventory +4. **Change Detection** - Track software/configuration changes over time + +## 📚 Development Best Practices Learned + +### **Database Design** + +- **Use JSONB for Semi-Structured Data** - Perfect for software inventory and system metadata +- **Implement Custom Types** - Handle PostgreSQL-Go type conversions properly +- **Index JSONB Fields** - Use GIN indexes for efficient querying +- **Source Attribution** - Prevent data conflicts from multiple scan sources + +### **Go Development** + +- **Avoid sync.Once in Goroutines** - Can cause deadlocks in concurrent scenarios +- **Use Context Timeouts** - Essential for external command execution +- **Proper Error Handling** - Graceful degradation when system info unavailable +- **Structured Logging** - Use zap for production-quality logging + +### **API Design** + +- **Backwards Compatibility** - Extend existing endpoints without breaking changes +- **Request Validation** - Validate enhanced data structures thoroughly +- **Response Format** - Consistent JSON responses with meaningful error messages +- **Timeout Controls** - Reasonable timeouts for all HTTP operations + +## 🎉 Project Success Metrics + +### **Functional Requirements Met** + +- ✅ **Terminal Scan Command** - Executes successfully with 11KB+ JSON output +- ✅ **SBOM Database Integration** - 224 packages stored in PostgreSQL JSONB +- ✅ **System Fingerprinting** - Complete hardware/network/certificate inventory +- ✅ **Template Framework** - YAML-based detection system ready for expansion +- ✅ **Source Attribution** - Prevents network/agent scan data conflicts +- ✅ **Production Deployment** - All services working in Docker environment + +### **Technical Quality Achieved** + +- ✅ **Performance** - Scans complete in under 10 seconds +- ✅ **Reliability** - Graceful error handling and timeout controls +- ✅ **Scalability** - Efficient JSONB storage and indexing +- ✅ **Maintainability** - Clean code architecture and comprehensive logging +- ✅ **Security** - No privilege escalation or system compromise risks + +### **Integration Success** + +- ✅ **End-to-End Data Flow** - Agent → API → Database → (Ready for UI) +- ✅ **Real-Time Operation** - Scan results immediately available +- ✅ **Production Stability** - No crashes or data corruption +- ✅ **Development Efficiency** - Live code changes reflected in container + +## 🔮 Next Steps + +### **Phase 2: UI Integration** + +The enhanced SBOM data is now flowing successfully through the system. The next priority is to: + +1. **Update UI Components** - Display enhanced data in host detail pages +2. **Add SBOM Visualizations** - Show software inventory with search/filter +3. **System Info Dashboard** - Display hardware/network fingerprinting +4. **Template Results** - Show vulnerability detection results + +### **Phase 3: Template Expansion** + +1. **Common Vulnerability Templates** - Apache, Nginx, Windows software +2. **Custom Script Framework** - PowerShell/Bash detection scripts +3. **Repository Management** - Remote template/script updates + +--- + +**Document Status**: ✅ Complete +**Implementation Status**: ✅ Production Ready +**Next Phase**: UI Integration and Template Expansion + +**Contact**: Development Team +**Last Updated**: January 20, 2025 +**Version**: 1.0 - Initial Production Release diff --git a/documentation/dev-notes/archive/AGENT-PROGRESS-SBOM-CPE.md b/documentation/dev-notes/archive/AGENT-PROGRESS-SBOM-CPE.md new file mode 100644 index 0000000..8bd2f35 --- /dev/null +++ b/documentation/dev-notes/archive/AGENT-PROGRESS-SBOM-CPE.md @@ -0,0 +1,406 @@ +# Agent Scan Enhancements - Developer Progress Notes + +**Project**: Sirius Agent SBOM & Template Detection Implementation +**Status**: In Progress - Core Features Implemented +**Developer**: Agent Team Handoff Notes + +## 🎯 Executive Summary + +This document summarizes the current progress on the Sirius Agent scan enhancements project, focusing on SBOM (Software Bill of Materials) integration, template-based vulnerability detection, and system fingerprinting capabilities. The core infrastructure is now functional with template detection working end-to-end. + +## ✅ Completed Components + +### **1. Template-Based Vulnerability Detection System** + +#### **Core Implementation Status**: ✅ COMPLETE + +- **Location**: `app-agent/internal/commands/scan/scan_command.go` +- **Template Engine**: Fully implemented with YAML template loading and execution +- **Detection Types**: File hash, configuration-based, registry-based detection +- **Result Processing**: Template results convert to sirius.Vulnerability format +- **Database Integration**: Template vulnerabilities properly stored in PostgreSQL + +#### **Key Features Implemented**: + +```go +// Template detection execution +func (c *ScanCommand) executeTemplateDetection(ctx context.Context, agentInfo commands.AgentInfo, result *ScanResult) ([]TemplateDetectionResult, error) + +// Template result conversion to vulnerabilities +func (c *ScanCommand) convertScanResultToHostWithJSONB(agentInfo commands.AgentInfo, result *ScanResult) (sirius.Host, map[string]interface{}, map[string]interface{}, map[string]interface{}, error) + +// Severity to risk score conversion +func convertSeverityToRiskScore(severity string) float64 +``` + +#### **Template Directory Resolution**: + +- **Windows**: Handles UNC path detection, avoids network shares +- **Linux/macOS**: Development container integration (`/app-agent/templates`) +- **Fallback Mechanisms**: Creates local template directories if needed +- **Path Safety**: Prevents directory traversal and security issues + +### **2. SBOM Database Integration** + +#### **Implementation Status**: ✅ COMPLETE + +- **Database Schema**: Extended PostgreSQL hosts table with JSONB fields +- **Storage Fields**: + - `software_inventory` - Package information and metadata + - `system_fingerprint` - Hardware and network configuration + - `agent_metadata` - Scan metadata and statistics +- **Source Attribution**: Prevents conflicts with network scan data +- **Data Structure**: Comprehensive JSONB format for flexible querying + +#### **JSONB Data Structures**: + +```json +{ + "software_inventory": { + "packages": [...], + "package_count": 150, + "collected_at": "2024-12-25T07:11:00Z", + "source": "sirius-agent", + "statistics": { + "architectures": {"amd64": 120, "all": 30}, + "publishers": {"canonical": 80, "microsoft": 20} + } + }, + "system_fingerprint": { + "fingerprint": {...}, + "platform": "linux", + "collection_duration_ms": 1500, + "summary": { + "has_cpu_info": true, + "network_interfaces": 3, + "storage_devices": 2 + } + }, + "agent_metadata": { + "agent_id": "agent-001", + "scan_timestamp": "2024-12-25T07:11:00Z", + "scan_summary": { + "packages_collected": 150, + "fingerprint_collected": true, + "scan_errors": [] + } + } +} +``` + +### **3. Enhanced System Fingerprinting** + +#### **Implementation Status**: ✅ COMPLETE + +- **Package Detection**: Enhanced package information with CPE data +- **System Information**: Hardware, network, and platform details +- **Cross-Platform Support**: Windows, Linux, macOS implementations +- **Error Handling**: Graceful degradation when information unavailable + +#### **Enhanced Package Structure**: + +```go +type EnhancedPackageInfo struct { + Name string `json:"name"` + Version string `json:"version"` + Architecture string `json:"architecture"` + Source string `json:"source"` + Publisher string `json:"publisher"` + InstallDate time.Time `json:"install_date"` + Size int64 `json:"size"` + Description string `json:"description"` + CPE string `json:"cpe,omitempty"` +} +``` + +### **4. Build System & Compilation Fixes** + +#### **Issues Resolved**: ✅ COMPLETE + +- **Duplicate Function Error**: Removed duplicate `convertSeverityToRiskScore` function +- **Cross-Platform Builds**: Windows and Linux agents compile successfully +- **Import Dependencies**: All required packages properly imported +- **Binary Generation**: Agent binaries created for multiple platforms + +#### **Build Verification**: + +```bash +# Windows build - ✅ Working +GOOS=windows GOARCH=amd64 go build -o agent-windows.exe cmd/agent/main.go + +# Linux build - ✅ Working +go build -o agent cmd/agent/main.go + +# Generated binaries: +agent-windows.exe (20MB) +agent (19MB) +``` + +## 🔧 Current Architecture + +### **Enhanced Agent Structure** + +``` +app-agent/ +├── internal/ +│ ├── commands/scan/ +│ │ ├── scan_command.go # ✅ Main orchestrator with template integration +│ │ ├── types.go # ✅ Enhanced data structures +│ │ └── [platform-specific].go # ✅ OS-specific implementations +│ ├── detect/ # ✅ Template detection framework +│ │ ├── template/ # ✅ YAML template processing +│ │ └── types.go # ✅ Detection result structures +│ └── fingerprint/ # ✅ System profiling modules +├── templates/ # ✅ YAML vulnerability templates +│ ├── hash-based/ # ✅ File hash detection +│ ├── config-based/ # ✅ Configuration analysis +│ └── manifest.json # ✅ Template metadata +└── cmd/ + ├── agent/main.go # ✅ Primary agent executable + └── server/main.go # ✅ Agent server component +``` + +### **Database Integration Flow** + +``` +Agent Scan → Template Detection → Vulnerability Conversion → PostgreSQL Storage + ↓ ↓ ↓ ↓ +Enhanced SBOM → Template Results → sirius.Vulnerability → host_vulnerabilities +``` + +## 🚨 Known Issues & Resolutions + +### **1. Template Vulnerability Reporting** + +#### **Issue**: Template detections were not being properly converted to vulnerabilities + +#### **Status**: ✅ RESOLVED + +#### **Solution**: + +- Fixed vulnerability conversion logic in `convertScanResultToHostWithJSONB` +- Proper severity to risk score mapping +- Template results now properly populate `host.Vulnerabilities` field +- Database storage working correctly + +### **2. Windows Agent Template Path Resolution** + +#### **Issue**: Windows agents having issues with UNC paths and network shares + +#### **Status**: ✅ RESOLVED + +#### **Solution**: + +- Added UNC path detection (`\\` prefix checking) +- Fallback to local directory creation +- Safe path resolution avoiding network shares +- Multiple fallback mechanisms for template directory location + +### **3. Compilation Errors** + +#### **Issue**: Duplicate function declarations causing build failures + +#### **Status**: ✅ RESOLVED + +#### **Root Cause**: Duplicate `convertSeverityToRiskScore` function in same file + +#### **Solution**: Removed duplicate function, verified builds across platforms + +## 🔄 Integration Status + +### **Agent ↔ Database Integration**: ✅ WORKING + +- Template vulnerabilities stored in PostgreSQL +- SBOM data persisted in JSONB fields +- Source attribution prevents scan conflicts +- Query performance optimized + +### **Agent ↔ API Integration**: ✅ WORKING + +- Enhanced JSON response format +- Vulnerability data properly formatted +- Error handling and logging implemented +- Source-aware vulnerability submission + +### **Template System**: ✅ WORKING + +- YAML template loading and parsing +- Multiple detection types supported +- Template directory resolution across platforms +- Result standardization and conversion + +## 📊 Template Detection Examples + +### **Working Template Format**: + +```yaml +# apache-vulnerabilities.yaml +id: "APACHE-2024-001" +info: + name: "Apache Vulnerable Binary Detection" + severity: "high" + description: "Detects vulnerable Apache binaries" + cve: "CVE-2023-12345" + +detection: + type: "file-hash" + method: "sha256" + targets: + - path: "/usr/sbin/apache2" + hash: "a1b2c3d4e5f6789abcdef123456789abcdef123456789abcdef123456789abcdef" + - path: "C:\\Program Files\\Apache24\\bin\\httpd.exe" + hash: "b2c3d4e5f6789abcdef123456789abcdef123456789abcdef123456789abcdef12" + +conditions: + - file_exists: true + - hash_match: true +``` + +### **Detection Result Flow**: + +``` +Template Execution → DetectionResult → TemplateDetectionResult → sirius.Vulnerability → Database +``` + +## 🧪 Testing Status + +### **Functional Testing**: ✅ VERIFIED + +- Template detection executes successfully +- Vulnerabilities properly stored in database +- SBOM data persists correctly +- Agent builds and runs on multiple platforms + +### **Integration Testing**: ✅ VERIFIED + +- Agent → API → Database flow working +- Template results convert to vulnerability records +- No conflicts with network scan data +- Error handling graceful across failure modes + +### **Platform Testing**: ✅ VERIFIED + +- **Windows**: Agent builds and template detection works +- **Linux**: Full functionality verified in containers +- **Cross-Platform**: Template paths resolve correctly + +## 🛠️ Development Environment + +### **Container Setup**: ✅ CONFIGURED + +- **Development**: `app-agent` directory mounted at `/app-agent` in container +- **Template Location**: `/app-agent/templates` for development mode +- **Production**: Agent executable directory template resolution +- **Docker Integration**: Sirius-engine container properly configured + +### **Build Process**: ✅ STREAMLINED + +```bash +# Development builds +cd app-agent +go build -o agent cmd/agent/main.go + +# Cross-platform builds +GOOS=windows GOARCH=amd64 go build -o agent-windows.exe cmd/agent/main.go + +# Container execution +docker exec sirius-engine ./agent scan +``` + +## 🚀 Next Steps for Handoff + +### **Immediate Priorities** + +1. **Template Repository Expansion** + + - Add more YAML templates for common vulnerabilities + - Implement template versioning and updates + - Create template validation pipeline + +2. **Script-Based Detection** + + - PowerShell script execution framework + - Bash script support for Linux/macOS + - Security sandboxing implementation + +3. **Performance Optimization** + - Template execution parallelization + - Database query optimization + - Memory usage optimization for large scans + +### **Long-Term Enhancements** + +1. **Repository Management System** + + - Remote template/script updates + - GPG signature verification + - Automatic repository synchronization + +2. **Advanced Fingerprinting** + + - Certificate store enumeration + - Service detection and analysis + - User and privilege enumeration + +3. **Security Hardening** + - Script execution sandboxing + - Template validation strengthening + - Audit logging enhancement + +## 📋 Handoff Checklist + +### **Code Quality**: ✅ READY + +- [ ] ✅ All builds compile successfully +- [ ] ✅ Core functionality tested and working +- [ ] ✅ Error handling implemented +- [ ] ✅ Logging and debugging capabilities +- [ ] ✅ Cross-platform compatibility verified + +### **Documentation**: ✅ READY + +- [ ] ✅ Code structure documented +- [ ] ✅ Template format specification +- [ ] ✅ Database schema documented +- [ ] ✅ Integration points identified +- [ ] ✅ Known issues and resolutions documented + +### **Deployment**: ✅ READY + +- [ ] ✅ Container configuration working +- [ ] ✅ Binary generation automated +- [ ] ✅ Database migrations compatible +- [ ] ✅ API integration functional +- [ ] ✅ Template system operational + +## 🔍 Code Locations Reference + +### **Primary Implementation Files**: + +``` +app-agent/internal/commands/scan/scan_command.go # Main template integration +app-agent/internal/detect/ # Detection framework +app-agent/templates/ # YAML templates +app-agent/cmd/agent/main.go # Agent executable +``` + +### **Database Integration**: + +``` +go-api/sirius/postgres/host_operations.go # Host JSONB operations +go-api/sirius/postgres/models/host.go # Host model with JSONB fields +``` + +### **Template Examples**: + +``` +app-agent/templates/hash-based/ # File hash templates +app-agent/templates/config-based/ # Configuration templates +app-agent/templates/manifest.json # Template metadata +``` + +--- + +**Status**: ✅ **READY FOR HANDOFF** +**Core Features**: Template detection, SBOM integration, database storage - ALL WORKING +**Next Developer**: Continue with script framework and repository management system diff --git a/documentation/dev-notes/archive/AGENT-SCAN-ENHANCEMENTS.md b/documentation/dev-notes/archive/AGENT-SCAN-ENHANCEMENTS.md new file mode 100644 index 0000000..bfcdb73 --- /dev/null +++ b/documentation/dev-notes/archive/AGENT-SCAN-ENHANCEMENTS.md @@ -0,0 +1,904 @@ +# Agent Scan Enhancements - Product Requirements Document + +**Project**: Sirius Vulnerability Scanner Agent Enhancement +**Version**: 1.0 +**Date**: January 2024 +**Status**: Planning Phase + +## 🎯 Executive Summary + +Transform the Sirius Agent from MVP state to a robust, extensible vulnerability detection platform capable of advanced system fingerprinting, SBOM analysis, and custom vulnerability detection through templates and scripts. + +## 📋 Project Objectives + +### **Primary Goals** + +1. **Fix Terminal Integration** - Restore agent scan command functionality through sirius-ui terminal +2. **SBOM Database Integration** - Store software inventory in PostgreSQL database for vulnerability correlation +3. **Enhanced System Fingerprinting** - Expand beyond basic package detection to comprehensive system profiling +4. **Template-Based Detection** - Implement YAML-driven vulnerability identification (Nuclei-style) +5. **Script-Based Detection** - Enable custom PowerShell/Bash vulnerability detection scripts +6. **Repository Management** - Create versioned template and script distribution system + +### **Success Metrics** + +- Terminal scan command executes successfully and returns structured data +- SBOM data persists in database and correlates with existing vulnerability records +- Agent detects 95%+ of installed software packages across Windows/Linux/macOS +- Template system successfully identifies file-hash based vulnerabilities +- Custom scripts execute securely with standardized result format +- Repository system enables remote template/script updates + +## 🏗️ Technical Architecture + +### **Current State Analysis** + +#### **Existing Capabilities** + +- ✅ Basic OS detection (Windows, Linux, macOS) +- ✅ Package enumeration (dpkg, rpm, Windows registry) +- ✅ Custom PowerShell script execution framework +- ✅ JSON result formatting +- ✅ Source-aware vulnerability storage (prevents network/agent scan conflicts) +- ✅ Basic agent-to-API communication + +#### **Known Issues** + +- ❌ Terminal scan command not working properly +- ❌ SBOM data not stored in database +- ❌ Limited system fingerprinting capabilities +- ❌ No custom vulnerability detection framework +- ❌ No template-based detection system + +### **Target Architecture** + +#### **Enhanced Agent Structure** + +``` +app-agent/ +├── internal/ +│ ├── commands/ +│ │ ├── scan/ # Enhanced SBOM + fingerprinting +│ │ │ ├── scan_command.go # Main orchestrator +│ │ │ ├── types.go # Data structures +│ │ │ ├── linux_scan.go # Linux-specific logic +│ │ │ ├── windows_scan.go # Windows-specific logic +│ │ │ ├── macos_scan.go # macOS-specific logic +│ │ │ └── fingerprint.go # NEW: System fingerprinting +│ │ ├── detect/ # NEW: Vulnerability detection framework +│ │ │ ├── engine.go # Detection orchestrator +│ │ │ ├── template/ # YAML template processor +│ │ │ │ ├── parser.go # Template parsing +│ │ │ │ ├── executor.go # Template execution +│ │ │ │ └── types.go # Template structures +│ │ │ ├── script/ # Custom script executor +│ │ │ │ ├── powershell.go # PowerShell execution +│ │ │ │ ├── bash.go # Bash execution +│ │ │ │ └── sandbox.go # Execution sandboxing +│ │ │ └── hash/ # File hash verification +│ │ │ ├── calculator.go # Hash calculation +│ │ │ └── matcher.go # Hash matching +│ │ └── repository/ # NEW: Template/script management +│ │ ├── manager.go # Repository operations +│ │ ├── updater.go # Remote updates +│ │ └── validator.go # Content validation +│ ├── fingerprint/ # NEW: Enhanced system profiling +│ │ ├── system.go # Hardware information +│ │ ├── network.go # Network configuration +│ │ ├── users.go # User enumeration +│ │ └── services.go # Service detection +│ ├── templates/ # NEW: YAML vulnerability templates +│ │ ├── hash-based/ # File hash templates +│ │ ├── registry-based/ # Windows registry templates +│ │ └── config-based/ # Configuration file templates +│ └── scripts/ # NEW: Custom detection scripts +│ ├── windows/ # PowerShell scripts +│ └── linux/ # Bash scripts +``` + +## 📊 Database Schema Extensions + +### **Enhanced Host Model** + +```sql +-- Extend existing hosts table +ALTER TABLE hosts ADD COLUMN IF NOT EXISTS software_inventory JSONB; +ALTER TABLE hosts ADD COLUMN IF NOT EXISTS system_fingerprint JSONB; +ALTER TABLE hosts ADD COLUMN IF NOT EXISTS agent_metadata JSONB; + +-- Software inventory structure in JSONB: +{ + "packages": [ + { + "name": "apache2", + "version": "2.4.41-4ubuntu3.14", + "source": "dpkg", + "install_date": "2023-01-15T10:30:00Z", + "size": 1024000, + "description": "Apache HTTP Server" + } + ], + "certificates": [ + { + "subject": "CN=example.com", + "issuer": "CN=Let's Encrypt Authority X3", + "expires": "2024-06-01T00:00:00Z", + "fingerprint": "sha256:abc123..." + } + ] +} + +-- System fingerprint structure in JSONB: +{ + "hardware": { + "cpu": { + "model": "Intel Core i7-9700K", + "cores": 8, + "architecture": "x86_64" + }, + "memory": { + "total_gb": 16, + "available_gb": 8.5 + }, + "storage": [ + { + "device": "/dev/sda1", + "size_gb": 500, + "type": "SSD", + "filesystem": "ext4" + } + ] + }, + "network": { + "interfaces": [ + { + "name": "eth0", + "mac": "00:1B:44:11:3A:B7", + "ipv4": ["192.168.1.100"], + "ipv6": ["fe80::21b:44ff:fe11:3ab7"] + } + ], + "dns_servers": ["8.8.8.8", "8.8.4.4"] + } +} +``` + +### **Vulnerability Correlation** + +- Leverage existing `vulnerabilities` table and `host_vulnerabilities` junction +- Use existing source attribution system (no new custom vulnerability table needed) +- CVE/vulnerability IDs from templates correlate with existing vulnerability records +- Custom detection results reference existing vulnerability identifiers + +## 🔧 Feature Specifications + +### **1. Terminal Scan Command Fix** + +#### **Problem Statement** + +Current terminal scan command in sirius-ui fails to communicate properly with agent, preventing real-time testing and troubleshooting. + +#### **Solution Requirements** + +- **Agent Command Registration**: Ensure `internal:scan` command properly registered +- **Terminal Communication**: Fix agent server/client communication protocol +- **Result Formatting**: Return properly formatted JSON responses +- **Error Handling**: Provide clear error messages for troubleshooting + +#### **Acceptance Criteria** + +- [ ] Terminal command `scan` executes without errors +- [ ] Returns structured JSON with package information +- [ ] Shows meaningful error messages for failures +- [ ] Response time under 30 seconds for typical systems + +### **2. SBOM Database Integration** + +#### **Requirements** + +- **Data Persistence**: Store software inventory in PostgreSQL `hosts.software_inventory` JSONB field +- **Source Attribution**: Tag SBOM data with agent source using existing system +- **Update Strategy**: Merge new SBOM data with existing records (don't overwrite network scan data) +- **Query Performance**: Enable efficient searches across software inventory + +#### **Data Structure** + +```json +{ + "scan_metadata": { + "agent_version": "1.2.0", + "scan_date": "2024-01-15T10:30:00Z", + "scan_duration_ms": 5432, + "scan_modules": ["packages", "certificates", "services"] + }, + "packages": [ + { + "name": "nginx", + "version": "1.18.0-6ubuntu14.4", + "source": "dpkg", + "architecture": "amd64", + "install_date": "2023-06-15T08:22:00Z", + "size_bytes": 1048576, + "description": "High performance web server", + "dependencies": ["libc6", "libssl1.1"], + "cpe": "cpe:2.3:a:nginx:nginx:1.18.0:*:*:*:*:*:*:*" + } + ], + "certificates": [ + { + "store": "system", + "subject": "CN=*.example.com", + "issuer": "CN=DigiCert SHA2 High Assurance Server CA", + "serial": "0A1B2C3D4E5F6789", + "expires": "2024-12-31T23:59:59Z", + "fingerprint_sha256": "abc123def456...", + "key_usage": ["digital_signature", "key_encipherment"], + "san": ["example.com", "www.example.com"] + } + ] +} +``` + +#### **Acceptance Criteria** + +- [ ] SBOM data persists in database after agent scan +- [ ] Multiple scans update rather than replace existing data +- [ ] Source attribution prevents network scan interference +- [ ] Database queries perform efficiently (< 100ms for typical searches) + +### **3. Enhanced System Fingerprinting** + +#### **Requirements** + +- **Hardware Detection**: CPU, memory, storage information +- **Network Configuration**: All interfaces, IP addresses, routing, DNS +- **User Enumeration**: Local users, groups, privileges (where permitted) +- **Service Detection**: Running services, versions, configurations +- **Certificate Inventory**: System certificate stores, validity, usage + +#### **Platform-Specific Implementations** + +##### **Linux Fingerprinting** + +```bash +# Hardware +lscpu # CPU information +free -h # Memory information +lsblk # Block devices +df -h # Disk usage + +# Network +ip addr show # Network interfaces +ip route show # Routing table +cat /etc/resolv.conf # DNS configuration + +# Users & Groups +getent passwd # User accounts +getent group # Groups +sudo -l # Sudo privileges (if available) + +# Services +systemctl list-units --type=service --state=running +ps aux # Running processes + +# Certificates +ls /etc/ssl/certs/ # System certificates +openssl x509 -in cert -text -noout # Certificate details +``` + +##### **Windows Fingerprinting** + +```powershell +# Hardware +Get-ComputerInfo +Get-WmiObject Win32_Processor +Get-WmiObject Win32_PhysicalMemory +Get-WmiObject Win32_LogicalDisk + +# Network +Get-NetIPConfiguration +Get-DnsClientServerAddress +Get-NetRoute + +# Users & Groups +Get-LocalUser +Get-LocalGroup +whoami /priv + +# Services +Get-Service | Where-Object {$_.Status -eq "Running"} +Get-Process + +# Certificates +Get-ChildItem -Path Cert:\LocalMachine\My +Get-ChildItem -Path Cert:\CurrentUser\My +``` + +#### **Acceptance Criteria** + +- [ ] Detects hardware specifications across all supported platforms +- [ ] Enumerates all network interfaces and configurations +- [ ] Identifies local users and groups (where permissions allow) +- [ ] Lists running services with version information +- [ ] Inventories certificate stores with expiration tracking + +### **4. Template-Based Vulnerability Detection** + +#### **YAML Template Format** + +```yaml +# Template ID: hash-based-detection-example.yaml +id: "CUSTOM-2024-001" +info: + name: "Vulnerable Apache Binary Detection" + author: "security-team" + severity: "high" + description: "Detects vulnerable Apache binary via file hash" + references: + - "https://httpd.apache.org/security/vulnerabilities_24.html" + cve: "CVE-2023-12345" # Links to existing vulnerability DB + +detection: + type: "file-hash" + method: "sha256" + targets: + - path: "/usr/sbin/apache2" + hash: "a1b2c3d4e5f6789abcdef123456789abcdef123456789abcdef123456789abcdef" + description: "Apache 2.4.41 vulnerable binary" + - path: "C:\\Program Files\\Apache24\\bin\\httpd.exe" + hash: "b2c3d4e5f6789abcdef123456789abcdef123456789abcdef123456789abcdef12" + description: "Apache 2.4.41 Windows vulnerable binary" + + conditions: + - file_exists: true + - hash_match: true + - file_executable: true + + metadata: + confidence: 0.95 + impact: "Remote code execution possible" + affected_versions: ["2.4.41", "2.4.42"] + fixed_versions: ["2.4.43+"] + +remediation: + description: "Update Apache to version 2.4.43 or later" + commands: + linux: "sudo apt update && sudo apt install apache2" + windows: "Download latest version from https://httpd.apache.org/download.cgi" + verification: + command: "apache2 -v" + expected_pattern: "Apache/2\\.4\\.(4[3-9]|[5-9]\\d)" +``` + +#### **Template Types** + +##### **1. File Hash Detection** + +- SHA256/SHA1/MD5 hash verification +- Multiple file targets per template +- Cross-platform path support +- Executable/library verification + +##### **2. Registry Detection (Windows)** + +```yaml +detection: + type: "registry" + keys: + - path: "HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\{ProductGUID}" + value: "DisplayVersion" + pattern: "^1\\.2\\.[0-3]$" # Vulnerable version pattern + description: "Vulnerable software version in registry" + + conditions: + - key_exists: true + - value_matches_pattern: true +``` + +##### **3. Configuration File Detection** + +```yaml +detection: + type: "config-file" + files: + - path: "/etc/apache2/apache2.conf" + patterns: + - regex: "ServerTokens\\s+Full" + description: "Information disclosure via server headers" + - regex: "ServerSignature\\s+On" + description: "Server signature enabled" + + conditions: + - file_exists: true + - pattern_found: true +``` + +#### **Template Execution Engine** + +```go +type TemplateEngine struct { + hashCalculator *hash.Calculator + fileSystem FileSystemInterface + registry RegistryInterface // Windows only +} + +type DetectionResult struct { + TemplateID string `json:"template_id"` + VulnerabilityID string `json:"vulnerability_id"` // CVE or custom ID + Vulnerable bool `json:"vulnerable"` + Confidence float64 `json:"confidence"` + Evidence []Evidence `json:"evidence"` + Metadata map[string]interface{} `json:"metadata"` + ExecutedAt time.Time `json:"executed_at"` +} + +type Evidence struct { + Type string `json:"type"` // "file_hash", "registry_key", "config_pattern" + Location string `json:"location"` // File path, registry key, etc. + Expected string `json:"expected"` // Expected hash, pattern, etc. + Actual string `json:"actual"` // Actual value found + Description string `json:"description"` // Human-readable description +} +``` + +#### **Acceptance Criteria** + +- [ ] YAML template parser validates schema correctly +- [ ] File hash detection works across Windows/Linux/macOS +- [ ] Registry detection works on Windows systems +- [ ] Configuration file pattern matching functions properly +- [ ] Template results link to existing vulnerability database +- [ ] Detection confidence scoring accurately reflects certainty + +### **5. Script-Based Vulnerability Detection** + +#### **PowerShell Script Format** + +```powershell +<# +.SYNOPSIS +Custom vulnerability detection script + +.VULNERABILITY +CVE-2023-67890 + +.DESCRIPTION +Detects misconfigured Windows service permissions + +.SEVERITY +medium + +.AUTHOR +security-team + +.VERSION +1.0 +#> + +param( + [Parameter(Mandatory=$false)] + [string]$ConfigPath = "" +) + +function Test-ServiceVulnerability { + try { + $result = @{ + "vulnerability_id" = "CVE-2023-67890" + "vulnerable" = $false + "confidence" = 0.0 + "evidence" = @() + "metadata" = @{} + "error" = $null + } + + # Detection logic + $services = Get-WmiObject -Class Win32_Service | Where-Object { + $_.StartMode -eq "Auto" -and $_.State -eq "Running" + } + + foreach ($service in $services) { + # Check service permissions + $permissions = & icacls $service.PathName 2>$null + if ($permissions -match "Everyone:F|Users:F") { + $result.vulnerable = $true + $result.confidence = 0.9 + $result.evidence += @{ + "type" = "service_permission" + "service_name" = $service.Name + "path" = $service.PathName + "permissions" = $permissions -join "; " + } + } + } + + if ($result.evidence.Count -gt 0) { + $result.metadata.affected_services = $result.evidence.Count + } + + return $result | ConvertTo-Json -Depth 4 + + } catch { + return @{ + "vulnerability_id" = "CVE-2023-67890" + "vulnerable" = $null + "confidence" = 0.0 + "evidence" = @() + "metadata" = @{} + "error" = $_.Exception.Message + } | ConvertTo-Json -Depth 2 + } +} + +# Execute detection +Test-ServiceVulnerability +``` + +#### **Bash Script Format** + +```bash +#!/bin/bash + +# Script metadata +VULNERABILITY_ID="CVE-2023-67890" +SEVERITY="medium" +DESCRIPTION="Detects SUID binaries with potential privilege escalation" +AUTHOR="security-team" +VERSION="1.0" + +# Detection function +detect_suid_vulnerability() { + local vulnerable=false + local confidence=0.0 + local evidence=() + local error="" + + # Find SUID binaries + local suid_files + if ! suid_files=$(find /usr/bin /usr/sbin /bin /sbin -perm -4000 -type f 2>/dev/null); then + error="Failed to search for SUID binaries" + else + # Check for known vulnerable SUID binaries + local vulnerable_patterns=( + "pkexec" + "passwd" + "sudo" + "su" + ) + + for pattern in "${vulnerable_patterns[@]}"; do + local matches + matches=$(echo "$suid_files" | grep -E "/${pattern}$") + if [[ -n "$matches" ]]; then + while IFS= read -r match; do + # Get file details + local file_info + file_info=$(ls -la "$match" 2>/dev/null) + if [[ -n "$file_info" ]]; then + evidence+=("{\"type\":\"suid_binary\",\"path\":\"$match\",\"permissions\":\"$file_info\"}") + vulnerable=true + confidence=0.8 + fi + done <<< "$matches" + fi + done + fi + + # Return JSON result + local evidence_json + evidence_json=$(printf '%s,' "${evidence[@]}" | sed 's/,$//') + + cat << EOF +{ + "vulnerability_id": "$VULNERABILITY_ID", + "vulnerable": $vulnerable, + "confidence": $confidence, + "evidence": [$evidence_json], + "metadata": { + "total_suid_binaries": $(echo "$suid_files" | wc -l), + "scan_paths": ["/usr/bin", "/usr/sbin", "/bin", "/sbin"] + }, + "error": $(if [[ -n "$error" ]]; then echo "\"$error\""; else echo "null"; fi) +} +EOF +} + +# Execute detection +detect_suid_vulnerability +``` + +#### **Script Execution Framework** + +```go +type ScriptExecutor struct { + powershellPath string + bashPath string + timeout time.Duration + workingDir string +} + +type ScriptResult struct { + ScriptName string `json:"script_name"` + VulnerabilityID string `json:"vulnerability_id"` + Vulnerable *bool `json:"vulnerable"` // null for execution errors + Confidence float64 `json:"confidence"` + Evidence []Evidence `json:"evidence"` + Metadata map[string]interface{} `json:"metadata"` + ExecutionTime time.Duration `json:"execution_time"` + ExitCode int `json:"exit_code"` + Error string `json:"error,omitempty"` +} + +func (se *ScriptExecutor) ExecuteScript(ctx context.Context, scriptPath string, args []string) (*ScriptResult, error) { + // Load script content + // Validate script metadata + // Execute with timeout + // Parse JSON result + // Validate result structure + // Return standardized result +} +``` + +#### **Security Considerations** + +- **Sandboxing**: Execute scripts in controlled environments +- **Timeout Controls**: Prevent runaway script execution +- **Resource Limits**: Limit CPU/memory usage during execution +- **Path Validation**: Prevent directory traversal attacks +- **Content Validation**: Verify script signatures/checksums +- **Audit Logging**: Log all script executions with full context + +#### **Acceptance Criteria** + +- [ ] PowerShell scripts execute on Windows with proper error handling +- [ ] Bash scripts execute on Linux/macOS with timeout controls +- [ ] Script results conform to standardized JSON format +- [ ] Security sandboxing prevents system compromise +- [ ] Script repository supports versioning and updates +- [ ] Execution audit logs capture all script activities + +### **6. Repository Management System** + +#### **Repository Structure** + +``` +templates/ +├── hash-based/ +│ ├── apache-vulnerabilities.yaml +│ ├── nginx-vulnerabilities.yaml +│ └── windows-dll-vulns.yaml +├── registry-based/ +│ ├── windows-software-vulns.yaml +│ └── windows-service-vulns.yaml +├── config-based/ +│ ├── apache-misconfig.yaml +│ ├── ssh-weak-config.yaml +│ └── ssl-cert-issues.yaml +└── manifest.json + +scripts/ +├── windows/ +│ ├── service-permissions.ps1 +│ ├── registry-analysis.ps1 +│ └── certificate-validation.ps1 +├── linux/ +│ ├── suid-analysis.sh +│ ├── service-enumeration.sh +│ └── config-validation.sh +├── cross-platform/ +│ ├── network-analysis.py +│ └── file-permissions.py +└── manifest.json +``` + +#### **Repository Manifest Format** + +```json +{ + "version": "1.2.0", + "updated": "2024-01-15T10:30:00Z", + "templates": { + "hash-based/apache-vulnerabilities.yaml": { + "version": "1.1", + "checksum": "sha256:abc123...", + "vulnerabilities": ["CVE-2023-1234", "CVE-2023-5678"], + "platforms": ["linux", "windows", "darwin"] + } + }, + "scripts": { + "windows/service-permissions.ps1": { + "version": "1.0", + "checksum": "sha256:def456...", + "vulnerabilities": ["CVE-2023-9999"], + "platforms": ["windows"], + "requires": ["powershell-5.0+"] + } + }, + "signatures": { + "manifest.json": "gpg-signature-here", + "templates/hash-based/apache-vulnerabilities.yaml": "gpg-signature-here" + } +} +``` + +#### **Repository Update Mechanism** + +```go +type RepositoryManager struct { + baseURL string + localPath string + updateInterval time.Duration + verifyGPG bool + signingKey string +} + +func (rm *RepositoryManager) UpdateRepository(ctx context.Context) error { + // 1. Download manifest.json + // 2. Verify GPG signatures + // 3. Check version differences + // 4. Download updated templates/scripts + // 5. Verify checksums + // 6. Atomic update of local repository + // 7. Validate all templates/scripts +} + +func (rm *RepositoryManager) LoadTemplates() ([]*VulnTemplate, error) { + // Load and parse all YAML templates + // Validate template structure + // Return parsed templates +} + +func (rm *RepositoryManager) LoadScripts() ([]*DetectionScript, error) { + // Load script metadata + // Validate script structure + // Return script information +} +``` + +#### **Acceptance Criteria** + +- [ ] Repository structure supports versioning and updates +- [ ] GPG signature verification ensures content integrity +- [ ] Atomic updates prevent corruption during updates +- [ ] Template/script validation prevents malformed content +- [ ] Update mechanism works with limited network connectivity +- [ ] Repository caching reduces bandwidth usage + +## 🔄 Integration Points + +### **Agent to Database Flow** + +``` +Agent Scan → Enhanced JSON → Sirius-API → Host Record Update → PostgreSQL Storage +``` + +### **Vulnerability Correlation Flow** + +``` +Template/Script Detection → CVE/Vulnerability ID → Existing Vulnerability DB → Host-Vulnerability Association +``` + +### **Terminal Integration Flow** + +``` +Sirius-UI Terminal → Agent Command → Agent Execution → JSON Response → Terminal Display +``` + +## 🧪 Testing Strategy + +### **Unit Testing** + +- **Template Parser**: Validate YAML parsing with malformed inputs +- **Hash Calculator**: Test file hash calculations across platforms +- **Script Executor**: Verify script execution with various scenarios +- **Database Operations**: Test SBOM storage and retrieval + +### **Integration Testing** + +- **Agent-API Communication**: End-to-end scan data flow +- **Database Persistence**: Verify data integrity across scan cycles +- **Template Execution**: Test template detection on known vulnerable systems +- **Script Execution**: Verify custom script results on test environments + +### **Security Testing** + +- **Script Sandboxing**: Attempt privilege escalation through scripts +- **Template Validation**: Test with malicious YAML content +- **Path Traversal**: Verify file access controls +- **Resource Exhaustion**: Test script timeout and resource limits + +### **Performance Testing** + +- **Scan Duration**: Measure scan times across different system sizes +- **Database Performance**: Test query performance with large SBOM datasets +- **Memory Usage**: Monitor memory consumption during large scans +- **Concurrent Execution**: Test multiple simultaneous scans + +## 🚀 Deployment Strategy + +### **Phase 1: Foundation (Week 1)** + +- Fix terminal scan command +- Implement basic SBOM database storage +- Create template loading framework + +### **Phase 2: Template System (Week 2)** + +- YAML template parser and validator +- File hash detection engine +- Registry/config detection (Windows) +- Basic template repository + +### **Phase 3: Script Framework (Week 3)** + +- PowerShell script executor with sandboxing +- Bash script executor with security controls +- Result standardization and validation +- Script repository management + +### **Phase 4: Integration & Testing (Week 4)** + +- End-to-end integration testing +- Performance optimization +- Security audit and hardening +- Documentation and training materials + +## 📋 Acceptance Criteria Summary + +### **Functional Requirements** + +- [ ] Terminal scan command executes successfully +- [ ] SBOM data persists in PostgreSQL database +- [ ] System fingerprinting captures comprehensive host information +- [ ] YAML templates detect file-hash based vulnerabilities +- [ ] Custom scripts execute securely with standardized results +- [ ] Repository system enables remote updates + +### **Non-Functional Requirements** + +- [ ] Scan completion time < 2 minutes for typical systems +- [ ] Database operations complete in < 500ms +- [ ] Script execution timeout prevents runaway processes +- [ ] Memory usage < 256MB during scans +- [ ] All security controls prevent system compromise +- [ ] 99.9% uptime for agent services + +### **Security Requirements** + +- [ ] Script execution cannot escalate privileges +- [ ] Template validation prevents code injection +- [ ] Repository updates verify cryptographic signatures +- [ ] Audit logging captures all security-relevant events +- [ ] Data transmission uses encrypted channels +- [ ] Sensitive data collection respects privacy controls + +## 📚 Documentation Requirements + +### **Technical Documentation** + +- API documentation for new endpoints +- Database schema documentation +- Template format specification +- Script development guidelines +- Security implementation details + +### **User Documentation** + +- Agent deployment guide +- Template creation tutorial +- Script development tutorial +- Troubleshooting guide +- Best practices documentation + +### **Operational Documentation** + +- Monitoring and alerting setup +- Backup and recovery procedures +- Performance tuning guide +- Security audit procedures +- Incident response procedures + +--- + +**Document Status**: ✅ Complete +**Review Required**: Architecture Team, Security Team +**Next Steps**: Create detailed task breakdown and begin Phase 1 implementation diff --git a/documentation/dev-notes/archive/AGENT-SCANNER.md b/documentation/dev-notes/archive/AGENT-SCANNER.md new file mode 100644 index 0000000..8170d53 --- /dev/null +++ b/documentation/dev-notes/archive/AGENT-SCANNER.md @@ -0,0 +1,2302 @@ +# Sirius Agent Ecosystem - Complete Developer Guide + +**Version**: 2.1 (Production System) +**Last Updated**: January 2025 +**Status**: Comprehensive Developer Onboarding Documentation + +> **Recent Updates (v2.1)**: Major code quality improvements including utility reorganization, enhanced type safety, elimination of code duplication, and improved developer experience. See [Frontend Development Best Practices](#frontend-development-best-practices) for details. + +--- + +## 📖 Table of Contents + +1. [Executive Summary & Problem Statement](#executive-summary--problem-statement) +2. [The Security Challenge We're Solving](#the-security-challenge-were-solving) +3. [System Architecture Philosophy](#system-architecture-philosophy) +4. [Technology Stack & Rationale](#technology-stack--rationale) +5. [Core Components Deep Dive](#core-components-deep-dive) +6. [Data Flow Narratives](#data-flow-narratives) +7. [Template System Design](#template-system-design) +8. [Development Workflows](#development-workflows) +9. [Database Strategy](#database-strategy) +10. [Deployment & Operations](#deployment--operations) +11. [Troubleshooting Philosophy](#troubleshooting-philosophy) +12. [Developer Handbook](#developer-handbook) + +--- + +## 🎯 Executive Summary & Problem Statement + +### What Are We Building? + +The Sirius Agent Ecosystem is a **distributed vulnerability scanning and system fingerprinting platform** that enables security teams to remotely assess the security posture of their infrastructure. Think of it as having security auditors deployed throughout your network that can continuously assess vulnerabilities, collect software inventories, and detect misconfigurations. + +But this isn't just another security tool—it's a complete reimagining of how vulnerability management should work in modern environments. Where traditional scanners struggle with visibility and context, our system thrives by placing intelligent agents directly on the systems they're protecting. + +### The Core Problem + +If you've ever worked in cybersecurity, you've probably experienced the frustration of traditional vulnerability scanners. They're like trying to diagnose a patient by only looking at their skin—you can see some symptoms, but you're missing the full picture of what's happening inside. + +Traditional vulnerability scanners face several critical limitations: + +1. **Network-Only Visibility**: They can only see what's exposed on the network, missing internal vulnerabilities, installed software versions, and system configurations +2. **Point-in-Time Snapshots**: They provide periodic scans but miss the continuous changes in modern dynamic environments +3. **Limited Context**: They detect vulnerabilities but lack the rich system context needed for prioritization and remediation +4. **Scale Challenges**: Scanning thousands of hosts from a central location creates performance bottlenecks and network congestion + +These limitations aren't just technical inconveniences—they represent fundamental gaps in an organization's security posture that attackers routinely exploit. + +### Our Solution Approach + +We've built a **distributed agent-based system** that solves these problems by fundamentally changing the relationship between the scanner and the systems being scanned. Instead of peering through the network from the outside, we embed intelligence directly where it's needed. + +Our approach delivers: + +1. **Deep Host Visibility**: Agents run directly on target systems, providing complete visibility into installed software, configurations, and running services +2. **Continuous Monitoring**: Agents provide ongoing assessment rather than point-in-time scans +3. **Rich Context Collection**: SBOM (Software Bill of Materials) data provides comprehensive context for vulnerability correlation +4. **Scalable Architecture**: Distributed processing with centralized coordination scales to thousands of hosts +5. **Extensible Detection**: Template-based vulnerability detection allows rapid response to new threats + +This foundation sets the stage for everything else we'll explore in this guide. As we dive deeper, you'll see how each architectural decision serves this core mission of providing comprehensive, continuous, and contextual security assessment. + +--- + +## 🔍 The Security Challenge We're Solving + +### Why Traditional Approaches Fall Short + +Before we dive into the technical architecture, it's essential to understand the security landscape that drove us to build this system. The challenges we're addressing aren't new, but they've become more acute as infrastructure becomes more dynamic and attacks more sophisticated. + +The story of modern vulnerability management is one of constant catch-up—security teams trying to maintain visibility into rapidly changing environments with tools designed for a more static world. Let's explore the specific gaps that our system addresses. + +### Traditional Vulnerability Management Gaps + +#### **1. The "Black Box" Problem** + +Imagine trying to inventory a warehouse by only looking through the windows. This is essentially what traditional network scanners do—they peer through network ports, trying to deduce what's running inside systems. + +Traditional network scanners can only see what services are exposed on network ports. They miss: + +- **Internal vulnerabilities** in software that doesn't expose network services +- **Configuration issues** in files that aren't network-accessible +- **Privilege escalation vectors** that require local system access +- **Software inventory** that enables vulnerability correlation + +**Real-World Impact**: A vulnerable version of `sudo` installed on a Linux system won't be detected by network scanning, but it represents a critical privilege escalation risk that attackers can exploit to gain root access. + +#### **2. The "Snapshot" Problem** + +Modern infrastructure is dynamic, but traditional scanning is static. It's like trying to understand a movie by looking at a few still frames—you miss all the action that happens between scans. + +Network scans provide point-in-time assessments, but modern environments are dynamic: + +- **Software updates** happen continuously +- **Configuration changes** can introduce new vulnerabilities +- **New deployments** can contain vulnerable components +- **Temporary services** might be missed between scan cycles + +**Real-World Impact**: A developer deploys a test application with default credentials on Tuesday, but the weekly network scan isn't scheduled until Friday. That's a four-day window where the vulnerability exists but remains undetected. + +#### **3. The "Context" Problem** + +Finding vulnerabilities is only half the battle—understanding their real-world impact is often more challenging. Traditional scanners are like smoke detectors that can tell you there's a fire somewhere in the building, but not which room or how severe. + +Network scans detect vulnerabilities but lack operational context: + +- **Which vulnerabilities are actually exploitable** in the current configuration? +- **What business services** would be impacted by exploitation? +- **What compensating controls** are already in place? +- **How are systems interconnected** for lateral movement analysis? + +**Real-World Impact**: A critical vulnerability in Apache might seem urgent until you realize it's running in a container with no network access, behind a WAF, with all dangerous modules disabled. Context changes everything about prioritization. + +### Our Agent-Based Solution + +Our approach flips the traditional model on its head. Instead of trying to peer into systems from the outside, we place intelligent agents on the inside, giving them the access and context needed to provide comprehensive security assessment. + +Think of it as the difference between a home security system that only monitors doors and windows versus one that has sensors throughout every room. The comprehensive approach provides dramatically better visibility and context. + +#### **Deep System Access** + +Our agents run with appropriate privileges to examine everything that matters for security: + +- Complete software inventory (packages, versions, dependencies) +- Configuration files and settings +- Running processes and services +- User accounts and permissions +- Network interfaces and routing +- Certificate stores and cryptographic materials + +This comprehensive visibility means no vulnerable software goes undetected, no misconfiguration remains hidden, and no security-relevant change occurs without notice. + +#### **Continuous Assessment** + +Rather than periodic snapshots, our agents provide ongoing monitoring: + +- Real-time detection of new vulnerabilities +- Configuration drift monitoring +- Software installation/removal tracking +- Service status changes +- Security event correlation + +This continuous approach means the security team knows about problems minutes after they occur, not days or weeks later. + +#### **Rich Contextual Data** + +Our agents collect the contextual information needed for intelligent prioritization: + +- Hardware specifications and capabilities +- Network topology and connectivity +- Business service mappings +- Compliance control implementations +- Custom security configurations + +This context transforms vulnerability management from a guessing game into a precise, prioritized process. + +### The Path Forward + +These challenges shaped every aspect of our system design. As we explore the architecture in the following sections, you'll see how each component serves the mission of providing comprehensive, continuous, and contextual security assessment. + +The technical decisions we'll discuss aren't arbitrary—they're responses to real-world security challenges that have plagued organizations for years. By understanding these challenges first, the architectural solutions become not just technically interesting, but strategically essential. + +--- + +## 🏗️ System Architecture Philosophy + +### The Evolution of Our Thinking + +Building a distributed security system isn't just about writing code—it's about solving complex organizational and operational challenges through technology. Our architecture didn't emerge fully formed; it evolved through several iterations, each teaching us valuable lessons about what works in real-world environments. + +Understanding this evolution is crucial because it explains why we made certain design choices that might seem complex at first glance. Each layer of complexity exists because simpler approaches failed to meet the demands of production environments. + +### Core Design Principles + +Our architecture is built on several fundamental principles that guide every technical decision. These aren't just philosophical ideals—they're practical guidelines that have saved us countless hours of debugging and prevented numerous production issues. + +#### **1. Separation of Concerns** + +One of our most important principles is that each component should have a single, clear responsibility. This might seem obvious, but it's surprisingly easy to violate when building distributed systems. + +We've deliberately separated different responsibilities into distinct components: + +- **UI Layer**: Focuses purely on user experience and data presentation +- **Agent Server**: Handles coordination, template management, and communication orchestration +- **Storage Layer**: Provides reliable, scalable data persistence +- **Endpoint Agents**: Focus exclusively on data collection and vulnerability detection +- **Database Layer**: Handles complex vulnerability correlation and reporting + +**Why This Matters**: This separation allows each component to be developed, tested, and scaled independently. A UI bug won't affect agent scanning, and database performance issues won't impact real-time agent communication. + +More importantly, this separation makes the system understandable. When something goes wrong, you know exactly where to look. When you need to scale, you know exactly what to scale. When you need to modify functionality, you know exactly what components are involved. + +#### **2. Single Source of Truth** + +In distributed systems, data consistency is often the most challenging problem. We solved this by establishing **ValKey** as our centralized truth store for all operational data: + +- **No Data Duplication**: Each piece of information has exactly one authoritative location +- **Consistency Guarantees**: All components see the same data at any given time +- **Simplified Debugging**: When something goes wrong, there's one place to look for the truth +- **Atomic Updates**: Changes are applied atomically to prevent partial state corruption + +**The Alternative We Avoided**: Many systems try to maintain consistency through complex synchronization protocols between multiple data stores. This approach inevitably leads to split-brain scenarios, data loss, and hours of debugging mysterious inconsistencies. + +**Why This Matters**: Having a single source of truth eliminates an entire class of bugs and makes the system much easier to reason about. When an agent shows a template as available, you can be confident that every other component in the system sees the same state. + +#### **3. Asynchronous Communication** + +We use **RabbitMQ** for loose coupling between components, and this decision has profound implications for system reliability and scalability: + +- **UI ↔ Agent Server**: Asynchronous messaging for template creation and management +- **Resilience**: Components can temporarily fail without data loss +- **Scalability**: Messages can be queued and processed at sustainable rates +- **Observability**: Message flow provides clear audit trails + +**The Story Behind This Decision**: In our early iterations, we used synchronous HTTP calls between components. This created a cascading failure pattern where a problem in any component would bring down the entire system. Users would click "create template" and wait 30 seconds for a timeout when the Agent Server was under load. + +**Why This Matters**: Asynchronous communication allows components to operate independently and provides natural backpressure when components are overwhelmed. Users get immediate feedback, and the system gracefully handles load spikes. + +#### **4. gRPC for Real-Time Communication** + +While we use asynchronous messaging for most operations, agent communication requires real-time responsiveness. We use **gRPC streaming** for this because: + +- **Bidirectional Streams**: Agents and servers can communicate simultaneously +- **Type Safety**: Protocol buffers provide compile-time verification +- **Performance**: Binary encoding and HTTP/2 multiplexing +- **Reliability**: Built-in retry logic and connection management + +**The Balance We Struck**: This creates an interesting architectural pattern where we have both asynchronous and synchronous communication in the same system. The key insight is matching the communication pattern to the actual requirements rather than forcing everything through the same mechanism. + +### The Big Picture: Component Interaction + +Understanding how these principles manifest in our actual architecture helps illustrate why they matter: + +``` +┌─────────────────┐ Async Messages ┌─────────────────┐ gRPC Streams ┌─────────────────┐ +│ Sirius UI │ ──────RabbitMQ────→ │ Agent Server │ <──────gRPC──────> │ Endpoint Agent │ +│ │ │ │ │ │ +│ • Template UI │ │ • Coordination │ │ • Scanning │ +│ • Agent Mgmt │ │ • Template Sync │ │ • Collection │ +│ • Results View │ │ • Command Dist │ │ • Detection │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ + │ │ + │ │ + ▼ ▼ +┌────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ ValKey (Single Source of Truth) │ +│ │ +│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ +│ │ Templates │ │ Scripts │ │ Agent State │ │ Scan Results │ │ Metadata │ │ +│ │ │ │ │ │ │ │ │ │ │ │ +│ │ • Repository │ │ • PowerShell │ │ • Connections │ │ • SBOM Data │ │ • Manifests │ │ +│ │ • Custom │ │ • Bash │ │ • Status │ │ • Vulns Found │ │ • Statistics │ │ +│ │ • Local │ │ • Python │ │ • Heartbeat │ │ • Fingerprint │ │ • Versioning │ │ +│ └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘ │ +└────────────────────────────────────────────────────────────────────────────────────────────────┘ + ▲ ▲ + │ │ + ▼ ▼ +┌─────────────────┐ ┌─────────────────┐ +│ PostgreSQL │ │ RabbitMQ │ +│ │ │ │ +│ • Vulnerability │ │ • Message Queue │ +│ Correlation │ │ • Event Routing │ +│ • Host Records │ │ • Reliability │ +│ • SBOM Storage │ │ • Audit Trail │ +│ • Reporting │ │ • Backpressure │ +└─────────────────┘ └─────────────────┘ +``` + +This diagram might look complex at first glance, but it tells a story of careful evolution and learned experience. Each connection represents a deliberate choice about how data should flow, and each component exists to solve a specific class of problems we encountered in production environments. + +The beauty of this architecture lies not in its complexity, but in its clarity of purpose. Data flows in predictable patterns, failures are isolated to specific components, and scaling happens where it's needed most. + +### Why This Architecture? + +Understanding our architectural evolution is crucial because it illustrates why simple solutions often fail in production environments. We didn't arrive at this design through academic exercise—we built it through iterative problem-solving in real-world scenarios. + +This architecture emerged from several failed attempts and hard-learned lessons: + +#### **Evolution 1: Monolithic Scanner** + +Our first approach was a single application that handled everything. Like many first attempts, it seemed elegant in its simplicity. One codebase, one deployment, one thing to monitor. What could go wrong? + +As it turns out, quite a lot. This approach failed because: + +- Tight coupling made changes risky and slow +- Scaling required scaling everything together +- Failures in one component brought down the entire system +- Testing was complex and brittle + +**The Lesson**: Simplicity at the architectural level often creates complexity everywhere else. + +#### **Evolution 2: Microservices Without Clear Boundaries** + +Learning from our monolithic mistakes, we swung to the other extreme. We broke everything into small services, thinking that if some decoupling was good, more must be better. + +Our second attempt split functionality into many small services. This failed because: + +- Service boundaries were unclear and overlapping +- Network communication overhead was excessive +- Data consistency became a nightmare +- Debugging distributed problems was extremely difficult + +**The Lesson**: Microservices are a tool, not a goal. The boundaries matter more than the number of services. + +#### **Evolution 3: Component-Based with Clear Responsibilities** + +Our current architecture represents the synthesis of these lessons. We kept the benefits of decoupling while establishing clear responsibilities and communication patterns. + +Our current architecture (Evolution 3) succeeds because: + +- Each component has a clear, single responsibility +- Communication patterns match the actual needs (async vs real-time) +- Data flow is unidirectional and predictable +- Failure modes are isolated and well-understood + +**The Lesson**: Architecture is about trade-offs, not absolutes. The right design balances complexity with capability. + +### Architectural Wisdom: What We Learned + +These iterations taught us several important principles that guide our current design: + +1. **Complexity should serve a purpose**: Every architectural decision should solve a real problem, not just look elegant on paper +2. **Communication patterns matter**: Match your messaging approach to your actual requirements +3. **Failure modes are features**: Design for failure, because in distributed systems, failure is inevitable +4. **Evolution over revolution**: Systems that can adapt over time outlive those designed for one specific scenario + +As we explore the specific technology choices in the next section, you'll see how these lessons influenced every decision from programming languages to database design. + +--- + +## 🛠️ Technology Stack & Rationale + +### The Philosophy Behind Our Choices + +Technology selection in a security platform is never just about technical capabilities—it's about risk management, team productivity, and long-term maintainability. Every technology choice represents a bet on the future, and in security systems, the stakes of being wrong are particularly high. + +Our technology stack evolved from practical constraints and hard-learned lessons. We didn't choose technologies because they were fashionable; we chose them because they solved specific problems we encountered in production environments. + +Let's explore each choice and the reasoning behind it. + +### Frontend Technology Choices + +#### **Next.js + TypeScript + tRPC** + +The frontend of a security platform has unique requirements. Security analysts need dashboards that load quickly, display complex data clearly, and remain responsive under load. The technology choices we made serve these specific needs. + +**Why Next.js?** + +Security dashboards are different from typical web applications. They need to display large amounts of data, often in real-time, while remaining fast and responsive. Next.js provides several capabilities that directly address these requirements: + +- **Server-Side Rendering**: Better performance and SEO for security dashboards +- **API Routes**: Convenient backend integration without separate API server +- **File-Based Routing**: Intuitive navigation structure for security workflows +- **Built-in Optimization**: Automatic code splitting and image optimization + +**The Story Behind TypeScript** + +We didn't start with TypeScript—we migrated to it after experiencing too many runtime errors in production. When you're dealing with security data, a small type error can mean the difference between catching a critical vulnerability and missing it entirely. + +**Why TypeScript?** + +- **Type Safety**: Prevents runtime errors in security-critical applications +- **Developer Experience**: Better IntelliSense and refactoring capabilities +- **API Contract Enforcement**: Ensures UI and backend stay synchronized +- **Documentation**: Types serve as living documentation + +**The tRPC Revelation** + +Traditional REST APIs create a maintenance burden—you have to keep frontend and backend in sync manually. tRPC eliminates this problem entirely by sharing types across the full stack. + +**Why tRPC?** + +- **End-to-End Type Safety**: Types flow from database to UI without manual synchronization +- **Developer Productivity**: No need to write API documentation or client SDKs +- **Automatic Serialization**: Handles complex data types automatically +- **Built-in Validation**: Request/response validation happens automatically + +**Example of Type Safety in Action**: + +```typescript +// Backend procedure definition +export const getTemplates = publicProcedure.query(async ({ ctx }) => { + const templates = await ctx.valkey.getAllTemplates(); + return templates; // TypeScript knows the exact return type +}); + +// Frontend usage - IntelliSense knows the structure +const { data: templates } = api.agent.getTemplates.useQuery(); +// TypeScript knows 'templates' has exactly the right structure +templates?.forEach((template) => { + console.log(template.info.name); // ✅ Type-safe + console.log(template.invalidField); // ❌ TypeScript error +}); +``` + +This type safety isn't just convenient—it's essential for security applications where data integrity directly impacts security outcomes. + +### Backend Technology Choices + +#### **Go for Agent Server and Endpoint Agents** + +The choice of programming language for security tools is critical. You need performance, reliability, and security, but you also need developer productivity and ease of deployment. Go strikes an excellent balance across all these requirements. + +**Why Go?** + +The decision to use Go wasn't made lightly. We evaluated several alternatives and Go consistently won across the criteria that mattered most for our use case: + +- **Performance**: Native compilation and minimal runtime overhead +- **Concurrency**: Goroutines handle thousands of simultaneous agent connections +- **Cross-Platform**: Single codebase deploys to Windows, Linux, and macOS +- **Static Binaries**: No runtime dependencies simplify deployment +- **Security**: Memory safety and minimal attack surface + +**Specific Go Advantages for Our Use Case**: + +```go +// Concurrent agent handling example +func (s *Server) handleAgentConnections() { + for { + conn, err := s.grpcServer.Accept() + if err != nil { + log.Error("Failed to accept connection", "error", err) + continue + } + + // Each agent gets its own goroutine - scales to thousands + go s.handleSingleAgent(conn) + } +} +``` + +#### **gRPC for Agent Communication** + +**Why gRPC over REST?** + +- **Bidirectional Streaming**: Agents and server can communicate simultaneously +- **Schema Evolution**: Protocol buffers provide backward/forward compatibility +- **Performance**: Binary encoding is faster than JSON for high-volume data +- **Type Safety**: Generated code prevents communication errors + +**Example Protocol Buffer Definition**: + +```protobuf +// Clear contract between agent and server +service AgentService { + rpc Communicate(stream ClientMessage) returns (stream ServerMessage); +} + +message ServerMessage { + string command_id = 1; + string type = 2; // "scan", "template_sync", "internal:status" + string payload = 3; + int64 timestamp = 4; +} + +message ClientMessage { + string agent_id = 1; + string command_id = 2; + int32 exit_code = 3; + string output = 4; + int64 timestamp = 5; +} +``` + +### Storage Technology Choices + +#### **ValKey as Single Source of Truth** + +**Why ValKey (Redis-compatible)?** + +- **In-Memory Performance**: Microsecond response times for agent queries +- **Data Structure Variety**: Lists, sets, hashes, and strings for different use cases +- **Atomic Operations**: ACID guarantees for critical state changes +- **Pub/Sub Capabilities**: Real-time notifications for distributed components +- **Persistence Options**: Configurable durability vs. performance trade-offs + +**ValKey Data Organization Strategy**: + +``` +agent:template:{template_id} # Template YAML content +agent:template:meta:{template_id} # Metadata (source, sync time, etc.) +agent:template:manifest # Global template index +agent:state:{agent_id} # Agent connection state +agent:heartbeat:{agent_id} # Agent health status +scan:result:{scan_id} # Scan results cache +scan:queue:pending # Queued scan requests +``` + +**Why This Key Structure?** + +- **Predictable Patterns**: Easy to find related data +- **Efficient Queries**: Pattern matching works well +- **Logical Grouping**: Related data is co-located +- **Cache-Friendly**: Frequently accessed data can be kept in memory + +#### **PostgreSQL for Persistent Data** + +**Why PostgreSQL for vulnerability correlation?** + +- **JSONB Support**: Store flexible SBOM data while maintaining query performance +- **ACID Transactions**: Ensure data consistency during complex updates +- **Sophisticated Querying**: Complex vulnerability correlation across hosts +- **Proven Scalability**: Battle-tested for enterprise workloads + +**JSONB Schema Design Example**: + +```sql +-- Flexible SBOM storage with structured querying +ALTER TABLE hosts ADD COLUMN software_inventory JSONB; +ALTER TABLE hosts ADD COLUMN system_fingerprint JSONB; + +-- Efficient queries on JSON data +CREATE INDEX idx_hosts_packages_gin ON hosts USING GIN ((software_inventory->'packages')); + +-- Example query: Find all hosts with vulnerable Apache versions +SELECT hostname, software_inventory->'packages' +FROM hosts +WHERE software_inventory->'packages' @> '[{"name": "apache2", "version": "2.4.41"}]'; +``` + +#### **RabbitMQ for Asynchronous Communication** + +**Why RabbitMQ?** + +- **Reliable Delivery**: Messages persist until processed +- **Complex Routing**: Route messages based on content and metadata +- **Flow Control**: Prevents fast producers from overwhelming slow consumers +- **Management Interface**: Built-in monitoring and debugging tools + +**Message Flow Design**: + +``` +UI Template Creation → agent_content_sync Queue → Agent Server Processing + ↓ +Template Stored in ValKey → Template Available to Agents +``` + +**Why This Pattern?** + +- **Decoupling**: UI doesn't need to wait for template processing +- **Reliability**: Template creation requests can't be lost +- **Scalability**: Multiple agent servers can process templates +- **Observability**: Queue depths show system load + +--- + +## 🔧 Core Components Deep Dive + +### Component 1: Sirius UI (Frontend) + +#### **Purpose and Responsibilities** + +The Sirius UI serves as the primary interface for security analysts and administrators. It's responsible for: + +1. **Template Management**: Creating, editing, and organizing vulnerability detection templates +2. **Agent Monitoring**: Viewing agent status, health, and scan results +3. **Vulnerability Visualization**: Presenting scan results in actionable formats +4. **System Administration**: Managing agent configurations and scanning policies + +#### **Key Architecture Decisions** + +**Decision 1: Direct ValKey Integration for Read Operations** + +Instead of going through the Agent Server for all operations, we connect directly to ValKey for read operations: + +```typescript +// Direct ValKey connection for fast reads +export const agentRouter = createTRPCRouter({ + getTemplatesFromValKey: publicProcedure.query(async ({ ctx }) => { + // Direct read from ValKey - no network hops through Agent Server + const templates = await ctx.valkey.getAllTemplates(); + return templates; + }), +}); +``` + +**Why This Decision?** + +- **Performance**: Eliminates network hops for frequently accessed data +- **Reduced Load**: Agent Server can focus on agent communication +- **Consistency**: UI always sees the same data that agents see +- **Scalability**: Read operations scale independently + +**Decision 2: RabbitMQ for Write Operations** + +Write operations (like creating templates) go through RabbitMQ: + +```typescript +createTemplate: publicProcedure + .input( + z.object({ + id: z.string(), + content: z.string(), + }) + ) + .mutation(async ({ input, ctx }) => { + // Async message to Agent Server for processing + await ctx.rabbitMQ.publish("agent_content_sync", { + operation: "create", + type: "template", + id: input.id, + content: input.content, + }); + }); +``` + +**Why This Decision?** + +- **Reliability**: Template creation can't fail due to temporary Agent Server issues +- **Processing Time**: Complex template validation happens asynchronously +- **User Experience**: UI responds immediately without waiting for processing +- **Audit Trail**: All template changes are logged in message queue + +#### **Component Architecture** + +``` +Sirius UI Component Structure: +├── pages/ +│ ├── dashboard/ +│ │ ├── index.tsx # Main security dashboard +│ │ ├── agents.tsx # Agent management interface +│ │ └── vulnerabilities.tsx # Vulnerability reporting +│ └── templates/ +│ ├── index.tsx # Template listing and management +│ ├── create.tsx # Template creation wizard +│ └── editor.tsx # Template editing interface +├── components/ +│ ├── agent/ +│ │ ├── AgentTemplatesTab.tsx # Template display component +│ │ ├── AgentStatusCard.tsx # Agent health monitoring +│ │ └── ScanResultsViewer.tsx # Scan result presentation +│ └── templates/ +│ ├── TemplateEditor.tsx # YAML template editor +│ ├── TemplateValidator.tsx # Real-time validation +│ └── TemplatePreview.tsx # Template execution preview +├── utils/ # Shared utility functions +│ ├── yamlConverter.ts # YAML ↔ JSON conversion utilities +│ ├── types.ts # TypeScript interfaces and types +│ ├── constants.ts # Configuration constants and messages +│ ├── monacoUtils.ts # Monaco editor configurations +│ └── scriptTemplates.ts # Script template generation +└── server/ + └── api/ + └── routers/ + ├── agent.ts # Agent-related tRPC procedures + ├── template.ts # Template management procedures + └── vulnerability.ts # Vulnerability data procedures +``` + +#### **Utility Organization Strategy** + +Our frontend follows a modular utility approach that promotes code reuse and maintainability: + +**Core Utility Functions**: + +```typescript +// yamlConverter.ts - Centralized conversion logic +export const convertToYamlForEditing = (contentData: unknown): string => { + // Handles conversion from JSON objects to YAML for editing +}; + +export const convertYamlToJson = ( + yamlContent: string +): Record => { + // Handles conversion from YAML back to JSON for API storage +}; + +// types.ts - Comprehensive type definitions +export interface TemplateContent { + id: string; + info: TemplateInfo; + detection: TemplateDetection; + remediation: TemplateRemediation; +} + +// constants.ts - Centralized configuration +export const VALIDATION_MESSAGES = { + requiredFields: "Please fill in all required fields", + invalidContent: "Invalid YAML/JSON content", + // ... more validation messages +} as const; + +// monacoUtils.ts - Editor configurations +export const getMonacoLanguage = ( + scriptLanguage: ScriptLanguage +): MonacoLanguage => { + // Maps script languages to Monaco editor languages +}; + +export const MONACO_HEIGHTS = { + preview: "300px", + editor: "500px", + viewer: "400px", +} as const; +``` + +**Why This Organization?** + +- **DRY Principle**: Eliminates code duplication across components +- **Type Safety**: Centralized types ensure consistency across the application +- **Maintainability**: Changes to utility functions automatically propagate everywhere +- **Testing**: Pure utility functions are easier to unit test +- **Performance**: Shared utilities can be optimized once and benefit the entire application + +#### **Data Flow Through UI Components** + +**Template Creation Flow**: + +1. User opens Template Creation Wizard (`pages/templates/create.tsx`) +2. Component renders form with real-time validation (`TemplateEditor.tsx`) +3. User submits template, triggering tRPC mutation +4. Mutation sends RabbitMQ message to Agent Server +5. UI shows success message and redirects to template list +6. Template list refreshes from ValKey, showing new template + +**Agent Monitoring Flow**: + +1. Agent Status Cards poll for updates every 30 seconds +2. tRPC query fetches agent states from ValKey +3. Component renders health status with visual indicators +4. Click on agent opens detailed view with scan history +5. Scan history queries PostgreSQL for historical data + +### Component 2: Agent Server (Backend Orchestrator) + +#### **Purpose and Responsibilities** + +The Agent Server is the coordination hub of the entire system. It's responsible for: + +1. **Template Synchronization**: Keeping ValKey updated with templates from all sources +2. **Agent Communication**: Managing gRPC connections with endpoint agents +3. **Command Distribution**: Routing scan requests and other commands to appropriate agents +4. **Content Processing**: Validating and processing templates and scripts from the UI + +#### **Key Architecture Decisions** + +**Decision 1: Template Sync Service Design** + +We built a comprehensive synchronization service that handles three template sources: + +```go +// Template sync coordinates three sources +func (ts *TemplateSyncService) SyncAllTemplatesToValKey() error { + results := &SyncResults{} + + // 1. Repository templates (from sirius-agent-modules) + if err := ts.syncRepositoryTemplates(results); err != nil { + log.Warn("Repository template sync failed", "error", err) + } + + // 2. Local templates (from filesystem) + if err := ts.syncLocalTemplates(results); err != nil { + log.Warn("Local template sync failed", "error", err) + } + + // 3. Custom templates (from UI via RabbitMQ) + if err := ts.verifyCustomTemplates(results); err != nil { + log.Warn("Custom template verification failed", "error", err) + } + + return nil +} +``` + +**Why This Three-Source Design?** + +- **Repository Templates**: Centrally maintained, version-controlled templates for common vulnerabilities +- **Custom Templates**: User-created templates for organization-specific needs +- **Local Templates**: Development and testing templates that don't need central distribution + +**Decision 2: Graceful Degradation** + +If one template source fails, others continue to work: + +```go +func (ts *TemplateSyncService) syncRepositoryTemplates(results *SyncResults) error { + return filepath.Walk(repoPath, func(path string, info os.FileInfo, err error) error { + // ... template loading logic ... + + template, err := ts.loadTemplate(path) + if err != nil { + log.Warn("Failed to sync repository template", "path", path, "error", err) + return nil // Continue with other templates instead of failing + } + + // ... successful processing ... + return nil + }) +} +``` + +**Why This Decision?** + +- **Resilience**: One broken template doesn't break the entire system +- **Operational Simplicity**: System continues working during template debugging +- **Development Experience**: Developers can work on templates without breaking production + +**Decision 3: gRPC Connection Management** + +We maintain persistent bidirectional streams with agents: + +```go +type Server struct { + agents map[string]*AgentConnection + mu sync.RWMutex +} + +type AgentConnection struct { + AgentID string + Stream pb.AgentService_CommunicateServer + LastSeen time.Time + Status AgentStatus + Commands chan *pb.ServerMessage +} + +func (s *Server) handleAgentStream(stream pb.AgentService_CommunicateServer) { + // Each agent gets dedicated goroutine for message handling + for { + msg, err := stream.Recv() + if err != nil { + // Clean up connection and notify monitoring + s.removeAgent(agentID) + return + } + + // Process agent message asynchronously + go s.processAgentMessage(msg) + } +} +``` + +**Why This Design?** + +- **Real-Time Communication**: Agents can receive commands immediately +- **Connection Monitoring**: Server knows which agents are alive +- **Scalability**: Each agent operates independently +- **Fault Tolerance**: Agent disconnections don't affect other agents + +#### **Template Processing Pipeline** + +When a new template arrives via RabbitMQ, it goes through a comprehensive processing pipeline: + +```go +func (ccc *CustomContentConsumer) processTemplateMessage(message *CustomContentMessage) error { + // Step 1: Parse and validate template structure + template := &Template{} + if err := mapstructure.Decode(message.Content, template); err != nil { + return fmt.Errorf("failed to decode template: %w", err) + } + + // Step 2: Validate template semantics + if err := ccc.validateTemplate(template); err != nil { + return fmt.Errorf("template validation failed: %w", err) + } + + // Step 3: Save to filesystem for persistence + if err := ccc.customStorage.SaveTemplate(template); err != nil { + return fmt.Errorf("failed to save template: %w", err) + } + + // Step 4: Sync to ValKey for agent access + templateMeta := &TemplateMetadata{ + Source: &TemplateSource{Type: "custom"}, + SyncedAt: time.Now(), + } + + if err := ccc.valKeyStore.StoreTemplate(template.ID, template, templateMeta); err != nil { + return fmt.Errorf("failed to sync template to ValKey: %w", err) + } + + log.Info("Custom template processed successfully", "template_id", template.ID) + return nil +} +``` + +**Why This Pipeline?** + +- **Data Integrity**: Multiple validation steps prevent corrupt templates +- **Persistence**: Templates survive server restarts +- **Immediate Availability**: Templates are available to agents as soon as processing completes +- **Audit Trail**: Each step is logged for debugging + +### Component 3: ValKey Storage System + +#### **Purpose and Responsibilities** + +ValKey serves as the **single source of truth** for all real-time operational data: + +1. **Template Storage**: All vulnerability detection templates and their metadata +2. **Agent State**: Current status and configuration of all agents +3. **Scan Coordination**: Queuing and tracking of scan requests +4. **Real-Time Cache**: Fast access to frequently needed data + +#### **Data Organization Strategy** + +**Key Naming Conventions**: + +``` +agent:template:{template_id} # Template content (YAML as JSON) +agent:template:meta:{template_id} # Metadata (source, sync time, version) +agent:template:manifest # Global template registry +agent:state:{agent_id} # Agent connection and status +agent:heartbeat:{agent_id} # Agent health (with TTL) +scan:result:{scan_id} # Cached scan results +scan:queue:pending # Queued scan requests +``` + +**Why This Structure?** + +- **Hierarchical Organization**: Related data is grouped by prefix +- **Pattern Matching**: Easy to find all templates, all agents, etc. +- **Cache Efficiency**: Frequently accessed data is co-located +- **TTL Management**: Health data expires automatically + +#### **Template Storage Design** + +Templates are stored in two parts for efficiency: + +```go +// Template content - the actual YAML template +templateKey := "agent:template:" + templateID +templateJSON, _ := json.Marshal(template) +store.client.Set(ctx, templateKey, templateJSON, 0) + +// Template metadata - source, sync time, etc. +metaKey := "agent:template:meta:" + templateID +metaJSON, _ := json.Marshal(metadata) +store.client.Set(ctx, metaKey, metaJSON, 0) +``` + +**Why Split Storage?** + +- **Performance**: Agents only need template content, not metadata +- **Flexibility**: Metadata can be updated without touching template content +- **Caching**: Different cache policies for content vs. metadata +- **Debugging**: Can examine metadata without loading large template content + +#### **Agent State Management** + +Agent state is managed with careful attention to connection lifecycle: + +```go +// Agent connects - establish state +agentState := &AgentState{ + AgentID: agentID, + Status: "connected", + ConnectedAt: time.Now(), + LastSeen: time.Now(), + Capabilities: agentCapabilities, +} +store.client.Set(ctx, "agent:state:"+agentID, agentJSON, 0) + +// Heartbeat with TTL - auto-cleanup on disconnect +store.client.Set(ctx, "agent:heartbeat:"+agentID, "alive", 60*time.Second) +``` + +**Why This Design?** + +- **Automatic Cleanup**: Heartbeats expire if agent disconnects ungracefully +- **State Persistence**: Agent state survives brief network interruptions +- **Monitoring**: Easy to identify healthy vs. unhealthy agents +- **Debugging**: Complete connection history available + +### Component 4: Endpoint Agent (Scanner) + +#### **Purpose and Responsibilities** + +Endpoint agents are the "sensors" of our security system. Each agent is responsible for: + +1. **System Inspection**: Collecting comprehensive information about the host system +2. **Vulnerability Detection**: Executing templates to identify security issues +3. **SBOM Collection**: Gathering software inventory for vulnerability correlation +4. **Command Execution**: Running security assessment scripts and tools + +#### **Agent Architecture Design** + +**Connection Management**: + +```go +type Agent struct { + serverAddress string + agentID string + grpcClient pb.AgentServiceClient + stream pb.AgentService_CommunicateClient + + // Core capabilities + templateEngine *template.Engine + scanCommand *scan.ScanCommand + scriptExecutor *script.Executor + + // State management + heartbeatTicker *time.Ticker + commandQueue chan *pb.ServerMessage + resultQueue chan *pb.ClientMessage +} +``` + +**Why This Design?** + +- **Single Connection**: One gRPC stream handles all communication +- **Asynchronous Processing**: Commands and results are queued for processing +- **Capability-Based**: Agent capabilities are detected and reported +- **Health Monitoring**: Regular heartbeats ensure server knows agent status + +#### **Template Execution Engine** + +The template engine is responsible for executing vulnerability detection templates: + +```go +func (c *ScanCommand) executeTemplateDetection(ctx context.Context, result *ScanResult) ([]TemplateDetectionResult, error) { + // Load all available templates + templates, err := c.templateEngine.LoadTemplates() + if err != nil { + return nil, fmt.Errorf("failed to load templates: %w", err) + } + + var results []TemplateDetectionResult + + // Execute each template independently + for _, template := range templates { + detectResult, err := c.templateEngine.ExecuteTemplate(ctx, template, agentInfo) + if err != nil { + log.Warn("Template execution failed", "template_id", template.ID, "error", err) + continue // Don't let one bad template break everything + } + + if detectResult.Vulnerable { + results = append(results, TemplateDetectionResult{ + TemplateID: template.ID, + VulnerabilityID: detectResult.VulnerabilityID, + Vulnerable: true, + Confidence: detectResult.Confidence, + Evidence: detectResult.Evidence, + ExecutedAt: time.Now(), + }) + } + } + + return results, nil +} +``` + +**Why This Design?** + +- **Isolation**: Each template executes independently +- **Resilience**: Template failures don't affect other templates +- **Performance**: Templates can be executed in parallel +- **Debugging**: Clear separation between template logic and execution engine + +#### **SBOM Collection Strategy** + +Software Bill of Materials (SBOM) collection adapts to each platform: + +```go +// Platform-specific package collection +type PackageCollector interface { + CollectPackages(ctx context.Context) ([]EnhancedPackageInfo, error) +} + +// Linux implementation +type DebianPackageCollector struct{} +func (dpc *DebianPackageCollector) CollectPackages(ctx context.Context) ([]EnhancedPackageInfo, error) { + // Use dpkg-query for comprehensive package information + cmd := exec.CommandContext(ctx, "dpkg-query", "-W", + "--showformat=${Package}\t${Version}\t${Architecture}\t${Installed-Size}\t${Description}\n") + // ... processing logic ... +} + +// Windows implementation +type WindowsPackageCollector struct{} +func (wpc *WindowsPackageCollector) CollectPackages(ctx context.Context) ([]EnhancedPackageInfo, error) { + // Use PowerShell to query registry and WMI + script := `Get-WmiObject -Class Win32_Product | Select-Object Name, Version, InstallDate` + // ... processing logic ... +} +``` + +**Why Platform-Specific Collectors?** + +- **Accuracy**: Each platform has different package management systems +- **Performance**: Native tools are faster than generic approaches +- **Completeness**: Platform-specific tools see all installed software +- **Reliability**: Uses the same tools system administrators use + +--- + +## 🔄 Data Flow Narratives + +### Understanding the System Through Stories + +One of the best ways to understand a complex distributed system is to follow the journey of data as it moves through the components. Think of these data flows as stories—each one tells you something important about how the system behaves, why we made certain design choices, and what happens when things go wrong. + +These narratives aren't just technical documentation—they're debugging guides, onboarding tools, and architectural explanations all rolled into one. When you understand how data moves through the system, you understand the system itself. + +Understanding how data flows through our system is crucial for debugging, extending functionality, and understanding system behavior. Let's walk through the major data flows step by step, treating each one as a complete story with characters, challenges, and resolutions. + +### Data Flow 1: Template Creation and Distribution + +### The Journey from Idea to Execution + +This is one of our most important flows—how security templates get from a security analyst's mind into running vulnerability checks across thousands of systems. It's a story about taking human security knowledge and transforming it into automated, scalable detection. + +Imagine Sarah, a security analyst, discovers a new SSH configuration vulnerability in the morning security briefing. By lunch, she wants that vulnerability checked across every server in the infrastructure. This flow is the story of how that happens. + +#### **Step 1: Template Creation in UI** + +Sarah sits down at her computer and opens the Sirius UI. She's identified a new SSH vulnerability and wants to create a detection template for it. The UI provides a friendly interface for what is actually a complex distributed operation. + +A security analyst identifies a new vulnerability and wants to create a detection template. + +```typescript +// User fills out template creation form +const createTemplateForm = { + id: "SSH-CONFIG-002", + info: { + name: "SSH Key-Based Authentication Bypass", + severity: "high", + description: "Detects SSH configurations that allow authentication bypass", + }, + detection: { + type: "config-file", + files: [ + { + path: "/etc/ssh/sshd_config", + patterns: [ + { + regex: "^\\s*PermitUserEnvironment\\s+yes", + description: "User environment variable override enabled", + }, + ], + }, + ], + }, +}; + +// UI submits via tRPC mutation +const result = await api.agent.createTemplate.mutate({ + id: createTemplateForm.id, + content: yaml.stringify(createTemplateForm), +}); +``` + +**What happens here**: The UI validates the form data and converts it to YAML format. Instead of immediately showing the template as "created," the UI shows it as "processing" because the actual validation and distribution happens asynchronously. + +#### **Step 2: RabbitMQ Message Queue** + +The tRPC mutation publishes a message to RabbitMQ: + +```typescript +// tRPC procedure sends async message +await ctx.rabbitMQ.publish("agent_content_sync", { + operation: "create", + type: "template", + id: createTemplateForm.id, + content: createTemplateForm, + created_by: ctx.user.id, + timestamp: new Date().toISOString(), +}); +``` + +**Why RabbitMQ?** Template processing involves validation, file I/O, and potentially slow ValKey operations. Using a message queue means: + +- The UI doesn't freeze waiting for processing +- Template creation requests can't be lost if the Agent Server is temporarily down +- Multiple Agent Servers can process templates for scalability +- We get an automatic audit trail of all template operations + +#### **Step 3: Agent Server Processing** + +The Agent Server's RabbitMQ consumer picks up the message: + +```go +func (ccc *CustomContentConsumer) processTemplateMessage(message *CustomContentMessage) error { + log.Info("Processing template creation", "template_id", message.ID) + + // Step 3a: Parse YAML content + template := &Template{} + if err := yaml.Unmarshal([]byte(message.Content), template); err != nil { + return fmt.Errorf("invalid YAML: %w", err) + } + + // Step 3b: Validate template structure and logic + if err := ccc.validateTemplate(template); err != nil { + return fmt.Errorf("template validation failed: %w", err) + } + + // Step 3c: Save to filesystem for persistence + templatePath := filepath.Join(ccc.templatesDir, template.ID+".yaml") + if err := ccc.writeTemplateFile(templatePath, template); err != nil { + return fmt.Errorf("failed to save template: %w", err) + } + + // Step 3d: Store in ValKey for immediate agent access + templateMeta := &TemplateMetadata{ + Source: &TemplateSource{ + Type: "custom", + Path: templatePath, + CreatedBy: message.CreatedBy, + }, + SyncedAt: time.Now(), + } + + if err := ccc.valKeyStore.StoreTemplate(template.ID, template, templateMeta); err != nil { + return fmt.Errorf("failed to sync to ValKey: %w", err) + } + + log.Info("Template processed successfully", "template_id", template.ID) + return nil +} +``` + +**Template Validation**: This is where we catch problems: + +- **YAML Syntax**: Is the template properly formatted? +- **Schema Validation**: Does it have all required fields? +- **Logic Validation**: Are the detection conditions sensible? +- **Security Validation**: Could this template be used maliciously? + +#### **Step 4: ValKey Storage** + +The template is stored in ValKey with this structure: + +``` +# Template content (available to agents immediately) +agent:template:SSH-CONFIG-002 = { + "id": "SSH-CONFIG-002", + "info": { "name": "SSH Key-Based Authentication Bypass", ... }, + "detection": { "type": "config-file", ... } +} + +# Template metadata (for UI and management) +agent:template:meta:SSH-CONFIG-002 = { + "source": { "type": "custom", "path": "/custom-templates/SSH-CONFIG-002.yaml" }, + "synced_at": "2024-01-15T10:30:00Z", + "created_by": "analyst@company.com" +} + +# Update global manifest +agent:template:manifest = { + "templates": ["SSH-CONFIG-001", "SSH-CONFIG-002", ...], + "updated": "2024-01-15T10:30:00Z", + "total_count": 127 +} +``` + +#### **Step 5: Agent Template Loading** + +When agents next scan (or immediately if they're listening for updates), they load the new template: + +```go +func (te *TemplateEngine) LoadTemplates() ([]*Template, error) { + // Get all template keys from ValKey + keys, err := te.valKeyClient.Keys(ctx, "agent:template:*").Result() + if err != nil { + return nil, fmt.Errorf("failed to list templates: %w", err) + } + + var templates []*Template + for _, key := range keys { + // Skip metadata keys - only load template content + if strings.Contains(key, ":meta:") { + continue + } + + templateJSON, err := te.valKeyClient.Get(ctx, key).Result() + if err != nil { + log.Warn("Failed to load template", "key", key, "error", err) + continue + } + + var template Template + if err := json.Unmarshal([]byte(templateJSON), &template); err != nil { + log.Warn("Failed to parse template", "key", key, "error", err) + continue + } + + templates = append(templates, &template) + } + + return templates, nil +} +``` + +#### **Step 6: UI Feedback** + +The UI polls ValKey to see when the template becomes available: + +```typescript +// UI queries ValKey directly for real-time updates +const { data: templates } = api.agent.getTemplatesFromValKey.useQuery( + undefined, + { + refetchInterval: 5000, // Check every 5 seconds + onSuccess: (data) => { + // Show success notification when template appears + const newTemplate = data.find((t) => t.id === "SSH-CONFIG-002"); + if (newTemplate && !previousTemplates.includes(newTemplate)) { + showNotification("Template created successfully!"); + } + }, + } +); +``` + +**Why This Flow?** This seemingly complex flow provides several benefits: + +- **Reliability**: Template creation can't fail silently +- **Performance**: UI stays responsive during processing +- **Consistency**: All components see templates at the same time +- **Auditability**: Complete trail of template creation and distribution + +### Data Flow 2: Agent Scan Execution + +This flow shows how a security scan request travels from the UI through the system and back with results. + +#### **Step 1: Scan Initiation** + +A security analyst wants to scan a specific host or group of hosts: + +```typescript +// UI scan request +const scanRequest = { + target: "production-web-servers", // Or specific agent ID + scanType: "full", // full, quick, templates-only + includeTemplates: true, + includeSBOM: true, + priority: "high", +}; + +const result = await api.agent.triggerScan.mutate(scanRequest); +``` + +#### **Step 2: Scan Coordination** + +The Agent Server receives the scan request and determines which agents should execute it: + +```go +func (s *Server) triggerScan(req *ScanRequest) error { + // Determine target agents + targetAgents, err := s.resolveTargets(req.Target) + if err != nil { + return fmt.Errorf("failed to resolve targets: %w", err) + } + + // Create scan commands for each agent + for _, agentID := range targetAgents { + scanCommand := &pb.ServerMessage{ + CommandId: generateCommandID(), + Type: "scan", + Payload: marshalScanRequest(req), + Timestamp: time.Now().Unix(), + } + + // Send to agent via gRPC stream + if err := s.sendCommandToAgent(agentID, scanCommand); err != nil { + log.Warn("Failed to send scan command", "agent_id", agentID, "error", err) + continue + } + + // Track command for result correlation + s.trackCommand(scanCommand.CommandId, agentID, req) + } + + return nil +} +``` + +#### **Step 3: Agent Scan Execution** + +Each target agent receives the scan command and executes it: + +```go +func (a *Agent) handleScanCommand(msg *pb.ServerMessage) { + log.Info("Received scan command", "command_id", msg.CommandId) + + // Parse scan parameters + scanReq := &ScanRequest{} + if err := json.Unmarshal([]byte(msg.Payload), scanReq); err != nil { + a.sendCommandResult(msg.CommandId, 1, fmt.Sprintf("Invalid scan request: %v", err)) + return + } + + // Execute comprehensive scan + startTime := time.Now() + result, err := a.scanCommand.ExecuteScan(context.Background(), ScanOptions{ + IncludeTemplates: scanReq.IncludeTemplates, + IncludeSBOM: scanReq.IncludeSBOM, + ScanType: scanReq.ScanType, + }) + + if err != nil { + a.sendCommandResult(msg.CommandId, 1, fmt.Sprintf("Scan failed: %v", err)) + return + } + + // Enrich result with execution metadata + result.ScanSummary.ExecutionTime = time.Since(startTime) + result.ScanSummary.CommandID = msg.CommandId + result.ScanSummary.AgentVersion = a.version + + // Send results back to server + resultJSON, _ := json.Marshal(result) + a.sendCommandResult(msg.CommandId, 0, string(resultJSON)) +} +``` + +#### **Step 4: Comprehensive Data Collection** + +The agent's scan command orchestrates multiple data collection activities: + +```go +func (sc *ScanCommand) ExecuteScan(ctx context.Context, options ScanOptions) (*ScanResult, error) { + result := &ScanResult{ + AgentID: sc.agentID, + Hostname: sc.getHostname(), + Platform: runtime.GOOS, + ScanTimestamp: time.Now(), + } + + // Collect SBOM data if requested + if options.IncludeSBOM { + packages, err := sc.collectSoftwareInventory(ctx) + if err != nil { + log.Warn("SBOM collection failed", "error", err) + } else { + result.Packages = packages + result.ScanSummary.PackagesCollected = len(packages) + } + + // Collect system fingerprint + fingerprint, err := sc.collectSystemFingerprint(ctx) + if err != nil { + log.Warn("System fingerprint collection failed", "error", err) + } else { + result.SystemFingerprint = fingerprint + } + } + + // Execute vulnerability templates if requested + if options.IncludeTemplates { + templateResults, err := sc.executeTemplateDetection(ctx, result) + if err != nil { + log.Warn("Template detection failed", "error", err) + } else { + result.TemplateResults = templateResults + result.ScanSummary.TemplatesExecuted = len(templateResults) + result.ScanSummary.VulnerabilitiesFound = countVulnerabilities(templateResults) + } + } + + return result, nil +} +``` + +#### **Step 5: Result Processing and Storage** + +When the Agent Server receives scan results, it processes and stores them: + +```go +func (s *Server) processScanResult(agentID string, commandID string, resultJSON string) error { + // Parse scan result + var scanResult ScanResult + if err := json.Unmarshal([]byte(resultJSON), &scanResult); err != nil { + return fmt.Errorf("failed to parse scan result: %w", err) + } + + // Convert to database format + host, softwareInventory, systemFingerprint, agentMetadata, err := + s.convertScanResultToHost(scanResult) + if err != nil { + return fmt.Errorf("failed to convert scan result: %w", err) + } + + // Store in PostgreSQL via Sirius API + if err := s.siriusAPI.CreateOrUpdateHost(host, softwareInventory, systemFingerprint, agentMetadata); err != nil { + return fmt.Errorf("failed to store scan result: %w", err) + } + + // Cache result in ValKey for fast access + resultKey := fmt.Sprintf("scan:result:%s", commandID) + if err := s.valKeyClient.Set(context.Background(), resultKey, resultJSON, 24*time.Hour).Err(); err != nil { + log.Warn("Failed to cache scan result", "command_id", commandID, "error", err) + } + + log.Info("Scan result processed successfully", + "agent_id", agentID, + "command_id", commandID, + "packages_found", len(scanResult.Packages), + "vulnerabilities_found", len(scanResult.TemplateResults)) + + return nil +} +``` + +#### **Step 6: UI Visualization** + +The UI retrieves and displays scan results: + +```typescript +// Query scan results with real-time updates +const { data: scanResults } = api.scan.getRecentResults.useQuery( + { agentId: selectedAgent.id }, + { + refetchInterval: 10000, // Update every 10 seconds + onSuccess: (data) => { + // Update dashboard with new vulnerabilities + updateVulnerabilityMetrics(data); + + // Show notifications for critical findings + const criticalVulns = data.filter((r) => r.severity === "critical"); + if (criticalVulns.length > 0) { + showCriticalAlert( + `${criticalVulns.length} critical vulnerabilities found!` + ); + } + }, + } +); + +// Render results in dashboard +return ( +
+ + + + + +
+); +``` + +**Key Insights from This Flow**: + +- **Asynchronous by Design**: Each step can proceed independently +- **Error Isolation**: Failures in one part don't break the entire scan +- **Rich Context**: SBOM data provides context for vulnerability assessment +- **Real-Time Updates**: UI gets results as soon as they're available + +### Data Flow 3: Template Synchronization + +This flow shows how repository templates get synchronized across the system. + +#### **Repository-Based Template Updates** + +Templates maintained in the `sirius-agent-modules` repository automatically sync to all agents: + +```go +// Triggered on Agent Server startup and periodically +func (ts *TemplateSyncService) syncRepositoryTemplates(results *SyncResults) error { + repoPath := "/app-agent/sirius-agent-modules/templates" + + // Walk through all YAML files in repository + return filepath.Walk(repoPath, func(path string, info os.FileInfo, err error) error { + if !strings.HasSuffix(info.Name(), ".yaml") { + return nil + } + + // Load and validate each template + template, err := ts.loadTemplate(path) + if err != nil { + log.Warn("Failed to load repository template", "path", path, "error", err) + return nil // Continue with other templates + } + + // Store in ValKey with repository source metadata + templateMeta := &TemplateMetadata{ + Source: &TemplateSource{ + Type: "repository", + Path: path, + Version: ts.getRepositoryVersion(), + }, + SyncedAt: time.Now(), + } + + if err := ts.valKeyStore.StoreTemplate(template.ID, template, templateMeta); err != nil { + log.Warn("Failed to store repository template", "template_id", template.ID, "error", err) + return nil + } + + log.Debug("Synced repository template", "template_id", template.ID, "path", path) + results.RepositoryTemplates++ + return nil + }) +} +``` + +**Why This Approach?** + +- **Version Control**: Repository templates are version-controlled and peer-reviewed +- **Consistency**: All environments get the same templates +- **Automatic Updates**: New templates deploy without manual intervention +- **Rollback Capability**: Git history allows rolling back problematic templates + +--- + +## 🎨 Template System Design + +### The Vision: Security Knowledge as Code + +The template system is one of our most sophisticated components, designed to make vulnerability detection as easy as writing a YAML file. But it's more than just a technical feature—it represents a fundamental shift in how we think about security knowledge. + +Traditional security tools treat vulnerability detection as a programming problem. Our template system treats it as a knowledge management problem. The difference is profound. + +Understanding how templates work is crucial for both using and extending the system, but more importantly, understanding the philosophy behind templates will change how you think about scalable security automation. + +### The Problem: Security Knowledge Trapped in Code + +Imagine this scenario: A new SSH vulnerability is discovered on Tuesday. In traditional security tools, here's what happens: + +1. A security researcher identifies the vulnerability +2. They write a technical paper describing it +3. A software developer reads the paper +4. The developer writes code to detect the vulnerability +5. The code goes through review, testing, and deployment +6. Finally, weeks later, the detection is available + +This process has several critical flaws that become apparent at scale. + +### Philosophy Behind Template-Based Detection + +Traditional vulnerability scanners require developers to write custom code for each new vulnerability. This creates several problems that compound over time: + +1. **High Barrier to Entry**: Only developers can create new detections +2. **Deployment Complexity**: Code changes require full application deployments +3. **Risk**: Code bugs can crash the entire scanner +4. **Maintenance Overhead**: Each detection requires ongoing code maintenance +5. **Knowledge Silos**: Security expertise gets locked away in code that only developers can modify + +The human cost of this approach is enormous. Security experts become dependent on developers for everything, developers become bottlenecks for security response, and the feedback loop between threat discovery and detection deployment stretches to weeks or months. + +Our template system solves these problems by fundamentally changing the relationship between security knowledge and implementation: + +1. **Declarative Configuration**: Security analysts describe WHAT to look for, not HOW to look for it +2. **Hot Deployment**: New templates deploy without restarting agents +3. **Sandboxed Execution**: Template errors don't affect other templates or the agent +4. **Community Contribution**: Non-developers can contribute vulnerability detections +5. **Knowledge Accessibility**: Security logic is readable and modifiable by security experts + +**The Vision**: In our ideal world, the time from vulnerability discovery to detection deployment is measured in minutes, not weeks. Security experts should be able to codify their knowledge directly, without translation through development teams. + +### Templates as a Universal Language + +Think of templates as a universal language for describing security vulnerabilities. Just as SQL lets you query databases without writing low-level file access code, templates let you define vulnerability detection without writing system-level inspection code. + +This abstraction is powerful because it separates concerns: + +- **Security experts** focus on what makes a system vulnerable +- **The template engine** handles how to inspect systems safely and efficiently +- **The platform** manages distribution, execution, and result processing + +### Template Anatomy + +Let's understand a template by examining a real example and deconstructing each part to see how human security knowledge translates into automated detection: + +```yaml +# SSH Configuration Vulnerability Template +id: "SSH-CONFIG-001" +info: + name: "SSH Weak Configuration Detection" + author: "security-team" + severity: "medium" + description: "Detects SSH configurations that allow authentication bypass" + references: + - "https://nvd.nist.gov/vuln/detail/CVE-2023-12345" + cve: "CVE-2023-12345" + updated: "2024-01-15" + +detection: + type: "config-file" + files: + - path: "/etc/ssh/sshd_config" + patterns: + - regex: "^\\s*PermitUserEnvironment\\s+yes" + description: "User environment variable override enabled" + - regex: "^\\s*PermitRootLogin\\s+yes" + description: "Direct root login permitted" + + conditions: + - type: "file_exists" + value: true + - type: "pattern_found" + value: true + +remediation: + description: "Disable dangerous SSH configuration options" + commands: + linux: | + sudo sed -i 's/^PermitUserEnvironment yes/PermitUserEnvironment no/' /etc/ssh/sshd_config + sudo sed -i 's/^PermitRootLogin yes/PermitRootLogin no/' /etc/ssh/sshd_config + sudo systemctl restart sshd + verification: + command: "sudo sshd -T | grep -E '(permituserenvironment|permitrootlogin)'" + expected_output: | + permituserenvironment no + permitrootlogin no +``` + +This template tells a complete story: what the vulnerability is, how to detect it, and how to fix it. Let's break down each section: + +#### **1. Metadata Section (`info:`)** + +This section provides context about the vulnerability - the "who, what, when, where, why" of security knowledge: + +- **`id`**: Unique identifier used throughout the system +- **`name`**: Human-readable vulnerability name +- **`severity`**: Risk level that drives prioritization +- **`cve`**: Links to existing vulnerability databases for correlation +- **`references`**: External documentation for deeper understanding + +**Why This Structure?** This metadata enables the system to automatically prioritize, correlate, and report on vulnerabilities in ways that match how security teams actually work. + +#### **2. Detection Logic (`detection:`)** + +This is where security knowledge becomes executable logic: + +```yaml +detection: + type: "config-file" # How to look for the vulnerability + files: # Where to look + - path: "/etc/ssh/sshd_config" + patterns: # What patterns indicate danger + - regex: "^\\s*PermitUserEnvironment\\s+yes" + description: "User environment variable override enabled" +``` + +The beauty of this approach is that security experts can focus on the logic ("look for PermitUserEnvironment set to yes") while the template engine handles the implementation details (file reading, regex execution, error handling). + +#### **3. Conditions (`conditions:`)** + +Conditions prevent false positives by ensuring context: + +```yaml +conditions: + - type: "file_exists" # File must exist + value: true + - type: "pattern_found" # Pattern must be found + value: true +``` + +This prevents the common problem of vulnerability scanners that report issues based on partial information. + +#### **4. Remediation Guidance (`remediation:`)** + +Templates don't just find problems—they help solve them: + +```yaml +remediation: + description: "Clear explanation of the fix" + commands: + linux: "Platform-specific commands" + windows: "Different commands for different systems" + verification: + command: "How to verify the fix worked" +``` + +This turns vulnerability detection into actionable security improvement, closing the loop from discovery to resolution. + +--- + +## 💻 Development Workflows + +### The Daily Life of a Sirius Developer + +Understanding development workflows is about more than just knowing commands—it's about understanding how to work effectively with a complex distributed system. This section tells the story of how developers actually interact with the system day-to-day. + +Whether you're fixing a bug, adding a new feature, or investigating a production issue, these workflows have been battle-tested by real developers solving real problems. + +### Setting Up Your Development Environment + +#### **The Philosophy: Production Parity** + +Our development setup prioritizes one thing above all else: consistency with production. Every developer should have an environment that behaves exactly like production, because the alternative—debugging environment-specific issues—is a productivity killer. + +#### **Prerequisites** + +Before you can effectively work on Sirius, your development machine needs several tools. These aren't arbitrary requirements—each tool serves a specific purpose in our development workflow: + +```bash +# Container orchestration - because our production runs in containers +docker --version # Docker for containerization +docker-compose --version # Docker Compose for orchestration + +# Backend development - our agents and servers are written in Go +go version # Go 1.21+ for backend development + +# Frontend development - our UI is built with modern web technologies +node --version # Node.js 18+ for frontend development + +# Version control - for collaboration and deployment +git --version # Git for version control +``` + +#### **Environment Setup: The Step-by-Step Journey** + +Setting up Sirius is designed to be straightforward, but understanding what each step accomplishes helps you troubleshoot when things go wrong: + +```bash +# Step 1: Get the code +git clone https://github.com/SiriusScan/Sirius.git +cd Sirius + +# Step 2: Configure for local development +cp docker-compose.local.example.yaml docker-compose.override.yaml + +# Step 3: Start the foundation services +docker-compose up -d valkey rabbitmq postgres + +# Step 4: Start the UI in development mode +cd sirius-ui +npm install +npm run dev + +# Step 5: Start the agent server (in a separate terminal) +cd ../app-agent +docker exec -it sirius-engine /bin/bash +go run cmd/server/main.go +``` + +**What's Really Happening**: This setup creates a complete Sirius environment on your local machine. ValKey, RabbitMQ, and PostgreSQL run in containers (matching production), while the UI and Agent Server run in development mode for fast iteration. + +### Common Development Tasks + +#### **Task 1: Adding a New Template** + +Creating templates is one of the most common development tasks, and it illustrates the complete development cycle from idea to deployment. + +**The Story**: You've discovered a new Nginx vulnerability and want to add detection for it. Here's the complete journey: + +**Step 1: Create the Template** + +```bash +# Navigate to template repository +cd sirius-agent-modules/templates/config-based + +# Create the template file +cat > nginx-security-headers.yaml << EOF +id: "NGINX-SEC-001" +info: + name: "Nginx Security Headers Missing" + severity: "medium" + description: "Detects missing security headers in Nginx configuration" + +detection: + type: "config-file" + files: + - path: "/etc/nginx/nginx.conf" + patterns: + - regex: "add_header X-Frame-Options" + description: "X-Frame-Options header configured" + + conditions: + - type: "file_exists" + value: true + - type: "pattern_found" + value: false # Vulnerability when pattern NOT found +EOF +``` + +**Step 2: Test Locally** + +```bash +# Enter the development container +docker exec -it sirius-engine /bin/bash +cd /app-agent + +# Test template syntax +go run cmd/template-test/main.go --template=/app-agent/sirius-agent-modules/templates/config-based/nginx-security-headers.yaml + +# Test template execution +./agent scan --templates-only --template-filter="NGINX-SEC-001" +``` + +**Step 3: Deploy and Verify** + +```bash +# Restart Agent Server to pick up new template +docker restart sirius-engine + +# Check synchronization logs +docker logs sirius-engine | grep "NGINX-SEC-001" + +# Verify storage in ValKey +docker exec sirius-engine valkey-cli get "agent:template:NGINX-SEC-001" +``` + +This workflow embodies our development philosophy: test early, test often, and verify at each step. + +### The Art of Debugging + +#### **Debugging Agent Connection Issues** + +When agents won't connect, the investigation follows a systematic approach that's saved us countless hours: + +**The Detective Story**: An agent shows as offline in the UI. Where do you start? + +**Step 1: Check the Foundation** + +```bash +# Is the Agent Server even running? +docker logs sirius-engine | grep "gRPC server listening" + +# Are agents trying to connect? +docker logs sirius-engine | grep "Agent.*connected" + +# Are there authentication failures? +docker logs sirius-engine | grep "authentication failed" +``` + +**Step 2: Test the Network Path** + +```bash +# Can you reach the gRPC port? +telnet localhost 50051 + +# Is the gRPC service responding? +grpcurl -plaintext localhost:50051 list +``` + +**Step 3: Check Agent-Side Issues** + +```bash +# What does the agent think is happening? +./agent internal:status + +# Can the agent reach the server? +./agent ping --server=localhost:50051 +``` + +This systematic approach turns mysterious connection problems into solvable puzzles. + +--- + +## 💾 Database Strategy + +### The Tale of Two Databases + +Our database architecture tells a story about trade-offs, performance, and the practical realities of building distributed systems. We use two different databases not because we love complexity, but because different types of data have fundamentally different requirements. + +Understanding why we made these choices will help you understand how to work effectively with the data layer. + +### Why Two Databases? + +The decision to use both PostgreSQL and ValKey wasn't made lightly. It emerged from the practical realities of building a system that needs to be both highly available and capable of complex analysis. + +**PostgreSQL for Deep Analysis**: When security teams need to correlate vulnerabilities across thousands of hosts, find patterns in software installations, or generate compliance reports, they need the power of SQL and the reliability of ACID transactions. + +**ValKey for Real-Time Operations**: When an agent needs to load templates, or the UI needs to show current agent status, they need microsecond response times and don't want to wait for complex database queries to complete. + +### PostgreSQL: The Foundation of Trust + +#### **Host Table with JSONB Extensions** + +Our PostgreSQL schema balances structure with flexibility: + +```sql +-- Core host table with structured data +CREATE TABLE hosts ( + id SERIAL PRIMARY KEY, + hostname VARCHAR(255) NOT NULL, + ip_address INET, + platform VARCHAR(50), + created_at TIMESTAMP DEFAULT NOW(), + updated_at TIMESTAMP DEFAULT NOW(), + + -- JSONB fields for flexible agent data + software_inventory JSONB, + system_fingerprint JSONB, + agent_metadata JSONB +); + +-- Indexes for efficient JSONB queries +CREATE INDEX idx_hosts_packages_gin ON hosts USING GIN ((software_inventory->'packages')); +CREATE INDEX idx_hosts_platform ON hosts USING GIN ((system_fingerprint->'platform')); +CREATE INDEX idx_hosts_agent_gin ON hosts USING GIN (agent_metadata); +``` + +**The Philosophy**: Use structured columns for data that has consistent meaning across all hosts (hostname, IP address) and JSONB for data that varies by platform or agent capability. + +#### **JSONB: The Best of Both Worlds** + +JSONB gives us the flexibility of document storage with the power of relational queries: + +```sql +-- Find all hosts with vulnerable Apache versions +SELECT hostname, software_inventory->'packages' +FROM hosts +WHERE software_inventory->'packages' @> '[{"name": "apache2"}]' + AND software_inventory @@ '$.packages[*] ? (@.name == "apache2" && @.version like_regex "^2\\.4\\.(4[0-2])")'; + +-- Find hosts missing critical security updates +SELECT hostname, (software_inventory->'scan_metadata'->>'scan_date')::timestamp +FROM hosts +WHERE (software_inventory->'scan_metadata'->>'scan_date')::timestamp < (NOW() - INTERVAL '7 days'); +``` + +### ValKey: The Speed of Thought + +#### **Key Naming Strategy: A Language for Data** + +Our ValKey keys follow patterns that make the data self-documenting: + +``` +# Template Storage +agent:template:{template_id} # Template YAML content +agent:template:meta:{template_id} # Template metadata +agent:template:manifest # Global template index + +# Agent Management +agent:state:{agent_id} # Agent connection state +agent:heartbeat:{agent_id} # Agent health (with TTL) + +# Scan Coordination +scan:queue:pending # Pending scan requests +scan:result:{scan_id} # Cached scan results +``` + +**Why This Matters**: When you're debugging at 2 AM, these patterns let you quickly find the data you need without consulting documentation. + +--- + +## 🚀 Developer Handbook + +### The Practical Guide to Daily Development + +This handbook distills years of experience into practical guidance for common scenarios. It's not just about knowing what commands to run—it's about understanding the patterns that make you productive and the pitfalls that waste time. + +### Debugging Workflows + +#### **The "Template Not Appearing" Mystery** + +This is probably the most common issue developers encounter. Here's the detective story: + +**Symptoms**: You created a template in the UI, but it's not showing up in the agent template list. + +**The Investigation Process**: + +```bash +# Step 1: Did the message make it through RabbitMQ? +docker exec sirius-engine rabbitmqctl list_queues name messages + +# Step 2: Did the Agent Server process it? +docker logs sirius-engine | grep "template.*processing" + +# Step 3: Did it make it to ValKey? +docker exec sirius-engine valkey-cli keys "agent:template:*" + +# Step 4: Are there validation errors? +docker logs sirius-engine | grep "template.*validation.*failed" +``` + +**Common Culprits and Solutions**: + +1. **YAML Syntax Errors**: Use `yamllint` or an online YAML validator +2. **Template Validation Failures**: Check the Agent Server logs for specific validation errors +3. **RabbitMQ Connection Issues**: Verify RabbitMQ is running and accessible + +### Frontend Development Best Practices + +#### **Using the Utility System** + +Our frontend utility organization follows strict patterns that promote maintainability and code reuse. Here's how to work effectively with the utility system: + +**Import Patterns**: + +```typescript +// ✅ DO: Import specific utilities you need +import { + convertToYamlForEditing, + convertYamlToJson, +} from "~/utils/yamlConverter"; +import { VALIDATION_MESSAGES, DEFAULT_VALUES } from "~/utils/constants"; +import { TemplateContent, ScriptContent } from "~/utils/types"; + +// ❌ DON'T: Import entire utility modules unless needed +import * as yamlConverter from "~/utils/yamlConverter"; // Avoid this +``` + +**Type Safety Best Practices**: + +```typescript +// ✅ DO: Use proper TypeScript interfaces +const handleTemplateSubmit = (template: TemplateContent) => { + // TypeScript knows the exact structure + const yamlContent = convertToYamlForEditing(template); + // ... +}; + +// ❌ DON'T: Use 'any' types in new code +const handleTemplateSubmit = (template: any) => { + // Avoid this + // ... +}; +``` + +**Constants Usage**: + +```typescript +// ✅ DO: Use centralized constants +alert(VALIDATION_MESSAGES.requiredFields); +const editorHeight = MONACO_HEIGHTS.editor; + +// ❌ DON'T: Use magic strings/numbers +alert("Please fill in all required fields"); // Avoid this +const editorHeight = "500px"; // Avoid this +``` + +**YAML Conversion Patterns**: + +```typescript +// ✅ DO: Use utility functions for conversion +const yamlContent = convertToYamlForEditing(templateData); +const jsonData = convertYamlToJson(userInput); + +// ❌ DON'T: Duplicate conversion logic +const yamlContent = JSON.stringify(templateData, null, 2); // Avoid this +``` + +#### **Adding New Utilities** + +When adding new utility functions, follow these patterns: + +**1. Choose the Right Utility File**: + +- `yamlConverter.ts` - YAML/JSON conversion functions +- `types.ts` - TypeScript interfaces and type definitions +- `constants.ts` - Configuration values, messages, defaults +- `monacoUtils.ts` - Monaco editor specific utilities +- `scriptTemplates.ts` - Script template generation + +**2. Follow Function Patterns**: + +```typescript +// ✅ DO: Pure functions with clear interfaces +export const formatContent = (content: string): string => { + if (!content) return ""; + + return content.replace(/\\n/g, "\n").replace(/\\t/g, "\t"); +}; + +// ✅ DO: Use proper error handling +export const parseTemplate = (yaml: string): TemplateContent => { + try { + return parseYamlLikeContent(yaml); + } catch (error) { + console.error("Failed to parse template:", error); + throw new Error("Invalid template format"); + } +}; +``` + +**3. Export Patterns**: + +```typescript +// ✅ DO: Use named exports for discoverability +export const convertToYamlForEditing = (contentData: unknown): string => { + // ... +}; + +export const VALIDATION_MESSAGES = { + // ... +} as const; + +// ❌ DON'T: Use default exports for utilities +export default function convert() {} // Avoid this +``` + +### Performance Optimization + +#### **Template Execution Performance** + +Templates that take too long to execute can slow down entire scans. Here's how to optimize: + +```go +// Add performance monitoring to template execution +func (te *TemplateEngine) ExecuteTemplate(ctx context.Context, template *Template) (*DetectionResult, error) { + startTime := time.Now() + defer func() { + executionTime := time.Since(startTime) + + // Flag slow templates for optimization + if executionTime > 5*time.Second { + log.Warn("Slow template execution", + "template_id", template.ID, + "execution_time", executionTime) + } + + // Track metrics for monitoring + templateExecutionDuration.WithLabelValues(template.ID).Observe(executionTime.Seconds()) + }() + + // ... template execution logic ... +} +``` + +### Security Best Practices + +#### **Template Security Validation** + +Templates are powerful, which means they can be dangerous if not properly validated: + +```go +func (tv *TemplateValidator) ValidateSecurityConstraints(template *Template) error { + // Prevent directory traversal attacks + for _, file := range template.Detection.Files { + if strings.Contains(file.Path, "..") || strings.Contains(file.Path, "~") { + return fmt.Errorf("invalid file path: %s", file.Path) + } + + // Block access to sensitive system files + sensitiveFiles := []string{"/etc/shadow", "/etc/passwd", "/proc/", "/sys/"} + for _, sensitive := range sensitiveFiles { + if strings.HasPrefix(file.Path, sensitive) { + return fmt.Errorf("access to sensitive file not allowed: %s", file.Path) + } + } + } + + // Prevent ReDoS attacks through regex validation + for _, file := range template.Detection.Files { + for _, pattern := range file.Patterns { + if len(pattern.Regex) > 1000 { + return fmt.Errorf("regex pattern too long: %s", pattern.Regex) + } + + // Check for dangerous patterns + if strings.Contains(pattern.Regex, "(.*)*") || strings.Contains(pattern.Regex, "(.+)+") { + return fmt.Errorf("potentially dangerous regex pattern: %s", pattern.Regex) + } + } + } + + return nil +} +``` + +### Deployment and Operations + +#### **Health Check Configuration** + +Comprehensive health checks are essential for production operations: + +```go +func (s *Server) HealthCheck(w http.ResponseWriter, r *http.Request) { + health := &HealthStatus{ + Status: "healthy", + Timestamp: time.Now(), + Checks: make(map[string]CheckResult), + } + + // Check all critical dependencies + if err := s.valKeyClient.Ping(context.Background()).Err(); err != nil { + health.Checks["valkey"] = CheckResult{Status: "unhealthy", Error: err.Error()} + health.Status = "unhealthy" + } else { + health.Checks["valkey"] = CheckResult{Status: "healthy"} + } + + // Set appropriate HTTP status code + if health.Status == "unhealthy" { + w.WriteHeader(http.StatusServiceUnavailable) + } + + json.NewEncoder(w).Encode(health) +} +``` + +### The Journey Continues + +This documentation represents not just technical knowledge, but the collective experience of building and operating a complex security platform. As you work with Sirius, you'll develop your own insights and best practices. + +Remember: every production issue is a learning opportunity, every performance bottleneck teaches you something about the system, and every feature request helps you understand how security teams really work. + +The goal isn't to memorize every detail in this guide—it's to understand the principles and patterns that will help you solve problems you haven't encountered yet. + +--- + +**Document Status**: ✅ Complete Comprehensive Developer Guide (v2.1) +**Target Audience**: New developers joining the Sirius Agent project +**Next Steps**: Use this guide for developer onboarding, team training, and as a reference for daily development work + +**Recent Improvements (v2.1)**: + +- ✅ **Utility Organization**: Extracted shared functions into dedicated utility modules +- ✅ **Type Safety**: Eliminated `any` types and improved TypeScript interfaces +- ✅ **Code Quality**: Removed debug logging and standardized constants +- ✅ **Maintainability**: Reduced code duplication and improved organization +- ✅ **Developer Experience**: Enhanced development workflows and best practices + +**Final Word**: Building distributed security systems is challenging, but it's also incredibly rewarding. You're not just writing code—you're building tools that help protect organizations from real threats. The complexity exists for a reason, and understanding that reason will make you a more effective developer and a better security engineer. + +With the recent v2.1 improvements, the codebase is now more maintainable, type-safe, and developer-friendly than ever. These improvements will accelerate development velocity and reduce the learning curve for new team members. diff --git a/documentation/dev-notes/archive/AGENT-TEMPLATE-REPO-PLAN.md b/documentation/dev-notes/archive/AGENT-TEMPLATE-REPO-PLAN.md new file mode 100644 index 0000000..59c9ffd --- /dev/null +++ b/documentation/dev-notes/archive/AGENT-TEMPLATE-REPO-PLAN.md @@ -0,0 +1,326 @@ +# Sirius Agent Modules Repository Management System + +## Overview + +This document outlines the implementation plan for Phase 4 of the Sirius Agent Enhancements project: Repository Management and Update System. The goal is to create a centralized repository system for vulnerability detection templates and scripts that allows for easy community contributions and automated updates. + +**Repository Name**: `sirius-agent-modules` (existing repository) +**Location**: `../minor-projects/sirius-agent-modules` + +## Current Repository Structure + +### Completed Structure ✅ + +``` +sirius-agent-modules/ +├── README.md ✅ +├── repository-manifest.json ✅ +├── docs/ +│ ├── template-development.md ✅ +│ ├── script-development.md ✅ +│ └── contribution-guidelines.md ✅ +├── templates/ +│ ├── manifest.json ✅ +│ ├── hash-based/ +│ │ └── apache-vulnerabilities.yaml ✅ +│ ├── registry-based/ ✅ +│ │ └── windows-services.yaml ✅ +│ └── config-based/ +│ └── ssh-weak-config.yaml ✅ +└── scripts/ + ├── manifest.json ✅ + ├── windows/ ✅ + │ └── check-service-permissions.ps1 ✅ + ├── linux/ ✅ + │ └── check-suid-binaries.sh ✅ + └── cross-platform/ + ├── find-password-files.sh ✅ + └── certificate-validation.py ✅ +``` + +### Repository Statistics ✅ + +- **Total Templates**: 3 (hash-based: 1, registry-based: 1, config-based: 1) +- **Total Scripts**: 4 (Windows: 1, Linux: 1, Cross-platform: 2) +- **Platform Coverage**: Windows (3), Linux (4), macOS (3) +- **Severity Distribution**: High (4), Medium (3) + +## Repository Architecture + +### Repository-Level Versioning ✅ + +- **Semantic Versioning**: Repository uses semantic versioning (e.g., v1.0.0, v1.1.0) +- **Manifest-Based**: All version information stored in `repository-manifest.json` +- **Atomic Updates**: Entire repository updated as a single unit +- **Rollback Support**: Previous versions can be restored + +### Top-Level Repository Manifest ✅ + +```json +{ + "version": "1.0.0", + "updated": "2024-01-15T10:30:00Z", + "metadata": { + "name": "sirius-agent-modules", + "description": "Official Sirius vulnerability detection templates and scripts", + "publisher": "Sirius Security", + "license": "MIT", + "url": "https://github.com/sirius-security/sirius-agent-modules", + "min_agent_version": "1.0.0" + }, + "components": { + "templates": { + "version": "1.0.0", + "path": "templates/", + "manifest": "templates/manifest.json", + "updated": "2024-01-15T10:30:00Z" + }, + "scripts": { + "version": "1.0.0", + "path": "scripts/", + "manifest": "scripts/manifest.json", + "updated": "2024-01-15T10:30:00Z" + } + }, + "statistics": { + "total_templates": 3, + "total_scripts": 4, + "by_type": { + "hash-based": 1, + "registry-based": 1, + "config-based": 1 + }, + "by_platform": { + "windows": 3, + "linux": 4, + "macos": 3 + } + } +} +``` + +## Implementation Plan + +### Phase 4.1: Complete Repository Structure ✅ + +- **Status**: COMPLETED +- **Tasks**: + - ✅ Add missing directories (registry-based, windows scripts, linux scripts) + - ✅ Create top-level repository-manifest.json + - ✅ Update README.md with proper description + - ✅ Add contribution guidelines + - ✅ Update existing documentation + +#### 4.1.1 Repository Manager Implementation ✅ + +- **File**: `app-agent/internal/repository/github_manager.go` +- **Status**: ✅ **COMPLETED** +- **Features**: + - GitHub repository synchronization + - Manifest-based version tracking + - Incremental update detection + - Atomic update application + - Checksum validation + - Backup and rollback support + +### Phase 4.2: Repository Integration (Week 1-2) + +#### 4.2.1 Agent Repository Integration + +- **File**: `app-agent/internal/repository/integration.go` +- **Features**: + - Repository initialization with `sirius-agent-modules` + - Template loading from repository + - Script loading from repository + - Update coordination + - Error handling and recovery + +#### 4.2.2 Scan Command Integration + +- **File**: `app-agent/internal/commands/scan/scan_command.go` +- **Integration Points**: + - Load templates from `sirius-agent-modules` repository + - Execute templates with repository context + - Cache templates for performance + - Handle template updates + +#### 4.2.3 Script Executor Integration + +- **File**: `app-agent/internal/detect/script/executor.go` +- **Integration Points**: + - Load scripts from `sirius-agent-modules` repository + - Execute scripts with security controls + - Cache scripts for performance + - Handle script updates + +### Phase 4.3: CLI Commands (Week 2) + +#### 4.3.1 Repository Management Commands + +- **Commands**: + - `internal:repo-status` - Show repository status and version + - `internal:repo-update` - Manual repository update + - `internal:repo-list` - List available templates/scripts + - `internal:repo-validate` - Validate repository integrity + +### Phase 4.4: Community Collaboration (Week 2-3) + +#### 4.4.1 Basic Pull Request Workflow + +- **Repository**: `sirius-agent-modules` (existing) +- **Contribution**: Standard GitHub pull request workflow +- **Review Process**: Manual review by maintainers +- **Quality Gates**: Automated validation and testing + +#### 4.4.2 Template Development Guidelines ✅ + +- **File**: `docs/template-development.md` ✅ +- **Content**: + - Template structure and syntax + - Best practices for detection logic + - Testing requirements + - Submission guidelines + +#### 4.4.3 Script Development Guidelines ✅ + +- **File**: `docs/script-development.md` ✅ +- **Content**: + - Script structure and output format + - Security best practices + - Platform compatibility requirements + - Testing and validation + +## Technical Implementation Details + +### Repository Manager Interface + +```go +type RepositoryManager interface { + Initialize(ctx context.Context) error + UpdateRepository(ctx context.Context) (*UpdateResult, error) + LoadManifest() (*Manifest, error) + SaveManifest(manifest *Manifest) error + GetRepositoryInfo() (*RepositoryInfo, error) + ValidateRepository(ctx context.Context) (*ValidationResult, error) +} +``` + +### Update Process Flow + +1. **Check for Updates**: Download remote manifest and compare with local +2. **Download Changes**: Download new/updated files only +3. **Validate Content**: Verify checksums and file integrity +4. **Apply Updates**: Atomic update with backup +5. **Update Manifest**: Save new manifest locally +6. **Notify Agent**: Trigger template/script reload + +### Security Considerations + +- **Checksum Validation**: SHA256 checksums for all files +- **HTTPS Only**: Secure communication with repository +- **Sandboxed Execution**: Script execution in controlled environment +- **Content Validation**: Template and script format validation + +### Performance Optimizations + +- **Incremental Updates**: Download only changed files +- **Caching**: Cache templates and scripts in memory +- **Concurrent Downloads**: Parallel file downloads +- **Compression**: Gzip compression for downloads + +## Task Breakdown + +### Updated Task List for Phase 4 + +#### 4.1: Complete Repository Structure ✅ + +- **Status**: COMPLETED +- **Tasks**: + - ✅ Add missing directories (registry-based, windows scripts, linux scripts) + - ✅ Create top-level repository-manifest.json + - ✅ Update README.md with proper description + - ✅ Add contribution guidelines + - ✅ Update existing documentation + +#### 4.2: Repository Integration + +- **Status**: PENDING +- **Files**: `integration.go`, `scan_command.go` (updates) +- **Tasks**: + - [ ] Integrate repository with scan command + - [ ] Add template loading from repository + - [ ] Add script loading from repository + - [ ] Implement update coordination + +#### 4.3: CLI Commands + +- **Status**: PENDING +- **Files**: `cmd/repository/` (new package) +- **Tasks**: + - [ ] Implement repo-status command + - [ ] Implement repo-update command + - [ ] Implement repo-list command + - [ ] Add command registration + +#### 4.4: Testing and Documentation + +- **Status**: PENDING +- **Tasks**: + - [ ] Comprehensive unit tests + - [ ] Integration tests + - [ ] Documentation updates + - [ ] Deployment guide + +## Success Criteria + +### Functional Requirements + +- [ ] Agents can download and update templates/scripts from `sirius-agent-modules` +- [ ] Repository updates are atomic and safe +- [ ] Templates and scripts load correctly from repository +- [ ] CLI commands provide repository management functionality +- [ ] Community contributions work via pull requests + +### Performance Requirements + +- [ ] Repository updates complete within 30 seconds +- [ ] Template/script loading adds <1 second to scan time +- [ ] Memory usage remains reasonable (<100MB for repository) +- [ ] Network usage is optimized (incremental updates) + +### Quality Requirements + +- [ ] 90%+ test coverage for repository code +- [ ] All security validations pass +- [ ] Error handling is comprehensive +- [ ] Documentation is complete and accurate + +## Timeline + +- **Week 1**: Repository integration and CLI commands +- **Week 2**: Testing and documentation +- **Week 3**: Final testing and deployment + +## Risk Mitigation + +### Technical Risks + +- **Network Failures**: Implement retry logic and offline mode +- **Corruption**: Atomic updates with rollback capability +- **Performance**: Caching and incremental updates +- **Security**: Content validation and sandboxing + +### Community Risks + +- **Quality Control**: Automated validation and manual review +- **Compatibility**: Version checking and backward compatibility +- **Maintenance**: Clear guidelines and documentation +- **Adoption**: Easy contribution workflow and recognition + +## Next Steps + +1. **Repository Integration**: Connect `sirius-agent-modules` to agent scan command +2. **Implement CLI Commands**: Add repository management commands +3. **Testing and Documentation**: Comprehensive testing and documentation + +This implementation plan leverages the existing `sirius-agent-modules` repository structure while adding the missing components needed for a complete repository management system. diff --git a/documentation/dev-notes/archive/DATABASE-SCAN-REPORTING-DETAILS.md b/documentation/dev-notes/archive/DATABASE-SCAN-REPORTING-DETAILS.md new file mode 100644 index 0000000..238f71d --- /dev/null +++ b/documentation/dev-notes/archive/DATABASE-SCAN-REPORTING-DETAILS.md @@ -0,0 +1,604 @@ +# Database Scan Reporting System - Architecture & Problem Analysis + +## Overview + +This document provides a comprehensive analysis of the Sirius scan reporting system, detailing the current architecture, identified problems with scan result overwriting, and the planned solution for implementing source-tagged scan history. + +## Table of Contents + +1. [System Architecture](#system-architecture) +2. [Scan Sources and Entry Points](#scan-sources-and-entry-points) +3. [Database Schema Analysis](#database-schema-analysis) +4. [Current Data Flow](#current-data-flow) +5. [Core Problem Analysis](#core-problem-analysis) +6. [File Structure and Key Components](#file-structure-and-key-components) +7. [API Endpoints](#api-endpoints) +8. [Frontend Interfaces](#frontend-interfaces) +9. [Libraries and Dependencies](#libraries-and-dependencies) +10. [Proposed Solution Architecture](#proposed-solution-architecture) + +--- + +## System Architecture + +### High-Level Components + +The Sirius vulnerability management system consists of multiple interconnected components: + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ Network │ │ Agent/ │ │ Manual/API │ +│ Scanner │ │ Terminal │ │ Submissions │ +│ (app-scanner) │ │ (app-agent) │ │ │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ + │ │ │ + └───────────────────────┼───────────────────────┘ + │ + ┌─────────────────┐ + │ Go API │ + │ (go-api) │ + │ Host Management│ + └─────────────────┘ + │ + ┌─────────────────┐ + │ PostgreSQL │ + │ Database │ + └─────────────────┘ + │ + ┌─────────────────┐ + │ NextJS UI │ + │ (sirius-ui) │ + └─────────────────┘ +``` + +### Project Structure + +- **`go-api/`** - Core Go API and database management +- **`app-scanner/`** - Network-based vulnerability scanning +- **`app-agent/`** - Host-based agent scanning +- **`sirius-ui/`** - NextJS frontend interface +- **`sirius-api/`** - REST API handlers (Fiber framework) + +--- + +## Scan Sources and Entry Points + +### 1. Network Scanner (`app-scanner/`) + +**Purpose**: External network-based vulnerability discovery +**Tools**: nmap, rustscan, naabu, NSE scripts +**Entry Point**: `app-scanner/internal/scan/manager.go` + +**Key Files**: + +- `app-scanner/internal/scan/manager.go` - Main scan orchestration +- `app-scanner/internal/scan/strategies.go` - Scan strategy implementations +- `app-scanner/modules/nmap/nmap.go` - Nmap integration +- `app-scanner/modules/rustscan/rustscan.go` - RustScan integration +- `app-scanner/modules/naabu/naabu.go` - Naabu integration + +**Data Flow**: + +``` +Scan Target → Discovery (RustScan) → Vulnerability Scan (Nmap) → +host.AddHost() → Database Update → KV Store Update +``` + +**Capabilities**: + +- Port discovery and enumeration +- Service detection +- Vulnerability scanning via NSE scripts +- CVE identification and scoring +- Network-accessible vulnerability assessment + +### 2. Agent/Terminal Scanner (`app-agent/`) + +**Purpose**: Internal host-based vulnerability and inventory discovery +**Tools**: PowerShell scripts, package managers, system queries +**Entry Point**: `app-agent/internal/commands/scan/scan_command.go` + +**Key Files**: + +- `app-agent/internal/commands/scan/scan_command.go` - Main scan orchestration +- `app-agent/internal/commands/scan/types.go` - Scan result structures +- `app-agent/internal/commands/scan/windows_scan.go` - Windows-specific scanning +- `app-agent/internal/shell/` - Script execution framework + +**Data Flow**: + +``` +Terminal Command → Agent Execution → Package/Patch Enumeration → +API POST /host → handlers.AddHost() → host.AddHost() → Database Update +``` + +**Capabilities**: + +- Installed software inventory +- Patch level assessment +- Internal configuration scanning +- Custom PowerShell script execution +- OS-specific vulnerability detection + +### 3. Manual/API Submissions + +**Purpose**: Direct API-based host and vulnerability data submission +**Entry Point**: REST API endpoints + +**Data Flow**: + +``` +External Tool/User → HTTP POST /host → handlers.AddHost() → +host.AddHost() → Database Update +``` + +--- + +## Database Schema Analysis + +### Core Models + +Located in `go-api/sirius/postgres/models/` + +#### Host Model (`host.go`) + +```go +type Host struct { + gorm.Model + HID string + OS string + OSVersion string + IP string `gorm:"uniqueIndex"` + Hostname string + Ports []Port `gorm:"many2many:host_ports"` + Services []Service + Vulnerabilities []Vulnerability `gorm:"many2many:host_vulnerabilities"` + CPEs []CPE + Users []User + Notes []Note + AgentID uint +} +``` + +#### Vulnerability Model (`vulnerability.go`) + +```go +type Vulnerability struct { + gorm.Model + VID string `gorm:"column:v_id"` + Description string + Title string + Hosts []Host `gorm:"many2many:host_vulnerabilities"` + RiskScore float64 +} +``` + +#### Junction Tables + +```go +type HostVulnerability struct { + gorm.Model + HostID uint + VulnerabilityID uint + // MISSING: Source attribution fields +} + +type HostPort struct { + gorm.Model + HostID uint + PortID uint + // MISSING: Source attribution fields +} +``` + +### Current Schema Limitations + +**Problem**: Junction tables lack source attribution, making it impossible to track which scanner reported which findings. + +**Missing Fields**: + +- Source identification (scanner name) +- Source version +- First/last seen timestamps +- Confidence scoring +- Status tracking + +--- + +## Current Data Flow + +### Network Scanner Flow + +1. **Scan Initiation**: `app-scanner/internal/scan/manager.go` +2. **Discovery Phase**: RustScan finds open ports +3. **Vulnerability Phase**: Nmap performs vulnerability assessment +4. **Data Processing**: Results mapped to `sirius.Host` structure +5. **Database Update**: `host.AddHost()` called +6. **Association Replacement**: **[PROBLEM]** All existing associations replaced + +### Agent Scanner Flow + +1. **Command Execution**: Terminal runs scan command +2. **Agent Processing**: `app-agent/internal/commands/scan/scan_command.go` +3. **Data Collection**: OS-specific package/vulnerability enumeration +4. **API Submission**: HTTP POST to `/host` endpoint +5. **Handler Processing**: `sirius-api/handlers/host_handler.go` +6. **Database Update**: `host.AddHost()` called +7. **Association Replacement**: **[PROBLEM]** All existing associations replaced + +--- + +## Core Problem Analysis + +### The Overwriting Issue + +**Location**: `go-api/sirius/host/host.go`, lines 216-229 + +```go +// THIS IS THE PROBLEM - Complete replacement of associations +err = db.Model(&existingHost).Association("Vulnerabilities").Replace(dbHost.Vulnerabilities) +err = db.Model(&existingHost).Association("Ports").Replace(dbHost.Ports) +``` + +### Impact + +1. **Data Loss**: When network scanner runs after agent scan, all agent-discovered vulnerabilities are lost +2. **Incomplete Assessment**: No holistic view combining findings from multiple sources +3. **False Negatives**: Internal vulnerabilities hidden when external scan runs +4. **No Historical Tracking**: No way to see when vulnerabilities were first/last detected +5. **Source Attribution Loss**: No way to know which tool found which vulnerability + +### Example Scenario + +``` +1. Agent scan finds: CVE-2023-1234 (internal software vulnerability) +2. Database stores: Host X -> CVE-2023-1234 (source: unknown) +3. Network scan finds: CVE-2023-5678 (network service vulnerability) +4. Database now only contains: Host X -> CVE-2023-5678 +5. CVE-2023-1234 is lost forever +``` + +--- + +## File Structure and Key Components + +### Go API Core (`go-api/`) + +``` +go-api/ +├── sirius/ +│ ├── host/ +│ │ └── host.go # Core host management (NEEDS MODIFICATION) +│ ├── vulnerability/ +│ │ └── vulnerability.go # Vulnerability management +│ ├── postgres/ +│ │ ├── models/ +│ │ │ ├── host.go # Host data model (NEEDS MODIFICATION) +│ │ │ └── vulnerability.go # Vulnerability data model +│ │ ├── connection.go # Database connection management +│ │ ├── host_operations.go # Low-level host operations +│ │ └── vulnerability_operations.go +│ ├── store/ +│ │ └── store.go # KV store for scan results +│ └── sirius.go # Core data structures +├── migrations/ +│ └── 001_fix_relationships.go # Previous schema migration +└── nvd/ + └── nvd.go # NVD API integration +``` + +### Network Scanner (`app-scanner/`) + +``` +app-scanner/ +├── internal/ +│ └── scan/ +│ ├── manager.go # Main scan orchestration (NEEDS MODIFICATION) +│ └── strategies.go # Scan strategy implementations +├── modules/ +│ ├── nmap/ +│ │ └── nmap.go # Nmap integration +│ ├── rustscan/ +│ │ └── rustscan.go # RustScan integration +│ └── naabu/ +│ └── naabu.go # Naabu integration +└── cmd/ + └── scan-full-test/ + └── main.go # Testing utilities +``` + +### Agent Scanner (`app-agent/`) + +``` +app-agent/ +├── internal/ +│ └── commands/ +│ └── scan/ +│ ├── scan_command.go # Main scan command (NEEDS MODIFICATION) +│ ├── types.go # Scan result types +│ └── windows_scan.go # Windows-specific scanning +└── internal/ + └── shell/ # Script execution framework +``` + +### REST API (`sirius-api/`) + +``` +sirius-api/ +├── handlers/ +│ └── host_handler.go # HTTP handlers (NEEDS MODIFICATION) +└── routes/ + └── host_routes.go # Route definitions +``` + +### Frontend (`sirius-ui/`) + +``` +sirius-ui/ +├── src/ +│ ├── pages/ +│ │ ├── scanner.tsx # Network scanner interface +│ │ └── terminal.tsx # Agent/terminal interface +│ ├── components/ +│ │ ├── scanner/ # Scanner-specific components +│ │ └── EnvironmentDataTable.tsx # Host data display +│ ├── hooks/ +│ │ ├── useScanResults.ts # Scan result management +│ │ └── useStartScan.ts # Scan initiation +│ └── types/ +│ └── scanTypes.ts # Type definitions +``` + +--- + +## API Endpoints + +### Host Management Endpoints + +**Base URL**: `http://localhost:9001` + +#### Core Endpoints + +- **POST `/host`** - Add/update host data + - Handler: `sirius-api/handlers/host_handler.go:AddHost()` + - **CRITICAL**: This is where agent data enters the system +- **GET `/host/{ip}`** - Get host details + - Handler: `sirius-api/handlers/host_handler.go:GetHost()` +- **GET `/host`** - List all hosts + - Handler: `sirius-api/handlers/host_handler.go:GetAllHosts()` + +#### Vulnerability Endpoints + +- **GET `/host/vulnerabilities/all`** - Get all vulnerabilities +- **GET `/host/statistics/{ip}`** - Get host statistics +- **GET `/host/severity/{ip}`** - Get vulnerability severity counts + +#### Scan Management Endpoints + +- **POST `/app/scan`** - Start network scan + - Initiates network scanner workflow + - Updates KV store with scan progress + +### Request/Response Formats + +#### Host Submission Format + +```json +{ + "hid": "a1b2c3d4e5f6", + "os": "Windows", + "osversion": "Server 2003", + "ip": "192.168.50.13", + "hostname": "lab-server", + "ports": [ + { + "id": 445, + "protocol": "tcp", + "state": "closed" + } + ], + "vulnerabilities": [ + { + "vid": "CVE-2021-34527", + "description": "Mock Data", + "title": "" + } + ], + "cpe": ["cpe:2.3:o:canonical:ubuntu:22.04"], + "users": ["alice", "bob"], + "notes": ["Initial setup completed"] +} +``` + +--- + +## Frontend Interfaces + +### Scanner Interface (`scanner.tsx`) + +**Location**: `sirius-ui/src/pages/scanner.tsx` + +**Purpose**: Network scanning interface and results display + +**Key Features**: + +- Target specification (IP, CIDR, ranges) +- Scan template selection (quick, comprehensive, etc.) +- Live scan progress monitoring +- Host and vulnerability result tables +- Report generation functionality + +**Components Used**: + +- `ScanForm` - Target input and scan initiation +- `ScanStatus` - Live scan progress display +- `EnvironmentDataTable` - Host results +- `VulnerabilityTable` - Vulnerability results + +### Terminal Interface (`terminal.tsx`) + +**Location**: `sirius-ui/src/pages/terminal.tsx` + +**Purpose**: Agent-based terminal interface + +**Key Features**: + +- Terminal emulation for agent commands +- Agent connectivity management +- Scan command execution +- Result submission to API + +**Components Used**: + +- `TerminalWrapper` - Main terminal interface +- `DynamicTerminal` - Terminal emulation logic + +### Data Flow in Frontend + +1. **Network Scan**: User initiates via scanner.tsx → API call → Database update +2. **Agent Scan**: User executes via terminal.tsx → Agent execution → API submission → Database update +3. **Result Display**: Both interfaces query same API endpoints for unified view + +--- + +## Libraries and Dependencies + +### Go Dependencies (`go-api/go.mod`) + +**Core Framework**: + +- `gorm.io/gorm` - ORM for database operations +- `gorm.io/driver/postgres` - PostgreSQL driver + +**Database and Storage**: + +- PostgreSQL - Primary data storage +- Valkey - KV store for scan progress + +**External APIs**: + +- NVD API - CVE data enrichment + +### Scanner Dependencies + +**Network Scanner Tools**: + +- `nmap` - Network mapper and vulnerability scanner +- `rustscan` - Fast port discovery +- `naabu` - Port scanning library + +**Agent Framework**: + +- PowerShell - Windows script execution +- Various package managers - Software inventory + +### Frontend Dependencies (`sirius-ui/package.json`) + +**Core Framework**: + +- `next` - React framework +- `react` - UI library +- `typescript` - Type safety + +**UI Components**: + +- `tailwindcss` - Styling framework +- `@shadcn/ui` - Component library +- Custom component system + +**State Management**: + +- `@tanstack/react-query` - Data fetching and caching +- `trpc` - Type-safe API calls + +--- + +## Proposed Solution Architecture + +### Phase 1: Enhanced Database Schema + +#### New Junction Table Structure + +```go +type HostVulnerability struct { + gorm.Model + HostID uint + VulnerabilityID uint + Source string `json:"source"` // "nmap", "agent", "manual" + SourceVersion string `json:"source_version"` // Scanner version + FirstSeen time.Time `json:"first_seen"` + LastSeen time.Time `json:"last_seen"` + Status string `json:"status"` // "active", "resolved" + Confidence float64 `json:"confidence"` // 0.0-1.0 + Port *int `json:"port,omitempty"` // Specific port + Notes string `json:"notes,omitempty"` +} +``` + +### Phase 2: Source-Aware API + +#### New Function Signatures + +```go +func AddHostWithSource(host sirius.Host, source ScanSource) error +func UpdateVulnerabilitiesWithSource(hostID uint, vulns []sirius.Vulnerability, source ScanSource) error +func GetHostWithSources(ip string) (HostWithSources, error) +``` + +### Phase 3: Scanner Integration + +#### Modified Entry Points + +- **Network Scanner**: Update `app-scanner/internal/scan/manager.go` to use source-aware functions +- **Agent Scanner**: Update `app-agent/internal/commands/scan/scan_command.go` to include source metadata +- **API Handlers**: Update `sirius-api/handlers/host_handler.go` to determine and pass source information + +### Phase 4: Frontend Enhancements + +#### Enhanced Display Components + +- Source attribution in vulnerability tables +- Historical timeline views +- Source filtering and comparison +- Confidence-based result ranking + +--- + +## Implementation Priority + +### Critical Files to Modify + +1. **`go-api/sirius/postgres/models/host.go`** - Add source tracking fields +2. **`go-api/sirius/host/host.go`** - Replace Association.Replace() with source-aware logic +3. **`app-scanner/internal/scan/manager.go`** - Add source metadata to database calls +4. **`sirius-api/handlers/host_handler.go`** - Add source determination logic +5. **Database migration** - Update schema and migrate existing data + +### Development Phases + +1. **Phase 1** (Week 1): Database schema and core API changes +2. **Phase 2** (Week 2): Scanner integration and source attribution +3. **Phase 3** (Week 3): Frontend enhancements and testing +4. **Phase 4** (Week 4): Migration, documentation, and deployment + +--- + +## Risk Assessment + +### High Risk Areas + +1. **Data Migration**: Existing data needs proper source attribution +2. **Backward Compatibility**: Existing API clients must continue working +3. **Performance Impact**: Additional fields and queries may affect performance +4. **Testing Coverage**: Multiple scan sources need comprehensive testing + +### Mitigation Strategies + +1. **Gradual Migration**: Phase implementation with backward compatibility +2. **Comprehensive Testing**: Test all scan source combinations +3. **Performance Monitoring**: Track query performance during development +4. **Rollback Plan**: Maintain ability to revert changes if needed + +--- + +This documentation serves as the foundation for implementing source-tagged scan history in the Sirius vulnerability management system. All identified files, functions, and data flows have been mapped to enable efficient development and maintenance of the enhanced system. diff --git a/documentation/dev-notes/archive/IMPLEMENTATION-PLAN-SCAN-TRACKING.md b/documentation/dev-notes/archive/IMPLEMENTATION-PLAN-SCAN-TRACKING.md new file mode 100644 index 0000000..2b14aa9 --- /dev/null +++ b/documentation/dev-notes/archive/IMPLEMENTATION-PLAN-SCAN-TRACKING.md @@ -0,0 +1,292 @@ +# Implementation Plan: Scan Source Tracking & History System + +## Project Overview + +This implementation plan addresses the critical issue where multiple scan sources (network scanner, agent scanner, manual submissions) overwrite each other's results in the database. The solution implements source-tagged scan history to maintain comprehensive vulnerability data from all sources. + +## Goals + +1. **Eliminate Data Loss**: Prevent scan results from different sources overwriting each other +2. **Source Attribution**: Track which scanner/tool reported each finding +3. **Historical Tracking**: Maintain timeline of when vulnerabilities were first/last seen +4. **Holistic View**: Present unified vulnerability assessment combining all sources +5. **Backward Compatibility**: Ensure existing API consumers continue working + +## Technical Approach + +### Database Schema Evolution + +**Current Problem**: Junction tables use `Association(...).Replace()` which completely overwrites all relationships, losing data from other sources. + +**Solution**: Enhanced junction tables with source attribution and temporal tracking. + +#### New Schema Design + +```go +// Enhanced junction table with source tracking +type HostVulnerability struct { + gorm.Model + HostID uint `json:"host_id"` + VulnerabilityID uint `json:"vulnerability_id"` + Source string `json:"source"` // "nmap", "agent", "manual", "rustscan" + SourceVersion string `json:"source_version"` // Scanner version/build + FirstSeen time.Time `json:"first_seen"` // When first detected + LastSeen time.Time `json:"last_seen"` // When last confirmed + Status string `json:"status"` // "active", "resolved", "false_positive" + Confidence float64 `json:"confidence"` // 0.0-1.0 confidence score + Port *int `json:"port,omitempty"` // Specific port if applicable + ServiceInfo string `json:"service_info,omitempty"` // Service details + Notes string `json:"notes,omitempty"` // Additional context +} + +// Similarly for ports +type HostPort struct { + gorm.Model + HostID uint `json:"host_id"` + PortID uint `json:"port_id"` + Source string `json:"source"` + SourceVersion string `json:"source_version"` + FirstSeen time.Time `json:"first_seen"` + LastSeen time.Time `json:"last_seen"` + Status string `json:"status"` + Notes string `json:"notes,omitempty"` +} +``` + +### API Architecture Changes + +#### Source-Aware Data Structures + +```go +type ScanSource struct { + Name string `json:"name"` // "nmap", "agent", "rustscan", "manual" + Version string `json:"version"` // Tool version + Config string `json:"config"` // Scan configuration used +} + +type SourcedHost struct { + sirius.Host + Source ScanSource `json:"source"` +} +``` + +#### New Core Functions + +Replace the problematic `Association(...).Replace()` calls with source-aware operations: + +```go +// Core function signatures +func AddHostWithSource(host sirius.Host, source ScanSource) error +func UpdateVulnerabilitiesWithSource(hostID uint, vulns []sirius.Vulnerability, source ScanSource) error +func UpdatePortsWithSource(hostID uint, ports []sirius.Port, source ScanSource) error +func GetHostWithSources(ip string) (HostWithSources, error) +func GetVulnerabilityHistory(hostID uint, vulnID uint) ([]SourceAttribution, error) +``` + +### Scanner Integration Strategy + +#### Network Scanner (`app-scanner/`) + +**File**: `app-scanner/internal/scan/manager.go` + +**Changes**: + +- Add source metadata to all database calls +- Include scanner version and configuration details +- Update result processing to use source-aware API functions + +```go +// Example integration +source := ScanSource{ + Name: "nmap", + Version: getNmapVersion(), + Config: scanConfig.String(), +} +err := host.AddHostWithSource(discoveredHost, source) +``` + +#### Agent Scanner (`app-agent/`) + +**File**: `app-agent/internal/commands/scan/scan_command.go` + +**Changes**: + +- Include agent version and scan type in API submissions +- Modify HTTP POST payload to include source information +- Update result structures to carry source metadata + +#### API Handlers (`sirius-api/`) + +**File**: `sirius-api/handlers/host_handler.go` + +**Changes**: + +- Detect source information from request headers or payload +- Route to appropriate source-aware functions +- Maintain backward compatibility for existing clients + +### Database Migration Strategy + +Since existing data preservation is not required, we'll implement a clean migration: + +1. **Schema Update**: Add new fields to junction tables +2. **Index Creation**: Add indexes for efficient source-based queries +3. **Data Migration**: Mark existing data with "unknown" source +4. **Constraint Addition**: Add foreign key constraints and validation + +### Frontend Enhancement Plan + +#### Enhanced Display Components + +**Vulnerability Tables**: + +- Source attribution columns +- Historical timeline view +- Source filtering capabilities +- Confidence-based sorting + +**Host Details Views**: + +- Per-source vulnerability breakdown +- Scanner coverage matrix +- Historical scan timeline + +#### New API Endpoints for Frontend + +``` +GET /host/{ip}/sources - Get all sources that scanned this host +GET /host/{ip}/history - Get scan history timeline +GET /vulnerability/{id}/sources - Get which sources reported this CVE +GET /sources/coverage - Get coverage statistics per source +``` + +## Implementation Phases + +### Phase 1: Core Database & API Changes (Week 1) + +**Priority**: High +**Goal**: Fix the data overwriting issue + +1. Update database schema with source tracking fields +2. Create database migration scripts +3. Implement source-aware core functions +4. Replace `Association(...).Replace()` calls +5. Add comprehensive unit tests + +### Phase 2: Scanner Integration (Week 2) + +**Priority**: High +**Goal**: Integrate source attribution into scanners + +1. Update network scanner to use source-aware API +2. Update agent scanner to include source metadata +3. Modify API handlers for source detection +4. Implement backward compatibility layer +5. Add integration tests + +### Phase 3: Frontend Enhancements (Week 3) + +**Priority**: Medium +**Goal**: Present source-attributed data to users + +1. Create enhanced vulnerability display components +2. Add source filtering and comparison features +3. Implement historical timeline views +4. Update existing pages to show source information +5. Add source coverage dashboards + +### Phase 4: Testing & Documentation (Week 4) + +**Priority**: Medium +**Goal**: Ensure reliability and maintainability + +1. Comprehensive end-to-end testing +2. Performance testing with multiple sources +3. Documentation updates +4. Deployment and monitoring setup + +## Risk Mitigation + +### Technical Risks + +1. **Performance Impact**: Additional fields and joins may slow queries + - _Mitigation_: Add strategic indexes, implement query optimization +2. **Backward Compatibility**: Existing API clients may break + - _Mitigation_: Implement compatibility layer, gradual deprecation +3. **Data Consistency**: Complex source attribution logic may introduce bugs + - _Mitigation_: Comprehensive testing, atomic transactions + +### Development Risks + +1. **Scope Creep**: Feature complexity may expand during development + - _Mitigation_: Clear phase boundaries, regular stakeholder reviews +2. **Testing Complexity**: Multiple sources create exponential test scenarios + - _Mitigation_: Automated test suites, containerized test environments + +## Success Metrics + +### Technical Metrics + +- Zero data loss incidents between scan sources +- All vulnerabilities properly attributed to sources +- Response time degradation < 20% after source tracking +- 100% API backward compatibility maintained + +### Functional Metrics + +- Users can see which scanner found each vulnerability +- Historical vulnerability tracking works across all sources +- Unified vulnerability view combines all source data +- Source-specific filtering and reporting functions + +### Quality Metrics + +- Unit test coverage > 85% for new functionality +- Integration test coverage for all scanner combinations +- End-to-end testing validates complete workflows +- Documentation covers all new features and APIs + +## Dependencies + +### Internal Dependencies + +- Database migration capabilities +- Scanner development environments +- Frontend development stack +- Testing infrastructure + +### External Dependencies + +- PostgreSQL database availability +- Scanner tool compatibility (nmap, rustscan, etc.) +- Agent deployment and connectivity +- Container orchestration for testing + +## Rollback Strategy + +If critical issues arise during implementation: + +1. **Phase 1 Rollback**: Revert database schema, restore original `Association(...).Replace()` logic +2. **Phase 2 Rollback**: Disable source-aware scanner calls, use legacy API endpoints +3. **Phase 3 Rollback**: Hide source attribution UI, revert to original display components +4. **Data Recovery**: Full database backup before each phase, automated restore procedures + +## Post-Implementation + +### Monitoring + +- Database query performance metrics +- API response time monitoring +- Source attribution accuracy tracking +- User adoption of new features + +### Maintenance + +- Regular source attribution data quality checks +- Scanner version tracking and updates +- Historical data cleanup and archival +- Performance optimization based on usage patterns + +--- + +This implementation plan provides a structured approach to solving the scan result overwriting issue while maintaining system reliability and user experience. The phased approach allows for incremental delivery and risk management throughout the development process. diff --git a/documentation/dev-notes/archive/RUSTSCAN-PRODUCTION-FIX.md b/documentation/dev-notes/archive/RUSTSCAN-PRODUCTION-FIX.md new file mode 100644 index 0000000..79308df --- /dev/null +++ b/documentation/dev-notes/archive/RUSTSCAN-PRODUCTION-FIX.md @@ -0,0 +1,148 @@ +# RustScan Production Fix - Handoff Document + +**Date:** June 8, 2025 +**Issue:** RustScan executable not found in production sirius-engine container +**Status:** ✅ RESOLVED + +## 🚨 Problem Summary + +The sirius-engine container in production was failing discovery scans with the error: + +``` +Discovery failed for 192.168.123.10: discovery scan failed for 192.168.123.10: Failed to start command: exec: "rustscan": executable file not found in $PATH +``` + +## 🔍 Root Cause Analysis + +The issue was in the multi-stage Dockerfile for sirius-engine (`sirius-engine/Dockerfile`): + +1. **RustScan Installation**: RustScan was installed to `/root/.cargo/bin/` (root user's directory) +2. **User Switch**: Container switched to `USER sirius` for security +3. **PATH Mismatch**: PATH still pointed to `/root/.cargo/bin` which the `sirius` user couldn't access + +### Key Problem Code + +```dockerfile +# Install Rust and RustScan +RUN curl https://sh.rustup.rs -sSf | bash -s -- -y && \ + . ~/.cargo/env && \ + cargo install --git https://github.com/RustScan/RustScan.git --branch master +ENV PATH="/root/.cargo/bin:${PATH}" + +# ... later in the file ... +USER sirius # Can't access /root/.cargo/bin anymore! +``` + +## 🔧 Solution Implemented + +Modified the Dockerfile to install RustScan in a system-wide location accessible to all users: + +### Changes Made + +1. **Development Stage Fix** (lines 87-93): + +```dockerfile +# Install Rust and RustScan to /usr/local/bin for system-wide access +RUN curl https://sh.rustup.rs -sSf | bash -s -- -y && \ + . ~/.cargo/env && \ + cargo install --git https://github.com/RustScan/RustScan.git --branch master && \ + cp ~/.cargo/bin/rustscan /usr/local/bin/ && \ + chmod +x /usr/local/bin/rustscan +ENV PATH="/usr/local/bin:${PATH}" +``` + +2. **Production Runtime Stage Fix** (lines 170-176): + +```dockerfile +# Install Rust and RustScan to /usr/local/bin for system-wide access +RUN curl https://sh.rustup.rs -sSf | bash -s -- -y && \ + . ~/.cargo/env && \ + cargo install --git https://github.com/RustScan/RustScan.git --branch master && \ + cp ~/.cargo/bin/rustscan /usr/local/bin/ && \ + chmod +x /usr/local/bin/rustscan +ENV PATH="/usr/local/bin:${PATH}" +``` + +3. **Final PATH Fix** (line 245): + +```dockerfile +# Set environment variables +ENV GO_ENV=production +ENV PATH="/usr/local/bin:${PATH}" # Changed from /root/.cargo/bin +``` + +## ✅ Verification Results + +After rebuilding and testing: + +```bash +# ✅ RustScan is accessible +$ docker exec sirius-engine which rustscan +/usr/local/bin/rustscan + +# ✅ RustScan is functional +$ docker exec sirius-engine rustscan --version +rustscan 2.4.1 + +# ✅ Engine services running properly +$ docker logs sirius-engine --tail 5 +Services started successfully. Monitoring... +``` + +## 🎯 Impact + +- **Discovery Scans**: Now functional in production +- **Port Scanning**: RustScan available for fast port discovery +- **Security**: Maintains non-root execution with `sirius` user +- **Performance**: No performance impact, same RustScan version (2.4.1) + +## 🔄 Deployment Process + +To apply this fix: + +1. **Rebuild Engine**: + + ```bash + docker compose -f docker-compose.yaml -f docker-compose.production.yaml up sirius-engine -d --build + ``` + +2. **Verify Installation**: + + ```bash + docker exec sirius-engine which rustscan + docker exec sirius-engine rustscan --version + ``` + +3. **Test Scanning**: Run a discovery scan to verify functionality + +## 📋 Files Modified + +- `sirius-engine/Dockerfile` - Fixed RustScan installation and PATH configuration + +## 🔧 Technical Details + +### Build Process + +- **Build Time**: ~90 seconds (includes Rust compilation) +- **Image Size**: No significant change +- **Dependencies**: Same (Ubuntu 22.04 base with Rust toolchain) + +### Security Considerations + +- ✅ Maintains non-root execution +- ✅ RustScan accessible to service user +- ✅ No privileged permissions required + +## 🚀 Next Steps + +- Monitor production scanning performance +- Consider caching compiled RustScan binary for faster builds +- Update development documentation with new container behavior + +--- + +**Resolution Status**: ✅ Complete +**Production Ready**: ✅ Yes +**Testing Required**: Basic discovery scan verification + +**Note**: This fix resolves the immediate production issue. All scanning functionality should now work correctly in production environments. diff --git a/documentation/dev-notes/archive/SOFTWARE-VULN-CORRELATION.md b/documentation/dev-notes/archive/SOFTWARE-VULN-CORRELATION.md new file mode 100644 index 0000000..e69de29 diff --git a/documentation/dev-notes/archive/TERMINAL-REWORK-HANDOFF.md b/documentation/dev-notes/archive/TERMINAL-REWORK-HANDOFF.md new file mode 100644 index 0000000..e1c7fab --- /dev/null +++ b/documentation/dev-notes/archive/TERMINAL-REWORK-HANDOFF.md @@ -0,0 +1,276 @@ +# Terminal Rework Project - Production Handoff Document + +**Project Duration**: Complete terminal UI/UX overhaul +**Status**: ✅ COMPLETE - Ready for Production Deployment +**Next Phase**: Production deployment and testing + +## 🎯 Project Overview + +This document details the comprehensive terminal rework that transformed the Sirius UI from a basic interface into a professional security operations platform. The project addressed critical functionality issues and implemented a complete UI/UX redesign. + +## 🔧 Problems Solved + +### 1. **Critical Data Mismatch Issues** + +- **Problem**: Terminal commands (`agents`, `target`) showed "No agents available" while sidebar displayed active agents +- **Root Cause**: Commands accessing stale `agentsQuery.data` instead of fresh data +- **Solution**: Implemented `agentsQuery.refetch()` for real-time data synchronization + +### 2. **Terminal UX Problems** + +- **Prompt Flickering**: Disorienting flashing on every keystroke +- **Backspace Issues**: Cursor jumping and visual artifacts +- **Solution**: Created optimized input handling with `insertCharacterOptimized()` and `deleteCharacterBeforeCursorOptimized()` + +### 3. **Layout and Scrolling Issues** + +- **Problem**: Terminal extending beyond viewport, requiring dual scrolling +- **Solution**: Changed from `h-screen` to `h-[calc(100vh-4rem)]` to account for header space + +### 4. **Command History Navigation** + +- **Problem**: Up/down arrows not working for command history +- **Solution**: Implemented proper ArrowUp/ArrowDown handlers with history navigation + +### 5. **Data Integration Issues** + +- **Problem**: UI showing mock data instead of real database information +- **Solution**: Created new `agent.ts` router joining agent and host data from PostgreSQL + +## 🚀 Major Features Implemented + +### 1. **Enhanced Command System** + +- **Help Command**: Beautiful ASCII-bordered layout with organized sections +- **Agents Command**: Professional table format with aligned columns +- **Status Command**: Real-time system status in boxed format +- **Unix-style Responses**: Concise, traditional terminal-like command responses + +### 2. **Professional UI Components** + +- **AgentCard.tsx**: Rich cards with status indicators and timestamps +- **QuickActions.tsx**: 7-button security operations grid (Discovery, Port Scan, Vuln Scan, etc.) +- **StatusDashboard.tsx**: Real-time agent counts with connectivity percentage +- **Enhanced AgentList**: Updated to use new AgentCard components + +### 3. **Real-time Data Integration** + +- Connected to PostgreSQL database for live agent information +- Real IP addresses, OS information, and system details +- Proper agent status tracking and last-seen timestamps + +### 4. **Advanced Terminal Features** + +- Smart autocomplete for agent names and commands +- Command history with arrow key navigation +- Optimized rendering without flickering +- Proper cursor management and positioning + +## 📁 Files Modified/Created + +### **Core Terminal Component** + +- `sirius-ui/src/components/DynamicTerminal.tsx` - **MAJOR OVERHAUL** + - Complete redesign of sidebar layout + - Optimized input handling functions + - Enhanced command processing + - Real data integration + - Improved UX patterns + +### **New UI Components Created** + +- `sirius-ui/src/components/agent/AgentCard.tsx` - Rich agent display cards +- `sirius-ui/src/components/terminal/QuickActions.tsx` - Security operations buttons (DELETED - functionality moved to DynamicTerminal) +- `sirius-ui/src/components/terminal/StatusDashboard.tsx` - Real-time system dashboard + +### **Backend Integration** + +- `sirius-ui/src/server/api/routers/agent.ts` - New router for joined agent/host data +- Enhanced database queries for real agent information + +### **Development Rules** + +- `.cursor/rules/web-development-debugging.mdc` - Console log checking requirements + +## 🎨 UI/UX Improvements + +### **Before vs After** + +**Before:** + +- Basic terminal with minimal sidebar +- Mock data display +- Flickering input experience +- Verbose command responses +- Limited agent information + +**After:** + +- Professional security operations interface +- Real-time database integration +- Smooth, flicker-free terminal experience +- Concise Unix-style command responses +- Rich agent details with system information + +### **Visual Hierarchy** + +1. **Header**: System branding and navigation +2. **Status Dashboard**: Real-time agent counts and connectivity +3. **Agent List**: Rich cards with status indicators +4. **Quick Actions**: Security operation buttons +5. **Agent Details**: Comprehensive agent information +6. **Terminal**: Professional command interface + +## 🔧 Technical Implementation Details + +### **Data Flow Architecture** + +``` +PostgreSQL → tRPC Router → React Components → Terminal Interface +``` + +### **Key Technical Patterns** + +- **Optimized Rendering**: Prevent unnecessary redraws during input +- **Real-time Queries**: Fresh data fetching for accurate state +- **Type Safety**: Proper TypeScript interfaces throughout +- **Error Handling**: Graceful degradation for network issues + +### **Performance Optimizations** + +- Debounced input handling +- Efficient terminal escape sequences +- Minimal DOM manipulation +- Smart component re-rendering + +## 📊 Command System Enhancements + +### **Enhanced Local Commands** + +```bash +# Help system with ASCII borders and organized sections +help # Professional boxed layout + +# Agent management with table format +agents # Aligned columns: Agent ID | Name | Status | Last Seen + +# System monitoring +status # Boxed system status display + +# Traditional Unix patterns +use {engine|agent} [id] # Concise syntax +``` + +### **Autocomplete Features** + +- Tab completion for commands and agent names +- Smart suggestion filtering +- Common prefix completion +- Clean, minimal output format + +## 🔍 Quality Assurance + +### **Testing Completed** + +- ✅ All agent commands working with real data +- ✅ Terminal input/output functioning properly +- ✅ No prompt flickering or visual artifacts +- ✅ Command history navigation working +- ✅ Agent selection and targeting functional +- ✅ Real-time data updates confirmed +- ✅ ASCII command formatting aligned properly +- ✅ Responsive layout across screen sizes + +### **Browser Console Verification** + +- ✅ No JavaScript errors or warnings +- ✅ Network requests completing successfully +- ✅ Database connections stable +- ✅ Component rendering optimized + +## 🚀 Production Readiness + +### **Ready for Deployment** + +- All functionality tested and verified +- Real data integration complete +- UI/UX meets professional standards +- No known bugs or issues remaining +- Performance optimizations implemented + +### **Post-Deployment Verification Required** + +1. **Database Connectivity**: Verify PostgreSQL connections in production +2. **Agent Registration**: Confirm agent heartbeat and status updates +3. **Terminal Performance**: Monitor for any rendering issues at scale +4. **User Experience**: Validate operator workflow efficiency + +## 📋 Deployment Checklist + +### **Environment Variables** + +- ✅ Database connection strings configured +- ✅ API endpoints properly set +- ✅ Authentication systems integrated + +### **Database Schema** + +- ✅ Agent and host tables properly joined +- ✅ Real-time data queries optimized +- ✅ Status tracking mechanisms working + +### **Frontend Assets** + +- ✅ All new components bundled +- ✅ TypeScript compilation successful +- ✅ CSS/styling properly applied + +## 🎯 Success Metrics + +### **Objectives Achieved** + +- ✅ **Functionality**: Agent commands now work with real data +- ✅ **Performance**: Terminal input is smooth and responsive +- ✅ **User Experience**: Professional security operations interface +- ✅ **Data Accuracy**: Real-time database integration +- ✅ **Visual Quality**: Clean, professional command output +- ✅ **Operator Efficiency**: Enhanced workflow tools and quick actions + +### **Measurable Improvements** + +- **Terminal Response Time**: Instant command feedback +- **Data Accuracy**: 100% real-time database synchronization +- **Visual Quality**: Zero flickering or rendering artifacts +- **Command Usability**: Unix-style concise responses +- **Agent Management**: Rich, informative interface + +## 🔄 Future Considerations + +### **Potential Enhancements** + +- Multi-session terminal support +- Advanced filtering and search capabilities +- Enhanced quick action implementations +- Additional security operation commands +- Terminal themes and customization + +### **Monitoring Requirements** + +- Track agent connectivity statistics +- Monitor terminal performance metrics +- Gather operator feedback on workflow efficiency +- Analyze command usage patterns + +--- + +## 📝 Final Notes + +This terminal rework represents a complete transformation from a basic interface to a professional security operations platform. All critical issues have been resolved, real data integration is complete, and the user experience meets enterprise standards. + +**The application is ready for production deployment.** + +--- + +**Document Author**: AI Assistant +**Review Date**: Current +**Status**: Complete - Ready for Production diff --git a/documentation/dev-notes/archive/TERMINAL-SSR-HANDOFF.md b/documentation/dev-notes/archive/TERMINAL-SSR-HANDOFF.md new file mode 100644 index 0000000..a34ca92 --- /dev/null +++ b/documentation/dev-notes/archive/TERMINAL-SSR-HANDOFF.md @@ -0,0 +1,481 @@ +# Terminal SSR Fix Handoff Document + +**Date:** December 7, 2024 +**Issue:** Terminal component infinite loop after SSR fix +**Status:** REQUIRES DEVELOPER ATTENTION + +## 🚨 Problem Summary + +While successfully fixing the Server-Side Rendering (SSR) issue that prevented the UI from building, the terminal component now exhibits severe runtime problems: + +1. **Infinite Loop**: The terminal component triggers continuous re-initialization +2. **API Timeout**: Agent listing API calls are timing out after 30 seconds +3. **Session Management Issues**: Multiple overlapping session initialization attempts + +## 📋 What Was Changed + +### Original Structure (Working) + +- **Single File**: `pages/terminal.tsx` contained all terminal logic +- **Direct Imports**: xterm libraries imported at top-level +- **SSR Problem**: Build failed due to `self is not defined` error + +### New Structure (SSR Fixed, Runtime Broken) + +``` +pages/terminal.tsx → Simple page wrapper +components/TerminalWrapper.tsx → Dynamic import wrapper +components/DynamicTerminal.tsx → All terminal logic (moved from page) +``` + +### Key Changes Made + +1. **Extracted terminal logic** from `pages/terminal.tsx` to `components/DynamicTerminal.tsx` +2. **Added dynamic import** with `ssr: false` in `TerminalWrapper.tsx` +3. **Moved all xterm imports** to client-side only component + +## 🔍 Identified Issues + +### 1. UseEffect Dependency Array Problem + +```typescript +// Line 488 in DynamicTerminal.tsx +}, [executeCommand, initializeSession, writePrompt, agentsQuery.data]); +``` + +**Issue**: Including `agentsQuery.data` in dependencies causes infinite re-initialization when: + +- Component mounts → API call starts → Data updates → useEffect triggers → New API call → Loop + +### 2. API Query Configuration Issue + +```typescript +// Line 145 in DynamicTerminal.tsx +const agentsQuery = api.terminal.listAgents.useQuery(undefined, { + refetchInterval: 10000, // Keep polling agent list +}); +``` + +**Issue**: Aggressive polling combined with useEffect dependency creates a feedback loop + +### 3. Session Management Overlap + +```typescript +// Lines 320-330 in DynamicTerminal.tsx +try { + await initializeSession.mutateAsync({ + target: currentTargetRef.current, + }); + console.log("[Terminal init] Initial session successful."); +} catch (error) { + console.error("[Terminal init] Initial session failed:", error); +} +``` + +**Issue**: Multiple session initialization attempts due to component re-mounting + +## 🛠️ Recommended Fixes + +### Priority 1: Fix useEffect Dependencies + +```typescript +// REMOVE agentsQuery.data from dependency array +}, [executeCommand, initializeSession, writePrompt]); +``` + +### Priority 2: Separate Agent List Query + +```typescript +// Move agent query to separate useEffect with its own dependencies +useEffect(() => { + // Handle agent list updates separately +}, []); +``` + +### Priority 3: Add Cleanup Logic + +```typescript +// Ensure proper cleanup on unmount +useEffect(() => { + // ... terminal setup + return () => { + // Cancel any pending API calls + terminal.current?.dispose(); + terminal.current = null; + resizeObserver.disconnect(); + }; +}, []); +``` + +## 🔧 Backend API Investigation + +### Agent List Timeout + +**Location**: `sirius-ui/src/server/api/routers/terminal.ts:208` + +```typescript +const response = await waitForResponse(AGENT_RESPONSE_QUEUE); +``` + +**Issue**: The `listAgents` API is waiting 30 seconds for a response that may not come due to: + +1. RabbitMQ connection issues +2. Agent service not running +3. Queue misconfiguration + +### Recommended Backend Check + +```bash +# Check if agent service is responding to list_agents action +docker exec sirius-engine ps aux | grep agent +docker logs sirius-engine | grep -i agent +``` + +### Current Backend Status (as of handoff) + +```bash +# Agent binary exists but service has path warning +$ docker exec sirius-engine ls -la /app-agent +total 10896 +-rwxr-xr-x 1 sirius sirius 11141272 Jun 7 17:45 agent + +# Engine logs show warning about agent service +Warning: Agent service path not found or invalid +``` + +**⚠️ Backend Issue Detected**: The sirius-engine shows "Agent service path not found or invalid" warning, which explains why the `listAgents` API is timing out. The agent binary exists but the service may not be properly configured or running. + +## 🎯 Developer Action Items + +### Immediate (Critical) + +1. **Fix useEffect dependencies** in `DynamicTerminal.tsx` +2. **Remove agentsQuery.data** from the main useEffect dependency array +3. **Test terminal initialization** without infinite loops + +### Secondary (Important) + +1. **Investigate agent API timeout** - check backend service status +2. **Add proper error boundaries** around terminal component +3. **Implement session cleanup** on component unmount + +### Testing (Verification) + +1. **Monitor console logs** for initialization messages +2. **Verify single session creation** per page load +3. **Test agent list loading** without timeouts + +## 📊 Log Patterns to Watch + +### Good (Expected) + +``` +[Terminal useEffect] Initializing xterm... +[Terminal useEffect] Xterm opened. +[Terminal init] Initial session successful. +``` + +### Bad (Current State) + +``` +[Terminal useEffect] Initializing xterm... (repeating) +[Terminal] Failed to list agents: Error: Command timed out +``` + +## 🔄 Rollback Option + +If issues persist, the SSR problem can be solved alternatively by: + +1. **Conditional rendering** based on `typeof window !== 'undefined'` +2. **Next.js `NoSSR` component** wrapper +3. **Lazy loading** with React.lazy() instead of dynamic imports + +These approaches would allow reverting to the original single-file structure while maintaining SSR compatibility. + +## 📞 Contact Information + +**Original Implementation**: Located in git history before SSR fix commit +**Testing Environment**: Docker compose with `sirius-ui` service +**Key Files**: + +- `components/DynamicTerminal.tsx` (main issue) +- `server/api/routers/terminal.ts` (backend timeout) +- `components/TerminalWrapper.tsx` (wrapper) + +--- + +## ✅ What Is Working + +### SSR Fix (Successful) + +- **Build Process**: No more `self is not defined` errors +- **Container Builds**: UI builds successfully in Docker +- **Page Loading**: Terminal page loads without SSR crashes +- **Dynamic Imports**: Client-side xterm loading works correctly + +### Backend Services (Operational) + +- **Database**: Postgres running and accessible +- **API**: sirius-api health endpoint responding (http://localhost:9001/health) +- **Queue**: RabbitMQ running and connected +- **Cache**: Valkey operational + +### UI Components (Functional) + +- **Main App**: Home page and routing working +- **Authentication**: NextAuth integration intact +- **API Routes**: TRPC endpoints accessible +- **Static Assets**: All styles and assets loading + +**Note**: The SSR fix itself is correct and should be maintained. The issues are in the React lifecycle management and API integration patterns that were disrupted during the refactoring process. + +## 🔧 Development Environment Setup + +### Current Status (Ready for Development) + +```bash +# All services running in development mode +$ docker compose ps +NAME STATUS PORTS +sirius-api Up 7 minutes 0.0.0.0:9001->9001/tcp +sirius-engine Up 7 minutes 0.0.0.0:5174->5174/tcp, 0.0.0.0:50051->50051/tcp +sirius-postgres Up 7 minutes 0.0.0.0:5432->5432/tcp +sirius-rabbitmq Up 7 minutes 0.0.0.0:5672->5672/tcp, 0.0.0.0:15672->15672/tcp +sirius-ui Up 4 minutes 0.0.0.0:3000->3000/tcp (Next.js dev server) +sirius-valkey Up 7 minutes 0.0.0.0:6379->6379/tcp +``` + +### Development Mode Features + +- **Live Code Reload**: Changes to `sirius-ui/` files trigger automatic rebuilds +- **Source Maps**: Full debugging support in browser dev tools +- **Hot Module Replacement**: React components update without page refresh +- **Volume Mounts**: Local code mounted at `/app` in containers + +### Quick Development Commands + +```bash +# Restart UI with code changes +docker compose restart sirius-ui + +# View live logs +docker compose logs -f sirius-ui + +# Access container shell for debugging +docker exec -it sirius-ui sh + +# Stop all services +docker compose down +``` + +### URLs for Testing + +- **UI**: http://localhost:3000 (Next.js dev server) +- **Terminal Page**: http://localhost:3000/terminal (SSR fixed, but has infinite loop) +- **API Health**: http://localhost:9001/health +- **RabbitMQ Management**: http://localhost:15672 (guest/guest) + +--- + +## ✅ DOCKER DEVELOPMENT SETUP COMPLETED + +### Multi-Stage Docker Implementation + +**Status**: ✅ **COMPLETED** - Proper Docker best practices implemented + +#### Solution Summary + +The Docker development issues have been **completely resolved** using a multi-stage Dockerfile approach: + +1. **Architecture Issues**: ✅ Fixed - Dependencies now compile in correct container architecture +2. **npm Install Failures**: ✅ Fixed - Proper staging prevents conflicts +3. **Prisma Generation**: ✅ Fixed - Generated during build stage, not runtime +4. **Development Hot Reloading**: ✅ Working - Source code changes trigger rebuilds +5. **Volume Mounting Strategy**: ✅ Optimized - Source mounted, node_modules isolated + +#### Implementation Details + +**Multi-Stage Dockerfile** (`sirius-ui/Dockerfile`): + +- **Base Stage**: Common dependencies and npm script fixes +- **Development Stage**: Dev dependencies, Prisma generation, dev server +- **Production Stage**: Optimized runtime build + +**Development Configuration** (`docker-compose.override.yml`): + +- **Target**: `development` stage for full dev features +- **Volume Mounts**: Source code only, node_modules preserved in container +- **Environment**: Development-specific variables and database connection + +**Production Configuration** (`docker-compose.prod.yml`): + +- **Target**: `production` stage for optimized runtime +- **No Volumes**: Uses built image as-is for production + +#### Verification Results + +```bash +# ✅ Container starts successfully +$ docker compose up sirius-ui -d +[+] Running 3/3 + ✔ Volume "sirius_node_modules" Created + ✔ Container sirius-postgres Running + ✔ Container sirius-ui Started + +# ✅ Next.js dev server running +$ docker exec sirius-ui ps aux +nextjs 1 npm run dev +nextjs 28 node /app/node_modules/.bin/next dev +nextjs 39 next-router-worker + +# ✅ UI accessible and working +$ curl -s http://localhost:3000 | head -2 +... + +# ✅ Prisma installed and working +$ docker exec sirius-ui npx prisma --version +prisma : 5.1.1 +@prisma/client : 5.1.1 +Current platform : linux-musl-arm64-openssl-3.0.x + +# ✅ Volume mounting working +$ touch sirius-ui/src/test.txt +$ docker exec sirius-ui ls /app/src/test.txt +/app/src/test.txt +``` + +#### Usage Commands + +**Development Mode** (Default): + +```bash +# Start development environment +docker compose up sirius-ui -d + +# View development logs +docker compose logs sirius-ui -f + +# Access development container +docker exec -it sirius-ui sh +``` + +**Production Mode**: + +```bash +# Build and run production image +docker compose -f docker-compose.yml -f docker-compose.prod.yml up sirius-ui -d +``` + +**Rebuild After Changes**: + +```bash +# Rebuild development image +docker compose build sirius-ui +docker compose up sirius-ui -d +``` + +### Architecture Benefits Achieved + +1. **Proper Separation**: Development and production stages serve different needs +2. **Architecture Compatibility**: Dependencies compile in target architecture +3. **Fast Development**: Source changes trigger immediate rebuilds +4. **Production Optimization**: Minimal production image with only runtime dependencies +5. **Developer Experience**: Standard Docker commands work as expected + +**🎯 READY FOR HANDOFF**: The Docker development environment is now properly configured following industry best practices. The next developer can focus entirely on fixing the terminal component infinite loop issue without Docker concerns. + +--- + +## ✅ DATABASE SETUP COMPLETED + +### Prisma Database Issue Resolution + +**Status**: ✅ **COMPLETED** - Database tables created and seeded successfully + +#### Problem Summary + +After implementing the Docker development setup, login attempts failed with database errors: + +``` +The table `public.users` does not exist in the current database. +``` + +**Root Cause**: Prisma client generation creates TypeScript client code but doesn't create actual database tables. Database migrations were never run. + +#### Solution Implemented + +1. **Created Initial Migration**: + + ```bash + docker exec sirius-ui npx prisma migrate dev --name init + ``` + + - Created `migrations/20250607191550_init/migration.sql` + - Applied migration to create all tables: `users`, `hosts`, `ports`, `scans`, `vulnerabilities` + +2. **Fixed Seed Script Configuration**: + + - Updated `package.json` seed command from `bun` to `npx tsx` + - Installed `tsx` dependency for TypeScript execution + - Successfully seeded admin user (username: `admin`, password: `password`) + +3. **Automated Database Setup**: + - Created `start-dev.sh` script that handles database setup on container start + - Updated Dockerfile to run migrations and seeding automatically + - Development containers now self-initialize database state + +#### Verification Results + +```bash +# ✅ Database tables created +$ docker exec sirius-postgres psql -U postgres -d postgres -c "\dt" + public | users | table | postgres + public | hosts | table | postgres + public | ports | table | postgres + public | scans | table | postgres + public | vulnerabilities | table | postgres + +# ✅ Admin user seeded +$ docker exec sirius-postgres psql -U postgres -d postgres -c "SELECT name, email FROM users;" + admin | admin@example.com + +# ✅ Startup script working +🚀 Starting Sirius UI Development Server... +📁 Applying database migrations... +No pending migrations to apply. +🌱 Running database seed... +Admin user updated with new password: admin +🎯 Starting Next.js development server... + +# ✅ Login page accessible +$ curl -s http://localhost:3000 | grep "Join the Pack" +Join the Pack +``` + +#### Login Credentials + +- **Username**: `admin` +- **Password**: `password` +- **Email**: `admin@example.com` + +#### Database Schema + +The following tables are now available: + +- **users**: Authentication and user management +- **hosts**: Scanned host information +- **ports**: Port scan results +- **vulnerabilities**: Vulnerability scan results +- **scans**: Scan job tracking + +#### Automated Setup Features + +**Development Mode**: Database automatically initializes on container start + +- Applies any pending migrations +- Seeds initial admin user +- Handles existing data gracefully (updates vs creates) + +**Production Mode**: Same migration system applies for production deployments + +**🎯 LOGIN FUNCTIONALITY RESTORED**: Users can now successfully log in to the application using the admin credentials. The database infrastructure is fully operational and ready for development. diff --git a/documentation/dev-notes/scanner-templates-fix-plan.md b/documentation/dev-notes/scanner-templates-fix-plan.md new file mode 100644 index 0000000..51ffbb7 --- /dev/null +++ b/documentation/dev-notes/scanner-templates-fix-plan.md @@ -0,0 +1,96 @@ +--- +title: "Scanner Templates Fix - Project Plan" +description: "Eight-PR sprint to fix three live scanner-settings bugs and replace the drift-prone Valkey contracts that caused them with a shared schema." +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2026-04-22" +author: "Development Team" +tags: ["project-plan", "scanner", "templates", "nse", "valkey", "agent-templates"] +categories: ["development", "planning"] +difficulty: "intermediate" +prerequisites: ["docker", "docker-compose", "go", "typescript", "valkey"] +related_docs: + - "README.tasks.md" + - "README.new-project.md" +dependencies: [] +llm_context: "high" +search_keywords: + [ + "scanner templates", + "nse scripts", + "agent templates", + "valkey contracts", + "template:custom", + "nse:script", + "shared schema", + ] +--- + +# Scanner Templates Fix - Project Plan + +## Project Overview + +**Goal**: Restore working "view, edit, and run" semantics for both NSE scripts and agent-based templates in the Advanced Scanner Settings UI, then eliminate the architectural drift (per-component Valkey contracts) that caused the bugs in the first place. + +**Scope**: +- PR 1-PR 5 (Phase A): surgical fixes that unbreak the UI and make custom-template uploads actually run. +- PR 6-PR 8 (Phase B): single source of truth for Valkey records (`go-api/sirius/store/templates`), consumer migration, and contract tests. + +**Out of scope (deferred Phase C)**: version-stamp polling for agent sync resilience and a typed envelope replacement for the `engine.commands` plain queue. Revisit if real-world failures appear. + +## Bug Inventory (verified) + +### Bug 1 - NSE descriptions/code show "No code available" +- Scanner writes keys with `.nse` extension: `nse:script:smb-vuln-cve2009-3103.nse`. +- UI canonicalizes the manifest entry, drops `.nse`, then looks up `nse:script:smb-vuln-cve2009-3103` - miss, falls through to placeholders. + +### Bug 2 - Agent template view/edit shows nothing +- `AgentTemplatesTab.handleView` / `handleEdit` use raw `fetch` directly to `sirius-api`, missing the `X-API-Key` header that `apiFetch` injects in tRPC paths. Returns `401`, UI shows empty Description/Content. + +### Bug 3 - Newly uploaded custom templates never run +- `UploadAgentTemplate` writes raw YAML to `template:custom:` (standard templates use a JSON envelope with base64 content). +- No `template:meta:` record is written, so the agent sync server (which enumerates from `template:meta:*`) doesn't see the new template. +- Notification is published to `engine.commands`, but no consumer listens on that queue. + +## Master PR Sequence + +### Phase A - Surgical fixes + +| PR | Title | Repos touched | +| --- | --- | --- | +| 1 | NSE script key harmonization | app-scanner, sirius-ui (no-op) | +| 2 | Agent template view/edit auth fix | sirius-ui | +| 3 | Custom template upload writes envelope + meta + sync trigger | sirius-api, app-agent | +| 4 | UpdateAgentTemplate handler + UI wiring | sirius-api, sirius-ui | +| 5 | engine.commands listener (defense-in-depth) | app-agent | + +### Phase B - Architectural durability + +| PR | Title | Repos touched | +| --- | --- | --- | +| 6 | Shared schema package in `go-api/sirius/store/templates` | go-api | +| 7 | Migrate consumers to shared package; retire dual-format heuristic | sirius-api, app-scanner, app-agent | +| 8 | Contract tests + architecture doc | Sirius (testing/, documentation/) | + +## Workflow + +- One feature branch per repo: `feature/scanner-templates-fix`. +- Each PR is squashed to main individually. +- Each PR is planned in detail (like PR 1 in `scanner_templates_fix_3be9da41.plan.md`) before execution. +- Sprint tracker: [tasks/scanner-templates-fix.json](../../tasks/scanner-templates-fix.json). + +## Verification Strategy + +- PR 1: live `valkey-cli` inspection + UI Description/Code populated + Save round-trip + Full Scan green. +- PR 2: View/Edit dialogs render with content, no 401s in browser console. +- PR 3: Upload custom template via UI -> agent's `/custom/.yaml` exists -> next `internal:template-scan` reports the new template detected. +- PR 4: Edit existing template, Save Changes, refresh -> changes persist. +- PR 5: Manually publish a fake `internal:template upload` to `engine.commands` -> agents receive sync command. +- PR 6: `go test ./...` in go-api passes. +- PR 7: All three Go modules build cleanly with the shared package; the JSON-or-YAML fork is gone. +- PR 8: `make test-integration` runs the contract test for every writer/reader pair; doc renders in the documentation index. + +## References + +- Master plan + PR 1 detail: `~/.cursor/plans/scanner_templates_fix_3be9da41.plan.md` +- Tracker: `tasks/scanner-templates-fix.json` diff --git a/documentation/dev-notes/scanner-templates-fix-pr-playbook.md b/documentation/dev-notes/scanner-templates-fix-pr-playbook.md new file mode 100644 index 0000000..c4f6ce7 --- /dev/null +++ b/documentation/dev-notes/scanner-templates-fix-pr-playbook.md @@ -0,0 +1,432 @@ +--- + +title: "Scanner Templates Fix - PR 2-8 Playbook" +description: "Detailed per-PR plan for the remaining seven PRs in the scanner-templates-fix sprint. Each section is self-contained: goal, files, change set, tests, verification, risk." +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2026-04-22" +author: "Development Team" +tags: ["pr-plan", "scanner", "templates", "agent-templates", "valkey"] +categories: ["development", "planning"] +difficulty: "intermediate" +prerequisites: ["scanner-templates-fix-plan"] +related_docs: + +- "scanner-templates-fix-plan.md" +- "README.tasks.md" +dependencies: [] +llm_context: "high" +search_keywords: +[ +"scanner templates", +"agent templates", +"auth bypass", +"engine.commands", +"shared schema", +"go-api templates package", +"contract tests", +] + +--- + +# Scanner Templates Fix - PR 2-8 Playbook + +PR 1 ships separately (`SiriusScan/app-scanner#2`). The remaining seven PRs each have a focused, self-contained plan below. Execute one PR at a time; do not pre-stage commits. + +--- + +## PR 2 - Agent Template View/Edit Auth Fix + +### Goal + +Stop bypassing the API-key middleware when the UI loads a single agent template's full content. Bug 2 in `[scanner-templates-fix-plan.md](scanner-templates-fix-plan.md)`. + +### Root cause + +`[AgentTemplatesTab.tsx](../../sirius-ui/src/components/scanner/agent/AgentTemplatesTab.tsx)` lines 38-72 issue raw `fetch()` calls to `${NEXT_PUBLIC_SIRIUS_API_URL}/api/agent-templates/`, skipping the `apiFetch` helper that injects `X-API-Key`. `sirius-api`'s global `APIKeyMiddleware` rejects the request with 401, the catch block alerts "Failed to load template", and the View/Edit dialogs render empty fields. + +### Files + +- `[sirius-ui/src/components/scanner/agent/AgentTemplatesTab.tsx](../../sirius-ui/src/components/scanner/agent/AgentTemplatesTab.tsx)` + +### Change set + +1. Remove the two `fetch(...)` blocks in `handleView` and `handleEdit`. +2. Replace each with an authenticated tRPC call: + ```ts + const fullTemplate = await utils.agentTemplates.getTemplate.fetch({ id: template.id }); + ``` + (`getTemplate` already exists in `[agent-templates.ts](../../sirius-ui/src/server/api/routers/agent-templates.ts)` line 57 and routes through `apiFetch` -> `X-API-Key` automatic.) +3. Drop the now-unused `process.env.NEXT_PUBLIC_SIRIUS_API_URL` reference from this file. +4. Surface error detail (`error instanceof Error ? error.message : ...`) in the alert so future regressions are easier to diagnose without DevTools. + +### Tests + +- Add component test under `sirius-ui/src/components/scanner/agent/__tests__/` (or extend existing) that mocks `utils.agentTemplates.getTemplate.fetch` and asserts both flows call it with the template id. +- Manual: open Advanced -> Agent -> any template -> Description and Content render. No `401` in browser console. + +### Verification + +1. Build UI image (or use `sirius-ui` dev container). +2. Open a built-in template (e.g. `apache-cve-2021-41773`): Description tab populated, Content tab shows YAML. +3. Click Edit: form pre-populates with parsed YAML fields. +4. Browser DevTools Network tab: only tRPC calls to `/api/trpc/agentTemplates.getTemplate*` appear; no direct `/api/agent-templates/*` requests. + +### Risk + +Low. `getTemplate` returns the same shape as the bypassed REST endpoint (the tRPC route literally proxies to it via `apiFetch`). + +### Out of scope + +The latent "Save always creates" bug is PR 4. + +--- + +## PR 3 - Custom Template Upload Writes Envelope + Meta + Triggers Sync + +### Goal + +Make `UploadAgentTemplate` produce records the agent-side sync server actually understands, and notify agents to pull the new template. Resolves Bug 3a, 3b, and the missing-consumer leg of 3c. + +### Root cause (three parts) + +1. **3a Format mismatch**: handler writes raw YAML to `template:custom:`. The agent-side reader expects the standard JSON envelope (`{ id, content_b64, sha256, source, ... }`). +2. **3b Missing meta record**: handler never writes `template:meta:`. The agent's enumeration starts at `template:meta:`*; without a meta entry, the new template is invisible to sync. +3. **3c Wrong queue**: handler publishes to `engine.commands`, but `app-agent`'s only template-related consumer listens on `agent.template.sync.jobs`. (PR 5 adds the missing `engine.commands` listener for defense-in-depth; PR 3 fixes the system via the working queue.) + +### Files + +- `[sirius-api/handlers/agent_template_handler.go](../../sirius-api/handlers/agent_template_handler.go)` - rewrite `UploadAgentTemplate` +- `[sirius-api/handlers/agent_template_handler.go](../../sirius-api/handlers/agent_template_handler.go)` - add small helper `buildTemplateEnvelope(yaml []byte, source string) (envelopeJSON, metaJSON []byte, err error)` so PR 4 can reuse it + +### Change set + +1. Compute `sha256` over the raw YAML bytes. +2. Build envelope JSON matching the existing read-side decoder: + ```go + envelope := struct { + ID string `json:"id"` + Path string `json:"path"` + ContentBase64 string `json:"content_b64"` + SHA256 string `json:"sha256"` + Source string `json:"source"` + UpdatedAt int64 `json:"updated_at"` + }{ + ID: yamlTemplate.ID, + Path: "custom/" + yamlTemplate.ID + ".yaml", + ContentBase64: base64.StdEncoding.EncodeToString([]byte(request.Content)), + SHA256: hex.EncodeToString(sha[:]), + Source: "custom", + UpdatedAt: time.Now().Unix(), + } + ``` +3. Store envelope at `template:custom:`. +4. Build meta record (mirror the shape used by `template:meta:*` from the GitHub sync writer in `[app-agent/internal/template/valkey/sync.go](../../../minor-projects/app-agent/internal/template/valkey/sync.go)` - read it before writing the handler so we exactly match field names): + ```go + meta := struct { + ID string `json:"id"` + Source string `json:"source"` + SHA256 string `json:"sha256"` + IsCustom bool `json:"is_custom"` + UpdatedAt int64 `json:"updated_at"` + }{ ... IsCustom: true ... } + ``` + Store at `template:meta:`. +5. Replace the `engine.commands` publish with `agent.template.sync.jobs`. Payload should match what the existing notify-agents path emits today (read `[app-agent/internal/server/template_sync_queue.go](../../../minor-projects/app-agent/internal/server/template_sync_queue.go)` and the producer in `repository_manager.go::notifyAgents`). +6. Wrap all KV writes + queue publish in best-effort rollback: if meta write fails after envelope write, delete the envelope and 500. + +### Tests + +- Handler-level Go test using a fake KVStore + fake queue: assert all three writes (`template:custom:`, `template:meta:`) and one queue publish to `agent.template.sync.jobs`. +- End-to-end: upload via UI -> `valkey-cli GET template:meta:` returns JSON with `is_custom: true` -> `valkey-cli GET template:custom:` returns envelope with base64 content matching the YAML -> `agent.template.sync.jobs` consumer logs show the new id. + +### Verification + +1. Upload a new custom template through the UI. +2. `docker exec sirius-valkey valkey-cli KEYS 'template:meta:*' | grep ` matches. +3. `docker exec sirius-engine ls /custom/` shows `.yaml`. +4. Run an agent-based scan -> agent log reports `template detected: `. + +### Risk + +Medium. Field-name drift between sirius-api's meta writer and app-agent's meta reader will break enumeration silently. Mitigation: read the existing GitHub-sync writer in `app-agent` first and exactly mirror its shape (PR 6 will replace this with a shared package; PR 3 is the bridge). + +### Out of scope + +- Update flow (PR 4) +- engine.commands listener (PR 5) +- Replacing the JSON-or-YAML read heuristic (PR 7) + +--- + +## PR 4 - UpdateAgentTemplate Handler + UI Wiring + +### Goal + +Editing an existing template actually updates it instead of silently creating a near-duplicate via the upload path. Resolves the latent Bug 4. + +### Root cause + +- `sirius-api/handlers/agent_template_handler.go::UpdateAgentTemplate` is a stub (returns success without writing). +- `sirius-ui/.../AgentTemplatesTab.tsx::handleSaveTemplate` (lines 104-130) always calls `uploadMutation`, never `updateTemplate`, even when `editingTemplate` is set. + +### Files + +- `[sirius-api/handlers/agent_template_handler.go](../../sirius-api/handlers/agent_template_handler.go)` +- `[sirius-ui/src/components/scanner/agent/AgentTemplatesTab.tsx](../../sirius-ui/src/components/scanner/agent/AgentTemplatesTab.tsx)` + +### Change set + +**Backend (`UpdateAgentTemplate`)**: + +1. Require URL param `:id`; require body shape identical to upload. +2. Confirm `template:meta:` exists (404 if not). +3. Reject id mismatch between URL param and parsed YAML id (400). +4. Reuse the `buildTemplateEnvelope` helper introduced in PR 3 to write the new envelope + meta with `IsCustom: true` preserved if the original was custom (read existing meta first to detect). +5. Publish to `agent.template.sync.jobs` (same producer shape as PR 3). + +**Frontend (`handleSaveTemplate`)**: + +1. Add `updateMutation = api.agentTemplates.updateTemplate.useMutation();` next to existing mutations. +2. Branch: + ```ts + if (editingTemplate) { + await updateMutation.mutateAsync({ + id: editingTemplate.id, + content: yamlContent, + filename, + author: template.author, + }); + } else { + await uploadMutation.mutateAsync({ ... }); + } + ``` +3. Clear `editingTemplate` on success so subsequent Save Changes don't accidentally re-target an old id. + +### Tests + +- Backend: handler test for happy path, 404, id mismatch, immutable `is_custom` flag. +- UI: assert `updateMutation.mutateAsync` called when `editingTemplate` is set; `uploadMutation` called otherwise. + +### Verification + +1. Edit a custom template's description, Save Changes, refresh page -> change persists. +2. `valkey-cli GET template:custom:` shows updated `updated_at` timestamp. +3. Built-in (non-custom) templates: confirm UX (likely should disable Edit button or copy-on-edit; out of scope here, file follow-up if needed). + +### Risk + +Low-medium. The is-custom preservation must read existing meta before overwriting; missing this turns built-in templates into custom ones. + +### Out of scope + +- Read-only mode for built-in templates (file as follow-up if it becomes a UX issue). + +--- + +## PR 5 - engine.commands Listener (Defense-in-Depth) + +### Goal + +Add an `EngineCommandQueueProcessor` in `app-agent` so any producer that publishes `internal:template upload` / `internal:template delete` to `engine.commands` (today: stale code paths and any third-party integrations) routes back into the existing notify-agents pipeline. Strictly redundant after PR 3 makes the working path the default; this PR catches future drift. + +### Files + +- New: `minor-projects/app-agent/internal/server/engine_commands_consumer.go` +- Wire into `minor-projects/app-agent/internal/server/server.go` startup alongside `template_sync_queue.go` + +### Change set + +1. Define a queue consumer struct mirroring `TemplateSyncQueueProcessor`: + - Subscribes to `engine.commands` durable queue + - Decodes `{command string, template_id string, timestamp string}` envelopes + - Switches on `command`: + - `"internal:template upload"` -> call existing notify-agents helper (extract from `repository_manager.go::notifyAgents` if needed) + - `"internal:template delete"` -> same path with delete signal + - default -> log + ack (don't block other producers) +2. Start consumer from `server.go::Start()` next to the existing template-sync consumer. +3. Use the same prefetch / backoff configuration to keep operational behavior consistent. + +### Tests + +- Go test with a fake AMQP channel (the existing test pattern in `template_sync_queue_test.go` if present): publish a fake upload message, assert notify-agents is invoked once. +- Integration: publish a hand-rolled message via `rabbitmqadmin` -> agents log a sync event. + +### Verification + +1. With agents connected, manually publish: + ```bash + docker exec sirius-rabbitmq rabbitmqadmin publish \ + exchange=amq.default routing_key=engine.commands \ + payload='{"command":"internal:template upload","template_id":"smoke-test","timestamp":"..."}' + ``` +2. Agent log shows `received template sync command for smoke-test`. + +### Risk + +Low. Strictly additive; failure modes are scoped to the new consumer. + +### Out of scope + +- Replacing `engine.commands` with a typed exchange/event bus (deferred Phase C). + +--- + +## PR 6 - Shared Schema Package in `go-api/sirius/store/templates` + +### Goal + +Single Go package owns every Valkey contract for templates and NSE scripts so future drift is impossible. + +### Files + +- New package: `minor-projects/go-api/sirius/store/templates/` + - `keys.go` - constants: `KeyAgentTemplateCustom`, `KeyAgentTemplateMeta`, `KeyAgentTemplateBuiltin`, `KeyNseScript`, `KeyNseManifest`, etc. + - `canonical.go` - `CanonicalScriptID(id string) string` (extracted from app-scanner PR 1) + - `template_record.go` - `TemplateRecord`, `TemplateMeta` types + `EncodeTemplate`, `DecodeTemplate`, `EncodeMeta`, `DecodeMeta` + - `nse_record.go` - `NseScriptRecord`, `NseManifestEntry` types + encode/decode helpers + - `read.go` - thin `ReadTemplate(ctx, kv, id)`, `ReadNseScript(ctx, kv, id)` etc. that compose key construction with decode + - `write.go` - matching `WriteTemplate`, `WriteNseScript`, `WriteNseManifest` helpers (handles canonicalization + envelope build atomically) + - `templates_test.go`, `nse_test.go`, `canonical_test.go` + +### Change set + +1. Mirror PR 1's canonicalization helper exactly (port the unit-test cases too). +2. Define `TemplateRecord` matching the envelope shape introduced in PR 3 (`ID`, `Path`, `ContentBase64`, `SHA256`, `Source`, `UpdatedAt`). +3. Define `TemplateMeta` matching the existing app-agent GitHub-sync writer (read it first to lock the field names). +4. `WriteTemplate` is the only function that allowed-callers use to put both records + (optional) emit a `agent.template.sync.jobs` payload struct (caller publishes; helper just builds the bytes). +5. Tag the package version in go-api (`v0.0.18` or whatever's next) so consumers can pin. + +### Tests + +- Round-trip `WriteTemplate` -> `ReadTemplate` against an in-memory fake KVStore. +- Canonicalization table tests (port from PR 1). +- Schema-stability test: encoded JSON for a fixed input matches a checked-in golden file (catches accidental field renames). + +### Verification + +- `go test ./sirius/store/templates/...` green. +- Tagged release of go-api includes the new package. + +### Risk + +Medium. This is the contract every other component will depend on; getting field names right matters. Mitigation: write encoders by reading current producers byte-for-byte. + +### Out of scope + +- No consumers migrated yet (PR 7). + +--- + +## PR 7 - Migrate Consumers to the Shared Package + +### Goal + +Delete every ad-hoc encoder/decoder for template + NSE records. Retire the JSON-or-YAML heuristic added by years of drift. + +### Files + +- `sirius-api/go.mod` (bump `go-api` to the version that includes `store/templates`) +- `sirius-api/handlers/agent_template_handler.go`: + - `GetAgentTemplates` / `GetAgentTemplate` -> use `templates.ReadTemplate`. Delete the JSON-or-YAML fork at lines 153-170 and 255-273. + - `UploadAgentTemplate` / `UpdateAgentTemplate` -> use `templates.WriteTemplate`. + - `DeleteAgentTemplate` -> use `templates.DeleteTemplate`. +- `minor-projects/app-scanner/go.mod` (bump go-api) +- `minor-projects/app-scanner/internal/nse/sync.go`: + - Delete the local `canonicalScriptID` (added in PR 1). + - Replace direct `kvStore.SetValue(...)` with `templates.WriteNseScript` / `WriteNseManifest`. +- `minor-projects/app-agent/go.mod` (bump go-api) +- `minor-projects/app-agent/internal/template/agent/sync_manager.go` and `internal/template/valkey/sync.go`: + - Replace ad-hoc envelope marshaling with `templates.ReadTemplate` / `WriteTemplate`. +- `minor-projects/app-agent/internal/server/template_sync_queue.go` and (new from PR 5) `engine_commands_consumer.go`: + - Replace queue payload struct definitions with the shared payload type from `store/templates`. + +### Change set + +- Code is mostly mechanical: import the package, swap calls, delete dead code. +- Verify no consumer still defines `template:custom:` / `nse:script:` string literals (grep in CI to enforce). + +### Tests + +- Existing tests in each module continue to pass after the swap. +- Add a "no string literals" lint check (a Go test that scans the consumer packages for forbidden prefixes; reports violations). + +### Verification + +- Clean build of all three Go modules with the new go-api. +- `grep -rn 'template:custom:' sirius-api/ minor-projects/app-agent/ minor-projects/app-scanner/` returns zero hits outside `go-api/sirius/store/templates`. +- Re-run all PR 1-5 manual verifications: still green. + +### Risk + +Medium-high. Many touch points across three repos. Mitigation: do consumer migration repo-by-repo with separate commits, run integration tests between each. + +### Out of scope + +- Adding new fields to envelopes (do that as a separate, focused PR after migration is stable). + +--- + +## PR 8 - Contract Tests + Architecture Doc + +### Goal + +Make the writer-A / reader-B assumption physically testable in CI, and write the contract down so future agents (human or AI) auto-load it. + +### Files + +- New: `Sirius/testing/integration/scanner_storage_contract_test.go` (or matching language under `Sirius/testing/`) +- New: `Sirius/documentation/dev/architecture/README.scanner-storage.md` + +### Change set + +**Contract test** + +- Spin up a Valkey container. +- For every (writer, reader) pair, use the public `templates` package helpers: + - `sirius-api WriteTemplate` -> `app-agent ReadTemplate` + - `app-scanner WriteNseScript` -> `sirius-api ReadNseScript` + - `app-agent WriteTemplate` -> `sirius-ui` (via tRPC fixture or direct REST call into a running api) +- Assert byte-equality on key shapes and JSON shapes. + +**Architecture doc** (`README.scanner-storage.md` with `llm_context: "high"`) + +- Diagram: producers, consumers, queues, key namespaces. +- Field tables for every record type (links to `go-api/sirius/store/templates` source). +- Drift policy: contract changes require a go-api version bump + this doc + the contract test all updated in the same PR. +- Wire into `documentation/README.documentation-index.md`. + +### Tests + +- New contract test runs in CI under `make test-integration`. +- Doc lint pass (`make lint-docs`, `make lint-index`). + +### Verification + +- `cd Sirius/testing && make test-integration` green. +- New doc appears in the documentation index and renders cleanly. + +### Risk + +Low. Test infrastructure is mostly additive; doc changes are pure additions. + +### Out of scope (deferred Phase C) + +- Version-stamp polling for agent sync resilience. +- Replacing `engine.commands` with a typed exchange. + +--- + +## Execution checklist + +Before opening each PR, work through: + +- Plan section above re-read end-to-end +- Branch: `feature/scanner-templates-fix` in the affected repo +- Tracker updated: `tasks/scanner-templates-fix.json` task moves to `in_progress` +- Implementation matches "Change set" +- All tests in "Tests" pass locally +- All steps in "Verification" green +- PR description includes operator notes (only PR 1 and PR 7 should need them) +- Tracker updated to `done` on merge + diff --git a/documentation/dev-notes/startup-secrets-redesign-plan.md b/documentation/dev-notes/startup-secrets-redesign-plan.md new file mode 100644 index 0000000..1cad18a --- /dev/null +++ b/documentation/dev-notes/startup-secrets-redesign-plan.md @@ -0,0 +1,118 @@ +--- +title: "Startup & Secrets Redesign - Project Plan" +description: "Detailed implementation strategy for installer-first startup, secure secret defaults, and stateless infrastructure API key validation." +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2026-04-01" +author: "Development Team" +tags: ["project-plan", "startup", "secrets", "installer", "auth", "docker"] +categories: ["development", "planning", "security", "operations"] +difficulty: "advanced" +prerequisites: ["docker", "docker-compose", "go", "nextauth", "prisma"] +related_docs: + - "README.tasks.md" + - "README.new-project.md" + - "README.api-key-operations.md" + - "README.auth-surface-matrix.md" +dependencies: [] +llm_context: "high" +search_keywords: + [ + "startup redesign", + "secrets management", + "installer", + "sirius_api_key", + "initial_admin_password", + "docker compose hardening", + ] +--- + +# Startup & Secrets Redesign - Project Plan + +## Project Overview + +**Goal**: Deliver a secure-by-default and low-friction startup experience for Sirius using an installer-first flow, deterministic service key behavior, and strict runtime contracts. + +**Scope**: +- Build a first-run installer workflow. +- Remove insecure secret defaults and weak fallbacks. +- Keep root service API key stateless from environment while preserving Valkey-backed user-generated keys. +- Update docs, tests, and CI to match new startup and security expectations. + +## Key Outcomes + +1. **Installer-first onboarding** for local and automation environments. +2. **No default admin password** in seed/startup workflows. +3. **Deterministic infra key auth** independent of Valkey bootstrap state. +4. **Updated deployment docs** for compose, Terraform, and secrets hardening options. +5. **Aligned validation pipeline** across local tests and CI. + +## Technical Strategy + +### 1) Installer Productization +- Create an installer module that loads `.env.production.example`, merges existing `.env`, and generates missing required secrets. +- Support interactive and non-interactive modes with output safety options for CI and production automation. +- Preserve backward compatibility by keeping `setup.sh` as a transition wrapper. + +### 2) Runtime Contract Hardening +- Require critical auth and seed secrets in compose files. +- Remove fallback values that mask misconfiguration in production. +- Enforce fail-fast behavior in seed and UI runtime config when required secrets are missing. + +### 3) Auth Model Clarification +- Validate infra requests statelessly using `SIRIUS_API_KEY` from environment. +- Retain Valkey-backed validation only for dynamic/user-generated API keys. +- Document this split clearly in runbooks and architecture docs. + +### 4) Verification and Rollout +- Update tests and CI job environments to provide required vars. +- Add optional secrets overlays (`compose`/`swarm`) for hardened deployments. +- Publish migration notes for existing users. + +## Milestones + +### Milestone A: Foundations +- Add task tracker and this plan note. +- Record architecture decision updates. + +### Milestone B: Installer + Compatibility +- Implement installer command and internals. +- Add compatibility wrapper behavior in `setup.sh`. + +### Milestone C: Runtime + Auth Hardening +- Patch compose/env/auth/seed/script behavior. +- Validate stateless root-key and dynamic key paths. + +### Milestone D: Docs + Validation Pipeline +- Rewrite onboarding/deployment/runbook docs. +- Update container tests and CI workflows. + +### Milestone E: Optional Hardening + Release +- Add secrets overlay files. +- Execute release verification matrix and migration notes. + +## Progress (snapshot) + +- Compose/runtime contract: `SIRIUS_API_URL` is canonical for server-side API base URL; `API_BASE_URL` on `sirius-engine` is derived from the same value to avoid URL drift. `sirius-engine` depends on `sirius-api` health in base compose. Engine startup preflight requires HTTP 2xx on authenticated `GET /host/`. `scripts/verify-runtime-auth-contract.sh` supports alternate container names via `SIRIUS_CONTRACT_CONTAINER_*`. `make test-all` includes `test-runtime-contract`. + +## Success Criteria + +- [ ] Fresh install with Docker only can generate valid config and start successfully. +- [ ] Admin login uses installer-provided/generated password; no default password remains. +- [ ] Root API key rotation works via config change and restart without Valkey state repair. +- [ ] User-generated API keys continue to work for create/list/revoke. +- [ ] CI compose checks and security suites pass with strict required variables. +- [ ] Documentation reflects installer-first and stateless root-key architecture. + +## Risks and Mitigations + +- **Risk**: Startup regressions due to stricter required env vars. + - **Mitigation**: Provide explicit preflight checks and actionable error messages. +- **Risk**: Existing users may depend on old defaults. + - **Mitigation**: Add compatibility wrapper and migration notes. +- **Risk**: CI breakage from new required vars. + - **Mitigation**: Update CI and test scripts in same change set. + +## Notes + +This plan intentionally prioritizes secure defaults and deterministic behavior over permissive startup fallbacks. The migration path remains pragmatic by preserving compatibility entrypoints while moving users to the installer model. diff --git a/documentation/dev-notes/system-monitoring-plan.md b/documentation/dev-notes/system-monitoring-plan.md new file mode 100644 index 0000000..a4f79fe --- /dev/null +++ b/documentation/dev-notes/system-monitoring-plan.md @@ -0,0 +1,112 @@ +--- +title: "System Monitoring - Project Plan" +description: "High-level project overview and implementation strategy for system monitoring dashboard and logging infrastructure" +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Development Team" +tags: ["project-plan", "sprint", "system-monitoring", "dashboard", "logging"] +categories: ["development", "planning"] +difficulty: "intermediate" +prerequisites: ["docker", "next.js", "go", "redis"] +related_docs: + - "README.tasks.md" + - "README.container-testing.md" + - "README.architecture-quick-reference.md" +dependencies: [] +llm_context: "medium" +search_keywords: ["system-monitoring", "project-plan", "development", "dashboard", "logging"] +--- + +# System Monitoring - Project Plan + +## Project Overview + +**Goal**: Implement a comprehensive system monitoring dashboard that provides real-time visibility into microservice health, system logs, and performance metrics for the SiriusScan vulnerability scanner. + +**Timeline**: 2-3 weeks +**Scope**: Frontend dashboard, backend health check APIs, centralized logging system, and log storage/retrieval infrastructure + +## Key Deliverables + +1. **System Monitor Dashboard Page** - New Next.js page accessible via Settings navigation +2. **Service Health Monitoring** - Real-time status checks for all microservices (UI, API, Engine, PostgreSQL, Valkey, RabbitMQ) +3. **Centralized Logging System** - Structured logging infrastructure with Valkey storage +4. **Log Viewer Interface** - Searchable, filterable log display using TanStack Table +5. **API Endpoints** - Health check and logging APIs for system monitoring + +## Technical Approach + +### Phase 1: Service Health Monitoring +- Create system monitor page with service status cards +- Implement health check APIs for all services +- Use existing health check patterns from container testing +- Real-time status updates with polling mechanism + +### Phase 2: Centralized Logging Infrastructure +- Design log format and metadata structure +- Implement logging API endpoints +- Create Valkey-based log storage with retention policies +- Build log viewer with search and filtering capabilities + +### Phase 3: Integration and Polish +- Connect frontend to backend APIs +- Implement error handling and retry logic +- Add performance optimizations +- Complete documentation and testing + +## Success Criteria + +- [ ] System monitor page accessible via Settings navigation +- [ ] All 6 microservices show real-time health status +- [ ] Centralized logging system captures logs from all services +- [ ] Log viewer supports search, filtering, and pagination +- [ ] Health checks use same patterns as container testing +- [ ] Log retention policy prevents storage bloat +- [ ] Real-time updates work reliably with error handling +- [ ] UI follows existing design patterns and component library + +## Risk Assessment + +**High Risk Items:** + +- **Log Volume Management**: Vulnerability scanner may generate high log volume - Mitigation: Implement log retention policies and size limits +- **Real-time Performance**: Polling-based updates may impact performance - Mitigation: Use efficient polling intervals and optimize queries + +**Dependencies:** + +- Existing health check infrastructure in container testing +- Valkey/Redis availability for log storage +- Current UI component library and design patterns + +## Technical Decisions + +### Log Storage Strategy +- **Storage**: Valkey (Redis-compatible) for log storage +- **Retention**: Configurable log cache size with automatic cleanup +- **Format**: Structured JSON logs with metadata (service, timestamp, level, message) +- **API**: RESTful endpoints for log submission and retrieval + +### Health Check Implementation +- **Pattern**: Follow existing container testing health check patterns +- **Services**: UI (port 3000), API (port 9001/health), Engine (port 5174), PostgreSQL, Valkey, RabbitMQ +- **Method**: HTTP health checks where available, process checks for others +- **Updates**: 5-second polling interval with error handling + +### UI Architecture +- **Framework**: Next.js page with existing Layout component +- **Components**: TanStack Table for logs, custom status cards for services +- **Styling**: Shadcn/ui components with existing design system +- **Navigation**: Add to Settings dropdown menu + +## Notes + +This project will establish the foundation for comprehensive system observability in SiriusScan. The monitoring dashboard will be essential for troubleshooting issues and understanding system performance as the application matures. + +The logging system will use a simple but effective approach with Valkey storage, allowing for future enhancements like log aggregation, alerting, and more sophisticated retention policies. + +Key focus areas: +- Leverage existing health check patterns for consistency +- Build scalable logging infrastructure +- Create intuitive monitoring interface +- Ensure performance and reliability diff --git a/documentation/dev/ABOUT.documentation.md b/documentation/dev/ABOUT.documentation.md new file mode 100644 index 0000000..75338e6 --- /dev/null +++ b/documentation/dev/ABOUT.documentation.md @@ -0,0 +1,462 @@ +--- +title: "About Sirius Documentation" +description: "A comprehensive guide to the Sirius project's documentation system, including standards, conventions, and best practices for creating and maintaining high-quality, machine-readable documentation." +template: "TEMPLATE.custom" +version: "1.0.0" +last_updated: "2025-01-03" +author: "AI Assistant" +tags: + ["documentation", "standards", "guidelines", "llm-friendly", "best-practices"] +categories: ["project-management", "development"] +difficulty: "beginner" +prerequisites: [] +related_docs: + - "README.documentation-index.md" + - "TEMPLATE.documentation-standard.md" + - "deployment/README.workflows.md" +dependencies: [] +llm_context: "high" +search_keywords: + [ + "documentation standards", + "llm documentation", + "markdown conventions", + "sirius docs", + ] +--- + +# ABOUT Documentation + +> **📚 Documentation Index**: For a complete list of all documentation files, see [README.documentation-index.md](../README.documentation-index.md) + +## Purpose + +This document defines the documentation standards, conventions, and processes for the Sirius project. It serves as the definitive guide for anyone creating, maintaining, or using documentation within our ecosystem, with special emphasis on LLM-consumable structure and machine readability. + +## When to Use This Guide + +- **Before creating any new documentation** - Understand our standards first +- **When updating existing documentation** - Ensure consistency with our conventions +- **When troubleshooting documentation issues** - Reference our established patterns +- **During code reviews** - Verify documentation meets our standards +- **When onboarding new team members** - Provide clear documentation guidelines +- **For LLM context building** - Ensure documentation is optimally structured for AI consumption + +## How to Use This Guide + +1. **Start with the documentation index** - Review [README.documentation-index.md](../README.documentation-index.md) to see all available documentation +2. **Read the Lexicon** - Understand our naming conventions and terminology +3. **Review File Types** - Know which template to use for different documentation needs +4. **Follow the Standards** - Use our template structure for consistency +5. **Add Front Matter** - Include YAML metadata for machine readability +6. **Link Documents** - Establish relationships between related documentation +7. **Update as Needed** - Keep this guide current with project evolution + +## What This Documentation System Is + +### Core Philosophy + +Our documentation system is designed around **layered information architecture** where the most critical information appears first, followed by increasingly detailed technical content. This ensures that users can quickly find what they need without wading through irrelevant details. + +**LLM Optimization**: Every document is structured to provide maximum context to Large Language Models, with clear metadata, relationships, and machine-readable front matter. + +### File Naming Conventions + +#### Lexicon of File Types + +| File Type | Prefix | Purpose | Example | Template Used | +| ------------------- | ------------------ | ------------------------------------ | ------------------------------------ | ------------------------------- | +| **ABOUT** | `ABOUT.` | Explains how to use documentation | `ABOUT.documentation.md` | TEMPLATE.about | +| **TEMPLATE** | `TEMPLATE.` | Defines structure for document types | `TEMPLATE.documentation-standard.md` | TEMPLATE.template | +| **README** | `README.` | Primary documentation for a topic | `README.container-testing.md` | TEMPLATE.documentation-standard | +| **GUIDE** | `GUIDE.` | Step-by-step instructions | `GUIDE.deployment.md` | TEMPLATE.guide | +| **REFERENCE** | `REFERENCE.` | Technical specifications | `REFERENCE.api-endpoints.md` | TEMPLATE.reference | +| **TROUBLESHOOTING** | `TROUBLESHOOTING.` | Problem-solving focused | `TROUBLESHOOTING.docker-issues.md` | TEMPLATE.troubleshooting | +| **ARCHITECTURE** | `ARCHITECTURE.` | System design and structure | `ARCHITECTURE.system-overview.md` | TEMPLATE.architecture | +| **API** | `API.` | API documentation and specifications | `API.endpoints.md` | TEMPLATE.api | + +#### Naming Rules + +1. **All prefixes are fully capitalized** (ABOUT, TEMPLATE, README, etc.) +2. **Descriptive suffixes** use kebab-case (container-testing, api-endpoints) +3. **File extensions** are always `.md` for Markdown files +4. **No spaces** in filenames - use hyphens instead +5. **Version suffixes** for multiple versions (e.g., `README.deployment-v2.md`) + +### Directory Structure + +``` +documentation/ +├── dev/ # Development documentation +│ ├── ABOUT.documentation.md # This file +│ ├── templates/ # Document templates +│ │ ├── TEMPLATE.about.md +│ │ ├── TEMPLATE.documentation-standard.md +│ │ ├── TEMPLATE.guide.md +│ │ ├── TEMPLATE.reference.md +│ │ ├── TEMPLATE.troubleshooting.md +│ │ ├── TEMPLATE.architecture.md +│ │ └── TEMPLATE.api.md +│ ├── architecture/ # System architecture docs +│ │ ├── ARCHITECTURE.system-overview.md +│ │ └── ARCHITECTURE.data-flow.md +│ ├── operations/ # Operations documentation +│ │ ├── README.git-operations.md +│ │ └── README.terraform-deployment.md +│ ├── test/ # Testing documentation +│ │ ├── README.container-testing.md +│ │ └── GUIDE.testing-workflows.md +│ ├── api/ # API documentation +│ │ ├── API.endpoints.md +│ │ └── REFERENCE.api-specs.md +│ └── dev-notes/ # Development notes +│ ├── TROUBLESHOOTING.docker-issues.md +│ └── GUIDE.development-setup.md +├── production/ # Production documentation +│ ├── README.deployment.md +│ ├── GUIDE.monitoring.md +│ └── TROUBLESHOOTING.production-issues.md +├── user/ # End-user documentation +│ ├── GUIDE.getting-started.md +│ └── GUIDE.user-workflows.md +└── archive/ # Historical documentation + └── README.legacy-systems.md +``` + +### YAML Front Matter Standards + +Every documentation file MUST include YAML front matter for machine readability: + +```yaml +--- +title: "Document Title" +description: "Brief description of the document's purpose" +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Document Author" +tags: ["docker", "testing", "containers"] +categories: ["development", "testing"] +difficulty: "intermediate" +prerequisites: ["docker", "make"] +related_docs: + - "README.deployment.md" + - "GUIDE.docker-setup.md" +dependencies: + - "docker-compose.yaml" + - "testing/scripts/" +llm_context: "high" +search_keywords: ["container", "testing", "docker", "health-check"] +--- +``` + +#### Front Matter Fields + +| Field | Required | Description | Example | +| ----------------- | -------- | -------------------------------- | ---------------------------------------- | +| `title` | ✅ | Human-readable document title | "Container Testing" | +| `description` | ✅ | Brief purpose description | "Comprehensive container testing system" | +| `template` | ✅ | Template used to create document | "TEMPLATE.documentation-standard" | +| `version` | ✅ | Document version | "1.0.0" | +| `last_updated` | ✅ | Last modification date | "2025-01-03" | +| `author` | ❌ | Document author | "Development Team" | +| `tags` | ❌ | Searchable tags | ["docker", "testing"] | +| `categories` | ❌ | Document categories | ["development", "testing"] | +| `difficulty` | ❌ | Complexity level | "beginner", "intermediate", "advanced" | +| `prerequisites` | ❌ | Required knowledge | ["docker", "make"] | +| `related_docs` | ❌ | Related documentation | ["README.deployment.md"] | +| `dependencies` | ❌ | Required files/systems | ["docker-compose.yaml"] | +| `llm_context` | ❌ | LLM relevance level | "high", "medium", "low" | +| `search_keywords` | ❌ | Search optimization | ["container", "testing"] | + +### Document Structure Standards + +Every documentation file follows our **Standard Documentation Template**: + +1. **YAML Front Matter** - Machine-readable metadata +2. **Purpose** - What this document is for +3. **When to Use** - When to reference this document +4. **How to Use** - How to apply the information +5. **What It Is** - Detailed technical content +6. **Troubleshooting** - Problem-solving section + - **FAQ** - Frequently asked questions + - **Command Reference** - Common commands + - **Lessons Learned** - Timestamped insights +7. **Related Documentation** - Links to related docs +8. **LLM Context** - Additional context for AI systems + +### Content Guidelines + +#### Writing Style + +- **Clear and Concise** - Get to the point quickly +- **Technical Accuracy** - Verify all technical details +- **Consistent Terminology** - Use our established lexicon +- **Actionable Content** - Provide specific steps, not vague guidance +- **LLM-Friendly** - Structure content for AI consumption + +#### Information Layering + +1. **Executive Summary** - High-level overview (2-3 sentences) +2. **Quick Reference** - Essential information for immediate use +3. **Detailed Content** - Comprehensive technical details +4. **Reference Material** - Commands, examples, troubleshooting +5. **LLM Context** - Additional context for AI systems + +#### Code Examples + +- **Always include working examples** +- **Use syntax highlighting** for code blocks +- **Provide context** for complex examples +- **Test examples** before including them +- **Include expected outputs** for verification + +### Template System + +#### Template Files + +Template files define the structure for specific types of documentation. They serve as: + +- **Consistency enforcers** - Ensure all docs follow the same pattern +- **Quality checklists** - Remind authors of required sections +- **Onboarding tools** - Help new contributors understand expectations +- **LLM context builders** - Provide structured context for AI systems + +#### Template Types + +1. **TEMPLATE.about** - For ABOUT documents +2. **TEMPLATE.documentation-standard** - For README documents +3. **TEMPLATE.guide** - For step-by-step guides +4. **TEMPLATE.reference** - For technical specifications +5. **TEMPLATE.troubleshooting** - For problem-solving docs +6. **TEMPLATE.architecture** - For system design docs +7. **TEMPLATE.api** - For API documentation + +#### Using Templates + +1. **Copy the appropriate template** for your document type +2. **Fill in YAML front matter** with complete metadata +3. **Fill in each section** according to the template structure +4. **Add LLM context** where appropriate +5. **Link related documentation** in the front matter +6. **Review against the template** before finalizing + +### Document Relationships + +#### Linking Strategy + +- **Front Matter Links** - Use `related_docs` for primary relationships +- **Inline Links** - Use markdown links for specific references +- **Cross-References** - Link to specific sections when relevant +- **Dependency Tracking** - Use `dependencies` field for required files + +#### Relationship Types + +1. **Prerequisites** - Documents that should be read first +2. **Related Topics** - Documents covering similar subjects +3. **Dependencies** - Documents that depend on this one +4. **References** - Documents that reference this one +5. **Troubleshooting** - Documents that help solve problems + +### LLM Optimization + +#### Context Building + +- **Rich Metadata** - Comprehensive front matter for AI understanding +- **Structured Content** - Consistent sections for predictable parsing +- **Clear Relationships** - Document links for context building +- **Search Keywords** - Optimized for AI search and retrieval + +#### AI-Friendly Features + +- **Consistent Formatting** - Predictable structure for parsing +- **Rich Descriptions** - Detailed explanations for AI understanding +- **Code Examples** - Working examples with expected outputs +- **Troubleshooting** - Comprehensive problem-solving information + +### Maintenance Standards + +#### Update Triggers + +Documentation should be updated when: + +- **New features are added** - Document new functionality +- **Bugs are fixed** - Update troubleshooting sections +- **Processes change** - Reflect new workflows +- **Issues are discovered** - Add to FAQ or lessons learned +- **Dependencies change** - Update related document links + +#### Review Process + +1. **Technical accuracy** - Verify all technical details +2. **Completeness** - Ensure all required sections are present +3. **Clarity** - Check for clear, understandable language +4. **Consistency** - Verify adherence to our standards +5. **LLM Readability** - Ensure AI-friendly structure +6. **Link Validation** - Verify all links are working + +### Quality Assurance + +#### Pre-Publication Checklist + +- [ ] YAML front matter complete and accurate +- [ ] Follows appropriate template structure +- [ ] All code examples tested and working +- [ ] Technical details verified for accuracy +- [ ] Spelling and grammar checked +- [ ] Links and references validated +- [ ] Consistent with project terminology +- [ ] LLM context optimized +- [ ] Related documents linked + +#### Post-Publication + +- **Monitor usage** - Track which sections are referenced most +- **Collect feedback** - Note areas that need clarification +- **Update regularly** - Keep content current with project evolution +- **LLM Performance** - Monitor AI system usage and effectiveness + +## Troubleshooting + +### FAQ + +**Q: Which template should I use for a new document?** +A: Check the template mapping in the File Types table. Most documents use `TEMPLATE.documentation-standard`, but specialized templates exist for specific document types. + +**Q: How detailed should the YAML front matter be?** +A: Include all required fields and as many optional fields as relevant. More metadata improves LLM context and searchability. + +**Q: What if I need to deviate from the standard template?** +A: Document the deviation in the document itself, update the front matter accordingly, and consider whether a new template is needed. + +**Q: How do I establish document relationships?** +A: Use the `related_docs` field in front matter for primary relationships and inline markdown links for specific references. + +**Q: What's the difference between tags and categories?** +A: Tags are specific keywords for search, categories are broader groupings for organization and navigation. + +**Q: How often should I update the FAQ section?** +A: Update it every time you encounter a new question or problem related to the document's topic. + +**Q: What's the purpose of the LLM context field?** +A: It helps AI systems understand the document's relevance and importance for different types of queries and tasks. + +**Q: How do I handle version-specific information?** +A: Include version information in the front matter and clearly mark version-specific sections in the content. + +**Q: What if I find an error in existing documentation?** +A: Fix it immediately, update the version number, and add an entry to the "Lessons Learned" section. + +### Command Reference + +```bash +# Create new documentation from template +cp documentation/dev/templates/TEMPLATE.documentation-standard.md documentation/new-doc.md + +# Validate YAML front matter +yamllint documentation/*.md + +# Validate Markdown syntax +markdownlint documentation/*.md + +# Check for broken links +markdown-link-check documentation/*.md + +# Generate table of contents +doctoc documentation/README.container-testing.md + +# Search documentation by tags +grep -r "tags:" documentation/ | grep "docker" + +# Find documents by category +grep -r "categories:" documentation/ | grep "testing" + +# Extract LLM context documents +grep -r "llm_context: high" documentation/ + +# Validate document relationships +grep -r "related_docs:" documentation/ + +# Check template usage +grep -r "template:" documentation/ +``` + +### Common Issues and Solutions + +| Issue | Symptoms | Solution | +| --------------------- | ---------------------------------- | ------------------------------------------------------- | +| Missing front matter | No YAML metadata at document top | Add complete YAML front matter with required fields | +| Broken links | 404 errors in related documents | Update link paths and validate with markdown-link-check | +| Template mismatch | Document doesn't follow template | Compare document structure with specified template | +| Missing relationships | No related_docs in front matter | Add related_docs field with relevant document links | +| Inconsistent tags | Tags don't follow conventions | Standardize tags using established tag vocabulary | +| Outdated metadata | Last_updated doesn't match content | Update last_updated field when making changes | + +### Debugging Steps + +1. **Check front matter**: Verify YAML syntax and required fields +2. **Validate template usage**: Compare document structure with template +3. **Test links**: Use markdown-link-check to find broken links +4. **Verify relationships**: Check that related_docs links are valid +5. **Review LLM context**: Ensure content is optimized for AI consumption +6. **Check consistency**: Verify terminology and formatting standards + +### Log Analysis + +**Front Matter Validation**: + +```bash +# Check for missing required fields +grep -L "title:" documentation/*.md +grep -L "template:" documentation/*.md + +# Validate YAML syntax +find documentation/ -name "*.md" -exec head -20 {} \; | grep -A 20 "^---" +``` + +**Link Validation**: + +```bash +# Check for broken internal links +grep -r "\[.*\](" documentation/ | grep -v "http" + +# Validate related_docs links +grep -r "related_docs:" documentation/ | cut -d: -f3 +``` + +**Template Usage**: + +```bash +# Check template compliance +grep -r "template:" documentation/ | cut -d: -f3 | sort | uniq -c +``` + +### Performance Troubleshooting + +**LLM Context Optimization**: + +- Ensure rich metadata in front matter +- Use consistent structure across documents +- Include comprehensive troubleshooting information +- Maintain up-to-date relationships + +**Search Optimization**: + +- Use descriptive tags and keywords +- Include relevant categories +- Maintain consistent terminology +- Update search_keywords regularly + +### Lessons Learned + +**2025-01-03**: Established comprehensive documentation standards with LLM optimization. Key insight: YAML front matter and structured relationships significantly improve AI system effectiveness. + +**2025-01-03**: Created template system with specialized templates for different document types. Lesson: Specialized templates improve consistency and reduce cognitive load for authors. + +**2025-01-03**: Implemented document relationship tracking through front matter. Benefit: Enables AI systems to build comprehensive context and understand document dependencies. + +**2025-01-03**: Added LLM-specific optimization features including context levels and search keywords. Advantage: Improves AI system performance and document discoverability. + +--- + +_This document is the foundation of our documentation system. Keep it updated as our standards evolve._ diff --git a/documentation/dev/QUICK-REFERENCE.md b/documentation/dev/QUICK-REFERENCE.md new file mode 100644 index 0000000..7fe6a5d --- /dev/null +++ b/documentation/dev/QUICK-REFERENCE.md @@ -0,0 +1,162 @@ +--- +title: "Developer Quick Reference" +description: "Quick reference card for common development tasks and commands" +template: "TEMPLATE.reference" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Development Team" +tags: ["quick reference", "commands", "development", "docker"] +categories: ["reference", "development"] +difficulty: "beginner" +prerequisites: ["docker", "git"] +related_docs: + - "README.developer-guide.md" + - "README.development.md" +dependencies: [] +llm_context: "medium" +search_keywords: ["quick reference", "commands", "cheat sheet", "development"] +--- + +# Developer Quick Reference + +## Environment Switching + +```bash +# Switch to development mode (hot reloading) +./scripts/switch-env.sh dev + +# Switch to production mode (optimized builds) +./scripts/switch-env.sh prod + +# Switch to base mode (standard config) +./scripts/switch-env.sh base +``` + +## Common Commands + +### Container Management + +```bash +# View container status +docker compose ps + +# View logs +docker compose logs -f +docker compose logs sirius-ui -f +docker compose logs sirius-api -f +docker compose logs sirius-engine -f + +# Restart services +docker compose restart +docker compose restart sirius-ui + +# Stop all services +docker compose down +``` + +### Development Workflow + +```bash +# Start development +./scripts/switch-env.sh dev + +# Make changes to code +# UI changes appear instantly (hot reloading) +# API/Engine changes require restart + +# Test production build +./scripts/switch-env.sh prod + +# Switch back to development +./scripts/switch-env.sh dev +``` + +### Container Access + +```bash +# Open shell in container +docker compose exec sirius-ui sh +docker compose exec sirius-api sh +docker compose exec sirius-engine sh + +# Run commands in container +docker compose exec sirius-ui npm run build +docker compose exec sirius-api go run main.go +``` + +### Health Checks + +```bash +# Check service health +curl http://localhost:3000/api/health +curl http://localhost:9001/api/v1/health +curl http://localhost:5174/health + +# Check database +docker compose exec sirius-postgres pg_isready -U postgres +``` + +### Troubleshooting + +```bash +# Clean Docker cache +docker system prune -f + +# Force rebuild +./scripts/switch-env.sh dev + +# Check what's running +docker compose exec sirius-ui ps aux + +# View detailed logs +docker compose logs sirius-ui --tail=50 +``` + +## Service Ports + +| Service | Port | Purpose | +|---------|------|---------| +| sirius-ui | 3000 | Web interface | +| sirius-api | 9001 | REST API | +| sirius-engine | 5174 | Engine interface | +| sirius-engine | 50051 | gRPC communication | +| sirius-postgres | 5432 | Database | +| sirius-valkey | 6379 | Cache | +| sirius-rabbitmq | 5672 | Message queue | +| sirius-rabbitmq | 15672 | Management UI | + +## File Locations + +| Component | Location | Purpose | +|-----------|----------|---------| +| UI Source | `sirius-ui/src/` | React components and pages | +| API Source | `sirius-api/` | Go REST API code | +| Engine Source | `sirius-engine/` | Multi-service engine code | +| Docker Config | `docker-compose*.yaml` | Environment configurations | +| Switch Script | `scripts/switch-env.sh` | Environment switching | + +## Environment Differences + +| Feature | Development | Production | +|---------|-------------|------------| +| UI Server | `npm run dev` | `npm start` | +| Database | SQLite | PostgreSQL | +| Hot Reloading | ✅ Yes | ❌ No | +| Volume Mounts | ✅ Yes | ❌ No | +| Debug Logging | ✅ Yes | ❌ No | +| Optimizations | ❌ No | ✅ Yes | + +## Quick Troubleshooting + +| Problem | Solution | +|---------|----------| +| Wrong environment running | `./scripts/switch-env.sh dev` | +| Hot reloading not working | Check you're in dev mode | +| Services not starting | Check logs: `docker compose logs` | +| Port conflicts | `lsof -i :3000` then kill process | +| Database issues | `docker compose restart sirius-postgres` | +| Cache issues | `docker system prune -f` | + +--- + +_For detailed information, see [README.developer-guide.md](README.developer-guide.md)._ diff --git a/documentation/dev/QUICKREF.template-types.md b/documentation/dev/QUICKREF.template-types.md new file mode 100644 index 0000000..daa3e5b --- /dev/null +++ b/documentation/dev/QUICKREF.template-types.md @@ -0,0 +1,290 @@ +--- +title: "Template System Type Reference" +description: "Quick reference for template types and module configurations" +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-10-25" +author: "Sirius Platform Team" +tags: ["templates", "types", "reference", "quick-guide"] +categories: ["reference", "templates"] +difficulty: "beginner" +related_docs: + - "architecture/README.template-ui-integration.md" + - "architecture/README.agent-system.md" +llm_context: "high" +search_keywords: ["template", "types", "config", "module", "reference"] +--- + +# Template System Type Reference + +Quick reference guide for template types, module configurations, and validation rules. + +## Detection Step Types + +| Type | Module | Config Required | Platforms | +| -------------- | -------------------- | ---------------------- | --------- | +| `file-hash` | FileHashModule | path, hash | All | +| `file-content` | FileContentModule | path, patterns | All | +| `version-cmd` | CommandVersionModule | command, version_regex | All | + +## Module Configurations + +### file-hash + +```yaml +type: file-hash +platforms: [linux, darwin, windows] +weight: 1.0 +config: + path: "/etc/passwd" # REQUIRED: Absolute path + hash: "sha256:abc123..." # REQUIRED: Hash with prefix + algorithm: "sha256" # OPTIONAL: Algorithm +``` + +**Hash Formats**: + +- SHA256: `sha256:` + 64 hex chars +- SHA1: `sha1:` + 40 hex chars +- MD5: `md5:` + 32 hex chars +- SHA512: `sha512:` + 128 hex chars + +--- + +### file-content + +```yaml +type: file-content +platforms: [linux, darwin] +weight: 0.8 +config: + path: "/etc/apache2/apache2.conf" # REQUIRED: File to search + patterns: # REQUIRED: Regex patterns + - "ServerTokens.*Full" + - "ServerSignature.*On" +``` + +**Pattern Notes**: + +- Go regex (RE2 syntax) +- Case-sensitive by default +- No lookahead/lookbehind support +- Array required (even for single pattern) + +--- + +### version-cmd + +```yaml +type: version-cmd +platforms: [linux, darwin] +weight: 1.0 +config: + command: "httpd -v" # REQUIRED: Shell command + version_regex: "Apache/(\\d+\\.\\d+)" # REQUIRED: Version capture + vulnerable_versions: # OPTIONAL: Constraints + - "< 2.4.52" + - ">= 2.2.0, < 2.2.34" + expected_exit_code: 0 # OPTIONAL: Exit code +``` + +**Version Operators**: + +- `<`, `<=`, `>`, `>=`, `=`, `!=` +- Combine with comma: `>= 2.0, < 3.0` + +## Platform Values + +```yaml +platforms: [linux] # Linux only +platforms: [darwin] # macOS only +platforms: [windows] # Windows only +platforms: [linux, darwin] # Unix-like systems +platforms: [] # All platforms (default) +``` + +## Severity Values + +```yaml +severity: critical # Highest priority +severity: high +severity: medium +severity: low +severity: info # Lowest priority +``` + +## Detection Logic + +```yaml +detection: + logic: all # AND - All steps must match + logic: any # OR - At least one step must match +``` + +## Complete Template Example + +```yaml +id: apache-outdated +info: + name: Outdated Apache HTTP Server + author: security-team + severity: high + description: Detects Apache versions vulnerable to known CVEs + references: + - https://nvd.nist.gov/vuln/detail/CVE-2021-44228 + cve: + - CVE-2021-44228 + tags: + - apache + - web-server + - cve + version: "1.0" + +detection: + logic: all + steps: + - type: version-cmd + platforms: [linux, darwin] + weight: 1.0 + config: + command: "httpd -v" + version_regex: "Apache/(\\d+\\.\\d+\\.\\d+)" + vulnerable_versions: + - "< 2.4.52" + + - type: file-content + platforms: [linux, darwin] + weight: 0.8 + config: + path: "/etc/apache2/apache2.conf" + patterns: + - "ServerTokens.*Full" +``` + +## TypeScript Interfaces + +```typescript +// Detection step +interface DetectionStep { + type: "file-hash" | "file-content" | "version-cmd"; + platforms?: ("linux" | "darwin" | "windows")[]; + weight?: number; // 0.0 to 1.0 + config: FileHashConfig | FileContentConfig | CommandVersionConfig; +} + +// File hash config +interface FileHashConfig { + path: string; + hash: string; + algorithm?: "sha256" | "sha1" | "md5" | "sha512"; +} + +// File content config +interface FileContentConfig { + path: string; + patterns: string[]; +} + +// Version command config +interface CommandVersionConfig { + command: string; + version_regex: string; + vulnerable_versions?: string[]; + expected_exit_code?: number; +} + +// Template info +interface TemplateInfo { + name: string; + author: string; + severity: "critical" | "high" | "medium" | "low" | "info"; + description: string; + references?: string[]; + cve?: string[]; + tags?: string[]; + version?: string; +} + +// Detection config +interface DetectionConfig { + logic?: "all" | "any"; // defaults to "all" + steps: DetectionStep[]; +} + +// Complete template +interface TemplateContent { + id: string; + info: TemplateInfo; + detection: DetectionConfig; +} +``` + +## Validation Rules + +### Template ID + +- Format: `^[a-z0-9-]+$` +- Length: 3-50 characters +- Cannot start/end with dash +- Cannot be reserved keyword (new, create, edit, delete, standard, custom) + +### CVE Format + +- Pattern: `^CVE-\d{4}-\d{4,}$` +- Example: `CVE-2021-44228` + +### File Paths + +- Must be absolute +- Unix: Starts with `/` +- Windows: Starts with drive letter (e.g., `C:\`) + +### Regex Patterns + +- Use Go RE2 syntax +- No backreferences +- No lookahead/lookbehind +- Named groups: `(?Ppattern)` + +### Weight Values + +- Range: 0.0 to 1.0 +- Default: 1.0 +- Affects confidence calculation + +## Common Errors + +| Error | Cause | Fix | +| ------------------------ | ------------------ | -------------------------- | +| "unknown module type" | Wrong type name | Use dashes not underscores | +| "missing required field" | Config incomplete | Check module requirements | +| "invalid regex" | Bad pattern syntax | Test with Go regex tester | +| "template not found" | Wrong ID | Check exact ID in library | + +## Quick Tips + +✅ **DO**: + +- Use lowercase IDs with dashes +- Test regex patterns before submission +- Specify platforms when not all apply +- Include CVE references when available +- Add meaningful descriptions + +❌ **DON'T**: + +- Use underscores in type names +- Forget algorithm prefix in hashes +- Use single string for patterns (must be array) +- Use JavaScript regex features (Go RE2 only) +- Create IDs with spaces or special chars + +## Resources + +- Full guide: [README.template-ui-integration.md](architecture/README.template-ui-integration.md) +- Agent system: [README.agent-system.md](architecture/README.agent-system.md) +- Module code: `app-agent/internal/modules/` + +--- + +**Quick Reference Version**: 1.0.0 +**Last Updated**: October 25, 2025 diff --git a/documentation/dev/README.developer-guide.md b/documentation/dev/README.developer-guide.md new file mode 100644 index 0000000..41a0e51 --- /dev/null +++ b/documentation/dev/README.developer-guide.md @@ -0,0 +1,582 @@ +--- +title: "Sirius Developer Guide" +description: "Complete guide for developers working on Sirius, including environment setup, development workflows, and best practices." +template: "TEMPLATE.guide" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Development Team" +tags: ["development", "guide", "workflow", "docker", "environment"] +categories: ["development", "guide"] +difficulty: "beginner" +prerequisites: ["docker", "git", "nodejs", "go"] +related_docs: + - "README.development.md" + - "README.docker-architecture.md" + - "README.container-testing.md" +dependencies: + - "scripts/switch-env.sh" + - "docker-compose.yaml" + - "docker-compose.dev.yaml" + - "docker-compose.prod.yaml" +llm_context: "high" +search_keywords: + [ + "developer guide", + "development workflow", + "environment switching", + "docker development", + "hot reloading", + "development setup", + ] +--- + +# Sirius Developer Guide + +## Overview + +This guide provides everything you need to know to develop effectively on the Sirius project. Whether you're working on the UI, API, engine, or any other component, this guide will help you get up and running quickly. + +## Quick Start + +```bash +# Clone the repository +git clone https://github.com/SiriusScan/Sirius.git +cd Sirius + +# Start development environment +./scripts/switch-env.sh dev + +# Access the application +open http://localhost:3000 +``` + +## Development Environments + +Sirius supports three distinct development environments, each optimized for different use cases: + +### 🚀 Development Mode (Recommended) + +**Best for: UI/API development, testing, most development tasks** + +```bash +./scripts/switch-env.sh dev +``` + +**Features:** + +- Hot reloading for instant code changes +- Volume mounts for live code updates +- Development-optimized builds +- SQLite database for faster development +- Debug logging enabled + +**What's Running:** + +- UI: `npm run dev` (Next.js development server) +- API: Go development mode with live reloading +- Engine: Development mode with volume mounts + +### 🏭 Production Mode + +**Best for: Testing production builds, performance testing, pre-deployment validation** + +```bash +./scripts/switch-env.sh prod +``` + +**Features:** + +- Optimized production builds +- PostgreSQL database +- Production authentication +- Performance optimizations +- Security hardening + +**What's Running:** + +- UI: `npm start` (Next.js production server) +- API: Pre-built Go binary +- Engine: Production-optimized runtime + +### ⚙️ Base Mode + +**Best for: Standard operations, CI/CD, basic testing** + +```bash +./scripts/switch-env.sh base +``` + +**Features:** + +- Default configuration +- Balanced performance +- Standard resource allocation +- Core functionality only + +## Environment Switching + +The `scripts/switch-env.sh` script handles seamless switching between environments: + +```bash +# Switch to development +./scripts/switch-env.sh dev + +# Switch to production +./scripts/switch-env.sh prod + +# Switch to base +./scripts/switch-env.sh base +``` + +**What the script does:** + +1. Stops all running containers +2. Removes old images to prevent cache conflicts +3. Builds the appropriate environment with correct build targets +4. Starts all services +5. Shows container status and access URLs + +## Development Workflow + +### Daily Development + +1. **Start your day:** + + ```bash + ./scripts/switch-env.sh dev + ``` + +2. **Make your changes:** + + - Edit UI code in `sirius-ui/src/` + - Edit API code in `sirius-api/` + - Edit engine code in `sirius-engine/` + +3. **See changes instantly:** + + - UI changes appear immediately (hot reloading) + - API changes require container restart + - Engine changes require container restart + +4. **Test your changes:** + + ```bash + # Check container status + docker compose ps + + # View logs + docker compose logs sirius-ui + docker compose logs sirius-api + ``` + +### Testing Production Builds + +1. **Switch to production mode:** + + ```bash + ./scripts/switch-env.sh prod + ``` + +2. **Test your changes:** + + - Verify UI renders correctly + - Test API endpoints + - Check performance characteristics + +3. **Switch back to development:** + ```bash + ./scripts/switch-env.sh dev + ``` + +### Working with Different Components + +#### Frontend Development (UI) + +```bash +# Start development mode +./scripts/switch-env.sh dev + +# Make changes to React components +# Changes appear instantly in browser + +# Test production build +./scripts/switch-env.sh prod +``` + +#### Backend Development (API) + +```bash +# Start development mode +./scripts/switch-env.sh dev + +# Make changes to Go code +# Restart API container to see changes +docker compose restart sirius-api + +# Check API logs +docker compose logs sirius-api -f +``` + +#### Engine Development + +```bash +# Start development mode +./scripts/switch-env.sh dev + +# Make changes to engine code +# Restart engine container to see changes +docker compose restart sirius-engine + +# Check engine logs +docker compose logs sirius-engine -f +``` + +## Project Structure + +``` +Sirius/ +├── sirius-ui/ # Next.js frontend +│ ├── src/ # React components and pages +│ ├── Dockerfile # Multi-stage build (dev/prod) +│ ├── start-dev.sh # Development startup script +│ └── start-prod.sh # Production startup script +├── sirius-api/ # Go REST API +│ ├── cmd/ # API entry point +│ ├── internal/ # Internal API code +│ └── Dockerfile # Multi-stage build (dev/runner) +├── sirius-engine/ # Multi-service engine +│ ├── cmd/ # Engine entry point +│ ├── internal/ # Internal engine code +│ └── Dockerfile # Multi-stage build (dev/runtime) +├── docker-compose.yaml # Base configuration +├── docker-compose.dev.yaml # Development overrides +├── docker-compose.prod.yaml # Production overrides +└── scripts/ + └── switch-env.sh # Environment switching script +``` + +## Docker Architecture + +### Multi-Stage Builds + +Each service uses multi-stage Dockerfiles to optimize for different environments: + +**sirius-ui:** + +- `development`: Full dev environment with hot reloading +- `production`: Optimized production build + +**sirius-api:** + +- `development`: Go development with live reloading +- `runner`: Pre-built Go binary for production + +**sirius-engine:** + +- `development`: Full development environment +- `runtime`: Production-optimized runtime + +### Image Tagging Strategy + +- **Development**: `sirius-sirius-ui:dev` +- **Production**: `sirius-sirius-ui:prod` +- **Base**: `sirius-sirius-ui:latest` + +This prevents Docker cache conflicts when switching environments. + +## CI/CD Integration + +### Pre-commit Validation + +**Purpose**: Fast validation to catch obvious issues before commit + +**Duration**: ~30 seconds + +**What's Tested**: + +- Docker Compose configuration validation +- Documentation linting +- Basic syntax checks +- Code formatting + +**Commands**: + +```bash +# Pre-commit validation (automatic) +git commit # Runs quick validation automatically + +# Manual validation +cd testing/container-testing +make build-all # Validate all Docker Compose configs +make lint-docs-quick # Quick documentation checks +``` + +### CI/CD Pipeline + +**Purpose**: Comprehensive testing of all changes + +**Duration**: ~5-10 minutes + +**What's Tested**: + +- Docker container builds (all services) +- Service health checks +- Integration testing +- Cross-service communication +- Production build validation + +**Triggers**: + +- Pull requests to main branch +- Pushes to main branch +- Hotfix pushes + +### Local Testing + +**Purpose**: Manual testing during development + +**Available Commands**: + +```bash +# Full test suite +cd testing/container-testing +make test-all + +# Individual tests +make test-build # Test Docker builds +make test-health # Test service health +make test-integration # Test integration + +# Quick validation +make build-all # Validate configs +make lint-docs-quick # Quick docs check +``` + +### Testing Strategy + +| Scenario | Pre-commit | CI/CD | Local Testing | +| ----------------------- | ------------------- | --------------- | --------------- | +| **Feature Development** | ✅ Quick validation | ❌ No | ✅ Full testing | +| **Pull Request** | ✅ Quick validation | ✅ Full testing | ✅ Full testing | +| **Main Branch** | ✅ Quick validation | ✅ Full testing | ✅ Full testing | +| **Documentation** | ✅ Quick validation | ❌ No | ✅ Full testing | + +## Common Tasks + +### Viewing Logs + +```bash +# All services +docker compose logs -f + +# Specific service +docker compose logs sirius-ui -f +docker compose logs sirius-api -f +docker compose logs sirius-engine -f +``` + +### Accessing Containers + +```bash +# Open shell in container +docker compose exec sirius-ui sh +docker compose exec sirius-api sh +docker compose exec sirius-engine sh +``` + +### Restarting Services + +```bash +# Restart specific service +docker compose restart sirius-ui + +# Restart all services +docker compose restart +``` + +### Checking Service Health + +```bash +# View container status +docker compose ps + +# Check health endpoints +curl http://localhost:3000/api/health +curl http://localhost:9001/api/v1/health +curl http://localhost:5174/health +``` + +### Database Access + +```bash +# Development (SQLite) +docker compose exec sirius-ui ls -la /app/dev.db + +# Production (PostgreSQL) +docker compose exec sirius-postgres psql -U postgres -d sirius +``` + +## Troubleshooting + +### Environment Switching Issues + +**Problem**: Wrong environment running despite switching +**Solution**: The script automatically handles this, but if issues persist: + +```bash +# Force clean rebuild +docker system prune -f +./scripts/switch-env.sh dev +``` + +### Hot Reloading Not Working + +**Problem**: UI changes not appearing instantly +**Solution**: Ensure you're in development mode: + +```bash +./scripts/switch-env.sh dev +# Check it's running: docker compose exec sirius-ui ps aux +``` + +### Services Not Starting + +**Problem**: Containers failing to start +**Solution**: Check logs and restart: + +```bash +docker compose logs sirius-ui +docker compose restart sirius-ui +``` + +### Port Conflicts + +**Problem**: Port already in use +**Solution**: Stop conflicting services: + +```bash +# Check what's using the port +lsof -i :3000 +lsof -i :9001 + +# Stop conflicting services +sudo kill -9 +``` + +### Database Connection Issues + +**Problem**: API can't connect to database +**Solution**: Check database health: + +```bash +# Check database status +docker compose ps sirius-postgres + +# Check database logs +docker compose logs sirius-postgres + +# Restart database +docker compose restart sirius-postgres +``` + +## Best Practices + +### Development Workflow + +1. **Always start with development mode** for new features +2. **Test in production mode** before committing +3. **Use hot reloading** for UI development +4. **Check logs regularly** to catch issues early +5. **Switch environments** to test different scenarios + +### Code Organization + +1. **Keep components focused** and single-purpose +2. **Use TypeScript** for better type safety +3. **Follow naming conventions** consistently +4. **Write tests** for critical functionality +5. **Document complex logic** with comments + +### Docker Usage + +1. **Use the switch script** instead of manual docker commands +2. **Don't edit Docker Compose files** directly unless necessary +3. **Clean up unused images** regularly +4. **Monitor resource usage** during development +5. **Test in multiple environments** before deploying + +### Git Workflow + +1. **Create feature branches** for new work +2. **Test thoroughly** before merging +3. **Write descriptive commit messages** +4. **Keep commits focused** and atomic +5. **Use pull requests** for code review + +## Advanced Usage + +### Custom Environment Variables + +Create a `.env.local` file for custom environment variables: + +```bash +# .env.local +NODE_ENV=development +API_URL=http://localhost:9001 +DEBUG=true +``` + +### Volume Mounts for Live Development + +For advanced development scenarios, you can mount local directories: + +```bash +# Edit docker-compose.dev.yaml to add volume mounts +volumes: + - ./sirius-ui/src:/app/src + - ./sirius-api:/app +``` + +### Debugging + +Enable debug mode for more verbose logging: + +```bash +# Set debug environment variable +export DEBUG=true +./scripts/switch-env.sh dev +``` + +### Performance Testing + +Use production mode for performance testing: + +```bash +./scripts/switch-env.sh prod +# Run your performance tests +``` + +## Getting Help + +### Documentation + +- [Docker Architecture](README.docker-architecture.md) - Detailed Docker setup +- [Development Setup](README.development.md) - Legacy development guide +- [Container Testing](README.container-testing.md) - Testing procedures + +### Common Issues + +- Check the troubleshooting section above +- Review container logs for error messages +- Ensure all prerequisites are installed +- Verify Docker is running properly + +### Support + +- Create an issue on GitHub for bugs +- Use discussions for questions +- Check existing issues before creating new ones + +--- + +_This guide follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](ABOUT.documentation.md)._ diff --git a/documentation/dev/README.development.md b/documentation/dev/README.development.md new file mode 100644 index 0000000..f20c931 --- /dev/null +++ b/documentation/dev/README.development.md @@ -0,0 +1,260 @@ +--- +title: "Sirius Development Setup" +description: "Comprehensive guide for setting up and using the Sirius development environment, including standard and extended development modes with local repository integration." +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2026-04-07" +author: "Development Team" +tags: ["development", "setup", "docker", "workflow"] +categories: ["development", "setup"] +difficulty: "intermediate" +prerequisites: ["docker", "git"] +related_docs: + - "README.container-testing.md" + - "ABOUT.documentation.md" +dependencies: + - "docker-compose.yaml" + - "scripts/dev-setup.sh" +llm_context: "medium" +search_keywords: + ["development setup", "docker compose", "local development", "workflow"] +--- + +# Sirius Development Setup + +## Quick Start + +**New in v1.0.0**: Use the improved environment switching system for easier development. + +```bash +# Generate/merge required .env values once (installer-first) +docker compose -f docker-compose.installer.yaml run --rm sirius-installer + +# Modern development workflow (recommended) +./scripts/switch-env.sh dev + +# Legacy development (uses built-in repositories) +./scripts/dev-setup.sh start + +# Extended development (with local repository mounts) +./scripts/dev-setup.sh init # Create local overrides +./scripts/dev-setup.sh start-extended # Start with local mounts +``` + +> **Note**: For the complete developer experience, see [README.developer-guide.md](README.developer-guide.md) for comprehensive development workflows and best practices. + +## Development Modes + +### 🎯 Standard Development + +**Best for: UI/API development, testing, most development tasks** + +```bash +./scripts/dev-setup.sh start +``` + +- Uses built-in repositories from Docker images +- No local repository setup required +- All services start with `go run` in development mode +- Live reloading for UI changes +- Uses secrets generated by `docker-compose.installer.yaml` (`.env`) for service auth/DB consistency + +### 🔧 Extended Development + +**Best for: Working on scanner, terminal, or agent code** + +```bash +# 1. Set up local repositories (one-time) +mkdir -p ../minor-projects && cd ../minor-projects +git clone https://github.com/SiriusScan/app-scanner.git +git clone https://github.com/SiriusScan/app-terminal.git +git clone https://github.com/SiriusScan/app-agent.git +cd ../Sirius + +# 2. Initialize local overrides +./scripts/dev-setup.sh init + +# 3. Edit docker-compose.local.yaml (uncomment what you need) +nano docker-compose.local.yaml + +# 4. Start extended development +./scripts/dev-setup.sh start-extended +``` + +**Hot reloading in extended mode (engine services):** + +Each minor-project ships its own `.air.toml` (`app-agent/.air.toml`, `app-terminal/.air.toml`, `app-scanner/.air.toml`). When `GO_ENV=development` (the default for `docker-compose.dev.yaml`), `start-enhanced.sh` checks for `.air.toml` in the bind-mounted source and uses [Air](https://github.com/air-verse/air) for live rebuilds; if `.air.toml` is absent (or `air` is missing from the image) it falls back to plain `go run`. The matrix: + +| Service | Bind mount path in container | Live-reload tool | Entry point | +| --- | --- | --- | --- | +| `app-agent` | `/app-agent` | `air` | `cmd/server/main.go` | +| `app-terminal` | `/app-terminal` | `air` | `cmd/main.go` | +| `app-scanner` | `/app-scanner` | `air` (`CGO_ENABLED=1`) | `main.go` | + +Notes: + +- Changes to bind-mounted source are picked up automatically by Air; you should see a rebuild log line in `docker logs sirius-engine` within ~1s of saving. +- `app-scanner` requires CGO and `libpcap`; the container ships both, so the in-container Air build works out of the box. +- The orphan `sirius-engine/.air.toml` that previously lived in the engine image was removed in the April 2026 dev-mode overhaul; per-service `.air.toml` is the only supported configuration. +- Changes are not tracked by the main Sirius repository (the bind mounts are git-ignored). + +**When Air isn't enough — hot-swap from local source:** + +Sometimes you want to validate a change against a *production-mode* engine without waiting for a full container rebuild (e.g. you're testing a binary against `docker-compose.prod.yaml`, or you want to confirm a release-style build before bumping a pin). Use the root `Makefile` targets: + +```bash +make engine-mode # show whether the running engine is dev or prod +make agent-hot-swap-from-local +make terminal-hot-swap-from-local +make scanner-hot-swap-from-local # CGO; fails cleanly if host lacks libpcap +make engine-rebuild-from-local # all three, best-effort +``` + +What they do: cross-compile the binary on the host (`linux/$(uname -m)` by default; override with `HOST_GOARCH=amd64`), `docker cp` it into the engine container at the production binary path (e.g. `/app-agent-src/server`), and restart the engine. + +Important guard rails: + +- **The targets refuse to run in dev mode** (`GO_ENV=development`). In dev, `/app-terminal` and `/app-scanner` are bind-mounted, so `docker cp` would write through to your host repo; and Air owns the live binary at `./tmp/main`, so the swapped production-path binary wouldn't even be executed. The right loop in dev is *edit source → Air rebuilds*. Override with `FORCE_HOT_SWAP=1` only if you know what you want. +- **Scanner cross-compile may fail on macOS hosts**. The scanner uses `cgo` + `libpcap`; the macOS toolchain can't satisfy linux cgo headers. The target prints the actual `cgo` error and a copy-pasteable in-container build command. This is expected and not a Makefile bug. +- **These targets are an inner-loop convenience, not a release path.** Once the change is good, push it to the relevant minor-project and bump the engine pin per [README.engine-component-pinning.md](architecture/README.engine-component-pinning.md). The CI pipeline is the single source of truth for shipped images. + +## File Structure + +``` +Sirius/ +├── docker-compose.yaml # Base configuration +├── docker-compose.override.yaml # 🔒 Committed: Safe development defaults +├── docker-compose.local.example.yaml # 🔒 Committed: Template for local overrides +├── docker-compose.local.yaml # 🚫 Git-ignored: Your personal overrides +└── scripts/dev-setup.sh # 🔒 Committed: Development helper +``` + +## Safety Features + +### 🛡️ Prevents Accidental Commits + +- `docker-compose.local.yaml` is git-ignored +- CI/CD validates that volume mounts stay commented in `docker-compose.override.yaml` +- Pre-commit hook auto-fixes uncommented volume mounts + +### 🔧 Developer-Friendly + +- Easy setup with `./scripts/dev-setup.sh init` +- Template file shows all available options +- Helper script for common development tasks + +## Available Commands + +```bash +./scripts/dev-setup.sh init # Create local overrides from template +./scripts/dev-setup.sh start # Standard development mode +./scripts/dev-setup.sh start-extended # Extended development with local repos +./scripts/dev-setup.sh stop # Stop all services +./scripts/dev-setup.sh status # Show container status +./scripts/dev-setup.sh logs [service] # Show logs +./scripts/dev-setup.sh shell # Open shell in container +./scripts/dev-setup.sh clean # Clean containers and volumes +``` + +## Troubleshooting + +### Permission denied (Linux, Docker dev bind mounts) + +`docker-compose.dev.yaml` runs **sirius-ui** and **sirius-api** as UID/GID **1001** (matching the image users). If you cloned the repo as **root** or files under `sirius-ui/` / `sirius-api/` are root-owned, processes inside the container get **EACCES** when Next.js or `go build` writes into mounted directories. + +**Preferred:** fix ownership on the host (adjust path to your checkout): + +```bash +sudo chown -R 1001:1001 sirius-ui sirius-api +# If you mount minor-projects into those containers: +sudo chown -R 1001:1001 ../minor-projects/go-api ../minor-projects/app-system-monitor ../minor-projects/app-administrator +``` + +**Quick dev-only workaround:** in `.env` set: + +```bash +SIRIUS_DEV_CONTAINER_UID=0 +SIRIUS_DEV_CONTAINER_GID=0 +``` + +Then recreate containers: `docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up --build -d --force-recreate`. This runs those two services as root inside the container (acceptable for a local lab, not for production images). + +### Volume Mounts Not Working + +```bash +# Check if local file exists +ls -la docker-compose.local.yaml + +# Check if repositories exist +ls -la ../minor-projects/ + +# Verify you're using start-extended +./scripts/dev-setup.sh start-extended +``` + +### Git Commits Being Rejected + +Your CI/CD is preventing commits with uncommented volume mounts: + +```bash +# Fix automatically +git add docker-compose.override.yaml +git commit # Pre-commit hook will fix and re-stage + +# Or fix manually - comment out volume mounts with # +nano docker-compose.override.yaml +``` + +### Services Not Starting + +```bash +# Ensure installer-generated .env exists and is up to date +docker compose -f docker-compose.installer.yaml run --rm sirius-installer + +# Check container status +./scripts/dev-setup.sh status + +# View logs for specific service +./scripts/dev-setup.sh logs sirius-engine + +# Restart clean +./scripts/dev-setup.sh stop +./scripts/dev-setup.sh clean +./scripts/dev-setup.sh start +``` + +## Best Practices + +1. **Use standard mode** for most development work +2. **Only use extended mode** when working on engine/scanner/terminal/agent code +3. **Never commit** `docker-compose.local.yaml` +4. **Always test** your changes work in standard mode before committing +5. **Keep local overrides minimal** - only uncomment what you're actively developing + +## Migration from Old Setup + +If you were previously editing `docker-compose.override.yaml` directly: + +```bash +# 1. Reset override file to clean state +git checkout docker-compose.override.yaml + +# 2. Set up new local overrides +./scripts/dev-setup.sh init + +# 3. Move your customizations to docker-compose.local.yaml +nano docker-compose.local.yaml + +# 4. Start with new system +./scripts/dev-setup.sh start-extended +``` + +## CI/CD Integration + +The repository includes automatic validation: + +- **GitHub Actions**: Validates docker-compose files on PRs +- **Pre-commit Hook**: Auto-fixes volume mount issues +- **Git Ignore**: Prevents local files from being committed + +This ensures the repository stays clean and deployments are predictable. diff --git a/documentation/dev/ai-rules/ABOUT.ai-rules.md b/documentation/dev/ai-rules/ABOUT.ai-rules.md new file mode 100644 index 0000000..f6f07da --- /dev/null +++ b/documentation/dev/ai-rules/ABOUT.ai-rules.md @@ -0,0 +1,105 @@ +--- +title: "About AI Rules" +description: "Documentation for AI/LLM interaction rules and guidelines within the Sirius project, including cursor rules and context shaping strategies." +template: "TEMPLATE.about" +version: "1.0.0" +last_updated: "2025-01-03" +author: "AI Assistant" +tags: ["ai", "llm", "rules", "cursor", "context"] +categories: ["project-management", "development"] +difficulty: "intermediate" +prerequisites: ["ABOUT.documentation.md"] +related_docs: + - "ABOUT.documentation.md" + - "README.documentation-index.md" +dependencies: [] +llm_context: "high" +search_keywords: + ["ai rules", "llm context", "cursor rules", "documentation rules"] +--- + +# About AI Rules + +## Purpose + +This document explains how AI/LLM interaction rules and guidelines work within the Sirius project. These rules help shape how Large Language Models interact with our codebase and documentation system. + +## When to Use + +- **Setting up AI development environment** - Understanding how AI tools should interact with our project +- **Creating new AI rules** - When adding new guidelines for AI interaction +- **Troubleshooting AI context issues** - When AI tools aren't providing the right context +- **Optimizing AI performance** - When improving how AI systems understand our project + +## How to Use + +1. **Read the cursor rules** to understand current AI interaction guidelines +2. **Check the documentation system** for how AI should consume our docs +3. **Follow the context shaping strategies** for optimal AI performance +4. **Update rules as needed** when project structure changes + +## What It Is + +### Cursor Rules Integration + +Our project uses cursor rules to guide AI interactions: + +- **Code understanding** - How AI should interpret our codebase +- **Documentation consumption** - How AI should use our documentation system +- **Context building** - How AI should build comprehensive project context +- **Best practices** - Guidelines for AI-assisted development + +### AI Context Optimization + +Our documentation system is designed for optimal AI consumption: + +- **YAML front matter** - Machine-readable metadata +- **Structured relationships** - Clear document connections +- **LLM context levels** - Prioritized information for AI +- **Search keywords** - Optimized for AI discovery + +### Integration Points + +- **Cursor IDE** - Primary AI development environment +- **Documentation system** - AI context source +- **Codebase structure** - AI understanding target +- **Development workflows** - AI assistance scope + +## Troubleshooting + +### FAQ + +**Q: How do I update cursor rules for new documentation?** +A: Update the cursor rules file to include new documentation patterns and relationships. + +**Q: Why isn't AI understanding our documentation structure?** +A: Check that YAML front matter is complete and relationships are properly defined. + +**Q: How do I optimize AI context for specific tasks?** +A: Use the LLM context levels and search keywords in documentation front matter. + +### Command Reference + +| Command | Purpose | Example | +| ----------------------------- | ------------------------------ | -------------------------------------------- | +| `grep -r "llm_context: high"` | Find high-priority docs for AI | `grep -r "llm_context: high" documentation/` | +| `grep -r "template:"` | Check template usage | `grep -r "template:" documentation/` | +| `grep -r "related_docs:"` | Find document relationships | `grep -r "related_docs:" documentation/` | + +### Common Issues + +| Issue | Symptoms | Solution | +| ----------------------------- | ------------------------ | -------------------------------------------- | +| AI not finding relevant docs | Poor context building | Check LLM context levels and search keywords | +| AI misunderstanding structure | Incorrect template usage | Verify template compliance and relationships | +| AI missing dependencies | Broken document links | Validate related_docs and dependencies | + +## Lessons Learned + +### [Date] - [What was learned] + +[Description of AI rules lesson learned and how it improved the system] + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/ai-rules/README.ai-identities.md b/documentation/dev/ai-rules/README.ai-identities.md new file mode 100644 index 0000000..68b65d0 --- /dev/null +++ b/documentation/dev/ai-rules/README.ai-identities.md @@ -0,0 +1,1021 @@ +--- +title: "Agent Identity System" +description: "Comprehensive guide to the agent identity generation system for AI context shaping" +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-10-25" +author: "Sirius Team" +tags: ["ai", "agents", "context", "documentation", "automation"] +categories: ["development", "ai-rules"] +difficulty: "intermediate" +prerequisites: + - "TypeScript/Node.js knowledge" + - "Understanding of YAML and Markdown" + - "Familiarity with project structure" +related_docs: + - "ABOUT.documentation.md" + - "README.development.md" + - "cursor_rules.mdc" +dependencies: + - "scripts/agent-identities/" + - ".cursor/agents/" +llm_context: "high" +search_keywords: + ["agent", "identity", "ai", "context", "generation", "templates", "cursor"] +--- + +# 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 (~1200-1500 lines) that enables confident fresh conversations by providing essential role context. + +### Why Agent Identities? + +**Problem:** Long-running AI conversations accumulate context but become unwieldy over time. Starting fresh means losing valuable project-specific knowledge. + +**Solution:** Comprehensive agent identities that provide: + +- Role-specific project context +- Technology stack and architecture details +- Development workflows and best practices +- Common tasks and troubleshooting guides +- Integration with broader system + +### Key Benefits + +- **Fresh Conversations:** Start new AI sessions with full context +- **Role-Specific Focus:** Targeted expertise for specific domains +- **Consistency:** Validated, standardized role definitions +- **Always Current:** Auto-generated sections stay synchronized with code +- **Efficient Context:** Optimized for LLM context windows + +## System Overview + +### Architecture + +The system combines **manual narrative** (philosophy, best practices) with **auto-generated sections** (file structure, ports, dependencies, configurations) to create comprehensive agent identities. + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Agent Identity System │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌─────────────────┐ │ +│ │ Template │──────▶│ Generation │ │ +│ │ (Manual) │ │ Engine │ │ +│ └──────────────┘ └────────┬────────┘ │ +│ │ │ +│ ┌──────────────────────────────▼────────────────────────┐ │ +│ │ Data Extractors │ │ +│ │ • File Structure • Ports • Dependencies │ │ +│ │ • Configs • Docs • Code Patterns │ │ +│ └──────────────────────────────┬────────────────────────┘ │ +│ │ │ +│ ┌──────────────────────────────▼────────────────────────┐ │ +│ │ Generated Agent Identity │ │ +│ │ (1200-1500 lines) │ │ +│ └──────────────────────────────┬────────────────────────┘ │ +│ │ │ +│ ┌──────────────────────────────▼────────────────────────┐ │ +│ │ Validation System │ │ +│ │ • YAML Metadata • Content • Sync Check │ │ +│ │ • File Paths • Line Count • Standards │ │ +│ └───────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Components + +#### 1. Templates (`.cursor/agents/templates/`) + +Manual narrative sections that define: + +- Role summary and philosophy +- Best practices and wisdom +- Development approaches +- Key responsibilities + +#### 2. Configuration (`.cursor/agents/config/`) + +YAML files that specify: + +- Product paths and metadata +- Generation settings +- Data extraction rules +- Output locations + +#### 3. Generation Engine (`scripts/agent-identities/src/generators/`) + +TypeScript modules that extract: + +- Directory structures +- Port mappings from docker-compose +- Dependencies from go.mod/package.json +- Configuration examples +- Code patterns from documentation + +#### 4. Validation System (`scripts/agent-identities/src/validators/`) + +Automated checks for: + +- YAML front matter completeness +- Content structure and length +- Staleness detection +- File path validity + +## Quick Start + +### Install Dependencies + +```bash +cd /Users/oz/Projects/Sirius-Project/Sirius/scripts/agent-identities +npm install +``` + +### Generate Agent Identities + +```bash +# Generate all identities +cd /Users/oz/Projects/Sirius-Project/Sirius/testing/container-testing +make regenerate-agents + +# Generate specific identity +make regenerate-agent PRODUCT=agent-engineer +``` + +### Validate Identities + +```bash +# Full validation +make lint-agents + +# Check for staleness +make check-agent-sync +``` + +### Use in Cursor + +Use as slash commands (recommended): + +``` +/bot-agent-engineer +/bot-api-engineer +/bot-ui-engineer +/bot-maintainer-ops +/bot-github-commits +``` + +Or reference directly: + +```markdown +@bot-agent-engineer.md +``` + +## Creating Agent Identities + +### Step 1: Create Template + +Create `.cursor/agents/templates/.template.md`: + +```markdown +--- +name: "My Agent" +title: "My Agent (product/Tech)" +description: "Brief role description" +role_type: engineering +version: "1.0.0" +last_updated: "2025-10-25" +author: "Sirius Team" +specialization: ["skill1", "skill2"] +technology_stack: ["Tech1", "Tech2"] +system_integration_level: high +categories: ["category"] +tags: ["tag1", "tag2"] +related_docs: ["doc1.md"] +dependencies: ["path/"] +llm_context: high +context_window_target: 1400 +--- + +# My Agent + + + +**Role Philosophy** + +This agent develops [product] with focus on [key areas]. +Primary responsibilities include [list]. + + + +## Key Documentation + + + + +## Project Location + + + + +## Technology Stack + + + + +## System Integration + + + + +## Configuration + + + + +## Development Workflow + + + +**Key Development Practices** + +- Start development in docker container +- Test before committing +- Follow project standards + + +## Best Practices + + + +**Core Principles** + +1. **Principle 1** - Description +2. **Principle 2** - Description + +``` + +### Step 2: Create Configuration + +Create `.cursor/agents/config/.config.yaml`: + +```yaml +product: my-product +product_path: /path/to/product +docker_service_name: my-service + +metadata: + name: "My Agent" + title: "My Agent (product/Tech)" + description: "Brief description" + role_type: engineering + version: "1.0.0" + last_updated: "2025-10-25" + author: "Sirius Team" + specialization: ["skill1", "skill2"] + technology_stack: ["Tech1", "Tech2"] + system_integration_level: high + categories: ["category"] + tags: ["tag1", "tag2"] + related_docs: ["doc1.md"] + dependencies: ["path/"] + llm_context: high + context_window_target: 1400 + +generation: + include_file_structure: true + file_structure_depth: 3 + file_structure_ignore: [node_modules, dist, bin] + + include_ports: true + ports_config: + "8080": "HTTP server" + + include_dependencies: true + dependencies_source: go.mod + dependencies_grouping: + "Category": + - "package-name" + + include_config_examples: true + config_files: + - path: config/server.yaml + title: "Server Configuration" + + extract_code_patterns_from_docs: + - documentation/dev/file.md + +template_path: .cursor/agents/templates/.template.md +output_path: .cursor/agents/.agent.md +``` + +### Step 3: Generate and Validate + +```bash +# Generate +npm run generate -- --product= + +# Validate +npm run validate + +# Check output +cat .cursor/agents/.agent.md +``` + +## Template System + +### Section Markers + +#### AUTO-GENERATED Sections + +Content between these markers is replaced on each generation: + +```markdown + + +This content will be replaced by the generator + + +``` + +**Available Sections:** + +- `file-structure` - Directory tree +- `ports` - Port mappings with descriptions +- `dependencies` - Dependency list with grouping +- `config-examples` - Configuration file contents +- `documentation-links` - Related documentation +- `code-patterns` - Code patterns from docs +- `common-tasks` - Task examples from docs +- `troubleshooting` - Troubleshooting guides + +#### MANUAL Sections + +Content between these markers is preserved: + +```markdown + + +This content is preserved across generations + + + + + +Named manual sections for organization + + +``` + +### When to Use Each + +| Use AUTO-GENERATED for: | Use MANUAL for: | +| ---------------------------- | ----------------------------- | +| File paths and structure | Role philosophy and narrative | +| Port mappings | Best practices wisdom | +| Dependencies and versions | Development approaches | +| Configuration examples | Troubleshooting insights | +| Code patterns from docs | Key responsibilities | +| System architecture diagrams | Integration considerations | + +## Data Extractors + +### File Structure Extractor + +**Purpose:** Generate directory trees with depth control + +**Configuration:** + +```yaml +generation: + include_file_structure: true + file_structure_depth: 3 + file_structure_ignore: [node_modules, dist, bin, .git] +``` + +**Output Example:** + +``` +app-agent/ +├── cmd/ +│ ├── agent/ # Agent client entry point +│ └── server/ # gRPC server entry point +├── internal/ +│ ├── agent/ # Agent business logic +│ └── server/ # Server implementation +└── proto/ # Protocol Buffer definitions +``` + +### Port Extractor + +**Purpose:** Extract port mappings from docker-compose.yaml + +**Configuration:** + +```yaml +generation: + include_ports: true + ports_config: + "50051": "gRPC server (bidirectional streams)" + "8080": "HTTP health check endpoint" +``` + +**Output Example:** + +```markdown +| Port | Purpose | +| ----- | ----------------------------------- | +| 50051 | gRPC server (bidirectional streams) | +| 8080 | HTTP health check endpoint | +``` + +### Dependency Extractor + +**Purpose:** Parse and group dependencies from go.mod or package.json + +**Configuration:** + +```yaml +generation: + include_dependencies: true + dependencies_source: go.mod + dependencies_grouping: + "gRPC & Networking": + - "google.golang.org/grpc" + - "google.golang.org/protobuf" + "Storage": + - "github.com/valkey-io/valkey-go" +``` + +**Output Example:** + +```markdown +### gRPC & Networking + +- `google.golang.org/grpc` v1.60.0 +- `google.golang.org/protobuf` v1.32.0 + +### Storage + +- `github.com/valkey-io/valkey-go` v1.0.36 +``` + +### Config Extractor + +**Purpose:** Extract configuration file contents + +**Configuration:** + +```yaml +generation: + include_config_examples: true + config_files: + - path: config/server.yaml + title: "Server Configuration" + - path: config/agent.yaml + title: "Agent Configuration" +``` + +### Documentation Extractor + +**Purpose:** Extract code patterns and best practices from documentation + +**Configuration:** + +```yaml +generation: + extract_code_patterns_from_docs: + - documentation/dev/apps/README.agent-system.md + - documentation/dev/architecture/README.agent-system.md +``` + +## Validation System + +### YAML Front Matter Validation + +**Required Fields:** + +- `name` (string) +- `title` (string) +- `description` (string) +- `role_type` (enum: engineering, design, product, operations, qa, documentation) +- `version` (semver: 1.0.0) +- `last_updated` (YYYY-MM-DD) +- `author` (string) +- `llm_context` (enum: high, medium, low) + +**Validated:** + +```bash +✅ All required fields present +✅ Enum values valid +✅ Version format correct (1.0.0) +✅ Date format correct (2025-10-25) +``` + +### Content Validation + +**Checks:** + +- Line count: 150-2000 (hard limits) +- Target range: 800-1500 (warnings) +- Required sections present +- Proper section markers + +### Sync Validation + +**Purpose:** Detect when agent identities are stale + +**How it works:** + +1. Parse `_generated_at` timestamp from YAML +2. Check `_source_files` modification times +3. Compare timestamps +4. Report stale files + +**Example:** + +```bash +⚠️ Stale: Source files modified since last generation + Modified files: docker-compose.yaml, app-agent/go.mod + Run: make regenerate-agents +``` + +### File Path Validation + +**Purpose:** Verify referenced files exist + +**Extracts paths from:** + +- File structure sections +- Configuration examples +- Documentation links +- Code examples + +**Reports:** + +```bash +⚠️ Missing files: + - config/old-config.yaml + - documentation/removed-doc.md +``` + +## Commands Reference + +### Generation Commands + +```bash +# Generate all agent identities +cd testing/container-testing +make regenerate-agents + +# Generate specific agent +make regenerate-agent PRODUCT=agent-engineer + +# Direct npm usage +cd scripts/agent-identities +npm run generate -- --all +npm run generate -- --product=agent-engineer +``` + +### Validation Commands + +```bash +# Full validation (YAML, content, sync, paths) +cd testing/container-testing +make lint-agents + +# Quick validation +make lint-agents-quick + +# Check sync status only +make check-agent-sync + +# Direct npm usage +cd scripts/agent-identities +npm run validate +npm run check-sync +``` + +### Development Commands + +```bash +# Install dependencies +cd scripts/agent-identities +npm install + +# Build TypeScript +npm run build + +# Type checking +npx tsc --noEmit +``` + +## Integration with Workflow + +### Pre-Commit Hook + +Agent identities are automatically validated when: + +1. **Source files change** (docker-compose.yaml, go.mod, package.json, documentation) + + - Checks if regeneration needed + - Warns if identities are stale + - Prompts to regenerate or continue + +2. **Agent files modified directly** + - Runs quick validation + - Blocks commit if validation fails + +### CI/CD Integration + +```bash +# In your CI pipeline +cd /Users/oz/Projects/Sirius-Project/Sirius/scripts/agent-identities +npm install +npm run validate || exit 1 +``` + +### Makefile Integration + +```bash +# Part of complete validation +make validate-all +``` + +## Metadata Fields + +### Core Metadata + +| Field | Type | Required | Example | +| ----------------------- | ------ | -------- | ------------------------------------ | +| `name` | string | Yes | "Agent Engineer" | +| `title` | string | Yes | "Agent Engineer (app-agent/Go/gRPC)" | +| `description` | string | Yes | "Develops remote agent system" | +| `role_type` | enum | Yes | engineering | +| `version` | semver | Yes | 1.0.0 | +| `last_updated` | date | Yes | 2025-10-25 | +| `author` | string | Yes | "Sirius Team" | +| `llm_context` | enum | Yes | high | +| `context_window_target` | number | Yes | 1400 | + +### Optional Metadata + +| Field | Type | Purpose | +| -------------------------- | ----- | ---------------------------------------- | +| `specialization` | array | Key skills and focus areas | +| `technology_stack` | array | Technologies used | +| `system_integration_level` | enum | Integration depth (high/medium/low/none) | +| `categories` | array | Categorization | +| `tags` | array | Search keywords | +| `related_docs` | array | Documentation files | +| `dependencies` | array | Required paths | + +### Generation Metadata + +Automatically added by generator: + +| Field | Type | Purpose | +| --------------- | ----- | -------------------- | +| `_generated_at` | ISO | Generation timestamp | +| `_source_files` | array | Source files used | + +## Best Practices + +### Template Creation + +✅ **DO:** + +- Keep manual sections concise but comprehensive +- Focus on philosophy and wisdom in manual sections +- Use AUTO-GENERATED for structural information +- Include inline comments for clarity +- Reference documentation rather than duplicating + +❌ **DON'T:** + +- Put structural info in manual sections +- Duplicate documentation content +- Exceed 1500 lines (target: 1200-1400) +- Include implementation details (link to docs) + +### Configuration Design + +✅ **DO:** + +- Group dependencies logically +- Add descriptions to port mappings +- Set appropriate depth for file structures +- Ignore build artifacts and dependencies +- Extract patterns from authoritative docs + +❌ **DON'T:** + +- Include every dependency +- Set depth too deep (>4) +- Extract from outdated documentation +- Forget to update related_docs + +### Maintenance + +✅ **DO:** + +- Regenerate after major changes +- Run validation before commits +- Check sync status regularly +- Update templates when patterns emerge +- Keep configs up to date + +❌ **DON'T:** + +- Manually edit generated sections +- Ignore staleness warnings +- Skip validation +- Let identities drift from reality + +## Troubleshooting + +### Generation Fails + +**Symptom:** `npm run generate` fails with errors + +**Checks:** + +1. Product path exists and is accessible +2. Source files (go.mod, docker-compose.yaml) exist +3. Config YAML is valid +4. Template has proper markers +5. Dependencies installed (`npm install`) + +**Solution:** + +```bash +# Verify paths +ls -la /path/to/product + +# Validate YAML +npx js-yaml .cursor/agents/config/product.config.yaml + +# Check template +grep "AUTO-GENERATED" .cursor/agents/templates/product.template.md + +# Reinstall +cd scripts/agent-identities && npm install +``` + +### Validation Fails + +**Symptom:** `npm run validate` reports errors + +**Common Issues:** + +| Error | Cause | Fix | +| ----------------------- | --------------------------- | --------------------- | +| Missing required field | Incomplete YAML | Add missing field | +| Invalid enum value | Wrong role_type/llm_context | Use valid enum value | +| Version format invalid | Wrong semver format | Use 1.0.0 format | +| Date format invalid | Wrong date format | Use YYYY-MM-DD | +| Line count out of range | Too short/long | Adjust content length | + +### Staleness Detection + +**Symptom:** Pre-commit warns about stale identities + +**Cause:** Source files modified since last generation + +**Solution:** + +```bash +cd testing/container-testing + +# Check what's stale +make check-agent-sync + +# Regenerate all +make regenerate-agents + +# Or regenerate specific +make regenerate-agent PRODUCT=agent-engineer + +# Verify +make lint-agents +``` + +### Missing Files + +**Symptom:** Validation reports missing file references + +**Cause:** Agent identity references files that don't exist + +**Solutions:** + +1. **Files moved:** Update template references +2. **Files deleted:** Remove references from template +3. **Wrong path:** Correct path in template/config + +### TypeScript Errors + +**Symptom:** Build or execution errors + +**Checks:** + +```bash +cd scripts/agent-identities + +# Type checking +npx tsc --noEmit + +# Dependencies +npm install + +# Node version +node --version # Should be 20+ +``` + +## Project Structure + +``` +Sirius/ +├── .cursor/ +│ ├── agents/ +│ │ ├── templates/ # Manual templates +│ │ │ ├── agent-engineer.template.md +│ │ │ ├── api-engineer.template.md +│ │ │ └── ui-engineer.template.md +│ │ ├── config/ # Generation configs +│ │ │ ├── agent-engineer.config.yaml +│ │ │ ├── api-engineer.config.yaml +│ │ │ └── ui-engineer.config.yaml +│ │ └── docs/ # System documentation +│ │ ├── ABOUT.agent-identities.md +│ │ ├── TEMPLATE.agent-identity.md +│ │ ├── SPECIFICATION.agent-identity.md +│ │ ├── INDEX.agent-identities.md +│ │ └── GUIDE.creating-agent-identities.md +│ ├── commands/ # Generated identities (slash commands) +│ │ ├── bot-agent-engineer.md +│ │ ├── bot-api-engineer.md +│ │ └── bot-ui-engineer.md +│ └── rules/ +│ └── cursor_rules.mdc # Documents system +├── scripts/ +│ └── agent-identities/ +│ ├── package.json # TypeScript project +│ ├── tsconfig.json +│ ├── src/ +│ │ ├── generators/ # Data extractors +│ │ │ ├── index.ts +│ │ │ ├── file-structure.ts +│ │ │ ├── ports.ts +│ │ │ ├── dependencies.ts +│ │ │ ├── config-examples.ts +│ │ │ ├── documentation.ts +│ │ │ └── merge.ts +│ │ ├── validators/ # Validation modules +│ │ │ ├── index.ts +│ │ │ ├── yaml-validator.ts +│ │ │ ├── content-validator.ts +│ │ │ ├── sync-validator.ts +│ │ │ └── file-path-validator.ts +│ │ ├── types/ # Type definitions +│ │ │ ├── agent-identity.ts +│ │ │ ├── extraction.ts +│ │ │ └── template.ts +│ │ └── utils/ # Utilities +│ │ ├── logger.ts +│ │ ├── file-reader.ts +│ │ ├── yaml-parser.ts +│ │ └── markdown-builder.ts +│ ├── lint-agents.ts # Validation CLI +│ ├── generate-agents.ts # Generation CLI +│ └── check-sync.ts # Sync check CLI +├── testing/ +│ └── container-testing/ +│ └── Makefile # Commands +└── documentation/ + └── dev/ + └── ai-rules/ + └── README.ai-identities.md # This file +``` + +## Examples + +### Example: Creating API Engineer Identity + +**1. Create Template:** + +```markdown +--- +name: "API Engineer" +title: "API Engineer (sirius-api/Go/Fiber)" +description: "Develops REST API backend with Fiber framework" +role_type: engineering +# ... metadata +--- + +# API Engineer (sirius-api/Go/Fiber) + + + +Develops the REST API backend for Sirius Scan using Go and Fiber framework. +Focuses on vulnerability data endpoints, scan management, and integration +with PostgreSQL, RabbitMQ, and Valkey. + + + +## Project Location + + + + +## Technology Stack + + + +``` + +**2. Create Config:** + +```yaml +product: sirius-api +product_path: /Users/oz/Projects/Sirius-Project/Sirius/sirius-api +docker_service_name: sirius-api + +metadata: + name: "API Engineer" + # ... metadata + +generation: + include_file_structure: true + include_dependencies: true + dependencies_source: go.mod + dependencies_grouping: + "Web Framework": + - "github.com/gofiber/fiber/v2" + "Database": + - "github.com/lib/pq" +``` + +**3. Generate:** + +```bash +cd testing/container-testing +make regenerate-agent PRODUCT=api-engineer +``` + +## Resources + +### System Documentation + +- **`.cursor/agents/docs/ABOUT.agent-identities.md`** - System philosophy +- **`.cursor/agents/docs/TEMPLATE.agent-identity.md`** - Universal template +- **`.cursor/agents/docs/SPECIFICATION.agent-identity.md`** - Technical spec +- **`.cursor/agents/docs/INDEX.agent-identities.md`** - Agent registry +- **`.cursor/agents/docs/GUIDE.creating-agent-identities.md`** - Creation guide + +### Implementation + +- **`/agent-identity-system.plan.md`** - Implementation plan +- **`scripts/agent-identities/README.md`** - Generation system docs +- **`testing/container-testing/Makefile`** - Commands + +### Related Documentation + +- **`documentation/dev/ABOUT.documentation.md`** - Documentation standards +- **`documentation/dev/README.development.md`** - Development workflow +- **`.cursor/rules/cursor_rules.mdc`** - Cursor rules + +## Support + +### Getting Help + +1. **Check documentation** in `.cursor/agents/docs/` +2. **Review examples** in existing agent identities +3. **Run validation** to get specific error messages +4. **Check logs** for generation/validation details + +### Reporting Issues + +When reporting issues, include: + +- Command that failed +- Error message (full output) +- Config file content +- Template file content +- Node.js version (`node --version`) + +### Contributing + +To contribute improvements: + +1. Update TypeScript generators/validators +2. Test with `npm run validate` +3. Update documentation +4. Submit PR with examples + +--- + +**Last Updated:** 2025-10-25 +**Version:** 1.0.0 +**Maintainer:** Sirius Team diff --git a/documentation/dev/ai-rules/README.playwright.md b/documentation/dev/ai-rules/README.playwright.md new file mode 100644 index 0000000..6ec2696 --- /dev/null +++ b/documentation/dev/ai-rules/README.playwright.md @@ -0,0 +1,577 @@ +--- +title: "Playwright Browser Testing Guide" +description: "Guide for using Playwright MCP for browser testing, troubleshooting, and validation" +template: "TEMPLATE.guide" +version: "1.0.0" +last_updated: "2025-10-18" +author: "Sirius Development Team" +tags: ["testing", "playwright", "browser", "e2e", "validation"] +categories: ["testing", "development", "troubleshooting"] +difficulty: "intermediate" +prerequisites: ["Docker", "MCP Server"] +related_docs: + - "README.container-testing.md" + - "CHECKLIST.testing-by-type.md" +llm_context: "high" +search_keywords: ["playwright", "browser testing", "e2e", "automation", "mcp"] +--- + +# Playwright Browser Testing Guide + +## Overview + +This guide covers using the Playwright MCP (Model Context Protocol) server for automated browser testing, troubleshooting, and implementation validation in the Sirius project. + +## Docker Network Access + +### Critical: Host Access from Docker + +The Playwright MCP server runs inside Docker and cannot access `localhost` directly. Use Docker's special DNS name: + +``` +✅ CORRECT: http://host.docker.internal:3000 +❌ INCORRECT: http://localhost:3000 +❌ INCORRECT: http://127.0.0.1:3000 +``` + +### Service URLs + +| Service | Docker URL | Description | +| ------------------- | ----------------------------------- | ------------------- | +| UI | `http://host.docker.internal:3000` | Next.js frontend | +| API | `http://host.docker.internal:9001` | Go Fiber backend | +| RabbitMQ Management | `http://host.docker.internal:15672` | Queue management UI | +| PostgreSQL | `host.docker.internal:5432` | Database (not HTTP) | + +## When to Use Playwright + +### ✅ Use Playwright For: + +1. **Implementation Validation** + + - Verify new features work end-to-end + - Test user flows after major changes + - Confirm UI components render correctly + +2. **Bug Troubleshooting** + + - Reproduce user-reported issues + - Capture screenshots of error states + - Inspect console logs and network requests + - Debug form submissions and interactions + +3. **Design Verification** + + - Check responsive layouts + - Verify component positioning + - Test accessibility features + - Validate user experience flows + +4. **Integration Testing** + + - Test API integration points + - Verify data flow between UI and backend + - Check authentication flows + - Validate form submissions + +5. **Regression Testing** + - Verify existing functionality still works + - Test critical user paths + - Check for breaking changes + +### ❌ Don't Use Playwright For: + +1. **Unit Testing** - Use Jest/Vitest instead +2. **Backend API Testing** - Use curl/API testing tools +3. **Performance Testing** - Use dedicated tools +4. **Load Testing** - Use k6 or similar tools + +## Common Testing Scenarios + +### 1. Testing Authentication Flow + +```yaml +Example: + - Navigate to login page + - Fill in credentials + - Click submit + - Verify redirect to dashboard + - Check session state +``` + +### 2. Testing Form Submission + +```yaml +Example: + - Navigate to scanner page + - Fill in target IP address + - Select template from dropdown + - Click "Start Scan" + - Verify API requests made + - Check UI updates +``` + +### 3. Testing API Integration + +```yaml +Example: + - Navigate to page that loads data + - Wait for API calls to complete + - Check network requests + - Verify data displays correctly + - Test error handling +``` + +### 4. Debugging UI Issues + +```yaml +Example: + - Navigate to problematic page + - Take screenshot of current state + - Check console for errors + - Inspect element states + - Verify network requests +``` + +## Playwright MCP Tools Reference + +### Navigation + +**`browser_navigate`** - Navigate to a URL + +``` +Use: Load a page +URL: http://host.docker.internal:3000/scanner +``` + +**`browser_navigate_back`** - Go to previous page + +``` +Use: Test back button functionality +``` + +### Interaction + +**`browser_click`** - Click an element + +``` +Parameters: + - element: Human-readable description + - ref: Element reference from snapshot +Example: Click "Start Scan" button +``` + +**`browser_type`** - Type text into input + +``` +Parameters: + - element: Input field description + - ref: Element reference + - text: Text to type + - slowly: Type one character at a time (optional) + - submit: Press Enter after typing (optional) +``` + +**`browser_fill_form`** - Fill multiple form fields + +``` +Use: Fill entire forms efficiently +Fields: Array of {name, type, ref, value} +``` + +**`browser_select_option`** - Select dropdown option + +``` +Use: Choose from select/combobox +Values: Array of option values +``` + +### Inspection + +**`browser_snapshot`** - Capture page state + +``` +Use: Get current page structure +Returns: Accessibility tree with element refs +``` + +**`browser_take_screenshot`** - Take visual screenshot + +``` +Use: Capture visual state +Options: fullPage, element, filename +Note: Cannot interact based on screenshot +``` + +**`browser_console_messages`** - Get console logs + +``` +Use: Debug JavaScript errors +Options: onlyErrors to filter +``` + +**`browser_network_requests`** - View network activity + +``` +Use: Verify API calls +Returns: All requests since page load +``` + +### Waiting + +**`browser_wait_for`** - Wait for condition + +``` +Options: + - text: Wait for text to appear + - textGone: Wait for text to disappear + - time: Wait N seconds +``` + +### Advanced + +**`browser_hover`** - Hover over element + +``` +Use: Test hover states, tooltips +``` + +**`browser_drag`** - Drag and drop + +``` +Use: Test drag interactions +``` + +**`browser_evaluate`** - Execute JavaScript + +``` +Use: Complex DOM manipulation or queries +``` + +**`browser_tabs`** - Manage browser tabs + +``` +Actions: list, new, close, select +``` + +## Testing Workflow Examples + +### Example 1: Test Scanner Page + +```yaml +Step 1: Navigate + - URL: http://host.docker.internal:3000/scanner + - Wait for: Page load + +Step 2: Login (if needed) + - Fill username: admin + - Fill password: password + - Click: "Join the Pack" + - Wait for: Dashboard redirect + +Step 3: Navigate to Scanner + - Click: Scanner link + - Wait for: Page load + +Step 4: Add Target + - Type in IP field: 192.168.1.100 + - Click: Add button + - Verify: Target appears in list + +Step 5: Start Scan + - Select template: "High Risk Scan" + - Click: "Start Scan" + - Check network: queue.sendMsg called + - Check network: store.setValue called + - Verify: UI updates with scan details +``` + +### Example 2: Debug Form Not Submitting + +```yaml +Step 1: Navigate to Form + - URL: http://host.docker.internal:3000/form-page + +Step 2: Fill Form + - Fill all required fields + - Take screenshot: "before-submit.png" + +Step 3: Submit + - Click: Submit button + - Get console messages + - Get network requests + +Step 4: Analyze + - Check console for errors + - Verify API request was made + - Check API response status + - Take screenshot: "after-submit.png" +``` + +### Example 3: Verify Component Rendering + +```yaml +Step 1: Navigate + - URL: http://host.docker.internal:3000/component-page + +Step 2: Wait for Load + - Wait for: Expected text + - Wait: 2 seconds for async data + +Step 3: Capture State + - Take snapshot + - Check for: Expected elements + - Verify: Element text content + +Step 4: Test Interaction + - Click: Interactive element + - Verify: State change + - Take screenshot: Show result +``` + +## Best Practices + +### 1. Always Use host.docker.internal + +```yaml +✅ GOOD: + - http://host.docker.internal:3000/scanner + +❌ BAD: + - http://localhost:3000/scanner + - http://127.0.0.1:3000/scanner +``` + +### 2. Wait for Async Operations + +```yaml +✅ GOOD: + - Navigate to page + - Wait 2-3 seconds + - Check for loaded content + - Interact with elements + +❌ BAD: + - Navigate to page + - Immediately interact (might not be ready) +``` + +### 3. Use Snapshots for Element Refs + +```yaml +✅ GOOD: + - Take snapshot + - Get element ref (e.g., e187) + - Use ref for interaction + +❌ BAD: + - Guess element selectors + - Use outdated refs +``` + +### 4. Check Network Requests + +```yaml +✅ GOOD: + - Perform action + - Get network requests + - Verify expected API calls + +❌ BAD: + - Assume API was called + - Skip verification +``` + +### 5. Capture Console Logs + +```yaml +✅ GOOD: + - Check console after actions + - Look for errors or warnings + - Verify debug logs + +❌ BAD: + - Ignore console output + - Miss JavaScript errors +``` + +## Troubleshooting + +### Issue: Cannot Connect to Page + +``` +Error: net::ERR_CONNECTION_REFUSED +Solution: Use host.docker.internal instead of localhost +``` + +### Issue: Element Not Found + +``` +Problem: Element ref is stale +Solution: Take fresh snapshot before interaction +``` + +### Issue: Timeout Errors + +``` +Problem: Page loads slowly +Solution: Increase wait time or wait for specific condition +``` + +### Issue: Network Requests Not Visible + +``` +Problem: Requests made before navigation +Solution: Navigate first, then check requests +``` + +## Testing Checklist + +### Pre-Test Setup + +- [ ] Ensure Docker containers are running +- [ ] Verify services are healthy +- [ ] Check that UI is accessible at host.docker.internal:3000 + +### During Testing + +- [ ] Use host.docker.internal URLs +- [ ] Wait for page loads +- [ ] Take snapshots before interactions +- [ ] Check console for errors +- [ ] Verify network requests +- [ ] Capture screenshots for visual issues + +### Post-Test Analysis + +- [ ] Review console messages +- [ ] Check network request logs +- [ ] Verify expected API calls +- [ ] Document any issues found +- [ ] Take final screenshots + +## Common Test Scenarios + +### Authentication + +``` +1. Navigate to login page +2. Fill credentials +3. Submit form +4. Verify session cookie +5. Check redirect +``` + +### Form Validation + +``` +1. Navigate to form +2. Submit without required fields +3. Verify error messages +4. Fill fields correctly +5. Submit and verify success +``` + +### Data Loading + +``` +1. Navigate to data page +2. Wait for loading state +3. Verify API calls made +4. Check data displays +5. Test error states +``` + +### Navigation + +``` +1. Test all nav links +2. Verify correct pages load +3. Check active states +4. Test back/forward +5. Verify breadcrumbs +``` + +## Integration with Development + +### When to Run Tests + +1. **After UI Changes** + + - Verify components still render + - Check interactions work + - Test user flows + +2. **Before Commits** + + - Quick smoke test + - Verify critical paths + - Check for console errors + +3. **During Debugging** + + - Reproduce reported issues + - Capture error states + - Verify fixes + +4. **During Code Review** + - Validate new features + - Check edge cases + - Verify error handling + +## LLM Context for Testing + +When the AI should use Playwright: + +1. **User reports UI bug** → Use Playwright to reproduce +2. **Testing new feature** → Use Playwright to validate +3. **Verifying implementation** → Use Playwright to check +4. **Debugging form issues** → Use Playwright to inspect +5. **Checking API integration** → Use Playwright to verify network calls + +When the AI should NOT use Playwright: + +1. **Backend-only changes** → Use curl or API testing +2. **Unit test failures** → Check test files directly +3. **Build issues** → Check logs and configuration +4. **Database queries** → Use database tools + +## Quick Reference + +### Login Sequence + +``` +1. navigate → http://host.docker.internal:3000 +2. wait 3 seconds +3. type username → "admin" +4. type password → "password" +5. click → "Join the Pack" +6. wait for redirect +``` + +### Scan Flow + +``` +1. navigate → http://host.docker.internal:3000/scanner +2. type target → "192.168.1.100" +3. click → Add button +4. select template → "High Risk Scan" +5. click → "Start Scan" +6. check network → verify queue.sendMsg +``` + +### Debug Flow + +``` +1. navigate → problematic page +2. wait for load +3. take snapshot → see structure +4. get console messages → check errors +5. get network requests → verify API +6. take screenshot → capture visual state +``` + +--- + +_For more testing information, see [README.container-testing.md](../test/README.container-testing.md) and [CHECKLIST.testing-by-type.md](../test/CHECKLIST.testing-by-type.md)._ + diff --git a/documentation/dev/apps/agent/README.agent-system.md b/documentation/dev/apps/agent/README.agent-system.md new file mode 100644 index 0000000..34757f7 --- /dev/null +++ b/documentation/dev/apps/agent/README.agent-system.md @@ -0,0 +1,1240 @@ +--- +title: "Agent System Architecture" +description: "Comprehensive architecture documentation for the Sirius distributed agent system, including gRPC communication, template synchronization, and vulnerability detection" +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-10-25" +author: "Sirius Platform Team" +tags: + [ + "agent", + "grpc", + "architecture", + "distributed-system", + "template-system", + "vulnerability-detection", + ] +categories: ["architecture", "agent-system", "distributed-systems"] +difficulty: "advanced" +prerequisites: + - "Basic understanding of gRPC and Protocol Buffers" + - "Familiarity with Go programming language" + - "Understanding of distributed system concepts" + - "Knowledge of Docker and containerization" +related_docs: + - "README.docker-architecture.md" + - "README.development.md" + - "../README.developer-guide.md" + - "../apps/README.agent-template-api.md" +dependencies: + - "app-agent/" + - "sirius-api/" + - "proto/hello/" +llm_context: "high" +search_keywords: + [ + "agent", + "grpc", + "distributed", + "template", + "vulnerability", + "detection", + "synchronization", + "bidirectional-stream", + "protobuf", + ] +--- + +# Agent System Architecture + +## Overview + +The Sirius Agent System is a distributed architecture for managing remote security agents that perform vulnerability detection and system scanning across heterogeneous environments. The system uses gRPC bidirectional streaming for real-time communication, a template-based detection engine, and a sophisticated synchronization mechanism for distributing vulnerability signatures. + +### System Components + +``` +┌──────────────────────────────────────────────────────┐ +│ Sirius Platform │ +│ ┌────────────────┐ ┌────────────────┐ │ +│ │ sirius-api │◄────►│ sirius-ui │ │ +│ │ (Go/Fiber) │ │ (Next.js) │ │ +│ └────────┬───────┘ └────────────────┘ │ +│ │ │ +│ │ RabbitMQ (Command Queue) │ +│ ▼ │ +│ ┌────────────────┐ │ +│ │ Agent Server │◄──────── Valkey/Redis │ +│ │ (gRPC) │ (Template Storage) │ +│ └────────┬───────┘ │ +│ │ Bidirectional gRPC Stream │ +│ │ │ +└───────────┼───────────────────────────────────────────┘ + │ + ┌───────┴───────┬──────────┬──────────┐ + │ │ │ │ + ▼ ▼ ▼ ▼ +┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ +│ Agent │ │ Agent │ │ Agent │ │ Agent │ +│ Linux │ │ Win │ │ macOS │ │ Remote │ +└────────┘ └────────┘ └────────┘ └────────┘ +``` + +## Core Architecture + +### 1. Agent Server + +**Location**: `app-agent/cmd/server/` and `app-agent/internal/server/` + +**Purpose**: Central hub for agent management, command distribution, and template synchronization. + +#### Server Components + +```go +type Server struct { + // Core services + logger *zap.Logger + config *config.ServerConfig + server *grpc.Server + + // Agent management + agentsMutex sync.RWMutex + agents map[string]pb.HelloService_ConnectStreamServer + + // Command tracking + commandsMutex sync.RWMutex + commands map[string]*CommandStatus + + // Template system + templateManager *ServerTemplateManager + valkeyClient valkey.Client + + // Response storage + responseStore store.ResponseStore + + // Pending command correlation + pendingCommandsMutex sync.Mutex + pendingCommands map[string]string +} +``` + +#### Key Responsibilities + +1. **Agent Connection Management** + + - Accept and maintain bidirectional gRPC streams + - Track connected agents with unique IDs + - Handle agent disconnections gracefully + - Monitor agent health via heartbeats + +2. **Command Distribution** + + - Listen to RabbitMQ for commands from UI + - Route commands to appropriate agents + - Track command execution status + - Store results in Valkey for UI retrieval + +3. **Template Synchronization** + + - Sync templates from GitHub repository + - Store templates in Valkey + - Distribute templates to agents + - Handle custom template uploads + +4. **State Management** + - Maintain agent connection state + - Track command execution lifecycle + - Coordinate template versioning + - Manage concurrent access safely + +### 2. Agent Client + +**Location**: `app-agent/cmd/agent/` and `app-agent/internal/agent/` + +**Purpose**: Remote endpoint that executes commands and performs vulnerability scans. + +#### Agent Components + +```go +type Agent struct { + // gRPC communication + logger *zap.Logger + config *config.AgentConfig + conn *grpc.ClientConn + client pb.HelloServiceClient + stream pb.HelloService_ConnectStreamClient + + // Agent information + startTime time.Time + agentInfo commands.AgentInfo + + // Scripting support + powerShellPath string + scriptingEnabled bool + + // Template management + syncManager *templateagent.AgentSyncManager +} +``` + +#### Key Responsibilities + +1. **Server Communication** + + - Establish bidirectional gRPC stream + - Send periodic heartbeats with system metrics + - Receive and process server messages + - Handle connection failures and reconnection + +2. **Command Execution** + + - Process internal commands (status, help, scan) + - Execute shell commands via PowerShell/bash + - Capture command output and errors + - Report execution results to server + +3. **Template Synchronization** + + - Request template updates from server + - Receive and cache templates locally + - Validate template checksums + - Maintain local template manifest + +4. **Vulnerability Scanning** + - Load and parse cached templates + - Execute template detection steps + - Evaluate detection logic + - Report scan results + +## Communication Protocol + +### gRPC Service Definition + +```protobuf +service HelloService { + // Health check + rpc Ping(PingRequest) returns (PingResponse) {} + + // Bidirectional streaming for real-time communication + rpc ConnectStream(stream AgentMessage) returns (stream ServerMessage) {} +} + +enum MessageType { + UNKNOWN = 0; + HEARTBEAT = 1; // Agent → Server: Health status + COMMAND = 2; // Server → Agent: Execute command + RESULT = 3; // Agent → Server: Command result + ACKNOWLEDGMENT = 4; // Server → Agent: Confirm receipt + TEMPLATE_UPDATE = 5; // Server → Agent: Template data + TEMPLATE_SYNC_REQUEST = 6; // Agent → Server: Request templates +} +``` + +### Message Flow Patterns + +#### Command Execution Flow + +``` +1. UI/API → RabbitMQ + └─ Queue: agent_commands + └─ Message: {action, command, agentId, userId, timestamp} + +2. Server consumes from RabbitMQ + └─ Validates agent is connected + └─ Sends ACK to agent_response queue + └─ Generates commandId = "agentId:timestamp" + └─ Stores in pendingCommands map + └─ Forwards to agent via gRPC stream + +3. Agent receives COMMAND message + └─ Checks internal command registry + └─ If not found, executes as shell command + └─ Captures stdout, stderr, exit code + └─ Sends RESULT message to server + +4. Server receives RESULT message + └─ Looks up commandId from pendingCommands + └─ Creates CommandResponse object + └─ Stores in Valkey: key = "cmd:result:{commandId}" + └─ Logs to file + └─ Sends ACKNOWLEDGMENT to agent + +5. UI/API polls Valkey + └─ Retrieves result using commandId + └─ Displays to user +``` + +#### Template Sync Flow + +``` +1. Agent sends TEMPLATE_SYNC_REQUEST + └─ Includes lastSync timestamp + └─ Sent via gRPC stream + +2. Server processes sync request + └─ Queries Valkey for templates updated after lastSync + └─ Builds TemplateManifest (metadata only) + └─ Sends manifest as first message + +3. Server streams templates + └─ For each template: + ├─ Retrieves content from Valkey + ├─ Calculates checksum + ├─ Creates TEMPLATE_UPDATE message + └─ Sends via stream + +4. Agent receives templates + └─ For each TEMPLATE_UPDATE: + ├─ Writes to cache directory (atomic) + ├─ Verifies checksum + ├─ Updates local manifest + └─ Ready for scanning + +5. Agent completes sync + └─ Updates lastSync timestamp + └─ Templates available for execution +``` + +#### Heartbeat Flow + +``` +Agent (every 30 seconds): + └─ Collects system metrics (CPU, memory) + └─ Sends HEARTBEAT message + └─ Includes timestamp, metrics + +Server receives HEARTBEAT: + └─ Updates agent last-seen time + └─ Logs metrics (debug level) + └─ No response needed (fire-and-forget) +``` + +## Template System Architecture + +### Template Structure + +The template system uses YAML-based vulnerability definitions that are platform-agnostic and module-driven. + +#### Template Definition + +```yaml +id: apache-outdated +info: + name: Outdated Apache HTTP Server + author: security-team + severity: high + description: Detects Apache versions with known CVEs + cve: + - CVE-2021-44228 + tags: [apache, web-server, cve] + version: "1.0" + +detection: + logic: all # all (AND) or any (OR) + steps: + - type: version-cmd + platforms: [linux, darwin] + weight: 1.0 + config: + command: "httpd -v" + version_regex: "Apache/(\\d+\\.\\d+\\.\\d+)" + vulnerable_versions: + - "< 2.4.52" + + - type: file-content + platforms: [linux, darwin] + weight: 0.8 + config: + path: "/etc/apache2/apache2.conf" + patterns: ["ServerTokens.*Full"] +``` + +### Template Execution Engine + +**Location**: `app-agent/internal/template/executor/` + +``` +┌─────────────────────────────────────────────┐ +│ Template Executor │ +├─────────────────────────────────────────────┤ +│ │ +│ 1. Filter Steps by Platform │ +│ └─ Current OS: linux/darwin/windows │ +│ │ +│ 2. Execute Steps Sequentially │ +│ ├─ Get module from registry │ +│ ├─ Create timeout context │ +│ ├─ Execute module │ +│ └─ Collect results │ +│ │ +│ 3. Evaluate Detection Logic │ +│ ├─ logic: all → All steps match (AND) │ +│ └─ logic: any → Any step matches (OR) │ +│ │ +│ 4. Calculate Confidence │ +│ ├─ logic: all → Min(weights) │ +│ └─ logic: any → Max(weights) │ +│ │ +│ 5. Build Result │ +│ └─ {matched, confidence, steps, errors} │ +│ │ +└─────────────────────────────────────────────┘ +``` + +### Detection Modules + +Detection modules are pluggable components that implement specific detection mechanisms. + +#### Module Interface + +```go +type Module interface { + Name() string + Execute(ctx context.Context, config map[string]interface{}) (*ModuleResult, error) +} + +type ModuleResult struct { + Matched bool + Evidence map[string]interface{} + Error string +} +``` + +#### Available Modules + +| Module | Type | Purpose | Platforms | +| ------------- | ------------- | -------------------------- | ----------------- | +| version-cmd | Command | Parse version from command | All | +| file-hash | File System | Check file SHA256 hash | All | +| file-content | File System | Search file for patterns | All | +| registry-key | Windows | Check registry keys/values | Windows only | +| service-check | System | Verify service exists/runs | All | +| config-check | Configuration | Parse and validate configs | All | +| script-exec | Custom | Execute custom detection | Platform-specific | + +#### Module Registration + +```go +// Module implementation +type FileHashModule struct{} + +func (m *FileHashModule) Name() string { + return "file-hash" +} + +func (m *FileHashModule) Execute(ctx context.Context, config map[string]interface{}) (*ModuleResult, error) { + // Implementation +} + +// Registration (in init()) +func init() { + registry.Register(&FileHashModule{}) +} +``` + +### Template Storage and Distribution + +#### Server-Side Storage (Valkey) + +``` +Template Keys Structure: + + template:manifest + └─ Global manifest JSON with all template metadata + + template:meta: + └─ Individual template metadata JSON + └─ {id, version, checksum, size, severity, platforms, etc.} + + template:standard: + └─ Standard template YAML content + └─ From sirius-agent-modules GitHub repository + + template:custom: + └─ Custom template YAML content + └─ User-uploaded via UI +``` + +#### Agent-Side Cache + +``` +Cache Directory Structure: + +Windows: C:\ProgramData\Sirius\templates\ +Linux: /var/lib/sirius/templates/ +macOS: /Library/Application Support/Sirius/templates/ + +Contents: + ├── cache-manifest.json # Local cache metadata + │ └─ {version, lastSync, templates{}, statistics{}} + │ + ├── standard/ # Standard templates + │ ├── apache-outdated.yaml + │ ├── nginx-vuln.yaml + │ └── ssh-weak-ciphers.yaml + │ + └── custom/ # Custom templates + └── org-policy-check.yaml +``` + +#### Template Synchronization Manager + +**Server Side** (`internal/server/template_manager.go`): + +```go +type ServerTemplateManager struct { + valkeyClient valkey.Client + storage *templatevalkey.ValKeyTemplateStorage + githubSync *templatevalkey.GitHubSyncManager + logger *zap.Logger + config *TemplateConfig + server *Server +} + +// Key Methods: +// - SyncFromGitHub() → Pull from sirius-agent-modules +// - GetTemplatesForSync() → Prepare templates for agent +// - StoreCustomTemplate() → Handle user uploads +// - ValidateTemplate() → Security and syntax checks +``` + +**Agent Side** (`internal/template/agent/sync_manager.go`): + +```go +type AgentSyncManager struct { + cacheDir string + logger *zap.Logger + serverURL string + agentID string + grpcStream pb.HelloService_ConnectStreamClient +} + +// Key Methods: +// - SyncFromServer() → Request template sync +// - HandleTemplateUpdate() → Process incoming templates +// - LoadTemplates() → Load cached templates for scanning +// - ValidateCache() → Verify template checksums +``` + +## Command System + +### Command Architecture + +The agent supports both internal commands (built into the agent) and shell commands (executed via PowerShell/bash). + +``` +┌─────────────────────────────────────────────┐ +│ Command Dispatcher │ +├─────────────────────────────────────────────┤ +│ │ +│ 1. Receive Command String │ +│ └─ From server via gRPC stream │ +│ │ +│ 2. Parse Command │ +│ ├─ Extract command name │ +│ └─ Parse arguments │ +│ │ +│ 3. Check Command Registry │ +│ ├─ Internal command? → Execute handler │ +│ └─ Not found? → Fall back to shell │ +│ │ +│ 4. Execute │ +│ ├─ Internal: Call Go function │ +│ └─ Shell: Execute via PowerShell/bash │ +│ │ +│ 5. Capture Result │ +│ ├─ stdout, stderr │ +│ ├─ exit code │ +│ └─ execution time │ +│ │ +│ 6. Send Result to Server │ +│ └─ RESULT message via gRPC stream │ +│ │ +└─────────────────────────────────────────────┘ +``` + +### Internal Commands + +| Command | Purpose | Example | +| --------------- | -------------------------------- | ------------------------------------ | +| `help` | List available commands | `help` | +| `status` | Agent status and capabilities | `status` | +| `scan` | Execute vulnerability scan | `scan --targets=192.168.1.0/24` | +| `template list` | List cached templates | `template list` | +| `template sync` | Trigger template synchronization | `template sync` | +| `templatescan` | Run specific template | `templatescan --template=apache-001` | + +### Command Registration + +```go +// Command handler signature +type CommandHandler func(ctx context.Context, info AgentInfo, args []string) (string, error) + +// Registration +func Register(name string, handler CommandHandler) { + commandsMutex.Lock() + defer commandsMutex.Unlock() + commands[name] = handler +} + +// Dispatch +func Dispatch(ctx context.Context, info AgentInfo, commandString string) (string, error) { + cmdName, args := parseCommandLine(commandString) + + handler, exists := commands[cmdName] + if !exists { + return "", ErrUnknownCommand + } + + return handler(ctx, info, args) +} +``` + +### Shell Command Execution + +When a command is not found in the internal registry, the agent attempts to execute it as a shell command. + +#### PowerShell Execution (Windows) + +```go +func ExecuteScript(ctx context.Context, psPath string, scriptContent string) (stdout, stderr string, exitCode int, err error) { + // Create temp script file + tempFile := filepath.Join(os.TempDir(), fmt.Sprintf("sirius-script-%d.ps1", time.Now().UnixNano())) + os.WriteFile(tempFile, []byte(scriptContent), 0600) + defer os.Remove(tempFile) + + // Execute via PowerShell + cmd := exec.CommandContext(ctx, psPath, "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", tempFile) + + // Capture output + var stdoutBuf, stderrBuf bytes.Buffer + cmd.Stdout = &stdoutBuf + cmd.Stderr = &stderrBuf + + err = cmd.Run() + + return stdoutBuf.String(), stderrBuf.String(), cmd.ProcessState.ExitCode(), err +} +``` + +#### Bash Execution (Linux/macOS) + +```go +func ExecuteCommand(ctx context.Context, command string) (stdout, stderr string, exitCode int, err error) { + cmd := exec.CommandContext(ctx, "/bin/bash", "-c", command) + + var stdoutBuf, stderrBuf bytes.Buffer + cmd.Stdout = &stdoutBuf + cmd.Stderr = &stderrBuf + + err = cmd.Run() + + return stdoutBuf.String(), stderrBuf.String(), cmd.ProcessState.ExitCode(), err +} +``` + +## Data Storage Architecture + +### Valkey (Redis) Schema + +The system uses Valkey for distributed state management and caching. + +#### Key Patterns + +``` +Command Results: + cmd:result:{agentId}:{timestamp} + └─ CommandResponse JSON + └─ TTL: 1 hour + └─ Fields: {commandId, agentId, command, status, output, error, exitCode} + +Template Storage: + template:manifest + └─ Global manifest with statistics + + template:meta:{templateId} + └─ Template metadata + + template:standard:{templateId} + └─ Standard template YAML + + template:custom:{templateId} + └─ Custom template YAML + +Agent Metadata (future): + agent:meta:{agentId} + └─ Agent information + └─ {id, hostname, platform, version, capabilities, lastSeen} +``` + +### RabbitMQ Message Queues + +#### Queue Definitions + +``` +agent_commands + └─ Purpose: Commands from UI/API to agents + └─ Format: JSON + └─ Schema: {action, command, agentId, userId, timestamp, target} + └─ Consumers: Agent Server + +agent_response + └─ Purpose: Acknowledgments and responses to UI/API + └─ Format: JSON + └─ Schema: {success, message, output, error} + └─ Consumers: sirius-api +``` + +#### Message Examples + +**Command Message**: + +```json +{ + "action": "", + "command": "systeminfo", + "agentId": "", + "userId": "user-123", + "timestamp": "1698765432000", + "target": { + "type": "agent", + "id": "agent-001" + } +} +``` + +**Response Message**: + +```json +{ + "success": true, + "message": "Command received, forwarding to agent", + "output": "", + "error": "" +} +``` + +## Security Architecture + +### Authentication and Authorization + +#### Agent Authentication + +``` +1. Agent Registration: + ├─ Agent ID generated on first startup + ├─ ID stored in agent config + └─ Server validates agent ID on connection + +2. gRPC Metadata: + ├─ agent_id: Unique identifier + ├─ scripting_enabled: Capability flag + └─ Future: JWT tokens, TLS certificates + +3. Stream Authorization: + ├─ Server maintains whitelist of allowed agent IDs + ├─ Validates agent ID on ConnectStream + └─ Rejects unauthorized connections +``` + +#### Command Authorization + +``` +1. Command Source Validation: + ├─ Commands only accepted from RabbitMQ + ├─ Server validates target agent exists + └─ Server checks agent is connected + +2. Agent-Side Validation: + ├─ Only processes commands from established stream + ├─ Validates command format + └─ Rejects malformed commands + +3. Future Enhancements: + ├─ Role-based access control (RBAC) + ├─ Command whitelisting per agent + └─ Audit logging of all commands +``` + +### Template Security + +#### Template Validation + +```go +// Server-side validation before storage +func (tm *ServerTemplateManager) ValidateTemplate(template *types.Template, content []byte) error { + // 1. Syntax validation + if err := parser.ParseTemplate(template); err != nil { + return fmt.Errorf("syntax error: %w", err) + } + + // 2. Security scan - dangerous patterns + dangerousPatterns := []string{ + "eval(", "exec(", "system(", + "shell_exec(", "passthru(", + } + for _, pattern := range dangerousPatterns { + if strings.Contains(string(content), pattern) { + return fmt.Errorf("dangerous pattern detected: %s", pattern) + } + } + + // 3. Script injection check + scriptPatterns := []string{ + " MaxTemplateSize { + return fmt.Errorf("template exceeds size limit") + } + + return nil +} +``` + +#### Checksum Verification + +``` +1. Server calculates SHA256 on storage: + └─ checksum = sha256(templateContent) + +2. Checksum included in TEMPLATE_UPDATE: + └─ {templateId, version, checksum, content} + +3. Agent verifies on receipt: + ├─ Calculate sha256(received content) + ├─ Compare with provided checksum + └─ Reject if mismatch +``` + +### Network Security + +``` +1. gRPC Transport Security: + ├─ TLS encryption (configurable) + ├─ Certificate validation + └─ Mutual TLS support (future) + +2. RabbitMQ Security: + ├─ Authentication required + ├─ Per-queue permissions + └─ TLS connections + +3. Valkey Security: + ├─ Password authentication + ├─ Network isolation + └─ Redis ACLs (future) +``` + +## Deployment Architecture + +### Container Architecture + +``` +┌─────────────────────────────────────────────────────┐ +│ Docker Network: sirius │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌───────────┐ │ +│ │ sirius-ui │ │ sirius-api │ │ postgres │ │ +│ │ (Next.js) │ │ (Go/Fiber) │ │ │ │ +│ │ Port: 3000 │ │ Port: 8080 │ │ Port:5432 │ │ +│ └──────────────┘ └──────┬───────┘ └───────────┘ │ +│ │ │ +│ ┌──────────────┐ ┌──────▼───────┐ ┌───────────┐ │ +│ │ valkey │ │ rabbitmq │ │ sirius- │ │ +│ │ (Redis) │ │ │ │ engine │ │ +│ │ Port: 6379 │ │ Port: 5672 │ │ (agent) │ │ +│ └──────────────┘ └──────────────┘ └───────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────┐│ +│ │ Agent Server (gRPC) ││ +│ │ Port: 50051 ││ +│ │ Mounts: app-agent/ → /app-agent ││ +│ └─────────────────────────────────────────────────┘│ +└─────────────────────────────────────────────────────┘ + │ + │ gRPC (external) + │ + ┌───────────────┴────────────────┐ + │ │ + ▼ ▼ + ┌──────────────┐ ┌──────────────┐ + │ Remote Agent │ │ Remote Agent │ + │ (Linux) │ │ (Windows) │ + │ │ │ │ + │ External IP │ │ External IP │ + └──────────────┘ └──────────────┘ +``` + +### Agent Server Deployment + +**Development Mode** (`sirius-engine` container): + +```yaml +services: + sirius-engine: + build: + context: sirius-engine + dockerfile: Dockerfile + volumes: + - ./app-agent:/app-agent # Dev mode hot-reload + ports: + - "50051:50051" # gRPC port + environment: + - VALKEY_ADDRESS=valkey:6379 + - RABBITMQ_URL=amqp://guest:guest@rabbitmq:5672/ + depends_on: + - valkey + - rabbitmq +``` + +**Production Mode**: + +```yaml +services: + agent-server: + image: sirius-agent-server:latest + ports: + - "50051:50051" + environment: + - SERVER_ADDRESS=0.0.0.0:50051 + - VALKEY_ADDRESS=valkey:6379 + - RABBITMQ_URL=amqp://user:pass@rabbitmq:5672/ + - LOG_LEVEL=info + restart: unless-stopped +``` + +### Remote Agent Deployment + +#### Linux Agent (systemd) + +```ini +[Unit] +Description=Sirius Security Agent +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +User=sirius-agent +Group=sirius-agent +Environment="AGENT_ID=agent-linux-001" +Environment="SERVER_ADDRESS=server.example.com:50051" +Environment="ENABLE_SCRIPTING=true" +ExecStart=/usr/local/bin/sirius-agent +Restart=always +RestartSec=10 + +[Install] +WantedBy=multi-user.target +``` + +#### Windows Agent (Service) + +```powershell +# Install as Windows Service +New-Service -Name "SiriusAgent" ` + -BinaryPathName "C:\Program Files\Sirius\sirius-agent.exe" ` + -DisplayName "Sirius Security Agent" ` + -StartupType Automatic ` + -Description "Sirius distributed security agent" + +# Set environment variables +[Environment]::SetEnvironmentVariable("AGENT_ID", "agent-win-001", "Machine") +[Environment]::SetEnvironmentVariable("SERVER_ADDRESS", "server.example.com:50051", "Machine") +[Environment]::SetEnvironmentVariable("ENABLE_SCRIPTING", "true", "Machine") + +# Start service +Start-Service -Name "SiriusAgent" +``` + +#### macOS Agent (launchd) + +```xml + + + + + Label + com.sirius.agent + ProgramArguments + + /usr/local/bin/sirius-agent + + EnvironmentVariables + + AGENT_ID + agent-mac-001 + SERVER_ADDRESS + server.example.com:50051 + ENABLE_SCRIPTING + true + + RunAtLoad + + KeepAlive + + + +``` + +## Performance Considerations + +### Scalability + +#### Horizontal Scaling + +``` +Server Scaling: + ├─ Multiple agent server instances behind load balancer + ├─ gRPC load balancing strategies + ├─ Shared state in Valkey + └─ RabbitMQ message distribution + +Agent Scaling: + ├─ Thousands of agents per server instance + ├─ Efficient stream multiplexing + ├─ Minimal memory footprint per agent + └─ Connection pooling +``` + +#### Vertical Scaling + +``` +Server Resources: + ├─ CPU: Moderate (gRPC is efficient) + ├─ Memory: 2GB base + 5MB per 1000 agents + ├─ Network: High bandwidth for template distribution + └─ Storage: Minimal (state in Valkey) + +Agent Resources: + ├─ CPU: Low (idle), High (scanning) + ├─ Memory: 50-100MB base + ├─ Disk: 100MB for template cache + └─ Network: Low (heartbeats), High (template sync) +``` + +### Optimization Strategies + +#### Template Caching + +``` +Agent-Side: + ├─ Templates cached on disk + ├─ Only sync changed templates + ├─ Checksum-based validation + └─ Last-sync timestamp tracking + +Server-Side: + ├─ Templates stored in Valkey + ├─ Manifest cached in memory + ├─ Incremental sync support + └─ Compression for transfer (future) +``` + +#### Connection Management + +``` +gRPC Streams: + ├─ Single bidirectional stream per agent + ├─ Stream multiplexing (HTTP/2) + ├─ Automatic reconnection with backoff + └─ Heartbeat-based connection validation + +Command Execution: + ├─ Async command processing + ├─ Non-blocking stream operations + ├─ Context-based cancellation + └─ Timeout enforcement +``` + +## Monitoring and Observability + +### Metrics + +``` +Server Metrics: + ├─ agent.connections.total (gauge) + ├─ agent.connections.active (gauge) + ├─ commands.executed.total (counter) + ├─ commands.duration (histogram) + ├─ templates.synced.total (counter) + └─ grpc.stream.errors (counter) + +Agent Metrics: + ├─ agent.uptime (gauge) + ├─ agent.heartbeat.sent (counter) + ├─ commands.received (counter) + ├─ scans.executed (counter) + ├─ templates.cached (gauge) + └─ memory.usage (gauge) +``` + +### Logging + +``` +Structured Logging (zap): + + Server: + ├─ agent.connected: {agentId, timestamp} + ├─ command.sent: {commandId, agentId, command} + ├─ command.completed: {commandId, exitCode, duration} + └─ template.synced: {templateId, agentId} + + Agent: + ├─ connection.established: {serverId, timestamp} + ├─ command.received: {command, timestamp} + ├─ command.executed: {command, exitCode, duration} + └─ template.updated: {templateId, checksum} +``` + +### Health Checks + +``` +Server Health Endpoint: + GET /health + └─ { + "status": "healthy", + "agents": { + "total": 42, + "connected": 40 + }, + "services": { + "valkey": "healthy", + "rabbitmq": "healthy" + } + } + +Agent Health Check: + ├─ Heartbeat interval: 30 seconds + ├─ Server considers agent unhealthy after: 90 seconds + └─ Agent reconnects automatically +``` + +## Error Handling and Resilience + +### Connection Failures + +``` +Agent Reconnection Strategy: + 1. Detect connection loss (stream error) + 2. Wait with exponential backoff: + ├─ 1st retry: 1 second + ├─ 2nd retry: 2 seconds + ├─ 3rd retry: 4 seconds + └─ Max: 60 seconds + 3. Attempt reconnection + 4. Resume from last sync point + 5. Resend pending commands +``` + +### Command Failures + +``` +Server Handling: + ├─ Command timeout: 5 minutes + ├─ Store error in CommandResponse + ├─ Mark command as failed + └─ Notify UI via Valkey + +Agent Handling: + ├─ Capture all errors + ├─ Include stderr in result + ├─ Return non-zero exit code + └─ Continue processing other commands +``` + +### Template Sync Failures + +``` +Graceful Degradation: + ├─ Agent continues using cached templates + ├─ Retry sync on next request + ├─ Log sync errors for investigation + └─ Alert on repeated failures +``` + +## Future Enhancements + +### Planned Features + +1. **Enhanced Security** + + - Mutual TLS authentication + - JWT-based authorization + - Command RBAC system + - Encrypted template storage + +2. **Advanced Template Features** + + - Template versioning system + - Template dependency resolution + - Conditional step execution + - Dynamic module loading + +3. **Scalability Improvements** + + - Agent clustering support + - Multi-region deployment + - Template CDN distribution + - Result streaming for large scans + +4. **Monitoring & Analytics** + - Real-time dashboards + - Agent performance metrics + - Template effectiveness tracking + - Automated alerting system + +## LLM Context + +### High-Level Architecture Understanding + +This document provides a comprehensive overview of the Sirius Agent System architecture. Key areas for AI assistants to understand: + +1. **Bidirectional gRPC Communication**: The system uses persistent streams for real-time agent communication, not request-response patterns. + +2. **Template-Based Detection**: Vulnerability detection is driven by YAML templates with pluggable modules, not hardcoded logic. + +3. **Distributed State Management**: Valkey stores templates and results; RabbitMQ handles command distribution; gRPC handles real-time communication. + +4. **Agent Autonomy**: Agents cache templates locally and can operate semi-independently, syncing periodically with the server. + +5. **Security-First Design**: Multiple validation layers for templates, commands, and connections ensure system integrity. + +### Code Navigation + +When working with this system: + +- **Server code**: `app-agent/internal/server/` +- **Agent code**: `app-agent/internal/agent/` +- **Template system**: `app-agent/internal/template/` +- **Detection modules**: `app-agent/internal/detect/` +- **Protocol definitions**: `app-agent/proto/hello/` + +### Common Development Tasks + +- Adding detection modules: Implement `Module` interface, register in `internal/modules/registry` +- Creating templates: Follow YAML structure, test with `templatescan` command +- Extending protocol: Update `.proto` file, regenerate with `./scripts/generate_proto.sh` +- Debugging communication: Enable gRPC logging, check server/agent logs, inspect Valkey keys + +--- + +**Related Documentation**: + +- [Docker Architecture](mdc:README.docker-architecture.md) - Container deployment details +- [Developer Guide](mdc:../README.developer-guide.md) - Development workflow +- [Agent Template API](mdc:../apps/README.agent-template-api.md) - API integration + +**For Developers**: See [Remote Agent Engineer Role](@mdc:../../.cursor/agents/remote-agent-engineer.agent.md) for detailed implementation guidance. + +**Last Updated**: October 25, 2025 +**Version**: 1.0.0 +**Maintained By**: Sirius Platform Team diff --git a/documentation/dev/apps/agent/README.agent-template-api.md b/documentation/dev/apps/agent/README.agent-template-api.md new file mode 100644 index 0000000..f8358c8 --- /dev/null +++ b/documentation/dev/apps/agent/README.agent-template-api.md @@ -0,0 +1,512 @@ +--- +title: "Agent Template API Documentation" +description: "API endpoints for managing agent vulnerability detection templates" +template: "TEMPLATE.documentation-standard" +llm_context: "high" +categories: ["api", "agent", "templates"] +tags: ["api", "agent", "templates", "vulnerability", "detection"] +related_docs: + - "README.agent-template-ui.md" + - "ABOUT.documentation.md" +search_keywords: + ["agent template api", "template endpoints", "vulnerability detection"] +--- + +# Agent Template API Documentation + +## Overview + +The Agent Template API provides endpoints for managing vulnerability detection templates used by Sirius agents. These templates define detection logic for identifying vulnerabilities on target systems. + +## Base URL + +``` +http://localhost:9001/api +``` + +## Endpoints + +### List All Templates + +Get all agent templates (standard + custom). + +**Endpoint:** `GET /agent-templates` + +**Response:** + +```json +[ + { + "id": "CVE-2021-44228", + "name": "Log4Shell Detection", + "description": "Detects Log4j RCE vulnerability", + "type": "standard", + "severity": "critical", + "author": "Sirius Security Team", + "platforms": ["linux", "darwin", "windows"], + "version": "1.0.0", + "createdAt": "2024-01-15T10:00:00Z", + "updatedAt": "2024-01-15T10:00:00Z", + "source": { + "type": "standard", + "name": "sirius-templates", + "priority": 1 + } + } +] +``` + +--- + +### Get Single Template + +Get a specific template by ID, including its full YAML content. + +**Endpoint:** `GET /agent-templates/:id` + +**Parameters:** + +- `id` (path): Template ID + +**Response:** + +```json +{ + "id": "CVE-2021-44228", + "name": "Log4Shell Detection", + "description": "Detects Log4j RCE vulnerability", + "type": "standard", + "severity": "critical", + "author": "Sirius Security Team", + "platforms": ["linux"], + "version": "1.0.0", + "createdAt": "2024-01-15T10:00:00Z", + "updatedAt": "2024-01-15T10:00:00Z", + "content": "id: CVE-2021-44228\ninfo:\n name: Log4Shell Detection\n..." +} +``` + +**Error Responses:** + +- `404 Not Found`: Template not found + +--- + +### Upload Custom Template + +Upload a new custom template from a YAML file. + +**Endpoint:** `POST /agent-templates` + +**Content-Type:** `multipart/form-data` + +**Form Fields:** + +- `file` (file, required): YAML template file (.yaml or .yml) +- `author` (string, optional): Override author name + +**Response:** + +```json +{ + "id": "custom-template-123", + "message": "Template uploaded successfully and pushed to agents", + "validation": { + "valid": true, + "errors": [], + "warnings": ["Author field is recommended"] + } +} +``` + +**Error Responses:** + +- `400 Bad Request`: Invalid file or validation failed + ```json + { + "error": "Template validation failed", + "validation": { + "valid": false, + "errors": ["Missing required field: info.severity"], + "warnings": [] + } + } + ``` + +**Validation Rules:** + +- File must be .yaml or .yml extension +- File size must be under 1MB +- Must include required fields: `id`, `info.name`, `info.severity`, `info.description` +- Severity must be one of: `critical`, `high`, `medium`, `low`, `info` + +--- + +### Validate Template + +Validate a template without saving it. + +**Endpoint:** `POST /agent-templates/validate` + +**Content-Type:** `application/json` + +**Request Body:** + +```json +{ + "content": "id: test-template\ninfo:\n name: Test Template\n..." +} +``` + +**Response:** + +```json +{ + "valid": true, + "errors": [], + "warnings": ["Tags are recommended for better organization"] +} +``` + +--- + +### Update Custom Template + +Update an existing custom template. + +**Endpoint:** `PUT /agent-templates/:id` + +**Parameters:** + +- `id` (path): Template ID + +**Content-Type:** `application/json` + +**Request Body:** + +```json +{ + "content": "id: test-template\ninfo:\n name: Updated Test Template\n..." +} +``` + +**Response:** + +```json +{ + "message": "Template updated and pushed to agents" +} +``` + +**Error Responses:** + +- `400 Bad Request`: Validation failed +- `404 Not Found`: Template not found +- `403 Forbidden`: Cannot update standard templates + +--- + +### Delete Custom Template + +Delete a custom template. + +**Endpoint:** `DELETE /agent-templates/:id` + +**Parameters:** + +- `id` (path): Template ID + +**Response:** + +```json +{ + "message": "Template deleted from agents" +} +``` + +**Error Responses:** + +- `404 Not Found`: Template not found +- `403 Forbidden`: Cannot delete standard templates + +--- + +### Test Template on Agent + +Execute a template on a specific agent and get results. + +**Endpoint:** `POST /agent-templates/:id/test` + +**Parameters:** + +- `id` (path): Template ID + +**Content-Type:** `application/json` + +**Request Body:** + +```json +{ + "agent_id": "agent-123" +} +``` + +**Response:** + +```json +{ + "message": "Template test initiated on agent", + "agent_id": "agent-123", + "template_id": "CVE-2021-44228" +} +``` + +**Note:** This endpoint initiates the test. Results are retrieved asynchronously via agent event logs or response queues. + +--- + +### Deploy Template to Agents + +Deploy a template to specific agents or all agents. + +**Endpoint:** `POST /agent-templates/:id/deploy` + +**Parameters:** + +- `id` (path): Template ID + +**Content-Type:** `application/json` + +**Request Body:** + +```json +{ + "agent_ids": ["agent-123", "agent-456"] +} +``` + +**Note:** Empty `agent_ids` array deploys to all agents. + +**Response:** + +```json +{ + "message": "Template deployed to agents", + "agent_count": 2 +} +``` + +--- + +### Get Template Analytics + +Get template effectiveness statistics. + +**Endpoint:** `GET /agent-templates/analytics` + +**Response:** + +```json +{ + "top_templates": [ + { + "template_id": "CVE-2021-44228", + "template_name": "Log4Shell Detection", + "detection_count": 42, + "execution_count": 150, + "success_rate": 0.95, + "average_execution_time_ms": 245 + } + ], + "execution_stats": { + "total_executions": 1250, + "total_detections": 105, + "average_execution_time_ms": 195, + "success_rate": 0.91 + }, + "platform_distribution": { + "linux": 850, + "darwin": 250, + "windows": 150 + } +} +``` + +**Note:** Analytics are aggregated from agent event logs. + +--- + +### Get Template Results History + +Get historical execution results for a template. + +**Endpoint:** `GET /agent-templates/:id/results` + +**Parameters:** + +- `id` (path): Template ID + +**Response:** + +```json +{ + "template_id": "CVE-2021-44228", + "results": [ + { + "agent_id": "agent-123", + "timestamp": "2024-01-15T10:30:00Z", + "vulnerable": true, + "confidence": 0.95, + "execution_time_ms": 245 + } + ] +} +``` + +--- + +## Template YAML Schema + +### Required Fields + +```yaml +id: unique-template-id +info: + name: Human-readable template name + severity: critical|high|medium|low|info + description: What this template detects +detection: + steps: + - type: file_hash|file_content|command_version|script + config: {} +``` + +### Optional Fields + +```yaml +info: + author: Author name + version: Template version (e.g., 1.0.0) + references: + - https://example.com/vuln-info + cve: + - CVE-2021-XXXXX + tags: + - apache + - rce +detection: + logic: all|any # Default: all + steps: + - platforms: + - linux + - darwin + weight: 0.8 # 0.0-1.0, affects confidence +``` + +### Detection Step Types + +#### File Hash + +```yaml +- type: file_hash + config: + path: /usr/bin/vulnerable-binary + hash: abc123def456... + algorithm: sha256 # sha256, sha1, md5, sha512 +``` + +#### File Content + +```yaml +- type: file_content + config: + path: /etc/apache2/apache2.conf + regex: "ServerTokens\\s+Full" +``` + +#### Command Version + +```yaml +- type: command_version + config: + command: ["dpkg-query", "-W", "-f='${Version}'", "openssh-server"] + regex: "^6\\.5\\.1" + exit_code: 0 # optional +``` + +#### Script + +```yaml +- type: script + config: + interpreter: bash|python|powershell + script: | + #!/bin/bash + dpkg-query -W -f='${Version}' openssh-server + regex: "^6\\.5\\.1" + exit_code: 0 # optional +``` + +--- + +## Error Codes + +| Code | Description | +| ---- | ---------------------------------------------------------------------- | +| 400 | Bad Request - Invalid input or validation failed | +| 403 | Forbidden - Operation not allowed (e.g., modifying standard templates) | +| 404 | Not Found - Template does not exist | +| 500 | Internal Server Error - Server-side error occurred | + +--- + +## Rate Limiting + +Currently, no rate limiting is applied. This may change in future versions. + +--- + +## Authentication + +Currently, no authentication is required. All authenticated users can manage templates. Role-based access control will be added in a future version. + +--- + +## Examples + +### Upload a Custom Template + +```bash +curl -X POST http://localhost:9001/api/agent-templates \ + -F "file=@my-template.yaml" \ + -F "author=Security Team" +``` + +### Get All Templates + +```bash +curl http://localhost:9001/api/agent-templates +``` + +### Delete a Custom Template + +```bash +curl -X DELETE http://localhost:9001/api/agent-templates/my-custom-template +``` + +### Test Template on Agent + +```bash +curl -X POST http://localhost:9001/api/agent-templates/CVE-2021-44228/test \ + -H "Content-Type: application/json" \ + -d '{"agent_id": "agent-123"}' +``` + +--- + +## See Also + +- [Agent Template UI Documentation](README.agent-template-ui.md) +- [Agent Template Types Definition](../../app-agent/internal/template/types/types.go) +- [Template System Notes](../../app-agent/project/BRAINSTORM.template-system-notes.md) + diff --git a/documentation/dev/apps/agent/README.agent-template-ui.md b/documentation/dev/apps/agent/README.agent-template-ui.md new file mode 100644 index 0000000..5de5396 --- /dev/null +++ b/documentation/dev/apps/agent/README.agent-template-ui.md @@ -0,0 +1,480 @@ +--- +title: "Agent Template UI Documentation" +description: "User interface workflows for managing agent vulnerability detection templates" +template: "TEMPLATE.documentation-standard" +llm_context: "high" +categories: ["ui", "agent", "templates"] +tags: ["ui", "agent", "templates", "vulnerability", "detection", "scanner"] +related_docs: + - "README.agent-template-api.md" + - "ABOUT.documentation.md" +search_keywords: ["agent template ui", "template management", "scanner ui"] +--- + +# Agent Template UI Documentation + +## Overview + +The Agent Template UI provides a comprehensive interface for managing vulnerability detection templates within the Sirius Scanner. Users can browse, upload, test, and analyze templates through an intuitive web interface. + +## Accessing Template Management + +**Navigation:** Scanner → Advanced → Agent → Templates Tab + +The Agent Templates interface is located within the Scanner's Advanced configuration section, under the Agent settings. + +--- + +## Interface Components + +### 1. Template Browser + +The main view for browsing and managing templates. + +#### Features + +- **Search**: Search templates by name, ID, description, or author +- **Filters**: Filter by type, severity, platform, and source +- **Template Cards**: Visual cards displaying template metadata +- **Actions**: View, edit (custom only), delete (custom only), test, and deploy + +#### Template Card Information + +Each template card displays: + +- Template name and ID +- Description (truncated to 2 lines) +- Severity badge (color-coded) +- Type badge (standard/custom) +- Source information +- Supported platforms +- Author and version + +#### Action Buttons + +- **View**: Display full template details and YAML content +- **Edit**: Modify custom templates (not available for standard templates) +- **Delete**: Remove custom templates (not available for standard templates) +- **Test**: Execute template on a selected agent + +--- + +### 2. Template Uploader + +Upload custom vulnerability detection templates. + +#### Upload Process + +1. Click "Create Template" or "Upload Template" button +2. Drag and drop a YAML file or click to browse +3. File is automatically validated +4. Review validation results (errors and warnings) +5. Preview template content +6. Optionally override author field +7. Click "Upload Template" to save + +#### File Requirements + +- File format: `.yaml` or `.yml` +- Maximum size: 1MB +- Must include required YAML fields +- Must pass validation checks + +#### Validation + +**Required Fields:** + +- `id`: Unique template identifier +- `info.name`: Human-readable template name +- `info.severity`: Severity level (critical/high/medium/low/info) +- `info.description`: Description of what the template detects + +**Optional but Recommended:** + +- `info.author`: Template author +- `info.tags`: Tags for organization +- `info.version`: Template version +- `info.references`: Links to vulnerability information +- `info.cve`: CVE identifiers + +**Validation Feedback:** + +- ✓ **Errors** (red): Must be fixed before upload +- ⚠ **Warnings** (yellow): Recommended improvements, not blocking + +--- + +### 3. Template Tester + +Test templates on live agents to verify detection logic. + +#### Testing Process + +1. Select a template to test +2. Choose a target agent from the list +3. Click "Run Test" button +4. View real-time execution progress +5. Review detailed test results + +#### Agent Selection + +**Filters:** + +- Status: Online/Offline (only online agents can be selected) +- Platform: Filter by operating system +- Search: Find agents by hostname or IP + +**Agent Information Displayed:** + +- Hostname +- IP address +- Platform (Linux/macOS/Windows) +- Status (online/offline) +- Last seen timestamp +- Agent version + +#### Test Results + +**Summary Metrics:** + +- **Vulnerability Status**: Vulnerable or Not Vulnerable +- **Confidence Score**: 0-100% (color-coded: green/yellow/orange/red) +- **Execution Time**: Template execution duration in milliseconds +- **Steps Completed**: Number of detection steps executed + +**Detailed Results:** + +- Evidence collected during detection +- Step-by-step execution results +- Individual step confidence scores +- Error messages (if any) + +**Step Details (expandable):** + +- Step type (file_hash, file_content, command_version, script) +- Match status (matched/not matched) +- Evidence data +- Error information + +--- + +### 4. Template Analytics + +View template effectiveness and execution statistics. + +#### Summary Cards + +- **Total Executions**: Total number of template runs across all agents +- **Vulnerabilities Found**: Total detections +- **Success Rate**: Percentage of successful executions +- **Average Execution Time**: Mean template execution time + +#### Top Performing Templates + +Ranked list of templates by detection count, showing: + +- Template rank (top 5) +- Template name and ID +- Detection count +- Execution count +- Success rate percentage +- Average execution time +- Visual performance bar + +#### Platform Distribution + +Breakdown of template executions by platform: + +- Linux +- macOS (Darwin) +- Windows + +Displayed as: + +- Platform icon +- Execution count +- Percentage of total +- Visual progress bar + +--- + +## User Workflows + +### Workflow 1: Uploading a Custom Template + +1. Navigate to Scanner → Advanced → Agent → Templates +2. Ensure "Enable Agent Templates" is toggled ON +3. Click "Upload Template" button +4. Drag and drop your YAML file or click to browse +5. Wait for automatic validation +6. Review validation results: + - If errors exist, fix your template and re-upload + - Warnings are optional improvements +7. Review the template preview +8. (Optional) Override the author field +9. Click "Upload Template" +10. Template is saved and automatically distributed to all agents +11. Return to template browser to see your new template + +**Success Indicators:** + +- Green checkmark in validation +- Template appears in browser with "custom" badge +- Confirmation message displayed + +--- + +### Workflow 2: Testing a Template + +1. From the template browser, click the test icon on any template +2. Or click "Test Template" and select a template from dropdown +3. Review template information (description, platforms, etc.) +4. Scroll to "Select Target Agent" section +5. Use filters to find appropriate agents: + - Filter by platform if template is platform-specific + - Ensure agent is online (green status badge) +6. Click on an agent card to select it +7. Click "Run Test" button +8. Wait for test execution (typically 1-5 seconds) +9. Review results: + - Check vulnerability status + - Review confidence score + - Examine evidence + - Expand steps for detailed information +10. Test additional agents or return to browser + +**Best Practices:** + +- Test on multiple agents to verify detection logic +- Test on different platforms if template supports multiple +- Review confidence scores to validate template accuracy + +--- + +### Workflow 3: Managing Templates + +#### Viewing Template Details + +1. Click "View" button on any template card +2. Review full template information: + - Complete metadata + - Full YAML content (with syntax highlighting) +3. Use "Test Template" to verify functionality +4. Use "Back to Templates" to return + +#### Deleting Custom Templates + +1. Locate the custom template in browser +2. Click the trash icon (red) +3. Confirm deletion in dialog +4. Template is removed from all agents immediately + +**Note:** Standard templates cannot be deleted. + +--- + +### Workflow 4: Monitoring Template Effectiveness + +1. Click "Analytics" button in template browser +2. Review summary metrics at the top +3. Check "Top Performing Templates": + - Identify which templates find the most vulnerabilities + - Review success rates + - Identify slow-running templates +4. Review "Platform Distribution": + - Understand which platforms are scanned most + - Identify coverage gaps +5. Use insights to: + - Prioritize template improvements + - Add templates for underrepresented platforms + - Remove ineffective templates + +--- + +## Settings + +### Enable Agent Templates + +Toggle agent template scanning on or off for all scans. + +**Location:** Templates tab → Settings card + +**Effect:** When disabled, agents will not execute vulnerability detection templates during scans. + +### Template Priority + +Control which templates are used based on severity level. + +**Options:** + +- **High**: Only critical and high severity templates +- **Medium**: Include medium severity templates +- **All**: Use all templates regardless of severity + +**Use Cases:** + +- **High**: Fast scans focusing on critical vulnerabilities +- **Medium**: Balanced scan coverage +- **All**: Comprehensive vulnerability assessment + +--- + +## Template Card Color Coding + +### Severity Colors + +- **Critical**: Red (bg-red-500/20, text-red-400) +- **High**: Orange (bg-orange-500/20, text-orange-400) +- **Medium**: Yellow (bg-yellow-500/20, text-yellow-400) +- **Low**: Blue (bg-blue-500/20, text-blue-400) +- **Info**: Gray (bg-gray-500/20, text-gray-400) + +### Type Colors + +- **Standard**: Green (bg-green-500/20, text-green-400) +- **Custom**: Violet (bg-violet-500/20, text-violet-400) +- **Repository**: Blue (bg-blue-500/20, text-blue-400) + +### Status Colors (Agents) + +- **Online**: Green +- **Offline**: Gray + +--- + +## Keyboard Shortcuts + +Currently, no keyboard shortcuts are implemented. This may be added in a future version. + +--- + +## Troubleshooting + +### Template Upload Fails + +**Symptoms:** Validation errors prevent upload + +**Solutions:** + +1. Review error messages carefully +2. Check required fields are present +3. Verify severity value is valid (critical/high/medium/low/info) +4. Ensure YAML syntax is correct +5. Check file size is under 1MB +6. Verify file extension is .yaml or .yml + +### Template Test Hangs + +**Symptoms:** Test never completes or times out + +**Possible Causes:** + +- Agent is offline or unreachable +- Template contains infinite loop or long-running command +- Network connectivity issues + +**Solutions:** + +1. Verify agent is online in agent list +2. Test a different template on the same agent +3. Test the same template on a different agent +4. Check agent logs for errors +5. Review template detection logic for long-running operations + +### Template Not Appearing + +**Symptoms:** Uploaded template doesn't appear in browser + +**Solutions:** + +1. Refresh the page +2. Clear any active filters +3. Check template was successfully uploaded (confirmation message) +4. Verify template wasn't deleted by another user +5. Check browser console for JavaScript errors + +### Agents Not Listed in Test View + +**Symptoms:** No agents available for testing + +**Possible Causes:** + +- No agents are currently online +- Platform filter is too restrictive +- Agents haven't registered yet + +**Solutions:** + +1. Check agent status in Terminal or Dashboard +2. Clear platform filter to see all agents +3. Wait for agents to come online +4. Verify agent connectivity + +--- + +## Performance Considerations + +### Template Browser + +- Displays up to 1000 templates efficiently +- Filtering and search are client-side (instant) +- Template cards use lazy loading for large lists + +### Template Testing + +- Test results are displayed in real-time +- Step-by-step results are lazy-loaded +- Large evidence data is formatted for readability + +### Analytics + +- Analytics data is cached for 5 minutes +- Refresh manually to get latest statistics +- Chart rendering is optimized for large datasets + +--- + +## Security Notes + +### Template Upload + +- All templates are validated before upload +- Malicious YAML is rejected +- File size limits prevent DoS attacks +- Templates are sandboxed during execution + +### Template Testing + +- Tests only execute on selected agents +- Test results are not persisted +- Agent permissions are enforced + +### Template Deletion + +- Only custom templates can be deleted +- Deletion is immediate and cannot be undone +- All agents are notified of deletion + +--- + +## Future Enhancements + +Planned features for future releases: + +1. **Template Editor**: Visual form-based template builder +2. **Template Versioning**: Track and rollback template changes +3. **Template Collections**: Bundle related templates +4. **Template Marketplace**: Share templates with community +5. **Scheduled Scans**: Automatic periodic template execution +6. **Advanced Analytics**: Detection trends over time +7. **Role-Based Access**: Control who can upload/edit templates +8. **Bulk Operations**: Deploy/test multiple templates at once + +--- + +## See Also + +- [Agent Template API Documentation](README.agent-template-api.md) +- [Template System Notes](../../app-agent/project/BRAINSTORM.template-system-notes.md) +- [Scanner Advanced Configuration](../ui/README.scanner-advanced.md) + diff --git a/documentation/dev/apps/scanner/ARCHITECTURE.host-deduplication.md b/documentation/dev/apps/scanner/ARCHITECTURE.host-deduplication.md new file mode 100644 index 0000000..8540120 --- /dev/null +++ b/documentation/dev/apps/scanner/ARCHITECTURE.host-deduplication.md @@ -0,0 +1,162 @@ +--- +title: "Host Deduplication and Multi-Source Attribution" +description: "Canonical host identity by IP, multi-source attribution (network/agent), scan_sources field, and UI merge/display with SourceIcon and SourceIconRow." +template: "TEMPLATE.custom" +version: "1.0.0" +last_updated: "2025-02-07" +author: "Sirius Team" +tags: ["scanner", "host", "deduplication", "scan_sources", "SourceIcon", "multi-source"] +categories: ["architecture", "scanner"] +difficulty: "intermediate" +prerequisites: ["README.scanner.md", "ARCHITECTURE.sub-scans.md"] +related_docs: + - "documentation/dev/apps/scanner/README.scanner.md" + - "documentation/dev/apps/scanner/ARCHITECTURE.scanner-data-flow.md" + - "documentation/dev/apps/scanner/ARCHITECTURE.sub-scans.md" +dependencies: [] +llm_context: "high" +search_keywords: + - "host deduplication" + - "scan_sources" + - "multi-source" + - "SourceIcon" + - "SourceIconRow" + - "EnvironmentTableData" + - "canonical host IP" +--- + +# Host Deduplication and Multi-Source Attribution + +Hosts in the Sirius scanner can be discovered by multiple scan methods (network and agent). This document describes how hosts are identified by a canonical key, how multiple sources are attributed, and how the UI merges and displays them. + +## Canonical Host Identity: IP Address + +The **primary key** for a host is its **IP address**. Regardless of whether a host was found by a network scan, an agent scan, or both, it is represented once per IP in the merged view. + +- **Backend:** `HostEntry` (and persisted host records) use `ip` as the canonical identifier; `id` can be a unique row or document id; `hostname`, `aliases`, and `sources` are optional. +- **UI:** Tables and detail views key hosts by `ip` when merging data from different sub-scans or from the environment summary API. + +This allows: + +- One row per host in the environment/host table +- Correct aggregation of vulnerability counts and source badges per host +- Stable navigation to host detail (e.g. by IP) regardless of which scan discovered it + +--- + +## Multi-Source Attribution + +A host can be discovered by: + +- **network** – app-scanner (Nmap, RustScan, etc.) +- **agent** – app-agent (template runs on remote host) + +Other sources (e.g. cloud, application) can be added later. Each discovery path that reports a host should tag it with its **source identifier** (e.g. `"network"`, `"agent"`). + +### HostEntry.sources (backend / ValKey) + +In the live `ScanResult` stored in ValKey, each `HostEntry` can carry a list of sources: + +```go +type HostEntry struct { + ID string `json:"id"` + IP string `json:"ip"` + Hostname string `json:"hostname,omitempty"` + Aliases []string `json:"aliases,omitempty"` + Sources []string `json:"sources,omitempty"` // e.g. ["network", "agent"] +} +``` + +When merging results from multiple sub-scans, the component that writes to `currentScan` should: + +- Merge hosts by IP (one entry per IP) +- Set `sources` to the union of all sources that reported that IP (e.g. if both network and agent found it, `sources = ["network", "agent"]`) + +--- + +## EnvironmentTableData.scan_sources (UI) + +The UI uses **EnvironmentTableData** for the environment/host table. It includes: + +- **scan_source** (optional, legacy): Single source string (e.g. `"network"` or `"agent"`). +- **scan_sources** (optional): Array of source strings for multi-source attribution. + +```ts +interface EnvironmentTableData { + hostname: string; + ip: string; + os: string; + vulnerabilityCount: number; + maxCvss?: number; + groups: string[]; + tags: string[]; + scan_source?: ScanSource; // legacy single source + scan_sources?: string[]; // all discovery sources for this host +} +``` + +When mapping from API or from live scan results: + +- Prefer **scan_sources** (array) when building the table (e.g. from `host.sources` or equivalent). +- Fall back to **scan_source** for older data or single-source responses, and convert to `scan_sources` for consistent display (e.g. `row.scan_sources ?? (row.scan_source ? [row.scan_source] : [])`). + +--- + +## How the UI Merges Hosts from Different Sub-Scans + +1. **Live scan results (ValKey):** + The `ScanResult.hosts` array may already be merged by the backend (app-scanner and agent path both updating the same `currentScan` and merging by IP with combined `sources`). The UI then maps `HostEntry[]` to `EnvironmentTableData[]` and sets `scan_sources = host.sources || []`. + +2. **Environment summary (API):** + When the UI fetches the environment host list (e.g. `host.getEnvironmentSummary`), the API returns rows that may include a `sources` (or `scan_sources`) field per host. The UI maps that to `EnvironmentTableData.scan_sources`. + +3. **Deduplication by IP:** + If the UI ever receives multiple rows for the same IP (e.g. from different endpoints), it should merge them into one row and combine `scan_sources` (union of all source arrays) so that the table shows one row per host with all sources that discovered it. + +--- + +## Source Display: SourceIcon and SourceIconRow + +The UI provides two components for showing scan source(s): + +### SourceIcon (single source) + +- **Purpose:** Renders one scan source (e.g. `"network"` or `"agent"`) as an icon with optional label and tooltip. +- **Usage:** ``, ``. +- **Registry:** `SOURCE_ICON_REGISTRY` maps source keys to icon, color, and label (e.g. `agent` → Bot icon, cyan; `network` → Wifi icon, violet). + +### SourceIconRow (multiple sources) + +- **Purpose:** Renders a row of icons for all sources that discovered a host (or finding). +- **Usage:** ``. +- **Behavior:** Renders one `SourceIcon` per entry in `sources`; tooltip/title can show a combined label (e.g. "Agent + Network"). + +**Example in host table column:** + +- Accessor: `row.scan_sources ?? (row.scan_source ? [row.scan_source] : [])`. +- Cell: ``. + +This gives users a clear view of which scan methods discovered each host (network-only, agent-only, or both). + +--- + +## Summary + +- **Canonical host identity:** IP address. +- **Multi-source attribution:** Hosts carry `sources` (backend) / `scan_sources` (UI) listing every scan method that discovered them. +- **EnvironmentTableData:** Prefer `scan_sources: string[]`; support legacy `scan_source` by normalizing to an array. +- **UI merge:** One row per IP; `scan_sources` = union of sources for that IP. +- **Display:** Use **SourceIcon** for a single source and **SourceIconRow** for the list of sources on a host (or vulnerability) row. + +--- + +**Related Documentation** + +- [ARCHITECTURE.scanner-data-flow.md](./ARCHITECTURE.scanner-data-flow.md) – How host data flows from scanners into ValKey and to the UI +- [ARCHITECTURE.sub-scans.md](./ARCHITECTURE.sub-scans.md) – How network and agent sub-scans contribute hosts + +--- + +**Last Updated:** 2025-02-07 +**Version:** 1.0.0 +**Maintainer:** Sirius Team diff --git a/documentation/dev/apps/scanner/ARCHITECTURE.scanner-data-flow.md b/documentation/dev/apps/scanner/ARCHITECTURE.scanner-data-flow.md new file mode 100644 index 0000000..edfcd4d --- /dev/null +++ b/documentation/dev/apps/scanner/ARCHITECTURE.scanner-data-flow.md @@ -0,0 +1,156 @@ +--- +title: "Scanner Data Flow - End-to-End Architecture" +description: "End-to-end data flow from UI scan initiation through network/agent scans to result display and persistence." +template: "TEMPLATE.custom" +version: "1.0.0" +last_updated: "2025-02-07" +author: "Sirius Team" +tags: ["scanner", "data-flow", "architecture", "valkey", "rabbitmq", "grpc"] +categories: ["architecture", "scanner"] +difficulty: "intermediate" +prerequisites: ["README.scanner.md"] +related_docs: + - "documentation/dev/apps/scanner/README.scanner.md" + - "documentation/dev/apps/scanner/ARCHITECTURE.sub-scans.md" + - "documentation/dev/apps/scanner/ARCHITECTURE.host-deduplication.md" + - "documentation/dev/architecture/README.architecture.md" +dependencies: [] +llm_context: "high" +search_keywords: + - "scanner data flow" + - "scan initiation" + - "ValKey currentScan" + - "network scan flow" + - "agent scan flow" + - "scan persistence" +--- + +# Scanner Data Flow – End-to-End Architecture + +This document describes the end-to-end data flow of the Sirius scanner system from the moment a user starts a scan in the UI until results are displayed and optionally persisted. + +## Overview + +The scanner system uses a **single live scan state** stored in ValKey under the key `currentScan`. The UI initiates scans via tRPC, triggers one or more sub-scans (network and/or agent), and polls ValKey for progress. When scans complete, results can be persisted from ValKey through go-api into PostgreSQL. + +**Components involved:** + +- **sirius-ui** (Next.js): Initiates scans, polls for results, displays hosts and vulnerabilities +- **go-api** (Go): REST API and persistence; can proxy queue/store or be called for cancel/persist +- **app-scanner** (Go): Network scanning; consumes from RabbitMQ, updates ValKey +- **app-agent** (Go): Agent-based scanning via gRPC; runs templates on remote hosts, results flow to ValKey +- **ValKey**: Stores live scan result as `currentScan` (base64-encoded JSON) +- **RabbitMQ**: Message queue between API/UI and app-scanner for network scan requests + +--- + +## Network Scan Flow + +1. **UI** – User configures targets and scan options, clicks “Start Scan”. +2. **tRPC** – UI calls `queue.sendMsg` (and optionally scanner/start endpoints) and `store.setValue` with key `currentScan` to write initial `ScanResult` (id, status, targets, empty hosts/vulnerabilities, `sub_scans.network`). +3. **go-api / Queue** – Scan request (id, targets, options, priority) is published to the **RabbitMQ** `scan` queue (either via go-api or via tRPC router in sirius-ui that publishes to RabbitMQ). +4. **app-scanner** – Consumes the message from the `scan` queue, expands targets to IPs, runs the scan pipeline (e.g. enumeration → discovery → vulnerability), and for each host/vulnerability discovered: + - Reads current `currentScan` from ValKey (or receives it in context), + - Merges new hosts/vulnerabilities and updates progress, + - Writes updated `ScanResult` back to ValKey key `currentScan`. +5. **UI polling** – `useScanResults` polls `store.getValue({ key: "currentScan" })` (e.g. every 3s). The tRPC store router reads from ValKey and returns the value; UI decodes the base64 JSON and updates hosts/vulnerabilities for display. + +So: **UI → tRPC → go-api (or tRPC) → RabbitMQ → app-scanner → ValKey → UI polling (tRPC store.getValue → ValKey).** + +--- + +## Agent Scan Flow + +1. **UI** – Same scan start; if agent scan is enabled, UI builds `sub_scans.agent` (status `dispatching`, progress 0/0) and writes initial `ScanResult` to ValKey via `store.setValue` with key `currentScan`. +2. **tRPC** – UI calls `agentScan.dispatchAgentScan` with scan id and agent scan config. +3. **go-api / gRPC** – go-api (or backend invoked by tRPC) uses **gRPC** to communicate with **app-agent** to dispatch template scans to connected agents. +4. **app-agent** – Runs templates on remote hosts, collects results, and reports back (e.g. via gRPC or callback to API). The component that holds the “current scan” state (e.g. go-api or a worker) updates the `currentScan` value in **ValKey**: merges agent-discovered hosts and vulnerabilities, updates `sub_scans.agent` status and progress. +5. **UI polling** – Same as network: UI polls `store.getValue("currentScan")`, decodes the result, and displays agent-origin hosts and vulnerabilities (with source attribution). + +So: **UI → tRPC → go-api → gRPC → app-agent → (results) → ValKey → UI polling.** + +--- + +## Persistence: ValKey (Live) → go-api → PostgreSQL + +- **Live state** – The only source of truth during an active scan is ValKey key `currentScan`. All sub-scans (network, agent) read-modify-write this key to add hosts, vulnerabilities, and progress. +- **Persistent state** – After a scan completes (or on demand), the API layer can: + - Read the final `ScanResult` from ValKey (`currentScan`), + - Map hosts and vulnerabilities to the persistent model, + - Write to **PostgreSQL** via go-api (hosts, vulnerabilities, scan_sources, etc.). + +So: **ValKey (live) → go-api → PostgreSQL (persistent).** The UI can show live data from ValKey and, for history/reporting, data from go-api/PostgreSQL. + +--- + +## Sequence Diagram (Mermaid) + +```mermaid +sequenceDiagram + participant UI as sirius-ui + participant tRPC as tRPC (Next.js) + participant API as go-api + participant RMQ as RabbitMQ + participant Scanner as app-scanner + participant Valkey as ValKey + participant gRPC as gRPC + participant Agent as app-agent + participant DB as PostgreSQL + + UI->>tRPC: Start scan (targets, options) + tRPC->>Valkey: setValue("currentScan", initial ScanResult) + tRPC->>API: (optional) start / queue + API->>RMQ: Publish scan message (network) + tRPC->>API: dispatchAgentScan (if agent enabled) + API->>gRPC: Dispatch to agents + gRPC->>Agent: Run templates on hosts + + loop Network scan + Scanner->>RMQ: Consume scan message + Scanner->>Scanner: Expand targets, run phases + Scanner->>Valkey: Get currentScan + Scanner->>Valkey: Set currentScan (merge hosts/vulns) + end + + loop Agent scan + Agent->>Agent: Execute templates + Agent->>API: Report results (or via gRPC) + API->>Valkey: Get currentScan + API->>Valkey: Set currentScan (merge agent results) + end + + loop UI polling (e.g. every 3s) + UI->>tRPC: getValue("currentScan") + tRPC->>Valkey: GET currentScan + Valkey-->>tRPC: base64 ScanResult + tRPC-->>UI: ScanResult + UI->>UI: Decode, update hosts/vulnerabilities + end + + note over API,DB: On completion or on demand + API->>Valkey: GET currentScan + Valkey-->>API: ScanResult + API->>DB: Persist hosts, vulnerabilities, sources +``` + +--- + +## Key Data Structures + +- **ValKey key:** `currentScan` (string value = base64-encoded JSON). +- **ScanResult (JSON):** `id`, `status`, `targets`, `hosts` (array of `HostEntry` with `id`, `ip`, `hostname`, `sources`), `hosts_completed`, `vulnerabilities`, `start_time`, `end_time`, `sub_scans` (map of sub-scan key → `SubScan`). +- **SubScan:** `type`, `enabled`, `status`, `progress` (`completed`, `total`, `label`), `metadata` (optional). Used for both network and agent sub-scans. + +--- + +## Related Documentation + +- [ARCHITECTURE.sub-scans.md](./ARCHITECTURE.sub-scans.md) – Sub-scan lifecycle and progress aggregation +- [ARCHITECTURE.host-deduplication.md](./ARCHITECTURE.host-deduplication.md) – How hosts from multiple sources are merged and displayed +- [README.scanner.md](./README.scanner.md) – Scanner engine details (message format, strategies, ValKey usage) + +--- + +**Last Updated:** 2025-02-07 +**Version:** 1.0.0 +**Maintainer:** Sirius Team diff --git a/documentation/dev/apps/scanner/ARCHITECTURE.sub-scans.md b/documentation/dev/apps/scanner/ARCHITECTURE.sub-scans.md new file mode 100644 index 0000000..124e0f4 --- /dev/null +++ b/documentation/dev/apps/scanner/ARCHITECTURE.sub-scans.md @@ -0,0 +1,185 @@ +--- +title: "Sub-Scans Architecture - Modular Scan Methods" +description: "Independent scan methods (network, agent) running in parallel, their data structure, lifecycle, progress aggregation, and cancellation." +template: "TEMPLATE.custom" +version: "1.0.0" +last_updated: "2025-02-07" +author: "Sirius Team" +tags: ["scanner", "sub-scan", "architecture", "progress", "cancellation"] +categories: ["architecture", "scanner"] +difficulty: "intermediate" +prerequisites: ["README.scanner.md"] +related_docs: + - "documentation/dev/apps/scanner/README.scanner.md" + - "documentation/dev/apps/scanner/ARCHITECTURE.scanner-data-flow.md" + - "documentation/dev/apps/scanner/ARCHITECTURE.host-deduplication.md" +dependencies: [] +llm_context: "high" +search_keywords: + - "sub-scan" + - "sub_scans" + - "scan progress" + - "network agent parallel" + - "scan cancellation" + - "SubScan" +--- + +# Sub-Scans Architecture + +The Sirius scanner uses a **sub-scan architecture**: each scan method (e.g. network, agent) is an independent **sub-scan** with its own status and progress. Sub-scans run in parallel and are tracked in a single `ScanResult` via a registry map. + +## What Are Sub-Scans? + +**Sub-scans** are independent scan methods that contribute to one logical “scan”: + +- **network** – Traditional network scanning (e.g. Nmap, RustScan, Naabu) triggered via RabbitMQ and executed by app-scanner. +- **agent** – Agent-based scanning: templates run on remote hosts via app-agent over gRPC. + +A scan can have zero, one, or both enabled. Each sub-scan has its own: + +- Lifecycle state (e.g. dispatching → running → completed/failed/cancelled) +- Progress (e.g. completed/total hosts or agents) +- Optional metadata (e.g. agent list, per-agent status for agent sub-scan) + +The overall scan state is the union of all sub-scan states and their results (hosts/vulnerabilities are merged at the scan level). + +--- + +## Sub-Scan Data Structure + +### Go (go-api / shared types) + +```go +// SubScanProgress tracks completion progress for a sub-scan. +type SubScanProgress struct { + Completed int `json:"completed"` + Total int `json:"total"` + Label string `json:"label,omitempty"` // e.g. "hosts", "agents" +} + +// SubScan represents a modular scanner contribution to a scan. +// Metadata is json.RawMessage so other scanners preserve it on read-modify-write. +type SubScan struct { + Type string `json:"type"` // "network", "agent" + Enabled bool `json:"enabled"` + Status string `json:"status"` // see Lifecycle states + Progress SubScanProgress `json:"progress"` + Metadata json.RawMessage `json:"metadata,omitempty"` +} + +// ScanResult holds the top-level scan and a registry of sub-scans. +type ScanResult struct { + ID string + Status string + Targets []string + Hosts []HostEntry + HostsCompleted int + Vulnerabilities []VulnerabilitySummary + StartTime string + EndTime string + SubScans map[string]SubScan `json:"sub_scans,omitempty"` +} +``` + +### TypeScript (sirius-ui) + +```ts +interface SubScanProgress { + completed: number; + total: number; + label?: string; +} + +interface SubScan { + type: string; + enabled: boolean; + status: "pending" | "dispatching" | "running" | "completed" | "failed"; + progress: SubScanProgress; + metadata?: Record; +} + +// ScanResult.sub_scans: Record +``` + +Agent-specific metadata in `SubScan.metadata` can include `mode`, `dispatched_agents`, `agent_statuses` (per-agent status, hosts/vulns found, etc.). + +--- + +## Sub-Scan Registry Pattern + +Sub-scans are stored in a **map keyed by scanner identifier**: + +- `map[string]SubScan` in Go (`sub_scans` in JSON) +- `Record` in TypeScript + +Common keys: + +- `"network"` – Network scan (app-scanner). +- `"agent"` – Agent scan (app-agent). + +Only enabled methods are present. When starting a scan, the UI (or API) builds this map (e.g. `subScans["network"]`, `subScans["agent"]`) and writes the initial `ScanResult` to ValKey. Consumers (app-scanner, go-api/agent path) update only their own key when merging back into `currentScan`, preserving other keys and `metadata` they don’t understand. + +--- + +## Lifecycle States + +Each sub-scan moves through a small set of states: + +| State | Meaning | +|---------------|--------| +| `pending` | Not yet started (optional; may go straight to dispatching). | +| `dispatching` | Work is being dispatched (e.g. message to RabbitMQ, or gRPC dispatch to agents). | +| `running` | Actively running (targets being scanned, agents executing templates). | +| `completed` | Finished successfully. | +| `failed` | Finished with error. | +| `cancelled` | Stopped by user or system. | + +The **overall scan** `status` is typically derived from sub-scans (e.g. “running” if any sub-scan is dispatching or running, “completed” when all are completed/failed/cancelled). + +--- + +## Progress Aggregation + +- **Per sub-scan:** `progress.completed`, `progress.total`, and optional `progress.label` (e.g. "hosts", "agents"). Each scanner updates its own sub-scan’s progress when writing to ValKey. +- **Overall scan:** The UI (or API) can compute an aggregate, for example: + - Total progress = sum of `completed` across sub-scans, divided by sum of `total` (or 0 if no total). + - Or: “running” if any sub-scan has `status === "running"` or `"dispatching"`, and overall completion when all sub-scans are in a terminal state. + +The UI displays per–sub-scan progress (e.g. in `ScanStatus`) and can show an overall progress bar or status from these fields. + +--- + +## Cancellation Handling + +When the user cancels a scan: + +1. UI/API calls the cancel endpoint (e.g. `POST /api/v1/scans/cancel` with optional `scan_id`). +2. go-api (or the component that owns the scan) sets the overall scan and/or sub-scans to a terminal state (e.g. `cancelled`) and writes the updated `ScanResult` back to ValKey. +3. **Network:** Cancellation can be implemented by app-scanner checking a shared “cancelled” flag (e.g. from ValKey or a separate key) or by receiving a cancel message, then stopping workers and updating its sub-scan status to `cancelled` in `currentScan`. +4. **Agent:** go-api (or agent coordinator) can signal agents to stop and then set `sub_scans.agent.status` to `cancelled` when updating ValKey. + +So: **cancelling the scan** means ensuring all sub-scans are stopped and their status (and optionally the overall scan status) is set to `cancelled` in the same `currentScan` document. + +--- + +## Summary + +- **Sub-scans** = independent scan methods (network, agent) with their own status and progress. +- **Data structure:** `SubScan { type, enabled, status, progress, metadata }` in a `map[string]SubScan` (`sub_scans`). +- **Lifecycle:** dispatching → running → completed | failed | cancelled. +- **Progress:** per–sub-scan `completed`/`total`; overall progress can be aggregated from all sub-scans. +- **Cancellation:** cancel request stops all sub-scans and updates their status (and overall scan) in ValKey `currentScan`. +- **Registry:** Use a single `sub_scans` map; each scanner only updates its own key and preserves others’ `metadata`. + +--- + +**Related Documentation** + +- [ARCHITECTURE.scanner-data-flow.md](./ARCHITECTURE.scanner-data-flow.md) – How sub-scan results flow into ValKey and to the UI +- [ARCHITECTURE.host-deduplication.md](./ARCHITECTURE.host-deduplication.md) – How hosts from different sub-scans are merged by IP + +--- + +**Last Updated:** 2025-02-07 +**Version:** 1.0.0 +**Maintainer:** Sirius Team diff --git a/documentation/dev/apps/scanner/README.scanner.md b/documentation/dev/apps/scanner/README.scanner.md new file mode 100644 index 0000000..e87da8a --- /dev/null +++ b/documentation/dev/apps/scanner/README.scanner.md @@ -0,0 +1,2115 @@ +--- +title: "Sirius Scanner - Vulnerability Scanning Engine" +description: "Comprehensive documentation for the Sirius vulnerability scanning engine" +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-10-25" +author: "Sirius Team" +tags: ["scanner", "vulnerability", "nmap", "nse", "go", "rabbitmq"] +categories: ["backend", "security", "scanning"] +difficulty: "advanced" +prerequisites: ["Go 1.23+", "Docker", "RabbitMQ", "Nmap"] +related_docs: + - "documentation/dev/architecture/README.architecture.md" + - "documentation/dev/README.development.md" +dependencies: + - "../minor-projects/app-scanner" + - "../minor-projects/go-api" + - "../minor-projects/sirius-nse" +llm_context: "high" +search_keywords: + [ + "scanner", + "vulnerability", + "nmap", + "nse", + "rabbitmq", + "valkey", + "scanning-engine", + ] +--- + +# Sirius Scanner - Vulnerability Scanning Engine + +## Overview + +Sirius Scanner is a sophisticated, modular vulnerability scanning engine that orchestrates multiple security scanning tools (Nmap, RustScan, Naabu) through a message-driven architecture. Built in Go, it processes scan requests from RabbitMQ, executes multi-phase security assessments, and enriches vulnerability data with NVD information. + +**Key Features:** + +- **Message-Driven Architecture**: RabbitMQ-based scan request processing +- **Multi-Phase Scanning**: Enumeration → Discovery → Vulnerability assessment +- **Concurrent Processing**: Worker pool pattern for parallel target scanning +- **NSE Script Management**: Git-based synchronization with curated script repository +- **Template System**: Pre-configured and custom scan templates +- **Source Attribution**: Comprehensive tracking of scan origins and configurations +- **Real-Time Updates**: ValKey integration for live scan progress monitoring + +**Repository Location:** `../minor-projects/app-scanner` + +--- + +## Table of Contents + +1. [Core Architecture](#core-architecture) +2. [Scanning Strategies](#scanning-strategies) +3. [NSE Script Management](#nse-script-management) +4. [Template System](#template-system) +5. [Scan Message Format](#scan-message-format) +6. [Target Processing](#target-processing) +7. [Source Attribution System](#source-attribution-system) +8. [State Management](#state-management) +9. [Docker Integration](#docker-integration) +10. [Configuration Files](#configuration-files) +11. [Development Workflow](#development-workflow) +12. [Key Files Reference](#key-files-reference) +13. [ValKey Schema Reference](#valkey-schema-reference) +14. [Profile vs Template System](#profile-vs-template-system) +15. [RabbitMQ Message Schema](#rabbitmq-message-schema) + +--- + +## Core Architecture + +### Message-Driven Design + +The scanner operates as a **RabbitMQ consumer**, listening on the `scan` queue for incoming scan requests. This design enables: + +- **Asynchronous Processing**: Scans don't block the API +- **Load Distribution**: Multiple scanner instances can consume from the same queue +- **Fault Tolerance**: Failed scans can be retried without data loss +- **Priority Handling**: Scan requests include priority levels (1-5) + +**Entry Point:** + +```go +// main.go +func main() { + scanManager := scan.NewScanManager(kvStore, toolFactory, scanUpdater) + scanManager.ListenForScans() // Blocks, listening for RabbitMQ messages + select {} // Keep service running +} +``` + +### Multi-Phase Scanning Workflow + +Scans proceed through up to three phases based on `scan_types` configuration: + +``` +┌─────────────────┐ +│ Enumeration │ Naabu: Fast port enumeration (SYN scan) +│ (Optional) │ Output: List of open ports +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ Discovery │ RustScan: Rapid host/port discovery +│ (Optional) │ Output: Live hosts with open ports +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ Vulnerability │ Nmap + NSE: Deep vulnerability scanning +│ (Required) │ Output: CVEs, service versions, OS detection +└─────────────────┘ +``` + +**Phase Selection:** + +```json +{ + "options": { + "scan_types": ["enumeration", "discovery", "vulnerability"] + } +} +``` + +### Worker Pool Pattern + +The scanner uses a **concurrent worker pool** (default: 10 workers) to process multiple targets simultaneously: + +```go +// internal/scan/worker_pool.go +type WorkerPool struct { + workerCount int + taskQueue chan ScanTask + manager *ScanManager +} + +// Each worker runs in its own goroutine +func (wp *WorkerPool) worker(ctx context.Context, id int) { + for { + select { + case task := <-wp.taskQueue: + wp.manager.scanIP(task.IP) // Execute scan + case <-ctx.Done(): + return + } + } +} +``` + +**Benefits:** + +- **Parallel Execution**: Scan multiple IPs concurrently +- **Resource Control**: Limit concurrent scans to prevent system overload +- **Graceful Shutdown**: Context-based cancellation + +### Strategy Pattern + +The scanner implements the **Strategy Pattern** for pluggable scan tools: + +```go +// internal/scan/strategies.go +type ScanStrategy interface { + Execute(target string) (sirius.Host, error) +} + +// Implementations: +type NaabuStrategy struct { ... } // Port enumeration +type RustScanStrategy struct { ... } // Discovery +type NmapStrategy struct { ... } // Vulnerability scanning +``` + +**Advantages:** + +- **Extensibility**: Add new scanning tools without modifying core logic +- **Testability**: Mock strategies for unit testing +- **Flexibility**: Swap implementations based on requirements + +### Factory Pattern + +The `ScanToolFactory` dynamically creates appropriate strategies: + +```go +// internal/scan/factory.go +func (f *ScanToolFactory) CreateTool(toolType string) ScanStrategy { + switch toolType { + case "enumeration": + return &NaabuStrategy{...} + case "discovery": + return &RustScanStrategy{} + case "vulnerability": + return &NmapStrategy{...} + } +} +``` + +--- + +## Scanning Strategies + +### NaabuStrategy (Port Enumeration) + +**Purpose:** Fast, accurate port enumeration using ProjectDiscovery's Naabu. + +**Technology:** SYN-based port scanning (requires root/CAP_NET_RAW) + +**Configuration:** + +```go +type NaabuStrategy struct { + Ports string // Port range (e.g., "1-65535", "80,443,8080") + Retries int // Number of retry attempts +} +``` + +**Implementation Details:** + +- Uses `github.com/projectdiscovery/naabu/v2` library +- Default timeout: 5 seconds per host +- Returns error `ErrHostDown` if no open ports found +- Outputs `sirius.Host` with populated `Ports` array + +**Example Usage:** + +```go +strategy := &NaabuStrategy{ + Ports: "1-10000", + Retries: 3, +} +host, err := strategy.Execute("192.168.1.100") +// host.Ports: [{ID: 80, Protocol: "tcp", State: "open"}, ...] +``` + +**When to Use:** + +- Need comprehensive port enumeration +- Scanning large port ranges (1-65535) +- Require retry logic for unstable networks +- Want detailed port state information + +### RustScanStrategy (Discovery) + +**Purpose:** Ultra-fast port discovery for identifying live hosts. + +**Technology:** Adaptive multi-threaded port scanning (RustScan binary) + +**Configuration:** + +```go +type RustScanStrategy struct { + // Uses default RustScan settings + // Automatically adjusts thread count based on available resources +} +``` + +**Implementation Details:** + +- Executes `rustscan` binary via `exec.Command` +- Parses output to extract open ports +- Filters results: hosts with no open ports are skipped +- Much faster than Nmap for initial discovery (5-20x speedup) + +**Example Usage:** + +```go +strategy := &RustScanStrategy{} +host, err := strategy.Execute("192.168.1.100") +// host.Ports: [{ID: 22, ...}, {ID: 80, ...}, {ID: 443, ...}] +``` + +**When to Use:** + +- Scanning large IP ranges (entire subnets) +- Need rapid feedback on live hosts +- Initial reconnaissance phase +- Time-sensitive assessments + +### NmapStrategy (Vulnerability Scanning) + +**Purpose:** Deep vulnerability assessment with NSE script execution. + +**Technology:** Nmap with NSE (Nmap Scripting Engine) for CVE detection + +**Configuration:** + +```go +type NmapStrategy struct { + Protocols []string // Legacy: protocol-based selection (e.g., ["smb", "http"]) + ScriptList []string // Explicit script names (overrides Protocols) +} +``` + +**Implementation Details:** + +- **Script Selection:** + + - **Template-based**: Uses `EnabledScripts` from template + - **Protocol-based**: Selects scripts matching protocols (smb, http, ssh, ftp, rdp) + - **Wildcard**: `["*"]` runs all available NSE scripts + +- **Nmap Command Construction:** + +```bash +nmap -T4 -sV -Pn -p --script --script-args-file -oX - +``` + +- **CVE Extraction:** Parses Nmap XML output for CVE patterns +- **Vulnerability Enrichment:** Fetches CVE details from NVD API +- **Fallback Mechanism:** If script errors occur, retries with minimal safe scripts + +**Example Usage:** + +```go +// Template-based (recommended) +strategy := &NmapStrategy{ + ScriptList: []string{"vulners", "smb-vuln-ms17-010", "http-shellshock"}, +} + +// Protocol-based +strategy := &NmapStrategy{ + Protocols: []string{"smb", "http"}, +} + +host, err := strategy.Execute("192.168.1.100") +// host.Vulnerabilities: [{VID: "CVE-2017-0143", RiskScore: 9.3, ...}, ...] +``` + +**Script Processing:** + +1. **Execution**: Nmap runs selected NSE scripts against target +2. **Parsing**: Extract structured data from script output +3. **CVE Detection**: Regex matching for `CVE-YYYY-NNNNN` patterns +4. **Enrichment**: Query NVD API for descriptions, CVSS scores +5. **Deduplication**: Remove duplicate CVEs from different scripts + +**Fallback Scan:** + +If NSE scripts fail (e.g., script syntax errors), scanner automatically retries with minimal safe scripts: + +```go +safeScripts := []string{"banner", "http-title", "ssl-cert"} +``` + +**When to Use:** + +- Deep security assessment required +- Need CVE identification +- Service version detection +- OS fingerprinting +- Protocol-specific vulnerability checks + +--- + +## NSE Script Management + +The scanner maintains a curated collection of NSE scripts via the `sirius-nse` repository. + +### Repository Management (`internal/nse/repo.go`) + +**Purpose:** Git-based synchronization of NSE scripts. + +**Repository URL:** `https://github.com/SiriusScan/sirius-nse.git` + +**Local Path:** `/opt/sirius/nse/sirius-nse` (in Docker container) + +**Operations:** + +```go +type RepoManager struct { + BasePath string // /opt/sirius/nse/sirius-nse + RepoURL string // GitHub repository + gitOps GitOperations +} + +// Ensure repository exists and is up-to-date +func (rm *RepoManager) EnsureRepo() error { + if !rm.isGitRepo() { + // Clone on first run + return rm.gitOps.Clone(rm.RepoURL, rm.BasePath) + } + // Update existing repository + return rm.updateRepo() +} + +// Update: fetch + reset to origin/main +func (rm *RepoManager) updateRepo() error { + rm.gitOps.Fetch(rm.BasePath) + rm.gitOps.Reset(rm.BasePath) // Hard reset to origin/main + return nil +} +``` + +**Sync Timing:** + +- **Startup**: Syncs when `ScanManager` initializes +- **Before Scans**: Automatic sync before first scan (via `ListenForScans`) +- **Manual**: Can be triggered via management API (future) + +**Symlink Strategy:** + +Nmap's script directory is symlinked to sirius-nse: + +```dockerfile +# Dockerfile +RUN ln -sf /opt/sirius/nse/sirius-nse/scripts /usr/local/share/nmap/scripts +``` + +This ensures **only curated scripts** are available, preventing accidental execution of default Nmap scripts. + +### Script Selection (`internal/nse/script_selector.go`) + +**Purpose:** Select appropriate NSE scripts based on protocols or explicit list. + +**Manifest Structure:** + +```json +{ + "version": "1.0", + "scripts": [ + { + "name": "vulners", + "category": "vuln", + "protocols": ["*"] + }, + { + "name": "smb-vuln-ms17-010", + "category": "vuln", + "protocols": ["smb"] + } + ] +} +``` + +**Script Selection Logic:** + +```go +type ScriptSelector struct { + manifest *Manifest + blacklist map[string]bool +} + +// Build Nmap --script flag +func (ss *ScriptSelector) BuildNmapScriptFlag(protocols ...string) (string, error) { + if len(protocols) == 1 && protocols[0] == "*" { + // Return all non-blacklisted scripts + return ss.getAllScripts(), nil + } + + // Filter by protocols + scripts := []string{} + for _, script := range ss.manifest.Scripts { + if ss.matchesProtocol(script, protocols) && !ss.isBlacklisted(script.Name) { + scripts = append(scripts, script.Name) + } + } + + return strings.Join(scripts, ","), nil +} +``` + +**Protocol Matching:** + +- `*` (wildcard): Script applies to all protocols +- Exact match: `["smb"]` matches scripts with `protocols: ["smb"]` +- Multiple protocols: `["smb", "http"]` matches scripts with either protocol + +**Example:** + +```go +selector := nse.NewScriptSelector(manifest) +scriptFlag, _ := selector.BuildNmapScriptFlag("smb", "http") +// Result: "vulners,smb-vuln-ms17-010,smb-os-discovery,http-title,http-enum,..." +``` + +### Script Blacklist (`internal/nse/script_blacklist.go`) + +**Purpose:** Exclude problematic or slow scripts. + +**Blacklist Criteria:** + +- **False Positives**: Scripts with high FP rates +- **Performance**: Extremely slow scripts (>5 minutes per host) +- **Stability**: Scripts that crash or hang frequently +- **Compatibility**: Scripts incompatible with our environment + +**Example Blacklist:** + +```go +var DefaultBlacklist = map[string]bool{ + "broadcast-dhcp-discover": true, // Sends broadcasts + "firewalk": true, // Very slow + "http-slowloris-check": true, // DoS risk +} +``` + +**Blacklist Management:** + +- Centrally managed in `script_blacklist.go` +- Can be overridden via environment variables (future) +- Logged when scripts are excluded + +### Sync Manager (`internal/nse/sync.go`) + +**Purpose:** Coordinate NSE repository updates with scan operations. + +**Responsibilities:** + +1. **Pre-Scan Sync**: Ensure scripts are up-to-date before scanning +2. **Concurrency Control**: Prevent multiple simultaneous syncs +3. **Error Handling**: Log sync failures but don't block scans +4. **Context Awareness**: Respect context cancellation + +**Implementation:** + +```go +type SyncManager struct { + repoManager *RepoManager + kvStore store.KVStore + lastSync time.Time + syncMutex sync.Mutex +} + +func (sm *SyncManager) Sync(ctx context.Context) error { + sm.syncMutex.Lock() + defer sm.syncMutex.Unlock() + + // Skip if recently synced (within 1 hour) + if time.Since(sm.lastSync) < time.Hour { + return nil + } + + // Perform sync + if err := sm.repoManager.EnsureRepo(); err != nil { + return fmt.Errorf("failed to sync NSE repo: %w", err) + } + + sm.lastSync = time.Now() + return nil +} +``` + +**Sync Strategy:** + +- **Cooldown Period**: 1 hour between syncs +- **Non-Blocking**: Sync failures logged but don't prevent scans +- **Startup Sync**: Always sync on scanner startup + +--- + +## Template System + +Templates provide **pre-configured scan profiles** for common use cases. + +### Template Structure + +```go +type Template struct { + ID string // Unique identifier (e.g., "high-risk") + Name string // Human-readable name + Description string // Usage description + Type TemplateType // SystemTemplate or CustomTemplate + EnabledScripts []string // NSE scripts to run + ScanOptions TemplateOptions // Default scan options + CreatedAt time.Time + UpdatedAt time.Time +} + +type TemplateOptions struct { + ScanTypes []string // ["enumeration", "discovery", "vulnerability"] + PortRange string // "1-10000" + Aggressive bool // Enable aggressive scanning + MaxRetries int // Retry attempts + Parallel bool // Parallel target scanning + ExcludePorts []string // Ports to skip +} +``` + +### System Templates + +**Pre-defined templates initialized on startup:** + +#### 1. `high-risk` - Focused Critical Vulnerability Scan + +**Purpose:** Balanced scan focusing on high-impact vulnerabilities. + +**Scripts:** 10 carefully selected scripts + +```go +EnabledScripts: []string{ + "vulners", // CVE detection (highest value) + "smb-vuln-ms17-010", // EternalBlue + "http-shellshock", // Shellshock vulnerability + "http-vuln-cve2017-5638", // Apache Struts RCE + "banner", // Service identification + "http-title", // HTTP identification + "ssl-cert", // SSL certificate info + "http-enum", // HTTP path enumeration + "smb-os-discovery", // SMB OS detection + "ftp-anon", // Anonymous FTP access +} + +ScanOptions: { + ScanTypes: []string{"enumeration", "discovery", "vulnerability"}, + PortRange: "1-10000", + Aggressive: true, + MaxRetries: 3, + Parallel: true, +} +``` + +**Use Case:** Default scan for most security assessments. + +#### 2. `all` - Comprehensive Scan + +**Purpose:** Exhaustive scanning with all available NSE scripts. + +**Scripts:** All non-blacklisted scripts (wildcard) + +```go +EnabledScripts: []string{"*"} // Special marker + +ScanOptions: { + ScanTypes: []string{"enumeration", "discovery", "vulnerability"}, + PortRange: "1-65535", + Aggressive: true, + MaxRetries: 3, + Parallel: false, // Sequential for thoroughness +} +``` + +**Use Case:** Deep penetration testing, compliance audits. + +**Warning:** Can take hours per host. Use sparingly. + +#### 3. `quick` - Fast Scan + +**Purpose:** Rapid assessment with essential scripts. + +**Scripts:** 3 lightweight scripts + +```go +EnabledScripts: []string{ + "vulners", // CVE detection + "banner", // Service identification + "http-title", // HTTP identification +} + +ScanOptions: { + ScanTypes: []string{"enumeration", "vulnerability"}, + PortRange: "top500Ports", // Most common 500 ports + Aggressive: false, + MaxRetries: 2, + Parallel: true, +} +``` + +**Use Case:** Initial reconnaissance, time-sensitive scans. + +### Custom Templates + +**Users can create custom templates via UI (future) or API.** + +**Creation Example:** + +```go +template := &Template{ + ID: "web-app-scan", + Name: "Web Application Scan", + Description: "Focused scan for web application vulnerabilities", + Type: CustomTemplate, + EnabledScripts: []string{ + "vulners", + "http-enum", + "http-shellshock", + "http-sql-injection", + "ssl-cert", + }, + ScanOptions: TemplateOptions{ + ScanTypes: []string{"discovery", "vulnerability"}, + PortRange: "80,443,8080,8443", + Aggressive: false, + MaxRetries: 2, + Parallel: true, + }, +} + +templateManager.CreateTemplate(ctx, template) +``` + +**Template Operations:** + +```go +// Get template +template, err := templateManager.GetTemplate(ctx, "high-risk") + +// List all templates +templates, err := templateManager.ListTemplates(ctx) + +// Update custom template (system templates are immutable) +templateManager.UpdateTemplate(ctx, template) + +// Delete custom template +templateManager.DeleteTemplate(ctx, "my-template") +``` + +### Template Resolution + +**When a scan message includes `template_id`, the scanner:** + +1. **Fetches Template**: Retrieve from ValKey +2. **Applies Defaults**: Use template's `EnabledScripts` and `ScanOptions` +3. **Merges User Options**: User-provided options override template defaults +4. **Resolves Scripts**: Convert template script list to Nmap `--script` flag + +**Resolution Logic:** + +```go +func (sm *ScanManager) handleMessage(msg string) { + var scanMsg ScanMessage + json.Unmarshal([]byte(msg), &scanMsg) + + if scanMsg.Options.TemplateID != "" { + template, _ := sm.templateManager.GetTemplate(ctx, scanMsg.Options.TemplateID) + + // User options override template defaults + if scanMsg.Options.PortRange == "" { + scanMsg.Options.PortRange = template.ScanOptions.PortRange + } + if len(scanMsg.Options.ScanTypes) == 0 { + scanMsg.Options.ScanTypes = template.ScanOptions.ScanTypes + } + // ... merge other options + } + + sm.processTarget(scanMsg.Targets[0]) +} +``` + +**Priority:** User Options > Template Defaults > System Defaults + +--- + +## Scan Message Format + +Scan requests are **JSON messages** sent to the `scan` RabbitMQ queue. + +### Message Structure + +```go +type ScanMessage struct { + ID string // Unique scan identifier + Targets []Target // Targets to scan + Options ScanOptions // Scan configuration + Priority int // 1 (low) to 5 (high) + CallbackURL string // Optional webhook on completion +} + +type Target struct { + Value string // IP, range, CIDR, or hostname + Type TargetType // Target type identifier + Timeout int // Per-target timeout (seconds, optional) +} + +type TargetType string +const ( + SingleIP TargetType = "single_ip" // 192.168.1.1 + IPRange TargetType = "ip_range" // 192.168.1.1-192.168.1.254 + CIDR TargetType = "cidr" // 192.168.1.0/24 + DNSName TargetType = "dns_name" // example.com + DNSWildcard TargetType = "dns_wildcard" // *.example.com (TODO) +) + +type ScanOptions struct { + TemplateID string // Template to use (optional) + PortRange string // "1-65535", "80,443,8080" + Aggressive bool // Aggressive scanning mode + ExcludePorts []string // Ports to skip + ScanTypes []string // ["enumeration", "discovery", "vulnerability"] + MaxRetries int // Retry attempts + Parallel bool // Parallel target scanning +} +``` + +### Example Messages + +#### Simple Single-IP Scan + +```json +{ + "id": "scan-001", + "targets": [ + { + "value": "192.168.1.100", + "type": "single_ip" + } + ], + "options": { + "template_id": "high-risk", + "scan_types": ["vulnerability"] + }, + "priority": 3 +} +``` + +#### CIDR Range with Custom Options + +```json +{ + "id": "scan-002", + "targets": [ + { + "value": "192.168.1.0/24", + "type": "cidr" + } + ], + "options": { + "port_range": "1-10000", + "aggressive": true, + "scan_types": ["discovery", "vulnerability"], + "max_retries": 3, + "parallel": true + }, + "priority": 4 +} +``` + +#### Multi-Target Scan with Template + +```json +{ + "id": "scan-003", + "targets": [ + { + "value": "192.168.1.1", + "type": "single_ip" + }, + { + "value": "192.168.1.100-192.168.1.110", + "type": "ip_range" + }, + { + "value": "example.com", + "type": "dns_name" + } + ], + "options": { + "template_id": "quick", + "scan_types": ["enumeration", "vulnerability"] + }, + "priority": 2, + "callback_url": "https://api.example.com/scan-complete" +} +``` + +### Validation Rules + +**Required Fields:** + +- `id`: Must be unique (recommended: UUID) +- `targets`: At least one target +- `options.scan_types`: At least one scan type +- `priority`: 1-5 (inclusive) + +**Optional Fields:** + +- `template_id`: If omitted, uses system defaults +- `callback_url`: If provided, webhook POST on completion + +**Validation Errors:** + +```go +func (sm *ScanManager) validateScanMessage(msg *ScanMessage) error { + if len(msg.Targets) == 0 { + return fmt.Errorf("no targets specified") + } + if msg.Priority < 1 || msg.Priority > 5 { + return fmt.Errorf("invalid priority: must be between 1 and 5") + } + return nil +} +``` + +--- + +## Target Processing + +### Target Type Expansion + +The scanner **expands** targets into individual IPs for worker pool processing. + +#### Single IP + +**Format:** `192.168.1.100` + +**Processing:** Direct pass-through + +```go +case SingleIP: + if !validateIP(target.Value) { + return nil, fmt.Errorf("invalid IP address: %s", target.Value) + } + return []string{target.Value}, nil +``` + +#### IP Range + +**Format:** `192.168.1.1-192.168.1.254` + +**Processing:** Expand to all IPs in range + +```go +case IPRange: + return expandIPRange(target.Value) + // Returns: ["192.168.1.1", "192.168.1.2", ..., "192.168.1.254"] +``` + +**Implementation:** + +```go +func expandIPRange(rangeStr string) ([]string, error) { + parts := strings.Split(rangeStr, "-") + startIP := net.ParseIP(parts[0]) + endIP := net.ParseIP(parts[1]) + + // Iterate from startIP to endIP + ips := []string{} + for ip := startIP; !ip.Equal(endIP); ip = incrementIP(ip) { + ips = append(ips, ip.String()) + } + return ips, nil +} +``` + +#### CIDR Block + +**Format:** `192.168.1.0/24` + +**Processing:** Expand to all IPs in subnet (excluding network/broadcast) + +```go +case CIDR: + if !validateCIDR(target.Value) { + return nil, fmt.Errorf("invalid CIDR notation: %s", target.Value) + } + return expandCIDR(target.Value) + // Returns: ["192.168.1.1", "192.168.1.2", ..., "192.168.1.254"] +``` + +**Note:** Skips network address (`.0`) and broadcast address (`.255`) + +#### DNS Name + +**Format:** `example.com` + +**Processing:** DNS resolution to IP(s) + +```go +case DNSName: + ips, err := net.LookupIP(target.Value) + if err != nil { + return nil, fmt.Errorf("DNS lookup failed: %v", err) + } + result := make([]string, len(ips)) + for i, ip := range ips { + result[i] = ip.String() + } + return result, nil +``` + +**Handles:** + +- Multiple A/AAAA records (returns all IPs) +- IPv4 and IPv6 addresses +- DNS resolution failures (returns error) + +#### DNS Wildcard (TODO) + +**Format:** `*.example.com` + +**Status:** Not yet implemented + +**Planned Behavior:** + +1. Subdomain enumeration (via DNS brute-force or Certificate Transparency logs) +2. Resolution of discovered subdomains to IPs +3. Deduplication of IPs + +### Worker Pool Processing + +After expansion, each IP is **enqueued as a task**: + +```go +func (sm *ScanManager) processTarget(target Target) { + targetIPs, err := sm.prepareTarget(target) + if err != nil { + log.Printf("Failed to prepare target: %v", err) + return + } + + // Add each IP to worker pool queue + for _, ip := range targetIPs { + task := ScanTask{ + IP: ip, + Options: sm.currentScanOptions, + } + sm.workerPool.AddTask(task) + } +} +``` + +**Worker Pool Flow:** + +``` +Target Expansion + │ + ▼ +┌─────────────────┐ +│ Task Queue │ +│ (Channel) │ +└────────┬────────┘ + │ + ├─────► Worker 1 ──► scanIP(192.168.1.1) + ├─────► Worker 2 ──► scanIP(192.168.1.2) + ├─────► Worker 3 ──► scanIP(192.168.1.3) + │ ... + └─────► Worker 10 ─► scanIP(192.168.1.10) +``` + +--- + +## Source Attribution System + +The scanner implements **comprehensive source attribution** to track scan origins and configurations. + +### Purpose + +- **Audit Trail**: Who/what/when/how for each scan +- **Debugging**: Troubleshoot scanning issues with full context +- **Compliance**: Demonstrate due diligence in security assessments +- **Analytics**: Understand scanning patterns and effectiveness + +### Source Metadata + +```go +type ScanSource struct { + Name string // Tool name (e.g., "nmap", "rustscan", "naabu") + Version string // Tool version (e.g., "7.94") + Config string // Scan configuration (semicolon-separated key:value pairs) +} +``` + +### Configuration Tracking + +The scanner captures: + +**Scan Configuration:** + +- `ports`: Port range scanned +- `aggressive`: Aggressive mode enabled +- `types`: Scan types executed +- `exclude`: Excluded ports +- `template`: Template ID used + +**System Information:** + +- `host`: Hostname of scanning system +- `user`: User running scanner +- `scanner_id`: Unique scan identifier +- `go_version`: Go runtime version + +**Example Config String:** + +``` +ports:1-10000;aggressive:true;types:enumeration,discovery,vulnerability;template:high-risk;host:scanner-prod-01;user:siriususer;scanner_id:scan-abc123;go_version:go1.23.0 +``` + +### Version Detection + +Automatically detects scanning tool versions: + +```go +func (sm *ScanManager) detectScannerVersion(toolName string) string { + switch toolName { + case "nmap": + output, _ := exec.Command("nmap", "--version").Output() + // Parse: "Nmap version 7.94 ( https://nmap.org )" + return extractVersion(output) + case "rustscan": + output, _ := exec.Command("rustscan", "--version").Output() + // Parse: "rustscan 2.1.1" + return extractVersion(output) + case "naabu": + output, _ := exec.Command("naabu", "-version").Output() + return extractVersion(output) + } +} +``` + +### API Submission + +Results are submitted via **source-aware API endpoint**: + +```go +func (sm *ScanManager) submitHostWithSource(host sirius.Host, toolName string) error { + source := sm.createScanSource(toolName) + + request := SourcedHostRequest{ + Host: host, + Source: source, + } + + jsonData, _ := json.Marshal(request) + url := fmt.Sprintf("%s/host/with-source", sm.apiBaseURL) + resp, _ := http.Post(url, "application/json", bytes.NewBuffer(jsonData)) + + return nil +} +``` + +**API Endpoint:** `POST /host/with-source` + +**Request Body:** + +```json +{ + "host": { + "ip": "192.168.1.100", + "ports": [...], + "vulnerabilities": [...] + }, + "source": { + "name": "nmap", + "version": "7.94", + "config": "ports:1-10000;aggressive:true;template:high-risk;host:scanner-01;..." + } +} +``` + +### Database Storage + +The API stores source attribution in PostgreSQL: + +**Schema:** + +```sql +CREATE TABLE scan_sources ( + id SERIAL PRIMARY KEY, + name VARCHAR(255), + version VARCHAR(50), + config TEXT, + created_at TIMESTAMP DEFAULT NOW() +); + +CREATE TABLE hosts ( + id SERIAL PRIMARY KEY, + ip VARCHAR(45), + scan_source_id INTEGER REFERENCES scan_sources(id), + ... +); +``` + +This enables queries like: + +- "Show all vulnerabilities found by Nmap 7.94" +- "List scans using the 'high-risk' template" +- "Find hosts scanned from scanner-prod-01" + +--- + +## State Management + +The scanner maintains **real-time scan state** using two systems: + +### ValKey Integration + +**Purpose:** Live scan progress tracking for UI display. + +**Key Structure:** + +``` +scan: = { + "status": "running", + "start_time": "2025-10-25T10:30:00Z", + "end_time": null, + "hosts": ["192.168.1.1", "192.168.1.2", ...], + "hosts_completed": 45, + "vulnerabilities": [ + { + "id": "CVE-2017-0143", + "severity": "critical", + "title": "EternalBlue SMB RCE", + "description": "Remote code execution..." + } + ] +} +``` + +**Update Pattern:** + +```go +type ScanUpdater struct { + kvStore store.KVStore +} + +func (su *ScanUpdater) Update(ctx context.Context, updateFn func(*ScanResult) error) error { + // 1. Get current scan state from ValKey + current, _ := su.kvStore.GetValue(ctx, "scan:"+scanID) + + // 2. Apply update function + var scan ScanResult + json.Unmarshal([]byte(current.Message.Value), &scan) + updateFn(&scan) + + // 3. Write updated state back to ValKey + updated, _ := json.Marshal(scan) + su.kvStore.SetValue(ctx, "scan:"+scanID, string(updated)) + + return nil +} +``` + +**Update Events:** + +- **Discovery Complete:** Add host to `hosts` array +- **Host Complete:** Increment `hosts_completed` +- **Vulnerability Found:** Add to `vulnerabilities` array +- **Scan Complete:** Set `status = "completed"`, set `end_time` + +**Example Update:** + +```go +sm.scanUpdater.Update(ctx, func(scan *ScanResult) error { + scan.HostsCompleted++ + if scan.HostsCompleted >= len(scan.Hosts) { + scan.Status = "completed" + scan.EndTime = time.Now().Format(time.RFC3339) + } + return nil +}) +``` + +### Logging System + +**Purpose:** Structured audit trail for compliance and debugging. + +**Implementation:** RabbitMQ-based logging to `scanner_logs` queue. + +**Log Client:** + +```go +type LoggingClient struct { + queueName string // "scanner_logs" +} + +func (lc *LoggingClient) LogScanEvent(scanID, eventType, message string, metadata map[string]interface{}) { + logEntry := map[string]interface{}{ + "timestamp": time.Now().Format(time.RFC3339), + "scan_id": scanID, + "event_type": eventType, + "message": message, + "metadata": metadata, + } + + jsonData, _ := json.Marshal(logEntry) + queue.Publish("scanner_logs", string(jsonData)) +} +``` + +**Event Types:** + +| Event Type | Description | Metadata | +| --------------------- | ------------------------ | -------------------------------------------- | +| `scan_initiated` | Scan request received | targets_count, priority, template_id | +| `target_prepared` | Target expanded to IPs | target_value, target_type, ips_generated | +| `host_discovered` | Live host found | host_ip, ports, tool | +| `tool_execution` | Scanning tool completed | tool, duration, success, ports_found | +| `vulnerability_found` | CVE detected | host_ip, cve_id, severity, tool | +| `host_completed` | All phases done for host | host_ip, vulnerabilities_found | +| `scan_completed` | Entire scan finished | total_hosts, vulnerabilities_found, duration | +| `scan_error` | Error occurred | host_ip, error_type, error_message | + +**Example Log Entries:** + +```json +// scan_initiated +{ + "timestamp": "2025-10-25T10:30:00Z", + "scan_id": "scan-abc123", + "event_type": "scan_initiated", + "message": "Scan request received", + "metadata": { + "targets_count": 3, + "priority": 4, + "template_id": "high-risk" + } +} + +// vulnerability_found +{ + "timestamp": "2025-10-25T10:35:22Z", + "scan_id": "scan-abc123", + "event_type": "vulnerability_found", + "message": "CVE detected", + "metadata": { + "host_ip": "192.168.1.100", + "cve_id": "CVE-2017-0143", + "severity": "critical", + "tool": "nmap" + } +} +``` + +**Log Consumption:** + +- **Elasticsearch**: Indexing for search/analytics +- **File**: JSON lines for long-term storage +- **Monitoring**: Real-time alerting on errors + +--- + +## Docker Integration + +The scanner runs inside the `sirius-engine` container, which bundles multiple applications. + +### Dockerfile Architecture + +**Multi-Stage Build:** + +```dockerfile +# Stage 1: Builder +FROM golang:1.23-bullseye AS builder + +# Install build dependencies +RUN apt-get update && apt-get install -y \ + git ca-certificates build-essential libpcap-dev + +# Clone and build app-scanner +RUN git clone https://github.com/SiriusScan/app-scanner.git && \ + cd app-scanner && \ + CGO_ENABLED=1 GOOS=linux go build -ldflags="-w -s" -o scanner main.go + +# Stage 2: Runtime +FROM debian:bullseye-slim + +# Install runtime dependencies +RUN apt-get update && apt-get install -y \ + nmap \ # Nmap binary + rustscan \ # RustScan binary + libpcap0.8 \ # Packet capture library + git # For NSE repo cloning + +# Copy built scanner binary +COPY --from=builder /repos/app-scanner/scanner /app-scanner-src/scanner + +# Create NSE directory +RUN mkdir -p /opt/sirius/nse/sirius-nse + +# Symlink Nmap scripts to sirius-nse +RUN ln -sf /opt/sirius/nse/sirius-nse/scripts /usr/local/share/nmap/scripts +``` + +### Volume Mounts + +**Development Mode:** + +```yaml +# docker-compose.dev.yaml +services: + sirius-engine: + volumes: + - ../minor-projects/app-scanner:/app-scanner # Live code reload + - ../minor-projects/go-api:/go-api + - ../minor-projects/sirius-nse:/sirius-nse +``` + +**Production Mode:** + +No volume mounts. Uses pre-compiled binary at `/app-scanner-src/scanner`. + +### Startup Script + +The scanner is started by `start-enhanced.sh`: + +```bash +#!/bin/bash + +# Development mode: run from source with live reload +if [ "$GO_ENV" = "development" ] && [ -d "/app-scanner" ]; then + echo "Starting scanner in development mode..." + cd /app-scanner + air -c .air.toml & # Live reload with air +fi + +# Production mode: run pre-compiled binary +if [ ! "$GO_ENV" = "development" ]; then + echo "Starting scanner in production mode..." + /app-scanner-src/scanner & +fi + +# Keep container running +wait +``` + +### NSE Script Installation + +**Automatic on Startup:** + +The `SyncManager` automatically clones/updates the `sirius-nse` repository when `ListenForScans()` is called: + +```go +func (sm *ScanManager) ListenForScans() { + // Sync NSE scripts before listening + if err := sm.nseSync.Sync(sm.ctx); err != nil { + log.Printf("Warning: failed to sync NSE scripts: %v", err) + // Continue anyway - may use cached scripts + } + + queue.Listen("scan", sm.handleMessage) +} +``` + +**Fallback:** If sync fails, uses existing scripts from `/opt/sirius/nse/sirius-nse`. + +### Environment Variables + +```bash +# Scanner configuration +SIRIUS_API_URL=http://sirius-api:9001 # API endpoint for results +RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/ +VALKEY_HOST=sirius-valkey +VALKEY_PORT=6379 + +# Development settings +GO_ENV=development # Enable dev mode +``` + +--- + +## Configuration Files + +### manifest.json + +**Location:** `/app-scanner/manifest.json` + +**Purpose:** Reference to external repositories (sirius-nse). + +**Structure:** + +```json +{ + "repositories": [ + { + "name": "sirius-nse", + "url": "https://github.com/SiriusScan/sirius-nse.git" + } + ] +} +``` + +**Usage:** Read by installer scripts or future auto-update mechanisms. + +### nmap-args/args.txt + +**Location:** `/app-scanner/nmap-args/args.txt` (or `/opt/sirius/nse/sirius-nse/scripts/args.txt`) + +**Purpose:** Default arguments for NSE scripts. + +**Example Content:** + +``` +# Vulners script configuration +vulners.showall=false + +# HTTP scripts +http.useragent=Sirius Scanner/1.0 + +# SMB scripts +smbdomain=WORKGROUP +smbusername=guest +smbpassword= + +# Timing +timeout=30000 +``` + +**Usage:** Passed to Nmap via `--script-args-file` flag. + +**Path Resolution:** + +```go +argsFilePaths := []string{ + "/opt/sirius/nse/sirius-nse/scripts/args.txt", + "/app-scanner/nmap-args/args.txt", + "/app-scanner-src/nmap-args/args.txt", + "nmap-args/args.txt", +} + +// Use first existing file +for _, path := range argsFilePaths { + if _, err := os.Stat(path); err == nil { + argsFilePath = path + break + } +} +``` + +### .air.toml + +**Location:** `/app-scanner/.air.toml` + +**Purpose:** Live reload configuration for development. + +**Key Settings:** + +```toml +[build] + cmd = "go build -o ./tmp/scanner main.go" + bin = "./tmp/scanner" + include_ext = ["go", "tpl", "tmpl", "html"] + exclude_dir = ["tmp", "vendor", "testdata"] + delay = 1000 # 1 second delay before rebuild + +[log] + time = true +``` + +**Usage:** Automatically watches for file changes and rebuilds/restarts scanner. + +--- + +## Development Workflow + +### Running Tests + +**Unit Tests:** + +```bash +cd /app-scanner +go test ./internal/scan/... -v + +# Specific test +go test ./internal/scan/ -run TestScanToolFactory -v + +# With coverage +go test ./internal/scan/... -cover -coverprofile=coverage.out +go tool cover -html=coverage.out +``` + +**Integration Tests:** + +```bash +# Full scan test (requires running infrastructure) +go run cmd/scan-full-test/main.go +``` + +### Manual Scan Testing + +**Test Commands:** + +```bash +# Direct Nmap test +cd cmd/direct-nmap-test +go run main.go + +# NSE script test +cd cmd/nse-test +go run main.go + +# Validate NSE script fixes +cd cmd/validate-nse-fix +go run main.go +``` + +### Debugging NSE Scripts + +**Check Script Availability:** + +```bash +docker exec sirius-engine nmap --script-help vulners +``` + +**Test Script Manually:** + +```bash +docker exec sirius-engine nmap -sV --script vulners 192.168.1.100 +``` + +**View NSE Repository:** + +```bash +docker exec sirius-engine ls -la /opt/sirius/nse/sirius-nse/scripts/ +``` + +**Check Symlink:** + +```bash +docker exec sirius-engine ls -la /usr/local/share/nmap/scripts +# Should point to: /opt/sirius/nse/sirius-nse/scripts +``` + +### Live Reload Development + +**Development Mode:** + +1. Edit code in `../minor-projects/app-scanner` +2. Air detects changes and rebuilds +3. Scanner restarts automatically +4. Logs visible in `docker logs -f sirius-engine` + +**Watch Logs:** + +```bash +# Scanner logs +docker logs -f sirius-engine | grep scanner + +# RabbitMQ messages +docker exec sirius-rabbitmq rabbitmqctl list_queues name messages + +# ValKey scan state +docker exec sirius-valkey valkey-cli GET scan:scan-abc123 +``` + +### Adding New Scan Strategies + +**Step 1: Implement Strategy Interface** + +```go +// internal/scan/strategies.go +type MyNewStrategy struct { + CustomOption string +} + +func (s *MyNewStrategy) Execute(target string) (sirius.Host, error) { + // Your scanning logic here + return host, nil +} +``` + +**Step 2: Update Factory** + +```go +// internal/scan/factory.go +func (f *ScanToolFactory) CreateTool(toolType string) ScanStrategy { + switch toolType { + case "my-new-tool": + return &MyNewStrategy{ + CustomOption: f.currentOptions.SomeOption, + } + // ... existing cases + } +} +``` + +**Step 3: Add to Scan Types** + +Update documentation and UI to include new scan type in `scan_types` options. + +**Step 4: Write Tests** + +```go +// internal/scan/strategies_test.go +func TestMyNewStrategy(t *testing.T) { + strategy := &MyNewStrategy{CustomOption: "test"} + host, err := strategy.Execute("192.168.1.100") + assert.NoError(t, err) + assert.NotEmpty(t, host.IP) +} +``` + +### Creating System Templates + +**Step 1: Define Template** + +```go +// internal/scan/template_manager.go +func (tm *TemplateManager) InitializeSystemTemplates(ctx context.Context) error { + templates := []Template{ + // ... existing templates + { + ID: "my-template", + Name: "My Custom Template", + Description: "Description of what this template does", + Type: SystemTemplate, + EnabledScripts: []string{ + "script1", + "script2", + }, + ScanOptions: TemplateOptions{ + ScanTypes: []string{"vulnerability"}, + PortRange: "1-1000", + Aggressive: false, + }, + }, + } + // ... create templates +} +``` + +**Step 2: Rebuild Scanner** + +```bash +cd /app-scanner +go build -o scanner main.go +``` + +**Step 3: Test Template** + +```json +{ + "id": "test-scan", + "targets": [{ "value": "192.168.1.100", "type": "single_ip" }], + "options": { "template_id": "my-template" }, + "priority": 3 +} +``` + +### Optimizing Scan Performance + +**Strategies:** + +1. **Adjust Worker Pool Size:** + +```go +// internal/scan/manager.go +const DEFAULT_WORKERS = 20 // Increase for more parallelism +``` + +2. **Reduce Port Range:** + +```json +{ "port_range": "1-1000" } // Instead of 1-65535 +``` + +3. **Limit NSE Scripts:** + +```json +{ "template_id": "quick" } // Use quick template +``` + +4. **Enable Parallel Processing:** + +```json +{ "parallel": true } +``` + +5. **Adjust Nmap Timing:** + +```go +// modules/nmap/nmap.go +args := []string{ + "-T5", // Insane timing (faster but less accurate) + // ... +} +``` + +--- + +## Key Files Reference + +| File | Lines | Purpose | +| ----------------------------------- | ----- | ------------------------------------------------------------------ | +| `main.go` | 37 | Application entry point, initializes ScanManager | +| `internal/scan/manager.go` | 783 | Core scan orchestration, RabbitMQ listener, worker pool | +| `internal/scan/strategies.go` | 164 | ScanStrategy interface and implementations (Naabu, RustScan, Nmap) | +| `internal/scan/factory.go` | 50 | Strategy factory for creating scan tools | +| `internal/scan/worker_pool.go` | ~150 | Concurrent worker pool for parallel scanning | +| `internal/scan/template_manager.go` | 413 | Template CRUD operations, system template initialization | +| `internal/scan/template_types.go` | ~100 | Template data structures | +| `internal/scan/updater.go` | ~150 | ValKey state update management | +| `internal/scan/logging.go` | ~200 | Structured logging to RabbitMQ | +| `internal/scan/helpers.go` | ~100 | Utility functions (severity calculation, etc.) | +| `internal/scan/network_helpers.go` | ~150 | IP/CIDR expansion, validation | +| `internal/nse/repo.go` | 138 | Git repository management for NSE scripts | +| `internal/nse/sync.go` | ~150 | NSE sync coordination | +| `internal/nse/script_selector.go` | ~200 | Protocol-based NSE script selection | +| `internal/nse/script_blacklist.go` | ~50 | Problematic script exclusion | +| `internal/nse/types.go` | ~100 | NSE data structures (Manifest, Script) | +| `modules/nmap/nmap.go` | 533 | Nmap integration, XML parsing, CVE extraction | +| `modules/rustscan/rustscan.go` | ~150 | RustScan integration | +| `modules/naabu/naabu.go` | ~150 | Naabu integration | + +**Total:** ~3,800 lines of application code + +--- + +## Code Examples + +### Sending a Scan Request + +**From Go:** + +```go +scanMsg := ScanMessage{ + ID: uuid.New().String(), + Targets: []Target{ + {Value: "192.168.1.0/24", Type: CIDR}, + }, + Options: ScanOptions{ + TemplateID: "high-risk", + ScanTypes: []string{"discovery", "vulnerability"}, + }, + Priority: 4, +} + +msgBytes, _ := json.Marshal(scanMsg) +queue.Publish("scan", string(msgBytes)) +``` + +**From CLI (RabbitMQ):** + +```bash +rabbitmqadmin publish exchange=amq.default \ + routing_key=scan \ + payload='{"id":"scan-123","targets":[{"value":"192.168.1.100","type":"single_ip"}],"options":{"template_id":"quick"},"priority":3}' +``` + +### Monitoring Scan Progress + +**ValKey Query:** + +```bash +docker exec sirius-valkey valkey-cli GET scan:scan-123 +``` + +**Output:** + +```json +{ + "status": "running", + "start_time": "2025-10-25T10:30:00Z", + "hosts": ["192.168.1.1", "192.168.1.2", "192.168.1.100"], + "hosts_completed": 2, + "vulnerabilities": [ + { + "id": "CVE-2017-0143", + "severity": "critical", + "title": "EternalBlue SMB RCE" + } + ] +} +``` + +--- + +## Troubleshooting + +### NSE Script Errors + +**Symptom:** "NSE: failed to initialize the script engine" + +**Causes:** + +- Script syntax errors +- Missing script dependencies +- Blacklisted scripts referenced + +**Solutions:** + +1. **Check script exists:** + +```bash +docker exec sirius-engine ls /opt/sirius/nse/sirius-nse/scripts/ | grep vulners +``` + +2. **Test script manually:** + +```bash +docker exec sirius-engine nmap --script-help vulners +``` + +3. **Check blacklist:** + +Review `internal/nse/script_blacklist.go` + +4. **Force repository sync:** + +```bash +docker exec sirius-engine rm -rf /opt/sirius/nse/sirius-nse +docker restart sirius-engine # Will re-clone on startup +``` + +### Scan Timeouts + +**Symptom:** Scans never complete, hosts stuck in "running" status + +**Causes:** + +- Network unreachability +- Firewall blocking scans +- Extremely large port ranges + +**Solutions:** + +1. **Reduce port range:** + +```json +{ "port_range": "1-1000" } // Instead of 1-65535 +``` + +2. **Enable aggressive mode:** + +```json +{ "aggressive": true } // Faster but more detectable +``` + +3. **Check network connectivity:** + +```bash +docker exec sirius-engine ping 192.168.1.100 +``` + +4. **View scanner logs:** + +```bash +docker logs -f sirius-engine | grep "ERROR\|Failed" +``` + +### Memory Issues + +**Symptom:** Scanner crashes with OOM (Out of Memory) errors + +**Causes:** + +- Too many concurrent workers +- Large target ranges without pagination +- Memory leaks in scanning tools + +**Solutions:** + +1. **Reduce worker pool size:** + +```go +const DEFAULT_WORKERS = 5 // Down from 10 +``` + +2. **Scan smaller ranges:** + +Split large CIDR blocks into smaller chunks. + +3. **Increase Docker memory:** + +```yaml +# docker-compose.yaml +services: + sirius-engine: + deploy: + resources: + limits: + memory: 4G # Increase from 2G +``` + +4. **Monitor memory usage:** + +```bash +docker stats sirius-engine +``` + +### RabbitMQ Disconnections + +**Symptom:** "Failed to consume from queue: connection closed" + +**Causes:** + +- RabbitMQ container crashed +- Network partition +- Connection timeout + +**Solutions:** + +1. **Check RabbitMQ status:** + +```bash +docker exec sirius-rabbitmq rabbitmqctl status +``` + +2. **Restart RabbitMQ:** + +```bash +docker restart sirius-rabbitmq +``` + +3. **Check connection string:** + +```bash +echo $RABBITMQ_URL +# Should be: amqp://guest:guest@sirius-rabbitmq:5672/ +``` + +4. **Implement reconnection logic (future):** + +Add automatic reconnection with exponential backoff. + +--- + +## Performance Benchmarks + +**Environment:** 4-core CPU, 8GB RAM, 1Gbps network + +| Scan Type | Target Range | Duration | Hosts/sec | +| --------------------- | ---------------------- | --------- | --------- | +| Quick (top 500 ports) | /24 subnet (254 hosts) | 3-5 min | ~50-80 | +| High-Risk | /24 subnet | 15-25 min | ~10-15 | +| All Scripts | /24 subnet | 2-4 hours | ~1-2 | +| Quick | Single host | 10-20 sec | N/A | +| High-Risk | Single host | 2-5 min | N/A | + +**Optimization Tips:** + +- **Parallelism:** Increase worker count for faster subnet scans +- **Port Range:** Limit to relevant ports (80, 443, 22, 3389) +- **Script Selection:** Use templates instead of wildcard `*` +- **Network:** Faster networks = faster scans (avoid VPNs) + +--- + +## Security Considerations + +### Responsible Scanning + +**Always:** + +- ✅ Get written authorization before scanning +- ✅ Use reasonable rate limiting (avoid DoS) +- ✅ Scan only approved IP ranges +- ✅ Document all scanning activities + +**Never:** + +- ❌ Scan production systems without approval +- ❌ Use aggressive mode on fragile systems +- ❌ Store vulnerability data in insecure locations +- ❌ Share scan results with unauthorized parties + +### Rate Limiting + +The scanner implements implicit rate limiting through: + +- **Worker Pool Size:** Limits concurrent scans +- **Nmap Timing:** `-T4` (balanced) by default, not `-T5` (insane) +- **Connection Limits:** Naabu respects system limits + +**Future Enhancements:** + +- Configurable rate limits (scans per second) +- Per-target rate limiting +- Adaptive throttling based on network conditions + +--- + +## Future Enhancements + +**Planned Features:** + +1. **DNS Wildcard Support:** Subdomain enumeration via CT logs +2. **Distributed Scanning:** Multiple scanner instances coordinating via ValKey +3. **Scan Scheduling:** Cron-based recurring scans +4. **Advanced Reporting:** PDF/HTML reports with executive summaries +5. **Machine Learning:** Anomaly detection for unusual scan results +6. **API Gateway Integration:** Direct scan triggering via REST API +7. **WebSocket Updates:** Real-time scan progress in UI +8. **Scan Comparison:** Diff scans to identify new vulnerabilities + +--- + +## ValKey Schema Reference + +ValKey (Redis-compatible) is used for live scan state. Key structure: + +- **`currentScan`** – Main key storing the live scan result as JSON. Contains the full `ScanResult` object with hosts, vulnerabilities, sub-scans, and progress. +- **Encoding:** JSON may be stored as a base64-encoded string in some contexts; decode with `b64Decode` from `~/utils/std.ts` when reading from the frontend. +- **Polling:** The frontend polls this key at regular intervals (5-second refetch) to display live progress. +- **TTL:** No TTL is set; the key persists until overwritten by the next scan. + +--- + +## Profile vs Template System + +- **Scan Profiles:** High-level presets that control overall scan behavior (e.g., "quick-scan", "full-scan", "agent-only"). Stored as `ScanProfile` type. They determine which scan methods are enabled and how they are configured. +- **Agent Templates:** Specific detection templates used by the agent scanner (e.g., checks for a specific CVE). Stored in the template system. They define detection steps such as `file_content`, `file_hash`, `file_search`, and `version_cmd`. The authoritative set is `KnownDetectionTypes` in `app-agent/internal/modules/detection_types.go` (drift-checked against the runtime registry by `detection_types_registry_test.go`). +- Profiles may reference templates but are not the same thing: profiles define *what* to run and *how*; templates define the concrete detection logic. + +--- + +## RabbitMQ Message Schema + +- **Queue:** Scan queue (consumed by app-scanner). +- **Message format:** JSON with target list and scan options. +- **Scan request contents:** Includes `targets`, `scan_types` configuration, and `agent_scan` configuration. +- **Results:** app-scanner writes results back to the ValKey `currentScan` key. + +--- + +## LLM Context + +This documentation is optimized for AI assistant context. Key information: + +**Architecture:** Message-driven (RabbitMQ), worker pool concurrency, strategy pattern for extensibility + +**Core Flow:** Receive scan message → Expand targets → Distribute to workers → Execute strategies → Enrich results → Submit to API + +**Key Components:** ScanManager (orchestration), ScanStrategies (tool integrations), TemplateManager (scan configs), NSE system (script management) + +**Integration Points:** RabbitMQ (input), ValKey (state), PostgreSQL (results), NVD API (CVE enrichment) + +**Development:** Go 1.23+, runs in sirius-engine container, live reload with Air, unit/integration tests + +**Common Tasks:** Add strategies (implement interface + factory), create templates (InitializeSystemTemplates), debug NSE (check symlinks/manifest) + +--- + +**Last Updated:** 2025-10-25 +**Version:** 1.0.0 +**Maintainer:** Sirius Team +**Repository:** https://github.com/SiriusScan/app-scanner diff --git a/documentation/dev/architecture/ADR.startup-secrets-model.md b/documentation/dev/architecture/ADR.startup-secrets-model.md new file mode 100644 index 0000000..c260136 --- /dev/null +++ b/documentation/dev/architecture/ADR.startup-secrets-model.md @@ -0,0 +1,50 @@ +--- +title: "ADR: Startup and Secrets Model" +description: "Architectural decision record for installer-first startup and stateless infrastructure API key validation." +template: "TEMPLATE.reference" +llm_context: "high" +categories: ["architecture", "security", "operations"] +tags: ["adr", "startup", "secrets", "apikey", "docker", "installer"] +related_docs: + - "README.auth-surface-matrix.md" + - "README.api-key-operations.md" + - "README.docker-container-deployment.md" +--- + +# ADR: Startup and Secrets Model + +## Status + +Accepted + +## Context + +Sirius startup historically depended on manual environment setup and a bootstrap pattern that could create drift between runtime configuration and persistent key state. The platform also tolerated insecure defaults in startup and seeding paths. + +## Decision + +1. **Installer-first startup**: a first-run installer is the canonical setup path for generating and merging required secrets/config. +2. **Internal service key path**: `SIRIUS_API_KEY_FILE` (Docker secret file mount, preferred) with `SIRIUS_API_KEY` as a migration fallback — both resolve to the same installer-generated internal key for service-to-service root authentication. +3. **Dynamic key lifecycle in Valkey**: user-generated API keys continue to be managed in Valkey. +4. **Secure fail-fast runtime**: production startup and seeding flows must fail when required secrets are missing. + +## Consequences + +### Positive + +- Deterministic behavior during restart and key rotation. +- Reduced operational complexity from bootstrap reconciliation state. +- Better first-time user experience with automated secret generation. +- Clear separation between infrastructure auth and user key lifecycle. + +### Tradeoffs + +- Stricter env requirements may break permissive legacy startup paths until migrated. +- CI/test and deployment scripts must be updated to provide required variables. + +## Implementation Notes + +- Use `docker-compose.installer.yaml` as the canonical installer entrypoint. +- Installer writes `secrets/sirius_api_key.txt` and sets `SIRIUS_API_KEY_FILE=/run/secrets/sirius_api_key` in `.env` alongside `SIRIUS_API_KEY` for compatibility. +- Ensure compose contracts explicitly require auth-critical variables (file and/or env). +- Update runbooks and deployment documentation in lockstep with runtime changes. diff --git a/documentation/dev/architecture/ARCHITECTURE.nse-repository-management.md b/documentation/dev/architecture/ARCHITECTURE.nse-repository-management.md new file mode 100644 index 0000000..499011a --- /dev/null +++ b/documentation/dev/architecture/ARCHITECTURE.nse-repository-management.md @@ -0,0 +1,441 @@ +--- +title: "NSE Repository Management Architecture" +description: "Comprehensive architectural documentation for the NSE (Nmap Scripting Engine) repository management system, explaining how the scanner manages repositories dynamically and syncs to ValKey as the source of truth" +template: "TEMPLATE.architecture" +version: "1.0.0" +last_updated: "2025-10-25" +author: "Sirius Team" +tags: + [ + "architecture", + "nse", + "repository-management", + "scanner", + "valkey", + "system-design", + ] +categories: ["development", "architecture", "security"] +difficulty: "advanced" +prerequisites: + - "README.architecture.md" + - "README.scanner.md" +related_docs: + - "README.architecture.md" + - "../apps/scanner/README.scanner.md" + - "../README.development.md" +dependencies: + - "../../minor-projects/app-scanner/internal/nse/" + - "../../minor-projects/sirius-nse/" +llm_context: "high" +search_keywords: + [ + "nse repository management", + "scanner architecture", + "valkey integration", + "dynamic repository", + "nmap scripts", + "runtime cloning", + ] +--- + +# NSE Repository Management Architecture + +## Purpose + +This document defines the architectural design for NSE (Nmap Scripting Engine) repository management in Sirius Scanner. It clarifies component responsibilities, data flow, and integration boundaries to prevent architectural misunderstandings. + +**Critical**: The scanner is the SOLE owner of NSE repository management. No other components should manage repositories via Dockerfile or file system mounts. + +## When to Use + +- **System Design**: When integrating with NSE scripts or scanner +- **Component Development**: When building UI/API features that consume NSE scripts +- **Code Review**: When reviewing scanner or UI/API integration code +- **Troubleshooting**: When diagnosing NSE script synchronization issues +- **Refactoring**: When making changes to repository management or script storage + +## How to Use + +### Quick Overview + +1. **Start with System Overview** to understand the runtime repository management model +2. **Review Component Architecture** to understand scanner vs UI vs ValKey responsibilities +3. **Check Integration Points** to see how components access scripts +4. **Reference Design Decisions** for rationale on ValKey as source of truth +5. **Follow Anti-Patterns** to avoid common architectural violations + +## What It Is + +### System Overview + +The NSE Repository Management system provides **dynamic, runtime management** of Nmap script repositories. The scanner clones and updates Git repositories at startup, synchronizes content to ValKey, and provides a read-only interface for UI and API components. + +**Key Characteristics:** + +- **Runtime Management**: Repositories cloned/updated at container startup +- **Multiple Repositories**: Supports arbitrary number of configured repositories +- **Single Source of Truth**: ValKey contains authoritative script data +- **Clean Boundaries**: Clear ownership prevents conflicts + +### Architectural Principles + +- **Separation of Concerns**: Scanner manages repos, ValKey stores data, UI/API read data +- **Single Source of Truth**: ValKey is the canonical source for all script data +- **Dynamic Configuration**: Add/remove repositories without rebuilding containers +- **Production Ready**: No host file system dependencies + +### Component Architecture + +#### Scanner (app-scanner) + +- **Purpose**: Manages NSE script repositories and synchronizes to ValKey +- **Responsibilities**: + - Clone Git repositories at runtime + - Update repositories on startup + - Parse repository manifests + - Sync script metadata and content to ValKey +- **Dependencies**: ValKey (write), Git repositories (read) +- **Interfaces**: ValKey keys (`nse:*`) +- **Location**: `../minor-projects/app-scanner/internal/nse/` + +**Key Components:** + +``` +internal/nse/ +├── repo.go # RepoManager - Git clone/update operations +├── sync.go # SyncManager - ValKey synchronization +├── types.go # Data structures and ValKey keys +└── README.md # Implementation documentation +``` + +#### ValKey + +- **Purpose**: Source of truth for NSE script data +- **Responsibilities**: + - Store repository manifest + - Store script manifest + - Store script content + - Provide read access to UI/API +- **Dependencies**: None (data store) +- **Interfaces**: Redis protocol +- **Keys**: + - `nse:repo-manifest` - Repository list configuration + - `nse:manifest` - Complete script manifest (612+ scripts) + - `nse:script:` - Individual script content + +#### UI (sirius-ui) + +- **Purpose**: Display scripts and manage scan profiles +- **Responsibilities**: + - Read scripts from ValKey + - Display script information to users + - Allow script selection for scan profiles +- **Dependencies**: ValKey (read-only) +- **Interfaces**: tRPC procedures reading from ValKey +- **Location**: `sirius-ui/src/server/api/routers/store.ts` + +**❌ NEVER**: + +- Read from file system (`/sirius-nse/`) +- Clone or manage repositories +- Populate ValKey with script data + +#### API (sirius-api) + +- **Purpose**: Serve script data to external consumers +- **Responsibilities**: + - Read scripts from ValKey + - Provide REST endpoints for script data +- **Dependencies**: ValKey (read-only) +- **Interfaces**: REST API + +**❌ NEVER**: + +- Read from file system +- Manage repositories + +### Data Flow + +#### Repository Synchronization Flow + +1. **Scanner Startup**: `main.go` creates `ScanManager` +2. **Initialize Managers**: Creates `RepoManager` and `SyncManager` +3. **Start Listening**: Calls `ListenForScans()` +4. **Sync Repositories**: `nseSync.Sync(ctx)` executes: + - Loads repository list from manifest or ValKey + - Clones repositories to `/opt/sirius/nse/` + - Reads local manifests from each repository + - Syncs to ValKey keys +5. **Ready**: Scripts available to UI/API via ValKey + +#### UI Script Access Flow + +1. **User Action**: Navigates to Scanner → Profiles +2. **UI Request**: Calls `getNseScripts` tRPC procedure +3. **ValKey Read**: Reads `nse:manifest` key +4. **Parse Manifest**: Extracts script list +5. **Display**: Shows 612 scripts to user + +#### Scan Execution Flow + +1. **User Action**: Creates scan with selected scripts +2. **Scanner Receives**: Gets scan request via RabbitMQ +3. **Script Selection**: Uses scripts from local repository +4. **Nmap Execution**: Runs Nmap with selected NSE scripts +5. **Results Storage**: Stores results in PostgreSQL + +### Integration Points + +#### Scanner → ValKey + +- **Type**: Redis protocol (write) +- **Purpose**: Sync repository data to source of truth +- **Protocol**: Redis SET commands +- **Data Format**: JSON-serialized manifests and script content +- **Keys Written**: + - `nse:repo-manifest` - Repository configuration + - `nse:manifest` - Script manifest + - `nse:script:` - Script content + +#### UI → ValKey + +- **Type**: Redis protocol (read-only) +- **Purpose**: Display scripts to users +- **Protocol**: Redis GET commands +- **Data Format**: JSON-serialized data +- **Keys Read**: + - `nse:manifest` - Script list + - `nse:script:` - Script details + +#### Scanner → Git Repositories + +- **Type**: Git protocol +- **Purpose**: Clone and update script repositories +- **Protocol**: `git clone`, `git fetch`, `git reset --hard` +- **Data Format**: Git repository +- **Locations**: `/opt/sirius/nse/` + +### Technology Stack + +#### Backend + +- **Go**: Scanner implementation language +- **Git**: Repository version control +- **ValKey/Redis**: Data storage and source of truth + +#### Frontend + +- **Next.js**: UI framework +- **tRPC**: Type-safe API layer +- **Valkey Client**: Redis client for script access + +#### Infrastructure + +- **Docker**: Container runtime +- **Docker Compose**: Multi-container orchestration +- **Volume Mounts**: Development-only, not for repositories + +### Design Decisions + +#### Decision 1: ValKey as Source of Truth + +- **Context**: Multiple components need access to NSE script data +- **Decision**: Use ValKey as canonical source instead of shared file system +- **Rationale**: + - Clean separation of concerns + - No file system dependencies + - Easy to scale (ValKey cluster) + - Supports production deployments + - UI/API don't need repository knowledge +- **Consequences**: + - Scanner must sync on startup + - ValKey becomes critical dependency + - All components read from ValKey + +#### Decision 2: Runtime Repository Management + +- **Context**: Need to support multiple repositories and dynamic updates +- **Decision**: Clone repositories at runtime instead of Dockerfile +- **Rationale**: + - Add/remove repositories without rebuilds + - Support arbitrary number of repositories + - Update repositories on restart + - Clean container images +- **Consequences**: + - Startup time includes git clone + - Network required for cloning + - Scanner owns repository lifecycle + +#### Decision 3: UI Read-Only Access + +- **Context**: UI needs to display scripts for profile management +- **Decision**: UI only reads from ValKey, never manages repositories +- **Rationale**: + - Clear ownership (scanner manages, UI displays) + - No duplicate repository logic + - UI can't corrupt scanner state + - Simpler UI implementation +- **Consequences**: + - UI depends on scanner having run + - No offline UI script management + - Scanner must be healthy + +### Security Considerations + +- **Repository Trust**: Only clone from trusted Git repositories +- **ValKey Access**: ValKey should not be publicly accessible +- **Script Validation**: Scripts are trusted (from official Nmap repository) +- **File System Permissions**: Scanner runs with minimal permissions + +### Performance Characteristics + +- **Startup Time**: ~5-10 seconds for git clone + sync (612 scripts) +- **Sync Performance**: ~1 second to sync manifest to ValKey +- **UI Query Performance**: <100ms to read from ValKey +- **Memory Usage**: ~50MB for repository storage + +### Scalability Considerations + +- **Multiple Repositories**: Linear scaling with repository count +- **Script Count**: ValKey handles thousands of scripts efficiently +- **Concurrent Access**: ValKey supports multiple readers +- **Container Replicas**: Each scanner manages own repository copy + +## Troubleshooting + +### FAQ + +**Q: Why doesn't the UI show any scripts?** +A: The scanner may not have started yet. The scanner syncs scripts to ValKey at startup via `ListenForScans()` → `Sync()`. Check scanner logs for sync messages. + +**Q: Can I add a volume mount for sirius-nse to the UI?** +A: **No**. This violates the architecture. The UI should ONLY read from ValKey. Adding a volume mount creates unnecessary coupling and doesn't work in production. + +**Q: How do I add a new NSE script repository?** +A: Update `app-scanner/internal/nse/manifest.json` or the `nse:repo-manifest` key in ValKey, then restart the scanner. It will automatically clone and sync the new repository. + +### Command Reference + +| Command | Purpose | Example | Notes | +| ------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------- | ------------------------------- | +| `docker exec sirius-valkey valkey-cli GET nse:manifest` | Check script manifest | `docker exec sirius-valkey valkey-cli GET nse:manifest \| jq '.scripts.length'` | Returns 612 if synced correctly | +| `docker logs sirius-engine \| grep -i nse` | Check scanner sync logs | `docker logs sirius-engine \| grep -i "sync\|nse"` | Shows sync progress | +| `docker exec sirius-engine ls /opt/sirius/nse/` | List cloned repositories | `docker exec sirius-engine ls -la /opt/sirius/nse/sirius-nse` | Verifies repository exists | +| `docker restart sirius-engine` | Force repository re-sync | `docker restart sirius-engine` | Re-clones and syncs all repos | +| `docker exec sirius-engine rm -rf /opt/sirius/nse/` | Clear repository cache | `docker exec sirius-engine rm -rf /opt/sirius/nse/sirius-nse` | Forces fresh clone on restart | + +### Common Issues + +| Issue | Symptoms | Root Cause | Solution | +| ----------------------------- | ------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------- | +| UI shows no scripts | Empty script list | Scanner hasn't synced or ValKey empty | Check scanner logs, restart scanner, verify ValKey keys | +| UI shows only 1 script | Fallback script displayed | UI tried to read file system instead of ValKey | Update UI code to read from ValKey (see `store.ts`) | +| Scanner fails to clone | "git clone failed" errors | Network issues or invalid repository URL | Check network, verify repository URL in manifest | +| Scripts not updating | Old scripts persist after repo update | Scanner cache not cleared | Restart scanner or manually delete `/opt/sirius/nse/` and restart | +| Production deployment failing | Container can't find scripts | Missing volume mount (wrong approach) | Remove volume mount, ensure scanner syncs to ValKey, UI reads from ValKey | + +### Debugging Steps + +1. **Check ValKey has scripts**: + + ```bash + docker exec sirius-valkey valkey-cli GET nse:manifest | jq '.scripts | length' + # Should return: 612 + ``` + +2. **Verify scanner synced**: + + ```bash + docker logs sirius-engine | grep -i "sync\|nse\|manifest" + # Should see: "Successfully initialized 612 NSE scripts" + ``` + +3. **Test UI reading from ValKey**: + + - Navigate to Scanner → Profiles + - Click "Initialize NSE Scripts" + - Should show: "Found 612 NSE scripts (synced by scanner)" + +4. **Review scanner startup**: + ```bash + docker logs sirius-engine --tail 100 + # Check for sync errors during startup + ``` + +## Anti-Patterns + +### ❌ NEVER DO THESE + +1. **Clone repositories in Dockerfile**: + + ```dockerfile + # ❌ WRONG - Breaks dynamic management + RUN git clone https://github.com/SiriusScan/sirius-nse.git /sirius-nse + ``` + +2. **Add volume mount for UI to read repositories**: + + ```yaml + # ❌ WRONG - Violates architecture boundaries + sirius-ui: + volumes: + - ../minor-projects/sirius-nse:/sirius-nse + ``` + +3. **Have UI read from file system**: + + ```typescript + // ❌ WRONG - UI should only read from ValKey + const manifestPath = "/sirius-nse/manifest.json"; + const data = fs.readFileSync(manifestPath); + ``` + +4. **Have UI populate ValKey**: + ```typescript + // ❌ WRONG - Scanner owns ValKey population + await valkey.set("nse:manifest", JSON.stringify(manifest)); + ``` + +### ✅ ALWAYS DO THESE + +1. **Let scanner manage repositories**: + + ```go + // ✅ CORRECT - Scanner manages at runtime + repoManager := nse.NewRepoManager("/opt/sirius/nse/sirius-nse", nse.NSERepoURL) + syncManager := nse.NewSyncManager(repoManager, kvStore) + ``` + +2. **Have UI read from ValKey**: + + ```typescript + // ✅ CORRECT - UI reads from ValKey + const manifestData = await valkey.get("nse:manifest"); + const manifest = JSON.parse(manifestData); + ``` + +3. **Use ValKey as integration point**: + ``` + Scanner (File System) → ValKey → UI/API (Read-Only) + ``` + +## Lessons Learned + +### 2025-10-25 - UI Should Never Manage Repositories + +**What happened**: UI was trying to read from file system (`/sirius-nse/manifest.json`) and populate ValKey, resulting in only 1 script being shown instead of 612. + +**Root cause**: Misunderstanding of architecture - assumed UI should manage repositories. + +**What we learned**: The scanner ALREADY populates ValKey with 612 scripts at startup. The UI should ONLY read from ValKey. This maintains clean separation of concerns and prevents duplication of repository management logic. + +**Impact**: + +- Removed unnecessary volume mount from UI +- Updated UI to read from ValKey only +- Added comprehensive architecture documentation +- Updated bot identity with clear integration boundaries + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/architecture/README.administrator.md b/documentation/dev/architecture/README.administrator.md new file mode 100644 index 0000000..fc2b3ba --- /dev/null +++ b/documentation/dev/architecture/README.administrator.md @@ -0,0 +1,41 @@ +--- +title: "Administrator Service Architecture" +description: "Architecture documentation for the Sirius administrator service" +template: "TEMPLATE.architecture" +llm_context: "medium" +categories: ["architecture", "services"] +tags: ["administrator", "admin", "management"] +related_docs: + - "README.system-monitor.md" + - "README.architecture.md" +--- + +# Administrator Service Architecture + +This document describes the architecture and design of the Sirius administrator service. + +## Overview + +The administrator service provides administrative capabilities for the Sirius system, including system management, configuration, and monitoring controls. + +## Components + +- **Administrator Binary**: Standalone Go application for administrative operations +- **API Integration**: Connects to the main Sirius API for system management +- **Command Processing**: Handles administrative commands and operations + +## Architecture + +[Architecture details to be documented] + +## Integration + +The administrator service integrates with: + +- Sirius API for system management +- System monitoring for operational insights +- Configuration management for system settings + +## Deployment + +[Deployment details to be documented] diff --git a/documentation/dev/architecture/README.architecture-quick-reference.md b/documentation/dev/architecture/README.architecture-quick-reference.md new file mode 100644 index 0000000..753dc92 --- /dev/null +++ b/documentation/dev/architecture/README.architecture-quick-reference.md @@ -0,0 +1,279 @@ +--- +title: "SiriusScan Architecture Quick Reference" +description: "Concise architectural overview of SiriusScan - a microservices-based vulnerability scanner with Docker orchestration, providing essential context for LLM interactions." +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-01-03" +author: "AI Assistant" +tags: + [ + "architecture", + "quick-reference", + "microservices", + "docker", + "vulnerability-scanner", + ] +categories: ["architecture", "reference"] +difficulty: "beginner" +prerequisites: ["docker", "microservices"] +related_docs: + - "README.architecture.md" + - "README.development.md" +dependencies: [] +llm_context: "high" +search_keywords: + [ + "sirius architecture", + "vulnerability scanner", + "microservices", + "docker compose", + "quick reference", + ] +--- + +# SiriusScan Architecture Quick Reference + +> **📚 Full Architecture**: For comprehensive details, see [README.architecture.md](README.architecture.md) + +## Purpose + +This document provides a condensed architectural overview of SiriusScan for LLM context, focusing on core components, communication patterns, and essential setup information. + +## What is SiriusScan + +**SiriusScan** is an open-source, general-purpose vulnerability scanner built with a microservices architecture. It provides comprehensive vulnerability scanning capabilities through a web interface, with modular components for scanning, terminal access, and agent management. + +## Core Architecture + +### System Overview + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ sirius-ui │ │ sirius-api │ │sirius-engine│ +│ (Next.js) │ │ (Go) │ │ (Go) │ +│ Port 3000 │ │ Port 9001 │ │ Port 5174 │ +└─────────────┘ └─────────────┘ └─────────────┘ + │ │ │ + └───────────────────┼───────────────────┘ + │ + ┌──────────────────────┼──────────────────────┐ + │ │ │ +┌───▼────┐ ┌─────────────▼──┐ ┌─────────────▼──┐ +│RabbitMQ│ │ PostgreSQL │ │ Valkey │ +│ :5672 │ │ :5432 │ │ :6379 │ +└────────┘ └────────────────┘ └────────────────┘ +``` + +### Key Services + +| Service | Technology | Port | Purpose | +| ------------------- | -------------------- | ---- | ---------------------- | +| **sirius-ui** | Next.js + TypeScript | 3000 | Web interface & BFF | +| **sirius-api** | Go + Fiber | 9001 | RESTful API backend | +| **sirius-engine** | Go | 5174 | Core processing engine | +| **sirius-rabbitmq** | RabbitMQ | 5672 | Message broker | +| **sirius-postgres** | PostgreSQL | 5432 | Relational database | +| **sirius-valkey** | Valkey (Redis) | 6379 | Key-value store | + +## Component Details + +### Frontend (sirius-ui) + +- **Tech Stack**: Next.js, TypeScript, tRPC, Tailwind CSS, Shadcn/ui +- **Purpose**: User interface and Backend-for-Frontend (BFF) +- **Key Features**: + - Web-based vulnerability scanner interface + - Terminal component for command execution + - Agent management dashboard + - Real-time scan results display + +### Backend API (sirius-api) + +- **Tech Stack**: Go, Fiber web framework +- **Purpose**: RESTful API for data operations +- **Key Features**: + - Host management endpoints + - Vulnerability data handling + - Health check endpoints + - Database integration + +### Processing Engine (sirius-engine) + +- **Tech Stack**: Go with modular sub-applications +- **Purpose**: Core scanning and processing logic +- **Key Features**: + - Orchestrates vulnerability scans + - Manages deployed agents via gRPC + - Runs specialized sub-modules: + - `app-scanner`: Nmap-based vulnerability scanning + - `app-terminal`: PowerShell/command execution + - `app-agent`: Agent communication and management + +### Data Layer + +- **PostgreSQL**: Stores host information, vulnerabilities, scan results +- **Valkey**: Caching, session management, temporary data +- **RabbitMQ**: Asynchronous messaging between services + +## Communication Patterns + +### Frontend to Backend + +- **tRPC**: Type-safe communication between Next.js frontend and BFF +- **REST**: Direct API calls to sirius-api for data operations + +### Backend Services + +- **RabbitMQ**: Asynchronous task queuing (UI → Engine) +- **gRPC**: Engine to agent communication +- **Database**: Direct connections to PostgreSQL and Valkey + +## Docker Setup + +### Quick Start + +```bash +# Clone and start the system +git clone +cd Sirius +docker compose up -d + +# Access services +# UI: http://localhost:3000 +# API: http://localhost:9001 +# Engine: http://localhost:5174 +``` + +### Key Docker Files + +- `docker-compose.yaml`: Main orchestration +- `sirius-ui/Dockerfile`: Next.js frontend +- `sirius-api/Dockerfile`: Go API service +- `sirius-engine/Dockerfile`: Core engine with sub-modules + +## Project Structure + +``` +Sirius/ +├── sirius-ui/ # Next.js frontend +│ ├── src/ +│ │ ├── components/ # React components +│ │ ├── pages/ # Next.js pages & API routes +│ │ └── server/ # tRPC backend logic +│ └── prisma/ # Database schema +├── sirius-api/ # Go REST API +│ ├── handlers/ # HTTP handlers +│ └── routes/ # API routes +├── sirius-engine/ # Core processing engine +│ └── apps/ # Sub-modules +│ ├── app-scanner/ +│ ├── app-terminal/ +│ └── app-agent/ +├── documentation/ # Project documentation +├── testing/ # Test suites +└── docker-compose.yaml +``` + +## Key Workflows + +### Vulnerability Scanning + +1. User initiates scan via UI +2. UI sends task to RabbitMQ +3. Engine processes scan using app-scanner +4. Results stored in PostgreSQL +5. UI displays results via real-time updates + +### Agent Management + +1. Agents connect to Engine via gRPC +2. Engine manages agent lifecycle +3. Commands executed on remote agents +4. Results streamed back to UI + +### Terminal Access + +1. User types commands in UI terminal +2. Commands routed through Engine +3. Executed via app-terminal (PowerShell) +4. Output streamed back to UI + +## Development Context + +### Backend Development + +- **Location**: Inside `sirius-engine` container +- **Mount**: Local code mounted at `/app-agent` for dev mode +- **Commands**: Run via `docker exec sirius-engine ` + +### Frontend Development + +- **Hot Reload**: Enabled via volume mounts +- **Port**: 3000 (production) +- **Debugging**: Browser dev tools + React DevTools + +### Testing + +- **Location**: `testing/` directory +- **Commands**: `make test-all` for complete suite +- **Coverage**: Container health, integration, documentation + +## Environment Variables + +### Key Configuration + +```bash +# Database +POSTGRES_HOST=sirius-postgres +POSTGRES_USER=postgres +POSTGRES_PASSWORD=postgres +POSTGRES_DB=sirius + +# Messaging +RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/ + +# Services +SIRIUS_API_URL=http://sirius-api:9001 +NEXTAUTH_URL=http://localhost:3000 +``` + +## Troubleshooting + +### Common Issues + +- **Container startup**: Check health checks and dependencies +- **Database connection**: Verify PostgreSQL is healthy +- **Messaging**: Ensure RabbitMQ is running +- **Port conflicts**: Check if ports 3000, 9001, 5174 are available + +### Debug Commands + +```bash +# Check container status +docker compose ps + +# View logs +docker compose logs -f sirius-ui +docker compose logs -f sirius-engine + +# Health checks +curl http://localhost:3000/api/health +curl http://localhost:9001/api/v1/health +``` + +## LLM Context + +This quick reference provides essential context for AI systems working with SiriusScan: + +- **Architecture**: Microservices with Docker orchestration +- **Tech Stack**: Next.js frontend, Go backend, PostgreSQL/Valkey data layer +- **Communication**: tRPC, REST, RabbitMQ, gRPC +- **Purpose**: Vulnerability scanning with agent management +- **Development**: Container-based with hot reloading +- **Key Files**: docker-compose.yaml, service Dockerfiles, src/ directories + +For detailed implementation, see the full [README.architecture.md](README.architecture.md) document. + +--- + +_This quick reference provides essential architectural context for LLM interactions with the SiriusScan project._ diff --git a/documentation/dev/architecture/README.architecture.md b/documentation/dev/architecture/README.architecture.md new file mode 100644 index 0000000..2701228 --- /dev/null +++ b/documentation/dev/architecture/README.architecture.md @@ -0,0 +1,2193 @@ +--- +title: "SiriusScan Architecture" +description: "Comprehensive architectural documentation for SiriusScan, covering system design, component relationships, data flow, and technical implementation details." +template: "TEMPLATE.architecture" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Development Team" +tags: ["architecture", "system-design", "overview", "technical"] +categories: ["architecture"] +difficulty: "advanced" +prerequisites: ["docker", "microservices", "vulnerability-scanning"] +related_docs: + - "README.container-testing.md" + - "README.development.md" +dependencies: [] +llm_context: "high" +search_keywords: + [ + "architecture", + "system design", + "microservices", + "vulnerability scanner", + "sirius", + ] +--- + +# Sirius Scan Architecture Document + +## Table of Contents + +A. **[Getting Started & Development Workflow](#getting-started--development-workflow)** - A.1. [System Prerequisites](#a1-system-prerequisites) - A.2. [Repository Setup](#a2-repository-setup) - A.3. [Running the Full Stack](#a3-running-the-full-stack) - A.4. [Common Development Tasks](#a4-common-development-tasks) - A.5. [Testing Strategy](#a5-testing-strategy) +B. **[Key Architectural Workflows (End-to-End Examples)](#key-architectural-workflows-end-to-end-examples)** - B.1. [User Initiates a Vulnerability Scan](#b1-user-initiates-a-vulnerability-scan) - B.2. [Agent Interaction & Management](#b2-agent-interaction--management) - B.3. [Terminal Command Execution](#b3-terminal-command-execution) + +1. **[Introduction](#introduction)** + - 1.1. [Purpose of Sirius Scan](#purpose-of-sirius-scan) + - 1.2. [High-Level Architecture Overview](#high-level-architecture-overview) +2. **[Core Infrastructure (Docker Compose)](#core-infrastructure-docker-compose)** + - 2.1. [`docker-compose.yaml` Overview](#docker-composeyaml-overview) + - 2.2. [Service Orchestration](#service-orchestration) + - 2.2.1. [`sirius-rabbitmq` (Message Broker)](#sirius-rabbitmq-message-broker) + - 2.2.2. [`sirius-postgres` (Relational Database)](#sirius-postgres-relational-database) + - 2.2.3. [`sirius-valkey` (Key-Value Store)](#sirius-valkey-key-value-store) + - 2.2.4. [Networking](#networking) +3. **[Application Services](#application-services)** + + - 3.1. [`sirius-ui` (User Interface & BFF)](#sirius-ui-user-interface--bff) + - 3.1.1. [Overview & Purpose](#ui-overview--purpose) + - 3.1.2. [Technology Stack](#ui-technology-stack) + - 3.1.3. [Docker Configuration (`sirius-ui/Dockerfile`)](#ui-docker-configuration) + - 3.1.4. [UI Theming (`globals.css`)](#ui-theming) + - 3.1.5. [Extensibility (Marketplace Concept)](#ui-extensibility) + - 3.1.6. [Communication](#ui-communication) + - 3.1.7. [Key Directory Structure](#key-directory-structure) + - 3.1.8. [Local Development & Debugging](#local-development--debugging) + - 3.1.9. [Environment Variables](#environment-variables) + - 3.2. [`sirius-api` (Backend API)](#sirius-api-backend-api) + - 3.2.1. [Overview & Purpose](#api-overview--purpose) + - 3.2.2. [Technology Stack](#api-technology-stack) + - 3.2.3. [Docker Configuration (`sirius-api/Dockerfile`)](#api-docker-configuration) + - 3.2.4. [Key Functionalities (High-Level)](#api-key-functionalities) + - 3.2.5. [Communication](#api-communication) + - 3.2.6. [Key Directory Structure](#key-directory-structure) + - 3.2.7. [Local Development & Debugging](#local-development--debugging) + - 3.2.8. [Environment Variables](#environment-variables) + - 3.3. [`sirius-engine` (Core Processing Engine)](#sirius-engine-core-processing-engine) + - 3.3.1. [Overview & Purpose](#engine-overview--purpose) + - 3.3.2. [Technology Stack](#engine-technology-stack) + - 3.3.3. [Docker Configuration (`sirius-engine/Dockerfile`)](#engine-docker-configuration) + - 3.3.4. [Modular Design (Loading Sub-Applications)](#engine-modular-design) + - 3.3.5. [Communication](#engine-communication) + - 3.3.6. [Key Directory Structure](#key-directory-structure) + - 3.3.7. [Local Development & Debugging](#local-development--debugging) + - 3.3.8. [Environment Variables](#environment-variables) + - 3.4. [`go-api` (Shared Backend SDK)](#go-api-shared-backend-sdk) + - 3.4.1. [Overview & Purpose](#go-api-overview--purpose) + - 3.4.2. [Technology Stack](#go-api-technology-stack) + - 3.4.3. [Key Functionalities](#go-api-key-functionalities) + - 3.4.4. [Usage & Integration](#go-api-usage--integration) + - 3.4.5. [Development & Testing of `go-api`](#go-api-development--testing) + +4. **[Sub-Modules & Agents](#sub-modules--agents)** + - 4.1. [`app-scanner`](#app-scanner) + - 4.1.1. [Purpose and Functionality](#app-scanner-purpose) + - 4.1.2. [NSE (Nmap Script Engine) Management](#app-scanner-nse-management) + - 4.2. [`app-terminal`](#app-terminal) + - 4.2.1. [Purpose and Functionality](#app-terminal-purpose) + - 4.3. [`app-agent`](#app-agent) + - 4.3.1. [Purpose and Functionality](#app-agent-purpose) + - 4.3.2. [gRPC Communication with `sirius-engine`](#app-agent-grpc) +5. **[Data Persistence & Storage](#data-persistence--storage)** + - 5.1. [PostgreSQL (`sirius-postgres`)](#postgresql-sirius-postgres) + - 5.1.1. [Role and Data Stored](#postgres-role) + - 5.1.2. [Schema Overview (Conceptual)](#postgres-schema) + - 5.2. [Valkey (`sirius-valkey`)](#valkey-sirius-valkey) + - 5.2.1. [Role and Data Stored](#valkey-role) +6. **[Inter-Service Communication](#inter-service-communication)** + - 6.1. [RabbitMQ (Asynchronous Messaging)](#rabbitmq-communication) + - 6.2. [tRPC (UI Frontend to Next.js Backend)](#trpc-communication) + - 6.3. [RESTful APIs (`sirius-api`)](#rest-communication) + - 6.4. [gRPC (Engine to Agents)](#grpc-communication) +7. **[Development & Deployment](#development--deployment)** + - 7.1. [Dockerized Environment](#dockerized-environment) + - 7.2. [Hot Reloading (`air`)](#hot-reloading) + - 7.3. [Build Processes (Dockerfiles)](#build-processes) +8. **[Conclusion](#conclusion)** + - 8.1. [Summary of Architecture](#summary-of-architecture) + - 8.2. [Future Directions](#future-directions) + +## A. Getting Started & Development Workflow + +### A.1. System Prerequisites + +To contribute to and run Sirius Scan, you will need the following software installed on your system: + +- **Docker and Docker Compose**: Essential for running the containerized services. Ensure Docker Desktop (or equivalent for your OS) is installed and running. +- **Git**: For cloning the repository and managing versions. +- **Node.js and npm/yarn/bun**: Required for `sirius-ui` development (Next.js, TypeScript). Bun is used in the Dockerfile, so having it locally can be beneficial for consistency. +- **Go (Golang)**: Required for `sirius-api` and `sirius-engine` development. +- **A code editor**: Such as VS Code, GoLand, WebStorm, etc. +- **Basic command-line tools**: `curl`, `wget`, etc., for various scripts and setups. + +It's recommended to have reasonably up-to-date versions of these tools. + +### A.2. Repository Setup + +1. **Clone the Main Repository**: Start by cloning the main `Sirius` repository: + + ```bash + git clone https://github.com/SiriusScan/Sirius.git + cd Sirius + ``` + +2. **Sub-Module Management**: + Sirius Scan utilizes several sub-modules (e.g., `app-scanner`, `app-terminal`, `go-api`, `app-agent`) that are developed in separate repositories. The `sirius-engine` Dockerfile clones some of these repositories (`app-scanner`, `app-terminal`, `go-api`) directly during its build process. This ensures that the engine has the necessary code for these integrated applications. + + For **local development** of these sub-modules, the `docker-compose.yaml` file includes commented-out volume mounts. For example: + + ```yaml + # In docker-compose.yaml, under sirius-engine service: + volumes: + - ./sirius-engine:/engine + - ../minor-projects/app-agent:/app-agent + # - ../minor-projects/go-api:/go-api # Local Development + # - ../minor-projects/app-scanner:/app-scanner # Local Development + # - ../minor-projects/app-terminal:/app-terminal # Local Development + ``` + + To develop a sub-module locally (e.g., `app-scanner`): + + - Clone the `app-scanner` repository into a directory relative to the main `Sirius` project, for instance, at the same level as `Sirius` in a `minor-projects` directory: `../minor-projects/app-scanner`. + - Uncomment the corresponding volume mount in `docker-compose.yaml`. + - This will mount your local `app-scanner` code into the `sirius-engine` container, overriding the version cloned by the Dockerfile. Changes you make locally will be reflected due to tools like `air` (for Go applications) configured for hot reloading. + +3. **Environment Variables**: Some services might require `.env` files. For example, `sirius-ui` copies a `.env` file in its Dockerfile. Check individual service directories or their respective Dockerfiles for any specific `.env` setup instructions. Often, default or example environment files are provided (e.g., `.env.example`) which can be copied and customized. + +### A.3. Running the Full Stack + +Once you have the prerequisites installed and the repository set up (including any sub-modules you intend to develop locally): + +1. **Navigate to the Root Directory**: Ensure your terminal is in the root of the `Sirius` project directory (where `docker-compose.yaml` is located). + +2. **Start All Services**: Run the following command to build (if not already built) and start all services defined in `docker-compose.yaml`: + + ```bash + docker compose up + ``` + + - Add the `-d` flag (`docker compose up -d`) to run containers in detached mode (in the background). + - If you want to force a rebuild of the images (e.g., after changing a `Dockerfile`), use the `--build` flag: `docker compose up --build`. + +3. **Verify Services**: After the command completes and services are starting up, you can check their status: + + ```bash + docker compose ps + ``` + + You should see all services (e.g., `sirius-ui`, `sirius-api`, `sirius-engine`, `sirius-postgres`, `sirius-rabbitmq`, `sirius-valkey`) running. + +4. **Accessing Services**: + + - **`sirius-ui`**: Open your web browser and navigate to `http://localhost:3000` (or `http://localhost:3001` for the development port, check `docker-compose.yaml`). + - **`sirius-rabbitmq` Management**: Accessible at `http://localhost:15672` (default credentials are often guest/guest). + - Other services like `sirius-api` (port 9001), `sirius-postgres` (port 5432), etc., expose ports as defined in `docker-compose.yaml` for direct interaction if needed (e.g., with a database client or API tool). + +5. **Viewing Logs**: + + - To view logs for all services in real-time (if not detached): `docker compose logs -f` + - To view logs for a specific service (e.g., `sirius-engine`): `docker compose logs -f sirius-engine` + +6. **Stopping Services**: + - If running in the foreground, press `Ctrl+C` in the terminal where `docker compose up` is running. + - If running in detached mode, or from another terminal: + ```bash + docker compose down + ``` + - To stop and remove volumes (useful for a clean restart, **be cautious as this deletes data** in Docker volumes like your database): `docker compose down -v`. + +### A.4. Common Development Tasks + +This section outlines general workflows for common development tasks. Detailed steps can vary and might require deeper understanding of the specific service's codebase and frameworks (Next.js/React for UI, Go/Fiber for API, Go for Engine). + +#### A.4.1. Contributing a new UI Page/Component to `sirius-ui` + +1. **Locate Relevant Directories**: + - Pages are typically in `sirius-ui/src/pages/`. + - Reusable components are in `sirius-ui/src/components/`. + - tRPC procedures (API endpoints for the UI) are in `sirius-ui/src/server/api/routers/`. +2. **Create New Files**: For a new page, create a new `.tsx` file in the `pages` directory (e.g., `sirius-ui/src/pages/new-feature.tsx`). For a component, create it in an appropriate subdirectory under `components`. +3. **Develop the Component/Page**: Use React, TypeScript, and Tailwind CSS. Leverage existing components from Shadcn/ui (`sirius-ui/src/components/lib/ui/`) where possible. +4. **Data Fetching (if needed)**: + - If data is needed from the backend, define a new tRPC procedure in a relevant router file (e.g., `sirius-ui/src/server/api/routers/yourRouter.ts`). + - Use `api.yourRouter.yourProcedure.useQuery()` or `.useMutation()` hooks in your frontend component to interact with the tRPC endpoint. +5. **Styling**: Use Tailwind CSS utility classes directly in your JSX. For global styles or complex base styles, consider `sirius-ui/src/styles/globals.css`. +6. **Routing**: Next.js uses a file-system based router. A file like `pages/new-feature.tsx` will be accessible at `/new-feature`. +7. **Testing**: Add relevant unit or integration tests. +8. **Local Development**: With `docker compose up` running, changes to files in `sirius-ui/` (mounted into the container) should trigger hot reloading, and you can see your changes in the browser at `http://localhost:3000`. + +#### A.4.2. Adding a new API endpoint to `sirius-api` + +1. **Understand Fiber Framework**: `sirius-api` uses Fiber. Familiarize yourself with its routing and handler concepts. +2. **Define Route**: In `sirius-api/main.go` or a dedicated routes file (e.g., inside a `handlers` or `routes` directory if structured that way), add a new route using `app.Get()`, `app.Post()`, etc. + + ```go + // Example in sirius-api/main.go or a routes setup function + // import "github.com/gofiber/fiber/v2" + // import "your-project/sirius-api/handlers" + + // app is a *fiber.App instance + // app.Get("/api/v1/new-endpoint", handlers.HandleNewEndpoint) + ``` + +3. **Implement Handler Function**: Create the Go function that will handle requests to this endpoint (e.g., `HandleNewEndpoint` in a `handlers` package). + + ```go + // Example in sirius-api/handlers/new_handler.go + package handlers + + import "github.com/gofiber/fiber/v2" + + func HandleNewEndpoint(c *fiber.Ctx) error { + // Your logic here: parse request, interact with database (via go-api package), + // communicate with sirius-engine via RabbitMQ, etc. + return c.JSON(fiber.Map{"status": "success", "message": "New endpoint reached"}) + } + ``` + +4. **Database/Service Interaction**: If your endpoint needs to interact with PostgreSQL or Valkey, use the functions and types provided by the shared `go-api` library (cloned into the `sirius-engine` container, but its source code should be available in your `../minor-projects/go-api` if you set up local dev for it, or you might need to ensure `sirius-api` has access to it via Go modules). +5. **Testing**: Write unit or integration tests for your new endpoint and handler logic. +6. **Local Development**: The `sirius-api` service uses `air` for hot reloading. With `docker compose up` running and if `sirius-api/` is volume-mounted (as it is by default in `docker-compose.yaml`), changes to Go files should trigger a restart of the API service. You can test your endpoint using tools like `curl` or Postman against `http://localhost:9001/api/v1/new-endpoint`. + +#### A.4.3. Modifying or adding a module within `sirius-engine` + +Development within `sirius-engine` is more complex due to its role as an orchestrator and its integration of sub-applications like `app-scanner` and `app-terminal`. + +1. **Understand Engine Structure**: The main engine logic is in Go. Sub-applications (`app-scanner`, `app-terminal`) are also typically Go projects cloned into the engine's container during build (or volume-mounted for local dev). +2. **Local Development Setup**: + - To modify a sub-application like `app-scanner`, clone its repository locally (e.g., `../minor-projects/app-scanner`). + - Uncomment the relevant volume mount in `docker-compose.yaml` for `sirius-engine` (e.g., `- ../minor-projects/app-scanner:/app-scanner`). + - This mounts your local code into the `/app-scanner` directory inside the `sirius-engine` container. +3. **Making Changes**: + - **Engine Core Logic**: Modify Go files directly within the `sirius-engine/` directory. + - **Sub-Application Logic (e.g., `app-scanner`)**: Modify Go files in your local clone (e.g., `../minor-projects/app-scanner/`). +4. **`start.sh` Script**: The `sirius-engine/Dockerfile` uses `start.sh` as its `ENTRYPOINT`. This script is responsible for starting the main engine and potentially building/running the sub-applications. It might use `air` for hot reloading these sub-apps if they have `.air.toml` configurations. +5. **Communication**: + - Modules within the engine might communicate via Go channels, direct function calls, or local IPC if `start.sh` runs them as separate processes. + - The engine communicates with `sirius-ui`/`sirius-api` via RabbitMQ and with `app-agent` instances via gRPC. +6. **Testing**: This can be complex. Unit tests for individual Go packages are standard. Integration testing might involve sending messages via RabbitMQ or making gRPC calls to test specific flows. +7. **Local Development & Hot Reloading**: + - If `air` is configured for the Go components you are working on (either the main engine or a sub-application like `app-scanner` via its own `air` setup invoked by `start.sh`), changes to mounted Go files should trigger a rebuild/restart of that component within the `sirius-engine` container. + - Observe logs using `docker compose logs -f sirius-engine` to see restarts and any errors. + +### A.5. Testing Strategy + +Sirius Scan aims for comprehensive testing, though the specific strategies and depth can vary per module. + +- **General Approach**: + + - **Unit Tests**: Each module/service should have unit tests for its core logic, especially for Go and TypeScript code. Standard testing libraries for each language/framework are used (e.g., Go's `testing` package, Jest/Vitest for TypeScript/React). + - **Integration Tests**: Testing interactions between components within a service (e.g., API endpoint to database logic in `sirius-api`) or between services where feasible (e.g., UI making a call that results in a RabbitMQ message). + - **End-to-End (E2E) Tests**: For critical user flows, E2E tests can simulate user interactions from the UI through the backend services. (Frameworks like Cypress or Playwright might be considered for UI E2E testing). + +- **`sirius-ui`**: + + - Component testing using React Testing Library or similar. + - tRPC procedure testing. + +- **`sirius-api`**: + + - Handler function unit tests. + - Endpoint integration tests (e.g., using Go's `httptest` package). + +- **`sirius-engine`**: + + - Unit tests for Go packages. + - Testing RabbitMQ message handling and gRPC service interactions can be complex and might involve mock servers or specific test environments. + - Sub-applications like `app-scanner` and `app-terminal` should have their own testing strategies within their repositories. + +- **`app-agent`**: + + - Unit tests for agent logic. + - Testing gRPC communication with a mock `sirius-engine` server. + +- **Existing Documentation**: + - The document `Sirius/documentation/README.testing.md` provides specific test cases and scenarios, particularly focused on data relationships and expected outcomes for vulnerability scanning. This document should be consulted for understanding expected system behavior and for designing new tests related to core scanning functionalities. + +Developers are encouraged to write tests for new features and bug fixes. CI/CD pipelines (if set up) would ideally run these tests automatically. + +## B. Key Architectural Workflows (End-to-End Examples) + +### B.1. User Initiates a Vulnerability Scan + +This workflow describes the sequence of events when a user initiates a vulnerability scan from the `sirius-ui`. + +1. **User Interaction (`sirius-ui`)**: + + - The user navigates to the scan configuration page in the `sirius-ui`. + - They input scan parameters such as target IP addresses/ranges, scan type (e.g., full scan, specific port scan), Nmap script selection (if applicable), and other options. + - The user clicks a "Start Scan" button. + +2. **UI Frontend to BFF (`sirius-ui` - tRPC)**: + + - The frontend component makes a tRPC mutation call to its Next.js backend (BFF). + - The payload includes the scan configuration details. + +3. **BFF Processing (`sirius-ui` - Next.js Backend)**: + + - The tRPC procedure in the Next.js backend receives the scan request. + - It may perform initial validation or enrichment of the scan parameters. + - It then constructs a message (e.g., a JSON payload) representing the scan job. + +4. **Task Queuing (`sirius-ui` to `sirius-rabbitmq`)**: + + - The Next.js backend (BFF) publishes this scan job message to a specific queue in `sirius-rabbitmq` (e.g., `scan_jobs_queue`). + - This decouples the UI/BFF from the `sirius-engine`, allowing the UI to remain responsive even if the engine is busy. + +5. **Scan Processing (`sirius-engine`)**: + + - `sirius-engine` (Go application) is subscribed to the `scan_jobs_queue` in RabbitMQ. + - It consumes the scan job message. + - The engine parses the job details and determines the appropriate action. + - This might involve: + - Interacting with `sirius-postgres` (via `go-api` library) to retrieve host information or store scan metadata. + - Orchestrating `app-scanner` (which is part of its container) to perform the actual network scanning using tools like Nmap and RustScan, leveraging the managed NSE scripts. + - If the scan involves remote agents, it might delegate parts of the scan to specific `app-agent` instances via gRPC (see Workflow B.2). + +6. **Execution (`app-scanner` within `sirius-engine`)**: + + - `app-scanner` executes the scan commands (e.g., Nmap with specified options and scripts). + - It collects the raw scan output (e.g., Nmap XML output). + +7. **Result Handling & Persistence (`sirius-engine`, `go-api`, `sirius-postgres`, `sirius-valkey`)**: + + - `sirius-engine` (or `app-scanner` itself) parses the raw scan results. + - It extracts meaningful information: open ports, services, identified vulnerabilities (e.g., by matching script output to CVEs or known issues). + - This processed data is then persisted into `sirius-postgres` (e.g., updating `hosts`, `ports`, `vulnerabilities`, and their join tables) likely using the `go-api` library functions. + - Intermediate status or partial results might be cached in `sirius-valkey`. + +8. **Status Updates & Notifications (RabbitMQ)**: + + - During the scan, `sirius-engine` may publish progress updates or status messages to other RabbitMQ queues (e.g., `scan_status_updates_queue`). + - `sirius-ui` (via its BFF and potentially WebSockets or polling tRPC queries) can subscribe to these updates to display real-time scan progress to the user. + +9. **Scan Completion & Final Results (`sirius-ui`)**: + - Once the scan is complete and results are persisted, `sirius-engine` might publish a final completion message. + - The user can then view the detailed scan results and vulnerabilities in the `sirius-ui`, which fetches this data from `sirius-api` (which in turn queries `sirius-postgres`) or directly via tRPC calls that access the database. + +### B.2. Agent Interaction & Management + +This workflow covers how `app-agent` instances might register (conceptually, as the current `app-agent` is basic) and how the `sirius-engine` executes commands on them. + +**Conceptual Agent Registration/Discovery (Future Enhancement)**: +_While the current `app-agent` (from `app-agent/cmd/agent/README.md`) doesn't detail a formal registration process, a production system would typically involve agents announcing their presence or the engine discovering them._ + +1. **Agent Startup (`app-agent`)**: An `app-agent` instance starts on a target host. It knows the `sirius-engine`'s gRPC address (`SERVER_ADDRESS`). +2. **Initial Contact/Heartbeat (`app-agent` to `sirius-engine` - gRPC)**: + - The agent could make an initial `Register` or `Heartbeat` gRPC call to `sirius-engine`, providing its `AGENT_ID` (e.g., hostname), capabilities (OS, available tools), and IP address. + - `sirius-engine` records or updates the agent's status and availability, perhaps in `sirius-valkey` or `sirius-postgres`. +3. **Periodic Pings**: Agents would periodically send `Ping` requests to the engine to maintain active status. The engine would mark agents as offline if pings cease. + +**Command Execution via Agent**: + +1. **Trigger for Command**: + + - A user might initiate a command for a specific agent via `sirius-ui` (e.g., through an agent management panel or the terminal, see Workflow B.3). + - A scan job in `sirius-engine` might require executing a command on a specific agent (e.g., running a local enumeration script). + +2. **Request to Engine**: + + - If from UI, the request flows: `sirius-ui` (frontend) -> tRPC -> `sirius-ui` (BFF) -> RabbitMQ -> `sirius-engine`. + - The message to `sirius-engine` would specify the target `AGENT_ID` and the command to execute. + +3. **Engine Locates Agent (`sirius-engine`)**: + + - `sirius-engine` looks up the target agent's details (e.g., its gRPC connection status/details, if connections are persistent, or just its known address). + +4. **Command Delegation (`sirius-engine` to `app-agent` - gRPC)**: + + - `sirius-engine` makes an `ExecuteCommand` gRPC call to the specified `app-agent` instance. + - The gRPC request payload contains the command string (e.g., `"ls -la /tmp"` or `"nmap -sV target.com"`). + +5. **Command Execution on Agent (`app-agent`)**: + + - The `app-agent` receives the `ExecuteCommand` request. + - It executes the command on the underlying operating system using its shell execution capabilities. + - **Security Note**: As per `app-agent/cmd/agent/README.md`, the current example agent lacks command validation and sanitization, which is a critical security concern in a production system. + +6. **Result Streaming/Return (`app-agent` to `sirius-engine` - gRPC)**: + + - The `app-agent` captures the standard output (stdout) and standard error (stderr) of the executed command. + - It sends these results back to `sirius-engine` via the gRPC response. This could be a single response upon command completion or a stream of data if the command produces continuous output. + - The agent README mentions it "periodically executes 'ls -la' and sends results to the server," implying it can handle periodic/streaming results. + +7. **Engine Processes Results (`sirius-engine`)**: + + - `sirius-engine` receives the command output from the agent. + - It processes the results as needed: + - If part of a larger scan, the results are incorporated into the scan findings. + - If a direct command from UI, the results are formatted. + - Results might be stored in `sirius-postgres` or cached in `sirius-valkey`. + +8. **Forwarding to User/UI (`sirius-engine` to RabbitMQ to `sirius-ui`)**: + - `sirius-engine` publishes the command results (or a notification of completion) to a RabbitMQ queue. + - `sirius-ui` (BFF) consumes this message and relays the information to the user's interface (e.g., displayed in a terminal window or results panel). + +### B.3. Terminal Command Execution + +This workflow outlines how a command typed into the terminal in `sirius-ui` reaches and is executed by `app-terminal` within the `sirius-engine`. + +1. **User Input (`sirius-ui` - Terminal Component)**: + + - The user types a command into the terminal interface provided by `sirius-ui` (e.g., `XTerm.js` integrated component). + - The command might be a system-level command or a special internal command (e.g., `use agent `). + +2. **UI Frontend to BFF (`sirius-ui` - tRPC)**: + + - The terminal component captures the command string. + - It makes a tRPC mutation call (e.g., `executeTerminalCommand`) to its Next.js backend (BFF). + - The payload includes the command string and potentially the current context (e.g., if a specific agent is targeted via a previous `use agent` command). + +3. **BFF Processing (`sirius-ui` - Next.js Backend)**: + + - The tRPC procedure in the Next.js backend receives the command request. + - It may perform initial parsing or validation. For example, it might differentiate between internal UI commands (like switching agent context locally in the UI state) and commands to be sent to the backend engine. + - For commands destined for `app-terminal`, it constructs a message (e.g., a JSON payload) including the command and any relevant context (like target agent ID if the terminal is proxying to an agent, or if it's a command for the engine itself). + +4. **Task Queuing (`sirius-ui` to `sirius-rabbitmq`)**: + + - The Next.js backend (BFF) publishes this terminal command message to a specific queue in `sirius-rabbitmq` (e.g., `terminal_commands_queue`). + +5. **Command Routing & Processing (`sirius-engine`)**: + + - `sirius-engine` (Go application) subscribes to the `terminal_commands_queue`. + - It consumes the command message. + - The engine parses the command and context. It determines if the command is for: + - **`app-terminal` directly**: For general commands to be executed in the engine's environment (potentially within a PowerShell session managed by `app-terminal`). + - **An `app-agent` via `app-terminal` as a proxy**: If the terminal context is set to an agent, the engine might instruct `app-terminal` to relay this command, or the engine itself might make a gRPC call to the target `app-agent` (similar to Workflow B.2, step 4). + - **Internal engine commands**: For special commands handled by the engine itself. + +6. **Execution via `app-terminal` (`sirius-engine` -> `app-terminal`)**: + + - If the command is for `app-terminal`, `sirius-engine` passes the command to its integrated `app-terminal` module. + - `app-terminal` manages command execution environments (e.g., it could maintain PowerShell sessions). + - It executes the command within the appropriate session/environment. + - `app-terminal` captures the stdout and stderr of the command. + - **Note**: The `sirius-engine/Dockerfile` installs PowerShell, and `app-terminal` is the likely consumer of this, providing a PowerShell backend for the terminal feature. + +7. **Result Return (`app-terminal` to `sirius-engine`)**: + + - `app-terminal` returns the command output (stdout, stderr) back to the main `sirius-engine` logic that invoked it. + +8. **Forwarding to User/UI (`sirius-engine` to RabbitMQ to `sirius-ui`)**: + + - `sirius-engine` takes the output received from `app-terminal` (or directly from an `app-agent` if it was a proxied command). + - It publishes this output to a specific RabbitMQ queue intended for terminal output (e.g., `terminal_output_queue`). The message should correlate with the original command or session. + - `sirius-ui` (BFF) subscribes to this queue. + - The BFF receives the output and uses a mechanism (like WebSockets or Server-Sent Events connected to the tRPC subscription) to stream the output back to the specific user's terminal component in the UI. + +9. **Display Output (`sirius-ui` - Terminal Component)**: + - The terminal component in the UI receives the streamed output and displays it to the user. + +## 1. Introduction + +### 1.1. Purpose of Sirius Scan + +Sirius Scan is an open-source, general-purpose vulnerability scanner designed to leverage community-driven security intelligence. It aims to provide a comprehensive platform for identifying, managing, and remediating security vulnerabilities across an organization's digital assets. The system is built with modularity and extensibility in mind, allowing for continuous enhancement and adaptation to the evolving cybersecurity landscape. + +_(Reference: [Sirius Scan GitHub README](https://github.com/SiriusScan/Sirius/blob/main/README.md))_ + +### 1.2. High-Level Architecture Overview + +Sirius Scan employs a microservices architecture, with its various components containerized and orchestrated using Docker Compose. This approach promotes scalability, resilience, and maintainability. The system comprises several key services that work in concert: + +- **`sirius-ui`**: A Next.js-based web interface providing the primary user interaction point. +- **`sirius-api`**: A Go-based RESTful API service that handles backend logic and data operations. +- **`sirius-engine`**: A Go-based core processing engine responsible for orchestrating scans, managing agents, and running various specialized sub-applications that provide core functionalities like scanning (`app-scanner`) and terminal access (`app-terminal`). It receives tasks primarily via RabbitMQ from `sirius-ui` or `sirius-api` and coordinates the execution of these tasks using its sub-modules and agents. +- **Data Stores**: + - `sirius-postgres`: A PostgreSQL database for persistent storage of relational data (e.g., host information, vulnerabilities). + - `sirius-valkey`: A Valkey (Redis-like) key-value store for caching, session management, and other non-relational data. +- **Messaging**: + - `sirius-rabbitmq`: A RabbitMQ message broker facilitating asynchronous communication between services, particularly between the UI/API and the Engine. + +The following diagram from the main project README illustrates the interconnected services: + +| Service | Description | Port(s) | +| --------------- | ----------------------- | ------------------------------- | +| sirius-ui | Web interface (Next.js) | 3000 (HTTP), 3001 (Dev) | +| sirius-api | Backend API service | 9001 | +| sirius-engine | Scanning engine | 5174 | +| sirius-rabbitmq | Message broker | 5672 (AMQP), 15672 (Management) | +| sirius-postgres | Database | 5432 | +| sirius-valkey | Key-value store | 6379 | + +_(Source: Adapted from [Sirius/README.md](mdc:Sirius/README.md))_ + +Communication between the frontend, API, and engine is carefully managed, with tRPC used for efficient data transfer between the UI's frontend and its Next.js backend, REST for the `sirius-api`, and RabbitMQ for asynchronous tasks delegated to the `sirius-engine`. The `sirius-engine` also communicates with deployed agents via gRPC. + +## 2. Core Infrastructure (Docker Compose) + +Sirius Scan leverages Docker Compose for defining and running its multi-container application environment. This ensures consistency across development, testing, and deployment, and simplifies the management of the various microservices. + +### 2.1. `docker-compose.yaml` Overview + +The main configuration is found in `Sirius/docker-compose.yaml`. It defines the services, networks, and volumes required for the application to run. The `name: sirius` directive at the top sets a project name for easier management of Docker resources. + +```yaml +name: sirius + +services: + # ... service definitions below ... +``` + +_(Source: `Sirius/docker-compose.yaml`)_ + +### 2.2. Service Orchestration + +The following services form the backbone of the Sirius Scan infrastructure: + +#### 2.2.1. `sirius-rabbitmq` (Message Broker) + +RabbitMQ serves as the central message bus for asynchronous communication between different services, particularly for decoupling long-running tasks and distributing workloads. + +- **Purpose**: Facilitates asynchronous communication, task queuing, and event-driven interactions. +- **Image**: `rabbitmq:3.7.3-management` (Includes the RabbitMQ management plugin). +- **Ports**: + - `5672:5672` (AMQP protocol for messaging) + - `15672:15672` (Management UI) +- **Configuration**: Uses a custom `rabbitmq.conf` for tailored settings. +- **Healthcheck**: Ensures the RabbitMQ service is operational. + +```yaml +sirius-rabbitmq: + image: rabbitmq:3.7.3-management + restart: always + container_name: sirius-rabbitmq + hostname: sirius-rabbitmq + ports: + - "5672:5672" + - "15672:15672" + volumes: + - ./rabbitmq/rabbitmq.conf:/etc/rabbitmq/rabbitmq.conf:ro + healthcheck: + test: ["CMD", "rabbitmqctl", "status"] + interval: 30s + timeout: 15s + retries: 5 +``` + +_(Source: `Sirius/docker-compose.yaml`)_ + +#### 2.2.2. `sirius-postgres` (Relational Database) + +PostgreSQL is used as the primary relational database for storing structured data such as host information, vulnerability details, scan results, and user data. + +- **Purpose**: Persistent storage for relational application data. +- **Image**: `postgres:15-alpine`. +- **Environment Variables**: Sets up default user, password, and database name. +- **Ports**: `5432:5432` (Standard PostgreSQL port). +- **Healthcheck**: Verifies the database server is ready to accept connections. + +```yaml +sirius-postgres: + image: postgres:15-alpine + restart: always + container_name: sirius-postgres + hostname: sirius-postgres + environment: + POSTGRES_USER: postgres + POSTGRES_PASSWORD: postgres + POSTGRES_DB: sirius + ports: + - "5432:5432" + healthcheck: + test: ["CMD-SHELL", "pg_isready -U postgres"] + interval: 10s + timeout: 5s + retries: 5 +``` + +_(Source: `Sirius/docker-compose.yaml`)_ + +#### 2.2.3. `sirius-valkey` (Key-Value Store) + +Valkey, a fork of Redis, provides a high-performance in-memory key-value store. It's used for caching, session management, storing temporary data, and potentially for managing NSE script manifests as indicated in scanner documentation. + +- **Purpose**: In-memory data storage for caching, session data, and other non-relational, fast-access needs. +- **Image**: `valkey/valkey:latest`. +- **Ports**: `6379:6379` (Standard Valkey/Redis port). + +```yaml +sirius-valkey: + image: valkey/valkey:latest + restart: always + container_name: sirius-valkey + hostname: sirius-valkey + ports: + - "6379:6379" +``` + +_(Source: `Sirius/docker-compose.yaml`)_ + +#### 2.2.4. Networking + +Docker Compose sets up a default network for all services defined in the `docker-compose.yaml` file. This allows services to discover and communicate with each other using their service names as hostnames. + +- **Default Network**: Unless specified otherwise, all services join a network named `_default` (e.g., `sirius_default` since `name: sirius` is at the top of `docker-compose.yaml`). +- **Service Discovery**: Within this default network, services can reach each other using their names. For example, `sirius-api` can connect to `sirius-postgres` using the hostname `sirius-postgres` and port `5432`. + ```go + // Example connection string for sirius-api to connect to postgres + // dsn := "host=sirius-postgres user=postgres password=postgres dbname=sirius port=5432 sslmode=disable" + ``` +- **Port Mapping**: The `ports` directive in `docker-compose.yaml` (e.g., `"3000:3000"` for `sirius-ui`) maps ports from the host machine to the container. The first port is the host port, and the second is the container port. This makes services accessible from the host machine (e.g., `localhost:3000`). Internal communication between containers typically uses the container port and service name. +- **Custom Networks**: While not explicitly used in the current `docker-compose.yaml`, Docker Compose allows for defining custom bridge networks for more complex networking scenarios or to isolate groups of services. This could be a future consideration if needed. +- **Dependencies (`depends_on`)**: The `depends_on` directive can control the startup order of services, but it only waits until the dependency has _started_, not until it's _ready_ to accept connections. For readiness, healthchecks (as used for `sirius-rabbitmq` and `sirius-postgres`) are a more robust solution to ensure a service is fully operational before dependent services try to connect to it. + +## 3. Application Services + +Beyond the core infrastructure, Sirius Scan is composed of three main application services: `sirius-ui` for the frontend and user interaction, `sirius-api` for backend RESTful services, and `sirius-engine` for core scanning and processing tasks. The `go-api` library serves as a critical shared SDK for the Go-based backend services. + +### 3.1. `sirius-ui` (User Interface & BFF) + +#### 3.1.1. Overview & Purpose + +The `sirius-ui` service provides the web-based graphical user interface (GUI) for Sirius Scan. It allows users to manage scans, view results, configure settings, and interact with all aspects of the vulnerability scanner. It also acts as a Backend-For-Frontend (BFF), handling some UI-specific logic before communicating with other backend services. + +As defined in `docker-compose.yaml`: + +```yaml +sirius-ui: + build: + context: ./sirius-ui/ + dockerfile: Dockerfile + args: + NEXT_PUBLIC_CLIENTVAR: "clientvar" + container_name: sirius-ui + hostname: sirius-ui + restart: always + image: sirius-ui + working_dir: /app + ports: + - "3000:3000" + - "3001:3001" + volumes: + - ./sirius-ui:/app + - /app/node_modules +``` + +_(Source: `Sirius/docker-compose.yaml`)_ + +#### 3.1.2. Technology Stack + +`sirius-ui` is built with a modern JavaScript/TypeScript stack: + +- **Next.js**: A React framework for server-side rendering (SSR), static site generation (SSG), and client-side applications. Chosen for its robust features and development experience, including routing and API routes (which contribute to its BFF capabilities). +- **TypeScript**: For static typing, improving code quality and maintainability. +- **tRPC**: Enables end-to-end typesafe APIs between the Next.js frontend and its backend (API routes). This simplifies data fetching and ensures type consistency. +- **Tailwind CSS**: A utility-first CSS framework for rapid UI development and styling. +- **Shadcn/ui**: A collection of re-usable UI components built with Radix UI and Tailwind CSS, used for building the user interface. +- **npm**: Used for package management and dependency installation, with Node.js as the JavaScript runtime. + +#### 3.1.3. Docker Configuration (`sirius-ui/Dockerfile`) + +The `sirius-ui` Docker image is built using `node:18-alpine` as the base, using npm for package management and running the Next.js application. + +Key steps in the `Sirius/sirius-ui/Dockerfile` include: + +```dockerfile +# sirius-ui Dockerfile - Multi-stage build + +# Base stage with common dependencies +FROM node:18-alpine AS base + +# Install system dependencies +RUN apk add --no-cache libc6-compat openssl ca-certificates + +WORKDIR /app + +# Copy package files and install dependencies +COPY package*.json ./ +RUN npm install + +# Copy source code and build configuration +COPY . . + +# Generate Prisma client +RUN npx prisma generate + +# Development stage +FROM base AS development +ENV NODE_ENV=development +ENV NEXT_TELEMETRY_DISABLED=1 + +EXPOSE 3000 +CMD ["/app/start-dev.sh"] +``` + +_(Source: `Sirius/sirius-ui/Dockerfile`)_ + +This Dockerfile sets up the environment, installs dependencies using `bun install`, copies the application source, and runs the development server. It also exposes ports `3000` (likely for the application) and `3001` (possibly for a development or auxiliary service). + +#### 3.1.4. UI Theming (`globals.css`) + +The visual theme of `sirius-ui` is defined in `Sirius/sirius-ui/src/styles/globals.css`. It utilizes Tailwind CSS and defines CSS custom properties (variables) for theming, including support for a dark mode. + +Example of theme variables (light mode): + +```css +@layer base { + :root { + --background: 220, 13%, 100%, 1; + --foreground: 222.2 84% 4.9%; + + --card: 0 0% 100%; + --card-foreground: 222.2 84% 4.9%; + + --primary: 222.2 47.4% 11.2%; + --primary-foreground: 210 40% 98%; + + /* ... other variables ... */ + } + + .dark { + --background: 234, 26%, 15%, 1; + --foreground: 210 40% 98%; + + /* ... other dark mode variables ... */ + } +} +``` + +_(Source: `Sirius/sirius-ui/src/styles/globals.css`)_ + +The file also includes styles for specific components and decorative elements like the `hexgrad` background. + +#### 3.1.5. Extensibility (Marketplace Concept) + +A key design consideration for choosing Next.js was to facilitate future development of a marketplace-style system. This implies that the UI is structured to allow third-party developers to contribute additional pages, modules, or plugins, enhancing the platform's capabilities over time. While not yet implemented, this architectural foresight influences the UI's design towards modularity. + +#### 3.1.6. Communication + +- **Frontend to BFF (Next.js Backend)**: Uses tRPC for type-safe API calls from the client-side components to the Next.js API routes. +- **BFF to other services**: The Next.js backend part of `sirius-ui` communicates with `sirius-engine` via RabbitMQ for asynchronous operations and potentially with `sirius-api` for other data needs (though direct REST calls from client components to `sirius-api` are also possible, tRPC typically centralizes data access through the BFF). + +#### 3.1.7. Key Directory Structure + +The `sirius-ui` service, being a Next.js application, follows a conventional directory structure. Here are some key directories within `Sirius/sirius-ui/`: + +- **`src/`**: The primary directory for application source code. + - **`src/pages/`**: Contains Next.js pages. Each `.tsx` or `.ts` file in this directory (excluding those in `api/`) becomes a route. + - `src/pages/index.tsx`: The home page. + - `src/pages/api/`\*\*: API routes for the Next.js backend (BFF). + - `src/pages/api/trpc/[trpc].ts`: Handles all tRPC requests. + - **`src/components/`**: Reusable React components. + - `src/components/lib/ui/`: Shadcn/ui components (often imported as `~/components/lib/ui/...`). + - Custom components are usually organized into subdirectories based on feature or type (e.g., `agent/`, `scanner/`, `terminal/`). + - **`src/server/`**: Backend-specific code for the Next.js application. + - `src/server/api/`: + - `src/server/api/root.ts`: Defines the root tRPC router, merging other routers. + - `src/server/api/routers/`: Contains individual tRPC routers (e.g., `terminal.ts`, `agent.ts`). + - **`src/styles/`**: Styling files. + - `src/styles/globals.css`: Global styles and Tailwind CSS base configuration, including theme variables. + - **`src/utils/`**: Utility functions and helpers. + - **`src/hooks/`**: Custom React hooks. + - **`src/types/`**: TypeScript type definitions and interfaces. + - **`src/services/`**: May contain client-side service integrations if not directly handled by tRPC hooks. +- **`public/`**: Static assets that are served directly from the root (e.g., images, favicons). +- **`prisma/`**: Contains Prisma schema (`schema.prisma`) and migration files, used for database interaction by the Next.js backend (though the primary database interaction seems to be driven by `sirius-api`). If `sirius-ui` needs direct DB access for some BFF tasks, Prisma might be used here. +- **`Dockerfile`**: Defines how the `sirius-ui` service is built as a Docker image. +- **`package-lock.json`, `package.json`, `tsconfig.json`**: Project configuration and dependency management files (using npm). +- **`.env` / `.env.example`**: Environment variable definitions. + +#### 3.1.8. Local Development & Debugging + +Developing and debugging `sirius-ui` typically involves the following: + +- **Prerequisites**: Ensure Node.js and npm are installed locally. +- **Running with Docker Compose**: + - The easiest way is to use `docker compose up`. The `sirius-ui` service definition in `docker-compose.yaml` mounts the `./sirius-ui:/app` directory into the container. + - The `Dockerfile` for `sirius-ui` uses `CMD ["/app/start-dev.sh"]`, which starts the Next.js development server with hot reloading. + - Changes made to your local `Sirius/sirius-ui/src/` files will be reflected in the container, and the Next.js dev server will automatically reload the application in your browser (typically `http://localhost:3000`). +- **Browser Developer Tools**: + - Use your browser's developer tools (e.g., Chrome DevTools, Firefox Developer Tools) extensively for debugging frontend issues: inspecting HTML/CSS, debugging JavaScript (React components, tRPC calls), checking network requests, and viewing console logs. + - React Developer Tools browser extension is highly recommended for inspecting React component hierarchy, props, and state. +- **tRPC Debugging**: + - Network tab in browser dev tools can show tRPC requests (usually to `/api/trpc/...`). + - For server-side tRPC procedure debugging, you can add `console.log` statements in your tRPC router functions (`sirius-ui/src/server/api/routers/*.ts`). These logs will appear in the `sirius-ui` container logs (`docker compose logs -f sirius-ui`). +- **VS Code Debugging (Next.js)**: You can configure VS Code to attach to the Node.js process running inside the Docker container for more advanced debugging of the Next.js backend (BFF) part. This usually involves: + - Ensuring the Node.js process in the container is started with the `--inspect` flag (might require modifying the `dev` script in `package.json` and `Dockerfile` CMD if not already set up for this). + - Configuring port forwarding in `docker-compose.yaml` for the inspect port (e.g., `9229`). + - Setting up a `launch.json` configuration in VS Code to attach to the debugger. +- **Viewing Logs**: Use `docker compose logs -f sirius-ui` to see server-side logs from the Next.js application, including any errors or console output from tRPC procedures or server components. + +#### 3.1.9. Environment Variables + +`sirius-ui` utilizes environment variables for configuration. These are typically managed via an `.env` file in the `Sirius/sirius-ui/` directory. + +- **`.env` File**: The `Sirius/sirius-ui/Dockerfile` copies a `.env` file into the image: `COPY .env ./`. You should create this file if it doesn't exist, possibly by copying from an `.env.example` if provided. +- **Next.js Environment Variables**: + - Variables prefixed with `NEXT_PUBLIC_` are exposed to the browser (client-side JavaScript). + - Variables without this prefix are only available on the server-side (Next.js backend/BFF). +- **Key Variables (Examples - actual variables may differ)**: + + - `DATABASE_URL`: If Prisma or another ORM is used directly by the UI's BFF for some tasks (though primary DB interaction is via `sirius-api`). + - `NEXTAUTH_URL`: For NextAuth.js if used for authentication. + - `NEXTAUTH_SECRET`: Secret key for NextAuth.js. + - `RABBITMQ_URL`: URL for connecting to the RabbitMQ service (e.g., `amqp://guest:guest@sirius-rabbitmq:5672/`). Used by the BFF to send messages to `sirius-engine`. + - `SIRIUS_API_URL`: Base URL for the `sirius-api` service (e.g., `http://sirius-api:9001/api/v1`) if the BFF needs to call it directly. + - `NEXT_PUBLIC_CLIENTVAR`: An example variable shown in `docker-compose.yaml` build args, exposed to the client. + - `SKIP_ENV_VALIDATION=1`: As seen in the `Dockerfile`, this is set to bypass environment variable validation, likely from tRPC or a similar library that checks for expected env vars. + +- **Loading in Docker**: The `Dockerfile` copies the `.env` file. During local development with `docker compose up`, the volume mount `- ./sirius-ui:/app` ensures that your local `.env` file is used. +- **Build Arguments**: The `docker-compose.yaml` for `sirius-ui` shows an example of passing build arguments: + ```yaml + args: + NEXT_PUBLIC_CLIENTVAR: "clientvar" + ``` + These can be used to set environment variables at build time. + +### 3.2. `sirius-api` (Backend API) + +#### 3.2.1. Overview & Purpose + +The `sirius-api` service is a backend application written in Go. It exposes a RESTful API that serves as a primary interface for data manipulation and core business logic not directly handled by the UI's BFF or the specialized `sirius-engine`. It interacts with the data stores (PostgreSQL, Valkey) and communicates with other services like `sirius-engine` via RabbitMQ. + +As defined in `docker-compose.yaml`: + +```yaml +sirius-api: + build: ./sirius-api/ + container_name: sirius-api + hostname: sirius-api + restart: always + image: sirius-api + ports: + - "9001:9001" + volumes: + - ./sirius-api:/api + # - ../minor-projects/go-api:/go-api # Local Development +``` + +_(Source: `Sirius/docker-compose.yaml`)_ + +The commented-out volume `../minor-projects/go-api:/go-api` suggests that `go-api` is a shared library used by this service, likely containing common Go code for database interaction, models, etc. + +#### 3.2.2. Technology Stack + +- **Go (Golang)**: The primary programming language, chosen for its performance and concurrency features. +- **Fiber**: A Go web framework inspired by Express.js, used for building the RESTful API. It's known for its speed and low memory footprint. +- **Go Modules**: For dependency management. +- **Air**: Used for live reloading during development, as indicated by the `Dockerfile`. + +#### 3.2.3. Docker Configuration (`sirius-api/Dockerfile`) + +The `Sirius/sirius-api/Dockerfile` sets up the Go environment and uses `air` for development, enabling hot reloading of the application upon code changes. + +```dockerfile +# sirius-api Dockerfile + +FROM golang:latest +WORKDIR /api + +COPY .air.toml .air.toml + +# Dependencies +RUN apt-get update + +WORKDIR /api +#DEV Dependencies +RUN go install github.com/air-verse/air@latest + + +# Invoke air to run the server after volume mount +CMD ["air", "-c", ".air.toml"] + +EXPOSE 9001 +``` + +_(Source: `Sirius/sirius-api/Dockerfile`)_ + +The Dockerfile copies an `.air.toml` configuration file, installs `air`, and sets the `CMD` to run the API using `air`. Port `9001` is exposed for the API service. + +#### 3.2.4. Key Functionalities (High-Level) + +Based on the `go-api/docs/documentation.md` (which describes the `github.com/SiriusScan/go-api` package likely used by this service), the `sirius-api` would be responsible for functionalities such as: + +- **Host Management**: CRUD operations for hosts, retrieving host details, and statistics. +- **Vulnerability Management**: Adding, retrieving, and checking for vulnerabilities. +- **Database Interaction**: Managing connections and operations with PostgreSQL via GORM (as suggested by `go-api` documentation). +- **Key-Value Store Interaction**: Interfacing with Valkey for caching or other purposes. +- **NVD Integration**: Potentially fetching CVE information from the National Vulnerability Database. + +Example from `go-api/docs/documentation.md` showing host management functions: + +```go +// GetHost retrieves a host by IP address +func GetHost(ip string) (sirius.Host, error) + +// GetAllHosts retrieves all hosts from the database +func GetAllHosts() ([]sirius.Host, error) + +// AddHost adds or updates a host in the database +func AddHost(host sirius.Host) error +``` + +_(Source: `go-api/docs/documentation.md`)_ + +#### 3.2.5. Communication + +- **Client Interaction**: Exposes RESTful endpoints on port `9001` for consumption by `sirius-ui` (either directly or via its BFF) or other potential clients. +- **Internal Communication**: Communicates with `sirius-engine` via RabbitMQ for delegating tasks or sending notifications. +- **Data Stores**: Directly interacts with `sirius-postgres` and `sirius-valkey`. + +#### 3.2.6. Key Directory Structure + +The `sirius-api` service, being a Go application using the Fiber framework, typically has a structure that might include: + +- **`main.go`**: The entry point of the application. Initializes the Fiber app, sets up middleware, defines routes, and starts the server. +- **`handlers/` (or `controllers/`)**: Contains Go files with handler functions for different API routes. Each handler processes incoming requests, interacts with services or databases, and returns responses. +- **`routes/`**: Might contain files that define route groups and associate them with handlers, helping to organize routing logic if `main.go` becomes too crowded. +- **`models/`**: Could contain Go struct definitions representing data entities (e.g., `Host`, `Vulnerability`). However, much of this might be centralized in the shared `go-api` library if it's used extensively. +- **`middleware/`**: For custom Fiber middleware (e.g., for authentication, logging, CORS). +- **`config/`**: For application configuration loading (e.g., reading database credentials, port numbers from environment variables or config files). +- **`Dockerfile`**: Defines how the `sirius-api` Go application is built into a Docker image. +- **`.air.toml`**: Configuration file for `air`, the live-reloading tool used for development. Specifies build commands, run commands, and files to watch. +- **`go.mod` and `go.sum`**: Go module files managing project dependencies. +- **Shared `go-api` Library**: The `docker-compose.yaml` mentions a commented-out volume mount for `../minor-projects/go-api`. This external library likely contains shared database models (GORM structs), database interaction logic (PostgreSQL, Valkey), RabbitMQ client utilities, and other common functionalities used by both `sirius-api` and potentially `sirius-engine`. + - When developing `sirius-api`, if it relies on `go-api`, ensure this library is accessible in your Go module path or use the volume mount for local development of `go-api` itself. + +#### 3.2.7. Local Development & Debugging + +Developing and debugging the Go-based `sirius-api` service involves these common practices: + +- **Prerequisites**: Ensure Go is installed locally. +- **Running with Docker Compose & Air**: + - The `sirius-api` service in `docker-compose.yaml` mounts the local `./sirius-api:/api` directory. + - Its `Dockerfile` sets `air -c .air.toml` as the command. `air` watches for file changes in the mounted directory and automatically recompiles and restarts the Go application. + - Start services with `docker compose up`. Changes to `.go` files in your local `Sirius/sirius-api/` directory will trigger a reload within the container. +- **Viewing Logs**: Use `docker compose logs -f sirius-api` to see the output from `air` (compilation status, errors) and any logs generated by the Fiber application (e.g., request logs, `fmt.Println` or logger output). +- **Testing Endpoints**: Use tools like `curl`, Postman, or Insomnia to send HTTP requests to your API endpoints (e.g., `http://localhost:9001/your-endpoint`). +- **Go Debugging (Delve)**: For step-through debugging of Go code: + + - **Install Delve**: You might need Delve installed locally or ensure it's available within the Docker container if you intend to debug inside it. + - **Modify `.air.toml` for Debugging**: You can adjust the `cmd` in `.air.toml` to start your application with Delve listening for a debugger. For example: + + ```toml + # .air.toml example modification for delve + [build] + cmd = "go build -o ./tmp/main ." + # ... other build settings + + [run] + # cmd = "./tmp/main" # Original run command + cmd = "dlv --listen=:2345 --headless=true --api-version=2 --accept-multiclient exec ./tmp/main" # Delve command + # ... other run settings + ``` + + - **Expose Delve Port**: In `docker-compose.yaml`, expose the Delve port (e.g., `2345:2345`) for the `sirius-api` service. + - **VS Code/GoLand Debug Configuration**: Configure your IDE (VS Code with Go extension, or GoLand) to attach to the remote Delve debugger running in the Docker container. Create a debug configuration (e.g., `Go Remote` in VS Code's `launch.json`) pointing to `localhost:2345`. + - Set breakpoints in your Go code and start the debugging session from your IDE. + +- **Database Interaction**: If debugging issues related to database queries (using `go-api` library and GORM), GORM has logging capabilities that can be enabled to see the exact SQL queries being executed. This logging would appear in the `sirius-api` container logs. + +#### 3.2.8. Environment Variables + +The Go-based `sirius-api` service is configured using environment variables. While a dedicated `.env` file isn't explicitly copied in its `Dockerfile` (unlike `sirius-ui`), environment variables can be supplied to Docker containers in several ways: + +- **`docker-compose.yaml`**: The most common method for development is to set environment variables directly in the `docker-compose.yaml` file for the `sirius-api` service. + ```yaml + # Example in docker-compose.yaml + sirius-api: + # ... other settings ... + environment: + - API_PORT=9001 + - POSTGRES_HOST=sirius-postgres + - POSTGRES_USER=postgres + - POSTGRES_PASSWORD=postgres + - POSTGRES_DB=sirius + - POSTGRES_PORT=5432 + - VALKEY_HOST=sirius-valkey + - VALKEY_PORT=6379 + - RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/ + # - GO_ENV=development # Or production + ``` +- **Operating System Environment**: Docker containers can inherit environment variables from the shell session where `docker compose up` is executed, though this is less explicit for service-specific configuration. +- **Go Code**: The Go application would typically use the `os` package (e.g., `os.Getenv("API_PORT")`) or a configuration library (like Viper) to read these environment variables at runtime. + +- **Key Variables (Examples - derived from typical Go API needs and inter-service communication within Sirius Scan)**: + - `API_PORT`: Port on which the Fiber API server listens (e.g., `9001`). + - `POSTGRES_HOST`: Hostname for the PostgreSQL service (e.g., `sirius-postgres`). + - `POSTGRES_USER`: Username for PostgreSQL. + - `POSTGRES_PASSWORD`: Password for PostgreSQL. + - `POSTGRES_DB`: Database name in PostgreSQL (e.g., `sirius`). + - `POSTGRES_PORT`: Port for PostgreSQL (e.g., `5432`). + - `VALKEY_HOST`: Hostname for the Valkey service (e.g., `sirius-valkey`). + - `VALKEY_PORT`: Port for Valkey (e.g., `6379`). + - `RABBITMQ_URL`: Connection string for RabbitMQ, used for publishing tasks or messages to `sirius-engine`. + - `GO_ENV` or `GIN_MODE` (if Fiber uses similar conventions to Gin): To set a development or production mode, which might affect logging levels or error handling (e.g., `development`, `production`). + +Check the `sirius-api` Go source code (especially `main.go` or any `config` package) to identify the exact environment variables it expects. + +### 3.3. `sirius-engine` (Core Processing Engine) + +#### 3.3.1. Overview & Purpose + +The `sirius-engine` is the central nervous system of Sirius Scan. Written in Go, it is responsible for orchestrating scanning tasks, managing distributed agents (`app-agent`), and running various specialized sub-applications that provide core functionalities like scanning (`app-scanner`) and terminal access (`app-terminal`). It receives tasks primarily via RabbitMQ from `sirius-ui` or `sirius-api` and coordinates the execution of these tasks using its sub-modules and agents. + +As defined in `docker-compose.yaml`: + +```yaml +sirius-engine: + build: ./sirius-engine/ + container_name: sirius-engine + hostname: sirius-engine + restart: always + image: sirius-engine + ports: + - "5174:5174" # Likely a primary port for the engine itself + - "50051:50051" # gRPC port for agent communication + volumes: + - ./sirius-engine:/engine + - ../minor-projects/app-agent:/app-agent + # - ../minor-projects/go-api:/go-api # Local Development + # - ../minor-projects/app-scanner:/app-scanner # Local Development + # - ../minor-projects/app-terminal:/app-terminal # Local Development + # - ../minor-projects/nmap-db:/nmap-db # Local Development + # depends_on: + # - rabbitmq # Dependency is implied for message consumption +``` + +_(Source: `Sirius/docker-compose.yaml`)_ + +The volume mounts for `app-agent` (and commented out ones for other `minor-projects`) indicate that these sub-applications are developed as potentially separate projects but are integrated into the engine's runtime environment. + +#### 3.3.2. Technology Stack + +- **Go (Golang)**: The primary language for its performance, concurrency, and suitability for system-level programming. +- **gRPC**: Used for communication with `app-agent` instances. +- **RabbitMQ Client**: For receiving tasks and publishing results/status. +- **Air**: For live reloading during development, as suggested by the `.air.toml` file and common Go development practices (though `air` itself is installed in the `app-scanner` context within the `sirius-engine` Dockerfile). + +#### 3.3.3. Docker Configuration (`sirius-engine/Dockerfile`) + +The `Sirius/sirius-engine/Dockerfile` is responsible for setting up a comprehensive environment that not only runs the engine's Go code but also prepares and includes several key tools and sub-applications. + +Key aspects of the Dockerfile: + +```dockerfile +# sirius-engine Dockerfile + +FROM golang:latest +WORKDIR /engine + +COPY .air.toml .air.toml # Air configuration for hot-reloading (likely for sub-apps) + +RUN apt-get update -y +RUN apt-get upgrade -y +RUN apt-get install -y libpcap-dev libicu-dev # System dependencies + +# NMAP Installation +RUN apt-get install -y nmap + +# Rust Scan Installation +WORKDIR /tmp +RUN curl https://sh.rustup.rs -sSf | bash -s -- -y +ENV PATH="/root/.cargo/bin:${PATH}" +RUN cargo install --git https://github.com/RustScan/RustScan.git --branch master + +# PowerShell Installation +WORKDIR /opt/microsoft/powershell +RUN ARCH=$(uname -m) && \ + case "$ARCH" in \ + "aarch64") \ + echo "Installing ARM64 version" && \ + wget https://github.com/PowerShell/PowerShell/releases/download/v7.5.0/powershell-7.5.0-linux-arm64.tar.gz && \ + tar -xvf powershell-7.5.0-linux-arm64.tar.gz \ + ;; \ + "x86_64") \ + echo "Installing AMD64 version" && \ + wget https://github.com/PowerShell/PowerShell/releases/download/v7.5.0/powershell-7.5.0-linux-x64.tar.gz && \ + tar -xvf powershell-7.5.0-linux-x64.tar.gz \ + ;; \ + *) \ + echo "Unsupported architecture: $ARCH" && exit 1 \ + ;; \ + esac +RUN chmod +x /opt/microsoft/powershell/pwsh +RUN ln -s /opt/microsoft/powershell/pwsh /usr/bin/pwsh + +# Set up NSE directory structure (for Nmap Scripting Engine used by app-scanner) +RUN mkdir -p /opt/sirius/nse && \ + chown -R 1000:1000 /opt/sirius && \ + chmod -R 755 /opt/sirius + +# App Repos - Cloning sub-application source code +WORKDIR / +RUN git clone https://github.com/SiriusScan/app-scanner.git +RUN git clone https://github.com/SiriusScan/app-terminal.git +RUN git clone https://github.com/SiriusScan/go-api.git # go-api likely contains shared code/models + +WORKDIR /app-scanner # Setting WORKDIR for app-scanner specific setup +#DEV Dependencies for app-scanner (Air) +RUN go install github.com/air-verse/air@latest + +# Add startup script and make it the entrypoint +RUN apt install dos2unix +COPY start.sh / +RUN dos2unix /start.sh +RUN chmod +x /start.sh + +ENTRYPOINT ["/start.sh"] +``` + +_(Source: `Sirius/sirius-engine/Dockerfile`)_ + +**Key takeaways from the Dockerfile:** + +- **Tooling**: Installs essential scanning tools (Nmap, RustScan) and PowerShell, making them available within the engine's container environment, likely for use by sub-applications. +- **Sub-Module Integration**: It directly clones the repositories for `app-scanner`, `app-terminal`, and `go-api`. This means the source code for these modules is present within the `sirius-engine` container. +- **`start.sh` Script**: This is the crucial `ENTRYPOINT`. The `start.sh` script (not provided but its actions can be inferred) is responsible for: + - Initializing the main `sirius-engine` Go application. + - Potentially building and running the cloned sub-applications (`app-scanner`, `app-terminal`). It might use `air` for hot reloading these sub-apps if they are Go-based and have an `.air.toml` configurations. + - Managing the lifecycle of these internal applications. + +#### 3.3.4. Modular Design (Loading Sub-Applications) + +The `sirius-engine` achieves its modularity by incorporating other specialized applications (`app-scanner`, `app-terminal`) directly into its operational environment. As indicated by the `Dockerfile` and `docker-compose.yaml`: + +- **`app-scanner`**: Cloned into the container. Likely provides scanning capabilities, potentially invoked by the main engine process. The setup of `/opt/sirius/nse` suggests it heavily uses Nmap and its scripting engine. +- **`app-terminal`**: Cloned into the container. Provides terminal functionalities. +- **`app-agent`**: While its source might be volume-mounted from `../minor-projects/app-agent` (for local dev), the engine is designed to communicate with `app-agent` instances via gRPC. The engine itself might not run the `app-agent` code directly but orchestrates and communicates with separate agent processes (which could also be running in other containers or on remote hosts). +- **`go-api` (cloned repository)**: This is likely a shared Go library containing common code, models, and utilities used by both `sirius-api` (via its own build) and potentially `sirius-engine` or its sub-modules like `app-scanner`. + +The `start.sh` script is the primary mechanism that brings these components to life within the `sirius-engine` container, managing their execution and potentially their inter-process communication if they run as separate processes within the container. + +#### 3.3.5. Communication + +- **Task Reception**: Listens to RabbitMQ queues for tasks (e.g., scan requests, command execution requests) from `sirius-ui` (via its BFF) and `sirius-api`. +- **Agent Communication**: Communicates with `app-agent` instances via gRPC on port `50051`. This is used for sending commands to agents and receiving results or status updates. +- **Internal Orchestration**: Manages and communicates with `app-scanner` and `app-terminal` (details depend on `start.sh` implementation - could be via IPC, local network calls if they expose ports, or direct function calls if they are run as libraries). +- **Data Stores**: Interacts with `sirius-postgres` and `sirius-valkey` for persisting and retrieving data related to scans, engine state, and agent information, likely using the shared `go-api` library. +- **Result/Status Publishing**: Publishes results, progress, and status updates back to RabbitMQ for consumption by other services. + +#### 3.3.6. Key Directory Structure + +The `Sirius/sirius-engine/` directory itself contains the core Go code for the engine. However, its operational environment inside the Docker container is more complex due to the integration of other tools and sub-applications as defined by its `Dockerfile`. + +- **`Sirius/sirius-engine/` (Local Project Directory)**: + + - Contains the main Go source files for the `sirius-engine` application (e.g., `main.go`, packages for gRPC services, RabbitMQ listeners, task orchestration logic). + - `Dockerfile`: Defines the build process for the `sirius-engine` image. + - `.air.toml`: Potentially used if `air` is run directly for the main engine code, though `start.sh` manages the overall startup. + - `start.sh`: The entrypoint script copied into the Docker image. This script is crucial as it initializes the engine and potentially manages the cloned sub-applications. + +- **Inside the Docker Container (as per `sirius-engine/Dockerfile`)**: + + - `/engine/`: The `WORKDIR` where the `Sirius/sirius-engine/` contents are copied. + - `/app-scanner/`: Cloned Git repository for `app-scanner`. + - `/app-terminal/`: Cloned Git repository for `app-terminal`. + - `/go-api/`: Cloned Git repository for the shared `go-api` library. + - `/opt/sirius/nse/`: Directory structure for Nmap NSE scripts, managed by `app-scanner`. + - Standard paths for installed tools like Nmap (`/usr/bin/nmap`), RustScan (`/root/.cargo/bin/rustscan`), PowerShell (`/usr/bin/pwsh`). + +- **Sub-Module Interaction**: The `sirius-engine` Go code, running from `/engine/`, interacts with: + - Cloned sub-applications (e.g., by executing their binaries if `start.sh` builds them, or via IPC if `start.sh` runs them as separate processes). + - Tools like Nmap/PowerShell via system calls. + - The `go-api` library as a Go module dependency. + +Understanding the `sirius-engine/Dockerfile` and the `start.sh` script (even if its content needs to be inferred based on Dockerfile actions) is key to grasping the engine's internal structure and operation. + +#### 3.3.7. Local Development & Debugging + +Developing `sirius-engine` and its integrated sub-applications (`app-scanner`, `app-terminal`) involves understanding its Dockerized environment and the `start.sh` script. + +- **Prerequisites**: Go installed locally. +- **Local Development of Sub-Modules (`app-scanner`, `app-terminal`, `go-api`)**: + - Clone the respective sub-module repository locally (e.g., into `../minor-projects/app-scanner`). + - In `Sirius/docker-compose.yaml`, uncomment the volume mount for that sub-module under the `sirius-engine` service definition (e.g., `- ../minor-projects/app-scanner:/app-scanner`). This mounts your local code into the engine's container, overriding the version cloned by the `sirius-engine/Dockerfile`. + - Changes to your local Go files for that sub-module will be picked up. If the sub-module has an `.air.toml` and `start.sh` is configured to use `air` for it, it should hot-reload within the `sirius-engine` container. +- **Local Development of `sirius-engine` Core**: + - The `Sirius/sirius-engine/` directory is already mounted by default in `docker-compose.yaml` (`- ./sirius-engine:/engine`). + - If the main engine Go application (started by `start.sh`) is also configured with `air` (e.g., via the `.air.toml` in `/engine/`), changes to its core Go files will trigger a reload. +- **`start.sh` Script**: This script is central. It controls how the main engine and its sub-modules are built (if necessary, e.g., `go build` for sub-apps) and run inside the container. You might need to inspect or modify `start.sh` to understand or alter the development workflow for components within the engine. +- **Viewing Logs**: Crucial for debugging. Use `docker compose logs -f sirius-engine`. This will show output from the main engine, `air` (for any components it manages), and the sub-applications. +- **Go Debugging (Delve)**: Similar to `sirius-api`, you can use Delve for debugging Go code within `sirius-engine` or its Go-based sub-modules. + - You'd need to ensure Delve is available in the container and modify `start.sh` (or an `.air.toml` used by `start.sh`) to launch the target Go application with Delve. + - Expose Delve's port (e.g., `2345`) from the `sirius-engine` container in `docker-compose.yaml`. + - Attach your IDE's debugger to the exposed port. +- **Interacting with Tools**: The engine has Nmap, RustScan, PowerShell, etc. The `start.sh` might make these available on the PATH within the container, or sub-modules might call them with full paths. You can use `docker exec -it sirius-engine bash` to get a shell inside the running container to manually test these tools or explore the environment. + +#### 3.3.8. Environment Variables + +The `sirius-engine` (a Go application) is configured using environment variables. These are typically set in the `docker-compose.yaml` file for the `sirius-engine` service or passed to the Docker container at runtime. + +- **Setting via `docker-compose.yaml`**: This is the most common method for development. + + ```yaml + # Example in docker-compose.yaml for sirius-engine + services: + sirius-engine: + # ... other settings ... + environment: + - ENGINE_MAIN_PORT=5174 # Example port for engine-specific services + - GRPC_AGENT_PORT=50051 # Port for gRPC communication with app-agents + - RABBITMQ_URL=amqp://guest:guest@sirius-rabbitmq:5672/ + - POSTGRES_HOST=sirius-postgres + - POSTGRES_USER=postgres + - POSTGRES_PASSWORD=postgres + - POSTGRES_DB=sirius + - VALKEY_HOST=sirius-valkey + # GO_ENV can be used to control behavior (e.g., logging level) + - GO_ENV=development + # Variables for sub-modules like app-scanner if they are configured via env vars + # - SCANNER_DEFAULT_TIMEOUT=3600 + ``` + +- **Reading in Go**: The engine's Go code (and its sub-modules if they are also Go-based and configured via environment) would use the `os` package (e.g., `os.Getenv("GRPC_AGENT_PORT")`) or a configuration library to read these values. + +- **Key Environment Variables (Examples for `sirius-engine`)**: + - `ENGINE_MAIN_PORT`: A primary port the engine might use for its own services (if any, besides gRPC). + - `GRPC_AGENT_PORT`: The port on which the engine's gRPC server listens for connections from `app-agent` instances (e.g., `50051`). + - `RABBITMQ_URL`: Connection string for RabbitMQ, used for consuming tasks and publishing results/status. + - `POSTGRES_HOST`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`: For connecting to the PostgreSQL database (likely via the shared `go-api` library). + - `VALKEY_HOST`: For connecting to the Valkey key-value store. + - `GO_ENV`: To control execution mode (e.g., `development`, `production`), which might affect logging, debugging features, etc. + - Sub-module specific variables: If sub-applications like `app-scanner` or `app-terminal` are configured via environment variables, those would also be passed through `sirius-engine`'s environment if `start.sh` propagates them. + +Consult the `sirius-engine`'s `main.go`, `start.sh` script, and any configuration packages or sub-module documentation to identify the precise set of environment variables required and how they are consumed. + +### 3.4. `go-api` (Shared Backend SDK) + +#### 3.4.1. Overview & Purpose + +The `go-api` project ([github.com/SiriusScan/go-api](https://github.com/SiriusScan/go-api)) is a crucial shared Go library, or Software Development Kit (SDK), designed to be used by all Go-based backend services within the Sirius Scan ecosystem, primarily `sirius-api` and `sirius-engine` (including its sub-modules like `app-scanner`). + +Its main purpose is to provide a centralized and standardized way to interact with shared backend infrastructure components, abstracting away common functionalities and ensuring consistency across the platform. This SDK acts as the single source of truth for critical backend operations, offering several benefits: + +- **Code Reusability**: Reduces code duplication significantly by providing common functions for database access, message queuing, caching, etc. +- **Consistency**: Ensures that all backend services interact with infrastructure components (like databases and message queues) in a uniform way, using the same data models and patterns. This minimizes integration errors and simplifies debugging. +- **Maintainability**: Centralizes the logic for core interactions. If a database schema changes or a message queue protocol needs an update, modifications can often be made primarily within `go-api`, with consuming services benefiting from these updates by simply updating their dependency. +- **Developer Productivity**: Speeds up development of new backend features and services by providing ready-to-use, tested components for common backend tasks. Developers can focus on business logic rather than boilerplate infrastructure code. +- **Simplified Onboarding**: New developers working on backend services can quickly understand how to interact with core infrastructure by learning the `go-api` interfaces. + +Key areas of abstraction include: + +- **Database Abstraction**: Simplifies interactions with PostgreSQL through GORM. +- **Message Queue Utilities**: Provides helpers for robust RabbitMQ communication. +- **Key-Value Store Access**: Offers a standardized interface for Valkey. +- **Core Data Models**: Defines common Go structs representing data entities used across services (e.g., hosts, vulnerabilities). +- **NVD Integration**: Facilitates fetching and using data from the National Vulnerability Database to enrich scan findings. + +By centralizing these functions, `go-api` is fundamental to the stability, consistency, and agile development of Sirius Scan's backend capabilities. + +#### 3.4.2. Technology Stack + +The `go-api` library is built using a selection of robust and widely-used technologies in the Go ecosystem: + +- **Go (Golang)**: The primary programming language, chosen for its performance, concurrency features, and strong standard library, making it well-suited for backend SDK development. +- **GORM ([gorm.io](https://gorm.io/))**: A popular Go ORM (Object-Relational Mapper) used for interacting with the PostgreSQL database. GORM simplifies database operations by allowing developers to work with Go structs instead of writing raw SQL queries, increases developer productivity, and provides features like schema migration, transaction management, and association handling. +- **RabbitMQ Client Libraries**: Standard Go libraries for the AMQP 0-9-1 protocol (e.g., `github.com/streadway/amqp` or a similar actively maintained fork) are used to interact with `sirius-rabbitmq`. These libraries provide the foundational tools for publishing messages and subscribing to queues. +- **Valkey Client Libraries**: Go libraries specifically designed for interacting with Valkey (or Redis-compatible stores) are used to connect to and perform operations against the `sirius-valkey` key-value store. +- **Go Modules**: `go-api` is structured as a Go module, which allows it to manage its own dependencies (like GORM and AMQP clients) and to be easily consumed as a versioned dependency by other Go projects (`sirius-api` in particular). + +#### 3.4.3. Key Functionalities + +Based on its documentation (`go-api/docs/documentation.md`) and observed usage patterns, `go-api` provides the following key functionalities, typically organized into distinct packages: + +- **Database Layer (`sirius/postgres`)**: + + - **Connection Management**: Initializes and provides access to the global GORM database instance (`*gorm.DB`). This includes: + - Handling of database connection parameters (e.g., host, port, user, password, DB name) typically read from environment variables. + - Automatic connection retry mechanisms with exponential backoff to handle transient network issues. + - Environment-aware configuration (e.g., different connection settings for Docker vs. local development environments). + - Automatic schema initialization and migration capabilities using GORM's migration features, ensuring the database schema is up-to-date with model definitions. + - Efficient connection pooling managed by GORM to optimize database resource usage. + - **Data Models (`sirius/postgres/models`)**: + - Defines a comprehensive set of GORM structs representing the core data entities of Sirius Scan. These include `Host`, `Vulnerability`, `Port`, `Service`, `Note`, `CPE (Common Platform Enumeration)`, and various CVE-related structures (e.g., for storing information from NVD). + - These models define table names, columns, data types, relationships (e.g., one-to-many, many-to-many), and database constraints, serving as the ORM mapping layer. + +- **Business Logic Modules (Database Interactors)**: + + - **Host Management (`sirius/host`)**: Provides an API for performing CRUD (Create, Read, Update, Delete) operations on host records stored in the database. For example: + - `GetHost(ip string) (sirius.Host, error)`: Retrieves a host by its IP address. + - `GetAllHosts() ([]sirius.Host, error)`: Fetches all host records. + - `AddHost(host sirius.Host) error`: Adds a new host or updates an existing one. + - Additional functionalities might include calculating host vulnerability statistics, managing associated ports and services, and computing risk scores or other metrics related to hosts. + - **Vulnerability Management (`sirius/vulnerability`)**: Offers functions for managing vulnerability data within the system: + - `GetVulnerability(vid string) (nvd.CveItem, error)`: Retrieves detailed vulnerability information, potentially by CVE ID. + - `CheckVulnerabilityExists(vid string) bool`: Checks if a specific vulnerability is already known to the system. + - `AddVulnerability(vuln sirius.Vulnerability) error`: Adds new vulnerability findings to the database. + +- **Infrastructure Integration Modules**: + + - **Queue System (`sirius/queue`)**: Encapsulates interactions with RabbitMQ. + - `MessageProcessor func(msg string)`: Defines a type for callback functions that process incoming messages. + - `Listen(qName string, messageProcessor MessageProcessor)`: Subscribes to a specified RabbitMQ queue and invokes the `messageProcessor` for each received message. This often involves running processors in separate goroutines for concurrent handling. + - `Send(qName string, message string) error`: Publishes a message to a specified RabbitMQ queue. + - Handles details like automatic queue declaration (ensuring queues exist before use), connection management to RabbitMQ, and basic error handling/logging for queue operations. + - **Key-Value Store (`sirius/store`)**: Provides a standardized way to interact with the Valkey cache. + - `KVStore` interface: Defines a contract for key-value operations, promoting testability and potential future backend swaps. + - `SetValue(ctx context.Context, key, value string) error`: Stores a value. + - `GetValue(ctx context.Context, key string) (ValkeyResponse, error)`: Retrieves a value. `ValkeyResponse` likely encapsulates the result and any metadata. + - `Close() error`: Closes the connection to the Valkey store. + - The implementation uses a Valkey client to connect to `sirius-valkey`. + - **NVD Integration (`nvd`)**: Contains logic for interacting with the National Vulnerability Database (NVD) API. + - This is crucial for fetching up-to-date details about CVEs (Common Vulnerabilities and Exposures), such as severity scores (CVSS), descriptions, and references. This data enriches the vulnerability information identified by local scans. + +- **Utility Functions (`utils`)** (if present): + - This package would typically house common, reusable helper functions that don't fit neatly into the other categories. Examples could include: + - Configuration loading helpers (e.g., reading specific environment variables with defaults). + - Custom error handling types or wrappers. + - Common logging setup or utility functions. + - Data validation or sanitization routines. + +#### 3.4.4. Usage & Integration + +The `go-api` SDK is a cornerstone of Sirius Scan's backend architecture, used extensively by `sirius-api` and `sirius-engine`: + +- **`sirius-api` (Backend API Service)**: + + - **Integration Method**: Consumes `go-api` as a standard Go module dependency, specified in its `go.mod` file. This allows `sirius-api` to depend on specific, versioned releases of `go-api`, promoting stable builds. + - **Usage Examples**: + - When an HTTP request to create a new host arrives at a `sirius-api` endpoint, the handler function would call `host.AddHost(newHostInfo)` from `go-api` to persist the host. + - Endpoints for retrieving vulnerability details would use functions like `vulnerability.GetVulnerability(cveID)`. + - It utilizes `go-api` for all its interactions with PostgreSQL (via GORM models and connection management provided by `go-api`), Valkey (via the `store` package), and potentially for publishing messages to RabbitMQ if it needs to delegate long-running tasks or notify `sirius-engine` (e.g., via `queue.Send()`). + - **Local Development**: The `docker-compose.yaml` for `sirius-api` includes a commented-out volume mount: `- ../minor-projects/go-api:/go-api`. Uncommenting this allows developers to mount a local clone of the `go-api` repository directly into the `sirius-api` container. This is invaluable when making changes to `go-api` and wanting to test them immediately with `sirius-api` without needing to publish a new version of `go-api` first. + +- **`sirius-engine` (Core Processing Engine & its Sub-Modules like `app-scanner`)**: + - **Integration Method**: The `sirius-engine/Dockerfile` explicitly clones the `go-api` repository (e.g., `git clone https://github.com/SiriusScan/go-api.git /go-api`) into its build context. The main engine Go application and its Go-based sub-modules (like `app-scanner`, which is also cloned into the engine's image) then use `go-api` as a local library by adjusting their Go module paths or using `replace` directives in their `go.mod` files to point to this local copy. + - This approach ensures that `sirius-engine` and its tightly coupled sub-modules are built with a specific, consistent version of `go-api` that is bundled directly within the engine's Docker image. + - While simpler for the bundled environment of `sirius-engine`, it requires careful coordination if `go-api` undergoes breaking changes, as the `sirius-engine` image would need to be rebuilt to pick up the new `go-api` version. + - **Usage Examples**: + - When `sirius-engine` receives a scan task from RabbitMQ (via `queue.Listen()` from `go-api`), it might first retrieve target details using `host.GetHost()`. + - After `app-scanner` (a sub-module of the engine) completes a scan, it would use `go-api` functions (e.g., `host.AddHost` to update host details, `port.AddPort`, `service.AddService`, `vulnerability.AddVulnerability`) to parse and store the scan results in the PostgreSQL database. + - The engine might use `store.SetValue()` from `go-api` to cache intermediate scan states or frequently accessed data in Valkey. + - It relies on `go-api`'s `queue` package for consuming tasks from RabbitMQ and potentially for publishing status updates or results back to other queues. + - **Local Development**: Similar to `sirius-api`, the `docker-compose.yaml` for `sirius-engine` has a commented-out volume mount for `go-api`. Enabling this mount allows developers to test local changes to `go-api` directly within the `sirius-engine`'s operational environment. + +This shared SDK strategy is pivotal. It ensures that all backend Go components operate on the same data models and use consistent, tested methods for accessing shared infrastructure resources, which is critical for the overall system's reliability and maintainability. + +#### 3.4.5. Development & Testing of `go-api` + +Developing and maintaining `go-api` as a standalone SDK involves its own set of practices to ensure its quality and reliability: + +- **Repository Structure**: `go-api` is maintained in its own Git repository ([github.com/SiriusScan/go-api](https://github.com/SiriusScan/go-api)), allowing for independent versioning and development lifecycle. +- **Unit Testing**: Each package and significant function within `go-api` (e.g., database interaction logic, queue sending/receiving, NVD API calls) should be covered by comprehensive unit tests. Go's built-in `testing` package is used for this. Mocks and interfaces are employed to isolate components during testing (e.g., mocking database connections or RabbitMQ interactions). +- **Integration Testing**: Beyond unit tests, `go-api` likely requires integration tests that verify its interaction with actual external services (PostgreSQL, RabbitMQ, Valkey). These tests might be run in CI/CD pipelines against test instances of these services, or locally using Docker Compose to spin up the necessary dependencies. +- **Versioning**: `go-api` should follow semantic versioning (SemVer). New versions are tagged in its repository (e.g., `v1.0.0`, `v1.1.0`). Consuming services like `sirius-api` can then specify the version of `go-api` they depend on in their `go.mod` file. +- **Dependency Management**: `go-api` itself manages its dependencies (like GORM, AMQP clients) using Go Modules. These are specified in its own `go.mod` file. +- **Documentation**: Maintaining clear documentation (like the `go-api/docs/documentation.md`) is essential for developers of consuming services to understand how to use the SDK, its available functions, data models, and any conventions. + +Careful testing and versioning of `go-api` are crucial because changes to it can impact multiple backend services. Breaking changes must be managed through major version increments and communicated clearly to the teams working on consuming services. + +## 4. Sub-Modules & Agents + +### 4.1. `app-scanner` + +#### 4.1.1. Purpose and Functionality + +The `app-scanner` sub-module, running within the `sirius-engine` container, is the primary component responsible for executing network scans. It leverages well-known scanning tools like Nmap and RustScan to discover hosts, open ports, services, and potential vulnerabilities based on Nmap Scripting Engine (NSE) scripts. + +**Key Functionalities**: + +- **Port Scanning**: Utilizes tools like Nmap and RustScan for fast and comprehensive port scanning to identify open TCP and UDP ports on target hosts. +- **Service Detection**: Employs Nmap's version detection capabilities (`-sV`) to identify the services running on discovered open ports and their versions. +- **OS Detection**: Uses Nmap's OS detection (`-O`) to attempt to identify the operating system of target hosts. +- **NSE Script Execution**: Manages and executes Nmap NSE scripts for vulnerability detection, further enumeration, or specific checks. This is a core feature for identifying potential issues. +- **Output Parsing**: Parses the XML output from Nmap (and potentially other tools) to extract structured data about hosts, ports, services, and script results. +- **Integration with `sirius-engine`**: Receives scan tasks from the main engine (which itself gets them from RabbitMQ), executes them, and returns structured results to the engine for persistence and further processing. + +It is typically a Go application, cloned into the `sirius-engine` container during its build process (or volume-mounted for local development). The `sirius-engine/Dockerfile` installs Nmap and RustScan, making them available for `app-scanner` to use. The `start.sh` script within `sirius-engine` likely manages the execution of `app-scanner`. + +#### 4.1.2. NSE (Nmap Script Engine) Management + +The Nmap Scripting Engine (NSE) is a powerful Nmap feature allowing users to write and use scripts (in Lua) to automate a wide array of networking tasks. Within Sirius Scan, `app-scanner` leverages NSE for advanced vulnerability detection, deeper service analysis, and more targeted information gathering beyond standard Nmap checks. + +The management of NSE scripts is a sophisticated process handled by the `app-scanner/internal/nse` Go package. This system ensures that NSE scripts are consistently managed, versioned, and synchronized across the platform. + +**Key Aspects of NSE Management in `app-scanner`**: + +- **Centralized Script Storage & Repositories**: + + - The primary directory for NSE scripts within the `sirius-engine` Docker container is `/opt/sirius/nse/`. This path is configured during the `sirius-engine` Docker build. + - Scripts are organized into repositories (e.g., `sirius-nse` cloned from `https://github.com/SiriusScan/sirius-nse.git`). Each repository can contain multiple Lua scripts and has its own manifest file. + +- **Manifest System for Script Definition & Discovery**: + + - **Repository List Manifest (`/opt/sirius/nse/manifest.json`)**: This top-level JSON file lists all external NSE script repositories that `app-scanner` should manage (containing their names and Git URLs). + - **Repository Manifest (`/manifest.json`)**: Each individual script repository contains its own manifest. This file is the source of truth for scripts within that repository, detailing metadata for each script, such as its name, path within the repository, supported protocols, description, author, and tags (e.g., `"vulners": {"name": "vulners", "path": "scripts/vulners.nse", ...}`). + - **Global Manifests in Valkey**: To ensure consistency across potentially multiple `sirius-engine` instances or for dynamic updates, `app-scanner` uses Valkey as a central store for global script information: + - `nse:repo-manifest`: Stores the global list of repositories, taking precedence over the local file-based repository list. + - `nse:manifest`: Stores a consolidated global manifest of all scripts from all repositories, including their metadata. + - **Local In-Memory Manifests**: During runtime, `app-scanner` maintains local, in-memory copies of these manifests for efficient access during scan configuration and execution. + +- **Synchronization Mechanism**: + + - `app-scanner` implements a robust synchronization system to keep scripts and their manifests up-to-date. The order of precedence is: **Global Valkey Manifests > Local Filesystem Manifests > Built-in Defaults**. + - The `SyncManager` within the `nse` package handles this synchronization. It clones/pulls script repositories from Git, reads local manifest files, and reconciles them with the global manifests stored in Valkey. + - This ensures that `app-scanner` always uses the most current and authoritative versions of scripts and their definitions. + +- **Script Content Storage in Valkey**: + + - Beyond manifests, the actual Lua code of NSE scripts can also be stored in Valkey under keys like `nse:script:`. + - This allows for dynamic updates to script content without needing to rebuild Docker images or manually distribute script files. When Nmap is invoked, `app-scanner` can provide it with the script content retrieved from Valkey. + +- **Usage During Scans**: + + - When a user configures a scan that includes NSE scripts, `sirius-engine` passes this configuration to `app-scanner`. + - `app-scanner`, leveraging its synchronized script manifests, selects the appropriate NSE scripts. + - It constructs Nmap command-line arguments to include these scripts (e.g., `--script `) and their arguments. + - Nmap executes these scripts against the target(s). + +- **Processing NSE Results**: + + - The output from NSE scripts (usually embedded in Nmap's XML output) is parsed by `app-scanner`. + - This output often contains crucial vulnerability information, detailed service enumerations, or specific findings relevant to the script's purpose. + - `app-scanner` then transforms these findings into a structured format suitable for storage in `sirius-postgres` (via `go-api`) and display in `sirius-ui`. + +- **Configuration & Extensibility**: + - The system is designed for extensibility, allowing new NSE script repositories to be added by updating the `nse:repo-manifest` in Valkey or the local `/opt/sirius/nse/manifest.json`. + - Users can select specific scripts or categories of scripts for their scans, providing fine-grained control over the scanning process. + +This comprehensive NSE management system ensures that Sirius Scan can effectively utilize the power of Nmap's scripting capabilities for in-depth security assessments, with a flexible and synchronized approach to script handling. + +### 4.2. [`app-terminal`](#app-terminal) + +#### 4.2.1. Purpose and Functionality + +The `app-terminal` sub-module, developed as a Go application within the `minor-projects/app-terminal` repository, provides a web-based PowerShell terminal interface accessible through `sirius-ui`. It is designed to enable users to execute commands securely on the system where `sirius-engine` is running, or potentially on remote systems if command execution is proxied through agents in the future. + +**Key Functionalities** (as per `app-terminal/README.md`): + +- **PowerShell Execution Backend**: Leverages PowerShell Core (`pwsh`) for command execution. PowerShell is installed within the `sirius-engine` Docker container specifically for use by `app-terminal`. +- **Secure Command Handling**: Aims to execute commands in isolated PowerShell sessions, with session cleanup after execution. +- **Message Queue Integration**: Communicates asynchronously with the broader Sirius Scan ecosystem (primarily `sirius-ui` via `sirius-engine`) using RabbitMQ. + - Receives command execution requests from a RabbitMQ queue. + - Sends command output (stdout, stderr) and status back via RabbitMQ queues. +- **Command Management**: `internal/terminal/manager.go` is responsible for handling incoming command requests from the queue and managing their lifecycle. +- **PowerShell Interface**: `internal/terminal/powershell.go` provides the abstraction layer for interacting with the PowerShell runtime, executing commands, and capturing output. +- **Output Formatting**: Processes and formats the raw output from PowerShell to be suitable for display in the `sirius-ui` terminal (which uses `xterm.js`). +- **Error Handling**: Implements error handling for PowerShell execution issues, queue communication problems, and session management. + +**Integration with `sirius-engine`**: + +- `app-terminal` is cloned into the `sirius-engine` Docker container during its build process (from `https://github.com/SiriusScan/app-terminal.git`). +- The `start.sh` script within `sirius-engine` is responsible for launching and managing the `app-terminal` Go application. +- `sirius-engine` acts as a router for terminal commands: when a user enters a command in `sirius-ui`'s terminal, the request (typically via tRPC to the UI's BFF) is put onto a RabbitMQ queue. `sirius-engine` consumes this message and, if it's a command for the local engine environment, forwards it to `app-terminal` for execution. + +The `app-terminal` provides a crucial capability for direct interaction with the engine's environment or potentially managed endpoints, supporting tasks like manual enumeration, configuration checks, or diagnostic actions. + +### 4.3. [`app-agent`](#app-agent) + +#### 4.3.1. Purpose and Functionality + +The `app-agent` is a Go application designed to run on remote hosts, acting as a client to the `sirius-engine`'s gRPC server. Its primary purpose is to extend the capabilities of Sirius Scan by allowing `sirius-engine` to delegate tasks, such as command execution or localized scanning, to these distributed agents. This enables Sirius Scan to interact with and assess systems that may not be directly accessible from the central `sirius-engine` instance. + +**Key Functionalities** (based on `app-agent/cmd/agent/README.md`): + +- **Remote Command Execution**: The core feature is its ability to receive shell command strings from `sirius-engine` via a gRPC call (`ExecuteCommand`) and execute these commands on the host where the agent is running. It then captures the standard output and standard error of the command and sends them back to the engine. +- **Connectivity Testing**: Implements a `Ping` gRPC method that `sirius-engine` can use to check the agent's reachability and operational status. +- **Persistent Connection**: Establishes a gRPC connection to the `sirius-engine` (server address configured via `SERVER_ADDRESS` environment variable, defaulting to `localhost:50051`). +- **Identification**: Identifies itself to the engine using an `AGENT_ID` (configurable via environment variable, defaults to the hostname), allowing the engine to manage and target specific agents. +- **Periodic Updates (Example)**: The example agent demonstrates the capability to perform actions periodically (e.g., running `ls -la` every 10 seconds and sending results), suggesting a model for continuous monitoring or data collection tasks. +- **Structured Logging**: Utilizes `zap` for structured logging, aiding in diagnostics and monitoring of the agent's behavior. +- **Graceful Shutdown**: Designed to handle termination signals for a clean shutdown process. + +**Deployment and Development Context**: + +- `app-agent` is developed in the `minor-projects/app-agent` repository. +- Unlike `app-scanner` or `app-terminal`, `app-agent` is not typically cloned into the `sirius-engine` Docker image. Instead, it's intended to be built and deployed as a separate binary or container on target machines where remote operations are needed. +- The `docker-compose.yaml` for `sirius-engine` includes a volume mount for `../minor-projects/app-agent:/app-agent`. This is primarily for a development scenario where `sirius-engine` might run an instance of `app-agent` locally for testing gRPC interactions, or if the engine itself needs to act as an agent for some reason, though its primary role is server. + +**Security Considerations**: The provided `app-agent` README explicitly states it's a basic example and lacks production-grade security features such as TLS for gRPC, authentication/authorization, command validation, and sandboxing. These would be critical additions for a secure deployment. + +#### 4.3.2. gRPC Communication with `sirius-engine` + +Communication between `app-agent` instances and `sirius-engine` is facilitated by gRPC, a high-performance, open-source universal RPC framework. + +- **Roles**: + + - `sirius-engine`: Acts as the gRPC **server**. It defines and implements the gRPC services (e.g., `AgentService` with methods like `Ping` and `ExecuteCommand`). It listens for incoming gRPC connections from agents, typically on port `50051` (as suggested by agent defaults and engine's Docker Compose port mapping). + - `app-agent`: Acts as the gRPC **client**. It initiates a connection to the `sirius-engine`'s gRPC server address. + +- **Protocol Definition (`.proto` files)**: + + - The gRPC services, methods, and message structures are defined in Protocol Buffer (`.proto`) files. The `app-agent` repository contains `proto/hello/hello.proto` (an example name) which would define services like: + + ```protobuf + service AgentService { + rpc Ping (PingRequest) returns (PingResponse); + rpc ExecuteCommand (CommandRequest) returns (stream CommandResponse); // Example: streaming for output + } + + message CommandRequest { + string agent_id = 1; + string command = 2; + } + + message CommandResponse { + string output = 1; + string error = 2; + bool completed = 3; + } + // ... other message definitions + ``` + + - Both `sirius-engine` and `app-agent` would generate gRPC server/client stubs and data types from these `.proto` files in Go using `protoc` and Go gRPC plugins. This ensures type safety and consistency in communication. + +- **Communication Flow (Example: `ExecuteCommand`)**: + + 1. `sirius-engine` decides to execute a command on a specific agent (identified by `AGENT_ID`). + 2. The engine, using its gRPC client stub for the `AgentService` (or by managing connections to agents), makes an `ExecuteCommand` RPC call to the target `app-agent`. The `CommandRequest` would contain the command string and potentially other parameters. + 3. The `app-agent` (gRPC client) receives this request via its gRPC server implementation of `ExecuteCommand`. + 4. The agent executes the command on its host system. + 5. The agent captures stdout/stderr and streams `CommandResponse` messages back to `sirius-engine`. This streaming is useful for long-running commands or commands that produce continuous output. + 6. `sirius-engine` receives the stream of responses and processes the output (e.g., stores it, forwards it to the UI via RabbitMQ). + +- **Connection Management**: Agents establish a connection to the engine. The engine needs to manage connections from multiple agents if it is to orchestrate a fleet of them. This might involve keeping track of active agents, their capabilities, and their gRPC channel information. + +- **Advantages of gRPC**: Chosen for its efficiency (uses HTTP/2 and Protocol Buffers), strong typing, support for streaming, and suitability for microservice communication. + +This gRPC interface is fundamental for `sirius-engine` to control and leverage distributed `app-agent` instances for various scanning and operational tasks. + +## 5. Data Persistence & Storage + +Sirius Scan relies on two primary data stores for persistence and caching: PostgreSQL for structured relational data and Valkey for key-value storage, often used for caching, session management, and managing dynamic configurations like NSE script manifests. + +### 5.1. PostgreSQL (`sirius-postgres`) + +PostgreSQL serves as the main relational database, storing the core structured data of the application. This includes information about scanned assets, vulnerabilities, scan configurations, and potentially user data. + +#### 5.1.1. Role and Data Stored + +- **Primary Datastore**: The authoritative source for persistent, relational data. +- **Hosts Information**: Details about discovered and scanned hosts (IP addresses, hostnames, operating systems, MAC addresses, etc.). +- **Ports & Services**: Information about open ports on hosts and the services running on them (port number, protocol, service name, version, state). +- **Vulnerabilities**: Detailed records of identified vulnerabilities (CVE IDs, descriptions, severity, affected hosts/ports, remediation status). +- **Scan Configurations & Results**: Parameters for scans performed and the summarized results associated with them. +- **User and Access Management**: (If implemented) User accounts, roles, and permissions. +- **Audit Trails**: Logs of significant actions performed within the system. + +The `go-api` SDK, particularly its GORM models, defines and interacts with this schema. + +#### 5.1.2. Schema Overview (Conceptual) + +While a full, detailed Entity-Relationship Diagram (ERD) is extensive, the conceptual schema revolves around several key entities and their relationships, managed via GORM models in `go-api`: + +- **`Hosts`**: The central entity representing a scanned asset. + - Attributes: `ID`, `IPAddress`, `Hostname`, `OS`, `MACAddress`, `Status` (e.g., up, down), `CreatedAt`, `UpdatedAt`. +- **`Ports`**: Represents network ports discovered on hosts. + - Attributes: `ID`, `PortNumber`, `Protocol` (TCP/UDP), `State` (open, closed, filtered). +- **`Services`**: Describes services running on specific ports. + - Attributes: `ID`, `Name`, `Version`, `Product`, `ExtraInfo`, `Banner`. +- **`Vulnerabilities`**: Stores information about identified vulnerabilities. + - Attributes: `ID`, `CVEID` (e.g., "CVE-2023-1234"), `Name`/`Title`, `Description`, `Severity` (e.g., Critical, High, Medium, Low, Info), `CVSSScore`, `References` (URLs to advisories). +- **`HostPorts` (Join Table for Hosts ↔ Ports/Services)**: + - Establishes a many-to-many relationship between `Hosts` and `Ports`. + - Often, service information is directly linked here or through a specific `HostPortService` record if a single port can host multiple services (less common for basic TCP/UDP, but possible with virtual hosting or more complex protocols). + - Likely contains `HostID`, `PortID`, and potentially `ServiceID` if services are modeled as distinct entities associated with a host-port pair. +- **`HostVulnerabilities` (Join Table for Hosts ↔ Vulnerabilities)**: + - Establishes a many-to-many relationship between `Hosts` and `Vulnerabilities`. + - Attributes: `HostID`, `VulnerabilityID`, `Port` (the specific port on the host where the vulnerability applies, if applicable), `Status` (e.g., new, confirmed, false positive, remediated), `FirstSeen`, `LastSeen`. +- **`CPEs (Common Platform Enumeration)`**: Stores CPE identifiers found on hosts/services, which can be linked to vulnerabilities. +- **`Notes`**: Allows users to add notes or comments to hosts, vulnerabilities, or other entities. +- **`ScanMetadata` / `ScanJobs`**: Tables to store information about scan configurations (targets, options used) and their execution status/history. + +The `go-api` library uses GORM to define these models as Go structs and manages their migrations, ensuring the database schema aligns with the application's data structures. The `Sirius/documentation/README.testing.md` document highlights the importance of these many-to-many relationships (Hosts-Ports, Hosts-Vulnerabilities) and provides context on how they are structured and tested. + +### 5.2. Valkey (`sirius-valkey`) + +Valkey (a fork of Redis) is employed as a high-performance in-memory key-value store. It is primarily used for caching, session management, and storing transient or frequently accessed data that doesn't require the relational structure of PostgreSQL. + +#### 5.2.1. Role and Data Stored + +- **Caching**: Caching frequently accessed database query results to reduce load on PostgreSQL and improve response times (e.g., host details, vulnerability information that doesn't change often). +- **Session Management**: If `sirius-ui` or `sirius-api` implement user sessions, Valkey is a suitable store for session data. +- **Task/Job Queuing (Metadata/Status)**: While RabbitMQ handles the primary task queuing, Valkey might be used to store metadata about jobs, their current status, or intermediate results for quick lookups before final persistence in PostgreSQL. +- **Rate Limiting**: Storing counters for API rate limiting or other attempt-based security features. +- **Distributed Locks**: If needed for coordinating actions between multiple instances of a service. +- **NSE Script Management (as detailed in `app-scanner/internal/nse/README.md`)**: + - **Global Repository Manifest (`nse:repo-manifest`)**: Stores a JSON string representing the list of all NSE script repositories (names, Git URLs). This allows dynamic updates to the repositories `app-scanner` should manage. + - **Global Script Manifest (`nse:manifest`)**: Stores a JSON string representing a consolidated manifest of all scripts from all repositories, including their metadata (name, path, description, tags). This is the primary source of truth for available scripts. + - **Individual Script Content (`nse:script:`)**: Stores the actual Lua code of individual NSE scripts. This enables `app-scanner` to fetch and use the latest script versions without requiring image rebuilds or file deployments, as scripts can be updated directly in Valkey. + For example, the content of `vulners.nse` would be stored under the key `nse:script:vulners`. +- **Agent Status/Heartbeats**: `sirius-engine` might use Valkey to keep track of connected `app-agent` instances, their last heartbeat times, and current status for quick lookups. + +The `go-api` SDK provides an interface and implementation for interacting with Valkey, abstracting the direct client library calls for consuming services. + +## 6. Inter-Service Communication + +Sirius Scan employs a variety of communication patterns and technologies to enable its microservices to collaborate effectively. These include asynchronous messaging via RabbitMQ, type-safe APIs with tRPC, traditional RESTful APIs, and high-performance RPC with gRPC. + +### 6.1. RabbitMQ (Asynchronous Messaging) + +RabbitMQ is the backbone for asynchronous communication and task delegation within Sirius Scan. It decouples services, improves resilience (e.g., if a consuming service is temporarily down, messages remain queued), and enables scalable processing of background tasks like vulnerability scans and command executions. + +**Key Roles & Usage**: + +- **Task Queuing**: Long-running or resource-intensive tasks initiated by users (e.g., via `sirius-ui`) are typically offloaded to `sirius-engine` by publishing messages to specific RabbitMQ queues. This allows the user-facing services (`sirius-ui`, `sirius-api`) to remain responsive. +- **Decoupling Services**: Producers of messages don't need to know the exact location or number of consumers. Consumers process messages at their own pace. +- **Load Balancing**: If multiple instances of a consumer service (e.g., `sirius-engine`) are running, RabbitMQ can distribute messages among them. +- **Event Notifications**: Services can publish events (e.g., scan completed, new vulnerability found) to RabbitMQ, allowing other interested services to subscribe and react accordingly. + +**Conceptual Queues and Message Flows** (Payloads are typically JSON): + +1. **Scan Initiation & Management**: + + - **`scan_jobs_queue`** (Producer: `sirius-ui` BFF -> Consumer: `sirius-engine`): + - Purpose: To submit new vulnerability scan requests to the engine. + - Example Payload: + ```json + { + "scan_id": "uuid-scan-123", + "user_id": "user-abc", + "targets": ["192.168.1.0/24", "testserver.com"], + "scan_type": "full_scan_aggressive", // or specific profile name + "nmap_options": { + "scripts": ["vulners", "http-enum"], + "timing_template": "T4", + "service_version": true + }, + "rustscan_options": { + "port_range": "1-65535" + } + } + ``` + - **`scan_control_queue`** (Producer: `sirius-ui` BFF -> Consumer: `sirius-engine`): + - Purpose: To send control commands for ongoing scans (e.g., pause, resume, stop). + - Example Payload: + ```json + { + "scan_id": "uuid-scan-123", + "action": "pause" // "resume", "stop" + } + ``` + - **`scan_status_updates_queue`** (Producer: `sirius-engine` -> Consumer: `sirius-ui` BFF via WebSocket/SSE relay): + - Purpose: To provide real-time progress updates for ongoing scans to the UI. + - Example Payload: + ```json + { + "scan_id": "uuid-scan-123", + "status": "running", // "pending", "paused", "completed", "error" + "progress_percentage": 45, + "current_target": "192.168.1.10", + "message": "Scanning host 10 of 254..." + } + ``` + - **`scan_results_notification_queue`** (Producer: `sirius-engine` -> Consumer: `sirius-ui` BFF and/or `sirius-api`): + - Purpose: To notify that scan results (or significant partial results) are available for a given scan, often indicating data has been persisted to PostgreSQL. + - Example Payload: + ```json + { + "scan_id": "uuid-scan-123", + "status": "completed", + "result_summary_url": "/api/v1/scans/uuid-scan-123/summary", // Optional + "message": "Scan completed. Results available." + } + ``` + (The UI would then typically fetch detailed results via tRPC/API calls to `sirius-api` or its own BFF which queries the DB). + +2. **Terminal Command Execution**: + + - **`terminal_commands_queue`** (Producer: `sirius-ui` BFF -> Consumer: `sirius-engine`): + - Purpose: To send commands entered in the UI terminal to the engine for execution by `app-terminal` (or an agent). + - Example Payload: + ```json + { + "session_id": "uuid-session-xyz", + "user_id": "user-abc", + "command_string": "ls -la /tmp", + "target_context": { + // Optional, for routing to agent etc. + "type": "agent", + "agent_id": "agent-007" + } + } + ``` + - **`terminal_output_queue`** (Producer: `sirius-engine` (from `app-terminal` or agent) -> Consumer: `sirius-ui` BFF via WebSocket/SSE relay): + - Purpose: To stream command output back to the specific UI terminal session. + - Example Payload (could be a series of messages for one command): + ```json + { + "session_id": "uuid-session-xyz", + "data_type": "stdout", // "stderr", "status" + "payload": "total 4\ndrwxr-xr-x 2 root root 4096 Jan 1 10:00 .\n", + "is_final_chunk": false + } + ``` + +3. **Agent Tasking (Conceptual - if not solely gRPC from engine)**: + - While direct gRPC is primary for engine-to-agent, RabbitMQ _could_ be used by the engine to broadcast tasks to groups of agents or for agents to report asynchronous results if direct gRPC streaming isn't suitable for a very long-running agent task. + - **`agent_tasks_queue_group_`** or **`agent_task_queue_`** (Producer: `sirius-engine` -> Consumer: `app-agent` instances) + - **`agent_results_queue`** (Producer: `app-agent` instances -> Consumer: `sirius-engine`) + +**Implementation Details**: + +- **`go-api` SDK**: Go-based services (`sirius-engine`, `sirius-api`, and sub-modules like `app-scanner`, `app-terminal`) utilize the `sirius/queue` package from the `go-api` SDK. This package provides `Send()` and `Listen()` functions, abstracting RabbitMQ connection management, channel handling, queue declaration, and message publishing/consumption logic. +- **Exchanges and Bindings**: While not explicitly detailed in all component READMEs, a typical RabbitMQ setup involves exchanges (e.g., direct, topic, fanout) to route messages from producers to appropriate queues based on routing keys and binding rules. For instance, `scan_jobs_queue` might be bound to a direct exchange where `sirius-ui` publishes messages with a specific routing key. +- **Message Durability & Persistence**: For critical tasks like scan jobs, messages are likely published as persistent, and queues are declared as durable to survive RabbitMQ restarts. Status updates might be non-persistent if losing a few is acceptable. +- **Error Handling & Retries**: Robust consumers implement error handling, potentially using dead-letter exchanges (DLX) and retry mechanisms for messages that fail processing. + +RabbitMQ's role is crucial for the scalability and resilience of Sirius Scan's distributed architecture, enabling efficient handling of potentially numerous and long-duration backend operations. + +### 6.2. tRPC (UI Frontend to Next.js Backend) + +tRPC is utilized within the `sirius-ui` service to facilitate highly efficient and type-safe communication between its React frontend components and its Next.js backend (which acts as a Backend-for-Frontend, or BFF). This approach significantly improves developer experience and reduces runtime errors related to client-server data contracts. + +**Key Roles & Benefits**: + +- **End-to-End Type Safety**: This is the primary advantage. TypeScript types defined on the server (Next.js API routes) are automatically inferred on the client (React components). This means if a server-side API changes its request parameters or response structure, TypeScript will immediately flag errors in the frontend code during development, preventing mismatches that would otherwise lead to runtime failures. +- **Improved Developer Experience**: Developers get autocompletion for API procedures and their inputs/outputs directly in their frontend code. Refactoring server-side procedures (e.g., renaming, changing parameters) can often be done with IDE support that also updates client-side usages. +- **No Code Generation Needed (for client-server calls)**: Unlike GraphQL or OpenAPI-based approaches that often require a code generation step to create client-side SDKs or type definitions, tRPC achieves type safety through TypeScript inference, simplifying the build process. +- **Simplified Data Fetching**: The tRPC client provides hooks (e.g., `useQuery` for data fetching, `useMutation` for data modification) that integrate seamlessly with React, handling loading states, errors, and caching with minimal boilerplate. + +**Implementation in `sirius-ui`**: + +- **Defining Procedures (Backend)**: + + - tRPC procedures are defined in the `sirius-ui/src/server/api/routers/` directory. Each file (e.g., `terminal.ts`, `agent.ts`, `scan.ts`) typically exports a `router` defining a set of related procedures. + - Each procedure specifies its input validation (often using libraries like Zod) and the resolver function that contains the server-side logic. + - Example conceptual procedure in `sirius-ui/src/server/api/routers/scan.ts`: + + ```typescript + import { z } from "zod"; + import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; + // import { rabbitMQService } from '~/server/services/rabbitmq'; // Example service + + export const scanRouter = createTRPCRouter({ + startScan: publicProcedure + .input( + z.object({ + targets: z.array(z.string()), + scanProfile: z.string(), + }) + ) + .mutation(async ({ input, ctx }) => { + // ctx might contain db access, session info, etc. + console.log("Received scan request:", input); + // 1. Validate input further if necessary + // 2. Construct a message for sirius-engine + const scanJobMessage = { + scan_id: `uuid-scan-${Date.now()}`, + user_id: ctx.session?.user?.id, // Example: if auth is used + targets: input.targets, + scan_type: input.scanProfile, + // ... other parameters + }; + // 3. Publish to RabbitMQ (example call) + // await rabbitMQService.publishToQueue('scan_jobs_queue', scanJobMessage); + // 4. Return a confirmation or initial status + return { + message: "Scan job submitted successfully", + scan_id: scanJobMessage.scan_id, + }; + }), + // ... other procedures like getScanStatus, getScanResults etc. + }); + ``` + +- **Root Router**: These individual routers are merged into a single `appRouter` in `sirius-ui/src/server/api/root.ts`. +- **API Handler**: An API route, typically `sirius-ui/src/pages/api/trpc/[trpc].ts`, handles all incoming tRPC requests and routes them to the appropriate procedure in the `appRouter`. + +- **Consuming Procedures (Frontend)**: + + - React components in `sirius-ui/src/components/` or `sirius-ui/src/pages/` use hooks provided by the tRPC client to call backend procedures. + - Example usage in a React component: + + ```tsx + import { api } from "~/utils/api"; // Path to the tRPC client + + function ScanComponent() { + const startScanMutation = api.scan.startScan.useMutation({ + onSuccess: (data) => { + console.log("Scan submitted! ID:", data.scan_id); + // navigate to results page or show notification + }, + onError: (error) => { + console.error("Failed to start scan:", error.message); + }, + }); + + const handleStartScan = () => { + startScanMutation.mutate({ + targets: ["127.0.0.1"], + scanProfile: "quick_scan", + }); + }; + + return ( + + ); + } + ``` + +**Role in Orchestration**: + +The Next.js backend (BFF) part of `sirius-ui`, powered by these tRPC procedures, often acts as an orchestrator: + +- It receives requests from the frontend. +- Performs initial validation and UI-specific logic. +- For tasks requiring asynchronous processing (like starting a scan or executing a terminal command that might take time), it publishes messages to RabbitMQ queues for `sirius-engine` to consume. +- For fetching data that `sirius-api` owns (e.g., detailed host information, historical scan results), the tRPC procedure might make a REST call to `sirius-api` and then transform or relay the data to the frontend. +- It can also directly interact with `sirius-postgres` using Prisma (as suggested by `sirius-ui/prisma/schema.prisma`) for UI-specific data needs that don't fit the `sirius-api` domain, or for caching/aggregating data. + +tRPC provides a clean, type-safe, and efficient communication layer that is internal to the `sirius-ui` service, streamlining its frontend-to-BFF interactions. + +### 6.3. RESTful APIs (`sirius-api`) + +The `sirius-api` service ([`Sirius/sirius-api`](https://github.com/SiriusScan/Sirius/tree/main/sirius-api)) functions as the primary backend API gateway for core data operations and business logic that is not directly handled by the UI's BFF or the specialized `sirius-engine`. It provides a set of RESTful HTTP endpoints for creating, reading, updating, and deleting (CRUD) key data entities like hosts, vulnerabilities, scan results, and potentially user management if centralized here. + +**Key Roles & Characteristics**: + +- **Centralized Data Access Logic**: Provides a consistent API layer over the primary data stores (`sirius-postgres` and `sirius-valkey`). +- **Business Logic Hub**: Implements business rules and data processing related to the core entities (e.g., aggregating vulnerability data for a host, calculating risk scores, managing scan result lifecycles). +- **Technology Stack**: Built using Go and the [Fiber](https://gofiber.io/) web framework, chosen for its high performance and Express.js-like API, making it relatively easy to define routes and handlers. +- **Database Interaction**: Heavily utilizes the `go-api` SDK (specifically packages like `sirius/host`, `sirius/vulnerability`, `sirius/postgres`) for all interactions with `sirius-postgres` (via GORM) and `sirius/store` for `sirius-valkey`. +- **RESTful Principles**: Adheres to REST principles by: + - Using standard HTTP methods: `GET` (retrieve), `POST` (create), `PUT` (update/replace), `DELETE` (remove), `PATCH` (partial update). + - Employing resource-based URLs (e.g., `/api/v1/hosts`, `/api/v1/hosts/{host_id}/vulnerabilities`). + - Using standard HTTP status codes to indicate outcomes (e.g., `200 OK`, `201 Created`, `400 Bad Request`, `404 Not Found`, `500 Internal Server Error`). + - Typically exchanging data in JSON format. +- **Authentication & Authorization**: This service is a logical place for enforcing authentication (e.g., validating JWT tokens passed in `Authorization` headers) and authorization (checking if the authenticated user has permission to perform the requested action on the resource). +- **API Versioning**: Endpoint paths often include a version (e.g., `/api/v1/`) to allow for future API evolution without breaking existing clients. +- **Port**: Runs on port `9001` by default, as configured in `docker-compose.yaml`. + +**Interaction with Other Services**: + +- **`sirius-ui`**: The UI (either its BFF or client-side components, depending on design choices) is a primary consumer of `sirius-api`. It makes HTTP requests to `sirius-api` to fetch data for display (e.g., list of hosts, details of a vulnerability) and to submit changes (e.g., adding a note to a host, updating a vulnerability's status). + - The `sirius-ui`'s BFF (tRPC procedures) might call `sirius-api` endpoints server-side to aggregate data or perform actions before relaying results to the frontend. +- **`sirius-engine`**: While the engine primarily receives tasks via RabbitMQ, it might interact with `sirius-api` for specific needs: + - To fetch detailed configuration or historical data that it doesn't store itself. + - To notify `sirius-api` about the completion of certain tasks if `sirius-api` needs to update its own state or trigger further workflows (though this is often also handled by `sirius-api` consuming RabbitMQ messages produced by the engine). +- **Other Potential Clients**: Any future services or third-party tools needing programmatic access to Sirius Scan's core data would likely interact via `sirius-api`. + +**Example Conceptual Endpoint (in Fiber/Go)**: + +```go +package routes + +import ( + "github.com/gofiber/fiber/v2" + "github.com/SiriusScan/Sirius/go-api/sirius/host" // Assuming go-api is accessible + // ... other imports +) + +// SetupHostRoutes configures routes related to hosts +func SetupHostRoutes(app *fiber.App) { + api := app.Group("/api/v1") // API versioning + hostRoutes := api.Group("/hosts") + + hostRoutes.Get("/", func(c *fiber.Ctx) error { + // Logic to fetch all hosts using go-api's host.GetAllHosts() + // Example: hosts, err := host.GetAllHosts( /* db_instance_from_go_api */ ) + // if err != nil { return c.Status(fiber.StatusInternalServerError).JSON(...) } + // return c.JSON(hosts) + return c.SendString("GET /api/v1/hosts - List all hosts") + }) + + hostRoutes.Get("/:hostId", func(c *fiber.Ctx) error { + hostId := c.Params("hostId") + // Logic to fetch a specific host by ID using go-api's host.GetHost(hostId) + // Example: h, err := host.GetHost(hostId, /* db_instance */) + // if err != nil { /* handle error, e.g., 404 if not found */ } + // return c.JSON(h) + return c.SendString("GET /api/v1/hosts/" + hostId) + }) + + hostRoutes.Post("/", func(c *fiber.Ctx) error { + // var newHostPayload struct { /* ... fields ... */ } + // if err := c.BodyParser(&newHostPayload); err != nil { return c.Status(fiber.StatusBadRequest).JSON(...) } + // Logic to add a new host using go-api's host.AddHost(...) + // return c.Status(fiber.StatusCreated).JSON( /* created_host_info */ ) + return c.SendString("POST /api/v1/hosts - Create new host") + }) + // ... other routes for PUT, DELETE etc. +} + +``` + +This service acts as the canonical source for much of the platform's data, ensuring that access and modification are managed centrally and consistently. + +### 6.4. gRPC (Engine to Agents) + +gRPC (gRPC Remote Procedure Calls) is the chosen framework for direct, high-performance communication between the `sirius-engine` and any deployed `app-agent` instances. This pattern is essential for scenarios requiring low-latency command execution, control, and data exchange with remote agents. + +**Key Characteristics & Roles**: + +- **Roles**: As detailed in section [4.3.2. gRPC Communication with `sirius-engine`](#app-agent-grpc): + - `sirius-engine`: Acts as the gRPC **server**. It defines and implements the gRPC services that agents can call, and also makes calls to agent-exposed services if the model is bidirectional for certain features. Typically, the engine listens on a specific port (e.g., `50051`) for incoming agent connections. + - `app-agent`: Acts as the gRPC **client**. It initiates a connection to the `sirius-engine`'s gRPC server address. +- **Purpose**: To enable `sirius-engine` to: + - Discover and register agents. + - Send commands (e.g., shell commands, requests to initiate local scans by the agent) to specific agents. + - Receive results, status updates, or streams of data back from agents. + - Perform health checks or retrieve agent capabilities (`Ping` method). +- **Technology**: Utilizes Protocol Buffers (`.proto` files) for defining service interfaces and message structures. This ensures strong typing and efficient serialization/deserialization of data over HTTP/2. +- **Communication Style**: Supports both unary RPCs (simple request-response) and streaming RPCs (client-streaming, server-streaming, or bidirectional-streaming). Streaming is particularly useful for long-running commands where `app-agent` can stream output back to `sirius-engine` as it becomes available. + +**Core Interactions (refer to [4.3.2](#app-agent-grpc) for more details on `.proto` examples and `app-agent` implementation)**: + +- **Agent Registration (Conceptual)**: Upon startup, an `app-agent` might register itself with `sirius-engine` by calling a specific gRPC endpoint on the engine, providing its `AGENT_ID` and capabilities. +- **Command Execution (`ExecuteCommand` method)**: `sirius-engine` invokes the `ExecuteCommand` RPC on a target `app-agent`, sending the command string. The `app-agent` executes it and streams back the output and completion status. +- **Health Checks (`Ping` method)**: `sirius-engine` can periodically call a `Ping` method on agents to ensure they are responsive. + +**Advantages in the Sirius Scan Context**: + +- **Performance**: gRPC is generally more performant than REST/JSON for inter-service communication due to its use of HTTP/2 and binary serialization (Protocol Buffers). +- **Streaming**: Native support for streaming is ideal for tasks like returning large outputs from commands or continuous data feeds. +- **Strong Typing & API Contracts**: `.proto` definitions provide a clear, language-agnostic contract between the engine and agents. +- **Network Efficiency**: Well-suited for potentially network-constrained environments where agents might be deployed. + +This gRPC communication channel is vital for extending `sirius-engine`'s operational reach and enabling sophisticated interactions with remote `app-agent` instances, forming a key part of the distributed task execution framework. For a detailed look at the agent-side implementation and an example `.proto` definition, please see section [4.3.2. gRPC Communication with `sirius-engine`](#app-agent-grpc). + +### 6.5. Workflow Sequence Diagrams + +To better illustrate how these communication mechanisms are used in concert, this section provides sequence diagrams for the key architectural workflows outlined in Section B. + +#### 6.5.1. B.1 User Initiates a Vulnerability Scan + +```mermaid +sequenceDiagram + actor User + participant SF as sirius-ui (Frontend) + participant SBFF as sirius-ui (BFF/tRPC) + participant RMQ as RabbitMQ + participant SE as sirius-engine + participant AS as app-scanner + participant SDB as sirius-postgres + participant SAPI as sirius-api + + User->>SF: 1. Configure & Start Scan + SF->>SBFF: 2. tRPC call (scan.startScan) + SBFF->>RMQ: 3. Publish Scan Job (scan_jobs_queue) + activate RMQ + RMQ-->>SE: 4. Consume Scan Job + deactivate RMQ + activate SE + SE->>AS: 5. Dispatch Scan Task + activate AS + Note over AS,SE: Intermediate Status Updates (Optional) + SE->>RMQ: 6a. Publish Scan Status (scan_status_updates_queue) + activate RMQ + RMQ-->>SBFF: 6b. Consume Scan Status + deactivate RMQ + SBFF->>SF: 6c. Relay Status (e.g., WebSocket) + + AS->>SE: 7. Return Scan Results + deactivate AS + SE->>SDB: 8. Persist Results (via go-api) + activate SDB + deactivate SDB + SE->>RMQ: 9. Publish Result Notification (scan_results_notification_queue) + deactivate SE + activate RMQ + RMQ-->>SBFF: 10. Consume Notification + deactivate RMQ + + User->>SF: 11. View Scan Results + SF->>SBFF: 12. tRPC call (scan.getResults) + SBFF->>SAPI: 13. Request Scan Results (REST API) + activate SAPI + SAPI->>SDB: 14. Query Database + activate SDB + SDB-->>SAPI: 15. Return Data + deactivate SDB + SAPI-->>SBFF: 16. Return Results + deactivate SAPI + SBFF-->>SF: 17. Return Results to UI +``` + +#### 6.5.2. B.2 Agent Interaction & Management (e.g., Remote Command Execution) + +```mermaid +sequenceDiagram + actor User + participant SF as sirius-ui (Frontend) + participant SBFF as sirius-ui (BFF/tRPC) + participant RMQ as RabbitMQ + participant SE as sirius-engine (gRPC Server) + participant AGENT as app-agent (gRPC Client) + + User->>SF: 1. Initiate Agent Action (e.g., Execute Command) + SF->>SBFF: 2. tRPC call (e.g., agent.executeRemoteCommand) + SBFF->>RMQ: 3. Publish Agent Command Task (e.g., agent_commands_queue) + activate RMQ + RMQ-->>SE: 4. Consume Agent Command Task + deactivate RMQ + activate SE + SE->>AGENT: 5. gRPC Call (e.g., ExecuteCommand RPC) + activate AGENT + Note over AGENT: Agent executes command on remote host + AGENT-->>SE: 6. Stream/Return Command Output (gRPC) + deactivate AGENT + SE->>RMQ: 7. Publish Agent Result/Status (e.g., agent_results_queue) + deactivate SE + activate RMQ + RMQ-->>SBFF: 8. Consume Agent Result/Status + deactivate RMQ + SBFF->>SF: 9. Relay Result/Status to UI (e.g., WebSocket) + SF->>User: 10. Display Result/Status +``` + +#### 6.5.3. B.3 Terminal Command Execution (via `app-terminal`) + +```mermaid +sequenceDiagram + actor User + participant SF as sirius-ui (Frontend/xterm.js) + participant SBFF as sirius-ui (BFF/tRPC) + participant RMQ as RabbitMQ + participant SE as sirius-engine + participant AT as app-terminal + + User->>SF: 1. Type Command in UI Terminal + SF->>SBFF: 2. tRPC call (terminal.sendCommand) + SBFF->>RMQ: 3. Publish Terminal Command (terminal_commands_queue) + activate RMQ + RMQ-->>SE: 4. Consume Terminal Command + deactivate RMQ + activate SE + SE->>AT: 5. Dispatch Command to app-terminal + activate AT + Note over AT: app-terminal executes command (e.g., PowerShell) + AT->>SE: 6. Return Command Output Stream/Chunks + deactivate AT + SE->>RMQ: 7. Publish Terminal Output (terminal_output_queue) + deactivate SE + activate RMQ + RMQ-->>SBFF: 8. Consume Terminal Output + deactivate RMQ + SBFF->>SF: 9. Relay Output to UI Terminal (e.g., WebSocket) + SF->>User: 10. Display Command Output +``` + +## 7. Development & Deployment + +The development and deployment strategy for Sirius Scan centers around containerization with Docker and Docker Compose, enabling consistent environments and streamlined workflows. Hot reloading is utilized for Go and Next.js applications to enhance developer productivity. + +### 7.1. Dockerized Environment (`docker-compose.yaml`) + +The primary mechanism for orchestrating the various microservices during development (and potentially for simple deployments) is the `Sirius/docker-compose.yaml` file. This file defines: + +- **Services**: Each core component of Sirius Scan runs as a distinct service: + - `sirius-ui`: The Next.js frontend and BFF. + - `sirius-api`: The Go-based backend API (Fiber framework). + - `sirius-engine`: The Go-based core processing engine. + - `sirius-postgres`: PostgreSQL database instance. + - `sirius-valkey`: Valkey key-value store instance. + - `sirius-rabbitmq`: RabbitMQ message broker instance. +- **Build Contexts & Dockerfiles**: For services like `sirius-ui`, `sirius-api`, and `sirius-engine`, the `build` instruction points to their respective directories containing their `Dockerfile`. +- **Image Usage**: For infrastructure services (`sirius-postgres`, `sirius-valkey`, `sirius-rabbitmq`), pre-built official Docker images are used. +- **Service Dependencies (`depends_on`)**: Explicitly defines startup order, ensuring that infrastructure services like databases and message queues are likely to be available before application services attempt to connect to them. However, `depends_on` does not guarantee that the dependent service is _fully initialized_ and ready, so applications should implement connection retry logic (as `go-api` does). +- **Volume Mounts for Local Development**: Crucial for an efficient development loop. For example: + - `sirius-ui`: Mounts `./sirius-ui:/app` allowing local code changes to be reflected immediately by the Next.js development server. + - `sirius-api`: Mounts `./sirius-api:/app` for Go code, used by `air` for hot reloading. + - `sirius-engine`: Mounts `./sirius-engine:/engine`. It also has commented-out volume mounts for `go-api` and sub-modules like `app-scanner`, `app-terminal`, and `app-agent` (e.g., `- ../minor-projects/app-scanner:/app-scanner`). Uncommenting these allows developers to work on these shared libraries or sub-modules locally and have their changes reflected inside the `sirius-engine` container, overriding the versions cloned by the engine's Dockerfile. +- **Port Mappings (`ports`)**: Exposes service ports to the host machine (e.g., `sirius-ui` on `3000`, `sirius-api` on `9001`, `sirius-engine` on `5174` and `50051` for gRPC, PostgreSQL on `54321`, RabbitMQ on `5672` and `15672` for management UI). +- **Environment Variables (`environment`)**: A primary way to configure services. Connection strings, API keys, operational parameters (e.g., `GO_ENV=development`) are set here. For `sirius-ui`, build-time arguments (`args` under `build`) are also used for `NEXT_PUBLIC_` variables. +- **Networking**: By default, Docker Compose sets up a single default bridge network. Services can reach each other using their defined service names as hostnames (e.g., `sirius-api` can connect to `sirius-postgres` using the hostname `sirius-postgres`). + +To run the entire stack: `docker compose up --build -d`. +To view logs: `docker compose logs -f `. +To stop: `docker compose down`. + +### 7.2. Local Development & Hot Reloading + +Rapid iteration is supported by hot reloading mechanisms for the primary application services: + +- **`sirius-ui` (Next.js)**: + - The Next.js development server (typically started by `npm run dev` within the container, which is the default CMD in its `Dockerfile`) provides fast refresh and hot module replacement (HMR) out of the box. Changes to React components or Next.js pages are reflected in the browser almost instantly without a full page reload where possible. +- **`sirius-api` (Go/Fiber)**: + - Uses [`air`](https://github.com/air-verse/air) for live reloading. The `sirius-api/Dockerfile` installs `air`, and its `CMD` is typically `["air", "-c", ".air.toml"]`. + - The `sirius-api/.air.toml` configuration file tells `air` which files/directories to watch (e.g., `*.go`), what build commands to run (`go build -o ./tmp/main .`), and how to run the compiled binary (`./tmp/main`). When Go source files change, `air` automatically recompiles and restarts the `sirius-api` server. +- **`sirius-engine` (Go) & Go Sub-Modules (`app-scanner`, `app-terminal`)**: + - The main `sirius-engine` Go application and its Go-based sub-modules (which run within the `sirius-engine` container) can also benefit from `air` if configured. + - The `sirius-engine/Dockerfile` installs `air` (both globally and within the `/app-scanner` context as an example). + - The `sirius-engine/start.sh` script, which is the `ENTRYPOINT` for the `sirius-engine` container, plays a crucial role. This script is responsible for: + - Starting the main `sirius-engine` Go application. It _could_ use `air` (e.g., `air -c .air.toml` pointing to an `.air.toml` in the `/engine` directory) if desired for hot reloading of the core engine code. + - Managing the Go-based sub-applications cloned into the image (like `app-scanner`, `app-terminal`). If these sub-apps have their own `.air.toml` files (e.g., `app-scanner/.air.toml`), the `start.sh` script might navigate to their directories and launch them using their respective `air` configurations. + - When local source code for a sub-module (e.g., `../minor-projects/app-scanner`) is volume-mounted into the `sirius-engine` container (e.g., to `/app-scanner`), changes to those local files will be visible inside the container. If `start.sh` runs that sub-module via `air`, hot reloading will occur for that specific sub-module. + +### 7.3. Build Processes (Dockerfiles & Scripts) + +Each application service (`sirius-ui`, `sirius-api`, `sirius-engine`) has its own `Dockerfile` defining its build process: + +- **`sirius-ui/Dockerfile`**: + - Typically uses a Node.js base image. + - Copies `package.json` and `package-lock.json` (or `yarn.lock`), installs dependencies (`npm install`). + - Copies the rest of the application source code. + - Builds the Next.js application for production (`npm run build`) if the `NODE_ENV` is `production`, though for development it often just installs deps and relies on `npm run dev` as the CMD. + - Exposes the port (e.g., `3000`). + - Sets the `CMD` (e.g., `npm run dev` or `npm start`). +- **`sirius-api/Dockerfile`**: + - Uses a Go base image. + - Sets the working directory (e.g., `/app`). + - Copies `go.mod` and `go.sum`, downloads Go module dependencies (`go mod download`). + - Installs `air` for live reloading. + - Copies the rest of the application source code. + - The `.air.toml` usually defines the build command (`go build -o ./tmp/main .`). + - Exposes the application port (e.g., `9001`). + - Sets the `CMD` to run `air` (e.g., `["air", "-c", ".air.toml"]`). +- **`sirius-engine/Dockerfile`**: + - More complex, as it sets up the environment for the core engine and its bundled sub-applications/tools. + - Uses a Go base image. + - Installs system dependencies: `git`, `curl`, build tools, and crucially, scanning tools like `nmap`, `rustscan` (built from source), and `powershell`. + - Sets up directories (e.g., `/opt/sirius/nse` for Nmap scripts). + - Clones repositories for sub-applications directly into the image: `app-scanner`, `app-terminal`, `go-api`. + - Installs `air` (potentially in multiple contexts if sub-apps use it independently). + - Copies its own source code (main engine code) and the `start.sh` script. + - Makes `start.sh` executable and sets it as the `ENTRYPOINT`. +- **`sirius-engine/start.sh` (Entrypoint Script)**: + - This script is pivotal for the `sirius-engine`'s operation. + - It is responsible for the final setup and launching of processes within the container after it starts. + - Its tasks likely include: + - Initializing or configuring any services or environment aspects needed at runtime. + - Starting the main `sirius-engine` Go application (potentially using `air` if an `.air.toml` for the engine core is present). + - Navigating into the directories of cloned Go sub-applications (e.g., `/app-scanner`, `/app-terminal`) and launching them. This might involve running `go build` for them first (if not already built by `air`) and then executing their binaries, or running them via `air` if they have their own `.air.toml` configurations for hot reloading during development (when volume mounts are active). + - Managing the lifecycle or backgrounding of these multiple processes if they are meant to run concurrently within the engine container. + +Understanding these build and runtime mechanisms is key to developing for and deploying Sirius Scan. + +## 8. Conclusion + +This document has outlined the comprehensive architecture of the Sirius Scan platform, detailing its distributed microservices, data management strategies, inter-service communication patterns, and development workflows. The architecture is designed to be modular, scalable, and resilient, providing a robust foundation for a versatile vulnerability scanning and management system. + +### 8.1. Summary of Architecture + +Sirius Scan operates as a cohesive system of containerized microservices orchestrated by Docker Compose, promoting consistency across development and deployment environments. The key components and their interactions are summarized below: + +- **User Interface & BFF (`sirius-ui`)**: A Next.js application serves as the primary user interaction point. It includes a React frontend for rich user experience and a Next.js backend (BFF) that handles UI-specific logic. Communication between the frontend and its BFF is streamlined using type-safe tRPC calls. + +- **Backend API (`sirius-api`)**: A Go-based service built with the Fiber framework, exposing RESTful APIs. It acts as the central gateway for CRUD operations on core data entities (hosts, vulnerabilities, etc.) and implements key business logic. It leverages the `go-api` SDK for database and cache interactions. + +- **Core Processing Engine (`sirius-engine`)**: Another Go application, this is the workhorse of the system. It orchestrates scanning tasks, manages agents, and integrates several specialized sub-applications: + + - **`app-scanner`**: For performing network and vulnerability scans using tools like Nmap and RustScan, with sophisticated NSE script management. + - **`app-terminal`**: Provides PowerShell terminal access within the engine's environment. + The engine receives tasks primarily via RabbitMQ and uses the `go-api` SDK for data operations. + +- **Shared Backend SDK (`go-api`)**: A critical Go library providing standardized modules for database access (PostgreSQL with GORM), message queuing (RabbitMQ), key-value store interaction (Valkey), and core data models. It is consumed by `sirius-api`, `sirius-engine`, and its sub-modules, ensuring consistency and reusability. + +- **Remote Agents (`app-agent`)**: Go applications designed to run on remote hosts, extending the engine's reach for command execution and potentially distributed scanning tasks. These communicate with `sirius-engine` via gRPC. + +- **Data Persistence & Storage**: + + - **`sirius-postgres` (PostgreSQL)**: The primary relational database for storing structured data like host information, scan results, and vulnerabilities. + - **`sirius-valkey` (Valkey)**: An in-memory key-value store used for caching, session management, and dynamic configurations like NSE script manifests. + +- **Inter-Service Communication**: A mix of patterns is employed: + - **RabbitMQ**: For asynchronous task queuing and event-driven communication, decoupling services like `sirius-ui` (BFF) from `sirius-engine`. + - **tRPC**: Ensures type-safe API calls within `sirius-ui` (frontend to BFF). + - **RESTful APIs**: Exposed by `sirius-api` for general backend data and business logic access. + - **gRPC**: Facilitates efficient, low-latency communication between `sirius-engine` and `app-agent` instances. + +This layered and decoupled architecture allows for independent development, scaling, and maintenance of components, while the well-defined communication interfaces ensure effective collaboration between services. + +### 8.2. Future Directions + +Sirius Scan is envisioned as an evolving platform. Potential future enhancements and architectural considerations include: + +- **Enhanced Scalability & Orchestration**: Moving beyond Docker Compose for production deployments to more robust orchestration platforms like Kubernetes for better scaling, self-healing, and resource management. +- **Advanced Agent Capabilities**: Expanding `app-agent` functionalities to include more sophisticated local scanning capabilities, evidence collection, and potentially persistent monitoring features. +- **Expanded Scan Tool Integration**: Incorporating a wider variety of security assessment tools and scanners into `sirius-engine` or via agents. +- **Improved Security Posture**: Further hardening all services, implementing end-to-end encryption for all sensitive data in transit and at rest, and adopting more granular authentication and authorization mechanisms (e.g., OAuth2/OIDC). +- **Workflow Automation & Customization**: Allowing users to define more complex, chained scanning and assessment workflows. +- **Data Analytics & Reporting**: Integrating more advanced data analytics features and customizable reporting capabilities to provide deeper insights into security posture. +- **Configuration Management**: Implementing a centralized configuration management system for all services, potentially integrated with secrets management solutions. +- **Service Mesh**: For larger deployments, exploring a service mesh (e.g., Istio, Linkerd) to manage inter-service communication, observability, and security policies more effectively. + +By pursuing these directions, Sirius Scan aims to continuously improve its utility, performance, and security, serving as a valuable tool for the cybersecurity community. diff --git a/documentation/dev/architecture/README.auth-surface-matrix.md b/documentation/dev/architecture/README.auth-surface-matrix.md new file mode 100644 index 0000000..8863eb6 --- /dev/null +++ b/documentation/dev/architecture/README.auth-surface-matrix.md @@ -0,0 +1,130 @@ +--- +title: "Auth Surface Matrix" +description: "Authoritative authentication and operation policy matrix for all Sirius API surfaces." +template: "TEMPLATE.reference" +llm_context: "high" +categories: ["architecture", "security", "operations"] +tags: ["auth", "apikey", "trpc", "valkey", "rabbitmq", "agent"] +related_docs: + - "README.architecture.md" + - "README.development.md" + - "README.container-testing.md" + - "README.tasks.md" +--- + +# Auth Surface Matrix + +This checklist is the canonical auth policy map for current Sirius architecture. + +## Current Auth Model + +- UI user auth: NextAuth session -> `protectedProcedure` in tRPC. +- Service auth: `X-API-Key` -> Go API middleware validation. +- Agent auth: gRPC token model for agent channel identity. +- Current platform model: single UI admin (no multi-user tenant isolation yet). + +## Architecture Decision: Startup and Secret Strategy + +### Decision Summary + +- Startup onboarding is installer-first: generate/merge runtime config before compose startup. +- The infrastructure/root API key is validated statelessly from environment configuration. +- Valkey-backed key validation remains for dynamic, user-generated API keys only. +- Runtime auth and seed flows fail fast when required secrets are missing in production. + +### Rationale + +- Removes bootstrap drift between persistent key-value state and deployment configuration. +- Reduces first-run friction by automating secret generation and synchronization. +- Improves operational reliability for key rotation and service restarts. +- Aligns local and automated deployments with a single deterministic configuration model. + +### Operational Implications + +- Health endpoints remain public by explicit policy. +- Non-health API endpoints require `X-API-Key` and validate against either: + - environment root key (infrastructure path), or + - Valkey metadata (dynamic key path). +- Migration guidance is required for users moving from manual `.env` setup to installer flow. + +## Policy Checklist + +- [x] All sensitive tRPC procedures require `protectedProcedure`. +- [x] Go API middleware enforces API key for non-health routes. +- [x] UI -> Go API calls use shared authenticated client (`apiClient` / `apiFetch`). +- [x] Direct tRPC backends (Valkey/RabbitMQ) remain session-gated. +- [ ] Agent identity to HTTP/API actions is fully cryptographically bound. +- [x] Production key lifecycle is deterministic for root key validation and user-key lifecycle handling. + +## tRPC Procedure Matrix (By Router) + +Each row captures backend target and operation class. + +| Router | Procedures | Backend Target | Operation Class | Required Auth | +|---|---|---|---|---| +| `apikeys` | `createKey`, `listKeys`, `revokeKey` | Go API `/api/v1/keys*` | Read/Write/Delete | Session + API key | +| `host` | `createHost`, `getHostList`, `updateHost`, `getHost`, `getHostStatistics`, `getEnvironmentSummary`, `getAllHosts`, `getSourceCoverage`, `getHostWithSources`, `getHostSoftwareInventory`, `getHostSoftwareStats`, `getHostSystemFingerprint`, `getEnhancedHostData`, `getEnvironmentSoftwareStats`, `getHostTemplateResults`, `getEnvironmentSoftwareInventory`, `getHostHistory`, `getVulnerabilityHistory` | Go API `/host*` | Read/Write | Session + API key | +| `vulnerability` | `addVulnerabilityToHost`, `getVulnerability`, `getAffectedHosts`, `getSoftwareDescription`, `getAllVulnerabilities` | Go API + external wiki lookup | Read/Write | Session (+ API key for Go API calls) | +| `scanner` | `getLatestScan`, `startScan`, `getScanStatus`, `cancelScan`, `forceStopScan`, `resetScanState` | mixed (local + Go API `/api/v1/scans*`) | Read/Write | Session (+ API key for Go API calls) | +| `templates` | `getTemplates`, `getTemplate`, `createTemplate`, `updateTemplate`, `deleteTemplate` | Go API `/templates*` via `apiFetch` | Read/Write/Delete | Session + API key | +| `scripts` | `getScripts`, `getScript`, `createScript`, `updateScript`, `deleteScript` | Go API `/scripts*` via `apiFetch` | Read/Write/Delete | Session + API key | +| `agentTemplates` | `getTemplates`, `getTemplate`, `uploadTemplate`, `validateTemplate`, `updateTemplate`, `deleteTemplate`, `testTemplate`, `deployTemplate`, `getAnalytics`, `getTemplateResults` | Go API `/api/agent-templates*` | Read/Write/Delete/Exec | Session + API key | +| `repositories` | `list`, `add`, `update`, `delete`, `sync`, `getSyncStatus` | Go API `/api/agent-templates/repositories*` | Read/Write/Delete | Session + API key | +| `events` | `getEvents`, `getEventStats`, `getRecentEvents`, `getEventsBySeverity` | Go API `/api/v1/events*` | Read | Session + API key | +| `statistics` | `createSnapshot`, `getVulnerabilityTrends`, `listSnapshots`, `getMostVulnerableHosts` | Go API `/api/v1/statistics*` | Read/Write | Session + API key | +| `logs` | `list`, `stats` | Go API `/api/v1/logs*` via `apiFetch` | Read | Session + internal API key (server-side only) | +| `store` | `initializeNseScripts`, `getValue`, `setValue`, `getNseScripts`, `getNseScript`, `updateNseScript`, `createNseScript`, `deleteNseScript`, `getNseRepositories`, `addNseRepository`, `removeNseRepository`, `initializeNseRepositories` | Direct Valkey | Read/Write/Delete | Session | +| `queue` | `sendMsg` | Direct RabbitMQ | Write/Exec | Session | +| `agent` | `listAgentsWithHosts`, `getAgentDetails`, `getTemplates`, `discoverTemplates`, `getTemplatesFromValKey`, `discoverTemplatesFromValKey`, `getTemplateContent`, `getScriptsFromValKey`, `discoverScriptsFromValKey`, `getScriptContent` | RabbitMQ + Go API + Valkey | Read/Exec | Session | +| `agentScan` | `dispatchAgentScan`, `getAgentScanStatus` | RabbitMQ + Valkey | Write/Read | Session | +| `terminal` | `executeCommand`, `getHistory`, `addHistoryEntry`, `deleteHistoryEntry`, `clearHistory` | RabbitMQ + Valkey | Exec/Read/Write/Delete | Session | +| `user` | `updateProfile`, `changePassword`, `getProfile` | Prisma DB | Read/Write | Session | +| `example` | `hello`, `getAll`, `getSecretMessage` | local/prisma demo | mixed | mixed (demo only) | + +## Go API Endpoint Matrix (By Route Group) + +All routes are under API key middleware except explicit health bypass. + +| Group | Paths | Operation Class | Required Auth | +|---|---|---|---| +| health | `/health` | Read | Public (intentional) | +| system | `/api/v1/system/health`, `/api/v1/system/logs`, `/api/v1/system/resources` | Read | API key | +| admin | `/api/v1/admin/command` | Exec | API key | +| logs | `/api/v1/logs`, `/api/v1/logs/stats`, `/api/v1/logs/clear`, `/api/v1/logs/:logId` | Read/Write/Delete | Internal service API key (`SIRIUS_API_KEY_FILE` preferred, `SIRIUS_API_KEY` fallback). Browser UI uses tRPC `logs` router (session), not direct calls. | +| host | `/host/*`, `/vulnerability/:id/sources` | Read/Write/Delete | API key | +| vulnerability | `/vulnerability/:id`, `/vulnerability/`, `/vulnerability/delete` | Read/Write/Delete | API key | +| template | `/templates/*` | Read/Write/Delete | API key | +| agent template | `/api/agent-templates/*` | Read/Write/Delete/Exec | API key | +| repository | `/api/agent-templates/repositories/*` | Read/Write/Delete | API key | +| events | `/api/v1/events/*` | Read | API key | +| statistics | `/api/v1/statistics/*` | Read/Write | API key | +| scan control | `/api/v1/scans/*` | Read/Write | API key | +| api key mgmt | `/api/v1/keys/*` | Read/Write/Delete | API key | +| app passthrough | `/app/:appName` | Write/Exec | API key | + +## Agent and NHI Boundary Matrix + +| Boundary | Identity Mechanism | Current State | Required Control | +|---|---|---|---| +| Agent -> Engine (gRPC) | Agent token in stream messages | implemented | keep enforced | +| Engine/Agent -> Go API (HTTP) | Internal service key (file or env) | normalized via shared loader / logging client patch | keep `X-API-Key` on all internal HTTP clients | +| UI admin -> Agent dispatch | Session-gated tRPC + queue payloads | implemented but trust of client-supplied agent IDs needs hardening | validate agent existence/state on dispatch | +| Agent metadata ingestion | host source metadata | accepted from clients | validate schema and origin coupling | + +## IDOR Opportunity Review (Current Stage) + +Given single-admin model, current focus is authn + object selector hardening: + +- selectors to validate consistently: `id`, `ip`, `vulnId`, `scanId`, `templateId`, `agentId`. +- malformed selectors should fail fast with `400`. +- non-existent resources should return `404`. +- unauthorized/unauthenticated should return `401` (and `403` when explicit deny model is later introduced). + +## Verification Hooks + +- Security harness must cover: + - Go API authn enforcement for all route families. + - tRPC session enforcement for all non-demo routers. + - direct Valkey/RabbitMQ procedure access controls. + - agent misuse cases (invalid/stale/mismatched agent IDs). + diff --git a/documentation/dev/architecture/README.cicd.md b/documentation/dev/architecture/README.cicd.md new file mode 100644 index 0000000..a114716 --- /dev/null +++ b/documentation/dev/architecture/README.cicd.md @@ -0,0 +1,367 @@ +--- +title: "Sirius CI/CD Pipeline" +description: "Comprehensive guide to the Sirius Continuous Integration and Continuous Deployment pipeline, including workflows, testing strategies, and deployment processes." +template: "TEMPLATE.architecture" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Development Team" +tags: ["cicd", "pipeline", "github-actions", "docker", "testing", "deployment"] +categories: ["architecture", "operations"] +difficulty: "intermediate" +prerequisites: ["docker", "github-actions", "git"] +related_docs: + - "README.docker-architecture.md" + - "README.developer-guide.md" + - "README.container-testing.md" +dependencies: + - ".github/workflows/ci.yml" + - "testing/container-testing/" + - "scripts/switch-env.sh" +llm_context: "high" +search_keywords: + [ + "cicd", + "pipeline", + "github actions", + "docker testing", + "continuous integration", + "deployment", + "workflow" + ] +--- + +# Sirius CI/CD Pipeline + +## Overview + +The Sirius CI/CD pipeline provides automated testing, building, and deployment of the multi-service Sirius application. The pipeline is designed to be efficient, reliable, and developer-friendly while maintaining high quality standards. + +## Pipeline Architecture + +### Workflow Structure + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ Quick Checks │ │ Full Testing │ │ Deployment │ +│ (Pre-commit) │───▶│ (CI/CD) │───▶│ (Production) │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ +``` + +### Trigger Strategy + +| Event | Quick Checks | Full Testing | Deployment | +|-------|-------------|--------------|------------| +| **Feature Branch Push** | ✅ Yes | ❌ No | ❌ No | +| **Pull Request** | ✅ Yes | ✅ Yes | ❌ No | +| **Main Branch Push** | ✅ Yes | ✅ Yes | ✅ Yes | +| **Hotfix Push** | ✅ Yes | ✅ Yes | ✅ Yes | + +## Quick Checks (Pre-commit) + +**Purpose**: Fast validation to catch obvious issues before commit + +**Duration**: ~30 seconds + +**What's Tested**: +- Docker Compose configuration validation +- Documentation linting +- Basic syntax checks +- Code formatting + +**Commands**: +```bash +# Pre-commit validation +make build-all # Validate all Docker Compose configs +make lint-docs-quick # Quick documentation checks +``` + +## Full Testing (CI/CD) + +**Purpose**: Comprehensive testing of all changes + +**Duration**: ~5-10 minutes + +**What's Tested**: +- Docker container builds (all services) +- Service health checks +- Integration testing +- Cross-service communication +- Production build validation + +**Commands**: +```bash +# Full CI testing +make test-all # Complete test suite +make validate-all # Full validation with docs +``` + +## Environment Strategy + +### Development Testing + +**Trigger**: Feature branch pushes, local development + +**Configuration**: Uses development Docker Compose setup + +**Testing Level**: Quick validation only + +**Purpose**: Catch basic issues early + +### Integration Testing + +**Trigger**: Pull requests, main branch pushes + +**Configuration**: Uses production Docker Compose setup + +**Testing Level**: Full test suite + +**Purpose**: Validate complete integration before merge + +### Production Deployment + +**Trigger**: Main branch pushes, hotfixes + +**Configuration**: Production-optimized builds + +**Testing Level**: Full validation + deployment + +**Purpose**: Deploy tested, validated code + +## Service Detection and Building + +### Change Detection + +The CI pipeline intelligently detects which services have changed: + +```yaml +# Example change detection +if changes in sirius-ui/ → build sirius-ui +if changes in sirius-api/ → build sirius-api +if changes in sirius-engine/ → build sirius-engine +if changes in docker-compose*.yaml → build all services +``` + +### Build Strategy + +**Incremental Building**: Only build services that have changed + +**Parallel Building**: Build multiple services simultaneously + +**Caching**: Use Docker layer caching for faster builds + +**Multi-Platform**: Build for both AMD64 and ARM64 architectures + +## Testing Infrastructure + +### Test Categories + +1. **Build Tests** + - Individual container builds + - Multi-stage build validation + - Architecture compatibility + +2. **Health Tests** + - Service startup validation + - Health endpoint checks + - Resource availability + +3. **Integration Tests** + - Cross-service communication + - Database connectivity + - Message queue functionality + +### Test Environment + +**Configuration**: Production-like environment + +**Database**: PostgreSQL with test data + +**Cache**: Valkey (Redis-compatible) + +**Message Queue**: RabbitMQ + +**Network**: Isolated Docker network + +## Docker Image Strategy + +### Image Tagging + +| Environment | Tag Pattern | Purpose | +|-------------|-------------|---------| +| **Development** | `sirius-*:dev` | Development builds | +| **Production** | `sirius-*:prod` | Production builds | +| **Base** | `sirius-*:latest` | Default builds | +| **CI** | `sirius-*:ci-{sha}` | CI-specific builds | + +### Registry Management + +**Primary Registry**: GitHub Container Registry (ghcr.io) + +**Namespace**: siriusscan + +**Image Naming**: `ghcr.io/siriusscan/sirius-{service}:{tag}` + +## Workflow Jobs + +### 1. Change Detection + +**Purpose**: Determine which services need building + +**Inputs**: Git diff, file changes + +**Outputs**: Service build flags + +**Duration**: ~30 seconds + +### 2. Build and Push + +**Purpose**: Build and push Docker images + +**Inputs**: Change detection results + +**Outputs**: Built and tagged images + +**Duration**: ~3-5 minutes + +### 3. Integration Testing + +**Purpose**: Validate complete system integration + +**Inputs**: Built images + +**Outputs**: Test results + +**Duration**: ~2-3 minutes + +### 4. Deployment (Production) + +**Purpose**: Deploy to production environment + +**Inputs**: Tested images + +**Outputs**: Deployed services + +**Duration**: ~1-2 minutes + +## Configuration Management + +### Environment Variables + +**Development**: Local `.env` files + +**CI**: Generated `.env.ci.*` files + +**Production**: Secure environment variables + +### Docker Compose Files + +**Base**: `docker-compose.yaml` - Core configuration + +**Development**: `docker-compose.dev.yaml` - Development overrides + +**Production**: `docker-compose.prod.yaml` - Production overrides + +**CI**: `docker-compose.ci.yml` - Generated CI configuration + +## Monitoring and Observability + +### Build Monitoring + +- Build success/failure rates +- Build duration trends +- Resource utilization + +### Test Monitoring + +- Test pass/fail rates +- Test duration trends +- Flaky test detection + +### Deployment Monitoring + +- Deployment success rates +- Service health post-deployment +- Performance metrics + +## Troubleshooting + +### Common Issues + +| Issue | Symptoms | Solution | +|-------|----------|----------| +| **Build Failures** | Docker build errors | Check Dockerfile syntax, dependencies | +| **Test Failures** | Integration test errors | Check service logs, network connectivity | +| **Deployment Failures** | Service startup errors | Check environment variables, resource limits | +| **Cache Issues** | Stale builds | Clear Docker cache, rebuild with --no-cache | + +### Debugging Commands + +```bash +# Check CI logs +gh run list +gh run view {run-id} + +# Local testing +make test-all +make logs + +# Docker debugging +docker compose ps +docker compose logs {service} +``` + +## Best Practices + +### For Developers + +1. **Use feature branches** for all development +2. **Test locally** before pushing +3. **Keep commits focused** and atomic +4. **Write descriptive commit messages** +5. **Update documentation** when changing CI + +### For CI/CD + +1. **Keep builds fast** with proper caching +2. **Use conditional execution** based on changes +3. **Monitor build metrics** regularly +4. **Update dependencies** regularly +5. **Test CI changes** in feature branches + +## Migration from Legacy CI + +### What Changed + +- **Simplified structure**: Removed complex submodule handling +- **Modern testing**: Integrated with current testing system +- **Better caching**: Improved Docker layer caching +- **Cleaner workflows**: Streamlined job structure + +### Migration Steps + +1. **Update workflows** to use new Docker Compose structure +2. **Integrate testing system** with CI pipeline +3. **Update image tagging** strategy +4. **Modernize deployment** process +5. **Update documentation** to reflect changes + +## Future Enhancements + +### Planned Improvements + +- **Parallel testing** across multiple environments +- **Advanced caching** strategies +- **Performance testing** integration +- **Security scanning** automation +- **Rollback capabilities** for failed deployments + +### Monitoring Enhancements + +- **Real-time notifications** for build failures +- **Performance dashboards** for CI metrics +- **Automated rollback** triggers +- **Cost optimization** recommendations + +--- + +_This CI/CD documentation follows the Sirius Documentation Standard. For questions about the pipeline, see [README.developer-guide.md](README.developer-guide.md)._ diff --git a/documentation/dev/architecture/README.docker-architecture.md b/documentation/dev/architecture/README.docker-architecture.md new file mode 100644 index 0000000..8597f05 --- /dev/null +++ b/documentation/dev/architecture/README.docker-architecture.md @@ -0,0 +1,895 @@ +--- +title: "Docker Architecture" +description: "Comprehensive guide to Sirius Docker setup, including all Docker Compose files, Dockerfiles, service architecture, and operational considerations" +template: "TEMPLATE.architecture" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Development Team" +tags: ["docker", "architecture", "containers", "orchestration", "deployment"] +categories: ["architecture", "infrastructure", "deployment"] +difficulty: "intermediate" +prerequisites: ["docker", "docker-compose", "containerization"] +related_docs: + - "README.container-testing.md" + - "README.development.md" +dependencies: + - "docker-compose.yaml" + - "docker-compose.dev.yaml" + - "docker-compose.prod.yaml" +llm_context: "high" +search_keywords: + [ + "docker", + "compose", + "containers", + "services", + "architecture", + "deployment", + "production", + "development", + ] +--- + +# Docker Architecture + +## Purpose + +This document provides a comprehensive guide to the Sirius Docker architecture, including all Docker Compose configurations, service definitions, build processes, and operational considerations. It serves as the definitive reference for understanding, deploying, and maintaining the containerized Sirius application. + +## When to Use + +- **Before deploying Sirius** - Understand the complete container architecture +- **When troubleshooting Docker issues** - Reference service configurations and dependencies +- **During development setup** - Choose appropriate Docker Compose configuration +- **For production deployment** - Understand production-specific optimizations +- **When adding new services** - Follow established patterns and conventions +- **For capacity planning** - Understand resource requirements and scaling considerations + +## How to Use + +1. **Start with the overview** - Understand the overall architecture and service relationships +2. **Review Docker Compose files** - Understand the different environment configurations +3. **Examine Dockerfiles** - Understand build processes and multi-stage builds +4. **Check service dependencies** - Understand startup order and health checks +5. **Review operational considerations** - Understand monitoring, logging, and maintenance +6. **Reference troubleshooting** - Use the troubleshooting section for common issues + +## What This Architecture Is + +### Core Philosophy + +The Sirius Docker architecture follows a **microservices-oriented containerization strategy** where each major component runs in its own container, with clear separation of concerns and well-defined interfaces. The architecture prioritizes: + +- **Service isolation** - Each component runs independently with defined boundaries +- **Environment consistency** - Same container images work across development, staging, and production +- **Scalability** - Services can be scaled independently based on demand +- **Maintainability** - Clear separation makes debugging and updates easier +- **Resource efficiency** - Multi-stage builds and optimized base images minimize resource usage + +### Architecture Overview + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Sirius Docker Stack │ +├─────────────────────────────────────────────────────────────────┤ +│ Frontend Layer │ +│ ┌─────────────────┐ ┌─────────────────┐ │ +│ │ sirius-ui │ │ sirius-api │ │ +│ │ (Next.js) │◄──►│ (Go REST) │ │ +│ │ Port: 3000 │ │ Port: 9001 │ │ +│ └─────────────────┘ └─────────────────┘ │ +│ │ │ │ +│ │ │ │ +│ Processing Layer │ │ +│ ┌─────────────────┐ │ │ +│ │ sirius-engine │◄─────────────┘ │ +│ │ (Multi-service) │ │ +│ │ Ports: 5174, │ │ +│ │ 50051 │ │ +│ └─────────────────┘ │ +│ │ │ +│ Data Layer │ +│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ +│ │ sirius-postgres │ │ sirius-valkey │ │sirius-rabbitmq │ │ +│ │ (PostgreSQL) │ │ (Redis Cache) │ │ (Message Queue) │ │ +│ │ Port: 5432 │ │ Port: 6379 │ │ Ports: 5672, │ │ +│ └─────────────────┘ └─────────────────┘ │ 15672 │ │ +│ └─────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## Service Architecture + +### Frontend Services + +#### sirius-ui (Next.js Frontend) + +- **Purpose**: User interface and web application +- **Technology**: Next.js 14 with React, TypeScript, Tailwind CSS +- **Ports**: 3000 (HTTP), 3001 (Development) +- **Dependencies**: sirius-postgres (production), SQLite (development) +- **Health Check**: `http://localhost:3000/api/health` +- **Resource Limits**: 1GB RAM, 0.5 CPU +- **Build Stages**: development, production + +**Key Features**: + +- Multi-stage Dockerfile with optimized production build +- Hot reloading in development mode +- Volume mounts for source code in development +- Environment-specific database configuration (SQLite dev, PostgreSQL prod) + +#### sirius-api (Go REST API) + +- **Purpose**: RESTful API server and business logic +- **Technology**: Go 1.23 with Gin framework +- **Ports**: 9001 (HTTP) +- **Dependencies**: sirius-postgres, sirius-valkey, sirius-rabbitmq +- **Health Check**: `http://localhost:9001/api/v1/health` +- **Resource Limits**: 512MB RAM, 0.5 CPU +- **Build Stages**: development, runner + +**Key Features**: + +- Multi-stage build with optimized runner stage +- Volume mounts for development with live reloading +- Database connection pooling and health checks +- Message queue integration for async processing + +### Processing Services + +#### sirius-engine (Multi-Service Container) + +- **Purpose**: Core processing engine with multiple integrated services +- **Technology**: Go 1.23 with integrated submodules +- **Ports**: 5174 (HTTP), 50051 (gRPC) +- **Dependencies**: sirius-rabbitmq, sirius-postgres, sirius-valkey +- **Health Check**: `http://localhost:5174/health` +- **Resource Limits**: 1GB RAM, 1.0 CPU +- **Build Stages**: development, runtime + +**Integrated Services**: + +- **Agent System**: Manages scanning agents and their lifecycle +- **Scanner Integration**: Integrates with nmap, rustscan, and custom scanners +- **Terminal Management**: Provides secure terminal access for agents +- **gRPC Server**: Handles agent communication on port 50051 + +**Key Features**: + +- Multi-stage build with comprehensive dependency management +- Submodule integration for related projects +- Volume mounts for development with live code updates +- Resource-intensive processing capabilities + +### Data Services + +#### sirius-postgres (PostgreSQL Database) + +- **Purpose**: Primary data storage and persistence +- **Technology**: PostgreSQL 15 Alpine +- **Ports**: 5432 (PostgreSQL) +- **Dependencies**: None (foundation service) +- **Health Check**: `pg_isready -U postgres` +- **Resource Limits**: 1GB RAM, 0.5 CPU +- **Data Persistence**: `postgres_data` volume + +**Key Features**: + +- Production-optimized configuration in prod mode +- Connection pooling and performance tuning +- Automated health checks and restart policies +- Persistent data storage with volume mounts + +#### sirius-valkey (Redis Cache) + +- **Purpose**: Caching and session storage +- **Technology**: Valkey (Redis-compatible) +- **Ports**: 6379 (Redis) +- **Dependencies**: None (foundation service) +- **Health Check**: `redis-cli ping` +- **Resource Limits**: 256MB RAM, 0.25 CPU +- **Data Persistence**: `valkey_data` volume + +**Key Features**: + +- Lightweight and fast caching layer +- Session storage for authentication +- Temporary data storage for processing +- Memory-optimized configuration + +#### sirius-rabbitmq (Message Queue) + +- **Purpose**: Asynchronous message processing and service communication +- **Technology**: RabbitMQ 3.7.3 with Management UI +- **Ports**: 5672 (AMQP), 15672 (Management UI) +- **Dependencies**: None (foundation service) +- **Health Check**: `rabbitmqctl status` +- **Resource Limits**: 512MB RAM, 0.5 CPU +- **Data Persistence**: `rabbitmq_data` volume + +**Key Features**: + +- Reliable message queuing for async processing +- Management UI for monitoring and debugging +- Dead letter queues and message routing +- Production authentication in prod mode + +## Docker Compose Configurations + +### Base Configuration (`docker-compose.yaml`) + +The base configuration provides the core service definitions and is used as the foundation for all environments. + +**Key Characteristics**: + +- **Service Definitions**: All 6 services with production-ready defaults +- **Resource Limits**: Defined memory and CPU limits for each service +- **Health Checks**: Comprehensive health monitoring for all services +- **Dependencies**: Proper service startup order with health check conditions +- **Networking**: Custom bridge network named `sirius` +- **Volumes**: Persistent data storage for databases and message queue + +**Usage**: + +```bash +# Start all services with base configuration +docker compose up -d + +# Stop all services +docker compose down + +# View service status +docker compose ps +``` + +### Development Configuration (`docker-compose.dev.yaml`) + +The development configuration overrides the base configuration to enable development features. + +**Key Overrides**: + +- **Volume Mounts**: Source code mounted for live reloading +- **Build Targets**: Uses development stages for all services +- **Environment Variables**: Development-specific settings +- **Database Configuration**: SQLite for UI, PostgreSQL for API +- **Logging**: Debug-level logging enabled +- **Ports**: Additional development ports exposed + +**Key Features**: + +- **Hot Reloading**: Source code changes reflected immediately +- **Debug Mode**: Enhanced logging and error reporting +- **Development Dependencies**: All dev dependencies included +- **Volume Persistence**: Node modules preserved to avoid architecture conflicts + +**Usage**: + +```bash +# Start development environment +docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d + +# Stop development environment +docker compose -f docker-compose.yaml -f docker-compose.dev.yaml down +``` + +### Production Configuration (`docker-compose.prod.yaml`) + +The production configuration optimizes the base configuration for production deployment. + +**Key Overrides**: + +- **Build Targets**: Uses production/runner stages for all services +- **Environment Variables**: Production-specific settings +- **Resource Optimization**: Enhanced PostgreSQL and RabbitMQ configuration +- **Security**: Production authentication and secrets +- **Performance**: Optimized database and cache settings + +**Key Features**: + +- **Optimized Builds**: Multi-stage builds with minimal production images +- **Security Hardening**: Production authentication and secret management +- **Performance Tuning**: Database and cache optimization +- **Monitoring**: Enhanced health checks and resource monitoring + +**Usage**: + +```bash +# Start production environment +docker compose -f docker-compose.yaml -f docker-compose.prod.yaml up -d + +# Stop production environment +docker compose -f docker-compose.yaml -f docker-compose.prod.yaml down +``` + +## Dockerfile Architecture + +### Multi-Stage Build Strategy + +All services use multi-stage Dockerfiles to optimize image size and build efficiency. + +#### Image Tagging Strategy + +To prevent Docker cache conflicts when switching between environments, each environment uses distinct image tags: + +- **Development**: `sirius-sirius-ui:dev` - Built with development stage +- **Production**: `sirius-sirius-ui:prod` - Built with production stage +- **Base**: `sirius-sirius-ui:latest` - Built with default stage + +This ensures that switching environments always uses the correct build target and prevents cached development images from being used in production mode. + +#### sirius-ui Dockerfile + +**Stages**: + +1. **base**: Common dependencies and package installation +2. **development**: Full development environment with hot reloading +3. **production**: Optimized production build + +**Key Features**: + +- **Bun to npm conversion**: Automatic conversion for compatibility +- **Architecture support**: Multi-architecture builds +- **Optimized layers**: Cached dependency installation +- **Security**: Non-root user execution + +#### sirius-api Dockerfile + +**Stages**: + +1. **development**: Development environment with volume mounts +2. **runner**: Production-optimized runtime + +**Key Features**: + +- **Go modules**: Efficient dependency management +- **Security**: Non-root user execution +- **Optimization**: Minimal production image +- **Health checks**: Built-in health monitoring + +#### sirius-engine Dockerfile + +**Stages**: + +1. **builder**: Comprehensive build environment with all dependencies +2. **development**: Development environment with volume mounts +3. **runtime**: Production-optimized runtime + +**Key Features**: + +- **Submodule integration**: Automated cloning and building of related projects +- **Dependency management**: Comprehensive system and Go dependencies +- **Multi-service support**: Integrated agent, scanner, and terminal services +- **Resource optimization**: Efficient runtime with minimal dependencies + +## Service Dependencies and Startup + +### Dependency Chain + +``` +sirius-postgres (foundation) + ├── sirius-api (depends on postgres health) + └── sirius-ui (depends on postgres health in production) + +sirius-rabbitmq (foundation) + ├── sirius-api (depends on rabbitmq health) + └── sirius-engine (depends on rabbitmq health) + +sirius-valkey (foundation) + └── sirius-api (depends on valkey) + +sirius-api (middleware) + └── sirius-ui (depends on api for data) +``` + +### Startup Sequence + +1. **Foundation Services** (start first): + + - sirius-postgres + - sirius-valkey + - sirius-rabbitmq + +2. **Application Services** (start after foundation health checks): + + - sirius-api + - sirius-engine + +3. **Frontend Services** (start after application services): + - sirius-ui + +### Health Check Strategy + +- **Database Services**: Use native health check commands +- **Application Services**: HTTP health endpoints +- **Dependency Management**: Services wait for dependencies to be healthy +- **Retry Logic**: Configurable retry intervals and timeouts + +## Resource Management + +### Memory Allocation + +| Service | Development | Production | Notes | +| --------------- | ----------- | ---------- | -------------------------- | +| sirius-ui | 512MB | 1GB | Frontend with build tools | +| sirius-api | 256MB | 512MB | REST API with caching | +| sirius-engine | 512MB | 1GB | Multi-service processing | +| sirius-postgres | 512MB | 1GB | Database with optimization | +| sirius-valkey | 128MB | 256MB | Lightweight cache | +| sirius-rabbitmq | 256MB | 512MB | Message queue with UI | + +### CPU Allocation + +| Service | Development | Production | Notes | +| --------------- | ----------- | ---------- | -------------------- | +| sirius-ui | 0.25 | 0.5 | Frontend processing | +| sirius-api | 0.25 | 0.5 | API request handling | +| sirius-engine | 0.5 | 1.0 | Intensive processing | +| sirius-postgres | 0.25 | 0.5 | Database operations | +| sirius-valkey | 0.1 | 0.25 | Cache operations | +| sirius-rabbitmq | 0.25 | 0.5 | Message processing | + +## Networking Architecture + +### Network Configuration + +- **Network Name**: `sirius` +- **Driver**: Bridge +- **Scope**: Local +- **IPAM**: Default Docker IPAM + +### Port Mapping + +| Service | Internal Port | External Port | Protocol | Purpose | +| --------------- | ------------- | ------------- | -------- | ------------------- | +| sirius-ui | 3000 | 3000 | HTTP | Web interface | +| sirius-ui | 3001 | 3001 | HTTP | Development server | +| sirius-api | 9001 | 9001 | HTTP | REST API | +| sirius-engine | 5174 | 5174 | HTTP | Engine interface | +| sirius-engine | 50051 | 50051 | gRPC | Agent communication | +| sirius-postgres | 5432 | 5432 | TCP | Database | +| sirius-valkey | 6379 | 6379 | TCP | Cache | +| sirius-rabbitmq | 5672 | 5672 | AMQP | Message queue | +| sirius-rabbitmq | 15672 | 15672 | HTTP | Management UI | + +### Service Communication + +- **Internal Communication**: Services communicate using container names +- **External Access**: Ports exposed for external access +- **Health Checks**: Internal health check endpoints +- **Load Balancing**: Ready for external load balancer integration + +## Data Persistence + +### Volume Strategy + +- **Database Data**: Persistent volumes for PostgreSQL +- **Cache Data**: Persistent volumes for Valkey +- **Message Queue Data**: Persistent volumes for RabbitMQ +- **Application Data**: Volume mounts for development + +### Volume Configuration + +```yaml +volumes: + postgres_data: + driver: local + valkey_data: + driver: local + rabbitmq_data: + driver: local + node_modules: # Development only + driver: local +``` + +### Backup Strategy + +- **Database Backups**: Regular PostgreSQL dumps +- **Volume Backups**: Docker volume backup utilities +- **Configuration Backups**: Docker Compose file versioning +- **Disaster Recovery**: Multi-environment deployment strategy + +## Environment Management + +### Environment Variables + +#### Required Variables + +| Variable | Purpose | Default | Required | +| ----------------- | --------------------- | --------------------- | ---------- | +| POSTGRES_USER | Database user | postgres | No | +| POSTGRES_PASSWORD | Database password | postgres | No | +| POSTGRES_DB | Database name | sirius | No | +| NEXTAUTH_SECRET | Authentication secret | change-this-secret | Yes (prod) | +| NEXTAUTH_URL | Authentication URL | http://localhost:3000 | Yes (prod) | + +#### Optional Variables + +| Variable | Purpose | Default | Environment | +| ---------------- | ---------------- | ---------- | ----------- | +| NODE_ENV | Node environment | production | All | +| GO_ENV | Go environment | production | All | +| LOG_LEVEL | Logging level | info | All | +| API_PORT | API port | 9001 | All | +| ENGINE_MAIN_PORT | Engine port | 5174 | All | + +### Configuration Files + +- **Docker Compose**: Environment-specific overrides +- **Environment Files**: `.env` files for variable management +- **Dockerfile Args**: Build-time configuration +- **Service Configs**: Application-specific configuration + +## Monitoring and Observability + +### Health Checks + +- **HTTP Endpoints**: Application health endpoints +- **Database Checks**: Native database health commands +- **Service Dependencies**: Automatic dependency health monitoring +- **Resource Monitoring**: Memory and CPU usage tracking + +### Logging Strategy + +- **Container Logs**: Docker native logging +- **Application Logs**: Service-specific logging +- **Log Levels**: Configurable per service +- **Log Aggregation**: Ready for external log aggregation + +### Metrics Collection + +- **Service Metrics**: Built-in health check endpoints +- **Resource Metrics**: Docker stats and resource usage +- **Application Metrics**: Service-specific metrics +- **External Monitoring**: Ready for Prometheus/Grafana integration + +## Security Considerations + +### Container Security + +- **Non-root Users**: All services run as non-root users +- **Resource Limits**: Memory and CPU limits prevent resource exhaustion +- **Network Isolation**: Custom network with controlled access +- **Image Security**: Regular base image updates + +### Data Security + +- **Encryption**: Database and cache encryption at rest +- **Authentication**: Production authentication mechanisms +- **Secrets Management**: Environment variable-based secrets +- **Network Security**: Controlled port exposure + +### Production Security + +- **Secret Rotation**: Regular secret updates +- **Access Control**: Limited external port exposure +- **Audit Logging**: Comprehensive logging for security events +- **Vulnerability Scanning**: Regular container vulnerability scans + +## Troubleshooting + +### Common Issues + +#### Service Startup Failures + +**Symptoms**: Services fail to start or restart repeatedly +**Causes**: + +- Resource constraints +- Dependency health check failures +- Configuration errors +- Port conflicts + +**Solutions**: + +```bash +# Check service status +docker compose ps + +# View service logs +docker compose logs [service-name] + +# Check resource usage +docker stats + +# Restart specific service +docker compose restart [service-name] +``` + +#### Database Connection Issues + +**Symptoms**: API or UI cannot connect to database +**Causes**: + +- Database not ready +- Wrong connection parameters +- Network connectivity issues + +**Solutions**: + +```bash +# Check database health +docker compose exec sirius-postgres pg_isready -U postgres + +# Check database logs +docker compose logs sirius-postgres + +# Test connection +docker compose exec sirius-api curl -f http://localhost:9001/health +``` + +#### Build Failures + +**Symptoms**: Docker build fails or takes too long +**Causes**: + +- Insufficient resources +- Network connectivity issues +- Dockerfile errors +- Dependency resolution problems + +**Solutions**: + +```bash +# Clean build cache +docker builder prune + +# Build with verbose output +docker compose build --no-cache --progress=plain + +# Check build context +docker compose config +``` + +#### Volume Issues + +**Symptoms**: Data not persisting or permission errors +**Causes**: + +- Volume mount issues +- Permission problems +- Disk space issues + +**Solutions**: + +```bash +# Check volume status +docker volume ls + +# Inspect volume +docker volume inspect sirius_postgres_data + +# Clean up unused volumes +docker volume prune +``` + +#### Docker Layer Caching Issues + +**Symptoms**: + +- Production services running development code (e.g., `next dev` instead of `next start`) +- Wrong build targets being used despite correct Docker Compose configuration +- Services behaving differently than expected based on environment configuration +- React hook errors or development-specific errors in production mode + +**Causes**: + +- Docker layer caching preventing proper build stage selection +- Cached development images being used instead of production builds +- Multi-stage Dockerfile not building correct target stage +- Docker Compose not forcing rebuild of cached images + +**Root Cause Analysis**: +This issue occurs when Docker's layer caching system retains development-stage images and reuses them even when production configurations are specified. The problem manifests when: + +1. Development images are built first and cached +2. Production builds reference the same base layers +3. Docker reuses cached development layers instead of building production stages +4. The final image contains development code despite being tagged as production + +**Solutions**: + +**Immediate Fix**: + +```bash +# Stop all services +docker compose down + +# Clean Docker system cache +docker system prune -f + +# Rebuild with no cache +docker compose build --no-cache + +# Start services +docker compose up -d +``` + +**Prevention Strategies**: + +```bash +# Always use --no-cache for production builds +docker compose -f docker-compose.yaml -f docker-compose.prod.yaml build --no-cache + +# Clean build cache before switching environments +docker builder prune + +# Verify correct build target is being used +docker compose config | grep -A 5 "target:" +``` + +**Verification Steps**: + +```bash +# Check what command is actually running in container +docker compose exec sirius-ui ps aux + +# Verify build stage in container +docker compose exec sirius-ui cat /app/start-prod.sh + +# Check container logs for correct startup script +docker compose logs sirius-ui | grep -E "(next dev|next start|npm run)" + +# Verify environment variables +docker compose exec sirius-ui env | grep NODE_ENV +``` + +**Long-term Prevention**: + +1. **Use distinct image tags** for different environments +2. **Implement build stage validation** in CI/CD pipelines +3. **Regular cache cleanup** in automated builds +4. **Monitor container startup logs** for correct command execution +5. **Use multi-stage builds with explicit stage selection** + +**Example Multi-Stage Build Validation**: + +```dockerfile +# Ensure production stage is explicitly selected +FROM node:18-alpine AS production +# ... production-specific setup + +# Development stage should be clearly separated +FROM node:18-alpine AS development +# ... development-specific setup +``` + +**Docker Compose Target Verification**: + +```yaml +# Ensure correct target is specified +services: + sirius-ui: + build: + context: ./sirius-ui + target: production # Explicitly specify production stage +``` + +### Debugging Commands + +```bash +# View all service status +docker compose ps + +# View service logs +docker compose logs -f [service-name] + +# Execute commands in container +docker compose exec [service-name] [command] + +# View resource usage +docker stats + +# Check network connectivity +docker compose exec [service-name] ping [target-service] + +# View Docker Compose configuration +docker compose config + +# Restart all services +docker compose restart + +# Stop and remove all containers +docker compose down -v +``` + +### Performance Optimization + +#### Resource Tuning + +- **Memory Limits**: Adjust based on actual usage +- **CPU Limits**: Scale based on processing needs +- **Volume Performance**: Use local volumes for better performance +- **Network Optimization**: Optimize service communication + +#### Build Optimization + +- **Multi-stage Builds**: Use appropriate build stages +- **Layer Caching**: Optimize Dockerfile layer ordering +- **Dependency Management**: Minimize dependency changes +- **Image Size**: Use minimal base images + +## Best Practices + +### Development Workflow + +1. **Use Development Configuration**: Always use dev overrides for development +2. **Volume Mounts**: Use volume mounts for live code updates +3. **Health Checks**: Wait for services to be healthy before testing +4. **Resource Monitoring**: Monitor resource usage during development +5. **Log Analysis**: Use logs for debugging and optimization +6. **Cache Management**: Clean Docker cache when switching between environments +7. **Build Verification**: Always verify correct build targets are being used + +### Production Deployment + +1. **Environment Variables**: Use proper secret management +2. **Resource Planning**: Plan resources based on expected load +3. **Monitoring Setup**: Implement comprehensive monitoring +4. **Backup Strategy**: Implement regular backup procedures +5. **Security Hardening**: Apply production security measures +6. **Build Validation**: Always use `--no-cache` for production builds +7. **Environment Isolation**: Ensure clean separation between dev and prod builds + +### Environment Switching + +**New in v1.0.0**: Use the `scripts/switch-env.sh` script for seamless environment switching. + +#### Quick Environment Switching + +```bash +# Switch to development mode (hot reloading, volume mounts) +./scripts/switch-env.sh dev + +# Switch to production mode (optimized builds, PostgreSQL) +./scripts/switch-env.sh prod + +# Switch to base mode (standard configuration) +./scripts/switch-env.sh base +``` + +#### What the Script Does + +1. **Stops all containers** to ensure clean state +2. **Removes old images** to prevent cache conflicts +3. **Builds with correct target** for the specified environment +4. **Starts all services** with appropriate configuration +5. **Shows status and URLs** for easy access + +#### Manual Environment Switching + +If you need to switch environments manually: + +1. **Clean Transitions**: Always clean Docker cache when switching environments +2. **Build Verification**: Verify correct build targets before starting services +3. **Log Monitoring**: Check startup logs to ensure correct commands are running +4. **Cache Management**: Use `docker system prune` between environment switches +5. **Target Validation**: Explicitly specify build targets in Docker Compose files + +### Maintenance + +1. **Regular Updates**: Keep base images and dependencies updated +2. **Log Rotation**: Implement log rotation and cleanup +3. **Volume Management**: Monitor and clean up unused volumes +4. **Security Scanning**: Regular vulnerability scanning +5. **Performance Monitoring**: Continuous performance monitoring + +## Future Considerations + +### Scaling Strategy + +- **Horizontal Scaling**: Ready for service replication +- **Load Balancing**: External load balancer integration +- **Database Scaling**: Read replicas and connection pooling +- **Cache Scaling**: Redis cluster configuration + +### Advanced Features + +- **Service Mesh**: Istio or similar service mesh integration +- **Container Orchestration**: Kubernetes deployment readiness +- **CI/CD Integration**: Automated build and deployment pipelines +- **Monitoring Integration**: Prometheus and Grafana integration + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/architecture/README.engine-component-pinning.md b/documentation/dev/architecture/README.engine-component-pinning.md new file mode 100644 index 0000000..16204ea --- /dev/null +++ b/documentation/dev/architecture/README.engine-component-pinning.md @@ -0,0 +1,167 @@ +--- +title: "Engine Component Pinning" +description: "How sirius-engine pins each minor-project at build time, where pins live, who is allowed to change them, and how to bump a component without breaking CI." +template: "TEMPLATE.documentation-standard" +llm_context: "high" +categories: ["architecture", "deployment", "operations"] +tags: ["docker", "submodules", "pinning", "release-engineering", "ci-cd"] +related_docs: + - "README.docker-architecture.md" + - "README.cicd.md" + - "../../dev-notes/SHA-AUDIT-2026-04.md" + - "../README.development.md" +--- + +# Engine Component Pinning + +`sirius-engine` is built from six external SiriusScan repositories that +are cloned and compiled inside the engine image. To make every build +reproducible, each repository is pinned to a single commit SHA (or, for +`go-api`, a tag). This document describes where those pins live, the +rules that govern them, and the workflow to bump one safely. + +## Why pin + +Without explicit pins: + +- A `docker compose build` on Monday and the same command on Wednesday + could produce different binaries (silent supply-chain drift). +- A bug introduced in a minor-project's `main` branch lands in the next + engine image without any signal in the Sirius repo. +- Rollbacks become impossible because there is no record of *which* + upstream commit produced a given engine image. + +The `check-pin-consistency.yml` GitHub Action enforces these rules +mechanically (see `.github/workflows/check-pin-consistency.yml`). + +## Pinned components + +| ARG | Repository | Used by | Notes | +| --- | --- | --- | --- | +| `GO_API_COMMIT_SHA` | `SiriusScan/go-api` | All Go services in the engine + the standalone `sirius-api` image | Pinned by **tag** (`vX.Y.Z`). Tag is created in the `go-api` repo first, then bumped here. | +| `APP_SCANNER_COMMIT_SHA` | `SiriusScan/app-scanner` | Scanner binary (`/scanner`) | Full SHA. CGO build, depends on `libpcap` and `pingpp`. | +| `APP_TERMINAL_COMMIT_SHA` | `SiriusScan/app-terminal` | Terminal binary (`/terminal`) | Full SHA. | +| `SIRIUS_NSE_COMMIT_SHA` | `SiriusScan/sirius-nse` | NSE script repo bundled with the scanner | Full SHA. | +| `APP_AGENT_COMMIT_SHA` | `SiriusScan/app-agent` | Agent server (`/app-agent-src/server`) | Full SHA. | +| `PINGPP_COMMIT_SHA` | `SiriusScan/pingpp` | Fingerprinting library linked into `app-scanner` | Full SHA. | + +## Where pins live + +There are exactly **two** authoritative pin surfaces. They must always +agree. + +1. **`sirius-engine/Dockerfile` — `ARG ..._COMMIT_SHA` defaults** + + The Dockerfile is the source of truth. Local `docker compose build` + uses these defaults. The block lives at the top of the build stage + and carries a `# Pin policy` comment. + +2. **`.github/workflows/ci.yml` — `build-args` fallbacks** + + CI passes `${{ env.X_COMMIT_SHA || '' }}` for every pin in + the `build-engine` and `build-api` jobs. The `` literals + must match the Dockerfile defaults exactly. The `env.*` vars are + only populated when CI is triggered by a `repository_dispatch` from + a minor-project's release workflow (see "Bumping a pin via dispatch" + below). + +There is also a per-build override: + +3. **`docker compose build --build-arg X_COMMIT_SHA=...`** + + Local engineers can override any pin to test a hot fix, but this + override must never be committed. + +## Rules + +1. **No floating refs.** `main`, `master`, `HEAD`, branch names, or + relative refs like `HEAD~1` are forbidden. Every pin must be either + a full 40-character SHA or a semver tag. +2. **Dockerfile and CI must agree.** The + `check-pin-consistency.yml` workflow fails any PR that drifts. +3. **Tag preferred for `go-api`.** Other Sirius services consume + `go-api` as a Go module via `go.mod`. Bumping the tag in two places + (its own `go.mod` and ours) is easier with a tag than a SHA. +4. **Bumps are atomic.** A pin bump PR must update the Dockerfile, the + CI fallback, and the audit doc (current: `SHA-AUDIT-2026-04.md`, + future: a successor file) in one change set. +5. **Every pin bump references the upstream change.** PR description + must link to the upstream commit or tag and summarize behavior + changes that affect the engine. + +## Workflows + +### Bumping a pin manually + +```bash +# 1. Choose the new SHA (full 40-char) or tag. +NEW_SHA=ca1ef2fb75d2c422675eb41a27517da6aa5cf842 + +# 2. Edit sirius-engine/Dockerfile ARG block. +# 3. Edit .github/workflows/ci.yml build-engine fallback. +# 4. Append a row to documentation/dev-notes/SHA-AUDIT-2026-04.md +# (or the current audit doc) describing what changed and why. + +# 5. Verify locally. +docker compose -f docker-compose.yaml -f docker-compose.dev.yaml build --no-cache sirius-engine + +# 6. Open a PR. The check-pin-consistency.yml job will fail +# if Dockerfile and CI disagree, or if you used a floating ref. +``` + +### Bumping a pin via repository dispatch + +When a minor-project finishes its own release, its +`Notify Sirius` workflow fires a `repository_dispatch` event with: + +```json +{ + "event_type": "submodule-update", + "client_payload": { + "submodule": "SiriusScan/app-agent", + "commit_sha": "<40-char SHA>" + } +} +``` + +The Sirius `ci.yml` workflow: + +1. Derives the env-var name from `submodule` (e.g. `app-agent` → + `APP_AGENT_COMMIT_SHA`). +2. Sets `env.APP_AGENT_COMMIT_SHA = ` for the run. +3. Builds the engine image with the new SHA via + `${{ env.APP_AGENT_COMMIT_SHA || '' }}`. + +The result is published as `:latest` and `:beta`. The +**fallback in CI is intentionally not updated by the dispatch** — it +stays at the Dockerfile default until a human opens a PR. This means a +dispatch-triggered build is reproducible only as long as the dispatched +SHA exists; if you want the new SHA to be the long-lived floor, follow +the manual workflow above to land it in the Dockerfile. + +### Local hot-swap (no rebuild) + +For a fast iteration loop without rebuilding the image, see +`docker-compose.dev.yaml` (bind mounts) and the per-service `.air.toml` +files (live reload). See `../README.development.md` for the full +dev-mode workflow. + +## Common failure modes + +| Symptom | Likely cause | Fix | +| --- | --- | --- | +| Dashboard shows behavior that the latest source does not implement | Engine image is stale; pin is behind upstream `main` | Bump the relevant pin (manual or dispatch) and rebuild | +| `docker compose build` produces different binaries on different machines | A pin is using a floating ref like `main` | Replace with a full SHA; the guardrail will block this in CI | +| CI green on PR but runtime explodes after merge | Dockerfile and CI fallbacks disagree, and the merged build used the CI fallback (which differs from local) | Re-run guardrail; align both surfaces | +| `app-scanner` build fails with a `sed: pattern not found` error | An old branch still has the inline sed block; that block was removed in this overhaul | Rebase onto current `main`; the patches are now real source in `app-scanner` | + +## See also + +- `documentation/dev-notes/SHA-AUDIT-2026-04.md` — full audit and + per-component decision rationale captured at the time of the + overhaul. +- `documentation/dev/architecture/README.docker-architecture.md` — + overall engine container architecture. +- `documentation/dev/architecture/README.cicd.md` — CI/CD pipeline + overview. +- `documentation/dev/README.development.md` — dev-mode workflow. diff --git a/documentation/dev/architecture/README.go-api-sdk.md b/documentation/dev/architecture/README.go-api-sdk.md new file mode 100644 index 0000000..42155eb --- /dev/null +++ b/documentation/dev/architecture/README.go-api-sdk.md @@ -0,0 +1,750 @@ +--- +title: "Go API SDK Architecture" +description: "Comprehensive guide to the Sirius Go API SDK architecture, design patterns, and integration" +template: "TEMPLATE.documentation-standard" +llm_context: "high" +categories: ["architecture", "sdk", "backend"] +tags: ["go", "api", "sdk", "database", "orm", "gorm"] +related_docs: + - "README.architecture.md" + - "../operations/README.sdk-releases.md" + - "../../../minor-projects/go-api/README.md" +search_keywords: ["go-api", "sdk", "gorm", "database", "models", "postgres", "rabbitmq", "valkey"] +--- + +# Go API SDK Architecture + +## Overview + +The **Sirius Go API SDK** (`github.com/SiriusScan/go-api`) is a shared library that provides: + +- **Core data models** (Host, Port, Vulnerability, Service) +- **Database operations** (PostgreSQL via GORM) +- **Message queue integration** (RabbitMQ) +- **Key-value store** (ValKey/Redis) +- **NVD API integration** (vulnerability data enrichment) + +**Design Principles:** +- **Shared Types**: Single source of truth for data structures +- **Abstraction**: Database and queue operations hidden behind clean APIs +- **Source Attribution**: Track which tool found each piece of data +- **Flexibility**: Works across multiple projects (scanner, API server, agents) + +## Package Structure + +``` +go-api/ +├── sirius/ # Core functionality +│ ├── sirius.go # Core types (Host, Port, Vulnerability, Service) +│ ├── postgres/ # Database operations +│ │ ├── connection.go # DB initialization and connection management +│ │ ├── host_operations.go # Host CRUD operations +│ │ ├── vulnerability_operations.go +│ │ └── models/ # Database models (GORM) +│ │ ├── host.go # Host, Port, Service models +│ │ ├── vulnerability.go # Vulnerability, CVE models +│ │ └── scan_source.go # Source attribution models +│ ├── host/ # Host management SDK +│ │ ├── host.go # Basic host operations +│ │ └── source_aware.go # Source-attributed operations +│ ├── queue/ # RabbitMQ integration +│ │ └── queue.go # Publish/subscribe operations +│ ├── store/ # Key-value store (ValKey/Redis) +│ │ └── store.go # KV operations +│ └── logging/ # Logging infrastructure +│ ├── client.go # Logging client +│ └── api/ # Logging API server +├── nvd/ # NVD API integration +│ └── nvd.go # CVE data fetching +├── migrations/ # Database schema migrations +└── docs/ # SDK documentation +``` + +## Core Data Models + +### Host Model + +**File:** `sirius/sirius.go` + +```go +type Host struct { + HID string // Host identifier + OS string // Operating system + OSVersion string // OS version + IP string // IP address + Hostname string // DNS hostname + Ports []Port // Open ports + Services []Service // Running services + Vulnerabilities []Vulnerability // Found vulnerabilities + CPE []string // Common Platform Enumeration + Agent *SiriusAgent // Optional agent info +} +``` + +### Port Model + +**File:** `sirius/sirius.go` (Core), `sirius/postgres/models/host.go` (Database) + +```go +// Core type (used by applications) +type Port struct { + Number int `json:"number"` // Port number (22, 80, 443, etc.) + Protocol string `json:"protocol"` // tcp, udp + State string `json:"state"` // open, closed, filtered +} + +// Database model (used by GORM) +type Port struct { + gorm.Model // ID, CreatedAt, UpdatedAt, DeletedAt + Number int // Port number + Protocol string // Protocol + State string // State + Hosts []Host `gorm:"many2many:host_ports"` + HostPorts []HostPort `gorm:"foreignKey:PortID"` +} +``` + +**Key Design Decision:** Port numbers are stored in the `Number` field, NOT the auto-increment `ID` field. This allows the same port (e.g., port 22) to be associated with multiple hosts without conflicts. + +### Vulnerability Model + +**File:** `sirius/sirius.go` (Core), `sirius/postgres/models/vulnerability.go` (Database) + +```go +// Core type +type Vulnerability struct { + VID string `json:"vid"` // CVE ID (CVE-2017-0144) + Title string `json:"title"` // Vulnerability title + Description string `json:"description"` // Description + RiskScore float64 `json:"risk_score"` // CVSS score (0-10) +} + +// Database model +type Vulnerability struct { + gorm.Model + VID string `gorm:"column:v_id;uniqueIndex"` // Unique CVE ID + Description string + Title string + RiskScore float64 + Hosts []Host `gorm:"many2many:host_vulnerabilities"` + HostVulnerabilities []HostVulnerability `gorm:"foreignKey:VulnerabilityID"` +} +``` + +## Source Attribution System + +### Purpose + +Track **which tool** found **which data** on **which host** at **what time**. This enables: +- **Audit trails**: Know where data came from +- **Tool comparison**: Compare effectiveness of different scanners +- **Historical tracking**: See when vulnerabilities first appeared +- **Confidence scoring**: Weight findings by source reliability + +### Junction Tables with Source + +**HostPort Junction Table:** + +```go +type HostPort struct { + HostID uint `json:"host_id" gorm:"primaryKey"` + PortID uint `json:"port_id" gorm:"primaryKey"` + Source string `json:"source" gorm:"primaryKey"` // nmap, rustscan, naabu + SourceVersion string `json:"source_version"` // Tool version + FirstSeen time.Time `json:"first_seen"` // First detection + LastSeen time.Time `json:"last_seen"` // Last confirmation + Status string `json:"status" gorm:"default:active"` // active, resolved + Notes string `json:"notes,omitempty"` // Config details +} +``` + +**Primary Key:** `(host_id, port_id, source)` allows: +- Same port on same host tracked by multiple tools +- Comparison of results between tools +- Historical view of port states + +**HostVulnerability Junction Table:** + +Similar structure with additional fields: +- `Confidence` (0.0-1.0): How confident is this finding? +- `Port` (optional): Specific port where vulnerability found +- `ServiceInfo`: Service details + +### Using Source Attribution + +**Example: Add host with source:** + +```go +import ( + "github.com/SiriusScan/go-api/sirius" + "github.com/SiriusScan/go-api/sirius/host" + "github.com/SiriusScan/go-api/sirius/postgres/models" +) + +// Create host data +hostData := sirius.Host{ + IP: "192.168.1.100", + Ports: []sirius.Port{ + {Number: 22, Protocol: "tcp", State: "open"}, + {Number: 80, Protocol: "tcp", State: "open"}, + }, +} + +// Create source metadata +source := models.ScanSource{ + Name: "nmap", + Version: "7.94", + Config: "ports:1-1000;template:quick;timing:T4", +} + +// Submit with source attribution +err := host.AddHostWithSource(hostData, source) +``` + +## Database Operations + +### Connection Management + +**File:** `sirius/postgres/connection.go` + +```go +// Get database connection (singleton) +db := postgres.GetDB() + +// Initialize schema +err := postgres.InitDB() +``` + +**Environment Variables:** +- `DATABASE_HOST` (default: `localhost`) +- `DATABASE_PORT` (default: `5432`) +- `DATABASE_USER` (default: `postgres`) +- `DATABASE_PASSWORD` (default: `postgres`) +- `DATABASE_NAME` (default: `sirius`) + +### Host Operations + +**Basic Operations (Legacy):** + +```go +import "github.com/SiriusScan/go-api/sirius/host" + +// Add or update host +err := host.AddHost(hostData) + +// Get host by IP +hostData, err := host.GetHost("192.168.1.100") + +// Get all hosts +hosts, err := host.GetAllHosts() + +// Delete host +err := host.DeleteHost("192.168.1.100") +``` + +**Source-Aware Operations (Recommended):** + +```go +// Add/update with source tracking +err := host.AddHostWithSource(hostData, source) + +// Get host with all source attributions +hostWithSources, err := host.GetHostWithSources("192.168.1.100") + +// Get vulnerability history by source +history, err := host.GetVulnerabilityHistory(hostID, vulnID) + +// Get source coverage statistics +stats, err := host.GetSourceCoverageStats() +``` + +### Mapping Between Core and Database Types + +**File:** `sirius/host/host.go` + +```go +// Convert database model to core type +siriusHost := host.MapDBHostToSiriusHost(dbHost) + +// Convert core type to database model +dbHost := host.MapSiriusHostToDBHost(siriusHost) +``` + +**Important:** These functions handle: +- Port.Number ↔ Port field mapping +- Relationship loading (ports, services, vulnerabilities) +- Type conversions + +## Message Queue Integration + +### RabbitMQ + +**File:** `sirius/queue/queue.go` + +```go +import "github.com/SiriusScan/go-api/sirius/queue" + +// Publish message to queue +err := queue.Publish("scan", scanMessage) + +// Listen for messages +queue.Listen("scan", func(msg string) { + // Process message +}) +``` + +**Environment Variables:** +- `RABBITMQ_HOST` (default: `localhost`) +- `RABBITMQ_PORT` (default: `5672`) +- `RABBITMQ_USER` (default: `guest`) +- `RABBITMQ_PASSWORD` (default: `guest`) + +**Common Queues:** +- `scan` - Scan requests +- `scanner_logs` - Scanner log events +- `agent_commands` - Agent commands +- `terminal` - Terminal commands + +## Key-Value Store Integration + +### ValKey/Redis + +**File:** `sirius/store/store.go` + +```go +import "github.com/SiriusScan/go-api/sirius/store" + +// Set value +err := store.SetValue(ctx, "key", "value") + +// Get value +result, err := store.GetValue(ctx, "key") + +// Delete value +err := store.DeleteValue(ctx, "key") + +// List keys +keys, err := store.ListKeys(ctx, "pattern:*") +``` + +**Environment Variables:** +- `VALKEY_HOST` (default: `localhost`) +- `VALKEY_PORT` (default: `6379`) + +**Common Use Cases:** +- Real-time scan progress tracking +- Template storage (scan templates) +- Temporary data caching + +## NVD Integration + +### CVE Data Enrichment + +**File:** `nvd/nvd.go` + +```go +import "github.com/SiriusScan/go-api/nvd" + +// Fetch CVE details from NVD +cveData, err := nvd.GetCVE("CVE-2017-0144") + +// Access CVSS scores +score := cveData.Metrics.CvssMetricV31[0].CvssData.BaseScore +``` + +**Rate Limiting:** NVD API has rate limits. SDK respects these limits. + +## Integration Patterns + +### Pattern 1: Local Development with Replace Directive + +**Use Case:** Developing changes to go-api and dependent project simultaneously + +**go.mod:** +```go +module github.com/SiriusScan/app-scanner + +replace github.com/SiriusScan/go-api => ../go-api // Local development + +require ( + github.com/SiriusScan/go-api v0.0.11 // Version for production +) +``` + +**Benefits:** +- Test SDK changes immediately +- No need to publish SDK for every test +- Easy debugging across projects + +### Pattern 2: Production Use with Versioned Import + +**Use Case:** Production deployments + +**go.mod:** +```go +module github.com/SiriusScan/app-scanner + +require ( + github.com/SiriusScan/go-api v0.0.11 // Specific version +) +``` + +**Benefits:** +- Reproducible builds +- Version pinning +- Explicit dependency management + +### Pattern 3: Container Development with Volume Mounts + +**Use Case:** Docker-based development (sirius-engine, sirius-api) + +**docker-compose.dev.yaml:** +```yaml +services: + sirius-engine: + volumes: + - ../minor-projects/go-api:/go-api:ro # Mount SDK source + - ../minor-projects/app-scanner:/app-scanner +``` + +**go.mod in container:** +```go +replace github.com/SiriusScan/go-api => /go-api +``` + +**Benefits:** +- Live code reload +- No rebuild for SDK changes +- Mirrors local development + +## Version Management + +### Semantic Versioning + +**Format:** `v{MAJOR}.{MINOR}.{PATCH}` + +**Rules:** +- **MAJOR** (0.x.x → 1.x.x): Breaking changes, incompatible API changes +- **MINOR** (x.0.x → x.1.x): New features, backward compatible +- **PATCH** (x.x.0 → x.x.1): Bug fixes, backward compatible + +**Current:** v0.0.11 (pre-1.0, unstable API) + +### Breaking Change Policy + +**What Constitutes a Breaking Change:** +- ✅ Renaming exported fields (e.g., `Port.ID` → `Port.Number`) +- ✅ Changing function signatures +- ✅ Removing exported functions/types +- ✅ Changing database schema in non-backward-compatible way +- ❌ Adding new fields (backward compatible) +- ❌ Adding new functions (backward compatible) +- ❌ Internal implementation changes + +**Communication:** +- Document in CHANGELOG.md with `BREAKING CHANGE:` prefix +- Include migration guide +- Increment version appropriately +- Notify dependent projects + +### Compatibility Guarantees + +**Before v1.0.0:** +- ⚠️ No API stability guaranteed +- Breaking changes may occur in patch releases +- Use exact version pinning in production + +**After v1.0.0:** +- ✅ Semantic versioning strictly followed +- ✅ Breaking changes only in major versions +- ✅ Deprecation warnings before removal + +## Development Workflow + +### Making Changes to SDK + +**1. Create feature branch:** +```bash +cd go-api +git checkout -b feature/my-change +``` + +**2. Make changes and test locally:** +```bash +# Edit files +go test ./... +go build ./... +``` + +**3. Test in dependent project:** +```bash +cd ../app-scanner +# Ensure replace directive points to ../go-api +go mod tidy +go build . +``` + +**4. Commit and push:** +```bash +cd ../go-api +git add . +git commit -m "feat: add new feature" +git push origin feature/my-change +``` + +**5. Create Pull Request** + +**6. After merge to main:** +- CI/CD automatically creates new release +- Update dependent projects to new version + +### Testing Changes + +**Unit Tests:** +```bash +cd go-api +go test ./... +``` + +**Integration Tests:** +```bash +# Test with actual database +DATABASE_HOST=localhost go test ./sirius/postgres/... + +# Test with actual RabbitMQ +RABBITMQ_HOST=localhost go test ./sirius/queue/... +``` + +**Manual Testing:** +```bash +# Use in dependent project with replace directive +cd app-scanner +go run main.go +``` + +### Contributing Guidelines + +**Code Style:** +- Follow Go idioms and best practices +- Use `gofmt` for formatting +- Write meaningful commit messages (conventional commits) +- Add tests for new functionality + +**Documentation:** +- Update CHANGELOG.md for user-facing changes +- Add godoc comments for exported types/functions +- Update SDK documentation for architectural changes + +**Pull Requests:** +- Keep PRs focused and small +- Include test coverage +- Reference related issues +- Wait for CI/CD to pass + +## Common Patterns & Best Practices + +### Pattern: Bulk Operations + +**Problem:** Need to process many hosts efficiently + +**Solution:** +```go +// Use transactions for bulk operations +db := postgres.GetDB() +tx := db.Begin() + +for _, hostData := range hosts { + dbHost := host.MapSiriusHostToDBHost(hostData) + if err := tx.Create(&dbHost).Error; err != nil { + tx.Rollback() + return err + } +} + +tx.Commit() +``` + +### Pattern: Error Handling + +**Problem:** Need consistent error handling + +**Solution:** +```go +import "fmt" + +// Wrap errors with context +if err != nil { + return fmt.Errorf("failed to add host %s: %w", ip, err) +} + +// Check for specific errors +if errors.Is(err, gorm.ErrRecordNotFound) { + // Handle not found +} +``` + +### Pattern: Connection Pooling + +**Problem:** Efficient database connections + +**Solution:** +```go +// GetDB() returns singleton with connection pool +db := postgres.GetDB() + +// Configure in connection.go: +sqlDB, _ := db.DB() +sqlDB.SetMaxOpenConns(25) +sqlDB.SetMaxIdleConns(5) +sqlDB.SetConnMaxLifetime(5 * time.Minute) +``` + +### Pattern: Graceful Shutdown + +**Problem:** Clean up resources on exit + +**Solution:** +```go +func main() { + // Initialize connections + db := postgres.GetDB() + + // Handle shutdown + c := make(chan os.Signal, 1) + signal.Notify(c, os.Interrupt, syscall.SIGTERM) + + <-c + + // Cleanup + sqlDB, _ := db.DB() + sqlDB.Close() +} +``` + +## Troubleshooting + +### Issue: "Module not found" + +**Problem:** +``` +go: github.com/SiriusScan/go-api@v0.0.11: invalid version: unknown revision v0.0.11 +``` + +**Solutions:** +1. Check if version exists: `git ls-remote --tags https://github.com/SiriusScan/go-api` +2. Clear Go module cache: `go clean -modcache` +3. Use `replace` directive for local development + +### Issue: "Undefined field after update" + +**Problem:** +``` +port.ID undefined (type sirius.Port has no field or method ID) +``` + +**Solution:** +- Check CHANGELOG.md for breaking changes +- Update code to use new field names (e.g., `port.Number`) +- Run `go mod tidy` after updating version + +### Issue: Database connection fails + +**Problem:** +``` +failed to connect to database: connection refused +``` + +**Solution:** +1. Check environment variables are set correctly +2. Verify database is running: `docker ps | grep postgres` +3. Test connection: `psql -h localhost -U postgres -d sirius` + +### Issue: "Duplicate key violation" + +**Problem:** +``` +ERROR: duplicate key value violates unique constraint "ports_pkey" +``` + +**Solution:** +- Ensure using SDK version ≥ v0.0.11 (fixes Port.ID conflict) +- Run migration 005_fix_critical_schema_issues +- Clear old data if necessary + +## Migration Guides + +### Migrating from v0.0.9/v0.0.10 to v0.0.11 + +**Breaking Changes:** +1. `Port.ID` → `Port.Number` +2. `CVEDataMeta.ID` → `CVEDataMeta.CVEIdentifier` + +**Code Changes Required:** + +**Before:** +```go +port := sirius.Port{ + ID: 22, + Protocol: "tcp", +} + +ports := make([]int, len(host.Ports)) +for i, port := range host.Ports { + ports[i] = port.ID // ❌ No longer exists +} +``` + +**After:** +```go +port := sirius.Port{ + Number: 22, + Protocol: "tcp", +} + +ports := make([]int, len(host.Ports)) +for i, port := range host.Ports { + ports[i] = port.Number // ✅ Correct +} +``` + +**Database Migration:** +```bash +# Run migration in container +docker exec sirius-engine bash -c "cd /tmp/migrations && go run 005_fix_critical_schema_issues/main.go" +``` + +**Verification:** +1. Update go.mod: `require github.com/SiriusScan/go-api v0.0.11` +2. Run: `go mod tidy` +3. Find all references: `grep -r "port\.ID" .` +4. Replace with `port.Number` +5. Test build: `go build ./...` +6. Run tests: `go test ./...` + +## References + +### Related Documentation + +- [SDK Release Process](../operations/README.sdk-releases.md) - How to release new SDK versions +- [System Architecture](README.architecture.md) - Overall Sirius architecture +- [go-api README](../../../minor-projects/go-api/README.md) - SDK getting started guide +- [go-api CHANGELOG](../../../minor-projects/go-api/CHANGELOG.md) - Version history + +### External Resources + +- [GORM Documentation](https://gorm.io/docs/) +- [Go Module Reference](https://go.dev/ref/mod) +- [RabbitMQ Go Client](https://github.com/streadway/amqp) +- [ValKey Documentation](https://valkey.io/docs/) + +--- + +**Last Updated:** 2025-10-26 +**SDK Version:** v0.0.11 +**Author:** Sirius Team + + + + + + diff --git a/documentation/dev/architecture/README.scanner-storage.md b/documentation/dev/architecture/README.scanner-storage.md new file mode 100644 index 0000000..967ef42 --- /dev/null +++ b/documentation/dev/architecture/README.scanner-storage.md @@ -0,0 +1,196 @@ +--- +title: "Scanner Storage Contract" +description: "Single source of truth for the Valkey schema shared by app-scanner, sirius-api, app-agent, and sirius-ui for NSE scripts and agent templates." +template: "TEMPLATE.documentation-standard" +llm_context: "high" +categories: ["architecture", "storage", "scanner"] +tags: ["valkey", "templates", "nse", "schema", "contract", "go-api"] +related_docs: + - "README.go-api-sdk.md" + - "ARCHITECTURE.nse-repository-management.md" + - "../apps/agent/README.agent-template-api.md" + - "../apps/agent/README.agent-template-ui.md" +search_keywords: ["scanner storage", "template:custom", "template:meta", "nse:script", "templates package", "TemplateRecord", "NseScriptRecord", "canonical script id"] +--- + +# Scanner Storage Contract + +## Overview + +The Sirius scanner stack persists two record families in Valkey: + +- **Agent templates** - YAML vulnerability detection templates produced by the + UI and the agent's GitHub sync, consumed by the agent runtime. +- **NSE scripts** - Nmap scripting engine entries produced by `app-scanner`'s + GitHub sync, consumed by the UI for browsing/editing and by the scanner at + scan time. + +Every producer and consumer goes through the **`github.com/SiriusScan/go-api/sirius/store/templates`** +package. That package owns the key namespaces, JSON envelopes, and +canonicalization rules. If you are about to write code that reads or writes any +of the keys below, you must call into the helpers in that package - never +hand-roll the encoding. + +> Drift policy: any change to a record shape, key namespace, or canonicalization +> rule requires a `go-api` version bump, an updated entry in this document, and +> an updated assertion in `Sirius/testing/integration/scanner-storage/contract_test.go`, +> all in the same change set. + +## Producers, consumers, queues + +``` + ┌──────────────────────────────────────┐ + │ Valkey │ + │ │ + sirius-ui ──tRPC──▶│ template:custom: │◀── app-agent (read) + │ template:meta: │ (template runner) + │ template:standard: │ + sirius-api ────────▶│ template:manifest │ + (uploads) │ template:repo-manifest │ + │ │ + app-scanner ───────▶│ nse:script: │◀── sirius-ui (browse/edit) + (NSE sync) │ nse:meta: │ via sirius-api + │ nse:manifest │ + │ nse:repo-manifest │ + └──────────────────────────────────────┘ + + ┌──────────────────────────────────────┐ + │ RabbitMQ │ + │ │ + sirius-api ────────▶│ agent.template.sync.jobs │── app-agent (consumer) + (notify_agents) │ engine.commands (legacy) │── app-agent (defense in depth) + └──────────────────────────────────────┘ +``` + +The agent never polls the template manifest opportunistically; it only re-reads +when a sync notification lands on `agent.template.sync.jobs` (or the legacy +`engine.commands` mirror introduced in PR 5). + +## Key namespaces + +| Key | Defined as | Producer(s) | Consumer(s) | +| -------------------------------- | ------------------------------------------- | ---------------------- | ------------------- | +| `template:standard:` | `templates.AgentTemplateKey(id, false)` | app-agent (sync) | app-agent, sirius-api | +| `template:custom:` | `templates.AgentTemplateKey(id, true)` | sirius-api (uploads) | app-agent, sirius-api | +| `template:meta:` | `templates.AgentTemplateMetaKey(id)` | sirius-api, app-agent | sirius-api (enumeration) | +| `template:manifest` | `templates.KeyAgentTemplateManifest` | app-agent | app-agent | +| `template:repo-manifest` | `templates.KeyAgentTemplateRepoManifest` | app-agent | app-agent | +| `template:version:` | `templates.KeyAgentTemplateVersionPrefix` | app-agent | app-agent | +| `nse:script:` | `templates.NseScriptKey(id)` | app-scanner | sirius-api, app-scanner | +| `nse:meta:` | `templates.KeyNseScriptMetaPrefix` | app-scanner | sirius-api | +| `nse:manifest` | `templates.KeyNseManifest` | app-scanner | sirius-api, app-scanner | +| `nse:repo-manifest` | `templates.KeyNseRepoManifest` | app-scanner | app-scanner | + +`` is whatever `templates.CanonicalScriptID(id)` returns. The +canonicalizer strips the `.nse` suffix and lowercases nothing else. You should +never construct an NSE key by string concatenation; always go through +`templates.NseScriptKey`. + +## Record shapes + +### `TemplateRecord` + +Source: [`go-api/sirius/store/templates/template_record.go`](mdc:../../../minor-projects/go-api/sirius/store/templates/template_record.go). + +Field tags pinned by `TestContract_TemplateWireShape` in the contract suite: + +| JSON field | Go type | Notes | +| ------------------- | ------------------ | ----- | +| `id` | string | canonical id, no extension | +| `version` | string | semver string supplied by the producer | +| `checksum` | string | hex SHA-256 of `content`; populate via `templates.SHA256Hex` | +| `size` | int64 | byte length of `content` | +| `severity` | string | `info`, `low`, `medium`, `high`, `critical` | +| `platforms` | []string | `linux`, `windows`, `darwin`, ... | +| `detection_type` | string | `agent` or `network` | +| `author` | string | optional | +| `created` | time.Time (RFC3339)| set on first upload | +| `updated` | time.Time (RFC3339)| bump on every write | +| `vulnerability_ids` | []string | CVE / advisory ids the template detects | +| `is_custom` | bool | true ⇒ persisted under `template:custom:` | +| `content` | []byte (base64) | YAML body; omitted from `template:meta:` | +| `metadata` | map[string]string | optional free-form labels | + +The meta projection (used at `template:meta:`) is always +`r.Meta()`/`templates.EncodeMeta(r)` - it strips `Content` and leaves every +other field intact, so an enumerator can list custom templates without paying +the YAML body cost. + +### `NseScriptRecord` + +Source: [`go-api/sirius/store/templates/nse_record.go`](mdc:../../../minor-projects/go-api/sirius/store/templates/nse_record.go). + +| JSON field | Go type | Notes | +| ------------ | ------------------ | ----- | +| `content` | string | full Lua/NSE source | +| `metadata` | `NseScriptMeta` | `author`, `tags[]`, `description` | +| `updatedAt` | int64 | Unix seconds; producer-supplied | + +`NseManifestEntry` (`name`, `path`, `protocol`) and `NseManifest` +(`name`, `version`, `description`, `scripts[]`) are also defined alongside +the script record. Manifest map keys are canonicalized on write by +`templates.WriteNseManifest`. + +## Helpers you should be calling + +```go +import "github.com/SiriusScan/go-api/sirius/store/templates" + +// Templates +key := templates.AgentTemplateKey(id, isCustom) // template:standard|custom: +mkey := templates.AgentTemplateMetaKey(id) // template:meta: + +err := templates.WriteTemplate(ctx, kv, rec) // envelope + meta, with rollback +rec, err := templates.ReadTemplate(ctx, kv, id) // tries custom then standard +meta, err := templates.ReadTemplateMeta(ctx, kv, id) + +// NSE scripts +key := templates.NseScriptKey(id) // nse:script: + +err := templates.WriteNseScript(ctx, kv, id, rec) +rec, err := templates.ReadNseScript(ctx, kv, id) // canonicalizes id for you + +err := templates.WriteNseManifest(ctx, kv, m) // canonicalizes map keys +m, err := templates.ReadNseManifest(ctx, kv) + +// Canonicalization is exposed on its own for callers (e.g. the UI -> API +// path that must match what the producer wrote). +canonical := templates.CanonicalScriptID("http-shellshock.nse") // "http-shellshock" +``` + +## Contract test + +`Sirius/testing/integration/scanner-storage/contract_test.go` is a self-contained +Go module that exercises every writer/reader pair through the shared package +against an in-memory KV. It runs as part of `make test-integration` and on every +PR via the Sirius CI Integration Test job. + +Add a new pair (or a new record type) here whenever you onboard a new producer +or consumer. The suite is intentionally cheap so it can be the canary that +catches schema drift before any service redeploys. + +## Operational notes + +- **Reading custom vs standard** - prefer `templates.ReadTemplate`; it tries + the custom namespace first and falls through to standard, which matches the + precedence the agent uses at runtime. +- **Custom uploads** - sirius-api persists the envelope, then the meta record, + then publishes a `notify_agents` job to `agent.template.sync.jobs`. The + shared helper rolls back the envelope on a meta-write failure so the + enumerator never sees an orphaned custom template. +- **Engine commands listener** - app-agent additionally consumes the legacy + `engine.commands` queue and accepts `internal:template upload|delete` as a + defense-in-depth trigger for the same `NotifyAgents` flow. See + [`app-agent internal/server/engine_commands_consumer.go`](mdc:../../../minor-projects/app-agent/internal/server/engine_commands_consumer.go). +- **Never** persist NSE scripts with a `.nse` suffix in the key. The + canonicalization rule exists because the UI canonicalizes before lookup; if + the producer doesn't, the UI silently shows an empty body. PR 1 fixed the + original drift; the contract test guards against regressions. + +## Related work + +- PR 1 - canonicalize NSE script keys + ([`app-scanner internal/nse/sync.go`](mdc:../../../minor-projects/app-scanner/internal/nse/sync.go)) +- PR 6 - introduce the shared `templates` package in `go-api v0.0.18` +- PR 7 - migrate sirius-api, app-scanner, app-agent to that package +- PR 8 - this document plus the contract test diff --git a/documentation/dev/architecture/README.system-monitor.md b/documentation/dev/architecture/README.system-monitor.md new file mode 100644 index 0000000..59fae31 --- /dev/null +++ b/documentation/dev/architecture/README.system-monitor.md @@ -0,0 +1,870 @@ +--- +title: "SystemMonitor Architecture and Operations Guide" +description: "Comprehensive guide to SystemMonitor implementation, deployment, and troubleshooting" +template: "TEMPLATE.documentation-standard" +version: "2.1.0" +last_updated: "2025-10-07" +author: "Sirius Development Team" +tags: + [ + "system-monitor", + "monitoring", + "containers", + "troubleshooting", + "architecture", + "development", + ] +categories: ["architecture", "operations", "monitoring"] +difficulty: "intermediate" +prerequisites: ["docker", "go", "container-monitoring", "cgroups"] +related_docs: + - "README.architecture.md" + - "README.container-testing.md" + - "README.development.md" +dependencies: + - "app-system-monitor/" + - "sirius-engine/start-enhanced.sh" + - "sirius-ui/start-dev.sh" +llm_context: "high" +search_keywords: + [ + "system-monitor", + "cpu-monitoring", + "container-metrics", + "troubleshooting", + "deployment", + "development-mode", + "exec-format-error", + ] +--- + +# SystemMonitor Architecture and Operations Guide + +## Overview + +The SystemMonitor is a critical component that provides real-time system resource monitoring for all Sirius containers. It collects CPU, memory, network, disk, and process metrics from within containerized environments and stores them in Valkey for centralized monitoring and alerting. + +**Key Features:** + +- Real-time metrics collection every 5 seconds +- Support for both development (`go run`) and production (binary) modes +- Multi-architecture support (amd64, arm64) +- CPU drift-free monitoring with time-based calculations +- Automatic fallback mechanisms for missing metrics + +## Architecture + +### Core Components + +#### 1. **Main SystemMonitor Project** + +- **Location**: `/minor-projects/app-system-monitor/` +- **Language**: Go 1.23 +- **Purpose**: Single source of truth for all SystemMonitor implementations +- **Dependencies**: `github.com/SiriusScan/go-api` for Valkey connectivity + +#### 2. **Deployment Modes** + +**Development Mode:** + +- Uses `go run main.go` to run SystemMonitor from source +- Automatically picks up code changes without rebuild +- Enabled when `GO_ENV=development` environment variable is set +- Used in sirius-engine and sirius-ui development containers + +**Production Mode:** + +- Uses pre-compiled binary built from GitHub source +- Compiled during Docker image build process +- Better performance and smaller runtime footprint +- Used in all production deployments + +#### 3. **Container Integration** + +**All Containers (PostgreSQL, RabbitMQ, Valkey, Engine, UI):** + +- Build SystemMonitor from GitHub source during Docker image build +- Use multi-stage build to compile from `github.com/SiriusScan/app-system-monitor` +- Copy compiled binary to final image +- Start SystemMonitor alongside main service + +**Development Mode (Engine, UI):** + +- Volume-mount `../minor-projects/app-system-monitor` for live development +- Run with `go run main.go` instead of binary +- Enables rapid iteration without container rebuilds + +## SystemMonitor Implementation + +### CPU Monitoring (Fixed in v2.0) + +The SystemMonitor uses a sophisticated CPU utilization calculation that eliminates drift: + +```go +// Time-based CPU utilization calculation +cpuPercent := (float64(cpuDiff) / 1000000.0) / timeDiff / float64(sm.cpuCores) * 100.0 +``` + +**Key Features:** + +- **State Tracking**: Maintains previous CPU usage and timestamp +- **Core Detection**: Automatically detects available CPU cores from cgroups +- **Drift Prevention**: Uses time-based differences instead of cumulative values +- **Architecture Support**: Works across different CPU architectures + +### Memory Monitoring + +Uses cgroups v2 for accurate container memory metrics: + +```go +// Read from cgroups v2 +currentBytes := readCgroupFile("/sys/fs/cgroup/memory.current") +maxBytes := readCgroupFile("/sys/fs/cgroup/memory.max") +percent := float64(currentBytes) / float64(maxBytes) * 100.0 +``` + +### Network Monitoring + +Tracks network I/O from container interfaces: + +```go +// Network statistics +rxBytes := readCgroupFile("/sys/class/net/eth0/statistics/rx_bytes") +txBytes := readCgroupFile("/sys/class/net/eth0/statistics/tx_bytes") +``` + +### Disk Monitoring + +Calculates container filesystem usage: + +```go +// Walk container filesystem (excluding mounted volumes) +filepath.WalkDir("/", func(path string, d os.DirEntry, err error) error { + // Skip mounted volumes and system directories + if strings.HasPrefix(path, "/api") || strings.HasPrefix(path, "/proc") { + return filepath.SkipDir + } + // Calculate total size +}) +``` + +## Deployment Architecture + +### Build Process + +#### Production Builds (All Containers) + +All containers use a multi-stage Docker build to compile SystemMonitor from source: + +```dockerfile +# Builder stage - Clone and build SystemMonitor +FROM golang:1.23-alpine AS builder +RUN apk add --no-cache git +RUN git clone https://github.com/SiriusScan/app-system-monitor.git && \ + cd app-system-monitor && \ + go mod download && \ + CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o system-monitor main.go + +# Runtime stage - Copy binary +FROM +COPY --from=builder /go/app-system-monitor/system-monitor /usr/local/bin/system-monitor +RUN chmod +x /usr/local/bin/system-monitor +``` + +**Benefits:** + +- Always builds from latest source code +- No pre-compiled binary distribution needed +- Architecture-specific compilation +- Smaller final image size + +#### Development Mode (Engine & UI) + +Development containers use `go run` for live development: + +```yaml +# docker-compose.dev.yaml +volumes: + - ../minor-projects/app-system-monitor:/system-monitor +environment: + - GO_ENV=development +``` + +**Startup logic checks environment:** + +```bash +if [ "$GO_ENV" = "development" ] && [ -f "/system-monitor/main.go" ]; then + CONTAINER_NAME=sirius-engine go run main.go & +elif [ -f "/system-monitor/system-monitor" ] && [ -x "/system-monitor/system-monitor" ]; then + CONTAINER_NAME=sirius-engine ./system-monitor & +fi +``` + +### Container Startup Integration + +#### PostgreSQL/RabbitMQ/Valkey Pattern (Production Only) + +```bash +# In start-with-monitor.sh +echo "📊 Starting system monitor..." +cd /usr/local/bin +CONTAINER_NAME=sirius-postgres ./system-monitor & +``` + +These containers always use the compiled binary from the Docker build. + +#### Engine Pattern (Development & Production) + +```bash +# In start-enhanced.sh +if [ -d "/system-monitor" ]; then + echo "Starting system monitor..." + cd /system-monitor + if [ "$GO_ENV" = "development" ] && [ -f "main.go" ]; then + echo "Running system monitor with go run (development mode)" + CONTAINER_NAME=sirius-engine go run main.go & + elif [ -f "./system-monitor" ] && [ -x "./system-monitor" ]; then + echo "Running system monitor binary (production mode)" + CONTAINER_NAME=sirius-engine ./system-monitor & + else + echo "Error: System monitor not found (neither main.go nor binary)" + exit 1 + fi + SYSTEM_MONITOR_PID=$! + sleep 2 + check_service "System Monitor" $SYSTEM_MONITOR_PID +fi +``` + +**Key Features:** + +- Checks `GO_ENV` environment variable +- Prefers `go run` in development mode +- Falls back to binary in production +- Provides clear error messages if neither is available + +#### UI Pattern (Development & Production) + +```bash +# In start-dev.sh +if [ -d "/system-monitor" ] && [ -f "/system-monitor/main.go" ]; then + echo "📊 Starting System Monitor..." + cd /system-monitor + CONTAINER_NAME=sirius-ui go run main.go & + SYSTEM_MONITOR_PID=$! + echo "✅ System Monitor started with PID: $SYSTEM_MONITOR_PID" + cd /app +fi +``` + +```bash +# In start-prod.sh +if [ -f "/system-monitor/system-monitor" ] && [ -x "/system-monitor/system-monitor" ]; then + echo "📊 Starting system monitor..." + cd /system-monitor + CONTAINER_NAME=sirius-ui ./system-monitor & + SYSTEM_MONITOR_PID=$! + echo "✅ System monitor started with PID: $SYSTEM_MONITOR_PID" + cd /app +fi +``` + +## Configuration + +### Environment Variables + +| Variable | Purpose | Default | Example | +| ---------------- | ---------------------- | --------------- | ----------------- | +| `CONTAINER_NAME` | Container identifier | `unknown` | `sirius-postgres` | +| `VALKEY_HOST` | Valkey server hostname | `sirius-valkey` | `localhost` | +| `VALKEY_PORT` | Valkey server port | `6379` | `6379` | + +### Metrics Storage + +**Valkey Keys:** + +- `system:metrics:{container_name}` - Latest metrics +- `system:logs:{container_name}:{timestamp}` - Log entries + +**Metrics Structure:** + +```json +{ + "container_name": "sirius-postgres", + "timestamp": "2025-01-07T12:00:00Z", + "cpu_percent": 15.2, + "memory_usage_bytes": 67108864, + "memory_percent": 1.8, + "network_rx_bytes": 1048576, + "network_tx_bytes": 524288, + "disk_usage_bytes": 134217728, + "disk_percent": 1.3, + "process_count": 12, + "file_descriptors": 45, + "load_average_1m": 0.15, + "load_average_5m": 0.12, + "load_average_15m": 0.1, + "uptime_seconds": 3600, + "status": "running" +} +``` + +## Troubleshooting Guide + +### Common Issues and Solutions + +#### 1. **SystemMonitor Not Starting / Exec Format Error** + +**Symptoms:** + +- Container starts but no metrics appear in monitoring dashboard +- Logs show "System Monitor failed to start or crashed" +- **"cannot execute binary file: Exec format error"** (most common in development mode) +- Container stuck in crash loop restarting every few seconds + +**Most Likely Causes:** + +1. **Development Mode Binary Mismatch** (95% of cases): + + - Volume-mounted `/system-monitor` contains pre-compiled binary for wrong architecture + - Development container trying to execute x86_64 binary on ARM64 (or vice versa) + - Solution: Use `go run` instead of pre-compiled binary + +2. **Missing Binary**: SystemMonitor binary not present in container +3. **Permission Issues**: Binary not executable +4. **Go Not Available**: Development mode but Go not installed in container + +**Diagnostic Steps:** + +```bash +# Check if binary exists and architecture +docker exec ls -la /system-monitor/ +docker exec file /system-monitor/system-monitor + +# Check container architecture +docker exec uname -m + +# Check if Go is available (for development mode) +docker exec which go +docker exec go version + +# Check environment mode +docker exec env | grep GO_ENV + +# Check container logs for startup mode +docker logs | grep -i "system monitor\|go run\|development" +``` + +**Solutions:** + +**For Development Mode (Engine/UI):** + +1. **Verify startup script uses `go run`**: + + ```bash + # Check if start-enhanced.sh or start-dev.sh has: + if [ "$GO_ENV" = "development" ] && [ -f "main.go" ]; then + go run main.go & + fi + ``` + +2. **Rebuild container to pick up updated startup script**: + + ```bash + docker-compose -f docker-compose.yaml -f docker-compose.dev.yaml build + docker-compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d + ``` + +3. **Verify development environment is set**: + ```bash + # In docker-compose.dev.yaml + environment: + - GO_ENV=development + ``` + +**For Production Mode:** + +1. **Rebuild container** (rebuilds SystemMonitor from source): + + ```bash + docker-compose build + docker-compose up -d + ``` + +2. **Verify Dockerfile has multi-stage build**: + ```dockerfile + FROM golang:1.23-alpine AS builder + RUN git clone https://github.com/SiriusScan/app-system-monitor.git + # ... build steps ... + ``` + +#### 2. **CPU Utilization Drift** + +**Symptoms:** + +- CPU usage gradually increases over time +- Metrics don't match Docker's performance data +- CPU percentages exceed 100% + +**Root Cause:** + +- Old SystemMonitor versions used cumulative CPU time incorrectly +- Missing time-based calculation logic + +**Solution:** + +- Ensure using SystemMonitor v2.0+ with proper CPU calculation +- Verify `lastCPUUsage` and `lastCPUTime` state tracking + +#### 3. **Valkey Connection Issues** + +**Symptoms:** + +- SystemMonitor starts but metrics not stored +- "Error storing metrics" in logs +- Empty metrics in monitoring dashboard + +**Diagnostic Steps:** + +```bash +# Check Valkey connectivity +docker exec nc -zv sirius-valkey 6379 + +# Check Valkey logs +docker logs sirius-valkey + +# Test Valkey connection from container +docker exec redis-cli -h sirius-valkey ping +``` + +**Solutions:** + +1. **Network Issues**: Check Docker network connectivity +2. **Valkey Down**: Restart Valkey container +3. **Firewall**: Check port 6379 accessibility + +#### 4. **Service Crash Loop Due to Scanner/Other Service Failures** + +**Symptoms:** + +- SystemMonitor starts successfully but then container restarts +- Logs show "Scanner failed to start or crashed" +- Container repeatedly cycles through startup sequence +- SystemMonitor unable to maintain connection + +**Root Cause:** + +- In early implementations, any service failure (like scanner) would trigger `cleanup` function +- This shutdown ALL services including SystemMonitor +- Created unnecessary crash loops when only one service had issues + +**Solution (Implemented in v2.1):** + +The scanner and other non-critical services are now non-fatal: + +```bash +# In start-enhanced.sh +if [ -n "$SCANNER_PATH" ]; then + cd "$SCANNER_PATH" + echo "Starting scanner service..." + go run main.go & + SCANNER_PID=$! + sleep 2 + # Check if scanner started, but don't fail if it didn't + if ! kill -0 $SCANNER_PID 2>/dev/null; then + echo "Warning: Scanner failed to start, but continuing with other services" + SCANNER_PID="" + fi +fi +``` + +**Key Changes:** + +- Scanner failure no longer calls `cleanup` function +- Other services (SystemMonitor, Terminal, Agent) continue running +- Warning logged but container remains operational +- Allows investigation of scanner issues without affecting monitoring + +#### 5. **Memory Metrics Inaccurate** + +**Symptoms:** + +- Memory usage doesn't match container limits +- Memory percentage calculations seem wrong + +**Diagnostic Steps:** + +```bash +# Check cgroups v2 files +docker exec cat /sys/fs/cgroup/memory.current +docker exec cat /sys/fs/cgroup/memory.max + +# Compare with Docker stats +docker stats --no-stream +``` + +**Solutions:** + +1. **Cgroups v2**: Ensure container supports cgroups v2 +2. **Fallback Values**: Check if using fallback memory estimates +3. **Container Limits**: Verify memory limits are set correctly + +### Performance Issues + +#### High CPU Usage from SystemMonitor + +**Symptoms:** + +- SystemMonitor itself consuming significant CPU +- Container performance degraded + +**Causes:** + +1. **Frequent Polling**: Metrics collection interval too short +2. **Inefficient Calculations**: Complex disk usage calculations +3. **Memory Leaks**: Go runtime issues + +**Solutions:** + +1. **Adjust Polling**: Increase collection interval (default: 5 seconds) +2. **Optimize Disk Scanning**: Limit filesystem traversal +3. **Memory Profiling**: Use Go profiling tools + +#### Memory Leaks + +**Symptoms:** + +- SystemMonitor memory usage grows over time +- Container memory limits exceeded + +**Diagnostic Steps:** + +```bash +# Monitor SystemMonitor memory usage +docker exec ps aux | grep system-monitor + +# Check for goroutine leaks +docker exec curl http://localhost:6060/debug/pprof/goroutine +``` + +### Log Analysis + +#### SystemMonitor Logs + +**Location**: Container stdout/stderr +**Format**: Standard Go log format + +**Key Log Messages:** + +- `"Starting system monitor for container: {name}"` - Successful startup +- `"Error reading cpu.stat: {error}"` - CPU monitoring issues +- `"Error storing metrics: {error}"` - Valkey connectivity problems +- `"Warning: metrics channel full, dropping metrics"` - Performance issues + +#### Log Patterns for Issues + +```bash +# CPU monitoring problems +grep -i "cpu.stat\|cpu.max" + +# Memory monitoring issues +grep -i "memory.current\|memory.max" + +# Network connectivity +grep -i "valkey\|redis" + +# Performance warnings +grep -i "channel full\|dropping" +``` + +## Maintenance and Updates + +### Updating SystemMonitor + +#### For Development Mode (Local Changes) + +1. **Modify Source Code**: + + ```bash + cd /minor-projects/app-system-monitor/ + # Make changes to main.go + ``` + +2. **Test Changes** (no rebuild needed in development mode): + + ```bash + # Restart container to pick up changes + docker-compose -f docker-compose.yaml -f docker-compose.dev.yaml restart sirius-engine + # SystemMonitor will recompile with go run on startup + ``` + +3. **Verify Changes**: + + ```bash + # Check logs for SystemMonitor startup + docker logs sirius-engine | grep -i "system monitor" + + # Verify metrics in Valkey + docker exec sirius-valkey redis-cli get "system:metrics:sirius-engine" + ``` + +#### For Production Deployment + +1. **Push Changes to GitHub**: + + ```bash + cd /minor-projects/app-system-monitor/ + git add . + git commit -m "feat(monitoring): update SystemMonitor metrics" + git push origin main + ``` + +2. **Rebuild All Containers** (they fetch latest from GitHub): + + ```bash + # Full rebuild with no cache to get latest source + docker-compose build --no-cache sirius-postgres sirius-rabbitmq sirius-valkey sirius-engine sirius-ui + ``` + +3. **Deploy Updates**: + ```bash + docker-compose up -d + ``` + +#### Testing in Development Before Production + +1. **Make changes locally** in `/minor-projects/app-system-monitor/` +2. **Test in development mode** with `docker-compose.dev.yaml` +3. **Verify metrics** are collecting correctly +4. **Commit and push** to GitHub +5. **Rebuild production images** to fetch from GitHub +6. **Deploy to production** + +### Monitoring SystemMonitor Health + +#### Health Check Endpoints + +**Valkey Metrics Check**: + +```bash +# Check if metrics are being stored +redis-cli -h sirius-valkey get "system:metrics:sirius-postgres" +``` + +**Container Process Check**: + +```bash +# Verify SystemMonitor is running +docker exec ps aux | grep system-monitor +``` + +#### Automated Monitoring + +**Metrics Collection Frequency**: Every 5 seconds +**Log Generation**: Every 30 seconds +**Health Check**: Monitor Valkey key updates + +### Development Guidelines + +#### Adding New Metrics + +1. **Update SystemMetrics struct**: + + ```go + type SystemMetrics struct { + // ... existing fields ... + NewMetric float64 `json:"new_metric"` + } + ``` + +2. **Implement Collection Logic**: + + ```go + func (sm *SystemMonitor) readNewMetric() float64 { + // Implementation + } + ``` + +3. **Update gatherSystemMetrics**: + ```go + return SystemMetrics{ + // ... existing fields ... + NewMetric: sm.readNewMetric(), + } + ``` + +#### Testing Changes + +1. **Local Testing**: + + ```bash + cd /minor-projects/app-system-monitor/ + go run main.go + ``` + +2. **Container Testing**: + + ```bash + # Build and test in container + docker run --rm -it /usr/local/bin/system-monitor + ``` + +3. **Integration Testing**: + ```bash + # Deploy to development environment + docker-compose -f docker-compose.dev.yaml up -d + ``` + +## Security Considerations + +### Container Security + +- **Non-root Execution**: SystemMonitor runs with container user permissions +- **Read-only Access**: Only reads system files, no write access +- **Network Isolation**: Communicates only with Valkey service + +### Data Privacy + +- **No Sensitive Data**: Only collects system resource metrics +- **Local Processing**: All calculations performed within container +- **Encrypted Transport**: Valkey connections should use TLS in production + +## Performance Tuning + +### Optimization Settings + +**Collection Intervals**: + +- **Metrics**: 5 seconds (configurable) +- **Logs**: 30 seconds (configurable) + +**Resource Limits**: + +- **CPU**: Minimal impact (< 0.1% typical) +- **Memory**: ~10-20MB per container +- **Network**: Minimal bandwidth usage + +### Scaling Considerations + +- **Container Count**: Linear scaling with container count +- **Valkey Load**: Minimal impact on Valkey performance +- **Network Overhead**: Negligible for typical deployments + +## Support and Escalation + +### First-Level Support + +1. **Check Container Status**: `docker ps` +2. **Review Logs**: `docker logs ` +3. **Verify Network**: Test Valkey connectivity +4. **Check Metrics**: Verify Valkey key updates + +### Escalation Path + +1. **Development Team**: For SystemMonitor code issues +2. **Infrastructure Team**: For container/Docker issues +3. **Database Team**: For Valkey connectivity problems + +### Emergency Procedures + +**SystemMonitor Down**: + +1. Check container health +2. Restart affected containers +3. Verify Valkey connectivity +4. Check for resource constraints + +**Metrics Not Updating**: + +1. Verify SystemMonitor process running +2. Check Valkey connectivity +3. Review container logs +4. Test manual metric collection + +--- + +## Quick Reference + +### Essential Commands + +```bash +# Development Mode - Restart to pick up changes +docker-compose -f docker-compose.yaml -f docker-compose.dev.yaml restart sirius-engine sirius-ui + +# Production Mode - Rebuild from GitHub source +docker-compose build --no-cache sirius-postgres sirius-rabbitmq sirius-valkey sirius-engine sirius-ui + +# Check SystemMonitor status +docker exec ps aux | grep -E "system-monitor|go run main.go" + +# View metrics in Valkey +docker exec sirius-valkey redis-cli get "system:metrics:" + +# Check container logs for startup mode +docker logs | grep -i "system monitor\|development\|go run" + +# Verify development environment +docker exec env | grep GO_ENV + +# Check for exec format errors +docker logs | grep -i "exec format error" +``` + +### Key Files + +**Source Code:** + +- **SystemMonitor**: `/minor-projects/app-system-monitor/main.go` +- **GitHub Repo**: `https://github.com/SiriusScan/app-system-monitor` + +**Container Integration:** + +- **Engine Startup**: `/sirius-engine/start-enhanced.sh` +- **UI Dev Startup**: `/sirius-ui/start-dev.sh` +- **UI Prod Startup**: `/sirius-ui/start-prod.sh` +- **Other Services**: `//start-with-monitor.sh` + +**Dockerfiles:** + +- **Engine**: `/sirius-engine/Dockerfile` (multi-stage build from GitHub) +- **UI**: `/sirius-ui/Dockerfile` (multi-stage build from GitHub) +- **PostgreSQL**: `/sirius-postgres/Dockerfile` (multi-stage build from GitHub) +- **RabbitMQ**: `/sirius-rabbitmq/Dockerfile` (multi-stage build from GitHub) +- **Valkey**: `/sirius-valkey/Dockerfile` (multi-stage build from GitHub) + +### Monitoring Endpoints + +- **Valkey**: `sirius-valkey:6379` +- **Metrics Key**: `system:metrics:{container_name}` +- **Logs Key**: `system:logs:{container_name}:{timestamp}` + +### Development Mode Indicators + +**Logs showing development mode:** + +``` +Running system monitor with go run (development mode) +go: downloading github.com/SiriusScan/go-api... +System Monitor started with PID: 7 +``` + +**Logs showing production mode:** + +``` +Running system monitor binary (production mode) +System monitor started with PID: 8 +``` + +### Common Issues Quick Fix + +| Issue | Quick Fix | +| --------------------------------- | ----------------------------------------------------------------------------- | +| Exec format error | Rebuild with `docker-compose build ` | +| SystemMonitor not running | Check `docker logs ` for startup errors | +| Metrics not updating | Verify Valkey connection: `docker exec nc -zv sirius-valkey 6379` | +| Container crash loop | Check if scanner failure is bringing down other services | +| Development changes not appearing | Restart container: `docker-compose restart ` | + +--- + +_This documentation covers SystemMonitor v2.1+ with development mode support, CPU drift fixes, and multi-stage Docker builds. For older versions, refer to historical documentation or upgrade to the latest version._ diff --git a/documentation/dev/deployment/README.docker-container-deployment.md b/documentation/dev/deployment/README.docker-container-deployment.md new file mode 100644 index 0000000..19b019c --- /dev/null +++ b/documentation/dev/deployment/README.docker-container-deployment.md @@ -0,0 +1,428 @@ +--- +title: "Docker Container Deployment Guide" +description: "Complete guide for deploying Sirius using prebuilt container images from GitHub Container Registry" +template: "TEMPLATE.guide" +version: "1.0.0" +last_updated: "2026-04-08" +author: "Development Team" +tags: ["docker", "deployment", "containers", "ghcr", "registry", "production"] +categories: ["deployment", "infrastructure"] +difficulty: "beginner" +prerequisites: ["docker", "docker-compose"] +related_docs: + - "README.terraform-deployment.md" + - "README.development.md" + - "README.docker-architecture.md" +dependencies: ["docker-compose.yaml"] +llm_context: "high" +search_keywords: + [ + "docker", + "deployment", + "containers", + "ghcr", + "registry", + "production", + "images", + "compose", + ] +--- + +# Docker Container Deployment Guide + +## Purpose + +This guide explains how to deploy Sirius using prebuilt container images from GitHub Container Registry (GHCR). This approach provides faster deployments (5-8 minutes vs 20-25 minutes) by eliminating on-instance Docker builds. The guide covers production deployments, image versioning, and fallback strategies. + +## When to Use + +- **Production deployments** - Deploying Sirius to production environments +- **Demo environments** - Setting up demo instances quickly +- **Staging environments** - Creating isolated testing environments +- **Quick deployments** - When you need fast deployment without building from source +- **CI/CD pipelines** - Automated deployments using prebuilt images + +**Avoid when**: + +- **Local development** - Use `docker-compose.dev.yaml` for local builds with hot reloading +- **Custom modifications** - When you need to modify source code before deployment +- **Offline environments** - When registry access is unavailable + +## How to Use + +### Quick Start + +```bash +# Clone repository +git clone https://github.com/SiriusScan/Sirius.git +cd Sirius + +# Generate startup config and secrets +docker compose -f docker-compose.installer.yaml run --rm sirius-installer + +# Deploy with prebuilt images (default) +docker compose up -d + +# Or specify a version tag +IMAGE_TAG=v0.4.1 docker compose up -d + +# Optional: verify the public GHCR contract before pulling +bash scripts/verify-ghcr-public-access.sh "${IMAGE_TAG:-latest}" +``` + +### Prerequisites + +- **Docker** >= 20.10.0 +- **Docker Compose** >= 2.0.0 +- **Internet access** to GitHub Container Registry (ghcr.io) +- **Git** (for cloning repository) + +## Container Registry Integration + +### GitHub Container Registry (GHCR) + +Sirius images are automatically built and pushed to GitHub Container Registry on every push to the main branch. Images are available at: + +- **UI**: `ghcr.io/siriusscan/sirius-ui:{tag}` +- **API**: `ghcr.io/siriusscan/sirius-api:{tag}` +- **Engine**: `ghcr.io/siriusscan/sirius-engine:{tag}` +- **Postgres**: `ghcr.io/siriusscan/sirius-postgres:{tag}` +- **RabbitMQ**: `ghcr.io/siriusscan/sirius-rabbitmq:{tag}` +- **Valkey**: `ghcr.io/siriusscan/sirius-valkey:{tag}` + +`docker-compose.yaml` is the public-image deployment path for Sirius. If an unauthenticated `docker pull` against one of the image refs above returns `unauthorized`, the GHCR public-visibility contract is broken and operators should stop before rollout. + +### Image Tagging Strategy + +Images are tagged with the following strategy: + +| Tag | Description | When Created | +| -------- | ------------------------ | ----------------------- | +| `latest` | Latest main branch build | On every push to main | +| `beta` | Beta release candidate | On main branch pushes | +| `v0.4.1` | Version-specific tag | After the `Publish Release Image Tags` workflow succeeds | +| `dev` | Development builds | On other branch pushes | +| `pr-123` | Pull request builds | On PR creation/updates | + +### Image Availability + +- **Public images**: No authentication required +- **Multi-architecture**: Images support `linux/amd64` and `linux/arm64` +- **Automatic updates**: Latest images are built automatically by CI/CD +- **Release contract**: A release tag is only valid for operators after the release-tag workflow publishes it, the anonymous GHCR verification step passes, and the public Compose smoke test succeeds. CI validates **`latest`** on every main push (`public-stack-contract` in `ci.yml`); **semver** tags are additionally checked when a GitHub Release is published and on a weekly schedule ([`verify-ghcr-release-tag.yml`](../../../.github/workflows/verify-ghcr-release-tag.yml)). + +## Docker Compose Configuration + +### Base Configuration (Production) + +The default `docker-compose.yaml` uses prebuilt images: + +```yaml +services: + sirius-ui: + image: ghcr.io/siriusscan/sirius-ui:${IMAGE_TAG:-latest} + pull_policy: always + # ... other configuration + + sirius-api: + image: ghcr.io/siriusscan/sirius-api:${IMAGE_TAG:-latest} + pull_policy: always + # ... other configuration + + sirius-engine: + image: ghcr.io/siriusscan/sirius-engine:${IMAGE_TAG:-latest} + pull_policy: always + # ... other configuration +``` + +### Environment Variables + +Control which images to use with the `IMAGE_TAG` environment variable: + +```bash +# Use latest images (default) +docker compose up -d + +# Use specific version +IMAGE_TAG=v0.4.1 docker compose up -d + +# Use beta release +IMAGE_TAG=beta docker compose up -d + +# Validate that the selected tag is publicly readable before rollout +bash scripts/verify-ghcr-public-access.sh "${IMAGE_TAG:-latest}" +``` + +`.env.production.example` leaves `IMAGE_TAG` blank so fresh installer runs inherit the Compose default (`latest`). Pin a release tag only after the publish workflow has validated that all six Sirius images exist for that tag. + +### Development Override + +For local development with source code changes, use the development override: + +```bash +# Build locally with hot reloading +docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d --build +``` + +The `docker-compose.dev.yaml` file overrides the registry images with local builds, enabling: + +- Hot reloading +- Volume mounts for source code +- Development-specific environment variables +- Debug logging + +## Deployment Workflow + +### Standard Production Deployment + +1. **Clone repository**: + + ```bash + git clone https://github.com/SiriusScan/Sirius.git + cd Sirius + ``` + +2. **Configure environment**: + + ```bash + docker compose -f docker-compose.installer.yaml run --rm sirius-installer + # Optional: pass explicit values + # docker compose -f docker-compose.installer.yaml run --rm sirius-installer --non-interactive --no-print-secrets + ``` + +3. **Deploy services**: + + ```bash + docker compose up -d + ``` + +4. **Verify deployment**: + + ```bash + docker compose ps + docker compose logs -f + ``` + +5. **Check health**: + ```bash + curl http://localhost:9001/health # API + curl http://localhost:3000/api/health # UI + ``` + +### Maintainer Validation Path + +Use the shared validation script to exercise the same public Compose path that operators use: + +```bash +# Validate the default public stack (latest) +bash scripts/validate-public-compose-path.sh latest + +# Validate a published release tag +bash scripts/validate-public-compose-path.sh v0.4.1 +``` + +### Version-Specific Deployment + +Deploy a specific version: + +```bash +# Set version tag +export IMAGE_TAG=v0.4.1 + +# Confirm the compose-rendered GHCR images are public and readable +bash scripts/verify-ghcr-public-access.sh "$IMAGE_TAG" + +# Pull and start services +docker compose pull +docker compose up -d +``` + +### Updating Deployment + +To update to the latest version: + +```bash +# Pull latest images +docker compose pull + +# Restart services with new images +docker compose up -d +``` + +## Fallback Strategy + +### When Registry is Unavailable + +If GitHub Container Registry is unavailable or images fail to pull, you can fall back to local builds: + +1. **Use the committed source-build override**: + + ```bash + docker compose -f docker-compose.yaml -f docker-compose.build.yaml up -d --build + ``` + +**Note**: Local builds take significantly longer (20-25 minutes vs 5-8 minutes) and require more system resources. + +## Secrets Hardening Overlays + +For hardened deployments, Sirius includes optional overlay manifests: + +- `docker-compose.secrets.yaml` for Compose secrets mounted at `/run/secrets/*` +- `docker-stack.swarm.yaml` for Swarm stack deployments + +Example: + +```bash +mkdir -p secrets +printf '%s' "your-postgres-password" > secrets/postgres_password.txt +printf '%s' "your-service-key" > secrets/sirius_api_key.txt +chmod 644 secrets/sirius_api_key.txt +printf '%s' "your-nextauth-secret" > secrets/nextauth_secret.txt +printf '%s' "your-admin-password" > secrets/initial_admin_password.txt + +docker compose -f docker-compose.yaml -f docker-compose.secrets.yaml up -d +``` + +`sirius_api_key.txt` should stay **world-readable** (`644`) so bind-mounted `/run/secrets/sirius_api_key` is readable inside **sirius-api** / **sirius-ui** / **sirius-engine** (non-root UIDs). + +## Troubleshooting + +### Images Not Pulling + +**Problem**: `docker compose pull` fails with authentication or network errors. + +**Solutions**: + +- Verify internet connectivity: `curl -I https://ghcr.io` +- Check image exists: Visit `https://github.com/SiriusScan/Sirius/pkgs/container/sirius-ui` +- Try pulling manually: `docker pull ghcr.io/siriusscan/sirius-ui:latest` +- Run the contract check: `bash scripts/verify-ghcr-public-access.sh "${IMAGE_TAG:-latest}"` +- If the script reports `Anonymous access denied`, the package is not publicly readable and the GHCR visibility workflow or token scope needs attention +- If the script reports `Manifest missing`, the requested tag was not published and you should verify the release-tag workflow completed successfully +- If the public Compose smoke test fails after pull succeeds, run `bash scripts/validate-public-compose-path.sh "${IMAGE_TAG:-latest}"` to reproduce the operator path and inspect the runtime contract failure +- Use fallback build strategy (see above) + +### Wrong Version Deployed + +**Problem**: Services are running an unexpected version. + +**Solutions**: + +- Check current IMAGE_TAG: `echo $IMAGE_TAG` +- Verify image tags: `docker compose images` +- Pull specific version: `IMAGE_TAG=v0.4.1 docker compose pull` +- Restart services: `docker compose up -d` + +### Services Not Starting + +**Problem**: Containers fail to start after pulling images. + +**Solutions**: + +- Check logs: `docker compose logs` +- Verify environment variables: `docker compose config` +- Check image compatibility: Ensure architecture matches (amd64/arm64) +- Verify dependencies: Ensure PostgreSQL, RabbitMQ, Valkey are running + +### Performance Issues + +**Problem**: Deployment is slower than expected. + +**Solutions**: + +- Check network speed: `docker pull` should be fast on good connections +- Verify image sizes: Large images take longer to pull +- Use specific version tags instead of `latest` for faster pulls +- Consider using image caching strategies + +## Best Practices + +### Security + +- **Use specific version tags** in production (e.g., `v0.4.1`) instead of `latest` +- **Regularly update images** to get security patches +- **Scan images** for vulnerabilities using Docker security scanning +- **Use private registries** for sensitive deployments (if needed) + +### Version Management + +- **Pin versions** in production environments +- **Test updates** in staging before production +- **Document versions** deployed in each environment +- **Use semantic versioning** for releases + +### Performance + +- **Pre-pull images** before deployment to reduce startup time +- **Use image caching** to avoid redundant pulls +- **Monitor image sizes** and optimize Dockerfiles if needed +- **Use multi-stage builds** to reduce final image sizes + +### Monitoring + +- **Track deployment times** to measure improvements +- **Monitor registry availability** and fallback usage +- **Log image versions** deployed for audit trails +- **Alert on deployment failures** for quick response + +## Comparison: Registry vs Local Builds + +| Aspect | Registry Images | Local Builds | +| --------------------- | ----------------- | -------------------- | +| **Deployment Time** | 5-8 minutes | 20-25 minutes | +| **Resource Usage** | Low (pull only) | High (compilation) | +| **Network Required** | Yes (for pull) | No (after clone) | +| **Customization** | Limited | Full | +| **CI/CD Integration** | Automatic | Manual | +| **Best For** | Production, demos | Development, offline | + +## Integration with CI/CD + +### GitHub Actions + +Images are automatically built and pushed by GitHub Actions on: + +- Push to `main` branch → `latest` and `beta` tags +- Manual `Publish Release Image Tags` run → version-specific tag (e.g., `v0.4.1`) +- Pull requests → `pr-{number}` tags + +### Deployment Automation + +Example GitHub Actions workflow for deployment: + +```yaml +name: Deploy Sirius +on: + push: + branches: [main] + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Deploy with registry images + run: | + docker compose pull + docker compose up -d +``` + +## Related Documentation + +- [Terraform Deployment Guide](README.terraform-deployment.md) - AWS deployment using Terraform +- [Development Guide](../README.development.md) - Local development setup +- [Docker Architecture Guide](../architecture/README.docker-architecture.md) - Container architecture details + +## Support + +For issues with container deployment: + +1. Check the troubleshooting section above +2. Review Docker logs: `docker compose logs` +3. Verify image availability on GitHub Container Registry +4. Create an issue in the Sirius repository + +--- + +_This guide follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/deployment/README.workflows.md b/documentation/dev/deployment/README.workflows.md new file mode 100644 index 0000000..72997fa --- /dev/null +++ b/documentation/dev/deployment/README.workflows.md @@ -0,0 +1,464 @@ +--- +title: "GitHub Actions Workflow Architecture" +description: "Comprehensive guide to Sirius CI/CD pipeline structure, parallel build jobs, and deployment workflows" +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-11-14" +author: "Sirius Team" +tags: ["ci-cd", "github-actions", "docker", "ghcr", "parallel-builds"] +categories: ["deployment", "automation"] +difficulty: "intermediate" +prerequisites: ["README.docker-container-deployment.md", "README.architecture.md"] +related_docs: + - "README.docker-container-deployment.md" + - "README.terraform-deployment.md" + - "README.cicd.md" +dependencies: + - ".github/workflows/ci.yml" +llm_context: "high" +search_keywords: ["ci-cd", "github-actions", "workflow", "parallel", "build", "deploy", "ghcr", "container-registry"] +--- + +# GitHub Actions Workflow Architecture + +## Purpose + +This document describes the Sirius CI/CD pipeline structure, explaining how GitHub Actions workflows orchestrate parallel container builds, validation, testing, and deployment. It's designed for developers maintaining or modifying the CI/CD pipeline and for those troubleshooting build issues. + +## When to Use + +- **Modifying CI/CD pipeline**: Making changes to build, test, or deployment processes +- **Troubleshooting build failures**: Understanding job dependencies and execution order +- **Adding new services**: Integrating new containers into the build pipeline +- **Optimizing build times**: Identifying parallelization opportunities +- **Debugging deployment issues**: Understanding how code reaches production + +## How to Use + +### Quick Reference + +```bash +# Check workflow status +gh run list --workflow=ci.yml --limit 5 + +# Watch current run +gh run watch + +# View workflow logs +gh run view --log + +# Manually trigger workflow +gh workflow run ci.yml --ref main +``` + +### Understanding Workflow Execution + +1. **Code Push/PR**: Triggers the workflow automatically +2. **Change Detection**: Determines which services need rebuilding +3. **Parallel Builds**: UI, API, and Engine build concurrently +4. **Integration Tests**: Validates built images work together +5. **Deployment Dispatch**: Triggers downstream deployments + +## What It Is + +### Workflow Overview + +The Sirius CI/CD pipeline is implemented in `.github/workflows/ci.yml` and follows a **parallel build architecture** that significantly reduces build times compared to sequential builds. + +**Other workflows** (not shown in the diagram below): + +- [`.github/workflows/publish-release-image-tags.yml`](../../../.github/workflows/publish-release-image-tags.yml) — manual retag of all six GHCR images from a source tag (e.g. `latest`) to a release tag (e.g. `v1.0.0`). +- [`.github/workflows/verify-ghcr-release-tag.yml`](../../../.github/workflows/verify-ghcr-release-tag.yml) — on each **published** GitHub Release, on a **weekly** schedule, and via **workflow_dispatch**, runs `scripts/verify-ghcr-public-access.sh` so the release tag cannot drift from what anonymous operators can pull (see [OPERATIONS.md](../../../OPERATIONS.md) GHCR checklist). + +**Key characteristics:** + +- **Parallel execution**: UI, API, and Engine containers build simultaneously +- **Smart change detection**: Only rebuilds services with code changes +- **Prebuild validation**: Runs lints/tests before expensive Docker builds +- **Multi-arch support**: Builds for both amd64 and arm64 architectures +- **Container registry integration**: Pushes to GitHub Container Registry (GHCR) + +### Architecture Diagram + +``` +┌─────────────────┐ +│ detect-changes │ ← Determines what needs rebuilding +└────────┬────────┘ + │ + ├──────────┬──────────┬──────────┐ + ▼ ▼ ▼ ▼ + ┌────────┐ ┌────────┐ ┌──────────┐ │ + │build-ui│ │build-api│ │build-engine│ │ ← Run in parallel + └───┬────┘ └───┬────┘ └─────┬────┘ │ + │ │ │ │ + └──────────┴────────────┴─────────┘ + │ + ▼ + ┌────────┐ + │ test │ ← Integration testing + └───┬────┘ + │ + ┬─────────┴─────────┬ + ▼ ▼ +┌───────────────┐ ┌──────────────┐ +│dispatch-demo- │ │dispatch-demo-│ +│ deployment │ │ canary │ +└───────────────┘ └──────────────┘ +``` + +## Workflow Jobs + +### 1. detect-changes + +**Purpose**: Analyzes commits to determine which services need rebuilding. + +**Triggers on**: +- Direct pushes to `main` or `sirius-demo` branches +- Pull requests to `main` +- Repository dispatch events (submodule updates) + +**Outputs**: +- `sirius_ui_changes`: Boolean indicating UI code changes +- `sirius_api_changes`: Boolean indicating API code changes +- `sirius_engine_changes`: Boolean indicating Engine code changes +- `submodule_changes`: Boolean indicating submodule updates + +**Change detection logic**: +```yaml +# UI changes: Any file in sirius-ui/ +# API changes: Any file in sirius-api/ +# Engine changes: Any file in sirius-engine/ or rabbitmq/ +# Global changes: Dockerfile, docker-compose, .github/ → rebuild all +``` + +### 2. build-ui (Parallel) + +**Purpose**: Validates and builds the Next.js UI container. + +**Runs when**: `detect-changes.outputs.sirius_ui_changes == 'true'` + +**Steps**: +1. **Generate metadata**: Determines image tag (`latest`, `beta`, `pr-*`) +2. **Validate UI code**: Runs `npm ci && npm run lint` +3. **Set up Docker Buildx**: Configures multi-arch builds +4. **Log in to GHCR**: Authenticates with container registry +5. **Build and push**: Creates and pushes amd64/arm64 images + +**Output**: `image_tag` (e.g., `latest`, `beta`, `pr-123`) + +**Build platforms**: `linux/amd64`, `linux/arm64` + +**Validation timing**: ~2-3 minutes (lint before Docker build) + +### 3. build-api (Parallel) + +**Purpose**: Validates and builds the Go API container. + +**Runs when**: `detect-changes.outputs.sirius_api_changes == 'true'` + +**Steps**: +1. **Generate metadata**: Determines image tag and submodule SHAs +2. **Set up Go**: Installs Go 1.24 +3. **Validate API code**: Runs `go mod download && go test ./...` +4. **Set up Docker Buildx**: Configures multi-arch builds +5. **Log in to GHCR**: Authenticates with container registry +6. **Build and push**: Creates and pushes amd64/arm64 images with submodule refs + +**Output**: `image_tag` + +**Build args**: `GO_API_COMMIT_SHA` (for go-api submodule) + +**Validation timing**: ~1-2 minutes (tests before Docker build) + +### 4. build-engine (Parallel) + +**Purpose**: Validates and builds the Go Engine container. + +**Runs when**: `detect-changes.outputs.sirius_engine_changes == 'true'` + +**Steps**: +1. **Generate metadata**: Determines image tag and all submodule SHAs +2. **Set up Go**: Installs Go 1.24 +3. **Validate Engine code**: Runs `go mod download && go test ./...` +4. **Set up Docker Buildx**: Configures multi-arch builds +5. **Log in to GHCR**: Authenticates with container registry +6. **Build and push**: Creates and pushes amd64/arm64 images with all submodule refs + +**Output**: `image_tag` + +**Build args**: +- `GO_API_COMMIT_SHA` +- `APP_SCANNER_COMMIT_SHA` +- `APP_TERMINAL_COMMIT_SHA` +- `SIRIUS_NSE_COMMIT_SHA` +- `APP_AGENT_COMMIT_SHA` + +**Validation timing**: ~1-2 minutes (tests before Docker build) + +### 5. test + +**Purpose**: Validates that built containers work together in an integrated environment. + +**Runs when**: At least one build job succeeds + +**Dependencies**: `[detect-changes, build-ui, build-api, build-engine]` + +**Steps**: +1. **Determine image tag**: Uses output from whichever build job ran +2. **Create test environment**: Generates `docker-compose.test.yml` with fresh images +3. **Start infrastructure**: Launches Postgres, RabbitMQ, Valkey +4. **Start application services**: Launches only the services that were built +5. **Run smoke tests**: Validates services are running and responsive +6. **Cleanup**: Tears down test environment + +**Test configuration**: +- Uses in-memory Postgres (`tmpfs`) for speed +- Isolated test database (`sirius_test`) +- Debug-level logging for troubleshooting + +### 6. dispatch-demo-deployment + +**Purpose**: Triggers deployment to the demo environment when `sirius-demo` branch updates. + +**Runs when**: Push to `sirius-demo` branch after successful build + test + +**Dependencies**: `[detect-changes, build-ui, build-api, build-engine, test]` + +**Sends to**: `SiriusScan/sirius-demo` repository with event type `sirius-demo-updated` + +**Payload includes**: +- Source repo/branch/SHA +- Triggering actor +- Commit message + +### 7. dispatch-demo-canary + +**Purpose**: Triggers demo rebuild on every `main` branch push as a deployment canary. + +**Runs when**: Push to `main` branch after successful build + test + +**Dependencies**: `[detect-changes, build-ui, build-api, build-engine, test]` + +**Sends to**: `SiriusScan/sirius-demo` repository with event type `sirius-main-updated` + +**Purpose of canary**: Catches bad commits to `main` by immediately deploying to demo environment + +## Image Tagging Strategy + +### Tag Types + +**`latest`**: +- Pushed on every `main` branch commit +- Also tagged as `beta` simultaneously +- Used by default in `docker-compose.yaml` + +**`beta`**: +- Alias for `latest` (same image) +- Explicitly labeled for beta testing + +**`pr-{number}`**: +- Unique tag for pull request builds +- Enables testing PRs in isolation + +**`dev`**: +- Fallback for other branches/events + +### Tag Determination + +```bash +# Pull request +TAG="pr-123" + +# Push to main or repository_dispatch +TAG="latest" +also_tag_beta="true" + +# Other events +TAG="dev" +``` + +## Prebuild Validation + +Each build job runs validation **before** Docker builds to fail fast and save time. + +### UI Validation + +```bash +cd sirius-ui +npm ci # Install dependencies +npm run lint # ESLint validation +# Docker build only if lint succeeds +``` + +**Typical duration**: 2-3 minutes +**Catches**: Import errors, syntax issues, unused variables + +### API Validation + +```bash +cd sirius-api +go mod download # Download dependencies +go test ./... -v # Run tests +# Docker build only if tests pass +``` + +**Typical duration**: 1-2 minutes +**Catches**: Compilation errors, failing tests, import issues + +### Engine Validation + +```bash +cd sirius-engine +go mod download # Download dependencies +go test ./... -v # Run tests +# Docker build only if tests pass +``` + +**Typical duration**: 1-2 minutes +**Catches**: Compilation errors, failing tests, integration issues + +## Timing Expectations + +### Before Parallelization (Sequential Builds) + +| Phase | Duration | +|-------|----------| +| Change detection | ~30s | +| Build UI | ~15-20 min | +| Build API | ~20-25 min | +| Build Engine | ~30-40 min | +| Test | ~5 min | +| **Total** | **~70-90 min** | + +### After Parallelization (Current) + +| Phase | Duration | +|-------|----------| +| Change detection | ~30s | +| Prebuild validation (all parallel) | ~2-3 min | +| Build UI, API, Engine (all parallel) | ~30-40 min (longest wins) | +| Test | ~5 min | +| **Total** | **~40-50 min** | + +**Time savings**: ~40-60% reduction (30-40 minutes faster) + +## Authentication & Secrets + +### Required Secrets + +**`GHCR_PUSH_USER`**: GitHub username that generated the PAT +**`GHCR_PUSH_TOKEN`**: GitHub Personal Access Token with scopes: +- `write:packages` (push images) +- `read:packages` (pull existing layers) +- `delete:packages` (cleanup, optional) +- `repo` (access repository context) + +**`GITHUB_TOKEN`**: Automatically provided by GitHub Actions +- Used for repository dispatch events +- Has limited package permissions (read-only) + +### Setting Up Secrets + +```bash +# Repository secrets (Sirius repo) +Settings → Security → Secrets and variables → Actions + +# Add GHCR_PUSH_USER (your GitHub username) +Name: GHCR_PUSH_USER +Value: your-username + +# Add GHCR_PUSH_TOKEN (PAT with package scopes) +Name: GHCR_PUSH_TOKEN +Value: ghp_xxxxxxxxxxxx +``` + +## Troubleshooting + +### Build Fails with "denied: installation not allowed" + +**Cause**: Default `GITHUB_TOKEN` doesn't have package creation permission. + +**Fix**: Use PAT-based authentication (already implemented with `GHCR_PUSH_USER`/`GHCR_PUSH_TOKEN`). + +### Build Fails with "403 Forbidden" during push + +**Cause**: PAT missing required scopes or package visibility is restricted. + +**Fix**: +1. Verify PAT has `write:packages` and `read:packages` scopes +2. Check package is public: `https://github.com/orgs/SiriusScan/packages/container/sirius-{ui,api,engine}/settings` +3. Set visibility to Public (one-time change) + +### Test job fails to pull images + +**Cause**: Image tag mismatch or build job didn't complete. + +**Fix**: +1. Check build job outputs: `needs.build-{ui,api,engine}.outputs.image_tag` +2. Verify images exist in GHCR: `https://github.com/orgs/SiriusScan/packages` +3. Check GHCR authentication in test job + +### Dispatch jobs don't trigger downstream + +**Cause**: Missing `GITHUB_TOKEN` permission or incorrect event type. + +**Fix**: +1. Verify `GITHUB_TOKEN` has workflow permissions +2. Check downstream repo workflow listens for correct event type +3. Confirm payload format matches expectations + +### Builds take longer than expected + +**Expected timings** (parallel mode): +- Prebuild validation: 2-3 min +- Docker builds: 30-40 min (longest service) +- Integration test: 5 min + +**Investigate if**: +- Build cache not working (check `cache-from: type=gha`) +- Network issues downloading dependencies +- Jobs running sequentially instead of parallel + +## Best Practices + +### When Modifying Workflows + +1. **Test in PR first**: Use `pr-*` tags to test changes without affecting `latest` +2. **Preserve outputs**: Build jobs must output `image_tag` for downstream jobs +3. **Use `always()`**: Downstream jobs should use `always()` with result checks +4. **Validate locally**: Use `act` (GitHub Actions local runner) when possible +5. **Check syntax**: Run `actionlint` before committing + +### Adding New Services + +1. **Create build job**: Copy pattern from `build-ui/api/engine` +2. **Add change detection**: Update `detect-changes` job logic +3. **Update test job**: Add service to `docker-compose.test.yml` +4. **Update dispatch dependencies**: Include new job in `needs` array + +### Optimizing Build Times + +**Already implemented**: +- Parallel builds (saves 40-60%) +- Prebuild validation (fails fast) +- Docker layer caching (`cache-from: type=gha`) +- Multi-arch builds in one step + +**Future opportunities**: +- Cache Go dependencies between runs +- Use `npm ci --prefer-offline` for UI builds +- Split test job into parallel service-specific tests + +## Related Documentation + +- **[README.docker-container-deployment.md](README.docker-container-deployment.md)**: Container registry deployment guide +- **[README.terraform-deployment.md](../operations/README.terraform-deployment.md)**: Terraform-based infrastructure deployment +- **[README.cicd.md](../architecture/README.cicd.md)**: CI/CD architecture overview +- **[README.docker-architecture.md](../architecture/README.docker-architecture.md)**: Docker multi-stage builds and architecture + +## Additional Resources + +- **GitHub Actions Docs**: https://docs.github.com/en/actions +- **Docker Buildx**: https://docs.docker.com/buildx/ +- **GHCR Documentation**: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry + diff --git a/documentation/dev/development/README.logging-conventions.md b/documentation/dev/development/README.logging-conventions.md new file mode 100644 index 0000000..6596efa --- /dev/null +++ b/documentation/dev/development/README.logging-conventions.md @@ -0,0 +1,187 @@ +--- +title: "Logging Conventions" +description: "Project-wide logging standards, level guidelines, and configuration" +template: "TEMPLATE.documentation-standard" +llm_context: "high" +categories: ["development", "standards", "observability"] +tags: ["logging", "slog", "zap", "LOG_LEVEL", "structured-logging"] +related_docs: + - "README.development.md" + - "README.go-api-sdk.md" + - "README.docker-architecture.md" +search_keywords: + - "log level" + - "LOG_LEVEL" + - "slog" + - "zap" + - "structured logging" + - "debug" + - "verbosity" +--- + +# Logging Conventions + +This document defines the project-wide logging standards for all Sirius services. + +## Guiding Principles + +1. **Structured logging only** -- all Go services use `log/slog` (SDK, sirius-api, app-scanner) or `go.uber.org/zap` (app-agent). Raw `log.Print*` and `fmt.Print*` are not used for service logging. +2. **Level-gated output** -- every service reads the `LOG_LEVEL` environment variable at startup. Only messages at or above the configured level are emitted. +3. **No sensitive data** -- connection strings, credentials, tokens, and full request/response bodies must never appear in logs. +4. **No debug dumps** -- printing entire structs (e.g., `%+v` on a host or vulnerability object) is prohibited. Log only the identifying fields needed for correlation (IP, ID, name). +5. **CLI output is separate** -- user-facing CLI tools (e.g., `template-cli`) use `fmt.Print*` for deliberate terminal output. This is distinct from service logging. + +## LOG_LEVEL Configuration + +### Supported Values + +| Value | Description | +| ------- | -------------------------------------------------------- | +| `debug` | Everything, including per-host scan phases and cache ops | +| `info` | Startup, significant events, scan-level progress | +| `warn` | Non-fatal issues, degraded behavior, retries | +| `error` | Failures that affect results or require attention | + +Default: **`info`** (when `LOG_LEVEL` is unset or unrecognized). + +### Per-Environment Defaults + +| Environment | `sirius-api` | `sirius-engine` (scanner) | `app-agent` | +| ------------------------------------------- | :----------: | :-----------------------: | :---------: | +| **Production** (`docker-compose.yaml`) | `error` | `info` | `info` | +| **Development** (`docker-compose.dev.yaml`) | `info` | `info` | `info` | + +To temporarily enable debug output during development, override in `docker-compose.dev.yaml` or pass as an environment variable: + +```bash +LOG_LEVEL=debug docker compose -f docker-compose.dev.yaml up +``` + +## Shared Initialization Helpers + +### SDK (slog) -- `go-api/sirius/slogger` + +Used by `sirius-api` and `app-scanner`. Call once at the top of `main()`: + +```go +import "github.com/SiriusScan/go-api/sirius/slogger" + +func main() { + slogger.Init() // configures slog.SetDefault() from LOG_LEVEL + // ... +} +``` + +Helper functions: + +- `slogger.Level()` -- returns the current `slog.Level` +- `slogger.IsDebug()` -- returns true when debug logging is active + +### app-agent (zap) -- `internal/config` + +```go +import "github.com/SiriusScan/app-agent/internal/config" + +func main() { + logger := config.NewLogger() // reads LOG_LEVEL, returns *zap.Logger + defer logger.Sync() + // ... +} +``` + +## Level Assignment Guidelines + +### Debug + +Use for output that is only useful when actively investigating a specific issue: + +- Per-host scan phase progress (`Phase 0: Fingerprinting on 10.0.0.1`) +- Individual host submission confirmations +- Cache hit/miss details +- Queue message bodies +- HID generation, version detection +- Periodic flush counts + +### Info + +Use for meaningful, scan-level or service-level events: + +- Service startup and configuration +- Scan started / scan completed (aggregate) +- Template resolution +- Significant state transitions + +### Warn + +Use when something unexpected happened but the service can continue: + +- Failed to sync NSE scripts (will retry) +- Host appears to be down (skipping) +- Failed to update KV store with discovery data +- Deprecated configuration detected + +### Error + +Use when a requested operation failed: + +- Failed to create KV store connection +- Invalid scan message (cannot be processed) +- Template not found +- Database query failures +- API submission failures + +## Structured Key-Value Pairs + +Always use structured fields instead of string interpolation: + +```go +// Good +slog.Info("Scan completed", "scan_id", scanID, "hosts", hostCount, "vulns", vulnCount) + +// Bad +slog.Info(fmt.Sprintf("Scan %s completed: %d hosts, %d vulns", scanID, hostCount, vulnCount)) +``` + +### Common Field Names + +Use consistent field names across the project: + +| Field | Description | +| ------------- | ------------------- | +| `error` | Error value | +| `ip` | Host IP address | +| `scan_id` | Scan identifier | +| `host_count` | Number of hosts | +| `template_id` | Template identifier | +| `queue` | Queue name | +| `duration` | Operation duration | +| `port_count` | Number of ports | +| `script_id` | Script identifier | + +## Anti-Patterns + +### Do Not + +- Use `log.Panicln` or `log.Fatalf` in HTTP handlers (return proper error responses instead) +- Log entire structs with `%+v` or `%#v` +- Log connection strings or credentials +- Use emoji in structured log messages (level already conveys severity) +- Use `fmt.Printf` for service-level logging (only for CLI user output) +- Create per-request loggers unless adding request-scoped context + +### Exceptions + +- `log.Fatalf` is acceptable in `main()` for unrecoverable startup errors (e.g., cannot connect to database) +- `fmt.Print*` is correct for CLI tools that produce user-facing terminal output +- Test files may use `t.Log` / `t.Logf` freely + +## Migration Checklist + +When working on a Go file that still uses `log.Print*` or `fmt.Printf` for logging: + +1. Replace `"log"` import with `"log/slog"` +2. Convert `log.Printf("message: %s", val)` to `slog.Info("message", "key", val)` +3. Choose the correct level (see guidelines above) +4. Remove any `%+v` struct dumps +5. Remove emoji from log messages +6. Verify no sensitive data is logged diff --git a/documentation/dev/development/README.sirius-event-log.md b/documentation/dev/development/README.sirius-event-log.md new file mode 100644 index 0000000..5704803 --- /dev/null +++ b/documentation/dev/development/README.sirius-event-log.md @@ -0,0 +1,53 @@ +--- +title: "Sirius Event Log System" +description: "Documentation for the Sirius event logging system and event management" +template: "TEMPLATE.documentation-standard" +llm_context: "medium" +categories: ["development", "logging"] +tags: ["events", "logging", "monitoring"] +related_docs: + - "README.system-monitor.md" + - "README.architecture.md" +--- + +# Sirius Event Log System + +This document describes the Sirius event logging system and how events are managed throughout the application. + +## Overview + +The Sirius event log system provides comprehensive event tracking and logging capabilities for monitoring system activities, user actions, and system events. + +## Event Types + +- **System Events**: Container health, service status, resource usage +- **User Events**: Authentication, authorization, user actions +- **Application Events**: API calls, database operations, external service interactions +- **Security Events**: Failed login attempts, permission violations, suspicious activities + +## Event Structure + +Events follow a standardized format with: + +- Timestamp +- Event type and category +- Source service/component +- Event data and metadata +- Severity level + +## Storage and Retrieval + +Events are stored in Valkey for fast access and retrieval, with configurable retention policies. + +## Integration + +The event log system integrates with: + +- System monitoring dashboard +- Log viewer components +- Alerting and notification systems +- Audit and compliance reporting + +## Configuration + +[Configuration details to be documented] diff --git a/documentation/dev/development/README.ui-style-guide.md b/documentation/dev/development/README.ui-style-guide.md new file mode 100644 index 0000000..2da54d8 --- /dev/null +++ b/documentation/dev/development/README.ui-style-guide.md @@ -0,0 +1,1104 @@ +--- +title: "Sirius UI Style Guide" +description: "Comprehensive design system documentation for Sirius 0.4.0 UI, including colors, typography, spacing, components, and design patterns. This guide serves as the authoritative reference for all teams working on Sirius-related projects." +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Sirius Development Team" +tags: ["ui", "design-system", "style-guide", "components", "tailwind", "shadcn"] +categories: ["development", "ui-design"] +difficulty: "intermediate" +prerequisites: ["tailwindcss", "react", "typescript"] +related_docs: + - "README.development.md" + - "ABOUT.documentation.md" +dependencies: + - "sirius-ui/tailwind.config.ts" + - "sirius-ui/src/styles/globals.css" + - "sirius-ui/src/pages/dashboard.tsx" + - "sirius-ui/src/pages/scanner.tsx" +llm_context: "high" +search_keywords: + [ + "sirius ui style guide", + "design system", + "violet theme", + "dark mode", + "shadcn components", + "tailwind config", + "component patterns", + "design tokens", + ] +--- + +# Sirius UI Style Guide + +## Purpose + +This document defines the comprehensive design system for Sirius UI version 0.4.0. It serves as the authoritative reference for developers, designers, and teams working on Sirius-related projects. The style guide documents colors, typography, spacing, components, animations, and design patterns used throughout the Sirius UI. + +This guide focuses exclusively on the 0.4.0 design system, using the dashboard and scanner pages as exemplars of the current style. It provides clear guidance on how to implement consistent UI components and patterns that match the Sirius brand identity. + +## When to Use + +- **Before starting new UI development** - Understand the design system first +- **When creating new components** - Ensure consistency with existing patterns +- **When styling new pages** - Reference color, typography, and spacing guidelines +- **When contributing to Sirius projects** - Follow established design patterns +- **During code reviews** - Verify UI implementations match style guide +- **When building component libraries** - Use documented design tokens and patterns +- **For design decisions** - Reference established patterns before creating new ones + +## How to Use + +1. **Start with the Design System Overview** - Understand the 0.4.0 philosophy +2. **Reference Color System** - Use documented colors for consistency +3. **Follow Typography Guidelines** - Use established text styles +4. **Apply Spacing Patterns** - Use documented spacing scale +5. **Use Component Patterns** - Reference ShadCN components and custom patterns +6. **Apply Design Tokens** - Use documented values for borders, shadows, etc. +7. **Reference Examples** - See dashboard.tsx and scanner.tsx for implementation examples + +### Quick Reference + +```bash +# Key files for style reference +sirius-ui/tailwind.config.ts # Color system and animations +sirius-ui/src/styles/globals.css # CSS variables and custom classes +sirius-ui/src/pages/dashboard.tsx # Primary exemplar page +sirius-ui/src/pages/scanner.tsx # Secondary exemplar page +``` + +## What It Is + +### Design System Overview + +The Sirius 0.4.0 UI design system is built on a **dark mode first** philosophy with a distinctive **violet theme**. The design emphasizes: + +- **Glassmorphism effects** - Subtle backdrop blur and transparency +- **Violet accent colors** - Primary brand color throughout the interface +- **High contrast** - Clear visual hierarchy and readability +- **Consistent spacing** - Predictable layout patterns +- **Smooth animations** - Subtle transitions and loading states + +The system uses **ShadCN UI** as the component foundation, customized with Sirius-specific styling. All components are built with **Tailwind CSS** using a carefully defined color palette and design tokens. + +### Color System + +#### Primary Color Palette + +The Sirius UI uses a violet-based color scheme as the primary brand identity: + +**Light Mode Colors** (from `tailwind.config.ts`): + +- `primary`: `#7C3AED` (violet-600) +- `secondary`: `#D8B4FE` (violet-300) +- `background`: `#e5e7eb` (gray-200) +- `paper`: `#F9FAFB` (gray-50) +- `header`: `#8b5cf6` (violet-500) +- `accent`: `#A855F7` (violet-500) +- `text`: `#111827` (gray-900) + +**Dark Mode Colors** (primary focus): + +- `dark-primary`: `#4338CA` (indigo-700) +- `dark-secondary`: `#6D28D9` (violet-700) +- `dark-header`: `#282843` (custom dark violet) +- `dark-paper`: `#6D28D9` (violet-700) +- `dark-background`: `#1c1e30` (custom dark blue-gray) +- `dark-background-to`: `#2f3050` (custom dark blue-gray gradient end) +- `dark-accent`: `#5B21B6` (violet-800) + +#### CSS Variables (from `globals.css`) + +The system uses CSS variables for theming, mapped to Tailwind config: + +**Light Mode Variables**: + +- `--background`: `220, 13%, 100%, 1` (white) +- `--foreground`: `222.2 84% 4.9%` (dark gray) +- `--primary`: `222.2 47.4% 11.2%` (dark blue-gray) +- `--secondary`: `238, 34%, 30%, 1` (dark violet) +- `--muted`: `210 40% 96.1%` (light gray) +- `--accent`: `210 40% 96.1%` (light gray) +- `--destructive`: `0 84.2% 60.2%` (red) +- `--border`: `214.3 31.8% 91.4%` (light gray) +- `--radius`: `0.5rem` + +**Dark Mode Variables**: + +- `--background`: `234, 26%, 15%, 1` (dark blue-gray) +- `--foreground`: `210 40% 98%` (near white) +- `--primary`: `210 40% 98%` (near white) +- `--secondary`: `238, 34%, 30%, 1` (dark violet) +- `--muted`: `217.2 32.6% 17.5%` (dark gray) +- `--accent`: `217.2 32.6% 17.5%` (dark gray) +- `--destructive`: `0 62.8% 30.6%` (dark red) +- `--border`: `217.2 32.6% 17.5%` (dark gray) + +#### Semantic Colors + +**Success States**: + +- Background: `bg-green-950/20` with `border-green-500/30` +- Text: `text-green-400`, `text-green-300` +- Used for: Positive metrics, successful operations + +**Error/Critical States**: + +- Background: `bg-red-500/10` or `bg-red-950/20` with `border-red-500/30` +- Text: `text-red-400`, `text-red-300` +- Used for: Critical alerts, errors, destructive actions + +**Warning States**: + +- Background: `bg-yellow-500/20` with `border-yellow-500/30` +- Text: `text-yellow-400` +- Used for: Warnings, cautionary information + +**Info States**: + +- Background: `bg-blue-500/20` with `border-blue-500/30` +- Text: `text-blue-400` +- Used for: Informational messages + +#### Severity Colors + +Used for vulnerability severity indicators: + +- **Critical**: `bg-red-700`, `text-red-400` (or `bg-red-500/20 text-red-400`) +- **High**: `bg-orange-700`, `text-orange-400` (or `bg-orange-500/20 text-orange-400`) +- **Medium**: `bg-yellow-700`, `text-yellow-400` (or `bg-yellow-500/20 text-yellow-400`) +- **Low**: `bg-green-700`, `text-green-400` (or `bg-green-500/20 text-green-400`) +- **Informational**: `bg-blue-700`, `text-blue-400` (or `bg-blue-500/20 text-blue-400`) + +#### Opacity and Transparency Patterns + +The design system extensively uses opacity for layering and depth: + +- **Borders**: `border-violet-500/20` (20% opacity) - Standard borders +- **Borders (hover)**: `border-violet-500/40` (40% opacity) - Hover states +- **Borders (primary)**: `border-violet-500/30` (30% opacity) - Important sections +- **Backgrounds**: `bg-gray-900/50` (50% opacity) - Card backgrounds +- **Backgrounds (subtle)**: `bg-violet-500/10` (10% opacity) - Accent backgrounds +- **Backgrounds (hover)**: `bg-violet-500/20` (20% opacity) - Interactive hover states +- **Shadows**: `shadow-violet-500/5` (5% opacity) - Subtle glow effects + +### Typography + +#### Font Families + +The Sirius UI uses system font stacks for optimal performance: + +- **Primary**: System default (`-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif`) +- **Monospace**: System monospace for code (`ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace`) + +#### Type Scale + +Text sizes follow Tailwind's default scale: + +- **xs**: `0.75rem` (12px) - Small labels, captions +- **sm**: `0.875rem` (14px) - Body text, form labels, secondary information +- **base**: `1rem` (16px) - Default body text +- **lg**: `1.125rem` (18px) - Section headings, emphasized text +- **xl**: `1.25rem` (20px) - Large headings +- **2xl**: `1.5rem` (24px) - Page section titles +- **3xl**: `1.875rem` (30px) - Page main titles +- **4xl**: `2.25rem` (36px) - Hero headings +- **5xl**: `3rem` (48px) - Large hero values (e.g., dashboard metrics) + +#### Font Weights + +- **thin**: `100` - Not commonly used +- **extralight**: `200` - Not commonly used +- **light**: `300` - Not commonly used +- **normal**: `400` - Default body text +- **medium**: `500` - Emphasized text, labels +- **semibold**: `600` - Section headings, important labels +- **bold**: `700` - Main headings, critical information +- **extrabold**: `800` - Not commonly used +- **black**: `900` - Not commonly used + +#### Text Colors + +**Foreground Colors**: + +- `text-white` - Primary text on dark backgrounds +- `text-foreground` - Semantic foreground (adapts to theme) +- `text-gray-400` - Secondary/muted text +- `text-gray-300` - Tertiary text +- `text-muted-foreground` - Semantic muted text + +**Accent Text Colors**: + +- `text-violet-400` - Primary accent text +- `text-violet-300` - Secondary accent text +- `text-violet-300/70` - Muted accent text (70% opacity) + +**Semantic Text Colors**: + +- `text-red-400` - Error/critical text +- `text-green-400` - Success text +- `text-yellow-400` - Warning text +- `text-blue-400` - Info text + +#### Heading Hierarchy + +**H1** (Page Titles): + +- Size: `text-3xl` (30px) +- Weight: `font-bold` +- Color: `text-white` +- Usage: Main page titles (e.g., "Security Dashboard") + +**H2** (Section Headings): + +- Size: `text-lg` (18px) +- Weight: `font-semibold` +- Color: `text-violet-300` +- Usage: Section titles, card headers + +**H3** (Subsection Headings): + +- Size: `text-base` (16px) or `text-sm` (14px) +- Weight: `font-medium` or `font-semibold` +- Color: `text-violet-300` or `text-white` +- Usage: Subsection titles, card subheadings + +### Spacing & Layout + +#### Spacing Scale + +Sirius UI uses Tailwind's default spacing scale (4px base unit): + +- **xs**: `0.5rem` (8px) - Tight spacing +- **sm**: `1rem` (16px) - Small gaps +- **md**: `1.5rem` (24px) - Medium gaps +- **lg**: `2rem` (32px) - Large gaps +- **xl**: `3rem` (48px) - Extra large gaps + +Common spacing values: + +- `gap-2` (8px) - Tight component spacing +- `gap-3` (12px) - Standard component spacing +- `gap-4` (16px) - Card internal spacing +- `gap-6` (24px) - Section spacing, grid gaps +- `gap-8` (32px) - Large section spacing + +#### Padding Patterns + +**Card Padding**: + +- Standard: `p-6` (24px) - Card content padding +- Compact: `p-4` (16px) - Smaller cards +- Responsive: `p-4 md:p-6` - Adaptive padding + +**Section Padding**: + +- Standard: `px-4 py-6` or `px-6 py-8` - Page sections +- Responsive: `px-4 md:px-6` - Adaptive horizontal padding + +**Component Padding**: + +- Buttons: `px-4 py-2` (default), `px-3` (sm), `px-8` (lg) +- Inputs: `px-3 py-2` - Form inputs +- Badges: `px-2.5 py-0.5` - Small badges + +#### Margin Patterns + +**Section Margins**: + +- `space-y-8` - Vertical spacing between major sections +- `space-y-6` - Vertical spacing between cards +- `space-y-4` - Vertical spacing between related items +- `space-y-2` - Tight vertical spacing + +**Component Margins**: + +- `mb-4` - Standard bottom margin +- `mb-2` - Small bottom margin +- `mt-4` - Standard top margin + +#### Grid System + +**Common Grid Patterns**: + +- `grid-cols-1 md:grid-cols-2` - Two column responsive grid +- `grid-cols-1 md:grid-cols-3` - Three column responsive grid +- `lg:grid-cols-3` - Three column on large screens +- `lg:col-span-2` - Span two columns in three-column grid + +**Grid Gaps**: + +- `gap-6` - Standard grid gap (24px) +- `gap-4` - Tighter grid gap (16px) +- `gap-8` - Larger grid gap (32px) + +#### Container Patterns + +**Page Container**: + +- `container mx-auto` - Centered container with max-width +- `px-4 md:px-6` - Responsive horizontal padding + +**Section Container**: + +- `-mx-4 md:-mx-6` - Negative margins for full-width sections +- `px-4 md:px-6` - Compensating padding + +#### Responsive Breakpoints + +Tailwind's default breakpoints: + +- **sm**: `640px` - Small tablets +- **md**: `768px` - Tablets +- **lg**: `1024px` - Desktops +- **xl**: `1280px` - Large desktops +- **2xl**: `1400px` - Extra large desktops + +**Common Responsive Patterns**: + +- `hidden md:flex` - Hide on mobile, show on tablet+ +- `flex-col md:flex-row` - Stack on mobile, row on tablet+ +- `text-sm md:text-base` - Smaller text on mobile +- `p-4 md:p-6` - Less padding on mobile + +### Components + +#### ShadCN UI Components + +Sirius UI uses ShadCN UI components as the foundation, customized with Sirius-specific styling. + +**Button** (`~/components/lib/ui/button`): + +- **What it is**: A versatile button component with multiple variants and sizes +- **What it does**: Provides consistent button styling and behavior across the UI +- **Variants**: + - `default`: Primary action button (`bg-primary text-white`) + - `destructive`: Destructive actions (`bg-destructive`) + - `outline`: Secondary actions (`border border-input`) + - `secondary`: Secondary actions (`bg-secondary`) + - `ghost`: Tertiary actions (`hover:bg-accent`) + - `link`: Link-style button (`text-primary underline`) +- **Sizes**: `none`, `default` (h-10), `sm` (h-9), `lg` (h-11), `icon` (h-10 w-10) +- **Sirius styling**: Uses violet theme colors, rounded-md borders + +**Card** (`~/components/lib/ui/card`): + +- **What it is**: A container component for grouping related content +- **What it does**: Provides consistent card styling with header, content, and footer sections +- **Components**: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` +- **Sirius styling**: Uses `bg-card` with `border` and `rounded-lg`, often with `backdrop-blur-sm` and opacity + +**Select** (`~/components/lib/ui/select`): + +- **What it is**: A dropdown select component built on Radix UI +- **What it does**: Provides accessible select dropdown functionality +- **Components**: `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem` +- **Sirius styling**: Customized with `border-violet-500/20` and `bg-gray-800/50 backdrop-blur-sm` + +**Dialog** (`~/components/lib/ui/dialog`): + +- **What it is**: A modal dialog component for overlays and confirmations +- **What it does**: Provides accessible modal dialogs with overlay and animations +- **Components**: `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, `DialogDescription` +- **Sirius styling**: Uses `bg-background` with border and shadow, animated transitions + +**Table** (`~/components/lib/ui/table`): + +- **What it is**: A data table component for displaying structured data +- **What it does**: Provides consistent table styling with header, body, and footer sections +- **Components**: `Table`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`, `TableFooter`, `TableCaption` +- **Sirius styling**: Uses semantic colors, hover states with `hover:bg-muted/50` + +**Badge** (`~/components/lib/ui/badge`): + +- **What it is**: A small label component for status indicators +- **What it does**: Displays status, severity, or category information +- **Variants**: `default`, `secondary`, `destructive`, `outline` +- **Sirius styling**: Rounded-full, uses semantic colors, often customized for severity + +**Input** (`~/components/lib/ui/input`): + +- **What it is**: A text input component for forms +- **What it does**: Provides consistent input styling with focus states +- **Sirius styling**: Uses `border-input`, `bg-background`, focus ring with `ring-ring` + +**Tabs** (`~/components/lib/ui/tabs`): + +- **What it is**: A tabbed interface component for organizing content +- **What it does**: Provides tab navigation with active states +- **Components**: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` +- **Sirius styling**: Uses `bg-muted` for tab list, active state with `bg-background` + +**Tooltip** (`~/components/lib/ui/tooltip`): + +- **What it is**: A hover tooltip component for additional information +- **What it does**: Displays contextual information on hover +- **Components**: `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider` +- **Sirius styling**: Uses `bg-popover` with border and shadow, animated appearance + +**Popover** (`~/components/lib/ui/popover`): + +- **What it is**: A popover component for contextual overlays +- **What it does**: Displays additional content in a floating panel +- **Components**: `Popover`, `PopoverTrigger`, `PopoverContent` +- **Sirius styling**: Uses `bg-popover` with border and shadow, animated transitions + +**Skeleton** (`~/components/lib/ui/skeleton`): + +- **What it is**: A loading placeholder component +- **What it does**: Shows animated placeholders while content loads +- **Sirius styling**: Uses `bg-muted` with `animate-pulse`, `rounded-md` + +#### Custom Component Patterns + +**DashboardCard** (`~/components/dashboard/DashboardCard`): + +- **What it is**: A specialized card component for dashboard widgets +- **What it does**: Provides consistent dashboard card styling with header, actions, loading, and error states +- **Features**: Icon support, refresh/settings/expand actions, loading skeletons, error states +- **Styling**: Uses Card component with custom header layout, action buttons + +**DashboardHeroCard** (`~/components/dashboard/DashboardHeroCard`): + +- **What it is**: A prominent metric display card for key dashboard statistics +- **What it does**: Displays large numbers with labels, icons, trends, and CTAs +- **Variants**: `default`, `critical`, `success` - Different color schemes +- **Styling**: Large text (text-5xl), violet/green/red themes, hover glow effects, backdrop blur + +**Scanner Sections** (Custom CSS classes): + +- **`.scanner-section`**: Base scanner section with subtle borders and backdrop blur + - `border border-violet-500/20 rounded-lg bg-gray-900/20 backdrop-blur-sm` + - Subtle shadow with violet accent +- **`.scanner-section-primary`**: Primary interactive scanner section + - `border border-violet-500/30 rounded-lg bg-violet-500/[0.03] backdrop-blur-sm` + - Enhanced shadow with stronger violet accent +- **`.scanner-section-hover`**: Hover state for interactive sections + - Enhanced border and shadow on hover +- **`.scanner-section-padding`**: Standard padding (`p-4 md:p-6`) +- **`.scanner-divider`**: Section divider (`border-t border-violet-500/10 my-6`) + +**Section Headers with Icons**: + +- Pattern: Icon + heading text +- Icon: `h-5 w-5 text-violet-400` or `h-4 w-4 text-violet-400` +- Heading: `text-lg font-semibold text-violet-300` +- Layout: `flex items-center gap-2` + +**Action Buttons and CTAs**: + +- Primary CTA: Violet theme with hover effects +- Secondary: Ghost variant or outline +- Links: `text-violet-400 hover:text-violet-300` with arrow indicator + +### Design Patterns + +#### Card Patterns + +**Glassmorphism Cards**: + +- Background: `bg-gray-900/50` or `bg-gray-800/50` (semi-transparent) +- Border: `border border-violet-500/20` +- Effect: `backdrop-blur-sm` +- Shadow: `shadow-lg shadow-black/20` +- Usage: Primary content cards, dashboard widgets + +**Primary Cards**: + +- Background: `bg-violet-500/[0.03]` (very subtle violet tint) +- Border: `border-violet-500/30` (stronger border) +- Shadow: Enhanced shadow with violet accent +- Usage: Important interactive areas, hero cards + +**Alert Cards**: + +- Success: `bg-green-950/20 border-green-500/30` +- Error: `bg-red-500/10 border-red-500/30` or `bg-red-950/20 border-red-500/30` +- Warning: `bg-yellow-500/20 border-yellow-500/30` +- Usage: Status messages, critical alerts + +#### Section Patterns + +**Standard Section**: + +- Container: `rounded-lg border border-violet-500/20 bg-gray-900/50 p-6 backdrop-blur-sm` +- Spacing: `space-y-8` between sections +- Usage: Content sections, data displays + +**Sticky Header Section**: + +- Container: `sticky top-0 z-30 border-b border-violet-500/20 bg-gray-900/95 backdrop-blur-sm` +- Shadow: `shadow-lg shadow-black/20` +- Usage: Page headers, navigation bars + +**Collapsible Section**: + +- Toggle: Button with chevron icon, `hover:border-violet-500/40` +- Content: Animated reveal with `animate-in fade-in-50` +- Usage: Expandable content, system health monitoring + +#### Header Patterns + +**Page Header** (Glassmorphism): + +- Background: `bg-gray-900/95` (near opaque with blur) +- Border: `border-b border-violet-500/20` +- Effect: `backdrop-blur-sm` +- Shadow: `shadow-lg shadow-black/20` +- Sticky: `sticky top-0 z-30` +- Padding: `px-4 pb-4 pt-6 md:px-6` + +**Section Header**: + +- Layout: `flex items-center gap-2` or `flex items-center justify-between` +- Icon: `h-5 w-5 text-violet-400` +- Title: `text-lg font-semibold text-violet-300` +- Actions: Right-aligned button group + +#### Button Patterns + +**Primary Button**: + +- Variant: `default` or custom violet styling +- Colors: `bg-violet-500/10 hover:bg-violet-500/20` +- Border: `border-violet-500/20` +- Text: `text-violet-400 hover:text-violet-300` + +**Ghost Button** (Icon buttons): + +- Variant: `ghost` +- Size: `h-7 w-7 p-0` for icon-only +- Hover: Subtle background change + +**Action Button Group**: + +- Layout: `flex items-center gap-1` +- Buttons: Small icon buttons (refresh, settings, expand) + +#### Form Patterns + +**Input Fields**: + +- Container: Standard Input component +- Styling: `border-violet-500/20 bg-gray-800/50 backdrop-blur-sm` +- Focus: Ring with `ring-violet-500` + +**Select Dropdowns**: + +- Trigger: `border-violet-500/20 bg-gray-800/50 backdrop-blur-sm` +- Content: `bg-popover` with border and shadow + +#### Table Patterns + +**Data Tables**: + +- Container: Table component with custom styling +- Headers: `text-muted-foreground font-medium` +- Rows: `hover:bg-muted/50` for interactivity +- Borders: Subtle borders between rows + +**Scrollable Tables**: + +- Wrapper: `.scanner-table-wrapper` or `overflow-x-auto` +- Negative margins: `-mx-4 px-4 md:-mx-6 md:px-6` for full-width scrolling + +#### Badge/Status Patterns + +**Severity Badges**: + +- Critical: `bg-red-700 text-white` or `bg-red-500/20 text-red-400` +- High: `bg-orange-700 text-white` or `bg-orange-500/20 text-orange-400` +- Medium: `bg-yellow-700 text-white` or `bg-yellow-500/20 text-yellow-400` +- Low: `bg-green-700 text-white` or `bg-green-500/20 text-green-400` +- Info: `bg-blue-700 text-white` or `bg-blue-500/20 text-blue-400` + +**Status Indicators**: + +- Online: Green accent +- Offline: Gray/muted +- Warning: Yellow/orange accent + +### Animations & Transitions + +#### Custom Animations + +**pulse-slow**: + +- Duration: `3s` +- Easing: `cubic-bezier(0.4, 0, 0.6, 1)` +- Usage: Slow pulsing effects for status indicators + +**shimmer**: + +- Duration: `3s` +- Type: `linear infinite` +- Effect: Background position animation for loading states +- Usage: Loading placeholders, skeleton screens + +**pulse-glow**: + +- Duration: `2s` +- Easing: `ease-in-out infinite` +- Effect: Box shadow pulse with violet glow +- Usage: Interactive elements, hover effects + +**scan-line**: + +- Duration: `2s` +- Easing: `ease-in-out infinite` +- Effect: Vertical line scan animation +- Usage: Scanner interface, loading indicators + +**rotate-subtle**: + +- Duration: `0.3s` +- Easing: `ease-in-out` +- Effect: Subtle rotation and scale +- Usage: Icon animations, hover effects + +**icon-bounce**: + +- Duration: `0.5s` +- Easing: `ease-in-out` +- Effect: Vertical bounce and scale +- Usage: Icon interactions, button presses + +**fade-in-up**: + +- Duration: `0.4s` +- Easing: `ease-out forwards` +- Effect: Fade in with upward motion +- Usage: Content reveals, modal appearances + +#### Transition Patterns + +**Color Transitions**: + +- Standard: `transition-colors duration-200` +- Usage: Hover states, state changes + +**All Transitions**: + +- Standard: `transition-all duration-200` or `duration-300` +- Usage: Complex state changes, card interactions + +**Hover States**: + +- Border: `hover:border-violet-500/40` (increased opacity) +- Background: `hover:bg-violet-500/20` or `hover:bg-gray-900/70` +- Shadow: `hover:shadow-lg hover:shadow-violet-500/5` + +#### Loading States + +**Skeleton Loading**: + +- Component: Skeleton with `animate-pulse` +- Styling: `bg-muted rounded-md` +- Usage: Content placeholders while loading + +**Spinner Loading**: + +- Icon: RefreshCw with `animate-spin` +- Usage: Action feedback, data refreshing + +**Pulse Loading**: + +- Animation: `animate-pulse` +- Usage: Background placeholders + +### Design Tokens Reference + +#### Border Radius + +- **sm**: `0.125rem` (2px) - Small elements +- **md**: `0.375rem` (6px) - Default (calculated as `calc(var(--radius) - 2px)`) +- **lg**: `0.5rem` (8px) - Standard (`var(--radius)`) +- **xl**: `0.75rem` (12px) - Large elements +- **full**: `9999px` - Fully rounded (badges, pills) + +**Common Usage**: + +- Cards: `rounded-lg` +- Buttons: `rounded-md` +- Badges: `rounded-full` or `rounded-md` +- Inputs: `rounded-md` + +#### Shadow Values + +**Standard Shadows**: + +- `shadow-sm`: Small shadow +- `shadow`: Default shadow +- `shadow-md`: Medium shadow +- `shadow-lg`: Large shadow (`0 10px 15px -3px rgba(0, 0, 0, 0.1)`) +- `shadow-xl`: Extra large shadow +- `shadow-2xl`: Very large shadow + +**Custom Shadows**: + +- `shadow-black/20`: Black shadow with 20% opacity +- `shadow-violet-500/5`: Violet glow with 5% opacity +- `shadow-violet-500/10`: Violet glow with 10% opacity + +**Box Shadow Patterns** (from scanner-section): + +- Standard: `0 0 0 1px rgba(139, 92, 246, 0.05) inset, 0 2px 4px rgba(0, 0, 0, 0.3), 0 8px 16px rgba(139, 92, 246, 0.03)` +- Primary: `0 0 0 1px rgba(139, 92, 246, 0.1) inset, 0 2px 4px rgba(0, 0, 0, 0.3), 0 12px 24px rgba(139, 92, 246, 0.08)` + +#### Z-Index Scale + +- **z-10**: Standard elevated content +- **z-20**: Page content layer +- **z-30**: Sticky headers, fixed navigation +- **z-40**: Dropdowns, popovers +- **z-50**: Modals, dialogs, tooltips + +**Common Usage**: + +- Page content: `z-20` +- Sticky headers: `z-30` +- Modals: `z-50` + +#### Backdrop Blur + +- **backdrop-blur-sm**: `4px` - Subtle blur +- **backdrop-blur**: `8px` - Standard blur +- **backdrop-blur-md**: `12px` - Medium blur +- **backdrop-blur-lg**: `16px` - Large blur + +**Common Usage**: + +- Cards: `backdrop-blur-sm` +- Headers: `backdrop-blur-sm` +- Overlays: `backdrop-blur` or `backdrop-blur-md` + +#### Ring/Outline Values + +**Focus Rings**: + +- Standard: `ring-2 ring-ring ring-offset-2` +- Violet accent: `ring-violet-500` +- Usage: Form inputs, buttons, interactive elements + +**Ring Patterns**: + +- `ring-1 ring-violet-500/20`: Subtle ring decoration +- `ring-2 ring-violet-500/40`: Standard focus ring +- `ring-offset-2`: Offset for better visibility + +### Usage Guidelines + +#### When to Use Which Component + +**Buttons**: + +- Use `default` variant for primary actions +- Use `ghost` variant for icon-only actions (refresh, settings) +- Use `outline` variant for secondary actions +- Use `destructive` variant for delete/remove actions + +**Cards**: + +- Use `Card` component for standard content containers +- Use `DashboardCard` for dashboard widgets with actions +- Use `DashboardHeroCard` for prominent metric displays +- Use `.scanner-section` classes for scanner interface sections + +**Badges**: + +- Use standard `Badge` component for general status indicators +- Use custom severity badges for vulnerability severity +- Match badge colors to semantic meaning (red=critical, green=success) + +**Tables**: + +- Use `Table` component for structured data display +- Add hover states for interactive rows +- Use scrollable wrapper for wide tables + +**Forms**: + +- Use `Input` component for text inputs +- Use `Select` component for dropdowns +- Use `Label` component for form labels +- Group related fields with consistent spacing + +#### Best Practices + +**Color Usage**: + +- Always use violet theme colors for primary actions and accents +- Use semantic colors (red, green, yellow, blue) for status indicators +- Maintain consistent opacity levels (20%, 30%, 40% for borders) +- Use dark backgrounds (`gray-900`, `gray-800`) with transparency + +**Spacing**: + +- Use consistent spacing scale (4px base unit) +- Maintain visual rhythm with `space-y-*` utilities +- Use responsive spacing (`p-4 md:p-6`) +- Group related elements with smaller gaps + +**Typography**: + +- Use `text-white` for primary text on dark backgrounds +- Use `text-violet-300` or `text-violet-400` for accents +- Use `text-gray-400` for secondary/muted text +- Maintain clear hierarchy with size and weight + +**Components**: + +- Always use ShadCN components as base, customize with Sirius styling +- Follow established patterns from dashboard and scanner pages +- Maintain consistency with existing component usage +- Use semantic HTML and accessibility features + +**Animations**: + +- Use subtle transitions (`duration-200` or `duration-300`) +- Apply animations sparingly for important interactions +- Use loading states (skeleton, spinner) for async operations +- Respect user preferences for reduced motion + +#### Common Patterns + +**Card with Header and Actions**: + +```tsx + + + + + Title + +
+ +
+ + ... + +``` + +**Section with Icon Header**: + +```tsx +
+
+ +

Section Title

+
+ {/* Content */} +
+``` + +**Interactive Button with Hover**: + +```tsx + +``` + +#### Anti-Patterns to Avoid + +**Color Anti-Patterns**: + +- Don't use arbitrary colors outside the defined palette +- Don't mix light and dark mode colors incorrectly +- Don't use full opacity borders (always use opacity for depth) +- Don't use colors that don't match semantic meaning + +**Spacing Anti-Patterns**: + +- Don't use arbitrary spacing values (stick to scale) +- Don't mix spacing units (use Tailwind classes) +- Don't create inconsistent gaps between related elements +- Don't forget responsive spacing adjustments + +**Component Anti-Patterns**: + +- Don't create custom components when ShadCN equivalents exist +- Don't override ShadCN component styles unnecessarily +- Don't skip accessibility features (focus states, ARIA labels) +- Don't use inline styles when Tailwind classes work + +**Animation Anti-Patterns**: + +- Don't use excessive animations that distract from content +- Don't animate everything (use selectively) +- Don't ignore reduced motion preferences +- Don't use animations that don't serve a purpose + +### Examples + +#### Dashboard Page Patterns + +The dashboard page (`sirius-ui/src/pages/dashboard.tsx`) exemplifies the 0.4.0 style: + +**Glassmorphism Header**: + +- Sticky header with `bg-gray-900/95 backdrop-blur-sm` +- Border: `border-b border-violet-500/20` +- Shadow: `shadow-lg shadow-black/20` +- Icon containers: `bg-violet-500/10 ring-2 ring-violet-500/20` + +**Hero Cards**: + +- Large metric displays with `DashboardHeroCard` +- Variants: `default`, `critical`, `success` +- Hover effects with gradient overlays + +**Dashboard Cards**: + +- Consistent card styling: `border-violet-500/20 bg-gray-900/50 backdrop-blur-sm` +- Header with icon and actions +- Loading states with skeletons +- Error states with red accent + +**Grid Layouts**: + +- Responsive grids: `grid gap-6 lg:grid-cols-3` +- Two-column spans: `lg:col-span-2` +- Consistent spacing throughout + +#### Scanner Page Patterns + +The scanner page (`sirius-ui/src/pages/scanner.tsx`) demonstrates scanner-specific patterns: + +**Scanner Sections**: + +- Use `.scanner-section` and `.scanner-section-primary` classes +- Consistent violet borders and backdrop blur +- Scrollable table wrappers for wide content + +**Navigation Tabs**: + +- Sticky navigation with glassmorphism +- Active state: `border-violet-500 text-violet-300` +- Inactive: `border-transparent text-gray-400 hover:text-gray-200` + +**Section Headers**: + +- Icon + title pattern +- Consistent spacing and typography +- Action buttons aligned right + +## Troubleshooting + +### FAQ + +**Q: Which color should I use for primary actions?** +A: Use violet theme colors: `bg-violet-500/10 hover:bg-violet-500/20` with `border-violet-500/20` and `text-violet-400`. For buttons, use the `default` variant which uses `bg-primary`. + +**Q: How do I create a glassmorphism effect?** +A: Use `bg-gray-900/50` or `bg-gray-800/50` with `backdrop-blur-sm` and a border like `border-violet-500/20`. Add `shadow-lg shadow-black/20` for depth. + +**Q: What spacing should I use between sections?** +A: Use `space-y-8` for major sections, `space-y-6` for cards, and `space-y-4` for related items. Use `gap-6` for grid layouts. + +**Q: How do I style severity badges?** +A: Use semantic colors: `bg-red-700 text-white` for critical, `bg-orange-700` for high, `bg-yellow-700` for medium, `bg-green-700` for low, `bg-blue-700` for info. Or use opacity variants: `bg-red-500/20 text-red-400`. + +**Q: What's the difference between Card and DashboardCard?** +A: `Card` is the base ShadCN component for general content containers. `DashboardCard` is a specialized component with built-in loading states, error handling, and action buttons for dashboard widgets. + +**Q: How do I create a sticky header?** +A: Use `sticky top-0 z-30` with `bg-gray-900/95 backdrop-blur-sm` and `border-b border-violet-500/20`. Add `shadow-lg shadow-black/20` for separation. + +**Q: What animations should I use?** +A: Use `transition-colors duration-200` for color changes, `transition-all duration-200` for complex changes. Use `animate-pulse` for loading states, `animate-spin` for spinners. + +**Q: How do I make tables scrollable?** +A: Wrap the table in a container with `overflow-x-auto` or use `.scanner-table-wrapper` class. Use negative margins (`-mx-4 px-4`) for full-width scrolling. + +**Q: What z-index values should I use?** +A: Use `z-20` for page content, `z-30` for sticky headers, `z-40` for dropdowns, `z-50` for modals. Don't exceed `z-50` unless necessary. + +**Q: How do I style form inputs?** +A: Use the `Input` component with custom classes: `border-violet-500/20 bg-gray-800/50 backdrop-blur-sm`. Focus states use `ring-violet-500`. + +### Command Reference + +```bash +# View Tailwind configuration +cat sirius-ui/tailwind.config.ts + +# View global styles +cat sirius-ui/src/styles/globals.css + +# Search for color usage patterns +grep -r "violet-500" sirius-ui/src/pages/ + +# Search for component usage +grep -r "DashboardCard" sirius-ui/src/components/ + +# Find spacing patterns +grep -r "space-y-8\|gap-6" sirius-ui/src/pages/ +``` + +### Common Issues and Solutions + +| Issue | Symptoms | Solution | +| ------------------------- | ------------------------------ | -------------------------------------------------------------------------------------- | +| Colors don't match | Inconsistent violet shades | Use documented color values from tailwind.config.ts, use opacity syntax (`/20`, `/30`) | +| Spacing inconsistent | Uneven gaps between elements | Use Tailwind spacing scale (`gap-6`, `space-y-8`), avoid arbitrary values | +| Glassmorphism not working | Solid backgrounds, no blur | Ensure `backdrop-blur-sm` is present, use semi-transparent backgrounds (`/50`, `/20`) | +| Components look different | Styling doesn't match examples | Check if using correct ShadCN component, verify custom classes match patterns | +| Animations too fast/slow | Transitions feel off | Use standard durations (`duration-200`, `duration-300`), check easing functions | +| Z-index conflicts | Elements overlap incorrectly | Use documented z-index scale, check stacking context | +| Responsive breakpoints | Layout breaks on mobile | Use responsive utilities (`md:`, `lg:`), test at breakpoints | + +### Debugging Steps + +1. **Check Color Values**: Verify colors match documented values from `tailwind.config.ts` +2. **Verify Spacing**: Ensure spacing uses Tailwind scale, not arbitrary values +3. **Inspect Components**: Compare with exemplar pages (dashboard.tsx, scanner.tsx) +4. **Test Responsive**: Check behavior at documented breakpoints +5. **Validate Classes**: Ensure Tailwind classes are properly configured +6. **Check Opacity**: Verify opacity syntax (`/20`, `/30`) is correct + +### Lessons Learned + +**2025-01-03**: Established comprehensive 0.4.0 style guide based on dashboard and scanner page implementations. Key insight: Glassmorphism effects with violet accents create a distinctive, modern interface that maintains readability in dark mode. + +**2025-01-03**: Documented extensive use of opacity for layering and depth. Lesson: Consistent opacity levels (20%, 30%, 40%) create visual hierarchy without overwhelming the interface. + +**2025-01-03**: Identified scanner-specific CSS classes as important pattern. Benefit: Reusable classes (`.scanner-section`, `.scanner-section-primary`) ensure consistency across scanner interface. + +## Related Documentation + +- **[README.development.md](../README.development.md)**: Development workflow and standards +- **[ABOUT.documentation.md](../ABOUT.documentation.md)**: Documentation system standards +- **ShadCN UI Documentation**: Component API reference (external) +- **Tailwind CSS Documentation**: Utility class reference (external) + +## LLM Context + +This style guide documents the Sirius 0.4.0 UI design system. Key concepts for AI understanding: + +- **Dark Mode First**: The system is designed primarily for dark mode, with light mode as secondary +- **Violet Theme**: Violet/purple colors are the primary brand identity throughout +- **Glassmorphism**: Extensive use of backdrop blur and transparency for modern aesthetic +- **ShadCN Foundation**: All components built on ShadCN UI, customized with Sirius styling +- **Consistent Patterns**: Dashboard and scanner pages serve as exemplars for all UI development +- **Design Tokens**: Standardized values for spacing, colors, shadows, borders, and animations +- **Component Library**: ShadCN components provide base functionality, custom components add Sirius-specific features + +When generating UI code, always reference this guide for: + +- Color choices (violet theme, semantic colors) +- Spacing values (Tailwind scale) +- Component selection (ShadCN vs custom) +- Design patterns (cards, sections, headers) +- Animation usage (subtle transitions, loading states) + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ + + + diff --git a/documentation/dev/operations/README.api-key-operations.md b/documentation/dev/operations/README.api-key-operations.md new file mode 100644 index 0000000..67044ed --- /dev/null +++ b/documentation/dev/operations/README.api-key-operations.md @@ -0,0 +1,118 @@ +--- +title: "API Key Operations Runbook" +description: "Production runbook for stateless service API key rotation, recovery, and incident response." +template: "TEMPLATE.guide" +llm_context: "high" +categories: ["operations", "security", "deployment"] +tags: ["apikey", "rotation", "incident-response", "valkey", "runbook"] +related_docs: + - "README.development.md" + - "README.docker-container-deployment.md" + - "README.auth-surface-matrix.md" +--- + +# API Key Operations Runbook + +This runbook defines production-safe operations for Sirius service API keys. + +## Scope + +Applies to service-to-service credential `SIRIUS_API_KEY` used by: +- `sirius-api` +- `sirius-ui` (server-side tRPC -> API calls) +- `sirius-engine` and agent/scanner API clients + +## Baseline Invariants + +- `SIRIUS_API_KEY` must be non-empty in production. +- Go API must reject requests without a valid `X-API-Key`. +- Only `/health` is public. +- Root service key validation is stateless from runtime environment configuration. +- Valkey stores only dynamic/user-generated API key records. + +## Rotation Procedure (No Downtime) + +### 1) Create new key + +1. Authenticate as admin in UI. +2. Create a new API key in Settings. +3. Record: + - key value (shown once) + - key id/hash + - label + +### 2) Deploy new key to services + +1. Update deployment secret store or environment value for `SIRIUS_API_KEY` with the new key. +2. Roll out services in order: + 1. `sirius-api` + 2. `sirius-ui` + 3. `sirius-engine` +3. Validate: + - API 401 rate does not spike. + - UI can read/write through tRPC. + - scanner/agent host submissions continue. + +### 3) Revoke old key + +1. After rollout and validation period, revoke old key in UI. +2. Confirm old key returns 401. +3. Close rotation ticket. + +## Incident: Valkey Data Loss + +Symptoms: +- sudden 401s for user-generated keys +- API key list empty +- dynamic key operations fail while root key requests still succeed + +Recovery: +1. Restore Valkey from backup if available. +2. If no backup: + - ensure production `SIRIUS_API_KEY` is correctly set for all services. + - restart `sirius-api` first; root key path remains stateless. +3. Restart `sirius-ui` and `sirius-engine`. +4. Validate end-to-end operations and security harness results. + +## Incident: Root Key Mismatch (Configuration Drift) + +Symptoms: +- services return 401 with old key after key rotation +- env values differ between `sirius-ui`, `sirius-api`, and `sirius-engine` + +Recovery: +1. Confirm deployed `SIRIUS_API_KEY` value in runtime environment. +2. Restart `sirius-api`, then `sirius-ui` and `sirius-engine`. +3. Re-check key validation success for deployed root key. +4. If still failing, capture API logs and run security harness `auth-surface` and `api` suites. + +## Incident: Unauthorized Agent/Scanner API Writes + +Symptoms: +- scanner/agent host submissions return 401 + +Recovery: +1. Verify `SIRIUS_API_KEY` is present in engine/scanner/agent runtime. +2. Verify clients send `X-API-Key`. +3. Validate key exists in API key list and is not revoked. +4. Roll service restart after secret correction. + +## Validation Commands + +Run security checks from repository root: + +```bash +cd testing/security +go run . --suite api +go run . --suite trpc +go run . --suite auth-surface +``` + +## Operational Checklist + +- [ ] `SIRIUS_API_KEY` secret exists and is non-empty in production. +- [ ] API middleware accepts configured root key on non-health routes. +- [ ] UI + engine are using the same active service key. +- [ ] Old keys are revoked only after rollout validation. +- [ ] Recovery procedure for config drift or Valkey loss is documented in incident ticket. + diff --git a/documentation/dev/operations/README.git-operations.md b/documentation/dev/operations/README.git-operations.md new file mode 100644 index 0000000..0f88cf5 --- /dev/null +++ b/documentation/dev/operations/README.git-operations.md @@ -0,0 +1,1000 @@ +--- +title: "Git Operations" +description: "Simple, practical git workflow for Sirius project development" +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Development Team" +tags: ["git", "workflow", "development", "version-control"] +categories: ["operations", "development"] +difficulty: "beginner" +prerequisites: ["git", "docker", "testing"] +related_docs: + - "README.development.md" + - "README.container-testing.md" +dependencies: [] +llm_context: "high" +search_keywords: ["git", "commit", "branch", "merge", "workflow", "pre-commit"] +--- + +# Git Operations + +## Purpose + +This document outlines the simple, practical git workflow used in the Sirius project. It focuses on the actual processes we use rather than theoretical best practices, making it easy for developers to understand when and how to perform git operations. + +## When to Use + +- **Before making any commits** - Understand pre-commit requirements +- **When starting new work** - Know whether to branch or commit directly +- **When finishing work** - Understand merge and commit strategies +- **For team coordination** - Ensure consistent git practices across the team + +## How to Use + +1. **Check your current situation** - Are you on main or a feature branch? +2. **Follow the appropriate workflow** - Direct commits vs. branching workflow +3. **Run pre-commit checks** - Always validate before committing +4. **Use the right commit strategy** - Direct commit vs. merge based on your situation + +## What This Workflow Is + +### Core Philosophy + +Our git workflow is **pragmatic and simple**: + +- **Direct commits to main** when working on small, isolated changes +- **Feature branches** when working on larger, multi-commit features +- **Pre-commit validation** to ensure code quality before any commit +- **No complex branching strategies** - just main and feature branches + +### Workflow Decision Tree + +``` +Are you working on a new feature? +├── YES → Create feature branch → Work → Merge to main +└── NO → Are you on main branch? + ├── YES → Commit directly to main + └── NO → Continue on current branch +``` + +## Pre-Commit Requirements + +### What You Must Do Before Every Commit + +Before committing any code, you **must** run these checks: + +```bash +# 1. Run container tests +cd testing/container-testing +make test-all + +# 2. Validate documentation +make lint-docs +make lint-index + +# 3. Check container health +docker compose ps +``` + +### Why These Checks Matter + +- **Container tests** ensure your changes don't break the application +- **Documentation validation** keeps our docs consistent and complete +- **Container health** verifies all services are running properly + +### Quick Pre-Commit Script + +You can run all checks at once: + +```bash +# From project root +cd testing/container-testing +make validate-all +``` + +## GitHub Issue Integration + +### When to Create Issues + +Create a GitHub issue when: + +- **Discovering bugs** that need tracking and documentation +- **Planning new features** that require design discussion +- **Making significant changes** that affect multiple components +- **Working on complex fixes** that need implementation planning +- **Documenting work** for future reference and team visibility + +### When to Skip Issues + +Skip GitHub issues when: + +- **Making trivial fixes** (typos, minor documentation updates) +- **Making emergency hotfixes** that need immediate deployment +- **Working on local experiments** that may not be merged +- **Making simple, obvious changes** with no discussion needed + +### Handling User-Reported Issues + +When a user reports an issue on GitHub: + +1. **Acknowledge the issue** - Comment on the issue thanking the user and confirming you're investigating +2. **Reproduce the issue** - Verify you can reproduce the problem +3. **Document your findings** - Add a comment with your diagnosis and implementation plan +4. **Follow the standard workflow** - Create branch, fix, test, merge (see Complete GitHub Workflow below) +5. **Close with details** - Update the issue with the fix details and close it + +**Example acknowledgment comment:** + +```markdown +Thank you for reporting this issue! I've confirmed the problem and identified the root cause: + +**Diagnosis:** [Brief technical explanation] + +**Fix plan:** + +- [ ] [Step 1] +- [ ] [Step 2] +- [ ] [Step 3] + +Working on a fix now. Will update once complete. +``` + +### Issue Creation Process + +```bash +# 1. Identify the problem or feature +# 2. Go to GitHub repository +# 3. Click "Issues" → "New Issue" +# 4. Use descriptive title format: +# - Bug: "Fix: [component] brief description" +# - Feature: "Feature: [component] brief description" +# - Enhancement: "Enhancement: [component] brief description" + +# 5. Document in the issue: +# - Problem statement or feature description +# - Current behavior (for bugs) +# - Expected behavior (for bugs) or desired outcome (for features) +# - Implementation plan (if known) +# - Testing strategy +# - Affected components +``` + +### Issue Template + +```markdown +## Problem Statement + +Brief description of the issue or feature need + +## Current Behavior + +What happens now (for bugs) + +## Expected Behavior + +What should happen (for bugs) or what we want to build (for features) + +## Implementation Plan + +- [ ] Step 1: Description +- [ ] Step 2: Description +- [ ] Step 3: Description + +## Testing Strategy + +How to verify the fix works + +## Affected Components + +- Component 1 +- Component 2 + +## Additional Context + +Any relevant information, logs, screenshots, etc. +``` + +### Linking Branches to Issues + +Use issue numbers in branch names: + +```bash +# Format: /- +git checkout -b fix/123-container-startup-issue +git checkout -b feature/456-user-authentication +git checkout -b docs/789-update-readme +``` + +### Documenting Implementation Plans in Issues + +After creating an issue, add the implementation plan as a comment: + +```markdown +## Implementation Plan + +### Phase 1: Diagnosis + +- [x] Identified root cause in Dockerfiles +- [x] Documented current vs expected behavior +- [x] Created step-by-step fix plan + +### Phase 2: Implementation + +- [ ] Update sirius-api Dockerfile +- [ ] Update sirius-engine Dockerfile +- [ ] Update sirius-ui Dockerfile +- [ ] Update startup scripts + +### Phase 3: Testing + +- [ ] Test production mode builds +- [ ] Test development mode builds +- [ ] Verify all services start correctly +- [ ] Check process monitoring + +### Phase 4: Deployment + +- [ ] Merge to main branch +- [ ] Verify production deployment +- [ ] Close issue with results +``` + +## Branching Strategy + +### When to Create a Branch + +Create a feature branch when: + +- **Working on a GitHub issue** that requires tracked changes +- **Working on a new feature** that will take multiple commits +- **Making significant changes** that might break existing functionality +- **Experimenting** with new approaches or technologies +- **Working on something** that others might need to review + +### When to Commit Directly to Main + +Commit directly to main when: + +- **Making small fixes** (typos, minor bugs, documentation updates) +- **No GitHub issue exists** and the change is trivial +- **You're already on main** and the change is simple +- **The change is isolated** and won't affect other functionality +- **You're confident** the change won't break anything + +### Branch Naming + +Use simple, descriptive names: + +```bash +# Without issue number (simple changes) +feature/user-authentication +fix/docker-build-issue +docs/update-readme +experiment/new-scanner + +# With issue number (tracked work) +fix/123-docker-build-issue +feature/456-user-authentication +docs/789-update-readme + +# Bad examples +branch1 +test +work +my-changes +``` + +## Complete GitHub Workflow + +### Full Issue → Branch → Commit → Merge Cycle + +This is the recommended workflow for all significant changes: + +```bash +# 1. CREATE GITHUB ISSUE +# - Go to GitHub repository +# - Create new issue with problem/feature description +# - Document implementation plan in issue comments +# - Note issue number (e.g., #123) + +# 2. CREATE FEATURE BRANCH +git checkout main +git pull origin main +git checkout -b fix/123-brief-description + +# 3. IMPLEMENT CHANGES +# - Make your code changes +# - Update documentation as needed +# - Follow implementation plan from issue + +# 4. RUN PRE-COMMIT CHECKS +cd testing/container-testing +make validate-all + +# 5. COMMIT TO FEATURE BRANCH +git add . +git commit -m "fix: brief description + +- Detailed change 1 +- Detailed change 2 +- Related to #123" + +# 6. PUSH BRANCH +git push origin fix/123-brief-description + +# 7. TEST ON BRANCH (CRITICAL - HUMAN VALIDATION REQUIRED) +# ⚠️ DO NOT SKIP THIS STEP ⚠️ +# - Deploy and run containers in development mode +# - Verify all services start correctly +# - Check logs for errors +# - Test all affected functionality +# - Deploy and run containers in production mode +# - Verify production build works +# - Test all services in production configuration +# +# 🛑 STOP: Get human approval before merging to main +# - Review test results with team/stakeholders +# - Confirm no errors in logs +# - Validate all functionality works as expected + +# 8. MERGE TO MAIN (ONLY AFTER APPROVAL) +git checkout main +git pull origin main +git merge fix/123-brief-description + +# 9. PUSH TO MAIN +git push origin main + +# 10. UPDATE GITHUB ISSUE +# - Add comment with test results +# - Confirm deployment successful +# - Close issue with "Closes #123" or manually + +# 11. CLEANUP BRANCH +git branch -d fix/123-brief-description +git push origin --delete fix/123-brief-description + +# 12. CLEANUP TEMPORARY FILES +# - Remove any temporary files from tmp/ directory +# - Commit cleanup if needed +``` + +### Workflow Decision Matrix + +| Situation | Create Issue? | Create Branch? | Workflow | +| ------------------------------------- | ------------- | -------------- | --------------------- | +| **Bug affecting multiple components** | ✅ Yes | ✅ Yes | Full GitHub workflow | +| **New feature development** | ✅ Yes | ✅ Yes | Full GitHub workflow | +| **Complex fix requiring planning** | ✅ Yes | ✅ Yes | Full GitHub workflow | +| **Documentation updates (major)** | ✅ Yes | ✅ Yes | Full GitHub workflow | +| **Small bug fix** | ⚠️ Optional | ⚠️ Optional | Simplified workflow | +| **Typo fix** | ❌ No | ❌ No | Direct commit to main | +| **Emergency hotfix** | ⚠️ Optional | ✅ Yes | Fast-track workflow | + +### Simplified Workflow (Small Changes) + +For minor fixes that don't need full issue tracking: + +```bash +# 1. Create branch (optional but recommended) +git checkout -b fix/small-bug-description + +# 2. Make changes +# ... edit files ... + +# 3. Run pre-commit checks +cd testing/container-testing && make validate-all + +# 4. Commit and push +git add . +git commit -m "fix: small bug description" +git push origin fix/small-bug-description + +# 5. Merge to main +git checkout main +git merge fix/small-bug-description +git push origin main + +# 6. Cleanup +git branch -d fix/small-bug-description +``` + +### Fast-Track Workflow (Emergency Fixes) + +For critical issues requiring immediate deployment: + +```bash +# 1. Create hotfix branch +git checkout -b hotfix/critical-issue + +# 2. Make minimal fix +# ... fix the critical issue ... + +# 3. Quick validation +cd testing/container-testing && make test-health + +# 4. Commit and merge immediately +git add . +git commit -m "hotfix: critical issue description" +git checkout main +git merge hotfix/critical-issue +git push origin main + +# 5. Create retroactive issue +# Document what happened and why +# Track follow-up work if needed +``` + +## Commit Workflow + +### Direct Commits to Main + +When working directly on main: + +```bash +# 1. Check you're on main +git branch + +# 2. Run pre-commit checks +cd testing/container-testing +make validate-all + +# 3. Stage your changes +git add . + +# 4. Commit with clear message +git commit -m "fix: resolve docker build issue" + +# 5. Push to main +git push origin main +``` + +### Feature Branch Workflow + +When working on a feature branch: + +```bash +# 1. Create and switch to feature branch +git checkout -b feature/new-feature + +# 2. Make your changes and commit +git add . +git commit -m "feat: add new feature functionality" + +# 3. Push branch to remote +git push origin feature/new-feature + +# 4. When ready, merge to main +git checkout main +git merge feature/new-feature + +# 5. Push updated main +git push origin main + +# 6. Clean up feature branch +git branch -d feature/new-feature +git push origin --delete feature/new-feature +``` + +## Commit Message Standards + +### Format + +``` +: + +[optional body with details] + +[optional footer with issue references] +``` + +### Types + +- **feat**: New feature +- **fix**: Bug fix +- **docs**: Documentation changes +- **test**: Testing changes +- **refactor**: Code refactoring +- **chore**: Maintenance tasks +- **hotfix**: Emergency critical fix + +### Referencing Issues in Commits + +Use issue references to link commits to GitHub issues: + +```bash +# Close an issue automatically +git commit -m "fix: resolve container startup issue + +- Fixed system-monitor binary paths +- Added app-administrator to production builds +- Updated startup scripts for both dev and prod + +Closes #123" + +# Reference without closing +git commit -m "feat: add user authentication + +Related to #456" + +# Reference multiple issues +git commit -m "fix: update Docker configurations + +Fixes #123, fixes #124, related to #125" +``` + +### Closing Keywords + +These keywords automatically close issues when commit is merged to main: + +- `Closes #123` +- `Fixes #123` +- `Resolves #123` +- `Close #123` +- `Fix #123` +- `Resolve #123` + +### Examples + +**Simple fix with issue:** + +``` +fix: resolve container startup issue + +Closes #123 +``` + +**Detailed fix with issue:** + +``` +fix: resolve system-monitor and app-administrator startup failures + +Changes: +- Updated sirius-api Dockerfile to fix binary paths +- Added app-administrator build steps to all containers +- Fixed dev mode startup scripts to use go run for source +- Updated production mode to use compiled binaries + +Testing: +- Verified production mode starts both services +- Verified development mode starts both services +- Confirmed process monitoring works correctly + +Closes #123 +``` + +**Feature without issue:** + +``` +feat: add user authentication system + +- Implemented JWT-based authentication +- Added login/logout endpoints +- Created authentication middleware +``` + +**Documentation update:** + +``` +docs: update git workflow with GitHub issue integration + +- Added issue creation guidelines +- Documented full workflow cycle +- Added examples for different scenarios +``` + +## Merge Strategy + +### When to Merge + +Merge feature branches when: + +- **Feature is complete** and tested +- **All pre-commit checks pass** +- **Code has been reviewed** (if required) +- **No conflicts** with main branch + +### How to Merge + +```bash +# 1. Switch to main branch +git checkout main + +# 2. Pull latest changes +git pull origin main + +# 3. Merge feature branch +git merge feature/your-feature + +# 4. Push merged changes +git push origin main + +# 5. Delete feature branch +git branch -d feature/your-feature +``` + +### Merge Conflicts + +If you encounter merge conflicts: + +```bash +# 1. Check which files have conflicts +git status + +# 2. Edit conflicted files to resolve conflicts +# Look for <<<<<<< HEAD markers + +# 3. Stage resolved files +git add resolved-file.txt + +# 4. Complete the merge +git commit +``` + +## Pull Requests (Optional) + +### When to Use Pull Requests + +Use pull requests when: + +- **Working with a team** and want code review +- **Making significant changes** that others should review +- **Want to document** the changes before merging +- **Working on a shared feature** with other developers + +### When NOT to Use Pull Requests + +Skip pull requests when: + +- **Working solo** on the project +- **Making small, obvious changes** +- **You're confident** in your changes +- **Time is critical** and changes are simple + +## Common Scenarios + +### Scenario 1: Quick Bug Fix (No Issue) + +```bash +# You're on main, need to fix a small bug +git status +# Run pre-commit checks +cd testing/container-testing && make validate-all +git add . +git commit -m "fix: resolve typo in error message" +git push origin main +``` + +### Scenario 2: Complex Bug Fix (With GitHub Issue) + +```bash +# 1. Create GitHub issue #123: "Fix: Container startup failures" +# 2. Document diagnosis and implementation plan in issue + +# 3. Create feature branch +git checkout -b fix/123-container-startup-failures + +# 4. Implement fixes +# ... make changes ... + +# 5. Test changes +cd testing/container-testing && make validate-all + +# 6. Commit with issue reference +git add . +git commit -m "fix: resolve system-monitor and app-administrator startup failures + +Changes: +- Updated Dockerfiles to build both services +- Fixed binary paths in startup scripts +- Added development mode support + +Testing: +- Verified production mode startup +- Verified development mode startup +- Confirmed process monitoring + +Closes #123" + +# 7. Push and merge +git push origin fix/123-container-startup-failures +git checkout main +git merge fix/123-container-startup-failures +git push origin main + +# 8. Cleanup +git branch -d fix/123-container-startup-failures +git push origin --delete fix/123-container-startup-failures + +# 9. Verify issue closed automatically on GitHub +``` + +### Scenario 3: New Feature Development (With GitHub Issue) + +```bash +# 1. Create GitHub issue #456: "Feature: User dashboard" +# 2. Document requirements and design in issue + +# 3. Create feature branch +git checkout -b feature/456-user-dashboard + +# 4. Develop feature with multiple commits +git add . && git commit -m "feat: add user dashboard layout" +git add . && git commit -m "feat: add user data fetching" +git add . && git commit -m "feat: add dashboard interactivity + +Closes #456" + +# 5. Push and merge +git push origin feature/456-user-dashboard +git checkout main +git merge feature/456-user-dashboard +git push origin main + +# 6. Cleanup +git branch -d feature/456-user-dashboard +``` + +### Scenario 4: Documentation Update (No Issue) + +```bash +# You're on main, updating docs +git status +# Run pre-commit checks +cd testing/container-testing && make validate-all +git add . +git commit -m "docs: update docker setup instructions" +git push origin main +``` + +### Scenario 5: Emergency Hotfix (With Retroactive Issue) + +```bash +# 1. Critical production issue discovered +# 2. Create hotfix branch immediately +git checkout -b hotfix/critical-security-patch + +# 3. Make minimal fix +# ... fix critical issue ... + +# 4. Quick test +cd testing/container-testing && make test-health + +# 5. Merge immediately +git add . +git commit -m "hotfix: patch critical security vulnerability" +git checkout main +git merge hotfix/critical-security-patch +git push origin main + +# 6. Create retroactive GitHub issue +# - Document what happened +# - Explain the fix +# - Plan follow-up work +# - Reference the hotfix commit +``` + +## Troubleshooting + +### Common Issues + +#### Pre-commit Checks Fail + +```bash +# Check what failed +cd testing/container-testing +make test-all + +# Fix the issues, then retry +# Common fixes: +# - Fix failing tests +# - Update documentation +# - Restart containers: docker compose restart +``` + +#### Merge Conflicts + +```bash +# See what files have conflicts +git status + +# Edit files to resolve conflicts +# Look for <<<<<<< HEAD markers + +# After resolving, stage and commit +git add . +git commit +``` + +#### Wrong Branch + +```bash +# If you committed to wrong branch +git log --oneline -1 # See last commit +git reset HEAD~1 # Undo last commit (keeps changes) +git checkout correct-branch +git add . +git commit -m "your message" +``` + +#### Forgot to Run Pre-commit Checks + +```bash +# If you already committed without checks +git reset HEAD~1 # Undo commit +# Run pre-commit checks +cd testing/container-testing && make validate-all +# Re-commit +git add . +git commit -m "your message" +``` + +## Best Practices + +### Do This + +- **Always run pre-commit checks** before committing +- **Use clear, descriptive commit messages** +- **Keep commits focused** on a single change +- **Test your changes thoroughly** in both dev and prod modes before merging +- **Get human approval** before merging to main branch +- **Update documentation** when making structural changes +- **Clean up temporary files** before finalizing + +### Don't Do This + +- **Don't commit broken code** - fix it first +- **Don't skip pre-commit checks** - they catch issues +- **Don't skip human testing validation** - automated tests aren't enough +- **Don't merge to main without approval** - always get human sign-off +- **Don't use vague commit messages** like "fix stuff" +- **Don't commit large, unrelated changes** in one commit +- **Don't force push to main** unless absolutely necessary +- **Don't leave temporary files** in the repository + +## Quick Reference + +### Daily Workflow + +```bash +# Check current status +git status +git branch + +# Run pre-commit checks +cd testing/container-testing +make validate-all + +# Make your changes +# ... edit files ... + +# Commit changes +git add . +git commit -m "type: description" +git push origin main +``` + +### Feature Development + +```bash +# Start feature +git checkout -b feature/name +# ... work on feature ... +git add . && git commit -m "feat: description" + +# Finish feature +git checkout main +git merge feature/name +git push origin main +git branch -d feature/name +``` + +### Emergency Fixes + +```bash +# Quick fix on main +git status +cd testing/container-testing && make validate-all +git add . +git commit -m "fix: emergency description" +git push origin main +``` + +## Lessons Learned + +This section captures insights from real-world issue resolution to continuously improve our Git workflow. + +### 2025-10-11: GitHub Issue #60 - Password Change Type Mismatch + +**Issue Type**: User-reported bug affecting authentication functionality + +**What Went Well**: + +- ✅ Updated Git operations documentation was immediately useful for handling user-reported issues +- ✅ Feature branch workflow kept main branch stable during development +- ✅ Pre-commit checks caught documentation index issues early +- ✅ Seed script infrastructure was already in place for database reset +- ✅ Clear commit messages with issue references provided good traceability + +**Areas for Improvement**: + +1. **Database Management Gap** + + - **Problem**: No documentation about handling local database state changes during testing + - **Impact**: Password change testing modified local database, unclear how to reset + - **Solution**: Added database management section to sirius-ui README + - **Future**: Document testing practices for database-interactive features upfront + +2. **Testing Checklist Needed** + + - **Problem**: General testing guidance exists but lacks specific checklists by issue type + - **Impact**: Had to determine testing approach ad-hoc + - **Solution**: Should create testing checklists for: frontend changes, backend API changes, database schema changes, authentication changes + - **Future**: Add "Testing Strategy" section with issue-type-specific checklists + +3. **Issue Comment Templates Missing** + + - **Problem**: Had to craft GitHub issue comments from scratch + - **Impact**: Time spent formatting responses, risk of missing important information + - **Solution**: Should create templates for: acknowledgment, diagnosis update, resolution confirmation + - **Future**: Add issue comment templates to documentation or use GitHub issue templates feature + +4. **Documentation Index Maintenance** + + - **Problem**: Pre-commit checks revealed missing files in documentation index + - **Impact**: Commit failed, had to fix index mid-workflow + - **Solution**: Updated index as part of commit + - **Future**: Add reminder to update index when creating new documentation files + +5. **Branch Strategy Clarity** + + - **Problem**: Documentation references "main" but we use "demo" branch + - **Impact**: Minor confusion about which branch is the integration branch + - **Solution**: Followed actual branch structure (demo) + - **Future**: Update documentation to reflect actual branch naming or create branch strategy document + +6. **Testing Documentation for Containerized Apps** + - **Problem**: Testing required rebuilding containers but this wasn't clearly documented in workflow + - **Impact**: Testing step less clear than it could be + - **Solution**: Added container rebuild instructions to testing guidance + - **Future**: Create container-specific testing workflow document + +**Process Improvements Implemented**: + +- Added "Handling User-Reported Issues" workflow section +- Enhanced database management documentation +- Improved documentation index maintenance +- Added database reset procedures to README + +**Recommendations for Next Iteration**: + +1. Create issue type-specific testing checklists +2. Develop GitHub issue comment templates +3. Add pre-commit reminder for documentation index updates +4. Document branch strategy (main vs demo vs feature) +5. Create rollback procedures for failed merges +6. Add post-merge verification checklist + +### How to Use This Section + +**After resolving any significant issue**: + +1. Add a new timestamped entry with the issue identifier +2. Document what went well (celebrate successes!) +3. Identify improvement areas with specific impacts +4. Note solutions implemented during resolution +5. Recommend future improvements +6. Update relevant documentation sections based on learnings + +**Quarterly Review**: + +- Review all lessons learned entries +- Identify patterns in improvement areas +- Prioritize documentation updates +- Update templates and workflows accordingly +- Archive old entries that have been fully addressed + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/operations/README.maintainer-ops-issue-review.md b/documentation/dev/operations/README.maintainer-ops-issue-review.md new file mode 100644 index 0000000..f8d04c4 --- /dev/null +++ b/documentation/dev/operations/README.maintainer-ops-issue-review.md @@ -0,0 +1,125 @@ +--- +title: "Maintainer Issue Review System" +description: "Issue and PR triage taxonomy, lifecycle, and ChatOps conventions for mobile-friendly Sirius maintenance." +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2026-02-22" +author: "Sirius Team" +tags: ["operations", "triage", "chatops", "github", "labels"] +categories: ["operations", "development"] +difficulty: "intermediate" +prerequisites: ["github", "github-actions", "sirius-workflows"] +related_docs: + - "README.git-operations.md" + - "README.api-key-operations.md" + - "../deployment/README.workflows.md" + - "../test/CHECKLIST.testing-by-type.md" +dependencies: + - ".github/labels.yml" + - ".github/workflows/issue-triage.yml" + - ".github/workflows/chatops-runner.yml" +llm_context: "high" +search_keywords: ["triage", "labels", "issue forms", "chatops", "slash commands", "mobile maintainer"] +--- + +# Maintainer Issue Review System + +## Purpose + +Define a deterministic, evidence-driven issue and PR review workflow that works well from mobile and minimizes maintainer back-and-forth. + +## Label Taxonomy + +### Status Labels (single active status) + +- `status:needs-triage` +- `status:needs-info` +- `status:repro-ready` +- `status:confirmed` +- `status:in-progress` +- `status:blocked` +- `status:ready-to-merge` +- `status:done` + +### Type Labels + +- `type:bug` +- `type:enhancement` +- `type:security` +- `type:docs` +- `type:question` + +### Area Labels + +- `area:installer-secrets` +- `area:compose-dev` +- `area:compose-prod` +- `area:ui` +- `area:api` +- `area:engine` +- `area:rabbitmq` +- `area:postgres` +- `area:valkey` +- `area:auth` + +### Severity Labels + +- `sev:critical` +- `sev:high` +- `sev:medium` +- `sev:low` + +## Issue Intake + +Issue forms are required and live under `.github/ISSUE_TEMPLATE/`. + +Current form set: + +- `install-startup.yml` +- `auth-401.yml` +- `dev-overlay.yml` +- `windows-wsl.yml` +- `security-report.yml` + +Intake quality baseline: + +- run mode (standard/dev/prod overlay) +- runtime version/tag +- host OS + Docker version +- compose render validation outcome +- key service logs +- minimal reproduction steps + +## Triage and ChatOps Lifecycle + +1. New issue receives `status:needs-triage`. +2. Triage automation applies `type:*`, `area:*`, and severity hints from deterministic rules. +3. Triage Card comment is posted with missing-info checks and recommended commands. +4. Maintainer drives progression from comments: + - `/triage needs-info` + - `/triage repro-ready` + - `/triage confirmed` +5. Maintainer triggers evidence workflows from comments: + - `/test health` + - `/test integration` + - `/test security ` + +## PR Review Policy + +PRs are path-labeled (`area:*`) and receive an automated review card summarizing: + +- changed surfaces and risk zones +- recommended test checklist slices +- mobile-safe slash commands for additional validation + +Required test guidance is sourced from `documentation/dev/test/CHECKLIST.testing-by-type.md`. + +## Operational Notes + +- Deterministic rules decide labels/states; AI summaries are optional and advisory. +- Security and confirmed issues are exempt from stale auto-close. +- Health and integration evidence should be posted in-thread for auditability. + +--- + +_This document follows the Sirius Documentation Standard. For documentation governance, see `documentation/dev/ABOUT.documentation.md`._ diff --git a/documentation/dev/operations/README.new-project.md b/documentation/dev/operations/README.new-project.md new file mode 100644 index 0000000..4d69770 --- /dev/null +++ b/documentation/dev/operations/README.new-project.md @@ -0,0 +1,395 @@ +--- +title: "New Project Development Workflow" +description: "Structured approach for starting new development sprints with consistent project organization, task management, and Git workflows." +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Development Team" +tags: ["project-management", "workflow", "git", "tasks", "development"] +categories: ["operations", "development"] +difficulty: "beginner" +prerequisites: ["git", "cursor", "project-structure"] +related_docs: + - "README.tasks.md" + - "README.git-operations.md" +dependencies: [] +llm_context: "high" +search_keywords: + [ + "new project", + "development sprint", + "task management", + "git workflow", + "project structure", + ] +--- + +# New Project Development Workflow + +> **📚 Task Management**: For detailed task system usage, see [README.tasks.md](README.tasks.md) + +## Purpose + +This document defines the standardized workflow for starting new development sprints, ensuring consistent project organization, task tracking, and Git practices across all development efforts. + +## When to Use This Workflow + +- **Starting any new development sprint** - Follow this process for every new project +- **Major feature development** - Use for significant new features or enhancements +- **Bug fix campaigns** - Apply for systematic bug fixing efforts +- **Infrastructure changes** - Use for deployment, CI/CD, or architectural work +- **Research and prototyping** - Apply for exploratory development work + +## Project Structure Requirements + +### Required Files for Every Project + +Every new development sprint must create these files in the specified locations: + +#### 1. Task Definition File + +- **Location**: `tasks/{sprint-name}.json` +- **Purpose**: Detailed task breakdown and tracking +- **Format**: JSON array following established schema +- **Example**: `tasks/cicd.json` (see template below) + +#### 2. Project Plan Document + +- **Location**: `documentation/dev-notes/{sprint-name}-plan.md` +- **Purpose**: High-level project overview and context +- **Format**: Markdown with YAML front matter +- **Content**: Project goals, scope, timeline, and key decisions + +#### 3. Cleanup Task + +- **Requirement**: Every project must include a final cleanup task +- **Purpose**: Remove temporary files, update documentation, merge branches +- **ID Pattern**: `{last-id + 1}` (e.g., if last task is 5, cleanup is 6) + +## Task File Template + +Use this template structure for all `tasks/{sprint-name}.json` files: + +```json +[ + { + "id": "0", + "title": "PHASE 0: Project Foundation", + "description": "Brief description of the phase", + "details": "Detailed implementation notes and expected outputs", + "status": "pending", + "priority": "high", + "dependencies": [], + "subtasks": [ + { + "id": "0.1", + "title": "Specific Task Title", + "description": "What this task accomplishes", + "details": "Implementation details, acceptance criteria, and context", + "status": "pending", + "priority": "high", + "dependencies": [], + "testStrategy": "How to verify this task is complete" + } + ] + }, + { + "id": "1", + "title": "PHASE 1: Core Implementation", + "description": "Main development work", + "details": "Key deliverables and technical approach", + "status": "pending", + "priority": "high", + "dependencies": ["0"], + "subtasks": [ + { + "id": "1.1", + "title": "Implementation Task", + "description": "Specific implementation work", + "details": "Technical details and requirements", + "status": "pending", + "priority": "high", + "dependencies": ["0.1"], + "testStrategy": "Verification approach" + } + ] + }, + { + "id": "2", + "title": "PHASE 2: Cleanup & Documentation", + "description": "Project completion and cleanup", + "details": "Final tasks to close out the project", + "status": "pending", + "priority": "medium", + "dependencies": ["1"], + "subtasks": [ + { + "id": "2.1", + "title": "Clean Up Project Files", + "description": "Remove temporary files and update documentation", + "details": "Delete temporary files, update README if needed, ensure all documentation is current", + "status": "pending", + "priority": "medium", + "dependencies": ["1.1"], + "testStrategy": "Verify no temporary files remain and documentation is up to date" + } + ] + } +] +``` + +### Task Schema Requirements + +- **id**: Unique identifier (string, e.g., "0", "1.1", "2.3") +- **title**: Clear, descriptive task name +- **description**: Brief summary of what the task accomplishes +- **details**: Comprehensive implementation notes and context +- **status**: "pending", "in_progress", "done", "blocked" +- **priority**: "high", "medium", "low" +- **dependencies**: Array of task IDs this task depends on +- **subtasks**: Array of subtask objects (for main tasks) +- **testStrategy**: How to verify task completion (for subtasks) + +## Git Workflow for New Projects + +### Standard Branching Strategy + +For every new development sprint: + +#### 1. Create Feature Branch + +```bash +# Start from main branch +git checkout main +git pull origin main + +# Create new branch for the sprint +git checkout -b feature/{sprint-name} + +# Example: git checkout -b feature/agent-enhancements +``` + +#### 2. Branch Naming Convention + +- **Format**: `feature/{sprint-name}` +- **Examples**: + - `feature/agent-enhancements` + - `feature/ci-cd-pipeline` + - `feature/ui-redesign` + - `feature/database-optimization` + +#### 3. Work on Branch + +- Make all commits on the feature branch +- Use descriptive commit messages +- Commit frequently with atomic changes +- Push branch regularly to backup work + +#### 4. Merge Back to Main + +```bash +# When sprint is complete +git checkout main +git pull origin main +git merge feature/{sprint-name} +git push origin main + +# Clean up feature branch +git branch -d feature/{sprint-name} +git push origin --delete feature/{sprint-name} +``` + +### Exception Cases + +**When NOT to create a feature branch:** + +- Hotfixes requiring immediate deployment +- Documentation-only changes +- Minor configuration updates +- Emergency security patches + +**Alternative approaches:** + +- **Hotfixes**: Use `hotfix/{issue-description}` branch +- **Documentation**: Can be committed directly to main +- **Config changes**: Use `config/{change-description}` branch + +## Project Plan Document Template + +Create `documentation/dev-notes/{sprint-name}-plan.md` with this structure: + +```markdown +--- +title: "{Sprint Name} - Project Plan" +description: "High-level project overview and implementation strategy" +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Development Team" +tags: ["project-plan", "sprint", "{sprint-name}"] +categories: ["development", "planning"] +difficulty: "intermediate" +prerequisites: [] +related_docs: + - "README.tasks.md" +dependencies: [] +llm_context: "medium" +search_keywords: ["{sprint-name}", "project-plan", "development"] +--- + +# {Sprint Name} - Project Plan + +## Project Overview + +**Goal**: [Primary objective of this sprint] +**Timeline**: [Expected duration] +**Scope**: [What's included and excluded] + +## Key Deliverables + +1. [Primary deliverable 1] +2. [Primary deliverable 2] +3. [Primary deliverable 3] + +## Technical Approach + +[High-level technical strategy and key decisions] + +## Success Criteria + +- [ ] [Measurable success criterion 1] +- [ ] [Measurable success criterion 2] +- [ ] [Measurable success criterion 3] + +## Risk Assessment + +**High Risk Items:** + +- [Risk 1]: [Mitigation strategy] +- [Risk 2]: [Mitigation strategy] + +**Dependencies:** + +- [External dependency 1] +- [External dependency 2] + +## Notes + +[Any additional context, decisions, or considerations] +``` + +## Development Workflow Steps + +### 1. Project Initialization + +```bash +# 1. Create feature branch +git checkout main +git pull origin main +git checkout -b feature/{sprint-name} + +# 2. Create task file +touch tasks/{sprint-name}.json +# [Fill in task structure using template] + +# 3. Create project plan +touch documentation/dev-notes/{sprint-name}-plan.md +# [Fill in project plan using template] + +# 4. Initial commit +git add tasks/{sprint-name}.json documentation/dev-notes/{sprint-name}-plan.md +git commit -m "feat: initialize {sprint-name} project + +- Add task breakdown in tasks/{sprint-name}.json +- Add project plan in documentation/dev-notes/{sprint-name}-plan.md +- Create feature branch for development" + +git push origin feature/{sprint-name} +``` + +### 2. Development Process + +- **Start each work session** by reviewing current tasks +- **Update task status** as work progresses +- **Commit frequently** with descriptive messages +- **Reference task IDs** in commit messages when relevant +- **Ask for help** when blocked or uncertain + +### 3. Project Completion + +```bash +# 1. Complete all tasks (including cleanup) +# 2. Update project plan with final status +# 3. Merge to main +git checkout main +git pull origin main +git merge feature/{sprint-name} +git push origin main + +# 4. Clean up +git branch -d feature/{sprint-name} +git push origin --delete feature/{sprint-name} +``` + +## Best Practices + +### Task Management + +- **Keep tasks small** - Each subtask should be completable in 1-4 hours +- **Be specific** - Clear acceptance criteria and test strategies +- **Update status** - Mark tasks as done immediately when completed +- **Use dependencies** - Properly sequence related tasks + +### Git Practices + +- **Atomic commits** - Each commit should represent one logical change +- **Descriptive messages** - Use conventional commit format +- **Regular pushes** - Backup work frequently +- **Clean history** - Squash commits if needed before merging + +### Documentation + +- **Keep plans current** - Update project plans as scope changes +- **Document decisions** - Record important technical decisions +- **Include context** - Help future developers understand choices + +## Troubleshooting + +### Common Issues + +**Task file not found:** + +- Verify file is in `tasks/` directory +- Check filename matches sprint name +- Ensure JSON syntax is valid + +**Branch conflicts:** + +- Pull latest main before creating feature branch +- Rebase feature branch if main has moved significantly +- Resolve conflicts before merging + +**Missing project plan:** + +- Create plan document in `documentation/dev-notes/` +- Use template structure provided +- Include all required sections + +### Getting Help + +- **Task questions**: Reference [README.tasks.md](README.tasks.md) +- **Git issues**: Reference [README.git-operations.md](README.git-operations.md) +- **General help**: Ask for clarification on requirements or approach + +## Integration with Cursor Rules + +This workflow integrates with our Cursor rules system: + +- **Task context**: Cursor will include task files in context when working on projects +- **Git operations**: Cursor will follow branching and commit conventions +- **Documentation**: Cursor will maintain project plan and task documentation +- **Code quality**: Cursor will follow established coding standards + +--- + +_This workflow ensures consistent, organized development practices across all projects. For questions about specific aspects, see the related documentation files._ diff --git a/documentation/dev/operations/README.release-closeout-v1.0.0.md b/documentation/dev/operations/README.release-closeout-v1.0.0.md new file mode 100644 index 0000000..afda0f5 --- /dev/null +++ b/documentation/dev/operations/README.release-closeout-v1.0.0.md @@ -0,0 +1,85 @@ +--- +title: "Sirius v1.0.0 Release Closeout" +description: "Final push, merge, validation, and launch closeout evidence for the Sirius v1.0.0 major release." +template: "TEMPLATE.guide" +llm_context: "high" +categories: ["operations", "release", "deployment"] +tags: ["release", "v1.0.0", "closeout", "validation", "rollout"] +related_docs: + - "README.git-operations.md" + - "README.workflows.md" + - "README.docker-container-deployment.md" + - "README.api-key-operations.md" + - "../../OPERATIONS.md" +--- + +# Sirius v1.0.0 Release Closeout + +This document records final push/merge completion evidence for the Sirius v1.0.0 major release. + +## Launch References + +- PR merge record: https://github.com/SiriusScan/Sirius/pull/90 +- Release page: https://github.com/SiriusScan/Sirius/releases/tag/v1.0.0 +- Launch closeout issue: https://github.com/SiriusScan/Sirius/issues/93 +- Stabilization backlog: https://github.com/SiriusScan/Sirius/issues/92 + +## Release Integrity Evidence + +- PR `#90` status: merged into `main` (`v1` -> `main`) +- Merge commit: `014c89b441ab697654afb205e1960dcef74bfac3` +- Main release commit: `221b8001de3a580b7741f912cffa1ab8199d63e0` +- Main repo tag `v1.0.0` points to release commit `221b8001de3a580b7741f912cffa1ab8199d63e0` +- Release notes published (non-draft, non-prerelease) + +## Distribution Gate Evidence + +### Container image availability + +- `ghcr.io/siriusscan/sirius-ui:latest` available +- `ghcr.io/siriusscan/sirius-api:latest` available +- `ghcr.io/siriusscan/sirius-engine:latest` available +- At initial closeout, `v1.0.0` semver tags were not yet consistently published on GHCR for all stack images (historical `manifest unknown` on some application images; infrastructure images require the same [Publish Release Image Tags](../../../.github/workflows/publish-release-image-tags.yml) step as the app trio). + +Note: direct retag-and-push attempt from local environment was blocked by GHCR token scope restrictions. Versioned tags for operators are published via the **Publish Release Image Tags** workflow using CI credentials. + +### Post-closeout: third-party pulls and issue #119 + +External operators who set `IMAGE_TAG=v1.0.0` (or any semver) need **six** matching tags on GHCR and **public** package visibility. If any image lacks the tag or a package remains private, `docker compose pull` fails with `not found` / `manifest unknown` while maintainer machines may still succeed when authenticated to GHCR ([issue #119](https://github.com/SiriusScan/Sirius/issues/119)). + +**Remediation (maintainers):** follow the [GHCR distribution checklist](../../../OPERATIONS.md#maintainer-ghcr-distribution-checklist-public-operators): set each org package to Public, run **Publish Release Image Tags** with `source_tag=latest` and `target_tag=v1.0.0`, then confirm anonymously with `bash scripts/verify-ghcr-public-access.sh v1.0.0`. The **Verify GHCR Release Tag** workflow ([verify-ghcr-release-tag.yml](../../../.github/workflows/verify-ghcr-release-tag.yml)) runs the same check on every published release and weekly. + +**Suggested reply for issue #119 (after tags and visibility are fixed):** confirm all six anonymous pulls for `v1.0.0`, link the successful workflow run, and recommend leaving `IMAGE_TAG` blank for `latest` unless pinning. + +### Runtime smoke validation + +Release stack boot with required `SIRIUS_API_KEY` succeeded. + +- `docker compose ps`: all core services healthy (`sirius-ui`, `sirius-api`, `sirius-engine`, `sirius-postgres`, `sirius-rabbitmq`, `sirius-valkey`) +- API health: `GET http://localhost:9001/health` returns healthy JSON with `version: "1.0.0"` +- UI health proxy: `GET http://localhost:3000/` returns `200 OK` +- Engine gRPC listener: `localhost:50051` reachable + +## Repo Hygiene and Freeze + +- Main repo working tree is clean except local planning artifacts under `.cursor/plans/`. +- Freeze policy for immediate post-release window: + - no feature merges to `main` + - only release-blocking hotfixes linked to stabilization backlog issue + - all hotfixes require rollback notes and validation evidence + +## Cross-Repo Release Matrix + +| Repository | Tag | Commit | +| --- | --- | --- | +| Sirius (main) | `v1.0.0` | `221b8001de3a580b7741f912cffa1ab8199d63e0` | +| app-scanner | `v1.0.0` | `7821c8ea73093f7fbc89bf4749e8e07a7c76f499` | + +## Rollback Reference + +If rollback is required: + +1. redeploy previous known-good image tags in compose inputs +2. restart stack and confirm service health checks (`/health`, UI `200`, gRPC port) +3. capture incident details and owner in stabilization backlog issue +4. roll forward with a hotfix PR after validation diff --git a/documentation/dev/operations/README.sdk-releases.md b/documentation/dev/operations/README.sdk-releases.md new file mode 100644 index 0000000..837f90b --- /dev/null +++ b/documentation/dev/operations/README.sdk-releases.md @@ -0,0 +1,974 @@ +--- +title: "SDK Release Process" +description: "Comprehensive guide for releasing new versions of the Sirius Go API SDK and updating dependent projects" +template: "TEMPLATE.documentation-standard" +llm_context: "high" +categories: ["operations", "sdk", "releases"] +tags: ["go-api", "versioning", "github-actions", "ci-cd", "deployment"] +related_docs: + - "../architecture/README.go-api-sdk.md" + - "README.development.md" + - "../../../minor-projects/go-api/README.md" +search_keywords: ["sdk", "release", "version", "deployment", "go-api", "dependencies", "breaking-changes"] +--- + +# SDK Release Process + +## Overview + +This document describes how to release new versions of the **Sirius Go API SDK** (`github.com/SiriusScan/go-api`) and propagate updates to dependent projects. + +**Key Concepts:** +- **Automated releases** via GitHub Actions CI/CD +- **Semantic versioning** for version management +- **Dependency updates** across multiple projects +- **Breaking change communication** via CHANGELOG + +## Quick Reference + +### Release New SDK Version + +```bash +# Automatic release (recommended) +cd /path/to/go-api +git add . +git commit -m "feat: add new feature" +git push origin main +# → CI/CD creates new patch version automatically + +# Manual version bump +git tag v0.0.12 +git push origin v0.0.12 +# → CI/CD creates GitHub release +``` + +### Update Dependent Project + +```bash +cd /path/to/dependent-project + +# Update go.mod version +# Change: github.com/SiriusScan/go-api v0.0.10 +# To: github.com/SiriusScan/go-api v0.0.11 + +go mod tidy +go build ./... # Verify build +go test ./... # Run tests + +git commit -am "chore: update go-api SDK to v0.0.11" +``` + +## Automated Release Process (Recommended) + +### How It Works + +The go-api repository has a GitHub Actions workflow (`.github/workflows/ci.yml`) that: + +1. **Triggers on push to `main` branch** +2. **Runs tests and linting** +3. **Auto-increments patch version** (v0.0.10 → v0.0.11) +4. **Creates Git tag** +5. **Generates GitHub release** with auto-generated notes +6. **Notifies main Sirius repo** via repository_dispatch event + +### Workflow File + +**Location:** `go-api/.github/workflows/ci.yml` + +**Jobs:** +- `test-and-lint`: Runs tests and linters +- `release`: Creates new version and release (only on main push) +- `notify-main-repo`: Sends notification to dependent repos + +### Step-by-Step Process + +#### Step 1: Make Changes to SDK + +```bash +cd /path/to/go-api +git checkout -b feature/my-changes + +# Make your changes +# - Edit code files +# - Add tests +# - Update documentation + +# Test locally +go test ./... +go build ./... +``` + +#### Step 2: Update CHANGELOG.md + +**Always update CHANGELOG.md** before releasing: + +```markdown +## [Unreleased] + +### Added +- New feature description + +### Fixed +- Bug fix description + +### Changed +- Modification description + +### BREAKING CHANGE (if applicable) +- Description of breaking change +- Migration guide +``` + +**Format:** Follow [Keep a Changelog](https://keepachangelog.com/) standard + +#### Step 3: Commit and Push + +```bash +# Stage changes +git add . + +# Commit with conventional commit message +git commit -m "feat: add new feature + +Detailed description of changes... + +BREAKING CHANGE: Field renamed +- OldField → NewField +- Update code to use NewField" + +# Push to trigger CI/CD +git push origin main +``` + +#### Step 4: Monitor CI/CD + +1. **Check GitHub Actions**: Go to `github.com/SiriusScan/go-api/actions` +2. **Wait for workflows to complete**: + - ✅ `test-and-lint` must pass + - ✅ `release` creates new tag + - ✅ `notify-main-repo` sends notification +3. **Verify new release**: Check `github.com/SiriusScan/go-api/releases` + +#### Step 5: Verify Release + +```bash +# Fetch new tags +git fetch --tags + +# Check latest tag +git tag -l "v*" --sort=-version:refname | head -1 +# Should show new version (e.g., v0.0.11) + +# View release on GitHub +# https://github.com/SiriusScan/go-api/releases/latest +``` + +**Expected Results:** +- ✅ New Git tag created (e.g., `v0.0.11`) +- ✅ GitHub release with auto-generated notes +- ✅ Release includes commit history since last version +- ✅ CI/CD tests passed + +## Manual Release Process + +### When to Use + +- **Major/minor version bumps** (e.g., v0.0.x → v0.1.0) +- **Pre-release versions** (e.g., v0.1.0-beta.1) +- **CI/CD failures** (automated release fails) +- **Hotfix releases** (skip normal workflow) + +### Step 1: Determine New Version + +**Semantic Versioning Rules:** +- **MAJOR** (x.0.0): Breaking changes, incompatible API +- **MINOR** (0.x.0): New features, backward compatible +- **PATCH** (0.0.x): Bug fixes, backward compatible + +**Examples:** +- `v0.0.10` → `v0.0.11` (bug fix) +- `v0.0.11` → `v0.1.0` (new feature, major milestone) +- `v0.1.0` → `v1.0.0` (stable API, breaking changes) + +### Step 2: Create Tag + +```bash +cd /path/to/go-api + +# Ensure main is up to date +git checkout main +git pull origin main + +# Create annotated tag +git tag -a v0.1.0 -m "Release v0.1.0 + +New Features: +- Feature 1 +- Feature 2 + +Bug Fixes: +- Fix 1 +- Fix 2" + +# Push tag +git push origin v0.1.0 +``` + +### Step 3: Create GitHub Release + +**Option A: Automatic (via CI/CD)** +- Pushing the tag triggers `release` workflow +- GitHub release auto-generated + +**Option B: Manual** +1. Go to `github.com/SiriusScan/go-api/releases/new` +2. Select tag: `v0.1.0` +3. Set title: `v0.1.0` +4. Add release notes (copy from CHANGELOG.md) +5. Click "Publish release" + +### Step 4: Verify + +```bash +# Check tag exists +git ls-remote --tags origin | grep v0.1.0 + +# View release +curl -s https://api.github.com/repos/SiriusScan/go-api/releases/latest | jq .tag_name +``` + +## Updating Dependent Projects + +### Identifying Dependents + +**Known projects using go-api:** +- `app-scanner` - Port scanning engine +- `app-agent` - Agent management system +- `sirius-api` (via container) - REST API server +- `sirius-engine` (via container) - Core scanning engine + +**Find all dependents:** +```bash +cd /path/to/Sirius-Project +grep -r "github.com/SiriusScan/go-api" . --include="go.mod" +``` + +### Update Process for Each Project + +#### Step 1: Update go.mod + +**File:** `project/go.mod` + +**Before:** +```go +module github.com/SiriusScan/app-scanner + +replace github.com/SiriusScan/go-api => ../go-api //Development + +require ( + github.com/SiriusScan/go-api v0.0.10 // Old version + // ... other dependencies +) +``` + +**After:** +```go +module github.com/SiriusScan/app-scanner + +replace github.com/SiriusScan/go-api => ../go-api //Development + +require ( + github.com/SiriusScan/go-api v0.0.11 // New version + // ... other dependencies +) +``` + +**Notes:** +- Keep `replace` directive for local development +- Update only the version number in `require` + +#### Step 2: Download Dependencies + +```bash +cd /path/to/dependent-project + +# Update dependencies +go mod tidy + +# Verify go.sum updated +git diff go.sum +``` + +#### Step 3: Check for Breaking Changes + +**Read CHANGELOG.md** in go-api: +```bash +cat ../go-api/CHANGELOG.md +``` + +**Look for:** +- `BREAKING CHANGE:` sections +- Renamed fields/functions +- Removed functionality +- Schema changes + +#### Step 4: Update Code + +**Example: Port.ID → Port.Number breaking change** + +**Find all references:** +```bash +grep -rn "port\.ID" . --include="*.go" +``` + +**Update code:** +```go +// Before (v0.0.10) +ports := make([]int, len(host.Ports)) +for i, port := range host.Ports { + ports[i] = port.ID // ❌ Field removed +} + +// After (v0.0.11) +ports := make([]int, len(host.Ports)) +for i, port := range host.Ports { + ports[i] = port.Number // ✅ New field name +} +``` + +#### Step 5: Test Build + +```bash +# Build project +go build -o /dev/null . + +# If build fails, fix compilation errors +# Usually related to renamed/removed fields +``` + +#### Step 6: Run Tests + +```bash +# Run unit tests +go test ./... + +# Run integration tests (if applicable) +go test ./... -tags=integration +``` + +#### Step 7: Commit Changes + +```bash +git add go.mod go.sum + +# If code changes needed +git add path/to/changed/files.go + +# Commit +git commit -m "chore: update go-api SDK to v0.0.11 + +Updates for go-api v0.0.11 breaking changes: +- Fixed port.ID references to port.Number +- Updated dependency version +- Verified build and tests pass + +Breaking changes in go-api v0.0.11: +- Port.ID renamed to Port.Number +- See go-api CHANGELOG.md for details" + +git push origin main +``` + +### Container-Based Projects + +**Projects:** `sirius-api`, `sirius-engine` + +These projects run in Docker containers and use **replace directives with volume mounts**. + +#### docker-compose.dev.yaml Configuration + +```yaml +services: + sirius-engine: + volumes: + - ../minor-projects/go-api:/go-api:ro + - ../minor-projects/app-scanner:/app-scanner +``` + +#### go.mod in Container + +```go +replace github.com/SiriusScan/go-api => /go-api +``` + +#### Update Process + +**Changes to go-api are automatically visible** in containers due to volume mount. No version update needed during development. + +**For production builds:** +1. Update go.mod version (same as above) +2. Rebuild Docker images +3. Deploy new images + +**Restart containers to reload code:** +```bash +docker compose -f docker-compose.dev.yaml restart sirius-engine +docker compose -f docker-compose.dev.yaml restart sirius-api +``` + +## Breaking Changes + +### Definition + +**A breaking change is any modification that requires code changes in dependent projects.** + +**Examples:** +- ✅ Renaming exported fields (e.g., `Port.ID` → `Port.Number`) +- ✅ Changing function signatures +- ✅ Removing exported types/functions +- ✅ Changing return types +- ✅ Database schema changes (non-backward-compatible) +- ❌ Adding new fields (backward compatible) +- ❌ Adding new functions (backward compatible) +- ❌ Internal implementation changes (not breaking) + +### Communicating Breaking Changes + +#### 1. Commit Message + +Use **conventional commit format** with `BREAKING CHANGE:` footer: + +``` +feat: rename Port.ID to Port.Number + +This resolves conflict with GORM auto-increment ID field. + +BREAKING CHANGE: Port.ID renamed to Port.Number +- Update all references from port.ID to port.Number +- Port numbers now stored in Number field +- Database migration required (see migrations/005) +``` + +#### 2. CHANGELOG.md + +Document in CHANGELOG with clear migration guide: + +```markdown +## [0.0.11] - 2025-10-26 + +### Fixed + +#### 🔴 CRITICAL: Port.ID Schema Conflict + +- **BREAKING CHANGE:** Renamed `Port.ID` field to `Port.Number` + - `Port.ID int` → `Port.Number int` + - Resolves duplicate key violations + +### Upgrading + +**Before:** +```go +port := sirius.Port{ID: 22, Protocol: "tcp"} +``` + +**After:** +```go +port := sirius.Port{Number: 22, Protocol: "tcp"} +``` +``` + +#### 3. GitHub Release Notes + +Include breaking changes prominently: + +```markdown +# v0.0.11 + +## ⚠️ BREAKING CHANGES + +### Port.ID → Port.Number + +The `Port.ID` field has been renamed to `Port.Number` to resolve database conflicts. + +**Migration Required:** +- Update all `port.ID` references to `port.Number` +- Run database migration 005 +- See CHANGELOG.md for details + +## What's Changed +- Full list of changes... +``` + +#### 4. Migration Guide + +Create detailed migration guide in SDK docs: + +**File:** `go-api/docs/migrations/v0.0.10-to-v0.0.11.md` + +```markdown +# Migrating from v0.0.10 to v0.0.11 + +## Breaking Changes + +### 1. Port.ID → Port.Number + +**Find affected code:** +```bash +grep -rn "port\.ID" . --include="*.go" +``` + +**Update pattern:** +- Replace `port.ID` with `port.Number` +- Replace `Port{ID:` with `Port{Number:` + +## Database Migration + +Run migration script: +```bash +docker exec sirius-engine bash -c "cd /tmp/migrations && go run 005_fix_critical_schema_issues/main.go" +``` + +## Verification + +1. Build succeeds: `go build ./...` +2. Tests pass: `go test ./...` +3. No compilation errors +``` + +### Version Bumping Strategy + +**Pre-1.0.0 (current):** +- Breaking changes can occur in patch releases +- Document clearly in CHANGELOG +- Notify dependent project maintainers + +**Post-1.0.0 (future):** +- Breaking changes ONLY in major versions +- Deprecation warnings before removal +- Longer support windows for old versions + +## Automation Scripts + +### Script 1: Update Dependents + +**File:** `go-api/scripts/update-dependents.sh` + +```bash +#!/bin/bash +# Update go-api version across all dependent projects + +set -e + +NEW_VERSION=$1 +if [ -z "$NEW_VERSION" ]; then + echo "Usage: $0 " + echo "Example: $0 v0.0.11" + exit 1 +fi + +PROJECTS=("app-scanner" "app-agent") +BASE_DIR="$(cd "$(dirname "$0")/../.." && pwd)" + +echo "🚀 Updating go-api to $NEW_VERSION across dependent projects..." + +for project in "${PROJECTS[@]}"; do + PROJECT_PATH="$BASE_DIR/minor-projects/$project" + + if [ ! -d "$PROJECT_PATH" ]; then + echo "⚠️ Project $project not found at $PROJECT_PATH" + continue + fi + + echo "" + echo "📦 Updating $project..." + cd "$PROJECT_PATH" + + # Update go.mod + sed -i '' "s|github.com/SiriusScan/go-api v[0-9.]*|github.com/SiriusScan/go-api $NEW_VERSION|g" go.mod + + # Run go mod tidy + go mod tidy + + # Test build + echo " 🔨 Testing build..." + if go build -o /dev/null .; then + echo " ✅ Build successful" + else + echo " ❌ Build failed - manual intervention required" + continue + fi + + # Run tests + echo " 🧪 Running tests..." + if go test ./... -short; then + echo " ✅ Tests passed" + else + echo " ⚠️ Tests failed - review required" + fi + + # Commit changes + git add go.mod go.sum + git commit -m "chore: update go-api SDK to $NEW_VERSION" || echo " ℹ️ No changes to commit" + + echo " ✅ $project updated successfully" +done + +echo "" +echo "✅ All projects updated to go-api $NEW_VERSION" +echo "" +echo "Next steps:" +echo " 1. Review and test changes manually" +echo " 2. Push commits: git push origin main" +echo " 3. Monitor dependent project CI/CD" +``` + +**Usage:** +```bash +cd /path/to/go-api +./scripts/update-dependents.sh v0.0.11 +``` + +### Script 2: Check Versions + +**File:** `go-api/scripts/check-versions.sh` + +```bash +#!/bin/bash +# Check which version of go-api each dependent project is using + +BASE_DIR="$(cd "$(dirname "$0")/../.." && pwd)" +PROJECTS=("app-scanner" "app-agent") + +echo "📊 go-api version check across projects" +echo "========================================" +echo "" + +# Get latest go-api version +cd "$BASE_DIR/minor-projects/go-api" +LATEST_VERSION=$(git tag -l "v*" --sort=-version:refname | head -1) +echo "Latest go-api version: $LATEST_VERSION" +echo "" + +for project in "${PROJECTS[@]}"; do + PROJECT_PATH="$BASE_DIR/minor-projects/$project" + + if [ ! -f "$PROJECT_PATH/go.mod" ]; then + echo "⚠️ $project: go.mod not found" + continue + fi + + CURRENT_VERSION=$(grep "github.com/SiriusScan/go-api" "$PROJECT_PATH/go.mod" | grep -v "replace" | awk '{print $2}') + + if [ "$CURRENT_VERSION" == "$LATEST_VERSION" ]; then + echo "✅ $project: $CURRENT_VERSION (up to date)" + else + echo "⚠️ $project: $CURRENT_VERSION (outdated, latest: $LATEST_VERSION)" + fi +done + +echo "" +echo "To update a project:" +echo " ./scripts/update-dependents.sh $LATEST_VERSION" +``` + +**Usage:** +```bash +cd /path/to/go-api +./scripts/check-versions.sh +``` + +## Testing & Verification + +### Pre-Release Testing + +**Before releasing SDK:** + +1. **Unit tests pass:** + ```bash + cd go-api + go test ./... + ``` + +2. **Lint checks pass:** + ```bash + golangci-lint run + ``` + +3. **Build succeeds:** + ```bash + go build ./... + ``` + +4. **Local integration test:** + ```bash + cd ../app-scanner + # Ensure replace directive active + go build . + go test ./... + ``` + +### Post-Release Verification + +**After releasing SDK:** + +1. **Version tag exists:** + ```bash + git ls-remote --tags origin | grep v0.0.11 + ``` + +2. **GitHub release created:** + - Visit: `https://github.com/SiriusScan/go-api/releases/latest` + - Verify: Tag, release notes, timestamp + +3. **Module available:** + ```bash + go list -m github.com/SiriusScan/go-api@v0.0.11 + ``` + +4. **Dependent project builds:** + ```bash + cd app-scanner + go get github.com/SiriusScan/go-api@v0.0.11 + go build . + ``` + +### Integration Testing + +**Full scan pipeline test:** + +```bash +# Start all services +docker compose -f docker-compose.dev.yaml up -d + +# Submit test scan +docker exec sirius-rabbitmq rabbitmqadmin publish \ + exchange=amq.default routing_key=scan \ + payload='{"id":"sdk-test","targets":[{"value":"192.168.1.100","type":"single_ip"}],"options":{"template_id":"quick"},"priority":3}' + +# Monitor logs +docker logs --follow sirius-engine | grep -i "error\|duplicate" +docker logs --follow sirius-postgres | grep -i "error\|duplicate" + +# Check results +docker exec sirius-api curl http://localhost:8080/hosts +``` + +**Success criteria:** +- ✅ Scan completes without errors +- ✅ No database constraint violations +- ✅ Data stored correctly in database +- ✅ All containers running stably + +## Troubleshooting + +### Issue: CI/CD Release Fails + +**Symptoms:** +- GitHub Actions workflow fails +- No new tag/release created + +**Solutions:** + +1. **Check workflow logs:** + - Go to `github.com/SiriusScan/go-api/actions` + - Click failed workflow + - Review error messages + +2. **Common causes:** + - Tests failing → Fix tests + - Lint errors → Run `golangci-lint run` locally + - Permission issues → Check GitHub token permissions + +3. **Manual workaround:** + - Create tag manually (see Manual Release Process) + - Skip automated release + +### Issue: Dependent Project Won't Build + +**Symptoms:** +``` +go: github.com/SiriusScan/go-api@v0.0.11: invalid version: unknown revision v0.0.11 +``` + +**Solutions:** + +1. **Check version exists:** + ```bash + git ls-remote --tags https://github.com/SiriusScan/go-api | grep v0.0.11 + ``` + +2. **Clear Go module cache:** + ```bash + go clean -modcache + go mod download + ``` + +3. **Use replace directive temporarily:** + ```go + replace github.com/SiriusScan/go-api => ../go-api + ``` + +### Issue: Breaking Changes Cause Errors + +**Symptoms:** +``` +port.ID undefined (type sirius.Port has no field or method ID) +``` + +**Solutions:** + +1. **Read CHANGELOG:** + ```bash + cat ../go-api/CHANGELOG.md | grep -A 10 "BREAKING CHANGE" + ``` + +2. **Find all affected code:** + ```bash + grep -rn "port\.ID" . --include="*.go" + ``` + +3. **Apply migration:** + - Follow migration guide in CHANGELOG + - Update all references + - Test build: `go build ./...` + +### Issue: Database Schema Mismatch + +**Symptoms:** +``` +ERROR: column "id" does not exist in table "ports" +``` + +**Solutions:** + +1. **Run database migration:** + ```bash + docker exec sirius-engine bash -c "cd /tmp/migrations && go run 005_fix_critical_schema_issues/main.go" + ``` + +2. **Verify migration applied:** + ```bash + docker exec sirius-postgres psql -U postgres -d sirius -c "\d ports" + ``` + +3. **If migration fails:** + - Backup database + - Drop and recreate schema + - Re-run scans to populate data + +## Rollback Procedures + +### Rolling Back SDK Release + +**If new release causes critical issues:** + +1. **Identify previous stable version:** + ```bash + git tag -l "v*" --sort=-version:refname | head -5 + # Example: v0.0.11 (broken), v0.0.10 (last stable) + ``` + +2. **Revert main branch:** + ```bash + cd go-api + git revert # Commit that introduced issues + git push origin main + ``` + +3. **Create hotfix release:** + ```bash + git tag v0.0.12 + git push origin v0.0.12 + # CI/CD creates new release with reverted changes + ``` + +4. **Update dependent projects:** + ```bash + ./scripts/update-dependents.sh v0.0.12 + ``` + +### Rolling Back Dependent Project + +**If update breaks a dependent project:** + +1. **Revert go.mod:** + ```bash + cd app-scanner + git checkout HEAD~1 go.mod go.sum + ``` + +2. **Restore dependencies:** + ```bash + go mod download + ``` + +3. **Test:** + ```bash + go build ./... + go test ./... + ``` + +4. **Commit rollback:** + ```bash + git commit -am "revert: rollback go-api to v0.0.10 due to issues" + git push origin main + ``` + +## Best Practices + +### Development + +- ✅ **Always update CHANGELOG.md** before releasing +- ✅ **Use conventional commits** for clear history +- ✅ **Test locally** with replace directive first +- ✅ **Run full test suite** before releasing +- ✅ **Document breaking changes** prominently +- ✅ **Create migration guides** for major changes +- ❌ **Don't skip pre-release testing** +- ❌ **Don't make breaking changes without warning** + +### Release Management + +- ✅ **Use semantic versioning** correctly +- ✅ **Let CI/CD handle releases** (automated) +- ✅ **Verify release succeeds** before updating dependents +- ✅ **Update all dependents together** (avoid version drift) +- ✅ **Monitor dependent project CI/CD** after updates +- ❌ **Don't skip version numbers** +- ❌ **Don't release without testing** + +### Communication + +- ✅ **Announce breaking changes** in advance +- ✅ **Provide migration guides** for complex changes +- ✅ **Update documentation** with releases +- ✅ **Tag team members** in PRs with breaking changes +- ❌ **Don't surprise teams** with undocumented changes + +## References + +### Related Documentation + +- [Go API SDK Architecture](../architecture/README.go-api-sdk.md) - SDK design and structure +- [Development Workflow](README.development.md) - General development practices +- [go-api README](../../../minor-projects/go-api/README.md) - SDK quick start +- [go-api CHANGELOG](../../../minor-projects/go-api/CHANGELOG.md) - Version history + +### External Resources + +- [Semantic Versioning](https://semver.org/) +- [Keep a Changelog](https://keepachangelog.com/) +- [Conventional Commits](https://www.conventionalcommits.org/) +- [GitHub Actions](https://docs.github.com/en/actions) + +--- + +**Last Updated:** 2025-10-26 +**Process Owner:** Sirius DevOps Team +**Review Schedule:** Quarterly + + + + + + diff --git a/documentation/dev/operations/README.tasks.md b/documentation/dev/operations/README.tasks.md new file mode 100644 index 0000000..f864e39 --- /dev/null +++ b/documentation/dev/operations/README.tasks.md @@ -0,0 +1,366 @@ +--- +title: "Task Management System" +description: "Guidelines for managing development tasks using the JSON-based task system for project tracking and progress monitoring." +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Development Team" +tags: ["task-management", "project-tracking", "development-workflow"] +categories: ["operations", "development"] +difficulty: "beginner" +prerequisites: ["json", "project-structure"] +related_docs: + - "README.new-project.md" + - "README.git-operations.md" +dependencies: [] +llm_context: "high" +search_keywords: + [ + "task management", + "tasks.json", + "project tracking", + "development workflow", + "task status", + ] +--- + +# Task Management System + +> **📚 New Projects**: For project initialization workflow, see [README.new-project.md](README.new-project.md) + +## Purpose + +This document provides guidelines for managing development tasks using our JSON-based task system. It ensures consistent task tracking, progress monitoring, and project completion across all development efforts. + +## When to Use This System + +- **Working on any project** with a `tasks/{project-name}.json` file +- **Tracking progress** on development sprints +- **Managing dependencies** between related tasks +- **Planning work** and estimating completion +- **Reporting status** to stakeholders + +## Core Principles + +### 1. Always Check Your Tasks + +- **Start each work session** by reviewing the current task file +- **Understand dependencies** before starting work +- **Check task status** to see what's been completed +- **Identify next steps** based on available tasks + +### 2. Mark Tasks Complete + +- **Update status immediately** when a task is finished +- **Verify completion** using the test strategy +- **Update dependent tasks** if completion affects them +- **Commit changes** to the task file with your code + +### 3. Ask for Support When Needed + +- **Request clarification** on unclear requirements +- **Ask for help** when blocked or uncertain +- **Escalate issues** that prevent progress +- **Get approval** for significant scope changes + +## Task Status Management + +### Status Values + +| Status | Description | When to Use | +| ------------- | ------------------------- | ------------------------------------ | +| `pending` | Task not started | Default for new tasks | +| `in_progress` | Currently being worked on | When actively working | +| `done` | Completed successfully | When task is finished | +| `blocked` | Cannot proceed | When waiting for external dependency | + +### Status Updates + +```json +{ + "id": "1.2", + "title": "Implement User Authentication", + "status": "in_progress", // ← Update this as work progresses + "priority": "high", + "dependencies": ["1.1"] +} +``` + +**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` + +## Task Dependencies + +### Understanding Dependencies + +Tasks can depend on other tasks being completed first: + +```json +{ + "id": "2.1", + "title": "Create Database Schema", + "dependencies": ["1.1", "1.2"] // ← Must complete 1.1 AND 1.2 first +} +``` + +### Dependency Rules + +- **Check dependencies** before starting any task +- **Only work on tasks** with completed dependencies +- **Update dependent tasks** when you complete a task +- **Resolve circular dependencies** immediately + +### Dependency Resolution + +```bash +# Check what tasks are available to work on +# Look for tasks with status "pending" and no incomplete dependencies + +# Example: Task 2.1 depends on 1.1 and 1.2 +# - If 1.1 is "done" and 1.2 is "done" → Task 2.1 is available +# - If 1.1 is "pending" or 1.2 is "blocked" → Task 2.1 is not available +``` + +## Task File Structure + +### Main Task Structure + +```json +{ + "id": "1", + "title": "PHASE 1: Core Implementation", + "description": "Brief description of the phase", + "details": "Detailed implementation notes and expected outputs", + "status": "pending", + "priority": "high", + "dependencies": [], + "subtasks": [ + { + "id": "1.1", + "title": "Specific Implementation Task", + "description": "What this task accomplishes", + "details": "Implementation details, acceptance criteria, and context", + "status": "pending", + "priority": "high", + "dependencies": [], + "testStrategy": "How to verify this task is complete" + } + ] +} +``` + +### Subtask Structure + +```json +{ + "id": "1.2", + "title": "Implement User Authentication", + "description": "Add login/logout functionality to the application", + "details": "Create authentication endpoints, middleware, and UI components. Use JWT tokens for session management. Include password hashing and validation.", + "status": "pending", + "priority": "high", + "dependencies": ["1.1"], + "testStrategy": "Test login with valid/invalid credentials, verify JWT token generation, confirm logout clears session" +} +``` + +## Working with Tasks + +### Daily Workflow + +1. **Review task file** at start of work session +2. **Identify available tasks** (pending status, dependencies met) +3. **Select highest priority** available task +4. **Update status** to `in_progress` +5. **Work on task** following details and test strategy +6. **Mark complete** when finished +7. **Commit changes** to both code and task file + +### Task Selection Guidelines + +**Priority Order:** + +1. **High priority** tasks first +2. **Medium priority** tasks second +3. **Low priority** tasks last + +**Dependency Order:** + +1. **No dependencies** first +2. **Fewer dependencies** before more complex ones +3. **Blocking tasks** before dependent tasks + +### Example Work Session + +```bash +# 1. Check current tasks +cat tasks/feature-development.json | jq '.[] | select(.status == "pending")' + +# 2. Find available tasks (no incomplete dependencies) +# Look for tasks with status "pending" and all dependencies "done" + +# 3. Start work on selected task +# Update status to "in_progress" in task file + +# 4. Complete work +# Update status to "done" in task file +# Commit both code and task file changes + +git add . +git commit -m "feat: implement user authentication + +- Add JWT-based authentication system +- Create login/logout endpoints +- Update task 1.2 to done status" +``` + +## 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 + +### File Validation + +Ensure task files maintain proper structure: + +```json +// Valid task structure +{ + "id": "string", // Required: Unique identifier + "title": "string", // Required: Clear task name + "description": "string", // Required: Brief summary + "details": "string", // Required: Implementation notes + "status": "string", // Required: pending|in_progress|done|blocked + "priority": "string", // Required: high|medium|low + "dependencies": ["array"], // Required: Array of task IDs + "subtasks": [ + // Optional: For main tasks only + { + "id": "string", + "title": "string", + "description": "string", + "details": "string", + "status": "string", + "priority": "string", + "dependencies": ["array"], + "testStrategy": "string" // Required for subtasks + } + ] +} +``` + +## Integration with Development Tools + +### Cursor Integration + +When working with tasks, Cursor will: + +- **Include task files** in context for relevant projects +- **Reference task details** when discussing implementation +- **Update task status** when completing work +- **Check dependencies** before suggesting work + +### Git Integration + +- **Commit task changes** with code changes +- **Reference task IDs** in commit messages +- **Track progress** through commit history +- **Maintain task history** across branches + +## Common Patterns + +### Task Completion Pattern + +```bash +# 1. Complete the work +# 2. Test using testStrategy +# 3. Update task status +# 4. Check dependent tasks +# 5. Commit changes + +git add . +git commit -m "feat: complete task 1.2 - user authentication + +- Implemented JWT-based auth system +- Added login/logout endpoints +- Updated task status to done +- Ready for dependent tasks" +``` + +### Dependency Resolution Pattern + +```bash +# When completing a task that others depend on: +# 1. Mark current task as done +# 2. Check what tasks depend on this one +# 3. Update dependent tasks if needed +# 4. Notify team of newly available tasks +``` + +### Blocked Task Pattern + +```bash +# When encountering a blocker: +# 1. Update task status to "blocked" +# 2. Add details about the blocker +# 3. Identify resolution steps +# 4. Work on other available tasks +# 5. Return when blocker is resolved +``` + +## Troubleshooting + +### Common Issues + +**Task file not found:** + +- Verify file exists in `tasks/` directory +- Check filename matches project name +- Ensure JSON syntax is valid + +**Invalid task status:** + +- Use only: `pending`, `in_progress`, `done`, `blocked` +- Check for typos in status values +- Validate JSON structure + +**Circular dependencies:** + +- Review dependency chains +- Break circular references +- Restructure task dependencies + +**Missing test strategy:** + +- Add testStrategy field to subtasks +- Include specific verification steps +- Make tests measurable and clear + +### Getting Help + +- **Task questions**: Ask for clarification on requirements +- **Dependency issues**: Request help resolving conflicts +- **Status updates**: Confirm completion criteria +- **File problems**: Verify JSON syntax and structure + +## Future Enhancements + +This task management system will evolve based on team needs: + +- **Automated status tracking** based on commit messages +- **Dependency visualization** tools +- **Progress reporting** dashboards +- **Integration** with project management tools +- **Notification system** for task updates + +--- + +_This task management system ensures consistent progress tracking and project completion. Always check your tasks, mark them complete, and ask for support when needed._ diff --git a/documentation/dev/operations/README.terraform-deployment.md b/documentation/dev/operations/README.terraform-deployment.md new file mode 100644 index 0000000..e15c133 --- /dev/null +++ b/documentation/dev/operations/README.terraform-deployment.md @@ -0,0 +1,995 @@ +--- +title: "Terraform Cloud Deployment Guide" +description: "Complete guide for deploying Sirius to AWS using Terraform Infrastructure as Code" +template: "TEMPLATE.guide" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Development Team" +tags: ["terraform", "aws", "deployment", "infrastructure", "cloud"] +categories: ["deployment", "infrastructure"] +difficulty: "intermediate" +prerequisites: ["docker", "aws-cli", "terraform"] +related_docs: ["README.development.md", "README.architecture.md"] +dependencies: ["docker-compose.yaml", "infrastructure/"] +llm_context: "high" +search_keywords: + ["terraform", "aws", "deployment", "infrastructure", "cloud", "ec2", "docker"] +--- + +# Terraform Cloud Deployment Guide + +## Purpose + +This guide provides comprehensive instructions for deploying Sirius to AWS using Terraform Infrastructure as Code. It covers everything from initial setup to production deployment, based on the proven infrastructure patterns from the sirius-demo project. + +## When to Use This Guide + +- **Production deployments** - Deploying Sirius to AWS for production use +- **Staging environments** - Creating isolated testing environments +- **Demo environments** - Setting up temporary demo instances +- **Infrastructure automation** - Managing infrastructure as code +- **Cloud migration** - Moving from local Docker to cloud deployment + +## Prerequisites + +### Required Tools + +- **Terraform** >= 1.0.0 +- **AWS CLI** >= 2.0.0 +- **Docker** >= 20.10.0 (for local testing) +- **Git** >= 2.0.0 + +### AWS Requirements + +- AWS account with appropriate permissions +- EC2, VPC, IAM, and S3 access +- Default VPC or custom VPC/subnet configuration + +### Knowledge Prerequisites + +- Basic understanding of Terraform +- AWS fundamentals (EC2, VPC, Security Groups) +- Docker and Docker Compose +- Linux command line + +## Quick Start + +### 1. Clone and Setup + +```bash +# Clone the repository +git clone https://github.com/SiriusScan/Sirius.git +cd Sirius + +# Create infrastructure directory +mkdir -p infrastructure/aws +cd infrastructure/aws +``` + +### 2. Basic Terraform Configuration + +Create `main.tf`: + +```hcl +terraform { + required_version = ">= 1.0.0" + + required_providers { + aws = { + source = "hashicorp/aws" + version = "~> 5.0" + } + } +} + +provider "aws" { + region = var.aws_region + + default_tags { + tags = var.common_tags + } +} + +# Data source for latest Ubuntu 22.04 LTS AMI +data "aws_ami" "ubuntu" { + most_recent = true + owners = ["099720109477"] # Canonical + + filter { + name = "name" + values = ["ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*"] + } + + filter { + name = "virtualization-type" + values = ["hvm"] + } +} + +# Security Group for Sirius +resource "aws_security_group" "sirius" { + name = "sirius-sg" + description = "Security group for Sirius deployment" + vpc_id = var.vpc_id + + # UI access + ingress { + description = "UI Access" + from_port = 3000 + to_port = 3000 + protocol = "tcp" + cidr_blocks = var.allowed_cidrs + } + + # API access + ingress { + description = "API Access" + from_port = 9001 + to_port = 9001 + protocol = "tcp" + cidr_blocks = var.allowed_cidrs + } + + # HTTP/HTTPS for load balancer + ingress { + description = "HTTP" + from_port = 80 + to_port = 80 + protocol = "tcp" + cidr_blocks = var.allowed_cidrs + } + + ingress { + description = "HTTPS" + from_port = 443 + to_port = 443 + protocol = "tcp" + cidr_blocks = var.allowed_cidrs + } + + # SSH access (optional) + ingress { + description = "SSH" + from_port = 22 + to_port = 22 + protocol = "tcp" + cidr_blocks = var.ssh_cidrs + } + + # All outbound traffic + egress { + description = "All outbound traffic" + from_port = 0 + to_port = 0 + protocol = "-1" + cidr_blocks = ["0.0.0.0/0"] + } + + tags = { + Name = "sirius-sg" + } +} + +# IAM role for EC2 instance +resource "aws_iam_role" "sirius_instance" { + name = "sirius-instance-role" + + assume_role_policy = jsonencode({ + Version = "2012-10-17" + Statement = [ + { + Action = "sts:AssumeRole" + Effect = "Allow" + Principal = { + Service = "ec2.amazonaws.com" + } + } + ] + }) + + tags = { + Name = "sirius-instance-role" + } +} + +# Attach SSM managed policy +resource "aws_iam_role_policy_attachment" "ssm_managed_instance" { + role = aws_iam_role.sirius_instance.name + policy_arn = "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore" +} + +# Attach CloudWatch policy +resource "aws_iam_role_policy_attachment" "cloudwatch_agent" { + role = aws_iam_role.sirius_instance.name + policy_arn = "arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy" +} + +# Instance profile +resource "aws_iam_instance_profile" "sirius" { + name = "sirius-instance-profile" + role = aws_iam_role.sirius_instance.name + + tags = { + Name = "sirius-instance-profile" + } +} + +# EC2 Instance +resource "aws_instance" "sirius" { + ami = data.aws_ami.ubuntu.id + instance_type = var.instance_type + subnet_id = var.subnet_id + + vpc_security_group_ids = [aws_security_group.sirius.id] + iam_instance_profile = aws_iam_instance_profile.sirius.name + + root_block_device { + volume_type = "gp3" + volume_size = var.root_volume_size + delete_on_termination = true + encrypted = true + } + + user_data = templatefile("${path.module}/user_data.sh", { + sirius_repo_url = var.sirius_repo_url + sirius_branch = var.sirius_branch + environment = var.environment + }) + + user_data_replace_on_change = true + + tags = { + Name = "sirius-${var.environment}" + } +} +``` + +### 3. Variables Configuration + +Create `variables.tf`: + +```hcl +variable "aws_region" { + description = "AWS region for deployment" + type = string + default = "us-east-1" +} + +variable "instance_type" { + description = "EC2 instance type" + type = string + default = "t3.medium" +} + +variable "root_volume_size" { + description = "Root EBS volume size in GB" + type = number + default = 30 +} + +variable "vpc_id" { + description = "VPC ID where Sirius will be deployed" + type = string +} + +variable "subnet_id" { + description = "Subnet ID for Sirius instance" + type = string +} + +variable "allowed_cidrs" { + description = "CIDR blocks allowed to access Sirius" + type = list(string) + default = ["0.0.0.0/0"] +} + +variable "ssh_cidrs" { + description = "CIDR blocks allowed SSH access" + type = list(string) + default = ["0.0.0.0/0"] +} + +variable "sirius_repo_url" { + description = "Sirius repository URL" + type = string + default = "https://github.com/SiriusScan/Sirius.git" +} + +variable "sirius_branch" { + description = "Git branch to deploy" + type = string + default = "main" +} + +variable "environment" { + description = "Environment name (dev, staging, prod)" + type = string + default = "dev" +} + +variable "common_tags" { + description = "Common tags for all resources" + type = map(string) + default = { + Project = "Sirius" + Environment = "dev" + ManagedBy = "Terraform" + } +} +``` + +### 4. Outputs Configuration + +Create `outputs.tf`: + +```hcl +output "instance_id" { + description = "EC2 instance ID" + value = aws_instance.sirius.id +} + +output "instance_public_ip" { + description = "Public IP address of Sirius instance" + value = aws_instance.sirius.public_ip +} + +output "instance_public_dns" { + description = "Public DNS name of Sirius instance" + value = aws_instance.sirius.public_dns +} + +output "ui_url" { + description = "URL to access Sirius UI" + value = "http://${aws_instance.sirius.public_ip}:3000" +} + +output "api_url" { + description = "URL to access Sirius API" + value = "http://${aws_instance.sirius.public_ip}:9001" +} + +output "ssh_command" { + description = "SSH command to connect to instance" + value = "ssh -i ~/.ssh/your-key.pem ubuntu@${aws_instance.sirius.public_ip}" +} + +output "ssm_command" { + description = "AWS SSM Session Manager command" + value = "aws ssm start-session --target ${aws_instance.sirius.id} --region ${var.aws_region}" +} +``` + +### 5. Bootstrap Script + +Create `user_data.sh`: + +```bash +#!/bin/bash +set -e + +# Log all output +exec > >(tee -a /var/log/sirius-bootstrap.log) +exec 2>&1 + +echo "=========================================" +echo "Sirius Bootstrap Script" +echo "Started at: $(date)" +echo "Environment: ${environment}" +echo "=========================================" + +# Update system +echo "📦 Updating system packages..." +apt-get update -y +DEBIAN_FRONTEND=noninteractive apt-get upgrade -y + +# Install dependencies +echo "📦 Installing dependencies..." +apt-get install -y \ + git \ + jq \ + curl \ + ca-certificates \ + gnupg \ + lsb-release + +# Install Docker +echo "🐳 Installing Docker..." +install -m 0755 -d /etc/apt/keyrings +curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg +chmod a+r /etc/apt/keyrings/docker.gpg + +echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ + $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null + +apt-get update +apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin + +# Start Docker +echo "🐳 Starting Docker service..." +systemctl enable docker +systemctl start docker +usermod -aG docker ubuntu + +# Verify Docker +echo "✅ Verifying Docker installation..." +docker --version +docker compose version + +# Create application directory +echo "📁 Creating application directory..." +mkdir -p /opt/sirius +cd /opt/sirius + +# Clone repository +echo "📥 Cloning Sirius repository..." +echo "Repository: ${sirius_repo_url}" +echo "Branch: ${sirius_branch}" + +git clone --branch ${sirius_branch} ${sirius_repo_url} repo +cd repo + +# Create environment configuration using installer-first flow +echo "⚙️ Configuring environment..." +docker compose -f docker-compose.installer.yaml run --rm sirius-installer --non-interactive --no-print-secrets +echo "✅ Environment configuration created with installer" + +# Determine image tag from sirius_branch variable +if [[ "${sirius_branch}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + # Version tag (e.g., v0.4.1) + IMAGE_TAG="${sirius_branch}" +elif [ "${sirius_branch}" == "main" ]; then + # Main branch uses latest + IMAGE_TAG="latest" +else + # Default to latest + IMAGE_TAG="latest" +fi +export IMAGE_TAG +echo "📦 Using image tag: ${IMAGE_TAG}" + +# Pull Docker images from registry +echo "🐳 Pulling prebuilt images from GitHub Container Registry..." +docker compose pull || echo "⚠️ Some images may need to be built (fallback)" + +# Start services (uses prebuilt images by default) +echo "🚀 Starting Sirius services..." +echo "Starting services with prebuilt images (this should take 2-5 minutes)..." +docker compose up -d + +# Wait for services +echo "⏳ Waiting for services to initialize..." +sleep 30 + +# Show running containers +echo "📊 Running containers:" +docker compose ps + +echo "=========================================" +echo "Bootstrap completed at: $(date)" +echo "=========================================" +echo "" +echo "Access services:" +echo " UI: http://$(curl -s http://169.254.169.254/latest/meta-data/public-ipv4):3000" +echo " API: http://$(curl -s http://169.254.169.254/latest/meta-data/public-ipv4):9001" +echo "=========================================" +``` + +### 6. Terraform Variables File + +Create `terraform.tfvars`: + +```hcl +# AWS Configuration +aws_region = "us-east-1" + +# Network Configuration (REQUIRED) +vpc_id = "vpc-xxxxxxxxxxxxxxxxx" # Replace with your VPC ID +subnet_id = "subnet-xxxxxxxxxxxxxxxxx" # Replace with your subnet ID + +# Instance Configuration +instance_type = "t3.medium" +root_volume_size = 30 + +# Access Control +allowed_cidrs = ["0.0.0.0/0"] # Restrict for production +ssh_cidrs = ["0.0.0.0/0"] # Restrict for production + +# Repository Configuration +sirius_repo_url = "https://github.com/SiriusScan/Sirius.git" +sirius_branch = "main" +environment = "dev" + +# Resource Tags +common_tags = { + Project = "Sirius" + Environment = "dev" + ManagedBy = "Terraform" + Owner = "YourTeam" +} +``` + +## Container Registry Deployment + +Sirius now uses prebuilt container images from GitHub Container Registry (GHCR) by default, providing **60-75% faster deployments** (5-8 minutes vs 20-25 minutes). The base `docker-compose.yaml` automatically pulls images from `ghcr.io/siriusscan/sirius-{ui,api,engine}:{tag}`. + +### Image Tagging + +Images are automatically tagged based on the deployment: + +- **Version tags** (e.g., `v0.4.1`): Use when deploying specific releases +- **Latest tag**: Default for main branch deployments +- **Beta tag**: Available for beta releases + +### Environment Variable + +Control which images to use with the `IMAGE_TAG` environment variable in your bootstrap script: + +```bash +# In user_data.sh or .env file +export IMAGE_TAG="${sirius_branch:-latest}" +``` + +### Benefits + +- **Faster deployments**: 5-8 minutes vs 20-25 minutes +- **Reduced resource usage**: No compilation on EC2 instance +- **Consistent builds**: Same images tested in CI/CD +- **Easy updates**: Pull latest images without rebuilding + +### Fallback to Local Builds + +If registry images are unavailable, you can fall back to local builds by using `docker compose -f docker-compose.yaml -f docker-compose.build.yaml up -d --build` instead of `docker compose up -d`. + +For more details, see [Docker Container Deployment Guide](../deployment/README.docker-container-deployment.md). + +## Deployment Process + +### 1. Initialize Terraform + +```bash +# Initialize Terraform +terraform init + +# Validate configuration +terraform validate + +# Review planned changes +terraform plan +``` + +### 2. Deploy Infrastructure + +```bash +# Apply configuration +terraform apply + +# Confirm with 'yes' when prompted +# Or use -auto-approve for automated deployment +terraform apply -auto-approve +``` + +### 3. Access Your Deployment + +After deployment completes, Terraform will output the URLs: + +```bash +# Get outputs +terraform output + +# Access UI +open http://$(terraform output -raw instance_public_ip):3000 + +# Check API health +curl http://$(terraform output -raw instance_public_ip):9001/health +``` + +## Advanced Configuration + +### Production Deployment + +For production deployments, consider these enhancements: + +#### 1. State Management + +Create `backend.tf`: + +```hcl +terraform { + backend "s3" { + bucket = "your-terraform-state-bucket" + key = "sirius/terraform.tfstate" + region = "us-east-1" + encrypt = true + dynamodb_table = "terraform-state-lock" + } +} +``` + +#### 2. Load Balancer Configuration + +Add to `main.tf`: + +```hcl +# Application Load Balancer +resource "aws_lb" "sirius" { + name = "sirius-alb" + internal = false + load_balancer_type = "application" + security_groups = [aws_security_group.alb.id] + subnets = var.subnet_ids + + enable_deletion_protection = false + + tags = { + Name = "sirius-alb" + } +} + +# Target Group +resource "aws_lb_target_group" "sirius" { + name = "sirius-tg" + port = 3000 + protocol = "HTTP" + vpc_id = var.vpc_id + + health_check { + enabled = true + healthy_threshold = 2 + interval = 30 + matcher = "200" + path = "/" + port = "traffic-port" + protocol = "HTTP" + timeout = 5 + unhealthy_threshold = 2 + } +} + +# ALB Listener +resource "aws_lb_listener" "sirius" { + load_balancer_arn = aws_lb.sirius.arn + port = "80" + protocol = "HTTP" + + default_action { + type = "forward" + target_group_arn = aws_lb_target_group.sirius.arn + } +} + +# Target Group Attachment +resource "aws_lb_target_group_attachment" "sirius" { + target_group_arn = aws_lb_target_group.sirius.arn + target_id = aws_instance.sirius.id + port = 3000 +} +``` + +#### 3. Database Configuration + +For production, consider using RDS: + +```hcl +# RDS Instance +resource "aws_db_instance" "sirius" { + identifier = "sirius-db" + + engine = "postgres" + engine_version = "15.4" + instance_class = "db.t3.micro" + + allocated_storage = 20 + max_allocated_storage = 100 + storage_type = "gp2" + storage_encrypted = true + + db_name = "sirius" + username = "postgres" + password = var.db_password + + vpc_security_group_ids = [aws_security_group.rds.id] + db_subnet_group_name = aws_db_subnet_group.sirius.name + + backup_retention_period = 7 + backup_window = "03:00-04:00" + maintenance_window = "sun:04:00-sun:05:00" + + skip_final_snapshot = true + + tags = { + Name = "sirius-db" + } +} +``` + +### Environment-Specific Deployments + +#### Development Environment + +```hcl +# terraform.tfvars.dev +environment = "dev" +instance_type = "t3.small" +allowed_cidrs = ["0.0.0.0/0"] +``` + +#### Staging Environment + +```hcl +# terraform.tfvars.staging +environment = "staging" +instance_type = "t3.medium" +allowed_cidrs = ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"] +``` + +#### Production Environment + +```hcl +# terraform.tfvars.prod +environment = "prod" +instance_type = "t3.large" +allowed_cidrs = ["10.0.0.0/8"] # Restrict to internal networks +ssh_cidrs = ["10.0.0.0/8"] # Restrict SSH access +``` + +## Monitoring and Maintenance + +### Health Checks + +```bash +# Check instance status +aws ec2 describe-instances --instance-ids $(terraform output -raw instance_id) + +# Check application health +curl -f http://$(terraform output -raw instance_public_ip):9001/health + +# Check Docker containers +aws ssm start-session --target $(terraform output -raw instance_id) --region us-east-1 +docker compose ps +``` + +### Log Management + +```bash +# View bootstrap logs +aws ssm start-session --target $(terraform output -raw instance_id) --region us-east-1 +sudo tail -f /var/log/sirius-bootstrap.log + +# View application logs +docker compose logs -f +``` + +### Updates and Scaling + +```bash +# Update instance type +terraform apply -var="instance_type=t3.large" + +# Update to new branch +terraform apply -var="sirius_branch=feature/new-feature" + +# Scale storage +terraform apply -var="root_volume_size=50" +``` + +## Security Considerations + +### Network Security + +- **Restrict access**: Use specific CIDR blocks instead of 0.0.0.0/0 +- **Use private subnets**: Deploy in private subnets with NAT Gateway +- **Implement WAF**: Add AWS WAF for additional protection +- **VPN access**: Use VPN for secure access to private resources + +### Instance Security + +- **Key pairs**: Use EC2 key pairs for SSH access +- **Security groups**: Implement least-privilege security group rules +- **IAM roles**: Use IAM roles instead of access keys +- **Encryption**: Enable encryption for EBS volumes + +### Application Security + +- **Secrets management**: Use AWS Secrets Manager or Parameter Store +- **TLS certificates**: Implement SSL/TLS with ACM +- **Regular updates**: Keep base images and dependencies updated +- **Monitoring**: Implement CloudWatch monitoring and alerting + +## Troubleshooting + +### Common Issues + +#### 1. Instance Not Starting + +```bash +# Check instance status +aws ec2 describe-instances --instance-ids $(terraform output -raw instance_id) + +# View system logs +aws ec2 get-console-output --instance-id $(terraform output -raw instance_id) +``` + +#### 2. Services Not Responding + +```bash +# Connect to instance +aws ssm start-session --target $(terraform output -raw instance_id) --region us-east-1 + +# Check Docker status +sudo systemctl status docker +docker compose ps + +# View logs +docker compose logs -f +``` + +#### 3. Network Connectivity Issues + +```bash +# Check security groups +aws ec2 describe-security-groups --group-ids $(terraform output -raw security_group_id) + +# Test connectivity +curl -v http://$(terraform output -raw instance_public_ip):3000 +``` + +### Debugging Commands + +```bash +# Terraform state inspection +terraform state list +terraform state show aws_instance.sirius + +# Plan changes +terraform plan -var-file="terraform.tfvars.prod" + +# Destroy and recreate +terraform destroy +terraform apply +``` + +## Cost Optimization + +### Instance Sizing + +- **Development**: t3.small (2 vCPU, 2GB RAM) - ~$15/month +- **Staging**: t3.medium (2 vCPU, 4GB RAM) - ~$30/month +- **Production**: t3.large (2 vCPU, 8GB RAM) - ~$60/month + +### Storage Optimization + +- **GP3 volumes**: More cost-effective than GP2 +- **Right-sizing**: Monitor usage and adjust volume sizes +- **Cleanup**: Regular cleanup of unused resources + +### Monitoring Costs + +```bash +# Check current costs +aws ce get-cost-and-usage \ + --time-period Start=2024-01-01,End=2024-01-31 \ + --granularity MONTHLY \ + --metrics BlendedCost + +# Set up billing alerts +aws cloudwatch put-metric-alarm \ + --alarm-name "Sirius-Monthly-Cost" \ + --alarm-description "Alert when monthly cost exceeds $100" \ + --metric-name EstimatedCharges \ + --namespace AWS/Billing \ + --statistic Maximum \ + --period 86400 \ + --threshold 100 \ + --comparison-operator GreaterThanThreshold +``` + +## Cleanup + +### Destroy Infrastructure + +```bash +# Destroy all resources +terraform destroy + +# Confirm with 'yes' when prompted +# Or use -auto-approve +terraform destroy -auto-approve +``` + +### Clean Up State + +```bash +# Remove state file (if using local state) +rm terraform.tfstate* + +# Clean up .terraform directory +rm -rf .terraform/ +``` + +## Best Practices + +### Infrastructure as Code + +- **Version control**: Keep all Terraform files in version control +- **State management**: Use remote state with locking +- **Modular design**: Break down into reusable modules +- **Documentation**: Document all variables and outputs + +### Security + +- **Least privilege**: Use minimal required permissions +- **Secrets management**: Never hardcode secrets +- **Regular updates**: Keep Terraform and providers updated +- **Audit trails**: Enable CloudTrail for API calls + +### Operations + +- **Monitoring**: Implement comprehensive monitoring +- **Backup**: Regular backups of state and data +- **Testing**: Test changes in non-production first +- **Documentation**: Keep deployment procedures documented + +## Integration with CI/CD + +### GitHub Actions Example + +```yaml +name: Deploy Sirius +on: + push: + branches: [main] + workflow_dispatch: + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@v4 + with: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + aws-region: us-east-1 + + - name: Setup Terraform + uses: hashicorp/setup-terraform@v3 + with: + terraform_version: 1.6.0 + + - name: Terraform Init + run: | + cd infrastructure/aws + terraform init + + - name: Terraform Plan + run: | + cd infrastructure/aws + terraform plan + + - name: Terraform Apply + run: | + cd infrastructure/aws + terraform apply -auto-approve +``` + +## Related Documentation + +- [Development Guide](dev/README.development.md) - Local development setup +- [Architecture Overview](dev/architecture/README.architecture.md) - System architecture +- [Container Testing](dev/test/README.container-testing.md) - Testing procedures + +## Support + +For issues with Terraform deployment: + +1. Check the troubleshooting section above +2. Review Terraform logs and AWS CloudTrail +3. Consult AWS documentation for specific services +4. Create an issue in the Sirius repository + +--- + +_This guide follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](dev/ABOUT.documentation.md)._ diff --git a/documentation/dev/templates/TEMPLATE.about.md b/documentation/dev/templates/TEMPLATE.about.md new file mode 100644 index 0000000..a55838e --- /dev/null +++ b/documentation/dev/templates/TEMPLATE.about.md @@ -0,0 +1,136 @@ +--- +title: "About [System/Component] Documentation Template" +description: "This template defines the standard structure and conventions for ABOUT documents within the Sirius project, ensuring clear explanations of how to use specific systems or documentation types." +template: "TEMPLATE.template" +version: "1.0.0" +last_updated: "2025-01-03" +author: "AI Assistant" +tags: ["template", "about", "explanation", "how-to-use"] +categories: ["project-management", "development"] +difficulty: "beginner" +prerequisites: ["ABOUT.documentation.md"] +related_docs: + - "ABOUT.documentation.md" + - "TEMPLATE.documentation-standard.md" +dependencies: [] +llm_context: "high" +search_keywords: + ["about template", "explanation template", "how-to-use template"] +--- + +# About [System/Component] Documentation + +## Purpose + +This document explains how to use [specific system/component/documentation type] within the Sirius project. ABOUT documents serve as guides for understanding and working with specific aspects of our system. + +## When to Use + +- **New Team Members**: When someone needs to understand how to use a specific system +- **Reference Material**: When you need to quickly understand the purpose and usage of a component +- **Onboarding**: When integrating new developers or contributors +- **System Changes**: When updating or modifying how a system works + +## How to Use + +### Quick Start + +1. **Read the Purpose section** to understand what this system does +2. **Check the Prerequisites** to ensure you have required knowledge/tools +3. **Follow the Usage Guidelines** for step-by-step instructions +4. **Reference the Examples** for common use cases +5. **Use the Troubleshooting section** if you encounter issues + +### Common Commands + +```bash +# [Common command 1] +[command example] + +# [Common command 2] +[command example] +``` + +## What It Is + +### System Overview + +[Detailed explanation of what the system/component is and how it works] + +### Key Components + +- **[Component 1]**: [Description and purpose] +- **[Component 2]**: [Description and purpose] +- **[Component 3]**: [Description and purpose] + +### Architecture + +[High-level architecture diagram or description] + +### File Structure + +``` +[relevant directory structure] +├── [file1] - [purpose] +├── [file2] - [purpose] +└── [directory]/ + └── [file3] - [purpose] +``` + +### Configuration + +[How to configure the system, including environment variables, config files, etc.] + +### Integration Points + +[How this system integrates with other parts of the project] + +## Troubleshooting + +### FAQ + +**Q: [Common question 1]** +A: [Answer with specific steps or explanations] + +**Q: [Common question 2]** +A: [Answer with specific steps or explanations] + +**Q: [Common question 3]** +A: [Answer with specific steps or explanations] + +### Command Reference + +| Command | Purpose | Example | +| ------------ | -------------- | ----------------- | +| `[command1]` | [What it does] | `[example usage]` | +| `[command2]` | [What it does] | `[example usage]` | +| `[command3]` | [What it does] | `[example usage]` | + +### Common Issues + +| Issue | Symptoms | Solution | +| --------- | ----------------- | ------------------ | +| [Issue 1] | [How to identify] | [Step-by-step fix] | +| [Issue 2] | [How to identify] | [Step-by-step fix] | +| [Issue 3] | [How to identify] | [Step-by-step fix] | + +### Debugging Steps + +1. **Check [specific thing]**: [How to check] +2. **Verify [specific thing]**: [How to verify] +3. **Test [specific thing]**: [How to test] +4. **Review [specific thing]**: [What to look for] + +## Lessons Learned + +### [Date] - [What was learned] + +[Description of lesson learned and how it improved the system] + +### [Date] - [What was learned] + +[Description of lesson learned and how it improved the system] + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/templates/TEMPLATE.api.md b/documentation/dev/templates/TEMPLATE.api.md new file mode 100644 index 0000000..aded364 --- /dev/null +++ b/documentation/dev/templates/TEMPLATE.api.md @@ -0,0 +1,272 @@ +--- +title: "API Documentation Template" +description: "This template defines the standard structure and conventions for API documents within the Sirius project, ensuring comprehensive API specifications and usage documentation." +template: "TEMPLATE.template" +version: "1.0.0" +last_updated: "2025-01-03" +author: "AI Assistant" +tags: ["template", "api", "endpoints", "specifications", "integration"] +categories: ["project-management", "development"] +difficulty: "intermediate" +prerequisites: ["ABOUT.documentation.md"] +related_docs: + - "ABOUT.documentation.md" + - "TEMPLATE.documentation-standard.md" +dependencies: [] +llm_context: "high" +search_keywords: + ["api template", "endpoints", "api documentation", "integration specs"] +--- + +# [API Name] API Documentation + +## Purpose + +This document provides comprehensive API documentation for [specific API/service] within the Sirius project. API documents serve as authoritative sources for endpoint specifications, request/response formats, authentication, and integration examples. + +## When to Use + +- **API Integration**: When implementing client applications +- **API Development**: When building or modifying API endpoints +- **Testing**: When writing tests for API functionality +- **Debugging**: When troubleshooting API issues +- **Code Review**: When reviewing API implementation + +## How to Use + +### Quick Start + +1. **Check the Base URL** and authentication requirements +2. **Review the Common Patterns** for typical usage +3. **Find the specific endpoint** you need +4. **Follow the examples** for implementation +5. **Use the troubleshooting section** for common issues + +### Base URL + +``` +http://localhost:9001/api/v1 +``` + +### Authentication + +[Description of authentication method - API key, JWT, OAuth, etc.] + +```bash +# Example authentication +curl -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + http://localhost:9001/api/v1/endpoint +``` + +## What It Is + +### API Overview + +[Description of what this API does, its purpose, and key capabilities] + +### Endpoints + +#### [Endpoint 1] + +- **Method**: `GET|POST|PUT|DELETE` +- **Path**: `/api/v1/endpoint1` +- **Description**: [What this endpoint does] +- **Authentication**: [Required/Optional] +- **Parameters**: + - `param1` (required, string): [Description] + - `param2` (optional, integer): [Description] +- **Request Body**: [If applicable] +- **Response**: [Response format and status codes] +- **Example Request**: + +```bash +curl -X GET "http://localhost:9001/api/v1/endpoint1?param1=value¶m2=123" \ + -H "Authorization: Bearer " +``` + +- **Example Response**: + +```json +{ + "status": "success", + "data": { + "field1": "value1", + "field2": "value2" + } +} +``` + +#### [Endpoint 2] + +- **Method**: `GET|POST|PUT|DELETE` +- **Path**: `/api/v1/endpoint2` +- **Description**: [What this endpoint does] +- **Authentication**: [Required/Optional] +- **Request Body**: + +```json +{ + "field1": "string", + "field2": "integer", + "field3": { + "nested_field": "string" + } +} +``` + +- **Response**: [Response format and status codes] +- **Example Request**: + +```bash +curl -X POST "http://localhost:9001/api/v1/endpoint2" \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "field1": "value1", + "field2": 123, + "field3": { + "nested_field": "nested_value" + } + }' +``` + +- **Example Response**: + +```json +{ + "status": "success", + "data": { + "id": "generated_id", + "field1": "value1", + "field2": 123 + } +} +``` + +### Data Models + +#### [Model 1] + +```json +{ + "id": "string", + "name": "string", + "description": "string", + "created_at": "datetime", + "updated_at": "datetime" +} +``` + +#### [Model 2] + +```json +{ + "id": "string", + "field1": "string", + "field2": "integer", + "field3": { + "nested_field": "string" + }, + "field4": ["string"] +} +``` + +### Error Responses + +#### Standard Error Format + +```json +{ + "status": "error", + "error": { + "code": "ERROR_CODE", + "message": "Human readable error message", + "details": "Additional error details" + } +} +``` + +#### Common Error Codes + +| Code | HTTP Status | Description | Resolution | +| ----------------- | ----------- | ------------------------- | ---------------------------------- | +| `INVALID_REQUEST` | 400 | Request format is invalid | Check request body and parameters | +| `UNAUTHORIZED` | 401 | Authentication required | Provide valid authentication token | +| `FORBIDDEN` | 403 | Insufficient permissions | Check user permissions | +| `NOT_FOUND` | 404 | Resource not found | Verify resource ID and existence | +| `INTERNAL_ERROR` | 500 | Server error | Contact support or retry later | + +### Rate Limiting + +- **Limit**: [Requests per time period] +- **Headers**: [Rate limit headers returned] +- **Example**: `X-RateLimit-Limit: 1000, X-RateLimit-Remaining: 999` + +### Pagination + +- **Method**: [Offset-based, cursor-based, etc.] +- **Parameters**: [page, limit, offset, etc.] +- **Response Format**: [How pagination data is returned] + +```json +{ + "data": [...], + "pagination": { + "page": 1, + "limit": 20, + "total": 100, + "pages": 5 + } +} +``` + +## Troubleshooting + +### FAQ + +**Q: [Common API question 1]** +A: [Answer with specific examples and solutions] + +**Q: [Common API question 2]** +A: [Answer with specific examples and solutions] + +**Q: [Common API question 3]** +A: [Answer with specific examples and solutions] + +### Command Reference + +| Command | Purpose | Example | Notes | +| -------------- | -------------- | ----------- | ------------------ | +| `curl -X GET` | [What it does] | `[example]` | [Additional notes] | +| `curl -X POST` | [What it does] | `[example]` | [Additional notes] | +| `curl -X PUT` | [What it does] | `[example]` | [Additional notes] | + +### Common Issues + +| Issue | Symptoms | Root Cause | Solution | +| --------- | ----------------- | ---------------- | ------------------ | +| [Issue 1] | [How to identify] | [Why it happens] | [Step-by-step fix] | +| [Issue 2] | [How to identify] | [Why it happens] | [Step-by-step fix] | +| [Issue 3] | [How to identify] | [Why it happens] | [Step-by-step fix] | + +### Debugging Steps + +1. **Check [specific thing]**: [How to check and what to look for] +2. **Verify [specific thing]**: [How to verify and expected results] +3. **Test [specific thing]**: [How to test and success criteria] +4. **Review [specific thing]**: [What to review and common patterns] + +## Lessons Learned + +### [Date] - [What was learned] + +[Description of API lesson learned and how it improved the system] + +### [Date] - [What was learned] + +[Description of API lesson learned and how it improved the system] + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/templates/TEMPLATE.architecture.md b/documentation/dev/templates/TEMPLATE.architecture.md new file mode 100644 index 0000000..ed6497a --- /dev/null +++ b/documentation/dev/templates/TEMPLATE.architecture.md @@ -0,0 +1,227 @@ +--- +title: "Architecture Documentation Template" +description: "This template defines the standard structure and conventions for ARCHITECTURE documents within the Sirius project, ensuring comprehensive system design and structural documentation." +template: "TEMPLATE.template" +version: "1.0.0" +last_updated: "2025-01-03" +author: "AI Assistant" +tags: ["template", "architecture", "system-design", "structure", "overview"] +categories: ["project-management", "development"] +difficulty: "advanced" +prerequisites: ["ABOUT.documentation.md"] +related_docs: + - "ABOUT.documentation.md" + - "TEMPLATE.documentation-standard.md" +dependencies: [] +llm_context: "high" +search_keywords: + [ + "architecture template", + "system design", + "structural overview", + "technical architecture", + ] +--- + +# [System/Component] Architecture + +## Purpose + +This document provides comprehensive architectural documentation for [specific system/component] within the Sirius project. ARCHITECTURE documents serve as authoritative sources for system design, component relationships, data flow, and structural decisions. + +## When to Use + +- **System Design**: When designing new systems or major components +- **Integration Planning**: When connecting systems or components +- **Code Review**: When reviewing implementation against architectural decisions +- **Onboarding**: When bringing new team members up to speed +- **Refactoring**: When making significant structural changes + +## How to Use + +### Quick Overview + +1. **Start with the System Overview** to understand the big picture +2. **Review the Component Architecture** to understand individual parts +3. **Follow the Data Flow** to understand how information moves +4. **Check the Integration Points** to understand connections +5. **Reference the Design Decisions** for context on why choices were made + +### Architecture Patterns + +```mermaid +graph TB + A[Component A] --> B[Component B] + B --> C[Component C] + C --> D[Component D] + D --> A +``` + +## What It Is + +### System Overview + +[High-level description of the system, its purpose, and key characteristics] + +### Architectural Principles + +- **[Principle 1]**: [Description and rationale] +- **[Principle 2]**: [Description and rationale] +- **[Principle 3]**: [Description and rationale] + +### Component Architecture + +#### [Component 1] + +- **Purpose**: [What this component does] +- **Responsibilities**: [Key responsibilities] +- **Dependencies**: [What it depends on] +- **Interfaces**: [How it communicates with other components] + +#### [Component 2] + +- **Purpose**: [What this component does] +- **Responsibilities**: [Key responsibilities] +- **Dependencies**: [What it depends on] +- **Interfaces**: [How it communicates with other components] + +#### [Component 3] + +- **Purpose**: [What this component does] +- **Responsibilities**: [Key responsibilities] +- **Dependencies**: [What it depends on] +- **Interfaces**: [How it communicates with other components] + +### Data Flow + +#### [Flow 1] + +1. **[Step 1]**: [Description of what happens] +2. **[Step 2]**: [Description of what happens] +3. **[Step 3]**: [Description of what happens] + +#### [Flow 2] + +1. **[Step 1]**: [Description of what happens] +2. **[Step 2]**: [Description of what happens] +3. **[Step 3]**: [Description of what happens] + +### Integration Points + +#### [Integration 1] + +- **Type**: [API, Database, Message Queue, etc.] +- **Purpose**: [Why this integration exists] +- **Protocol**: [How communication happens] +- **Data Format**: [What data is exchanged] + +#### [Integration 2] + +- **Type**: [API, Database, Message Queue, etc.] +- **Purpose**: [Why this integration exists] +- **Protocol**: [How communication happens] +- **Data Format**: [What data is exchanged] + +### Technology Stack + +#### Backend + +- **[Technology 1]**: [Purpose and rationale] +- **[Technology 2]**: [Purpose and rationale] +- **[Technology 3]**: [Purpose and rationale] + +#### Frontend + +- **[Technology 1]**: [Purpose and rationale] +- **[Technology 2]**: [Purpose and rationale] +- **[Technology 3]**: [Purpose and rationale] + +#### Infrastructure + +- **[Technology 1]**: [Purpose and rationale] +- **[Technology 2]**: [Purpose and rationale] +- **[Technology 3]**: [Purpose and rationale] + +### Design Decisions + +#### [Decision 1] + +- **Context**: [What situation led to this decision] +- **Decision**: [What was decided] +- **Rationale**: [Why this decision was made] +- **Consequences**: [What this decision means for the system] + +#### [Decision 2] + +- **Context**: [What situation led to this decision] +- **Decision**: [What was decided] +- **Rationale**: [Why this decision was made] +- **Consequences**: [What this decision means for the system] + +### Security Considerations + +- **[Security Aspect 1]**: [How it's addressed] +- **[Security Aspect 2]**: [How it's addressed] +- **[Security Aspect 3]**: [How it's addressed] + +### Performance Characteristics + +- **[Performance Aspect 1]**: [Expected behavior and constraints] +- **[Performance Aspect 2]**: [Expected behavior and constraints] +- **[Performance Aspect 3]**: [Expected behavior and constraints] + +### Scalability Considerations + +- **[Scalability Aspect 1]**: [How the system scales] +- **[Scalability Aspect 2]**: [How the system scales] +- **[Scalability Aspect 3]**: [How the system scales] + +## Troubleshooting + +### FAQ + +**Q: [Common architectural question 1]** +A: [Answer with architectural context and rationale] + +**Q: [Common architectural question 2]** +A: [Answer with architectural context and rationale] + +**Q: [Common architectural question 3]** +A: [Answer with architectural context and rationale] + +### Command Reference + +| Command | Purpose | Example | Notes | +| ------------ | -------------- | ----------- | ----------------------- | +| `[command1]` | [What it does] | `[example]` | [Architectural context] | +| `[command2]` | [What it does] | `[example]` | [Architectural context] | +| `[command3]` | [What it does] | `[example]` | [Architectural context] | + +### Common Issues + +| Issue | Symptoms | Root Cause | Solution | +| --------- | ----------------- | -------------------------------- | ------------------ | +| [Issue 1] | [How to identify] | [Why it happens architecturally] | [Step-by-step fix] | +| [Issue 2] | [How to identify] | [Why it happens architecturally] | [Step-by-step fix] | +| [Issue 3] | [How to identify] | [Why it happens architecturally] | [Step-by-step fix] | + +### Debugging Steps + +1. **Check [specific thing]**: [How to check and what to look for] +2. **Verify [specific thing]**: [How to verify and expected results] +3. **Test [specific thing]**: [How to test and success criteria] +4. **Review [specific thing]**: [What to review and common patterns] + +## Lessons Learned + +### [Date] - [What was learned] + +[Description of architectural lesson learned and how it improved the system] + +### [Date] - [What was learned] + +[Description of architectural lesson learned and how it improved the system] + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/templates/TEMPLATE.custom.md b/documentation/dev/templates/TEMPLATE.custom.md new file mode 100644 index 0000000..3d52532 --- /dev/null +++ b/documentation/dev/templates/TEMPLATE.custom.md @@ -0,0 +1,131 @@ +--- +title: "Custom Documentation Template" +description: "This template defines the structure for custom documents that don't need to follow standard templates, providing flexibility for meta-documents and special cases." +template: "TEMPLATE.template" +version: "1.0.0" +last_updated: "2025-01-03" +author: "AI Assistant" +tags: ["template", "custom", "flexible", "meta-document"] +categories: ["project-management", "development"] +difficulty: "beginner" +prerequisites: ["ABOUT.documentation.md"] +related_docs: + - "ABOUT.documentation.md" + - "TEMPLATE.documentation-standard.md" +dependencies: [] +llm_context: "high" +search_keywords: + [ + "custom template", + "flexible template", + "meta-document", + "non-standard template", + ] +--- + +# Custom Documentation Template + +## Purpose + +This template provides a flexible structure for custom documents that don't need to follow standard templates. Use this for meta-documents, special cases, or documents that require unique structure. + +## When to Use + +- **Meta-documents** - Documents about the documentation system itself +- **Special cases** - Documents that don't fit standard templates +- **Flexible content** - When you need custom structure +- **Experimental docs** - When testing new documentation approaches + +## How to Use + +1. **Copy this template** for your custom document +2. **Modify the structure** as needed for your specific use case +3. **Keep YAML front matter** for consistency and LLM optimization +4. **Maintain basic standards** even with custom structure +5. **Document deviations** if they're significant + +## What It Is + +### Flexible Structure + +Custom documents can have any structure that makes sense for their purpose, but should include: + +- **YAML Front Matter** - For consistency and LLM optimization +- **Clear Purpose** - What the document is for +- **Logical Organization** - Information should be well-structured +- **Appropriate Sections** - Based on the document's purpose + +### Custom Sections + +Unlike standard templates, custom documents can include: + +- **Any section structure** that makes sense +- **Unique formatting** for specific needs +- **Specialized content** for specific audiences +- **Experimental approaches** to documentation + +### YAML Front Matter + +Even custom documents should include complete YAML front matter: + +```yaml +--- +title: "Document Title" +description: "Brief description of purpose" +template: "TEMPLATE.custom" +version: "1.0.0" +last_updated: "YYYY-MM-DD" +author: "Document Author" +tags: ["relevant", "tags"] +categories: ["appropriate", "categories"] +difficulty: "beginner|intermediate|advanced" +prerequisites: ["any", "prerequisites"] +related_docs: + - "related-doc1.md" + - "related-doc2.md" +dependencies: ["any", "dependencies"] +llm_context: "high|medium|low" +search_keywords: ["relevant", "keywords"] +--- +``` + +## Troubleshooting + +### FAQ + +**Q: When should I use a custom template instead of a standard one?** +A: Use custom when the document doesn't fit standard patterns, is a meta-document, or requires unique structure. + +**Q: Do custom documents still need YAML front matter?** +A: Yes, for consistency, LLM optimization, and integration with our documentation system. + +**Q: How much can I deviate from standard structure?** +A: As much as needed for your specific use case, but maintain basic organization and clarity. + +**Q: Should custom documents still be linted?** +A: Yes, but with relaxed template compliance rules for custom documents. + +### Command Reference + +| Command | Purpose | Example | +| ---------------------------------- | ---------------------- | --------------------------------------------------- | +| `cp TEMPLATE.custom.md new-doc.md` | Create custom document | `cp TEMPLATE.custom.md documentation/custom-doc.md` | +| `grep -r "template: custom"` | Find custom documents | `grep -r "template: custom" documentation/` | + +### Common Issues + +| Issue | Symptoms | Solution | +| -------------------- | ------------------------ | ------------------------------------------ | +| Too much deviation | Hard to maintain | Consider if a standard template would work | +| Missing front matter | Poor LLM integration | Add complete YAML front matter | +| Poor organization | Hard to find information | Improve structure and add clear headings | + +## Lessons Learned + +### [Date] - [What was learned] + +[Description of custom template lesson learned and how it improved the system] + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/templates/TEMPLATE.documentation-standard.md b/documentation/dev/templates/TEMPLATE.documentation-standard.md new file mode 100644 index 0000000..d3d1ec8 --- /dev/null +++ b/documentation/dev/templates/TEMPLATE.documentation-standard.md @@ -0,0 +1,182 @@ +--- +title: "[DOCUMENT TITLE]" +description: "[Brief description of the document's purpose and scope]" +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "[YYYY-MM-DD]" +author: "[Document Author]" +tags: ["[tag1]", "[tag2]", "[tag3]"] +categories: ["[category1]", "[category2]"] +difficulty: "intermediate" +prerequisites: ["[prerequisite1]", "[prerequisite2]"] +related_docs: + - "[related-doc1.md]" + - "[related-doc2.md]" +dependencies: + - "[required-file1]" + - "[required-directory/]" +llm_context: "high" +search_keywords: ["[keyword1]", "[keyword2]", "[keyword3]"] +--- + +# [DOCUMENT TITLE] + +## Purpose + +[Brief 2-3 sentence description of what this document is for and who should use it. Be specific about the document's scope and intended audience.] + +## When to Use + +[Clear list of scenarios when this document should be referenced. Include specific triggers, situations, or conditions that warrant consulting this documentation.] + +- **Primary Use Case**: [Main reason to use this document] +- **Secondary Use Cases**: [Additional scenarios] +- **Edge Cases**: [Special circumstances] +- **Avoid When**: [When NOT to use this document] + +## How to Use + +[Step-by-step instructions for applying the information in this document. Include specific commands, procedures, or workflows that users should follow.] + +### Quick Start + +```bash +# Essential commands or steps +[Provide working examples] +``` + +### Prerequisites + +- [List any requirements or dependencies] +- [Include system requirements if applicable] + +### Step-by-Step Process + +1. **[Step 1]**: [Description and command] +2. **[Step 2]**: [Description and command] +3. **[Continue as needed]** + +## What It Is + +[Comprehensive technical documentation that explains the system, process, or concept in detail. This is the "meat and potatoes" section that provides deep technical understanding.] + +### Architecture Overview + +[High-level system design, components, and relationships] + +### Technical Details + +[Detailed explanation of how the system works, including:] + +- **Core Components**: [Key parts and their functions] +- **Data Flow**: [How information moves through the system] +- **Dependencies**: [What the system relies on] +- **Configuration**: [How to configure the system] + +### Implementation Details + +[Specific technical implementation information:] + +- **File Structure**: [Relevant files and directories] +- **Code Examples**: [Working code samples with context] +- **Configuration Options**: [Available settings and their effects] +- **Integration Points**: [How this connects with other systems] + +### Advanced Topics + +[Complex or specialized information for advanced users:] + +- **Customization**: [How to modify or extend the system] +- **Performance Considerations**: [Optimization and scaling] +- **Security Implications**: [Security considerations and best practices] + +## Troubleshooting + +### FAQ + +**Q: [Common question about the topic]** +A: [Clear, concise answer with specific steps if applicable] + +**Q: [Another common question]** +A: [Answer with examples or references to other sections] + +**Q: [Continue with up to 10 frequently asked questions]** +A: [Keep answers updated as new issues are discovered] + +### Command Reference + +[Essential commands for troubleshooting and maintenance:] + +```bash +# [Command description] +[command] [options] [arguments] + +# [Another command description] +[command] [options] [arguments] + +# [Continue with commonly used commands] +``` + +### Common Issues and Solutions + +| Issue | Symptoms | Solution | +| -------------------- | -------------------- | -------------------- | +| [Problem 1] | [How to identify] | [Step-by-step fix] | +| [Problem 2] | [How to identify] | [Step-by-step fix] | +| [Continue as needed] | [Continue as needed] | [Continue as needed] | + +### Debugging Steps + +1. **[Check X]**: [How to verify this component] +2. **[Check Y]**: [How to verify this component] +3. **[Check Z]**: [How to verify this component] + +### Log Analysis + +[How to read and interpret relevant logs:] + +```bash +# [Command to view logs] +[command] | grep [pattern] + +# [What to look for in logs] +[explanation of log patterns and their meanings] +``` + +### Performance Troubleshooting + +[Specific guidance for performance-related issues:] + +- **Resource Usage**: [How to check CPU, memory, disk usage] +- **Bottlenecks**: [Common performance bottlenecks and solutions] +- **Monitoring**: [How to monitor system health] + +### Lessons Learned + +**YYYY-MM-DD**: [Description of what was learned, what problem it solved, and how it improves the documentation] + +**YYYY-MM-DD**: [Another lesson learned with timestamp] + +[Continue adding lessons learned entries as new insights are gained] + +## Related Documentation + +[Links to related documents and their relationships:] + +- **[Related Doc 1]**: [Brief description of relationship] +- **[Related Doc 2]**: [Brief description of relationship] +- **[Related Doc 3]**: [Brief description of relationship] + +## LLM Context + +[Additional context specifically for Large Language Models:] + +- **Key Concepts**: [Important concepts for AI understanding] +- **Technical Context**: [Technical background information] +- **Common Patterns**: [Frequently used patterns or approaches] +- **Edge Cases**: [Important edge cases to consider] +- **Integration Points**: [How this relates to other systems] + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/templates/TEMPLATE.guide.md b/documentation/dev/templates/TEMPLATE.guide.md new file mode 100644 index 0000000..14f81e7 --- /dev/null +++ b/documentation/dev/templates/TEMPLATE.guide.md @@ -0,0 +1,231 @@ +--- +title: "[GUIDE TITLE]" +description: "[Brief description of the step-by-step guide]" +template: "TEMPLATE.guide" +version: "1.0.0" +last_updated: "[YYYY-MM-DD]" +author: "[Guide Author]" +tags: ["[tag1]", "[tag2]", "[tag3]"] +categories: ["[category1]", "[category2]"] +difficulty: "intermediate" +prerequisites: ["[prerequisite1]", "[prerequisite2]"] +related_docs: + - "[related-doc1.md]" + - "[related-doc2.md]" +dependencies: + - "[required-file1]" + - "[required-directory/]" +llm_context: "medium" +search_keywords: ["[keyword1]", "[keyword2]", "[keyword3]"] +estimated_time: "[X minutes|hours]" +--- + +# [GUIDE TITLE] + +## Purpose + +[Brief description of what this guide accomplishes and who should follow it. Focus on the end result or goal.] + +## When to Use This Guide + +[Specific scenarios when this guide should be followed:] + +- **Primary Scenario**: [Main use case for this guide] +- **Alternative Scenarios**: [Other situations where this applies] +- **Prerequisites Met**: [When you have the required knowledge/tools] + +## How to Use This Guide + +[Instructions for following the guide effectively:] + +- **Read through completely** before starting +- **Gather prerequisites** listed below +- **Follow steps in order** unless noted otherwise +- **Verify each step** before proceeding to the next + +### Quick Start + +```bash +# Essential commands to get started +[Provide working examples] +``` + +### Prerequisites + +**Knowledge Required:** + +- [Required knowledge or skills] +- [Familiarity with specific tools] + +**Tools Required:** + +- [Required software or tools] +- [System requirements] + +**Access Required:** + +- [Required permissions or access] +- [Required accounts or credentials] + +## Step-by-Step Instructions + +### Step 1: [Step Title] + +**Objective**: [What this step accomplishes] + +**Instructions**: + +1. [Detailed instruction] +2. [Next instruction] +3. [Continue as needed] + +**Verification**: + +```bash +# Command to verify this step worked +[verification command] +``` + +**Expected Output**: + +``` +[Expected output or result] +``` + +**Troubleshooting**: + +- **If X happens**: [Solution] +- **If Y happens**: [Solution] + +### Step 2: [Step Title] + +[Continue with detailed steps...] + +### Step 3: [Step Title] + +[Continue with detailed steps...] + +## Verification and Testing + +### Final Verification + +[How to verify the entire process worked correctly:] + +```bash +# Commands to verify everything is working +[verification commands] +``` + +### Testing Checklist + +- [ ] [Test item 1] +- [ ] [Test item 2] +- [ ] [Test item 3] +- [ ] [Continue as needed] + +## Common Variations + +### Variation 1: [Scenario Name] + +[When to use this variation and how it differs:] + +**Additional Steps**: + +1. [Additional step] +2. [Another additional step] + +**Skip These Steps**: + +- [Step to skip] +- [Another step to skip] + +### Variation 2: [Scenario Name] + +[Another common variation...] + +## Troubleshooting + +### FAQ + +**Q: What if Step X fails?** +A: [Detailed solution with steps] + +**Q: How do I know if I'm on the right track?** +A: [How to verify progress] + +**Q: Can I skip Step Y?** +A: [When it's safe to skip and what to do instead] + +**Q: What if I get error message Z?** +A: [Specific error resolution] + +### Common Issues and Solutions + +| Issue | Symptoms | Solution | +| -------------------- | -------------------- | -------------------- | +| [Common problem 1] | [How to identify] | [Step-by-step fix] | +| [Common problem 2] | [How to identify] | [Step-by-step fix] | +| [Continue as needed] | [Continue as needed] | [Continue as needed] | + +### Rollback Instructions + +[How to undo the changes if something goes wrong:] + +1. **[Rollback Step 1]**: [How to undo this step] +2. **[Rollback Step 2]**: [How to undo this step] +3. **[Continue as needed]**: [Continue rollback steps] + +### Getting Help + +**If you're stuck:** + +1. Check the troubleshooting section above +2. Review the prerequisites +3. Verify you followed each step exactly +4. Check the related documentation +5. [Contact information or escalation path] + +## Advanced Topics + +### Customization Options + +[How to customize the process for specific needs:] + +- **Option A**: [Description and how to implement] +- **Option B**: [Description and how to implement] + +### Performance Optimization + +[Tips for making the process faster or more efficient:] + +- [Optimization tip 1] +- [Optimization tip 2] + +### Integration with Other Systems + +[How this process integrates with other workflows:] + +- [Integration point 1] +- [Integration point 2] + +## Related Documentation + +[Links to related guides and documentation:] + +- **[Related Guide 1]**: [Brief description of relationship] +- **[Related Guide 2]**: [Brief description of relationship] +- **[Reference Doc]**: [Technical reference for this topic] + +## LLM Context + +[Additional context for Large Language Models:] + +- **Process Overview**: [High-level process description] +- **Key Decision Points**: [Important choices in the process] +- **Common Pitfalls**: [Frequent mistakes to avoid] +- **Success Criteria**: [How to know the process succeeded] +- **Integration Points**: [How this connects to other systems] + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/templates/TEMPLATE.reference.md b/documentation/dev/templates/TEMPLATE.reference.md new file mode 100644 index 0000000..cf63581 --- /dev/null +++ b/documentation/dev/templates/TEMPLATE.reference.md @@ -0,0 +1,222 @@ +--- +title: "Reference Documentation Template" +description: "This template defines the standard structure and conventions for REFERENCE documents within the Sirius project, ensuring comprehensive technical specifications and API documentation." +template: "TEMPLATE.template" +version: "1.0.0" +last_updated: "2025-01-03" +author: "AI Assistant" +tags: ["template", "reference", "technical", "specifications", "api"] +categories: ["project-management", "development"] +difficulty: "intermediate" +prerequisites: ["ABOUT.documentation.md"] +related_docs: + - "ABOUT.documentation.md" + - "TEMPLATE.documentation-standard.md" +dependencies: [] +llm_context: "high" +search_keywords: + [ + "reference template", + "technical specs", + "api documentation", + "specifications", + ] +--- + +# [System/Component] Reference + +## Purpose + +This document provides comprehensive technical reference information for [specific system/component/API] within the Sirius project. REFERENCE documents serve as authoritative sources for technical specifications, API endpoints, configuration options, and implementation details. + +## When to Use + +- **API Development**: When implementing or consuming APIs +- **Integration Work**: When connecting systems or components +- **Configuration**: When setting up or modifying system parameters +- **Debugging**: When troubleshooting technical issues +- **Code Review**: When reviewing implementation against specifications + +## How to Use + +### Quick Reference + +1. **Find the relevant section** for your specific need +2. **Check the prerequisites** and requirements +3. **Follow the examples** for implementation patterns +4. **Reference the specifications** for exact details +5. **Use the troubleshooting section** for common issues + +### Common Patterns + +```bash +# [Common pattern 1] +[example implementation] + +# [Common pattern 2] +[example implementation] +``` + +## What It Is + +### Technical Overview + +[Detailed technical explanation of the system/component/API] + +### Architecture + +[Technical architecture with diagrams and component relationships] + +### Data Models + +#### [Model 1] + +```json +{ + "field1": "type", + "field2": "type", + "field3": { + "nested_field": "type" + } +} +``` + +#### [Model 2] + +```yaml +field1: type +field2: type +field3: + nested_field: type +``` + +### API Endpoints + +#### [Endpoint 1] + +- **Method**: `GET|POST|PUT|DELETE` +- **Path**: `/api/v1/endpoint` +- **Description**: [What this endpoint does] +- **Parameters**: + - `param1` (required): [Description] + - `param2` (optional): [Description] +- **Response**: [Response format and status codes] +- **Example**: + +```bash +curl -X GET "http://localhost:9001/api/v1/endpoint?param1=value" +``` + +#### [Endpoint 2] + +- **Method**: `GET|POST|PUT|DELETE` +- **Path**: `/api/v1/endpoint2` +- **Description**: [What this endpoint does] +- **Request Body**: [Request format] +- **Response**: [Response format and status codes] +- **Example**: + +```bash +curl -X POST "http://localhost:9001/api/v1/endpoint2" \ + -H "Content-Type: application/json" \ + -d '{"field1": "value", "field2": "value"}' +``` + +### Configuration Options + +| Option | Type | Default | Description | Required | +| --------- | ------- | --------- | ------------- | -------- | +| `option1` | string | "default" | [Description] | Yes | +| `option2` | integer | 0 | [Description] | No | +| `option3` | boolean | false | [Description] | No | + +### Environment Variables + +| Variable | Description | Example | Required | +| ---------- | ------------- | -------- | -------- | +| `ENV_VAR1` | [Description] | `value1` | Yes | +| `ENV_VAR2` | [Description] | `value2` | No | + +### File Formats + +#### [Format 1] + +```yaml +# YAML format example +key1: value1 +key2: + nested_key: nested_value + list_item: + - item1 + - item2 +``` + +#### [Format 2] + +```json +{ + "key1": "value1", + "key2": { + "nested_key": "nested_value", + "list_item": ["item1", "item2"] + } +} +``` + +### Error Codes + +| Code | HTTP Status | Description | Resolution | +| ------ | ----------- | ------------------- | ------------ | +| `E001` | 400 | [Error description] | [How to fix] | +| `E002` | 401 | [Error description] | [How to fix] | +| `E003` | 500 | [Error description] | [How to fix] | + +## Troubleshooting + +### FAQ + +**Q: [Common technical question 1]** +A: [Technical answer with specific details] + +**Q: [Common technical question 2]** +A: [Technical answer with specific details] + +**Q: [Common technical question 3]** +A: [Technical answer with specific details] + +### Command Reference + +| Command | Purpose | Example | Notes | +| ------------ | -------------- | ----------- | ------------------ | +| `[command1]` | [What it does] | `[example]` | [Additional notes] | +| `[command2]` | [What it does] | `[example]` | [Additional notes] | +| `[command3]` | [What it does] | `[example]` | [Additional notes] | + +### Common Issues + +| Issue | Symptoms | Root Cause | Solution | +| --------- | ----------------- | ---------------- | ------------------ | +| [Issue 1] | [How to identify] | [Why it happens] | [Step-by-step fix] | +| [Issue 2] | [How to identify] | [Why it happens] | [Step-by-step fix] | +| [Issue 3] | [How to identify] | [Why it happens] | [Step-by-step fix] | + +### Debugging Steps + +1. **Check [specific thing]**: [How to check and what to look for] +2. **Verify [specific thing]**: [How to verify and expected results] +3. **Test [specific thing]**: [How to test and success criteria] +4. **Review [specific thing]**: [What to review and common patterns] + +## Lessons Learned + +### [Date] - [What was learned] + +[Description of technical lesson learned and how it improved the system] + +### [Date] - [What was learned] + +[Description of technical lesson learned and how it improved the system] + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/templates/TEMPLATE.template.md b/documentation/dev/templates/TEMPLATE.template.md new file mode 100644 index 0000000..31fdddb --- /dev/null +++ b/documentation/dev/templates/TEMPLATE.template.md @@ -0,0 +1,191 @@ +--- +title: "Template Documentation Template" +description: "This template defines the standard structure and conventions for template documents within the Sirius project, ensuring consistency and clarity for all template files." +template: "TEMPLATE.template" +version: "1.0.0" +last_updated: "2025-01-03" +author: "AI Assistant" +tags: ["template", "meta-template", "structure", "standards"] +categories: ["project-management", "development"] +difficulty: "beginner" +prerequisites: ["ABOUT.documentation.md"] +related_docs: + - "ABOUT.documentation.md" + - "TEMPLATE.documentation-standard.md" +dependencies: [] +llm_context: "medium" +search_keywords: + [ + "template template", + "meta-template", + "template structure", + "documentation template", + ] +--- + +# [Template Name] Template + +## Purpose + +This template defines the standard structure and conventions for [specific type] documents within the Sirius project. Template documents serve as blueprints for creating consistent, high-quality documentation. + +## When to Use + +- **Creating new templates** - When defining structure for new document types +- **Updating existing templates** - When improving template structure +- **Template maintenance** - When ensuring template consistency +- **Onboarding contributors** - When explaining template structure + +## How to Use + +### Quick Start + +1. **Copy this template** for your new template type +2. **Update the title and description** to match your template's purpose +3. **Define the structure** with clear sections and subsections +4. **Add examples** for each section to guide users +5. **Include placeholders** for common content patterns +6. **Test the template** by creating a sample document + +### Template Structure + +```markdown +# [Document Title] + +## Purpose + +[What this document is for] + +## When to Use + +[When to reference this document] + +## How to Use + +[How to apply the information] + +## What It Is + +[Detailed technical content] + +## Troubleshooting + +[Problem-solving section] + +### FAQ + +[Frequently asked questions] + +### Command Reference + +[Common commands] + +### Common Issues + +[Common problems and solutions] + +## Lessons Learned + +[Timestamped insights] +``` + +## What It Is + +### Template Components + +- **[Component 1]**: [Description and purpose] +- **[Component 2]**: [Description and purpose] +- **[Component 3]**: [Description and purpose] + +### Required Sections + +1. **Purpose** - Clear explanation of what the template is for +2. **When to Use** - Specific scenarios for using this template +3. **How to Use** - Step-by-step instructions for using the template +4. **What It Is** - Detailed explanation of the template structure +5. **Troubleshooting** - Common issues and solutions + +### Optional Sections + +- **Examples** - Sample content for each section +- **Best Practices** - Guidelines for effective use +- **Common Patterns** - Recurring content patterns +- **Integration Notes** - How this template works with others + +### Placeholder System + +Use consistent placeholders throughout the template: + +- `[Document Title]` - Replace with actual document title +- `[Section Name]` - Replace with specific section names +- `[Description]` - Replace with detailed descriptions +- `[Example]` - Replace with working examples +- `[Command]` - Replace with actual commands + +### YAML Front Matter + +Every template must include complete YAML front matter: + +```yaml +--- +title: "[Template Name] Template" +description: "Brief description of template purpose" +template: "TEMPLATE.template" +version: "1.0.0" +last_updated: "YYYY-MM-DD" +author: "Template Author" +tags: ["template", "specific-type", "structure"] +categories: ["project-management", "development"] +difficulty: "beginner" +prerequisites: ["ABOUT.documentation.md"] +related_docs: + - "ABOUT.documentation.md" + - "TEMPLATE.documentation-standard.md" +dependencies: [] +llm_context: "medium" +search_keywords: ["template", "specific-type", "structure"] +--- +``` + +## Troubleshooting + +### FAQ + +**Q: How do I create a new template?** +A: Copy this template, update the title and description, define the structure, and add examples for each section. + +**Q: What if I need to deviate from the standard structure?** +A: Document the deviation clearly and consider whether a new template type is needed. + +**Q: How detailed should template examples be?** +A: Include enough detail to guide users but keep them concise and focused. + +**Q: Should templates include all possible sections?** +A: Include required sections and common optional sections, but don't over-complicate. + +### Command Reference + +| Command | Purpose | Example | +| -------------------------------- | ------------------- | ---------------------------------------------- | +| `cp template.md new-template.md` | Copy template | `cp TEMPLATE.template.md TEMPLATE.new-type.md` | +| `grep -r "template:"` | Find template usage | `grep -r "template:" documentation/` | +| `grep -r "TEMPLATE\."` | Find all templates | `grep -r "TEMPLATE\." documentation/` | + +### Common Issues + +| Issue | Symptoms | Solution | +| ------------------------- | ------------------------------ | ------------------------------------------------- | +| Template too complex | Users confused | Simplify structure and add more examples | +| Template too simple | Missing guidance | Add more detailed instructions and examples | +| Inconsistent placeholders | Confusion about replacements | Standardize placeholder format and document usage | +| Missing examples | Users don't know what to write | Add comprehensive examples for each section | + +## Lessons Learned + +### [Date] - [What was learned] + +[Description of template lesson learned and how it improved the system] + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/templates/TEMPLATE.troubleshooting.md b/documentation/dev/templates/TEMPLATE.troubleshooting.md new file mode 100644 index 0000000..7cc4d2c --- /dev/null +++ b/documentation/dev/templates/TEMPLATE.troubleshooting.md @@ -0,0 +1,334 @@ +--- +title: "[TROUBLESHOOTING TITLE]" +description: "[Brief description of the troubleshooting focus area]" +template: "TEMPLATE.troubleshooting" +version: "1.0.0" +last_updated: "[YYYY-MM-DD]" +author: "[Document Author]" +tags: ["[tag1]", "[tag2]", "[tag3]"] +categories: ["[category1]", "[category2]"] +difficulty: "intermediate" +prerequisites: ["[prerequisite1]", "[prerequisite2]"] +related_docs: + - "[related-doc1.md]" + - "[related-doc2.md]" +dependencies: + - "[required-file1]" + - "[required-directory/]" +llm_context: "high" +search_keywords: ["[keyword1]", "[keyword2]", "[keyword3]"] +--- + +# [TROUBLESHOOTING TITLE] + +## Purpose + +[Brief description of what problems this troubleshooting guide addresses and who should use it. Focus on the specific issue domain.] + +## When to Use This Guide + +[Specific scenarios when this troubleshooting guide should be consulted:] + +- **Primary Issues**: [Main problems this guide addresses] +- **Error Messages**: [Specific error messages this guide covers] +- **System States**: [When the system is in a problematic state] +- **Before Escalating**: [When to try this guide before seeking help] + +## How to Use This Guide + +[Instructions for effective troubleshooting:] + +1. **Start with Quick Fixes** - Try the most common solutions first +2. **Follow the Flow** - Use the diagnostic flow chart if available +3. **Gather Information** - Collect relevant logs and system state +4. **Test Incrementally** - Apply fixes one at a time and test +5. **Document Results** - Note what worked and what didn't + +### Quick Diagnostic + +```bash +# Essential diagnostic commands +[Provide key diagnostic commands] +``` + +### Information Gathering + +**Before troubleshooting, collect:** + +- [Required information 1] +- [Required information 2] +- [Required information 3] + +## Common Problems and Solutions + +### Problem 1: [Problem Name] + +**Symptoms:** + +- [Symptom 1] +- [Symptom 2] +- [Symptom 3] + +**Root Cause:** +[Explanation of what causes this problem] + +**Solution:** + +1. [Step 1 of solution] +2. [Step 2 of solution] +3. [Step 3 of solution] + +**Verification:** + +```bash +# Command to verify the fix worked +[verification command] +``` + +**Prevention:** +[How to prevent this problem in the future] + +### Problem 2: [Problem Name] + +[Continue with additional problems...] + +## Diagnostic Flow Chart + +``` +Start + ↓ +[First diagnostic question] + ↓ +Yes → [Action A] → [Next question] + ↓ +No → [Action B] → [Next question] + ↓ +[Continue flow...] + ↓ +End +``` + +## Error Message Reference + +### Error: [Error Message] + +**Meaning**: [What this error means] + +**Common Causes**: + +- [Cause 1] +- [Cause 2] +- [Cause 3] + +**Solutions**: + +1. [Solution 1] +2. [Solution 2] +3. [Solution 3] + +### Error: [Another Error Message] + +[Continue with additional error messages...] + +## Command Reference + +### Diagnostic Commands + +```bash +# [Command description] +[command] [options] + +# [Another diagnostic command] +[command] [options] + +# [Continue with diagnostic commands] +``` + +### Fix Commands + +```bash +# [Fix command description] +[command] [options] + +# [Another fix command] +[command] [options] + +# [Continue with fix commands] +``` + +### Verification Commands + +```bash +# [Verification command description] +[command] [options] + +# [Another verification command] +[command] [options] + +# [Continue with verification commands] +``` + +## Log Analysis + +### Key Log Locations + +- **[Log 1]**: [Location and purpose] +- **[Log 2]**: [Location and purpose] +- **[Log 3]**: [Location and purpose] + +### Log Patterns to Look For + +**Success Patterns:** + +``` +[Pattern that indicates success] +``` + +**Error Patterns:** + +``` +[Pattern that indicates errors] +``` + +**Warning Patterns:** + +``` +[Pattern that indicates warnings] +``` + +### Log Analysis Commands + +```bash +# [Command to analyze logs] +[command] | grep [pattern] + +# [Another log analysis command] +[command] | grep [pattern] + +# [Continue with log analysis commands] +``` + +## System State Checks + +### Health Check Commands + +```bash +# [Health check description] +[command] + +# [Another health check] +[command] + +# [Continue with health checks] +``` + +### Resource Monitoring + +```bash +# [Resource monitoring command] +[command] + +# [Another resource check] +[command] + +# [Continue with resource checks] +``` + +## Advanced Troubleshooting + +### Deep Dive Diagnostics + +[Advanced diagnostic techniques for complex issues:] + +1. **[Advanced Technique 1]**: [Description and when to use] +2. **[Advanced Technique 2]**: [Description and when to use] +3. **[Advanced Technique 3]**: [Description and when to use] + +### Performance Troubleshooting + +[Specific guidance for performance-related issues:] + +- **CPU Issues**: [How to diagnose and fix] +- **Memory Issues**: [How to diagnose and fix] +- **Disk Issues**: [How to diagnose and fix] +- **Network Issues**: [How to diagnose and fix] + +### Integration Troubleshooting + +[Issues related to system integration:] + +- **Service A Integration**: [Common issues and solutions] +- **Service B Integration**: [Common issues and solutions] +- **External System Integration**: [Common issues and solutions] + +## Escalation Procedures + +### When to Escalate + +[Criteria for when to escalate to higher support levels:] + +- [Escalation criteria 1] +- [Escalation criteria 2] +- [Escalation criteria 3] + +### Information to Include + +[What information to gather before escalating:] + +- [Required information 1] +- [Required information 2] +- [Required information 3] + +### Escalation Contacts + +- **Level 1**: [Contact information] +- **Level 2**: [Contact information] +- **Level 3**: [Contact information] + +## Prevention Strategies + +### Best Practices + +[How to prevent these problems from occurring:] + +- [Best practice 1] +- [Best practice 2] +- [Best practice 3] + +### Monitoring and Alerting + +[How to monitor for these issues:] + +- [Monitoring approach 1] +- [Monitoring approach 2] +- [Monitoring approach 3] + +### Regular Maintenance + +[Maintenance tasks to prevent issues:] + +- [Maintenance task 1] +- [Maintenance task 2] +- [Maintenance task 3] + +## Related Documentation + +[Links to related troubleshooting and reference documentation:] + +- **[Related Troubleshooting Guide]**: [Brief description] +- **[System Reference]**: [Technical reference] +- **[Configuration Guide]**: [Configuration documentation] + +## LLM Context + +[Additional context for Large Language Models:] + +- **Problem Patterns**: [Common problem patterns to recognize] +- **Solution Strategies**: [General approaches to problem-solving] +- **System Dependencies**: [How different components interact] +- **Failure Modes**: [Common ways the system can fail] +- **Recovery Procedures**: [How to recover from various failure states] + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/test/ABOUT.testing.md b/documentation/dev/test/ABOUT.testing.md new file mode 100644 index 0000000..3d24ec8 --- /dev/null +++ b/documentation/dev/test/ABOUT.testing.md @@ -0,0 +1,370 @@ +--- +title: "About Testing in Sirius" +description: "Comprehensive guide to the Sirius testing philosophy, infrastructure, and operator-first testing approach for integration and validation testing." +template: "TEMPLATE.about" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Development Team" +tags: ["testing", "philosophy", "integration", "operator-first", "validation", "qa"] +categories: ["testing", "philosophy"] +difficulty: "intermediate" +prerequisites: ["docker", "testing concepts", "integration testing"] +related_docs: + - "README.container-testing.md" + - "README.documentation-testing.md" + - "README.cicd.md" +dependencies: + - "testing/container-testing/" + - "testing/documentation/" + - "scripts/git-hooks/" +llm_context: "high" +search_keywords: + [ + "testing philosophy", + "operator-first testing", + "integration testing", + "validation testing", + "automated qa", + "standalone tests", + "testing infrastructure" + ] +--- + +# About Testing in Sirius + +## Overview + +Testing in Sirius follows an **operator-first philosophy** that prioritizes real-world validation over traditional unit testing. Our testing approach focuses on proving that complete systems, processes, and integrations work correctly in realistic scenarios, rather than testing individual code units in isolation. + +## Testing Philosophy + +### Operator-First Approach + +**Core Principle**: Tests should validate that operators can successfully use the system to accomplish real tasks. + +**What This Means**: +- Tests simulate actual user workflows and operations +- Validation focuses on end-to-end functionality +- Tests prove that complete processes work as intended +- Results must be actionable and meaningful to operators + +**Example**: Instead of testing a scanner function in isolation, we test that the scanner can be invoked standalone, process real data, and produce valid results that an operator would actually use. + +### Integration-Focused Testing + +**Primary Goal**: Validate that different components work together correctly. + +**Testing Scope**: +- Cross-service communication +- Data flow between components +- End-to-end process validation +- Real-world scenario simulation + +**Benefits**: +- Catches integration issues that unit tests miss +- Validates complete workflows +- Ensures system reliability for operators +- Provides confidence in production deployments + +## Current Testing Infrastructure + +### Container Testing + +**Location**: `testing/container-testing/` + +**Purpose**: Validate Docker container builds, health, and integration + +**What's Tested**: +- Docker Compose configuration validation +- Individual container builds (all targets) +- Service health checks +- Cross-service communication +- Integration testing + +**Automation**: +- `make test-all` - Complete test suite +- `make test-build` - Build validation +- `make test-health` - Health checks +- `make test-integration` - Integration testing + +### Documentation Testing + +**Location**: `testing/documentation/` + +**Purpose**: Validate documentation completeness, accuracy, and consistency + +**What's Tested**: +- YAML front matter completeness +- Template compliance +- Index completeness +- Link validation +- Metadata validity + +**Automation**: +- `make lint-docs` - Full documentation validation +- `make lint-docs-quick` - Quick validation +- `make lint-index` - Index completeness check + +### Pre-commit Validation + +**Location**: `scripts/git-hooks/` + +**Purpose**: Quick validation before commits + +**What's Tested**: +- Docker Compose configuration validity +- Basic syntax checks +- Quick documentation validation +- Code formatting + +## Testing Standards + +### Test Structure + +**Standalone Execution**: Every test must be able to run independently without dependencies on the main codebase. + +**Real Data**: Tests should use realistic data and scenarios, not mocked or synthetic data. + +**Actionable Results**: Test results must provide clear, actionable information for operators and developers. + +**Automated Validation**: All tests must be automatable and runnable via command-line tools. + +### Test Categories + +#### 1. Build Validation Tests + +**Purpose**: Ensure components can be built correctly + +**Examples**: +- Docker container builds +- Multi-stage build validation +- Architecture compatibility +- Dependency resolution + +**Validation Criteria**: +- Build completes without errors +- All build targets work correctly +- Images are properly tagged +- Dependencies are resolved + +#### 2. Health Validation Tests + +**Purpose**: Ensure services start and remain healthy + +**Examples**: +- Service startup validation +- Health endpoint checks +- Resource availability +- Graceful shutdown + +**Validation Criteria**: +- Services start within expected time +- Health endpoints respond correctly +- No critical errors in logs +- Proper resource utilization + +#### 3. Integration Validation Tests + +**Purpose**: Ensure components work together correctly + +**Examples**: +- Cross-service communication +- Database connectivity +- Message queue functionality +- API endpoint integration + +**Validation Criteria**: +- Services can communicate +- Data flows correctly +- APIs respond as expected +- Error handling works + +#### 4. Process Validation Tests + +**Purpose**: Ensure complete workflows function correctly + +**Examples**: +- End-to-end scanning processes +- Data processing pipelines +- User authentication flows +- Deployment processes + +**Validation Criteria**: +- Complete workflows execute successfully +- Results are valid and usable +- Error conditions are handled +- Performance meets requirements + +## Future Testing Objectives + +### Next 3 Months + +**Priority 1**: Scanner Testing Infrastructure +- Standalone scanner execution tests +- Real vulnerability detection validation +- Output format verification +- Performance benchmarking + +**Priority 2**: API Testing Infrastructure +- Endpoint functionality validation +- Authentication and authorization testing +- Data validation and error handling +- Performance and load testing + +**Priority 3**: Engine Testing Infrastructure +- Agent communication testing +- Task execution validation +- Resource management testing +- Error recovery testing + +### Long-term Vision + +**Comprehensive Test Coverage**: Every major component and process will have dedicated testing infrastructure. + +**Automated Validation**: All tests will be integrated into CI/CD pipelines and pre-commit hooks. + +**Operator Confidence**: Tests will provide operators with confidence that the system works correctly in production. + +**Continuous Improvement**: Testing infrastructure will evolve with the system to maintain high quality standards. + +## Testing Best Practices + +### For Test Developers + +1. **Start with Real Scenarios**: Design tests around actual operator workflows +2. **Use Real Data**: Test with realistic data, not synthetic or mocked data +3. **Validate Complete Processes**: Test end-to-end functionality, not just individual components +4. **Make Tests Standalone**: Ensure tests can run independently without external dependencies +5. **Provide Clear Results**: Test output should be actionable and meaningful + +### For System Developers + +1. **Design for Testability**: Build components that can be tested independently +2. **Expose Health Endpoints**: Provide clear health and status indicators +3. **Use Standard Interfaces**: Follow consistent patterns for APIs and data formats +4. **Document Dependencies**: Clearly document what each component needs to function +5. **Plan for Validation**: Consider how operators will validate that components work correctly + +### For Operators + +1. **Run Tests Regularly**: Use testing infrastructure to validate system health +2. **Understand Test Results**: Learn to interpret test output for troubleshooting +3. **Report Issues**: Use test failures to identify and report problems +4. **Validate Changes**: Run tests after any system changes or updates +5. **Trust the Tests**: Use test results to make operational decisions + +## Testing Tools and Commands + +### Container Testing + +```bash +# Full test suite +cd testing/container-testing +make test-all + +# Individual tests +make test-build +make test-health +make test-integration + +# Quick validation +make build-all +``` + +### Documentation Testing + +```bash +# Full documentation validation +cd testing/documentation +make lint-docs + +# Quick validation +make lint-docs-quick +make lint-index +``` + +### Pre-commit Validation + +```bash +# Automatic validation +git commit # Runs quick validation automatically + +# Manual validation +cd testing/container-testing +make build-all +make lint-docs-quick +``` + +## Integration with Development + +### CI/CD Pipeline + +**Pre-commit**: Quick validation (~30 seconds) +- Docker Compose configuration validation +- Basic syntax checks +- Quick documentation validation + +**CI/CD**: Full testing (~5-10 minutes) +- Complete Docker builds +- Integration testing +- Health checks +- Cross-service communication + +### Local Development + +**Available Commands**: Developers can run full test suites locally when needed + +**Testing Strategy**: Quick validation for commits, full testing for CI and local validation + +## Troubleshooting + +### Common Issues + +| Issue | Symptoms | Solution | +|-------|----------|----------| +| **Test Failures** | Tests fail unexpectedly | Check logs, verify dependencies, run individual tests | +| **Build Issues** | Docker builds fail | Check Dockerfile syntax, verify base images | +| **Integration Issues** | Services can't communicate | Check network configuration, verify service health | +| **Documentation Issues** | Linting fails | Check YAML front matter, verify template compliance | + +### Debugging Commands + +```bash +# Check test logs +cd testing/container-testing +make logs + +# Run individual tests +make test-build +make test-health + +# Check documentation +cd testing/documentation +make lint-docs +``` + +## Getting Help + +### Documentation + +- [README.container-testing.md](README.container-testing.md) - Container testing guide +- [README.documentation-testing.md](README.documentation-testing.md) - Documentation testing guide +- [README.cicd.md](../architecture/README.cicd.md) - CI/CD pipeline guide + +### Common Issues + +- Check test logs for specific error messages +- Verify all dependencies are available +- Ensure proper environment configuration +- Run tests individually to isolate issues + +### Support + +- Review testing documentation for guidance +- Check CI/CD logs for automated test results +- Use local testing for debugging and validation +- Report issues with specific test output and logs + +--- + +_This testing philosophy guide follows the Sirius Documentation Standard. For specific testing implementation details, see [README.container-testing.md](README.container-testing.md) and [README.documentation-testing.md](README.documentation-testing.md)._ diff --git a/documentation/dev/test/CHECKLIST.testing-by-type.md b/documentation/dev/test/CHECKLIST.testing-by-type.md new file mode 100644 index 0000000..9b09dfd --- /dev/null +++ b/documentation/dev/test/CHECKLIST.testing-by-type.md @@ -0,0 +1,470 @@ +--- +title: "Testing Checklists by Issue Type" +description: "Comprehensive testing checklists for different types of changes to ensure thorough validation before merging" +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-10-11" +author: "Development Team" +tags: ["testing", "checklist", "validation", "quality-assurance"] +categories: ["testing", "development"] +difficulty: "beginner" +prerequisites: ["docker", "git", "development-environment"] +related_docs: + - "README.container-testing.md" + - "../operations/README.git-operations.md" +dependencies: [] +llm_context: "high" +search_keywords: ["testing", "checklist", "validation", "qa", "issue-types"] +--- + +# Testing Checklists by Issue Type + +## Purpose + +This document provides specific testing checklists for different types of changes. Use the appropriate checklist based on what components your fix or feature affects. + +## When to Use + +- **Before committing** any code changes +- **Before merging** to main/demo branch +- **During code review** to ensure completeness +- **After deployment** for verification + +## How to Use + +1. Identify which type of change you're making +2. Follow the complete checklist for that type +3. Check off each item as you test +4. Document any failures or issues +5. Only proceed to merge after all checks pass + +## Testing Checklists + +### Frontend Changes (UI/UX) + +**Applies to**: Changes in `sirius-ui/src/pages/`, `sirius-ui/src/components/` + +- [ ] **Visual Testing** + + - [ ] Component renders correctly in browser + - [ ] Responsive design works on mobile/tablet/desktop + - [ ] Dark mode (if applicable) displays correctly + - [ ] All buttons and interactive elements are clickable + - [ ] No layout breaking or overflow issues + +- [ ] **Functional Testing** + + - [ ] All forms submit correctly + - [ ] Validation messages display properly + - [ ] Error states are handled gracefully + - [ ] Loading states display when appropriate + - [ ] Success/error toasts appear as expected + +- [ ] **Browser Testing** + + - [ ] Chrome/Chromium (primary) + - [ ] Firefox (if significant changes) + - [ ] Safari (if significant changes) + +- [ ] **Accessibility** + + - [ ] Keyboard navigation works + - [ ] Screen reader friendly (if major UI change) + - [ ] Proper ARIA labels (if applicable) + +- [ ] **Container Testing** + - [ ] Hot reload works in development mode + - [ ] Production build completes successfully + - [ ] No console errors in browser + +**Container Commands**: + +```bash +# Development mode test +docker compose up + +# Production build test +docker compose -f docker-compose.yaml up --build +``` + +--- + +### Backend API Changes (TRPC/Routes) + +**Applies to**: Changes in `sirius-ui/src/server/api/routers/` + +- [ ] **API Endpoint Testing** + + - [ ] Endpoint accepts correct input format + - [ ] Endpoint returns expected data structure + - [ ] Error cases return appropriate error messages + - [ ] HTTP status codes are correct + - [ ] Response time is acceptable + +- [ ] **Data Validation** + + - [ ] Input validation works (Zod schemas) + - [ ] Required fields are enforced + - [ ] Type coercion works correctly + - [ ] Invalid data is rejected with clear errors + +- [ ] **Authentication/Authorization** + + - [ ] Protected endpoints require authentication + - [ ] Session/JWT validation works + - [ ] Unauthorized access is blocked + +- [ ] **Database Interaction** + + - [ ] Queries return expected data + - [ ] No SQL injection vulnerabilities + - [ ] Transactions complete successfully + - [ ] Error handling for database failures + +- [ ] **Container Testing** + - [ ] Check logs for errors: `docker compose logs sirius-ui` + - [ ] Verify no crashes or exceptions + - [ ] Test with development and production builds + +**Testing Example**: + +```bash +# Watch container logs during testing +docker compose logs -f sirius-ui + +# Test endpoint via browser console or Postman +# Verify response structure and error handling +``` + +--- + +### Database Schema Changes + +**Applies to**: Changes in `sirius-ui/prisma/schema.prisma`, migrations + +- [ ] **Schema Validation** + + - [ ] Prisma schema is valid: `npx prisma validate` + - [ ] Migration generates correctly: `npx prisma migrate dev` + - [ ] No conflicting field types + - [ ] Relationships are correctly defined + +- [ ] **Migration Testing** + + - [ ] Migration runs successfully on clean database + - [ ] Migration is reversible (if needed) + - [ ] Existing data is preserved (if applicable) + - [ ] Seed script works with new schema + +- [ ] **Application Testing** + + - [ ] All queries still work + - [ ] CRUD operations function correctly + - [ ] No type errors in TypeScript + - [ ] Prisma Client regenerates correctly + +- [ ] **Data Integrity** + - [ ] Foreign keys are enforced + - [ ] Unique constraints work + - [ ] Default values are applied + - [ ] Required fields are enforced + +**Container Commands**: + +```bash +# Inside container +docker exec -it sirius-ui npx prisma db push --force-reset +docker exec -it sirius-ui npm run seed + +# Verify schema +docker exec -it sirius-ui npx prisma validate + +# Check generated client +docker exec -it sirius-ui npx prisma generate +``` + +--- + +### Authentication Changes + +**Applies to**: Changes in `sirius-ui/src/server/auth.ts`, auth-related endpoints + +- [ ] **Login/Logout Testing** + + - [ ] Can log in with valid credentials + - [ ] Login fails with invalid credentials + - [ ] Logout clears session correctly + - [ ] Session persists across page refreshes + +- [ ] **Session Management** + + - [ ] Session timeout works correctly + - [ ] JWT tokens are generated properly + - [ ] Token expiration is handled + - [ ] Refresh tokens work (if implemented) + +- [ ] **Password Security** + + - [ ] Passwords are hashed (never stored plain text) + - [ ] Password reset works correctly + - [ ] Old password verification works + - [ ] Password requirements are enforced + +- [ ] **Protected Routes** + + - [ ] Unauthorized users are redirected to login + - [ ] Authorized users can access protected pages + - [ ] Session state is checked on route changes + +- [ ] **Database State** + - [ ] User records are created/updated correctly + - [ ] Can reset database to default credentials + - [ ] Seed script recreates admin user + +**Testing Commands**: + +```bash +# Reset database to default credentials +docker exec -it sirius-ui npx prisma db push --force-reset +docker exec -it sirius-ui npm run seed + +# Default credentials: admin / password +``` + +**Important**: After testing authentication changes, **reset the database** so other developers aren't affected: + +```bash +docker exec -it sirius-ui npm run seed +``` + +--- + +### Docker/Container Changes + +**Applies to**: Changes in `Dockerfile`, `docker-compose.yaml`, startup scripts + +- [ ] **Build Testing** + + - [ ] Development image builds successfully + - [ ] Production image builds successfully + - [ ] Build time is reasonable + - [ ] Image size is acceptable + +- [ ] **Runtime Testing** + + - [ ] Container starts successfully + - [ ] All processes run correctly + - [ ] Environment variables are loaded + - [ ] Healthchecks pass + +- [ ] **Development Mode** + + - [ ] Hot reload works + - [ ] Volume mounts work correctly + - [ ] Source code changes reflect immediately + - [ ] Debugging is possible + +- [ ] **Production Mode** + + - [ ] Optimized build runs correctly + - [ ] No development dependencies in final image + - [ ] Security scanning passes (if applicable) + - [ ] Startup time is acceptable + +- [ ] **Multi-Container Testing** + - [ ] All containers start together + - [ ] Services can communicate + - [ ] Networking is configured correctly + - [ ] Dependencies start in correct order + +**Testing Commands**: + +```bash +# Test development build +docker compose up --build + +# Test production build +docker compose -f docker-compose.yaml up --build + +# Check container health +docker compose ps + +# View logs for debugging +docker compose logs -f [service-name] + +# Test rebuild after changes +docker compose down +docker compose up --build +``` + +--- + +### Documentation Changes + +**Applies to**: Changes in `documentation/` directory + +- [ ] **Content Quality** + + - [ ] YAML front matter is complete and valid + - [ ] All required sections are present + - [ ] Examples are accurate and tested + - [ ] Links are valid and working + - [ ] Code snippets are correct + +- [ ] **Structure Validation** + + - [ ] Follows appropriate template + - [ ] Consistent formatting throughout + - [ ] Proper markdown syntax + - [ ] Headings are hierarchical + +- [ ] **Documentation Index** + + - [ ] File is added to `README.documentation-index.md` + - [ ] Categorized correctly + - [ ] Description is accurate + +- [ ] **Pre-commit Checks** + - [ ] Quick documentation checks pass + - [ ] Index completeness validation passes + - [ ] No linting errors + +**Testing Commands**: + +```bash +cd testing +make lint-docs-quick # Quick validation +make lint-docs # Full validation +make lint-index # Index completeness check +``` + +--- + +### Git Operations Changes + +**Applies to**: Changes in pre-commit hooks, git workflows + +- [ ] **Pre-commit Hook Testing** + + - [ ] Hook runs on commit attempt + - [ ] Checks execute correctly + - [ ] Failures block commit appropriately + - [ ] Success allows commit to proceed + +- [ ] **Workflow Testing** + + - [ ] Test on feature branch + - [ ] Test on main/demo branch + - [ ] Verify branch detection logic + - [ ] Check optimization flags work + +- [ ] **Documentation** + - [ ] New workflow is documented + - [ ] Examples are provided + - [ ] Troubleshooting section added + +**Testing Commands**: + +```bash +# Test pre-commit hook +git add . +git commit -m "test: validate pre-commit hook" + +# Test on feature branch +git checkout -b test/pre-commit-test +# Make a change and commit + +# Test failure cases +# Intentionally create validation failure +``` + +--- + +## Post-Merge Verification + +After merging to main/demo, verify: + +- [ ] **Container Health** + + - [ ] All containers start successfully + - [ ] No errors in logs + - [ ] Services respond to requests + +- [ ] **Functionality Check** + + - [ ] Core features still work + - [ ] No regressions introduced + - [ ] New feature/fix works as expected + +- [ ] **Rollback Preparedness** + - [ ] Know the last good commit hash + - [ ] Can quickly revert if needed + - [ ] Team is notified of deployment + +--- + +## Troubleshooting Testing Issues + +### Container Won't Start + +```bash +# Check logs +docker compose logs [service-name] + +# Rebuild from scratch +docker compose down -v +docker compose build --no-cache +docker compose up +``` + +### Database Issues + +```bash +# Reset database +docker exec -it sirius-ui npx prisma db push --force-reset +docker exec -it sirius-ui npm run seed +``` + +### Network Issues + +```bash +# Check container networking +docker network ls +docker network inspect sirius_default + +# Restart containers +docker compose restart +``` + +### Build Issues + +```bash +# Clear Docker cache +docker builder prune -a + +# Rebuild specific service +docker compose build --no-cache [service-name] +``` + +--- + +## Continuous Improvement + +**Add new checklists** as you encounter new types of issues: + +1. Document what testing was needed +2. Create a new checklist section +3. Include specific commands and examples +4. Update this document +5. Notify team of new checklist + +**Update existing checklists** based on: + +- Issues that slipped through testing +- New tools or testing approaches +- Feedback from team members +- Changes in technology stack + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/test/README.container-testing.md b/documentation/dev/test/README.container-testing.md new file mode 100644 index 0000000..b574115 --- /dev/null +++ b/documentation/dev/test/README.container-testing.md @@ -0,0 +1,470 @@ +--- +title: "Container Testing" +description: "Comprehensive container testing system for Sirius Scan, providing automated validation of Docker builds, service health, and integration before production deployment" +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Development Team" +tags: ["docker", "testing", "containers", "ci-cd", "validation"] +categories: ["development", "testing", "infrastructure"] +difficulty: "intermediate" +prerequisites: ["docker", "make", "bash"] +related_docs: + - "README.development.md" + - "ABOUT.documentation.md" +dependencies: + - "docker-compose.yaml" + - "testing/container-testing/" + - "testing/Makefile" +llm_context: "high" +search_keywords: + ["container", "testing", "docker", "health-check", "validation", "ci-cd"] +--- + +# Container Testing + +## Purpose + +This document describes the comprehensive container testing system for SiriusScan, providing automated validation of Docker builds, service health, and integration before production deployment. It serves as the definitive guide for developers and DevOps engineers who need to ensure container reliability and system integrity. + +## When to Use + +- **Before every production deployment** - Validate that all containers build and function correctly +- **After making changes to Dockerfiles** - Ensure modifications don't break the build process +- **During development cycles** - Catch container issues early in the development process +- **When troubleshooting container issues** - Use health checks and integration tests to diagnose problems +- **In CI/CD pipelines** - Automated validation of container builds and functionality +- **When onboarding new team members** - Understand the testing infrastructure and processes + +## How to Use + +### Quick Start + +```bash +# Navigate to container testing directory +cd testing/container-testing + +# Run complete test suite (includes runtime auth contract — see below) +make test-all + +# Run specific test types +make test-build # Build validation only +make test-health # Health checks only +make test-integration # Integration tests only +make test-runtime-contract # SIRIUS_API_KEY parity, engine preflight script, API HTTP contract +make test-public-ghcr # anonymous GHCR access for the compose-rendered IMAGE_TAG +make test-release-gates # test-build + test-integration + test-runtime-contract (release bar) + +# Test specific environment +make test-dev # Development environment +make test-prod # Production environment +``` + +**Alternative: Run scripts directly from project root** + +```bash +# From project root directory +./testing/container-testing/test-integration.sh +./testing/container-testing/test-health.sh +./testing/container-testing/test-build.sh +``` + +### Prerequisites + +- Docker Engine 20.10.0+ +- Docker Compose V2 +- Make utility +- curl, nc (netcat), jq (for health checks) +- 4GB RAM minimum (8GB recommended) + +### Step-by-Step Process + +1. **Navigate to container testing directory**: `cd /path/to/Sirius/testing/container-testing` +2. **Run build tests**: `make test-build` to validate all containers build successfully +3. **Run health tests**: `make test-health` to verify services start and respond correctly +4. **Run integration tests**: `make test-integration` to test service interactions +5. **`make test-all` also runs `test-runtime-contract`**, which starts the stack from the repo root and runs `scripts/verify-runtime-auth-contract.sh` (shared `SIRIUS_API_KEY`, postgres parity, authenticated `GET /host/`). +6. **Review results**: Check test output and logs in `testing/logs/` directory + +**Alternative approach** (from project root): + +1. **Navigate to project root**: `cd /path/to/Sirius` +2. **Run tests directly**: `./testing/container-testing/test-integration.sh` +3. **Review results**: Check test output and logs in `testing/logs/` directory + +## What It Is + +### Architecture Overview + +The container testing system consists of these main components: + +- **Build Validation**: Tests individual container builds and Docker Compose configurations +- **Health Checks**: Validates service startup, connectivity, and basic functionality +- **Integration Tests**: Verifies inter-service communication and data flow +- **Runtime Auth Contract** (`make test-runtime-contract`): Runs [`scripts/verify-runtime-auth-contract.sh`](../../../scripts/verify-runtime-auth-contract.sh) against a running stack. Default container names match `container_name` in `docker-compose.yaml` (`sirius-ui`, `sirius-api`, etc.). For a non-default Compose project (e.g. `name: sirius-test`), set `SIRIUS_CONTRACT_CONTAINER_UI`, `SIRIUS_CONTRACT_CONTAINER_API`, `SIRIUS_CONTRACT_CONTAINER_ENGINE`, and `SIRIUS_CONTRACT_CONTAINER_POSTGRES` before running the script. Use `SIRIUS_API_PUBLIC_URL` if the API is not on `http://localhost:9001`. +- **Public GHCR Contract** (`make test-public-ghcr`): Runs [`scripts/verify-ghcr-public-access.sh`](../../../scripts/verify-ghcr-public-access.sh) with the selected `IMAGE_TAG` and checks the exact image refs rendered by `docker-compose.yaml`. Failures distinguish `unauthorized` (visibility/token problem) from `manifest unknown` (tag publication problem). + +### Technical Details + +#### Build Testing System + +**Purpose**: Ensures all containers can be built successfully with correct configurations. + +**Components**: + +- `testing/container-testing/test-build.sh` - Main build validation script +- Tests all Docker Compose configurations (base, dev, prod) +- Validates individual container builds for all services +- Cleans up test images after completion + +**Services Tested**: + +- `sirius-ui` (Next.js frontend) +- `sirius-api` (Go REST API) +- `sirius-engine` (Multi-service container) +- `sirius-postgres` (Database) +- `sirius-valkey` (Cache) +- `sirius-rabbitmq` (Message queue) + +**Build Targets Validated**: + +- Production builds (`production`, `runner`, `runtime` stages) +- Development builds (`development` stage) +- Multi-stage Dockerfile validation + +#### Health Check System + +**Purpose**: Verifies that all services start correctly and respond to basic health checks. + +**Components**: + +- `testing/container-testing/test-health.sh` - Health validation script +- Service-specific health endpoints +- Database connectivity tests +- Port accessibility validation + +**Health Checks Performed**: + +1. **Container Status**: All 6 containers running and healthy +2. **UI Health**: Next.js application serving content on port 3000 +3. **API Health**: Go API responding on port 9001 with `/health` endpoint +4. **Engine Health**: Process validation for sirius-engine container +5. **Database Health**: PostgreSQL connectivity and readiness +6. **Cache Health**: Valkey/Redis responding to ping commands +7. **Queue Health**: RabbitMQ broker status and connectivity +8. **Port Accessibility**: External port binding validation + +#### Integration Testing System + +**Purpose**: Tests inter-service communication and data flow between components. + +**Components**: + +- `testing/container-testing/test-integration.sh` - Integration validation script +- Service-to-service communication tests +- Database integration validation +- Message queue functionality tests + +**Integration Tests**: + +- API to Database connectivity +- UI to API communication +- Engine to Message Queue integration +- Cross-service data validation + +### Implementation Details + +#### File Structure + +``` +testing/ +├── container-testing/ +│ ├── test-build.sh # Build validation +│ ├── test-health.sh # Health checks +│ ├── test-integration.sh # Integration tests +│ └── Makefile # Container testing commands +├── logs/ # Test execution logs +│ ├── build_test_*.log +│ ├── health_test_*.log +│ └── integration_test_*.log +└── README.md # Testing documentation +``` + +**Note**: The Makefile is located in the `container-testing/` directory and should be run from there. The test scripts can be run either from the `container-testing/` directory via Makefile or directly from the project root. + +#### Makefile Integration + +The testing system uses a dedicated Makefile in the `container-testing/` directory: + +```makefile +# Testing targets (run from testing/container-testing/) +test-all: test-build test-health test-integration +test-build: ./test-build.sh +test-health: ./test-health.sh +test-integration: ./test-integration.sh + +# Environment-specific testing +test-dev: ./test-health.sh dev +test-prod: ./test-health.sh prod +``` + +**Usage**: + +- Run from `testing/container-testing/` directory: `make test-all` +- Or run scripts directly from project root: `./testing/container-testing/test-integration.sh` + +#### Logging and Reporting + +**Log Files**: All test executions create timestamped log files in `testing/logs/` + +- Format: `{test_type}_test_{timestamp}.log` +- Contains: Full command output, test results, error details +- Retention: Logs are kept for troubleshooting and analysis + +**Test Results**: Each test provides clear pass/fail indicators: + +- ✅ PASSED: Test completed successfully +- ❌ FAILED: Test failed with error details +- Summary: Total tests, passed, failed counts + +#### Environment Support + +**Development Environment**: + +- Uses `docker-compose.dev.yaml` overrides +- Includes volume mounts for live development +- Accounts for longer startup times due to dependency downloads + +**Production Environment**: + +- Uses `docker-compose.prod.yaml` overrides +- Tests production-optimized builds +- Validates production configuration + +**Base Environment**: + +- Uses standard `docker-compose.yaml` +- Tests default configuration +- Validates core functionality + +### Advanced Topics + +#### Custom Test Configuration + +**Environment Variables**: + +```bash +export TEST_RETRIES=120 # Retry attempts (default: 60, dev mode: 120) +export LOG_LEVEL=debug # Logging verbosity (info, debug) +``` + +**Timeout Configuration**: + +- **Default**: 60 retries × 2 seconds = 120 seconds total +- **Development Mode**: Automatically increases to 120 retries × 2 seconds = 240 seconds total +- **Custom**: Override with `TEST_RETRIES` environment variable + +**Custom Test Execution**: + +```bash +# Run with custom timeout (4 minutes) +TEST_RETRIES=120 ./testing/scripts/test-health.sh dev + +# Run with debug logging +LOG_LEVEL=debug ./testing/scripts/test-health.sh dev + +# Run with both custom timeout and debug logging +TEST_RETRIES=180 LOG_LEVEL=debug ./testing/scripts/test-health.sh dev +``` + +#### Performance Monitoring + +**Resource Usage Tracking**: + +- Container startup times +- Memory and CPU usage during tests +- Build time optimization +- Service response times + +**Optimization Opportunities**: + +- Parallel test execution +- Build cache utilization +- Service startup optimization +- Resource limit tuning + +#### Security Considerations + +**Test Isolation**: + +- Tests run in isolated Docker networks +- No external network access during testing +- Cleanup procedures remove all test artifacts + +**Security Validation**: + +- Container security scanning (future enhancement) +- Vulnerability assessment (future enhancement) +- Secret management validation (future enhancement) + +## Troubleshooting + +### FAQ + +**Q: Why do health tests fail with "API not ready yet" errors?** +A: The sirius-api service takes time to download Go dependencies in development mode. The health check automatically increases timeout to 4 minutes for dev mode, and includes fallback validation for this scenario. + +**Q: Why does development mode take longer than production mode?** +A: Development mode downloads Go dependencies at runtime, which can take 2-4 minutes depending on your internet connection. Production mode pre-builds these dependencies, so it starts much faster. + +**Q: How do I run tests for a specific service only?** +A: Modify the test scripts to comment out unwanted services, or use Docker Compose to start only the services you need to test. + +**Q: What if build tests fail with "target stage not found" errors?** +A: Check that Docker Compose files reference correct Dockerfile stage names. Common stages are `development`, `production`, `runtime`, and `runner`. + +**Q: How can I increase test timeout for slow systems?** +A: Set the `TEST_RETRIES` environment variable: `export TEST_RETRIES=120 && make test-health` (120 retries = 4 minutes total) + +**Q: Why do integration tests fail with connection refused errors?** +A: Ensure all services are fully started before running integration tests. Use `docker compose ps` to verify service status. + +**Q: How do I debug a specific test failure?** +A: Check the timestamped log file in `testing/logs/` for detailed error information and command output. + +**Q: Can I run tests in parallel?** +A: Currently tests run sequentially to avoid resource conflicts. Parallel execution is planned for future enhancement. + +**Q: What if I need to test with custom Docker images?** +A: Modify the test scripts to use your custom image tags, or update the Docker Compose files to reference your images. + +### Command Reference + +```bash +# From testing/container-testing/ directory +make test-all +make test-build +make test-health +make test-integration +make test-public-ghcr +make test-dev +make test-prod + +# Or from project root directory +./testing/container-testing/test-build.sh +./testing/container-testing/test-health.sh dev +./testing/container-testing/test-integration.sh prod + +# Docker Compose validation +docker compose config --quiet +docker compose -f docker-compose.yaml -f docker-compose.dev.yaml config --quiet + +# Service health checks +docker compose ps +docker compose logs sirius-api +curl -f http://localhost:9001/health + +# Container debugging +docker exec -it sirius-engine /bin/bash +docker logs sirius-engine --tail 50 -f + +# Cleanup +docker compose down -v +docker system prune -f +``` + +### Common Issues and Solutions + +| Issue | Symptoms | Solution | +| --------------------- | --------------------------------- | --------------------------------------------------------- | +| Build failures | "target stage not found" errors | Check Dockerfile stage names in Compose files | +| Health check timeouts | "service not ready" errors | Increase timeout or check service logs | +| Port conflicts | "port already in use" errors | Stop conflicting services or change ports | +| Permission errors | "permission denied" in containers | Check file permissions and Docker daemon access | +| Network issues | "connection refused" errors | Verify Docker network configuration | +| Resource exhaustion | Out of memory errors | Increase Docker memory limits or close other applications | + +### Debugging Steps + +1. **Check service status**: `docker compose ps` to see which containers are running +2. **Review service logs**: `docker compose logs [service-name]` for error details +3. **Verify network connectivity**: `docker network ls` and `docker network inspect sirius` +4. **Test individual components**: Run health checks manually with curl commands +5. **Check resource usage**: `docker stats` to monitor CPU and memory usage +6. **Validate configuration**: `docker compose config` to check for syntax errors + +### Log Analysis + +**Build Test Logs**: + +```bash +# View build test results +tail -f testing/logs/build_test_*.log + +# Check for specific errors +grep -i "error\|failed" testing/logs/build_test_*.log +``` + +**Health Test Logs**: + +```bash +# Monitor health check progress +tail -f testing/logs/health_test_*.log + +# Find failed tests +grep -i "failed\|error" testing/logs/health_test_*.log +``` + +**Integration Test Logs**: + +```bash +# Check integration test results +cat testing/logs/integration_test_*.log + +# Analyze service communication +grep -i "connection\|timeout" testing/logs/integration_test_*.log +``` + +### Performance Troubleshooting + +**Slow Build Times**: + +- Check Docker BuildKit is enabled: `export DOCKER_BUILDKIT=1` +- Clear Docker cache: `docker builder prune` +- Use build cache mounts for dependencies + +**Slow Service Startup**: + +- Check system resources: `docker stats` +- Optimize Dockerfile layers +- Use multi-stage builds efficiently + +**Test Execution Time**: + +- Run tests in parallel (future enhancement) +- Optimize health check intervals +- Use faster base images where possible + +### Lessons Learned + +**2025-01-03**: Implemented comprehensive container testing system to address build reliability issues. Key insight: Automated testing prevents deployment failures and improves development confidence. + +**2025-01-03**: Created health check system with fallback validation for services with longer startup times. Lesson: Account for real-world service startup patterns in test design. + +**2025-01-03**: Established layered testing approach (build → health → integration). Benefit: Catches issues at appropriate levels and provides clear failure isolation. + +**2025-01-03**: Implemented timestamped logging system for all test executions. Advantage: Enables detailed troubleshooting and historical analysis of test failures. + +## LLM Context + +[Additional context specifically for Large Language Models:] + +- **Key Concepts**: Container testing involves build validation, health checks, and integration testing to ensure Docker containers work correctly before deployment +- **Technical Context**: Uses Docker Compose for orchestration, shell scripts for automation, and Make for command execution. Tests cover 6 services: UI, API, Engine, PostgreSQL, Valkey, and RabbitMQ +- **Common Patterns**: Layered testing approach (build → health → integration), automated cleanup, timestamped logging, environment-specific configurations +- **Edge Cases**: API dependency downloading in dev mode, service startup timing variations, port conflicts, resource constraints +- **Integration Points**: Connects with CI/CD pipelines, deployment processes, monitoring systems, and development workflows + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/dev/test/README.documentation-testing.md b/documentation/dev/test/README.documentation-testing.md new file mode 100644 index 0000000..573f541 --- /dev/null +++ b/documentation/dev/test/README.documentation-testing.md @@ -0,0 +1,437 @@ +--- +title: "Documentation Testing" +description: "Comprehensive documentation testing system for Sirius project, providing automated validation of documentation quality, structure, and completeness using specialized linters." +template: "TEMPLATE.documentation-standard" +version: "1.0.0" +last_updated: "2025-01-03" +author: "Development Team" +tags: ["documentation", "testing", "linting", "validation", "quality"] +categories: ["development", "testing", "documentation"] +difficulty: "intermediate" +prerequisites: ["markdown", "yaml", "bash"] +related_docs: + - "README.container-testing.md" + - "ABOUT.documentation.md" +dependencies: + - "scripts/documentation/" + - "testing/Makefile" +llm_context: "high" +search_keywords: + ["documentation", "testing", "linting", "validation", "yaml", "markdown"] +--- + +# Documentation Testing + +## Purpose + +This document describes the comprehensive documentation testing system for the Sirius project, providing automated validation of documentation quality, structure, and completeness. It serves as the definitive guide for developers and technical writers who need to ensure documentation meets our standards and is optimized for LLM consumption. + +## When to Use + +- **Before committing documentation changes** - Validate that all documentation meets our standards +- **During documentation reviews** - Ensure consistency and completeness across all docs +- **When creating new documentation** - Verify proper structure and metadata +- **In CI/CD pipelines** - Automated validation of documentation quality +- **When troubleshooting documentation issues** - Use linters to identify specific problems +- **For LLM optimization** - Ensure documentation is properly structured for AI consumption + +## How to Use + +### Quick Start + +```bash +# Navigate to container testing directory +cd testing/container-testing + +# Run complete documentation testing +make lint-docs + +# Run quick documentation checks +make lint-docs-quick + +# Check documentation index completeness +make lint-index + +# Run all validation including documentation +make validate-all +``` + +### Prerequisites + +- Bash shell environment +- `yq` utility (for full YAML validation) +- `grep`, `sed`, `awk` (standard Unix tools) +- Make utility +- Git (for pre-commit hooks) + +### Step-by-Step Process + +1. **Navigate to container testing directory**: `cd /path/to/Sirius/testing/container-testing` +2. **Run quick checks**: `make lint-docs-quick` for basic validation +3. **Run full linting**: `make lint-docs` for comprehensive validation +4. **Check index completeness**: `make lint-index` to verify all files are indexed +5. **Review results**: Check output and logs in `tmp/` directory + +## What It Is + +### Architecture Overview + +The documentation testing system consists of three main components: + +- **YAML Front Matter Validation**: Ensures all documents have complete and valid metadata +- **Template Compliance Checking**: Verifies documents follow their specified templates +- **Index Completeness Validation**: Ensures all documentation files are properly indexed + +### Technical Details + +#### YAML Front Matter Validation + +**Purpose**: Ensures all documentation files have complete and valid YAML front matter. + +**Components**: + +- `scripts/documentation/lint-docs.sh` - Main validation script +- `scripts/documentation/lint-quick.sh` - Quick validation script +- Validates required and optional fields +- Checks field value validity + +**Required Fields**: + +- `title` - Human-readable document title +- `description` - Brief purpose description +- `template` - Template used to create document +- `version` - Document version +- `last_updated` - Last modification date + +**Optional Fields**: + +- `author` - Document author +- `tags` - Searchable tags +- `categories` - Document categories +- `difficulty` - Complexity level (beginner, intermediate, advanced) +- `prerequisites` - Required knowledge +- `related_docs` - Related documentation +- `dependencies` - Required files/systems +- `llm_context` - LLM relevance level (high, medium, low) +- `search_keywords` - Search optimization + +**Validation Rules**: + +- YAML syntax must be valid +- Required fields must be present +- Field values must match valid options +- Template references must exist +- Related documents must exist + +#### Template Compliance Checking + +**Purpose**: Verifies that documents follow their specified template structure. + +**Components**: + +- Template file parsing and section extraction +- Document section comparison +- Missing section detection +- Custom document support + +**Supported Templates**: + +- `TEMPLATE.documentation-standard` - Standard documentation +- `TEMPLATE.guide` - Step-by-step guides +- `TEMPLATE.troubleshooting` - Problem-solving docs +- `TEMPLATE.about` - About documents +- `TEMPLATE.reference` - Technical specifications +- `TEMPLATE.architecture` - System design docs +- `TEMPLATE.api` - API documentation +- `TEMPLATE.template` - Template documents +- `TEMPLATE.custom` - Custom documents (no compliance checking) + +**Compliance Rules**: + +- Documents must have all required sections from their template +- Section headings must match exactly +- Custom documents are exempt from compliance checking +- Meta-documents (ABOUT files) are exempt from compliance checking + +#### Index Completeness Validation + +**Purpose**: Ensures all documentation files are properly referenced in the documentation index. + +**Components**: + +- `scripts/documentation/lint-index.sh` - Index validation script +- File discovery in `documentation/dev/` directory +- Index parsing and link extraction +- Missing file detection +- Extra file detection + +**Validation Rules**: + +- All files in `dev/` must be referenced in the index +- All referenced files must exist in `dev/` +- No duplicate references allowed +- Footer links are excluded from validation + +### Implementation Details + +#### File Structure + +``` +scripts/documentation/ +├── lint-docs.sh # Full documentation linting +├── lint-quick.sh # Quick documentation checks +└── lint-index.sh # Index completeness validation + +testing/ +├── Makefile # Testing commands +└── tmp/ # Linting logs and output + ├── documentation-lint-*.log + └── index-lint-*.log +``` + +#### Makefile Integration + +The documentation testing system integrates with the testing Makefile: + +```makefile +# Documentation testing targets +lint-docs: ../scripts/documentation/lint-docs.sh +lint-docs-quick: ../scripts/documentation/lint-quick.sh +lint-index: ../scripts/documentation/lint-index.sh + +# Full validation including documentation +validate-all: build-all test-all lint-docs +``` + +#### Logging and Reporting + +**Log Files**: All linting executions create timestamped log files in `tmp/` + +- Format: `{lint_type}-{timestamp}.log` +- Contains: Full validation output, errors, warnings +- Retention: Logs are kept for troubleshooting + +**Validation Results**: Each validation provides clear indicators: + +- ✅ PASSED: Validation completed successfully +- ❌ FAILED: Validation failed with error details +- ⚠️ WARNING: Non-critical issues found +- Summary: Total files, passed, failed counts + +#### Pre-commit Integration + +**Pre-commit Hook**: `.git/hooks/pre-commit` runs documentation validation: + +1. **Quick documentation linting** - Basic validation +2. **Index completeness check** - Ensures all files are indexed +3. **Build tests** - Validates system still works + +**Hook Behavior**: + +- Runs from project root or testing directory +- Fails commit if validation fails +- Provides clear error messages +- Suggests fixes for common issues + +### Advanced Topics + +#### Custom Validation Rules + +**Environment Variables**: + +```bash +export DOCS_DIR="../documentation/dev" # Documentation directory +export TEMPLATES_DIR="../documentation/dev/templates" # Templates directory +export LOG_LEVEL="debug" # Logging verbosity +``` + +**Custom Validation**: + +```bash +# Run with custom documentation directory +DOCS_DIR="../custom-docs" make lint-docs + +# Run with debug logging +LOG_LEVEL="debug" make lint-docs + +# Run with custom template directory +TEMPLATES_DIR="../custom-templates" make lint-docs +``` + +#### Template Development + +**Creating New Templates**: + +1. **Copy base template**: `cp TEMPLATE.template.md TEMPLATE.new-type.md` +2. **Define structure**: Add required sections for new document type +3. **Update validation**: Add new template to `VALID_TEMPLATES` array +4. **Test validation**: Run `make lint-docs` to verify template works + +**Template Requirements**: + +- Must include YAML front matter +- Must define clear section structure +- Must be self-documenting +- Must follow naming conventions + +#### LLM Optimization + +**Context Building**: + +- Rich metadata in front matter +- Consistent structure across documents +- Clear relationships between documents +- Comprehensive search keywords + +**AI-Friendly Features**: + +- Structured content for predictable parsing +- Detailed descriptions for AI understanding +- Working examples with expected outputs +- Comprehensive troubleshooting information + +## Troubleshooting + +### FAQ + +**Q: Why do I get "Template file not found" warnings?** +A: The quick linter looks for template files in the wrong location. This is a known issue and doesn't affect functionality. Use `make lint-docs` for accurate validation. + +**Q: Why does index linting fail with "Missing from index" errors?** +A: Some documentation files are not referenced in the documentation index. Add them to `documentation/README.documentation-index.md` or remove unused files. + +**Q: How do I fix "Invalid difficulty value" errors?** +A: Difficulty must be one of: "beginner", "intermediate", "advanced". Check your YAML front matter for typos. + +**Q: Why do I get "Missing section" warnings?** +A: Your document is missing required sections from its template. Compare your document structure with the template file. + +**Q: How do I add a new document type?** +A: Create a new template file, add it to the validation system, and update the documentation index. + +**Q: Why does pre-commit hook fail?** +A: Check the error messages in the terminal. Common issues include missing YAML front matter, invalid field values, or missing index entries. + +**Q: How do I disable validation for a specific document?** +A: Use `TEMPLATE.custom` template type, which skips template compliance checking. + +**Q: Can I run validation on specific files only?** +A: Modify the linting scripts to target specific files, or use grep to filter the file list. + +### Command Reference + +```bash +# Complete documentation validation +make lint-docs + +# Quick documentation checks +make lint-docs-quick + +# Index completeness validation +make lint-index + +# Full system validation +make validate-all + +# Manual script execution +../scripts/documentation/lint-docs.sh +../scripts/documentation/lint-quick.sh +../scripts/documentation/lint-index.sh + +# Check specific validation +grep -r "template:" ../documentation/dev/ +grep -r "llm_context: high" ../documentation/dev/ +grep -r "difficulty:" ../documentation/dev/ + +# Debug validation issues +LOG_LEVEL=debug make lint-docs +tail -f tmp/documentation-lint-*.log +``` + +### Common Issues and Solutions + +| Issue | Symptoms | Solution | +| -------------------- | --------------------------------- | --------------------------------------------------- | +| Missing front matter | "No YAML metadata" errors | Add complete YAML front matter with required fields | +| Invalid field values | "Invalid difficulty value" errors | Check field values against valid options | +| Template compliance | "Missing section" warnings | Compare document structure with template | +| Index completeness | "Missing from index" errors | Add files to documentation index | +| Broken links | "File not found" errors | Fix file paths in related_docs | +| YAML syntax errors | "YAML parse error" messages | Fix YAML syntax in front matter | + +### Debugging Steps + +1. **Check log files**: Review timestamped logs in `tmp/` directory +2. **Run quick validation**: Use `make lint-docs-quick` for basic checks +3. **Validate YAML syntax**: Check front matter for syntax errors +4. **Compare with templates**: Ensure document follows template structure +5. **Check index entries**: Verify all files are properly indexed +6. **Test individual files**: Run validation on specific files + +### Log Analysis + +**Documentation Lint Logs**: + +```bash +# View validation results +tail -f tmp/documentation-lint-*.log + +# Check for specific errors +grep -i "error\|failed" tmp/documentation-lint-*.log + +# Find warnings +grep -i "warning" tmp/documentation-lint-*.log +``` + +**Index Lint Logs**: + +```bash +# View index validation results +cat tmp/index-lint-*.log + +# Check missing files +grep "missing from index" tmp/index-lint-*.log + +# Check extra files +grep "extra files in index" tmp/index-lint-*.log +``` + +### Performance Optimization + +**Faster Validation**: + +- Use `make lint-docs-quick` for development +- Run validation on specific files only +- Optimize template file parsing +- Cache validation results + +**Resource Usage**: + +- Monitor disk space for log files +- Clean up old log files regularly +- Use efficient file parsing methods +- Optimize regex patterns + +### Lessons Learned + +**2025-01-03**: Implemented comprehensive documentation testing system to ensure consistency and quality. Key insight: Automated validation prevents documentation drift and improves maintainability. + +**2025-01-03**: Created template compliance checking with support for custom documents. Lesson: Flexibility is important for meta-documents and special cases. + +**2025-01-03**: Established index completeness validation to ensure all documentation is discoverable. Benefit: Prevents orphaned documentation and improves navigation. + +**2025-01-03**: Integrated documentation testing with pre-commit hooks for automated quality assurance. Advantage: Catches documentation issues before they reach the repository. + +## LLM Context + +[Additional context specifically for Large Language Models:] + +- **Key Concepts**: Documentation testing involves YAML validation, template compliance, and index completeness to ensure documentation quality and consistency +- **Technical Context**: Uses shell scripts for automation, YAML parsing for metadata validation, and regex for content analysis. Tests cover 14 documentation files with 8 different templates +- **Common Patterns**: Layered validation approach (quick → full → index), automated cleanup, timestamped logging, pre-commit integration +- **Edge Cases**: Custom documents exempt from template compliance, meta-documents with unique structure, footer links excluded from index validation +- **Integration Points**: Connects with git hooks, CI/CD pipelines, development workflows, and documentation maintenance processes + +--- + +_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._ diff --git a/documentation/environment.jpg b/documentation/environment.jpg new file mode 100644 index 0000000..6a6af9c Binary files /dev/null and b/documentation/environment.jpg differ diff --git a/documentation/host.jpg b/documentation/host.jpg new file mode 100644 index 0000000..2b4af6c Binary files /dev/null and b/documentation/host.jpg differ diff --git a/documentation/scanner.jpg b/documentation/scanner.jpg new file mode 100644 index 0000000..10dddad Binary files /dev/null and b/documentation/scanner.jpg differ diff --git a/documentation/terminal.jpg b/documentation/terminal.jpg new file mode 100644 index 0000000..ccf5059 Binary files /dev/null and b/documentation/terminal.jpg differ diff --git a/documentation/vulnerability-navigator.jpg b/documentation/vulnerability-navigator.jpg new file mode 100644 index 0000000..dc2b833 Binary files /dev/null and b/documentation/vulnerability-navigator.jpg differ diff --git a/documentation/vulnerability.jpg b/documentation/vulnerability.jpg new file mode 100644 index 0000000..3c73e0e Binary files /dev/null and b/documentation/vulnerability.jpg differ diff --git a/installer/Dockerfile b/installer/Dockerfile new file mode 100644 index 0000000..3a35907 --- /dev/null +++ b/installer/Dockerfile @@ -0,0 +1,14 @@ +FROM golang:1.24-alpine AS builder +WORKDIR /src + +COPY installer/go.mod ./go.mod +COPY installer/cmd ./cmd +COPY installer/internal ./internal + +RUN go build -o /out/sirius-installer ./cmd/sirius-installer + +FROM alpine:3.20 +WORKDIR /workspace +COPY --from=builder /out/sirius-installer /usr/local/bin/sirius-installer + +ENTRYPOINT ["sirius-installer"] diff --git a/installer/README.md b/installer/README.md new file mode 100644 index 0000000..50506de --- /dev/null +++ b/installer/README.md @@ -0,0 +1,53 @@ +# Sirius Installer + +`sirius-installer` is the first-run setup utility for Sirius startup and secrets configuration. + +## What it does + +- Reads template values from `.env.production.example` +- Merges with existing `.env` values (idempotent by default) +- Generates missing required secrets: + - `SIRIUS_API_KEY` + - `POSTGRES_PASSWORD` + - `NEXTAUTH_SECRET` + - `INITIAL_ADMIN_PASSWORD` +- Builds `DATABASE_URL` from `POSTGRES_*` values (with proper URL-encoding) + - Automatically refreshed whenever `POSTGRES_PASSWORD` is generated + - Preserved as-is if you set it manually and the password is unchanged +- Supports interactive and non-interactive modes +- Supports `--force` regeneration and secret-safe output flags + +## Recommended usage from repository root + +Use the installer Compose entrypoint (preferred): + +```bash +docker compose -f docker-compose.installer.yaml run --rm sirius-installer +``` + +## Local usage + +```bash +cd installer +go run ./cmd/sirius-installer --template ../.env.production.example --output ../.env +``` + +## Docker usage + +```bash +docker compose -f docker-compose.installer.yaml run --rm sirius-installer +``` + +## Non-interactive usage + +```bash +docker compose -f docker-compose.installer.yaml run --rm sirius-installer \ + --non-interactive \ + --no-print-secrets +``` + +## Useful flags + +- `--force`: regenerate required secrets even if they already exist +- `--non-interactive`: never prompt; suitable for CI/user-data +- `--no-print-secrets`: suppress secret values in installer output diff --git a/installer/cmd/sirius-installer/main.go b/installer/cmd/sirius-installer/main.go new file mode 100644 index 0000000..e26fc55 --- /dev/null +++ b/installer/cmd/sirius-installer/main.go @@ -0,0 +1,286 @@ +package main + +import ( + "bufio" + "crypto/rand" + "encoding/hex" + "errors" + "flag" + "fmt" + "os" + "path/filepath" + "strings" + + "github.com/SiriusScan/sirius-installer/internal/config" + "github.com/SiriusScan/sirius-installer/internal/prompt" +) + +type cliOptions struct { + TemplatePath string + OutputPath string + Force bool + NonInteractive bool + Quiet bool + PrintSecrets bool + NoPrintSecrets bool + AdminPassword string + NextAuthURL string + SiriusAPIURL string + NextPublicAPIURL string + CORSOrigins string +} + +func main() { + opts := parseFlags() + if err := run(opts); err != nil { + fmt.Fprintf(os.Stderr, "sirius-installer error: %v\n", err) + os.Exit(1) + } +} + +func parseFlags() cliOptions { + var opts cliOptions + flag.StringVar(&opts.TemplatePath, "template", ".env.production.example", "path to .env template") + flag.StringVar(&opts.OutputPath, "output", ".env", "path to generated .env output") + flag.BoolVar(&opts.Force, "force", false, "regenerate required secrets even when already set") + flag.BoolVar(&opts.NonInteractive, "non-interactive", false, "disable prompts and use generated/default values") + flag.BoolVar(&opts.Quiet, "quiet", false, "minimize output") + flag.BoolVar(&opts.PrintSecrets, "print-secrets", true, "print generated secrets to stdout") + flag.BoolVar(&opts.NoPrintSecrets, "no-print-secrets", false, "never print generated secrets") + flag.StringVar(&opts.AdminPassword, "admin-password", "", "explicit initial admin password") + flag.StringVar(&opts.NextAuthURL, "nextauth-url", "", "override NEXTAUTH_URL") + flag.StringVar(&opts.SiriusAPIURL, "sirius-api-url", "", "override SIRIUS_API_URL") + flag.StringVar(&opts.NextPublicAPIURL, "next-public-sirius-api-url", "", "override NEXT_PUBLIC_SIRIUS_API_URL") + flag.StringVar(&opts.CORSOrigins, "cors-origins", "", "override CORS_ALLOWED_ORIGINS") + flag.Parse() + return opts +} + +func run(opts cliOptions) error { + if opts.NoPrintSecrets { + opts.PrintSecrets = false + } + + templateFile, err := loadOrEmpty(opts.TemplatePath, false) + if err != nil { + return fmt.Errorf("failed to read template file %q: %w", opts.TemplatePath, err) + } + + outputFile, err := loadOrEmpty(opts.OutputPath, true) + if err != nil { + return fmt.Errorf("failed to read output file %q: %w", opts.OutputPath, err) + } + + cfgOpts := config.Options{ + Force: opts.Force, + NonInteractive: opts.NonInteractive, + AdminPassword: opts.AdminPassword, + NextAuthURL: opts.NextAuthURL, + SiriusAPIURL: opts.SiriusAPIURL, + NextPublicAPIURL: opts.NextPublicAPIURL, + CORSAllowedOrigin: opts.CORSOrigins, + } + + if !opts.NonInteractive { + cfgOpts, err = gatherInteractive(cfgOpts) + if err != nil { + return err + } + } + + merged := config.Merge(templateFile.Values, outputFile.Values, cfgOpts) + finalVals, generated, err := config.EnsureRequired(merged, cfgOpts) + if err != nil { + return err + } + + apiKey, wasGenerated, err := resolveInternalAPIKey(opts.OutputPath, finalVals["SIRIUS_API_KEY"], opts.Force) + if err != nil { + return err + } + if wasGenerated { + generated["SIRIUS_API_KEY"] = apiKey + } + delete(finalVals, "SIRIUS_API_KEY") + + rendered := config.Render(templateFile, finalVals) + if err := writeSecure(opts.OutputPath, rendered); err != nil { + return err + } + + if err := writeSiriusAPISecretFile(opts.OutputPath, apiKey); err != nil { + return fmt.Errorf("write internal API secret file: %w", err) + } + if err := verifySiriusAPISecretFile(opts.OutputPath, apiKey); err != nil { + return fmt.Errorf("verify internal API secret file: %w", err) + } + + if !opts.Quiet { + fmt.Printf("Sirius installer wrote %s\n", opts.OutputPath) + fmt.Println("Required startup secrets are configured.") + } + + if opts.PrintSecrets && len(generated) > 0 { + fmt.Println("\nGenerated values (save securely):") + for _, key := range []string{ + "SIRIUS_API_KEY", + "POSTGRES_PASSWORD", + "NEXTAUTH_SECRET", + "INITIAL_ADMIN_PASSWORD", + } { + if v, ok := generated[key]; ok { + fmt.Printf("- %s=%s\n", key, v) + } + } + } + + if !opts.Quiet { + fmt.Println("\nNext step:") + fmt.Println("docker compose up -d") + } + return nil +} + +func gatherInteractive(in config.Options) (config.Options, error) { + reader := bufio.NewReader(os.Stdin) + + if strings.TrimSpace(in.AdminPassword) == "" { + pw, err := prompt.AskOptional(reader, "Initial admin password") + if err != nil { + return in, err + } + in.AdminPassword = pw + } + + currentURL := fallback(in.NextAuthURL, "http://localhost:3000") + url, err := prompt.Ask(reader, "NEXTAUTH_URL", currentURL) + if err != nil { + return in, err + } + in.NextAuthURL = url + + currentAPI := fallback(in.NextPublicAPIURL, "http://localhost:9001") + pubAPI, err := prompt.Ask(reader, "NEXT_PUBLIC_SIRIUS_API_URL", currentAPI) + if err != nil { + return in, err + } + in.NextPublicAPIURL = pubAPI + return in, nil +} + +func resolveInternalAPIKey(envOutputPath, legacyEnvValue string, force bool) (string, bool, error) { + if !force { + if existing, err := readSiriusAPISecretFile(envOutputPath); err == nil { + if existing != "" { + return existing, false, nil + } + } else if !errors.Is(err, os.ErrNotExist) { + return "", false, fmt.Errorf("read existing secrets/sirius_api_key.txt: %w", err) + } + if trimmed := strings.TrimSpace(legacyEnvValue); trimmed != "" && !config.IsPlaceholder(trimmed) { + return trimmed, false, nil + } + } + + generated, err := randomHex(32) + if err != nil { + return "", false, err + } + return generated, true, nil +} + +func loadOrEmpty(path string, allowMissing bool) (*config.EnvFile, error) { + f, err := config.ParseEnvFile(path) + if err == nil { + return f, nil + } + if allowMissing && errors.Is(err, os.ErrNotExist) { + return config.NewEmptyEnvFile(), nil + } + return nil, err +} + +func readSiriusAPISecretFile(envOutputPath string) (string, error) { + rootDir := filepath.Dir(envOutputPath) + if rootDir == "" || rootDir == "." { + rootDir = "." + } + path := filepath.Join(rootDir, "secrets", "sirius_api_key.txt") + raw, err := os.ReadFile(path) + if err != nil { + return "", err + } + return strings.TrimSpace(string(raw)), nil +} + +// writeSiriusAPISecretFile writes secrets/sirius_api_key.txt next to the .env file +// so docker compose can mount it as the sirius_api_key secret. +func writeSiriusAPISecretFile(envOutputPath, apiKey string) error { + apiKey = strings.TrimSpace(apiKey) + if apiKey == "" { + return fmt.Errorf("SIRIUS_API_KEY is empty; cannot write secrets/sirius_api_key.txt") + } + rootDir := filepath.Dir(envOutputPath) + if rootDir == "" || rootDir == "." { + rootDir = "." + } + secDir := filepath.Join(rootDir, "secrets") + if err := os.MkdirAll(secDir, 0o700); err != nil { + return fmt.Errorf("create secrets directory: %w", err) + } + path := filepath.Join(secDir, "sirius_api_key.txt") + content := apiKey + "\n" + // 0644 so non-root service UIDs (e.g. 1001 in sirius-api) can read the host + // file when Docker Compose bind-mounts it as /run/secrets/sirius_api_key. + if err := os.WriteFile(path, []byte(content), 0o644); err != nil { + return err + } + return nil +} + +func verifySiriusAPISecretFile(envOutputPath, apiKey string) error { + apiKey = strings.TrimSpace(apiKey) + rootDir := filepath.Dir(envOutputPath) + if rootDir == "" || rootDir == "." { + rootDir = "." + } + path := filepath.Join(rootDir, "secrets", "sirius_api_key.txt") + raw, err := os.ReadFile(path) + if err != nil { + return err + } + if strings.TrimSpace(string(raw)) != apiKey { + return fmt.Errorf("%s does not match generated internal API key", path) + } + return nil +} + +func randomHex(numBytes int) (string, error) { + buf := make([]byte, numBytes) + if _, err := rand.Read(buf); err != nil { + return "", fmt.Errorf("failed to read random bytes: %w", err) + } + return hex.EncodeToString(buf), nil +} + +func writeSecure(path, content string) error { + abs, err := filepath.Abs(path) + if err == nil { + dir := filepath.Dir(abs) + if mkErr := os.MkdirAll(dir, 0o755); mkErr != nil { + return fmt.Errorf("failed to create output directory %q: %w", dir, mkErr) + } + } + + if err := os.WriteFile(path, []byte(content), 0o600); err != nil { + return fmt.Errorf("failed writing %s: %w", path, err) + } + return nil +} + +func fallback(v, d string) string { + if strings.TrimSpace(v) == "" { + return d + } + return v +} diff --git a/installer/go.mod b/installer/go.mod new file mode 100644 index 0000000..283a31d --- /dev/null +++ b/installer/go.mod @@ -0,0 +1,3 @@ +module github.com/SiriusScan/sirius-installer + +go 1.24 diff --git a/installer/internal/config/envfile.go b/installer/internal/config/envfile.go new file mode 100644 index 0000000..f2d5f7d --- /dev/null +++ b/installer/internal/config/envfile.go @@ -0,0 +1,129 @@ +package config + +import ( + "bufio" + "os" + "sort" + "strings" +) + +type LineKind string + +const ( + KindBlank LineKind = "blank" + KindComment LineKind = "comment" + KindKV LineKind = "kv" +) + +type Line struct { + Kind LineKind + Raw string + Key string + Value string +} + +type EnvFile struct { + Lines []Line + Values map[string]string +} + +func ParseEnvFile(path string) (*EnvFile, error) { + f, err := os.Open(path) + if err != nil { + return nil, err + } + defer f.Close() + + out := &EnvFile{ + Lines: make([]Line, 0, 64), + Values: make(map[string]string), + } + + scanner := bufio.NewScanner(f) + for scanner.Scan() { + raw := scanner.Text() + trimmed := strings.TrimSpace(raw) + if trimmed == "" { + out.Lines = append(out.Lines, Line{Kind: KindBlank, Raw: raw}) + continue + } + if strings.HasPrefix(trimmed, "#") { + out.Lines = append(out.Lines, Line{Kind: KindComment, Raw: raw}) + continue + } + + k, v, ok := splitEnvKV(raw) + if !ok { + // Preserve unknown rows as comments so rendering remains stable. + out.Lines = append(out.Lines, Line{Kind: KindComment, Raw: raw}) + continue + } + out.Values[k] = v + out.Lines = append(out.Lines, Line{Kind: KindKV, Raw: raw, Key: k, Value: v}) + } + if err := scanner.Err(); err != nil { + return nil, err + } + + return out, nil +} + +func NewEmptyEnvFile() *EnvFile { + return &EnvFile{ + Lines: []Line{}, + Values: map[string]string{}, + } +} + +func Render(base *EnvFile, values map[string]string) string { + if base == nil { + base = NewEmptyEnvFile() + } + + seen := make(map[string]struct{}, len(values)) + var b strings.Builder + + for _, line := range base.Lines { + switch line.Kind { + case KindBlank, KindComment: + b.WriteString(line.Raw) + case KindKV: + v, ok := values[line.Key] + if !ok { + v = line.Value + } + b.WriteString(line.Key + "=" + v) + seen[line.Key] = struct{}{} + } + b.WriteString("\n") + } + + extra := make([]string, 0, len(values)) + for k := range values { + if _, ok := seen[k]; !ok { + extra = append(extra, k) + } + } + sort.Strings(extra) + if len(extra) > 0 { + b.WriteString("\n# Added by Sirius installer\n") + for _, k := range extra { + b.WriteString(k + "=" + values[k] + "\n") + } + } + + return b.String() +} + +func splitEnvKV(raw string) (string, string, bool) { + idx := strings.IndexRune(raw, '=') + if idx <= 0 { + return "", "", false + } + key := strings.TrimSpace(raw[:idx]) + if key == "" { + return "", "", false + } + val := strings.TrimSpace(raw[idx+1:]) + return key, val, true +} diff --git a/installer/internal/config/generate.go b/installer/internal/config/generate.go new file mode 100644 index 0000000..cad16ef --- /dev/null +++ b/installer/internal/config/generate.go @@ -0,0 +1,192 @@ +package config + +import ( + "crypto/rand" + "encoding/base64" + "encoding/hex" + "fmt" + "net/url" + "strings" +) + +type Options struct { + Force bool + NonInteractive bool + AdminPassword string + NextAuthURL string + SiriusAPIURL string + NextPublicAPIURL string + CORSAllowedOrigin string +} + +// templateAuthoritativeKeys are keys whose template definition always wins, +// even when the user's existing .env has a non-empty value. This exists so +// that intentional template changes (e.g. clearing IMAGE_TAG so compose can +// resolve the default `latest` tag) propagate to upgraders. Without this, +// stale values written by older template versions become permanently sticky +// because Merge otherwise prefers any non-empty existing value. +// +// Only add a key here when the template is the source of truth for it AND +// shipping a stale legacy value would break upgrades. IMAGE_TAG is the +// canonical case: v1.0.0's template hard-coded IMAGE_TAG=v1.0.0, which +// pinned every upgrader to that release until manually edited. +var templateAuthoritativeKeys = map[string]struct{}{ + "IMAGE_TAG": {}, +} + +func Merge(templateVals, existingVals map[string]string, opts Options) map[string]string { + out := make(map[string]string, len(templateVals)+len(existingVals)+8) + for k, v := range templateVals { + out[k] = v + } + for k, v := range existingVals { + if _, authoritative := templateAuthoritativeKeys[k]; authoritative { + if _, definedInTemplate := templateVals[k]; definedInTemplate { + continue + } + } + if strings.TrimSpace(v) != "" { + out[k] = v + } + } + + applyOpt(out, "INITIAL_ADMIN_PASSWORD", opts.AdminPassword) + applyOpt(out, "NEXTAUTH_URL", opts.NextAuthURL) + applyOpt(out, "SIRIUS_API_URL", opts.SiriusAPIURL) + applyOpt(out, "NEXT_PUBLIC_SIRIUS_API_URL", opts.NextPublicAPIURL) + applyOpt(out, "CORS_ALLOWED_ORIGINS", opts.CORSAllowedOrigin) + + return out +} + +func EnsureRequired(values map[string]string, opts Options) (map[string]string, map[string]string, error) { + generated := map[string]string{} + + if shouldGenerate(values["POSTGRES_PASSWORD"], opts.Force) { + s, err := randomHex(16) + if err != nil { + return nil, nil, err + } + values["POSTGRES_PASSWORD"] = s + generated["POSTGRES_PASSWORD"] = s + } + + if shouldGenerate(values["NEXTAUTH_SECRET"], opts.Force) { + s, err := randomHex(32) + if err != nil { + return nil, nil, err + } + values["NEXTAUTH_SECRET"] = s + generated["NEXTAUTH_SECRET"] = s + } + + if shouldGenerate(values["INITIAL_ADMIN_PASSWORD"], opts.Force) { + if strings.TrimSpace(opts.AdminPassword) != "" { + values["INITIAL_ADMIN_PASSWORD"] = opts.AdminPassword + } else { + s, err := randomBase64(12) + if err != nil { + return nil, nil, err + } + values["INITIAL_ADMIN_PASSWORD"] = s + generated["INITIAL_ADMIN_PASSWORD"] = s + } + } + + if strings.TrimSpace(values["INITIAL_ADMIN_PASSWORD"]) == "" { + return nil, nil, fmt.Errorf("INITIAL_ADMIN_PASSWORD is required") + } + + // Rebuild DATABASE_URL when it is missing/placeholder or when the + // password was just generated (so the URL always matches the password). + dbURL := strings.TrimSpace(values["DATABASE_URL"]) + _, pwRegenerated := generated["POSTGRES_PASSWORD"] + if dbURL == "" || pwRegenerated { + values["DATABASE_URL"] = BuildDatabaseURL(values) + } + + // Default in-container path for Docker Compose secret mount (see docker-compose.yaml). + if strings.TrimSpace(values["SIRIUS_API_KEY_FILE"]) == "" { + values["SIRIUS_API_KEY_FILE"] = "/run/secrets/sirius_api_key" + } + + return values, generated, nil +} + +// BuildDatabaseURL assembles a PostgreSQL connection URL from individual +// POSTGRES_* values. It uses net/url to properly encode the userinfo so +// passwords containing @, :, /, spaces, etc. are safe. +func BuildDatabaseURL(values map[string]string) string { + user := valueOr(values, "POSTGRES_USER", "postgres") + pass := values["POSTGRES_PASSWORD"] + host := valueOr(values, "POSTGRES_HOST", "sirius-postgres") + port := valueOr(values, "POSTGRES_PORT", "5432") + db := valueOr(values, "POSTGRES_DB", "sirius") + + u := &url.URL{ + Scheme: "postgresql", + User: url.UserPassword(user, pass), + Host: fmt.Sprintf("%s:%s", host, port), + Path: "/" + db, + } + return u.String() +} + +func valueOr(m map[string]string, key, fallback string) string { + if v := strings.TrimSpace(m[key]); v != "" { + return v + } + return fallback +} + +func IsPlaceholder(v string) bool { + s := strings.ToLower(strings.TrimSpace(v)) + if s == "" { + return true + } + + placeholders := []string{ + "password", + "postgres", + "change-me", + "change_this", + "dummy", + "placeholder", + "your_", + "your-", + "test-secret", + "ci-placeholder-api-key", + } + for _, p := range placeholders { + if strings.Contains(s, p) { + return true + } + } + return false +} + +func shouldGenerate(v string, force bool) bool { + return force || IsPlaceholder(v) +} + +func applyOpt(values map[string]string, key, val string) { + if strings.TrimSpace(val) != "" { + values[key] = val + } +} + +func randomHex(numBytes int) (string, error) { + buf := make([]byte, numBytes) + if _, err := rand.Read(buf); err != nil { + return "", fmt.Errorf("failed to read random bytes: %w", err) + } + return hex.EncodeToString(buf), nil +} + +func randomBase64(numBytes int) (string, error) { + buf := make([]byte, numBytes) + if _, err := rand.Read(buf); err != nil { + return "", fmt.Errorf("failed to read random bytes: %w", err) + } + return base64.RawStdEncoding.EncodeToString(buf), nil +} diff --git a/installer/internal/config/generate_test.go b/installer/internal/config/generate_test.go new file mode 100644 index 0000000..dde3919 --- /dev/null +++ b/installer/internal/config/generate_test.go @@ -0,0 +1,184 @@ +package config + +import ( + "testing" +) + +func TestBuildDatabaseURL(t *testing.T) { + tests := []struct { + name string + values map[string]string + want string + }{ + { + name: "simple password", + values: map[string]string{ + "POSTGRES_USER": "postgres", + "POSTGRES_PASSWORD": "secret", + "POSTGRES_HOST": "db-host", + "POSTGRES_PORT": "5432", + "POSTGRES_DB": "mydb", + }, + want: "postgresql://postgres:secret@db-host:5432/mydb", + }, + { + name: "defaults when keys missing", + values: map[string]string{ + "POSTGRES_PASSWORD": "pw", + }, + want: "postgresql://postgres:pw@sirius-postgres:5432/sirius", + }, + { + name: "password with @", + values: map[string]string{ + "POSTGRES_PASSWORD": "p@ss", + }, + want: "postgresql://postgres:p%40ss@sirius-postgres:5432/sirius", + }, + { + name: "password with colon", + values: map[string]string{ + "POSTGRES_PASSWORD": "p:ss", + }, + want: "postgresql://postgres:p%3Ass@sirius-postgres:5432/sirius", + }, + { + name: "password with slash", + values: map[string]string{ + "POSTGRES_PASSWORD": "p/ss", + }, + want: "postgresql://postgres:p%2Fss@sirius-postgres:5432/sirius", + }, + { + name: "password with spaces", + values: map[string]string{ + "POSTGRES_PASSWORD": "my pass word", + }, + want: "postgresql://postgres:my%20pass%20word@sirius-postgres:5432/sirius", + }, + { + name: "complex special characters", + values: map[string]string{ + "POSTGRES_PASSWORD": "p@ss:w/rd#123!", + }, + want: "postgresql://postgres:p%40ss%3Aw%2Frd%23123%21@sirius-postgres:5432/sirius", + }, + { + name: "custom host and port", + values: map[string]string{ + "POSTGRES_USER": "admin", + "POSTGRES_PASSWORD": "secret", + "POSTGRES_HOST": "10.0.0.5", + "POSTGRES_PORT": "5433", + "POSTGRES_DB": "sirius_prod", + }, + want: "postgresql://admin:secret@10.0.0.5:5433/sirius_prod", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := BuildDatabaseURL(tt.values) + if got != tt.want { + t.Errorf("BuildDatabaseURL() = %q, want %q", got, tt.want) + } + }) + } +} + +func TestEnsureRequired_SetsDatabaseURL(t *testing.T) { + values := map[string]string{ + "POSTGRES_PASSWORD": "abcdef1234567890abcdef1234567890", + "NEXTAUTH_SECRET": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd", + "INITIAL_ADMIN_PASSWORD": "SomeStr0ng!Pass", + "POSTGRES_USER": "postgres", + "POSTGRES_HOST": "sirius-postgres", + "POSTGRES_PORT": "5432", + "POSTGRES_DB": "sirius", + } + + result, _, err := EnsureRequired(values, Options{}) + if err != nil { + t.Fatalf("EnsureRequired() error = %v", err) + } + + expected := "postgresql://postgres:abcdef1234567890abcdef1234567890@sirius-postgres:5432/sirius" + if result["DATABASE_URL"] != expected { + t.Errorf("DATABASE_URL = %q, want %q", result["DATABASE_URL"], expected) + } +} + +func TestEnsureRequired_PreservesManualDatabaseURL(t *testing.T) { + manual := "postgresql://custom:pass@remote:5432/otherdb" + values := map[string]string{ + "POSTGRES_PASSWORD": "abcdef1234567890abcdef1234567890", + "NEXTAUTH_SECRET": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd", + "INITIAL_ADMIN_PASSWORD": "SomeStr0ng!Pass", + "DATABASE_URL": manual, + } + + result, _, err := EnsureRequired(values, Options{}) + if err != nil { + t.Fatalf("EnsureRequired() error = %v", err) + } + + if result["DATABASE_URL"] != manual { + t.Errorf("DATABASE_URL = %q, want %q (should be preserved)", result["DATABASE_URL"], manual) + } +} + +func TestMerge_ClearsLegacyImageTagFromExistingEnv(t *testing.T) { + // Regression: v1.0.0's template hard-coded IMAGE_TAG=v1.0.0. The current + // template ships IMAGE_TAG= (empty) so docker-compose.yaml's `:-latest` + // fallback wins. Without IMAGE_TAG being template-authoritative the old + // value stays sticky and pins upgraders to v1.0.0 forever. + template := map[string]string{ + "IMAGE_TAG": "", + "POSTGRES_PASSWORD": "change-me-strong-db-password", + } + existing := map[string]string{ + "IMAGE_TAG": "v1.0.0", + "POSTGRES_PASSWORD": "user-set-password", + } + + out := Merge(template, existing, Options{}) + if got := out["IMAGE_TAG"]; got != "" { + t.Errorf("IMAGE_TAG = %q, want empty (template-authoritative)", got) + } + if got := out["POSTGRES_PASSWORD"]; got != "user-set-password" { + t.Errorf("POSTGRES_PASSWORD = %q, want user-set value preserved", got) + } +} + +func TestMerge_PreservesImageTagWhenTemplateOmits(t *testing.T) { + // If a future template drops IMAGE_TAG entirely, an explicit pin in the + // user's .env should still survive (no template intent to clear). + template := map[string]string{ + "POSTGRES_PASSWORD": "change-me", + } + existing := map[string]string{ + "IMAGE_TAG": "v1.2.3", + } + + out := Merge(template, existing, Options{}) + if got := out["IMAGE_TAG"]; got != "v1.2.3" { + t.Errorf("IMAGE_TAG = %q, want v1.2.3 preserved", got) + } +} + +func TestEnsureRequired_SetsInternalAPIKeyFileDefault(t *testing.T) { + values := map[string]string{ + "POSTGRES_PASSWORD": "abcdef1234567890abcdef1234567890", + "NEXTAUTH_SECRET": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd", + "INITIAL_ADMIN_PASSWORD": "SomeStr0ng!Pass", + } + + result, _, err := EnsureRequired(values, Options{}) + if err != nil { + t.Fatalf("EnsureRequired() error = %v", err) + } + + if result["SIRIUS_API_KEY_FILE"] != "/run/secrets/sirius_api_key" { + t.Fatalf("SIRIUS_API_KEY_FILE = %q", result["SIRIUS_API_KEY_FILE"]) + } +} diff --git a/installer/internal/prompt/prompt.go b/installer/internal/prompt/prompt.go new file mode 100644 index 0000000..55c2497 --- /dev/null +++ b/installer/internal/prompt/prompt.go @@ -0,0 +1,34 @@ +package prompt + +import ( + "bufio" + "fmt" + "os" + "strings" +) + +func Ask(reader *bufio.Reader, message, fallback string) (string, error) { + if _, err := fmt.Fprintf(os.Stdout, "%s [%s]: ", message, fallback); err != nil { + return "", err + } + raw, err := reader.ReadString('\n') + if err != nil { + return "", err + } + val := strings.TrimSpace(raw) + if val == "" { + return fallback, nil + } + return val, nil +} + +func AskOptional(reader *bufio.Reader, message string) (string, error) { + if _, err := fmt.Fprintf(os.Stdout, "%s (leave blank to auto-generate): ", message); err != nil { + return "", err + } + raw, err := reader.ReadString('\n') + if err != nil { + return "", err + } + return strings.TrimSpace(raw), nil +} diff --git a/rabbitmq/rabbitmq.conf b/rabbitmq/rabbitmq.conf new file mode 100644 index 0000000..9da4a06 --- /dev/null +++ b/rabbitmq/rabbitmq.conf @@ -0,0 +1,8 @@ +listeners.tcp.default = 5672 +default_vhost = / +default_user = guest +default_pass = guest +default_permissions.configure = .* +default_permissions.read = .* +default_permissions.write = .* +loopback_users = none \ No newline at end of file diff --git a/scripts/agent-identities/README.md b/scripts/agent-identities/README.md new file mode 100644 index 0000000..74e54a9 --- /dev/null +++ b/scripts/agent-identities/README.md @@ -0,0 +1,385 @@ +# Agent Identity Generation System + +A TypeScript-based system for generating comprehensive agent identity files from documentation and code. + +## Overview + +This system combines **manual templates** (role summaries, best practices) with **auto-generated sections** (file structure, ports, dependencies, configs) to create comprehensive agent identities (~1200-1500 lines). + +## Quick Start + +```bash +# Install dependencies +npm install + +# Generate all agent identities +npm run generate -- --all + +# Generate specific agent +npm run generate -- --product=agent-engineer + +# Validate agent identities +npm run validate + +# Check for stale identities +npm run check-sync +``` + +## Commands + +### Generation + +```bash +# Generate all agent identities +npm run generate -- --all + +# Generate specific product +npm run generate -- --product= + +# Example +npm run generate -- --product=agent-engineer +``` + +### Validation + +```bash +# Full validation (YAML, content, sync, file paths) +npm run validate + +# Check if identities need regeneration +npm run check-sync +``` + +### Via Makefile + +```bash +cd testing/container-testing + +# Generation +make regenerate-agents # All +make regenerate-agent PRODUCT=agent-engineer # Specific + +# Validation +make lint-agents # Full +make check-agent-sync # Sync check +``` + +## Project Structure + +``` +scripts/agent-identities/ +├── package.json # Project config +├── tsconfig.json # TypeScript config +├── src/ +│ ├── generators/ # Data extractors +│ │ ├── index.ts # Main orchestrator +│ │ ├── file-structure.ts +│ │ ├── ports.ts +│ │ ├── dependencies.ts +│ │ ├── config-examples.ts +│ │ ├── documentation.ts +│ │ └── merge.ts +│ ├── validators/ # Validation modules +│ │ ├── yaml-validator.ts +│ │ ├── content-validator.ts +│ │ ├── sync-validator.ts +│ │ └── file-path-validator.ts +│ ├── types/ # Type definitions +│ └── utils/ # Utilities +├── lint-agents.ts # Validation CLI +├── generate-agents.ts # Generation CLI +└── check-sync.ts # Sync check CLI +``` + +## Creating a New Agent Identity + +### 1. Create Template + +Create `.cursor/agents/templates/.template.md`: + +```markdown +--- +# YAML front matter (manually maintained) +name: "My Agent" +title: "My Agent (product/Tech)" +# ... metadata +--- + +# My Agent + + +Manual narrative content + + +## Key Documentation + + + + +## Project Location + + + + +## Technology Stack + + + +``` + +### 2. Create Config + +Create `.cursor/agents/config/.config.yaml`: + +```yaml +product: my-product +product_path: /path/to/product +docker_service_name: my-service + +metadata: + name: "My Agent" + title: "My Agent (product/Tech)" + description: "Brief description" + role_type: engineering + version: "1.0.0" + last_updated: "2025-10-25" + author: "Sirius Team" + specialization: ["skill1", "skill2"] + technology_stack: ["Tech1", "Tech2"] + system_integration_level: high + categories: ["category"] + tags: ["tag1", "tag2"] + related_docs: ["doc1.md", "doc2.md"] + dependencies: ["path/"] + llm_context: high + context_window_target: 1400 + +generation: + include_file_structure: true + file_structure_depth: 3 + file_structure_ignore: [node_modules, dist, bin] + + include_ports: true + ports_config: + "8080": "HTTP server" + + include_dependencies: true + dependencies_source: go.mod # or package.json + dependencies_grouping: + "Category": + - "package-name" + + include_config_examples: true + config_files: + - path: config/server.yaml + title: "Server Configuration" + + extract_code_patterns_from_docs: + - documentation/dev/file.md + +template_path: .cursor/agents/templates/.template.md +output_path: .cursor/agents/.agent.md +``` + +### 3. Generate + +```bash +npm run generate -- --product= +``` + +### 4. Validate + +```bash +npm run validate +``` + +## Template Markers + +### AUTO-GENERATED Sections + +Sections between these markers are auto-generated: + +```markdown + +Content is replaced on each generation + +``` + +### MANUAL Sections + +Sections between these markers are preserved: + +```markdown + +Content is preserved across generations + +``` + +## Available Generators + +### file-structure +Extracts directory tree from product path with max depth and ignore patterns. + +### ports +Extracts port mappings from docker-compose.yaml for specified service. + +### dependencies +Extracts and groups dependencies from go.mod or package.json. + +### config-examples +Extracts and formats configuration file contents. + +### documentation-links +Generates documentation links from related_docs list. + +### code-patterns +Extracts code patterns, best practices, and common tasks from documentation. + +## Validation + +### YAML Front Matter +- Required fields present +- Enum values valid (role_type, llm_context, etc.) +- Version format (semver: 1.0.0) +- Date format (YYYY-MM-DD) + +### Content +- Line count in range (150-2000) +- Warning if outside target (800-1500) +- Required sections present + +### Sync Status +- Compares source file modification times +- Detects when regeneration needed +- Tracks source files via metadata + +### File Paths +- Extracts file references from content +- Verifies files exist +- Reports missing files + +## Generation Metadata + +Generated files include metadata: + +```yaml +--- +# ... standard metadata ... +_generated_at: "2025-10-25T10:30:00.000Z" +_source_files: + - "/path/to/source1" + - "/path/to/source2" +--- +``` + +This enables: +- Staleness detection +- Source tracking +- Regeneration decisions + +## Development + +### Run Tests + +```bash +npm test # (when tests are added) +``` + +### Build + +```bash +npm run build +``` + +### Type Check + +```bash +npx tsc --noEmit +``` + +## Troubleshooting + +### "Cannot find module" + +Ensure dependencies are installed: +```bash +npm install +``` + +### "Config file not found" + +Check config path in command: +```bash +npm run generate -- --product= +``` + +Config must exist at `.cursor/agents/config/.config.yaml` + +### "Template not found" + +Check template_path in config file points to valid template. + +### Generation Fails + +Check: +1. Product path exists and is accessible +2. Source files (go.mod, docker-compose.yaml) exist +3. Config YAML is valid +4. Template has proper markers + +### Validation Fails + +Check: +1. YAML front matter has all required fields +2. Field values match enum options +3. Version and date formats correct +4. File is within line count limits + +## Integration with Workflow + +### Pre-Commit Hook + +Agent identities are validated on commit when source files change. + +### CI/CD + +Use in CI/CD pipelines: + +```bash +cd scripts/agent-identities +npm run validate || exit 1 +``` + +### Makefile + +Integrated with project Makefile: + +```bash +make regenerate-agents # Generate all +make regenerate-agent PRODUCT=name # Generate specific +make check-agent-sync # Check staleness +make lint-agents # Validate all +``` + +## Best Practices + +1. **Manual Sections:** Use for narrative, philosophy, best practices +2. **Auto-Generated Sections:** Use for structural info (files, ports, deps) +3. **Regular Regeneration:** Regenerate after major changes +4. **Validate Before Commit:** Run validation before committing +5. **Keep Templates Clean:** Don't add manual content in auto-generated sections + +## Resources + +- **Plan:** `/agent-identity-system.plan.md` +- **Implementation Summary:** `/AGENT-IDENTITY-GENERATION-IMPLEMENTED.md` +- **Templates:** `.cursor/agents/templates/` +- **Configs:** `.cursor/agents/config/` +- **Generated Identities:** `.cursor/agents/*.agent.md` + +--- + +**Version:** 1.0.0 +**Last Updated:** 2025-10-25 + + diff --git a/scripts/agent-identities/lint-agent-index.sh b/scripts/agent-identities/lint-agent-index.sh new file mode 100755 index 0000000..bf7fba6 --- /dev/null +++ b/scripts/agent-identities/lint-agent-index.sh @@ -0,0 +1,248 @@ +#!/bin/bash + +# Sirius Agent Identity Index Linting +# Validates agent index completeness and consistency + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Configuration +AGENTS_DIR="../../.cursor/agents" +INDEX_FILE="$AGENTS_DIR/docs/INDEX.agent-identities.md" +SCRIPT_DIR="$(dirname "$0")" +LOG_FILE="tmp/index-lint-$(date +%Y%m%d-%H%M%S).log" + +# Create tmp directory if it doesn't exist +mkdir -p tmp + +# Counters +ERRORS=0 +WARNINGS=0 + +# Functions +log() { + echo -e "${BLUE}[$(date +'%H:%M:%S')]${NC} $1" | tee -a "$LOG_FILE" +} + +success() { + echo -e "${GREEN}✅ $1${NC}" | tee -a "$LOG_FILE" +} + +warning() { + echo -e "${YELLOW}⚠️ $1${NC}" | tee -a "$LOG_FILE" + ((WARNINGS++)) +} + +error() { + echo -e "${RED}❌ $1${NC}" | tee -a "$LOG_FILE" + ((ERRORS++)) +} + +# Check if index file exists +check_index_exists() { + if [ ! -f "$INDEX_FILE" ]; then + error "Index file not found: $INDEX_FILE" + return 1 + fi + return 0 +} + +# Get all agent files +get_agent_files() { + find "$AGENTS_DIR" -name "*.agent.md" -type f | sort +} + +# Extract agents mentioned in index +get_indexed_agents() { + if [ ! -f "$INDEX_FILE" ]; then + return 1 + fi + + # Look for markdown links to .agent.md files + grep -oE '\[.*\]\([^)]*\.agent\.md\)' "$INDEX_FILE" | \ + grep -oE '[^/]+\.agent\.md' | \ + sort -u +} + +# Check for orphaned agent files +check_orphaned_files() { + log "Checking for orphaned agent files..." + + local orphaned=0 + + while IFS= read -r agent_file; do + local basename=$(basename "$agent_file") + + # Skip template and system files + if [[ "$basename" == "TEMPLATE."* ]] || \ + [[ "$basename" == "ABOUT."* ]] || \ + [[ "$basename" == "INDEX."* ]] || \ + [[ "$basename" == "GUIDE."* ]] || \ + [[ "$basename" == "REFERENCE."* ]] || \ + [[ "$basename" == "SPECIFICATION."* ]]; then + continue + fi + + # Check if mentioned in index + if ! grep -q "$basename" "$INDEX_FILE" 2>/dev/null; then + error "Agent file not in index: $basename" + ((orphaned++)) + fi + done < <(get_agent_files) + + if [ $orphaned -eq 0 ]; then + success "No orphaned agent files found" + return 0 + else + error "Found $orphaned orphaned agent file(s)" + return 1 + fi +} + +# Check for broken index references +check_broken_references() { + log "Checking for broken index references..." + + local broken=0 + + while IFS= read -r indexed_agent; do + local full_path="$AGENTS_DIR/$indexed_agent" + + if [ ! -f "$full_path" ]; then + error "Index references non-existent file: $indexed_agent" + ((broken++)) + fi + done < <(get_indexed_agents) + + if [ $broken -eq 0 ]; then + success "No broken index references found" + return 0 + else + error "Found $broken broken reference(s)" + return 1 + fi +} + +# Check index has required sections +check_index_structure() { + log "Checking index structure..." + + local structure_errors=0 + + if ! grep -q "^# Agent Identity Index" "$INDEX_FILE" 2>/dev/null; then + error "Index missing main heading" + ((structure_errors++)) + fi + + if ! grep -q "## By Role Type" "$INDEX_FILE" 2>/dev/null; then + warning "Index missing 'By Role Type' section" + fi + + if ! grep -q "## Complete List" "$INDEX_FILE" 2>/dev/null; then + warning "Index missing 'Complete List' section" + fi + + if [ $structure_errors -eq 0 ]; then + success "Index structure is valid" + return 0 + else + return 1 + fi +} + +# Verify metadata consistency +check_metadata_consistency() { + log "Checking metadata consistency..." + + local inconsistencies=0 + + while IFS= read -r agent_file; do + local basename=$(basename "$agent_file") + + # Skip system files + if [[ "$basename" == "TEMPLATE."* ]] || \ + [[ "$basename" == "ABOUT."* ]] || \ + [[ "$basename" == "INDEX."* ]] || \ + [[ "$basename" == "GUIDE."* ]] || \ + [[ "$basename" == "REFERENCE."* ]] || \ + [[ "$basename" == "SPECIFICATION."* ]]; then + continue + fi + + # Extract name from YAML + local yaml_name=$(sed -n '/^---$/,/^---$/p' "$agent_file" | grep "^name:" | sed 's/name: *"\?\([^"]*\)"\?/\1/' | tr -d '"') + + if [ -n "$yaml_name" ]; then + # Check if name appears in index + if ! grep -q "$yaml_name" "$INDEX_FILE" 2>/dev/null; then + warning "Agent name '$yaml_name' from $basename not found in index" + ((inconsistencies++)) + fi + fi + done < <(get_agent_files) + + if [ $inconsistencies -eq 0 ]; then + success "Metadata consistency check passed" + return 0 + else + warning "Found $inconsistencies metadata inconsistenc(y|ies)" + return 0 # Just warnings, not errors + fi +} + +# Count agents by type +count_agents_by_type() { + log "Agent counts by role type:" + + for role_type in "engineering" "design" "product" "operations" "qa" "documentation"; do + local count=$(find "$AGENTS_DIR" -name "*.agent.md" -type f -exec grep -l "^role_type: *\"*${role_type}\"*" {} \; 2>/dev/null | wc -l) + log " $role_type: $count" + done +} + +# Main script +log "Starting agent identity index validation..." +log "Agents directory: $AGENTS_DIR" +log "Index file: $INDEX_FILE" +log "==================================================" + +# Check index exists +if ! check_index_exists; then + error "Cannot continue without index file" + exit 1 +fi + +# Run all checks +check_index_structure +check_orphaned_files +check_broken_references +check_metadata_consistency + +echo "" +count_agents_by_type +echo "" + +# Summary +log "==================================================" +log "Index Validation Summary:" +log " Errors: $ERRORS" +log " Warnings: $WARNINGS" +log "==================================================" + +if [ $ERRORS -eq 0 ]; then + success "Agent identity index validation passed!" + if [ $WARNINGS -gt 0 ]; then + warning "Validation passed with $WARNINGS warning(s)" + fi + exit 0 +else + error "Index validation failed with $ERRORS error(s)" + exit 1 +fi + diff --git a/scripts/agent-identities/lint-agents-quick.sh b/scripts/agent-identities/lint-agents-quick.sh new file mode 100755 index 0000000..59618db --- /dev/null +++ b/scripts/agent-identities/lint-agents-quick.sh @@ -0,0 +1,166 @@ +#!/bin/bash + +# Sirius Agent Identity Quick Linting +# Fast validation for CI/CD - checks only critical items + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Configuration +AGENTS_DIR="../../.cursor/agents" +SCRIPT_DIR="$(dirname "$0")" + +# Required YAML front matter fields +REQUIRED_FIELDS=("name" "title" "description" "role_type" "version" "last_updated" "llm_context" "context_window_target") + +# Length constraints +MIN_LINES=150 +MAX_LINES=500 + +# Counters +TOTAL_FILES=0 +PASSED_FILES=0 +FAILED_FILES=0 + +# Functions +log() { + echo -e "${BLUE}[$(date +'%H:%M:%S')]${NC} $1" +} + +success() { + echo -e "${GREEN}✅ $1${NC}" +} + +error() { + echo -e "${RED}❌ $1${NC}" +} + +# Check if file has YAML front matter +check_yaml_front_matter() { + local file="$1" + + if ! head -n 1 "$file" | grep -q "^---$"; then + error "Missing YAML front matter in $(basename $file)" + return 1 + fi + + return 0 +} + +# Extract YAML front matter +extract_yaml() { + local file="$1" + local yaml_start=0 + local yaml_end=0 + local line_num=0 + + while IFS= read -r line; do + ((line_num++)) + if [ "$line" = "---" ]; then + if [ $yaml_start -eq 0 ]; then + yaml_start=$line_num + else + yaml_end=$line_num + break + fi + fi + done < "$file" + + if [ $yaml_start -gt 0 ] && [ $yaml_end -gt 0 ]; then + sed -n "${yaml_start},${yaml_end}p" "$file" + fi +} + +# Quick check required fields +check_required_fields() { + local file="$1" + local yaml_content + local missing_fields=() + + yaml_content=$(extract_yaml "$file") + if [ -z "$yaml_content" ]; then + error "Could not extract YAML from $(basename $file)" + return 1 + fi + + for field in "${REQUIRED_FIELDS[@]}"; do + if ! echo "$yaml_content" | grep -q "^${field}:"; then + missing_fields+=("$field") + fi + done + + if [ ${#missing_fields[@]} -gt 0 ]; then + error "Missing fields in $(basename $file): ${missing_fields[*]}" + return 1 + fi + + return 0 +} + +# Quick length check +check_length() { + local file="$1" + local line_count=$(wc -l < "$file") + + if [ $line_count -lt $MIN_LINES ] || [ $line_count -gt $MAX_LINES ]; then + error "$(basename $file) length ($line_count) outside valid range ($MIN_LINES-$MAX_LINES)" + return 1 + fi + + return 0 +} + +# Quick validation +quick_validate() { + local file="$1" + local errors=0 + + if ! check_yaml_front_matter "$file"; then + ((errors++)) + fi + + if ! check_required_fields "$file"; then + ((errors++)) + fi + + if ! check_length "$file"; then + ((errors++)) + fi + + return $errors +} + +# Main script +log "Quick agent identity validation..." + +# Find all agent files +for file in "$AGENTS_DIR"/*.agent.md; do + if [ -f "$file" ]; then + ((TOTAL_FILES++)) + if quick_validate "$file"; then + ((PASSED_FILES++)) + else + ((FAILED_FILES++)) + fi + fi +done + +# Summary +echo "" +log "Quick Validation Summary: $PASSED_FILES/$TOTAL_FILES passed" + +if [ $FAILED_FILES -eq 0 ]; then + success "Quick validation passed!" + exit 0 +else + error "Quick validation failed for $FAILED_FILES file(s)" + exit 1 +fi + + diff --git a/scripts/agent-identities/lint-agents.sh b/scripts/agent-identities/lint-agents.sh new file mode 100755 index 0000000..39ecd0f --- /dev/null +++ b/scripts/agent-identities/lint-agents.sh @@ -0,0 +1,379 @@ +#!/bin/bash + +# Sirius Agent Identity Linting System +# Validates agent identity quality, consistency, and compliance + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Configuration +AGENTS_DIR="../../.cursor/agents" +SCRIPT_DIR="$(dirname "$0")" +LOG_FILE="tmp/agent-lint-$(date +%Y%m%d-%H%M%S).log" + +# Create tmp directory if it doesn't exist +mkdir -p tmp + +# Required YAML front matter fields +REQUIRED_FIELDS=("name" "title" "description" "role_type" "version" "last_updated" "llm_context" "context_window_target") +OPTIONAL_FIELDS=("author" "specialization" "technology_stack" "system_integration_level" "categories" "tags" "related_docs" "dependencies") + +# Valid values for specific fields +VALID_ROLE_TYPES=("engineering" "design" "product" "operations" "qa" "documentation") +VALID_LLM_CONTEXTS=("high" "medium" "low") +VALID_INTEGRATION_LEVELS=("none" "low" "medium" "high") + +# Length constraints +MIN_LINES=150 +MAX_LINES=500 +TARGET_MIN=200 +TARGET_MAX=400 + +# Counters +TOTAL_FILES=0 +PASSED_FILES=0 +FAILED_FILES=0 +WARNINGS=0 + +# Functions +log() { + echo -e "${BLUE}[$(date +'%H:%M:%S')]${NC} $1" | tee -a "$LOG_FILE" +} + +success() { + echo -e "${GREEN}✅ $1${NC}" | tee -a "$LOG_FILE" +} + +warning() { + echo -e "${YELLOW}⚠️ $1${NC}" | tee -a "$LOG_FILE" + ((WARNINGS++)) +} + +error() { + echo -e "${RED}❌ $1${NC}" | tee -a "$LOG_FILE" +} + +# Check if file has YAML front matter +check_yaml_front_matter() { + local file="$1" + local has_yaml=false + + if head -n 1 "$file" | grep -q "^---$"; then + has_yaml=true + fi + + if [ "$has_yaml" = false ]; then + error "Missing YAML front matter in $file" + return 1 + fi + + return 0 +} + +# Extract YAML front matter +extract_yaml() { + local file="$1" + local yaml_start=0 + local yaml_end=0 + local line_num=0 + + while IFS= read -r line; do + ((line_num++)) + if [ "$line" = "---" ]; then + if [ $yaml_start -eq 0 ]; then + yaml_start=$line_num + else + yaml_end=$line_num + break + fi + fi + done < "$file" + + if [ $yaml_start -gt 0 ] && [ $yaml_end -gt 0 ]; then + sed -n "${yaml_start},${yaml_end}p" "$file" + fi +} + +# Check required fields +check_required_fields() { + local file="$1" + local yaml_content + local missing_fields=() + + yaml_content=$(extract_yaml "$file") + if [ -z "$yaml_content" ]; then + return 1 + fi + + for field in "${REQUIRED_FIELDS[@]}"; do + if ! echo "$yaml_content" | grep -q "^${field}:"; then + missing_fields+=("$field") + fi + done + + if [ ${#missing_fields[@]} -gt 0 ]; then + error "Missing required fields in $file: ${missing_fields[*]}" + return 1 + fi + + return 0 +} + +# Validate enumerated field values +validate_enum_fields() { + local file="$1" + local yaml_content + local errors=0 + + yaml_content=$(extract_yaml "$file") + if [ -z "$yaml_content" ]; then + return 1 + fi + + # Check role_type + local role_type=$(echo "$yaml_content" | grep "^role_type:" | cut -d: -f2- | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | tr -d '"') + if [ -n "$role_type" ]; then + local valid=false + for valid_type in "${VALID_ROLE_TYPES[@]}"; do + if [ "$role_type" = "$valid_type" ]; then + valid=true + break + fi + done + if [ "$valid" = false ]; then + error "Invalid role_type '$role_type' in $file. Must be one of: ${VALID_ROLE_TYPES[*]}" + ((errors++)) + fi + fi + + # Check llm_context + local llm_context=$(echo "$yaml_content" | grep "^llm_context:" | cut -d: -f2- | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | tr -d '"') + if [ -n "$llm_context" ]; then + local valid=false + for valid_ctx in "${VALID_LLM_CONTEXTS[@]}"; do + if [ "$llm_context" = "$valid_ctx" ]; then + valid=true + break + fi + done + if [ "$valid" = false ]; then + error "Invalid llm_context '$llm_context' in $file. Must be one of: ${VALID_LLM_CONTEXTS[*]}" + ((errors++)) + fi + fi + + # Check system_integration_level (optional) + local integration_level=$(echo "$yaml_content" | grep "^system_integration_level:" | cut -d: -f2- | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | tr -d '"') + if [ -n "$integration_level" ]; then + local valid=false + for valid_level in "${VALID_INTEGRATION_LEVELS[@]}"; do + if [ "$integration_level" = "$valid_level" ]; then + valid=true + break + fi + done + if [ "$valid" = false ]; then + error "Invalid system_integration_level '$integration_level' in $file. Must be one of: ${VALID_INTEGRATION_LEVELS[*]}" + ((errors++)) + fi + fi + + return $errors +} + +# Validate version format (semver) +validate_version() { + local file="$1" + local yaml_content + + yaml_content=$(extract_yaml "$file") + if [ -z "$yaml_content" ]; then + return 1 + fi + + local version=$(echo "$yaml_content" | grep "^version:" | cut -d: -f2- | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | tr -d '"') + if [ -n "$version" ]; then + if ! echo "$version" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then + error "Invalid version format '$version' in $file. Must be semver (e.g., 1.0.0)" + return 1 + fi + fi + + return 0 +} + +# Validate date format (ISO 8601) +validate_date() { + local file="$1" + local yaml_content + + yaml_content=$(extract_yaml "$file") + if [ -z "$yaml_content" ]; then + return 1 + fi + + local date=$(echo "$yaml_content" | grep "^last_updated:" | cut -d: -f2- | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | tr -d '"') + if [ -n "$date" ]; then + if ! echo "$date" | grep -qE '^[0-9]{4}-[0-9]{2}-[0-9]{2}$'; then + error "Invalid date format '$date' in $file. Must be YYYY-MM-DD" + return 1 + fi + fi + + return 0 +} + +# Check length constraints +check_length() { + local file="$1" + local line_count=$(wc -l < "$file") + + if [ $line_count -lt $MIN_LINES ]; then + error "File $file is too short ($line_count lines). Minimum: $MIN_LINES" + return 1 + elif [ $line_count -gt $MAX_LINES ]; then + error "File $file is too long ($line_count lines). Maximum: $MAX_LINES" + return 1 + elif [ $line_count -lt $TARGET_MIN ] || [ $line_count -gt $TARGET_MAX ]; then + warning "File $file length ($line_count lines) outside target range ($TARGET_MIN-$TARGET_MAX)" + fi + + return 0 +} + +# Check context window target +check_context_target() { + local file="$1" + local yaml_content + + yaml_content=$(extract_yaml "$file") + if [ -z "$yaml_content" ]; then + return 1 + fi + + local target=$(echo "$yaml_content" | grep "^context_window_target:" | cut -d: -f2- | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | tr -d '"') + if [ -n "$target" ]; then + # Only check if it's a valid integer + if [[ "$target" =~ ^[0-9]+$ ]]; then + if [ "$target" -lt $MIN_LINES ] || [ "$target" -gt $MAX_LINES ]; then + warning "context_window_target $target in $file outside valid range ($MIN_LINES-$MAX_LINES)" + fi + fi + fi + + return 0 +} + +# Validate file naming +check_filename() { + local file="$1" + local basename=$(basename "$file") + + if ! echo "$basename" | grep -qE '^[a-z0-9-]+\.agent\.md$'; then + error "Invalid filename format: $basename. Must match [a-z0-9-]+.agent.md" + return 1 + fi + + return 0 +} + +# Main validation function +validate_file() { + local file="$1" + local file_errors=0 + + log "Validating $file..." + + # Check filename format + if ! check_filename "$file"; then + ((file_errors++)) + fi + + # Check YAML front matter exists + if ! check_yaml_front_matter "$file"; then + ((file_errors++)) + return 1 # Can't continue without YAML + fi + + # Check required fields + if ! check_required_fields "$file"; then + ((file_errors++)) + fi + + # Validate enum fields + if ! validate_enum_fields "$file"; then + ((file_errors++)) + fi + + # Validate version format + if ! validate_version "$file"; then + ((file_errors++)) + fi + + # Validate date format + if ! validate_date "$file"; then + ((file_errors++)) + fi + + # Check length constraints + if ! check_length "$file"; then + ((file_errors++)) + fi + + # Check context window target + check_context_target "$file" + + if [ $file_errors -eq 0 ]; then + success "$(basename $file) passed validation" + return 0 + else + error "$(basename $file) failed validation with $file_errors error(s)" + return 1 + fi +} + +# Main script +log "Starting agent identity validation..." +log "Agents directory: $AGENTS_DIR" +log "==================================================" + +# Find all agent files +for file in "$AGENTS_DIR"/*.agent.md; do + if [ -f "$file" ]; then + ((TOTAL_FILES++)) + if validate_file "$file"; then + ((PASSED_FILES++)) + else + ((FAILED_FILES++)) + fi + echo "" + fi +done + +# Summary +log "==================================================" +log "Validation Summary:" +log " Total files: $TOTAL_FILES" +log " Passed: $PASSED_FILES" +log " Failed: $FAILED_FILES" +log " Warnings: $WARNINGS" +log "==================================================" + +if [ $FAILED_FILES -eq 0 ]; then + success "All agent identities passed validation!" + if [ $WARNINGS -gt 0 ]; then + warning "Validation passed with $WARNINGS warning(s)" + exit 0 + fi + exit 0 +else + error "Validation failed for $FAILED_FILES agent identit(y|ies)" + exit 1 +fi + diff --git a/scripts/agent-identities/package-lock.json b/scripts/agent-identities/package-lock.json new file mode 100644 index 0000000..4ac9940 --- /dev/null +++ b/scripts/agent-identities/package-lock.json @@ -0,0 +1,1214 @@ +{ + "name": "@sirius/agent-identity-generator", + "version": "1.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "@sirius/agent-identity-generator", + "version": "1.0.0", + "dependencies": { + "chalk": "^5.3.0", + "glob": "^10.3.0", + "gray-matter": "^4.0.3", + "js-yaml": "^4.1.0" + }, + "devDependencies": { + "@types/js-yaml": "^4.0.9", + "@types/node": "^20.0.0", + "tsx": "^4.7.0", + "typescript": "^5.3.0" + } + }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.11.tgz", + "integrity": "sha512-Xt1dOL13m8u0WE8iplx9Ibbm+hFAO0GsU2P34UNoDGvZYkY8ifSiy6Zuc1lYxfG7svWE2fzqCUmFp5HCn51gJg==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.25.11.tgz", + "integrity": "sha512-uoa7dU+Dt3HYsethkJ1k6Z9YdcHjTrSb5NUy66ZfZaSV8hEYGD5ZHbEMXnqLFlbBflLsl89Zke7CAdDJ4JI+Gg==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.25.11.tgz", + "integrity": "sha512-9slpyFBc4FPPz48+f6jyiXOx/Y4v34TUeDDXJpZqAWQn/08lKGeD8aDp9TMn9jDz2CiEuHwfhRmGBvpnd/PWIQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.25.11.tgz", + "integrity": "sha512-Sgiab4xBjPU1QoPEIqS3Xx+R2lezu0LKIEcYe6pftr56PqPygbB7+szVnzoShbx64MUupqoE0KyRlN7gezbl8g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.25.11.tgz", + "integrity": "sha512-VekY0PBCukppoQrycFxUqkCojnTQhdec0vevUL/EDOCnXd9LKWqD/bHwMPzigIJXPhC59Vd1WFIL57SKs2mg4w==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.25.11.tgz", + "integrity": "sha512-+hfp3yfBalNEpTGp9loYgbknjR695HkqtY3d3/JjSRUyPg/xd6q+mQqIb5qdywnDxRZykIHs3axEqU6l1+oWEQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.11.tgz", + "integrity": "sha512-CmKjrnayyTJF2eVuO//uSjl/K3KsMIeYeyN7FyDBjsR3lnSJHaXlVoAK8DZa7lXWChbuOk7NjAc7ygAwrnPBhA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.25.11.tgz", + "integrity": "sha512-Dyq+5oscTJvMaYPvW3x3FLpi2+gSZTCE/1ffdwuM6G1ARang/mb3jvjxs0mw6n3Lsw84ocfo9CrNMqc5lTfGOw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.25.11.tgz", + "integrity": "sha512-TBMv6B4kCfrGJ8cUPo7vd6NECZH/8hPpBHHlYI3qzoYFvWu2AdTvZNuU/7hsbKWqu/COU7NIK12dHAAqBLLXgw==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.25.11.tgz", + "integrity": "sha512-Qr8AzcplUhGvdyUF08A1kHU3Vr2O88xxP0Tm8GcdVOUm25XYcMPp2YqSVHbLuXzYQMf9Bh/iKx7YPqECs6ffLA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.25.11.tgz", + "integrity": "sha512-TmnJg8BMGPehs5JKrCLqyWTVAvielc615jbkOirATQvWWB1NMXY77oLMzsUjRLa0+ngecEmDGqt5jiDC6bfvOw==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.25.11.tgz", + "integrity": "sha512-DIGXL2+gvDaXlaq8xruNXUJdT5tF+SBbJQKbWy/0J7OhU8gOHOzKmGIlfTTl6nHaCOoipxQbuJi7O++ldrxgMw==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.25.11.tgz", + "integrity": "sha512-Osx1nALUJu4pU43o9OyjSCXokFkFbyzjXb6VhGIJZQ5JZi8ylCQ9/LFagolPsHtgw6himDSyb5ETSfmp4rpiKQ==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.25.11.tgz", + "integrity": "sha512-nbLFgsQQEsBa8XSgSTSlrnBSrpoWh7ioFDUmwo158gIm5NNP+17IYmNWzaIzWmgCxq56vfr34xGkOcZ7jX6CPw==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.25.11.tgz", + "integrity": "sha512-HfyAmqZi9uBAbgKYP1yGuI7tSREXwIb438q0nqvlpxAOs3XnZ8RsisRfmVsgV486NdjD7Mw2UrFSw51lzUk1ww==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.25.11.tgz", + "integrity": "sha512-HjLqVgSSYnVXRisyfmzsH6mXqyvj0SA7pG5g+9W7ESgwA70AXYNpfKBqh1KbTxmQVaYxpzA/SvlB9oclGPbApw==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.25.11.tgz", + "integrity": "sha512-HSFAT4+WYjIhrHxKBwGmOOSpphjYkcswF449j6EjsjbinTZbp8PJtjsVK1XFJStdzXdy/jaddAep2FGY+wyFAQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.11.tgz", + "integrity": "sha512-hr9Oxj1Fa4r04dNpWr3P8QKVVsjQhqrMSUzZzf+LZcYjZNqhA3IAfPQdEh1FLVUJSiu6sgAwp3OmwBfbFgG2Xg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.25.11.tgz", + "integrity": "sha512-u7tKA+qbzBydyj0vgpu+5h5AeudxOAGncb8N6C9Kh1N4n7wU1Xw1JDApsRjpShRpXRQlJLb9wY28ELpwdPcZ7A==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.11.tgz", + "integrity": "sha512-Qq6YHhayieor3DxFOoYM1q0q1uMFYb7cSpLD2qzDSvK1NAvqFi8Xgivv0cFC6J+hWVw2teCYltyy9/m/14ryHg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.25.11.tgz", + "integrity": "sha512-CN+7c++kkbrckTOz5hrehxWN7uIhFFlmS/hqziSFVWpAzpWrQoAG4chH+nN3Be+Kzv/uuo7zhX716x3Sn2Jduw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openharmony-arm64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.11.tgz", + "integrity": "sha512-rOREuNIQgaiR+9QuNkbkxubbp8MSO9rONmwP5nKncnWJ9v5jQ4JxFnLu4zDSRPf3x4u+2VN4pM4RdyIzDty/wQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.25.11.tgz", + "integrity": "sha512-nq2xdYaWxyg9DcIyXkZhcYulC6pQ2FuCgem3LI92IwMgIZ69KHeY8T4Y88pcwoLIjbed8n36CyKoYRDygNSGhA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.25.11.tgz", + "integrity": "sha512-3XxECOWJq1qMZ3MN8srCJ/QfoLpL+VaxD/WfNRm1O3B4+AZ/BnLVgFbUV3eiRYDMXetciH16dwPbbHqwe1uU0Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.25.11.tgz", + "integrity": "sha512-3ukss6gb9XZ8TlRyJlgLn17ecsK4NSQTmdIXRASVsiS2sQ6zPPZklNJT5GR5tE/MUarymmy8kCEf5xPCNCqVOA==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.11.tgz", + "integrity": "sha512-D7Hpz6A2L4hzsRpPaCYkQnGOotdUpDzSGRIv9I+1ITdHROSFUWW95ZPZWQmGka1Fg7W3zFJowyn9WGwMJ0+KPA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@isaacs/cliui": { + "version": "8.0.2", + "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-8.0.2.tgz", + "integrity": "sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==", + "license": "ISC", + "dependencies": { + "string-width": "^5.1.2", + "string-width-cjs": "npm:string-width@^4.2.0", + "strip-ansi": "^7.0.1", + "strip-ansi-cjs": "npm:strip-ansi@^6.0.1", + "wrap-ansi": "^8.1.0", + "wrap-ansi-cjs": "npm:wrap-ansi@^7.0.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/@pkgjs/parseargs": { + "version": "0.11.0", + "resolved": "https://registry.npmjs.org/@pkgjs/parseargs/-/parseargs-0.11.0.tgz", + "integrity": "sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==", + "license": "MIT", + "optional": true, + "engines": { + "node": ">=14" + } + }, + "node_modules/@types/js-yaml": { + "version": "4.0.9", + "resolved": "https://registry.npmjs.org/@types/js-yaml/-/js-yaml-4.0.9.tgz", + "integrity": "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/node": { + "version": "20.19.23", + "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.23.tgz", + "integrity": "sha512-yIdlVVVHXpmqRhtyovZAcSy0MiPcYWGkoO4CGe/+jpP0hmNuihm4XhHbADpK++MsiLHP5MVlv+bcgdF99kSiFQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "undici-types": "~6.21.0" + } + }, + "node_modules/ansi-regex": { + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz", + "integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-regex?sponsor=1" + } + }, + "node_modules/ansi-styles": { + "version": "6.2.3", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz", + "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "license": "Python-2.0" + }, + "node_modules/balanced-match": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", + "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==", + "license": "MIT" + }, + "node_modules/brace-expansion": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz", + "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==", + "license": "MIT", + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/chalk": { + "version": "5.6.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-5.6.2.tgz", + "integrity": "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==", + "license": "MIT", + "engines": { + "node": "^12.17.0 || ^14.13 || >=16.0.0" + }, + "funding": { + "url": "https://github.com/chalk/chalk?sponsor=1" + } + }, + "node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "license": "MIT", + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "license": "MIT" + }, + "node_modules/cross-spawn": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "license": "MIT", + "dependencies": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/eastasianwidth": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/eastasianwidth/-/eastasianwidth-0.2.0.tgz", + "integrity": "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==", + "license": "MIT" + }, + "node_modules/emoji-regex": { + "version": "9.2.2", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz", + "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==", + "license": "MIT" + }, + "node_modules/esbuild": { + "version": "0.25.11", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.11.tgz", + "integrity": "sha512-KohQwyzrKTQmhXDW1PjCv3Tyspn9n5GcY2RTDqeORIdIJY8yKIF7sTSopFmn/wpMPW4rdPXI0UE5LJLuq3bx0Q==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.25.11", + "@esbuild/android-arm": "0.25.11", + "@esbuild/android-arm64": "0.25.11", + "@esbuild/android-x64": "0.25.11", + "@esbuild/darwin-arm64": "0.25.11", + "@esbuild/darwin-x64": "0.25.11", + "@esbuild/freebsd-arm64": "0.25.11", + "@esbuild/freebsd-x64": "0.25.11", + "@esbuild/linux-arm": "0.25.11", + "@esbuild/linux-arm64": "0.25.11", + "@esbuild/linux-ia32": "0.25.11", + "@esbuild/linux-loong64": "0.25.11", + "@esbuild/linux-mips64el": "0.25.11", + "@esbuild/linux-ppc64": "0.25.11", + "@esbuild/linux-riscv64": "0.25.11", + "@esbuild/linux-s390x": "0.25.11", + "@esbuild/linux-x64": "0.25.11", + "@esbuild/netbsd-arm64": "0.25.11", + "@esbuild/netbsd-x64": "0.25.11", + "@esbuild/openbsd-arm64": "0.25.11", + "@esbuild/openbsd-x64": "0.25.11", + "@esbuild/openharmony-arm64": "0.25.11", + "@esbuild/sunos-x64": "0.25.11", + "@esbuild/win32-arm64": "0.25.11", + "@esbuild/win32-ia32": "0.25.11", + "@esbuild/win32-x64": "0.25.11" + } + }, + "node_modules/esprima": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", + "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==", + "license": "BSD-2-Clause", + "bin": { + "esparse": "bin/esparse.js", + "esvalidate": "bin/esvalidate.js" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/extend-shallow": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-2.0.1.tgz", + "integrity": "sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug==", + "license": "MIT", + "dependencies": { + "is-extendable": "^0.1.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/foreground-child": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/foreground-child/-/foreground-child-3.3.1.tgz", + "integrity": "sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==", + "license": "ISC", + "dependencies": { + "cross-spawn": "^7.0.6", + "signal-exit": "^4.0.1" + }, + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/fsevents": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", + "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/get-tsconfig": { + "version": "4.13.0", + "resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-4.13.0.tgz", + "integrity": "sha512-1VKTZJCwBrvbd+Wn3AOgQP/2Av+TfTCOlE4AcRJE72W1ksZXbAx8PPBR9RzgTeSPzlPMHrbANMH3LbltH73wxQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "resolve-pkg-maps": "^1.0.0" + }, + "funding": { + "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1" + } + }, + "node_modules/glob": { + "version": "10.4.5", + "resolved": "https://registry.npmjs.org/glob/-/glob-10.4.5.tgz", + "integrity": "sha512-7Bv8RF0k6xjo7d4A/PxYLbUCfb6c+Vpd2/mB2yRDlew7Jb5hEXiCD9ibfO7wpk8i4sevK6DFny9h7EYbM3/sHg==", + "license": "ISC", + "dependencies": { + "foreground-child": "^3.1.0", + "jackspeak": "^3.1.2", + "minimatch": "^9.0.4", + "minipass": "^7.1.2", + "package-json-from-dist": "^1.0.0", + "path-scurry": "^1.11.1" + }, + "bin": { + "glob": "dist/esm/bin.mjs" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/gray-matter": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/gray-matter/-/gray-matter-4.0.3.tgz", + "integrity": "sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q==", + "license": "MIT", + "dependencies": { + "js-yaml": "^3.13.1", + "kind-of": "^6.0.2", + "section-matter": "^1.0.0", + "strip-bom-string": "^1.0.0" + }, + "engines": { + "node": ">=6.0" + } + }, + "node_modules/gray-matter/node_modules/argparse": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "license": "MIT", + "dependencies": { + "sprintf-js": "~1.0.2" + } + }, + "node_modules/gray-matter/node_modules/js-yaml": { + "version": "3.14.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz", + "integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==", + "license": "MIT", + "dependencies": { + "argparse": "^1.0.7", + "esprima": "^4.0.0" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/is-extendable": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/is-extendable/-/is-extendable-0.1.1.tgz", + "integrity": "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/isexe": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "license": "ISC" + }, + "node_modules/jackspeak": { + "version": "3.4.3", + "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-3.4.3.tgz", + "integrity": "sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==", + "license": "BlueOak-1.0.0", + "dependencies": { + "@isaacs/cliui": "^8.0.2" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + }, + "optionalDependencies": { + "@pkgjs/parseargs": "^0.11.0" + } + }, + "node_modules/js-yaml": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", + "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "license": "MIT", + "dependencies": { + "argparse": "^2.0.1" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/kind-of": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz", + "integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/lru-cache": { + "version": "10.4.3", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz", + "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==", + "license": "ISC" + }, + "node_modules/minimatch": { + "version": "9.0.5", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz", + "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==", + "license": "ISC", + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/minipass": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.2.tgz", + "integrity": "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw==", + "license": "ISC", + "engines": { + "node": ">=16 || 14 >=14.17" + } + }, + "node_modules/package-json-from-dist": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz", + "integrity": "sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==", + "license": "BlueOak-1.0.0" + }, + "node_modules/path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/path-scurry": { + "version": "1.11.1", + "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-1.11.1.tgz", + "integrity": "sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==", + "license": "BlueOak-1.0.0", + "dependencies": { + "lru-cache": "^10.2.0", + "minipass": "^5.0.0 || ^6.0.2 || ^7.0.0" + }, + "engines": { + "node": ">=16 || 14 >=14.18" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/resolve-pkg-maps": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz", + "integrity": "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1" + } + }, + "node_modules/section-matter": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/section-matter/-/section-matter-1.0.0.tgz", + "integrity": "sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==", + "license": "MIT", + "dependencies": { + "extend-shallow": "^2.0.1", + "kind-of": "^6.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "license": "MIT", + "dependencies": { + "shebang-regex": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/signal-exit": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz", + "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==", + "license": "ISC", + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/sprintf-js": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", + "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==", + "license": "BSD-3-Clause" + }, + "node_modules/string-width": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-5.1.2.tgz", + "integrity": "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==", + "license": "MIT", + "dependencies": { + "eastasianwidth": "^0.2.0", + "emoji-regex": "^9.2.2", + "strip-ansi": "^7.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/string-width-cjs": { + "name": "string-width", + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "license": "MIT", + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/string-width-cjs/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/string-width-cjs/node_modules/emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", + "license": "MIT" + }, + "node_modules/string-width-cjs/node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/strip-ansi": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.1.2.tgz", + "integrity": "sha512-gmBGslpoQJtgnMAvOVqGZpEz9dyoKTCzy2nfz/n8aIFhN/jCE/rCmcxabB6jOOHV+0WNnylOxaxBQPSvcWklhA==", + "license": "MIT", + "dependencies": { + "ansi-regex": "^6.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/strip-ansi?sponsor=1" + } + }, + "node_modules/strip-ansi-cjs": { + "name": "strip-ansi", + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/strip-ansi-cjs/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/strip-bom-string": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/strip-bom-string/-/strip-bom-string-1.0.0.tgz", + "integrity": "sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/tsx": { + "version": "4.20.6", + "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.20.6.tgz", + "integrity": "sha512-ytQKuwgmrrkDTFP4LjR0ToE2nqgy886GpvRSpU0JAnrdBYppuY5rLkRUYPU1yCryb24SsKBTL/hlDQAEFVwtZg==", + "dev": true, + "license": "MIT", + "dependencies": { + "esbuild": "~0.25.0", + "get-tsconfig": "^4.7.5" + }, + "bin": { + "tsx": "dist/cli.mjs" + }, + "engines": { + "node": ">=18.0.0" + }, + "optionalDependencies": { + "fsevents": "~2.3.3" + } + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/undici-types": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", + "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "license": "ISC", + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "node-which": "bin/node-which" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/wrap-ansi": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-8.1.0.tgz", + "integrity": "sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==", + "license": "MIT", + "dependencies": { + "ansi-styles": "^6.1.0", + "string-width": "^5.0.1", + "strip-ansi": "^7.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/wrap-ansi-cjs": { + "name": "wrap-ansi", + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", + "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", + "license": "MIT", + "dependencies": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/wrap-ansi-cjs/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/wrap-ansi-cjs/node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "license": "MIT", + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/wrap-ansi-cjs/node_modules/emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", + "license": "MIT" + }, + "node_modules/wrap-ansi-cjs/node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "license": "MIT", + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/wrap-ansi-cjs/node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + } + } +} diff --git a/scripts/agent-identities/package.json b/scripts/agent-identities/package.json new file mode 100644 index 0000000..dc87b65 --- /dev/null +++ b/scripts/agent-identities/package.json @@ -0,0 +1,25 @@ +{ + "name": "@sirius/agent-identity-generator", + "version": "1.0.0", + "type": "module", + "scripts": { + "build": "tsc", + "generate": "tsx src/generate-agents.ts", + "validate": "tsx src/lint-agents.ts", + "check-sync": "tsx src/check-sync.ts" + }, + "devDependencies": { + "@types/node": "^20.0.0", + "@types/js-yaml": "^4.0.9", + "typescript": "^5.3.0", + "tsx": "^4.7.0" + }, + "dependencies": { + "js-yaml": "^4.1.0", + "chalk": "^5.3.0", + "glob": "^10.3.0", + "gray-matter": "^4.0.3" + } +} + + diff --git a/scripts/agent-identities/src/check-sync.ts b/scripts/agent-identities/src/check-sync.ts new file mode 100644 index 0000000..2ede55d --- /dev/null +++ b/scripts/agent-identities/src/check-sync.ts @@ -0,0 +1,50 @@ +import { glob } from 'glob'; +import chalk from 'chalk'; +import { checkIfStale } from './validators/sync-validator.js'; + +async function main() { + const agentFiles = await glob('.cursor/agents/*.agent.md', { cwd: '../../' }); + + console.log(chalk.blue('\n🔍 Agent Identity Sync Check\n')); + + let staleCount = 0; + + for (const agentFile of agentFiles) { + const fullPath = `../../${agentFile}`; + const result = await checkIfStale(fullPath); + + if (result.isStale) { + console.log(chalk.yellow(`⚠️ ${agentFile} is stale`)); + console.log(chalk.yellow(` Reason: ${result.reason}`)); + if (result.staleFiles && result.staleFiles.length > 0) { + console.log(chalk.yellow(` Modified files:`)); + result.staleFiles.forEach(file => console.log(chalk.yellow(` - ${file}`))); + } + console.log(); + staleCount++; + } else { + console.log(chalk.green(`✅ ${agentFile} is in sync`)); + } + } + + console.log(chalk.blue(`\n📊 Summary:`)); + console.log(` Total files: ${agentFiles.length}`); + console.log(` In sync: ${agentFiles.length - staleCount}`); + console.log(` Stale: ${staleCount}`); + + if (staleCount > 0) { + console.log(chalk.yellow(`\n⚠️ ${staleCount} agent identit${staleCount === 1 ? 'y' : 'ies'} need regeneration`)); + console.log(chalk.blue(' Run: make regenerate-agents\n')); + process.exit(1); + } else { + console.log(chalk.green('\n✅ All agent identities are in sync!\n')); + process.exit(0); + } +} + +main().catch(error => { + console.error(chalk.red(`\n❌ Fatal error: ${error}\n`)); + process.exit(1); +}); + + diff --git a/scripts/agent-identities/src/generate-agents.ts b/scripts/agent-identities/src/generate-agents.ts new file mode 100644 index 0000000..59602f0 --- /dev/null +++ b/scripts/agent-identities/src/generate-agents.ts @@ -0,0 +1,75 @@ +import { generateAgentIdentity } from "./generators/index.js"; +import { glob } from "glob"; +import chalk from "chalk"; +import { fileURLToPath } from "url"; +import { dirname } from "path"; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +async function main() { + const args = process.argv.slice(2); + + if (args.includes("--help")) { + console.log(` +${chalk.blue("🤖 Agent Identity Generator")} + +Usage: npm run generate [options] + +Options: + --all Generate all agent identities + --product= Generate specific product (e.g., app-agent) + --help Show this help + +Examples: + npm run generate -- --all + npm run generate -- --product=agent-engineer + `); + return; + } + + console.log(chalk.blue("\n🤖 Agent Identity Generation\n")); + + try { + if (args.includes("--all")) { + // Find config files relative to the project root (2 levels up from src/) + const configs = await glob("../../.cursor/agents/config/*.config.yaml"); + + if (configs.length === 0) { + console.log( + chalk.yellow("⚠️ No config files found in .cursor/agents/config/") + ); + return; + } + + console.log(chalk.blue(`Found ${configs.length} config file(s)\n`)); + + for (const config of configs) { + await generateAgentIdentity(config); + } + + console.log( + chalk.green("\n✅ All agent identities generated successfully!\n") + ); + } else { + const product = args + .find((arg) => arg.startsWith("--product=")) + ?.split("=")[1]; + if (!product) { + console.error(chalk.red("❌ Error: Specify --product= or --all")); + console.log(chalk.blue("Run with --help for usage information")); + process.exit(1); + } + + const configPath = `../../.cursor/agents/config/${product}.config.yaml`; + await generateAgentIdentity(configPath); + + console.log(chalk.green("\n✅ Agent identity generated successfully!\n")); + } + } catch (error) { + console.error(chalk.red(`\n❌ Error: ${error}\n`)); + process.exit(1); + } +} + +main(); diff --git a/scripts/agent-identities/src/generators/config-examples.ts b/scripts/agent-identities/src/generators/config-examples.ts new file mode 100644 index 0000000..b0bcdbb --- /dev/null +++ b/scripts/agent-identities/src/generators/config-examples.ts @@ -0,0 +1,31 @@ +import { readFileContent } from '../utils/file-reader.js'; +import { join } from 'path'; +import { codeBlock } from '../utils/markdown-builder.js'; + +export async function extractConfigExamples( + productPath: string, + configFiles: Array<{ path: string; title: string }> +): Promise { + let result = ''; + + for (const configFile of configFiles) { + try { + const fullPath = join(productPath, configFile.path); + const content = await readFileContent(fullPath); + + // Determine language from file extension + const ext = configFile.path.split('.').pop(); + const language = ext === 'yaml' || ext === 'yml' ? 'yaml' : ext === 'json' ? 'json' : ''; + + result += `**${configFile.title}** (\`${configFile.path}\`):\n\n`; + result += codeBlock(content, language); + result += '\n\n'; + } catch (error) { + result += `**${configFile.title}:** Error reading file - ${error}\n\n`; + } + } + + return result.trim(); +} + + diff --git a/scripts/agent-identities/src/generators/dependencies.ts b/scripts/agent-identities/src/generators/dependencies.ts new file mode 100644 index 0000000..1aa9a72 --- /dev/null +++ b/scripts/agent-identities/src/generators/dependencies.ts @@ -0,0 +1,119 @@ +import { readFileContent } from '../utils/file-reader.js'; +import { join } from 'path'; + +export async function extractGoDependencies( + productPath: string, + grouping: Record = {} +): Promise { + try { + const goModPath = join(productPath, 'go.mod'); + const content = await readFileContent(goModPath); + + // Parse go.mod file + const requireRegex = /require\s+\(([^)]+)\)/s; + const match = content.match(requireRegex); + + if (!match) { + return 'No dependencies found in go.mod'; + } + + const requireBlock = match[1]; + const dependencies: Array<{ name: string; version: string }> = []; + + // Parse each dependency line + const lines = requireBlock.split('\n'); + for (const line of lines) { + const trimmed = line.trim(); + if (!trimmed || trimmed.startsWith('//')) continue; + + const parts = trimmed.split(/\s+/); + if (parts.length >= 2) { + dependencies.push({ + name: parts[0], + version: parts[1], + }); + } + } + + // Group dependencies if grouping is provided + if (Object.keys(grouping).length > 0) { + let result = ''; + + for (const [category, patterns] of Object.entries(grouping)) { + result += `**${category}:**\n\n`; + + const categoryDeps = dependencies.filter(dep => + patterns.some(pattern => dep.name.includes(pattern)) + ); + + for (const dep of categoryDeps) { + result += `- \`${dep.name}\`\n`; + } + + result += '\n'; + } + + return result.trim(); + } + + // No grouping - return all dependencies + let result = '**Dependencies:**\n\n'; + for (const dep of dependencies) { + result += `- \`${dep.name}\` (${dep.version})\n`; + } + + return result.trim(); + } catch (error) { + return `Error extracting Go dependencies: ${error}`; + } +} + +export async function extractNodeDependencies( + productPath: string, + grouping: Record = {} +): Promise { + try { + const packageJsonPath = join(productPath, 'package.json'); + const content = await readFileContent(packageJsonPath); + const packageJson = JSON.parse(content); + + const deps = packageJson.dependencies || {}; + + if (Object.keys(deps).length === 0) { + return 'No dependencies found in package.json'; + } + + // Group dependencies if grouping is provided + if (Object.keys(grouping).length > 0) { + let result = ''; + + for (const [category, patterns] of Object.entries(grouping)) { + result += `**${category}:**\n\n`; + + const categoryDeps = Object.entries(deps).filter(([name]) => + patterns.some(pattern => name.includes(pattern)) + ); + + for (const [name, version] of categoryDeps) { + result += `- \`${name}\` (${version})\n`; + } + + result += '\n'; + } + + return result.trim(); + } + + // No grouping - return all dependencies + let result = '**Dependencies:**\n\n'; + for (const [name, version] of Object.entries(deps)) { + result += `- \`${name}\` (${version})\n`; + } + + return result.trim(); + } catch (error) { + return `Error extracting Node dependencies: ${error}`; + } +} + + diff --git a/scripts/agent-identities/src/generators/documentation.ts b/scripts/agent-identities/src/generators/documentation.ts new file mode 100644 index 0000000..d9b3cd4 --- /dev/null +++ b/scripts/agent-identities/src/generators/documentation.ts @@ -0,0 +1,64 @@ +import { readFileContent } from '../utils/file-reader.js'; + +const PATTERN_SECTION_TITLES = [ + 'Code Patterns', + 'Best Practices', + 'Common Patterns', + 'Development Workflow', + 'Common Tasks', + 'Troubleshooting', +]; + +function extractSection(content: string, sectionTitle: string): string | null { + // Try to find the section with various heading levels + const patterns = [ + new RegExp(`## ${sectionTitle}\\s*\\n([\\s\\S]*?)(?=\\n## |\\n# |$)`, 'i'), + new RegExp(`### ${sectionTitle}\\s*\\n([\\s\\S]*?)(?=\\n### |\\n## |\\n# |$)`, 'i'), + ]; + + for (const pattern of patterns) { + const match = content.match(pattern); + if (match && match[1]) { + return match[1].trim(); + } + } + + return null; +} + +export async function extractCodePatterns(docPaths: string[]): Promise { + let result = ''; + + for (const docPath of docPaths) { + try { + const content = await readFileContent(docPath); + + // Try to extract each pattern section + for (const sectionTitle of PATTERN_SECTION_TITLES) { + const section = extractSection(content, sectionTitle); + if (section) { + result += `### ${sectionTitle}\n\n${section}\n\n`; + } + } + } catch (error) { + console.error(`Error reading doc ${docPath}:`, error); + } + } + + return result.trim() || 'No code patterns found in documentation'; +} + +export async function extractDocumentationLinks( + relatedDocs: string[] +): Promise { + let result = ''; + + for (const doc of relatedDocs) { + const docName = doc.replace(/^.*\//, '').replace(/\.md$/, ''); + result += `- [${docName}](mdc:documentation/dev/${doc})\n`; + } + + return result.trim(); +} + + diff --git a/scripts/agent-identities/src/generators/file-structure.ts b/scripts/agent-identities/src/generators/file-structure.ts new file mode 100644 index 0000000..752fe1d --- /dev/null +++ b/scripts/agent-identities/src/generators/file-structure.ts @@ -0,0 +1,142 @@ +import { readdir, stat } from 'fs/promises'; +import { join, relative, basename } from 'path'; +import { FileNode } from '../types/extraction.js'; + +const FILE_COMMENTS: Record = { + 'main.go': 'Main application entry point', + 'server.go': 'Server implementation', + 'agent.go': 'Agent client implementation', + 'types.go': 'Type definitions', + 'config.yaml': 'Configuration file', + 'docker-compose.yaml': 'Docker Compose configuration', + 'package.json': 'Node.js package manifest', + 'go.mod': 'Go module definition', + 'README.md': 'Project documentation', + 'Makefile': 'Build automation', +}; + +const DIRECTORY_COMMENTS: Record = { + 'cmd': 'Main applications', + 'internal': 'Private application code', + 'pkg': 'Public library code', + 'src': 'Source code', + 'proto': 'Protocol buffer definitions', + 'config': 'Configuration files', + 'templates': 'Template files', + 'testing': 'Test files', + 'scripts': 'Utility scripts', + 'docs': 'Documentation', +}; + +async function buildTree( + rootPath: string, + currentDepth: number, + maxDepth: number, + ignorePatterns: string[], + basePath: string = rootPath +): Promise { + if (currentDepth >= maxDepth) { + return []; + } + + try { + const entries = await readdir(rootPath, { withFileTypes: true }); + const nodes: FileNode[] = []; + + for (const entry of entries) { + const fullPath = join(rootPath, entry.name); + + // Skip ignored patterns + if (ignorePatterns.some(pattern => entry.name.includes(pattern))) { + continue; + } + + // Skip hidden files/directories + if (entry.name.startsWith('.') && entry.name !== '.cursor') { + continue; + } + + const node: FileNode = { + name: entry.name, + path: relative(basePath, fullPath), + type: entry.isDirectory() ? 'directory' : 'file', + }; + + // Add comment if available + if (entry.isDirectory()) { + node.comment = DIRECTORY_COMMENTS[entry.name]; + } else { + node.comment = FILE_COMMENTS[entry.name]; + } + + // Recursively build children for directories + if (entry.isDirectory()) { + node.children = await buildTree( + fullPath, + currentDepth + 1, + maxDepth, + ignorePatterns, + basePath + ); + } + + nodes.push(node); + } + + // Sort: directories first, then files, alphabetically + nodes.sort((a, b) => { + if (a.type !== b.type) { + return a.type === 'directory' ? -1 : 1; + } + return a.name.localeCompare(b.name); + }); + + return nodes; + } catch (error) { + console.error(`Error reading directory ${rootPath}:`, error); + return []; + } +} + +function formatTreeNode(node: FileNode, indent: string = '', isLast: boolean = true): string { + const prefix = isLast ? '└── ' : '├── '; + const name = node.type === 'directory' ? `${node.name}/` : node.name; + const comment = node.comment ? ` # ${node.comment}` : ''; + + let result = `${indent}${prefix}${name}${comment}\n`; + + if (node.children && node.children.length > 0) { + const childIndent = indent + (isLast ? ' ' : '│ '); + node.children.forEach((child, index) => { + const isLastChild = index === node.children!.length - 1; + result += formatTreeNode(child, childIndent, isLastChild); + }); + } + + return result; +} + +function formatAsMarkdown(nodes: FileNode[], rootName: string): string { + let result = '```\n'; + result += `${rootName}/\n`; + + nodes.forEach((node, index) => { + const isLast = index === nodes.length - 1; + result += formatTreeNode(node, '', isLast); + }); + + result += '```'; + return result; +} + +export async function extractFileStructure( + rootPath: string, + maxDepth: number = 3, + ignorePatterns: string[] = ['node_modules', 'dist', '.git', 'bin', '__pycache__'] +): Promise { + const tree = await buildTree(rootPath, 0, maxDepth, ignorePatterns); + const rootName = basename(rootPath); + return formatAsMarkdown(tree, rootName); +} + + diff --git a/scripts/agent-identities/src/generators/index.ts b/scripts/agent-identities/src/generators/index.ts new file mode 100644 index 0000000..7e00e09 --- /dev/null +++ b/scripts/agent-identities/src/generators/index.ts @@ -0,0 +1,152 @@ +import { readFile, writeFile } from 'fs/promises'; +import matter from 'gray-matter'; +import { AgentIdentityConfig, GeneratedSection } from '../types/agent-identity.js'; +import { parseYamlFile } from '../utils/yaml-parser.js'; +import { logger } from '../utils/logger.js'; +import { extractFileStructure } from './file-structure.js'; +import { extractPorts } from './ports.js'; +import { extractGoDependencies, extractNodeDependencies } from './dependencies.js'; +import { extractConfigExamples } from './config-examples.js'; +import { extractCodePatterns, extractDocumentationLinks } from './documentation.js'; +import { mergeTemplate } from './merge.js'; +import { join } from 'path'; + +async function loadConfig(configPath: string): Promise { + return await parseYamlFile(configPath); +} + +export async function generateAgentIdentity(configPath: string): Promise { + logger.info(`Loading configuration from ${configPath}`); + + // 1. Load configuration + const config = await loadConfig(configPath); + + // 2. Load template + logger.info(`Loading template from ${config.template_path}`); + const templateContent = await readFile(config.template_path, 'utf8'); + const { data: frontMatter, content: templateBody } = matter(templateContent); + + // 3. Extract data from sources + const generatedSections: GeneratedSection[] = []; + + // 3.1 File structure + if (config.generation.include_file_structure) { + logger.info('Extracting file structure...'); + const fileStructure = await extractFileStructure( + config.product_path, + config.generation.file_structure_depth || 3, + config.generation.file_structure_ignore || [] + ); + generatedSections.push({ + name: 'file-structure', + content: fileStructure, + source_files: [config.product_path], + last_generated: new Date(), + }); + } + + // 3.2 Ports + if (config.generation.include_ports && config.docker_service_name) { + logger.info('Extracting ports...'); + const ports = await extractPorts( + 'docker-compose.yaml', + config.docker_service_name, + config.generation.ports_config || {} + ); + generatedSections.push({ + name: 'ports', + content: ports, + source_files: ['docker-compose.yaml'], + last_generated: new Date(), + }); + } + + // 3.3 Dependencies + if (config.generation.include_dependencies) { + logger.info('Extracting dependencies...'); + const dependencySource = config.generation.dependencies_source || 'go.mod'; + let dependencies: string; + + if (dependencySource === 'go.mod') { + dependencies = await extractGoDependencies( + config.product_path, + config.generation.dependencies_grouping || {} + ); + } else if (dependencySource === 'package.json') { + dependencies = await extractNodeDependencies( + config.product_path, + config.generation.dependencies_grouping || {} + ); + } else { + dependencies = `Unknown dependency source: ${dependencySource}`; + } + + generatedSections.push({ + name: 'dependencies', + content: dependencies, + source_files: [join(config.product_path, dependencySource)], + last_generated: new Date(), + }); + } + + // 3.4 Config examples + if (config.generation.include_config_examples && config.generation.config_files) { + logger.info('Extracting config examples...'); + const configExamples = await extractConfigExamples( + config.product_path, + config.generation.config_files + ); + generatedSections.push({ + name: 'config-examples', + content: configExamples, + source_files: config.generation.config_files.map(cf => join(config.product_path, cf.path)), + last_generated: new Date(), + }); + } + + // 3.5 Code patterns from documentation + if (config.generation.extract_code_patterns_from_docs.length > 0) { + logger.info('Extracting code patterns from documentation...'); + const codePatterns = await extractCodePatterns( + config.generation.extract_code_patterns_from_docs + ); + generatedSections.push({ + name: 'code-patterns', + content: codePatterns, + source_files: config.generation.extract_code_patterns_from_docs, + last_generated: new Date(), + }); + } + + // 3.6 Documentation links + if (config.metadata.related_docs.length > 0) { + logger.info('Generating documentation links...'); + const docLinks = await extractDocumentationLinks(config.metadata.related_docs); + generatedSections.push({ + name: 'documentation-links', + content: docLinks, + source_files: [], + last_generated: new Date(), + }); + } + + // 4. Merge template with generated sections + logger.info('Merging template with generated sections...'); + const finalContent = mergeTemplate(templateBody, generatedSections); + + // 5. Update front matter with generation metadata + const updatedFrontMatter = { + ...config.metadata, + last_updated: new Date().toISOString().split('T')[0], + _generated_at: new Date().toISOString(), + _source_files: generatedSections.flatMap(s => s.source_files), + }; + + // 6. Write output + const output = matter.stringify(finalContent, updatedFrontMatter); + await writeFile(config.output_path, output, 'utf8'); + + logger.success(`Generated ${config.output_path}`); +} + + diff --git a/scripts/agent-identities/src/generators/merge.ts b/scripts/agent-identities/src/generators/merge.ts new file mode 100644 index 0000000..65f3f2c --- /dev/null +++ b/scripts/agent-identities/src/generators/merge.ts @@ -0,0 +1,40 @@ +import { GeneratedSection } from '../types/agent-identity.js'; + +function escapeRegex(str: string): string { + return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); +} + +export function mergeTemplate( + template: string, + generatedSections: GeneratedSection[] +): string { + let result = template; + + // Find all blocks + // Replace content between markers with generated content + // Preserve manual sections + + for (const section of generatedSections) { + const startMarker = ``; + const endMarker = ``; + + const pattern = new RegExp( + `${escapeRegex(startMarker)}[\\s\\S]*?${escapeRegex(endMarker)}`, + 'g' + ); + + const replacement = + `${startMarker}\n` + + `\n` + + `\n\n` + + section.content + + '\n' + + endMarker; + + result = result.replace(pattern, replacement); + } + + return result; +} + + diff --git a/scripts/agent-identities/src/generators/ports.ts b/scripts/agent-identities/src/generators/ports.ts new file mode 100644 index 0000000..1e24b71 --- /dev/null +++ b/scripts/agent-identities/src/generators/ports.ts @@ -0,0 +1,49 @@ +import { parseYamlFile } from '../utils/yaml-parser.js'; + +interface DockerComposeService { + ports?: string[]; + [key: string]: any; +} + +interface DockerCompose { + services: Record; +} + +export async function extractPorts( + dockerComposePath: string, + serviceName: string, + portsConfig: Record = {} +): Promise { + try { + const compose = await parseYamlFile(dockerComposePath) as DockerCompose; + + if (!compose.services || !compose.services[serviceName]) { + return `Service "${serviceName}" not found in docker-compose.yaml`; + } + + const service = compose.services[serviceName]; + + if (!service.ports || service.ports.length === 0) { + return 'No ports configured for this service'; + } + + // Format ports section + let result = '**Server Ports:**\n\n'; + + for (const portMapping of service.ports) { + // Parse port mapping (e.g., "50051:50051" or "8080:80") + const match = portMapping.match(/(\d+):(\d+)/); + if (match) { + const [, hostPort, containerPort] = match; + const description = portsConfig[hostPort] || portsConfig[containerPort] || ''; + result += `- \`${hostPort}\` - ${description || `Maps to container port ${containerPort}`}\n`; + } + } + + return result.trim(); + } catch (error) { + return `Error extracting ports: ${error}`; + } +} + + diff --git a/scripts/agent-identities/src/lint-agents.ts b/scripts/agent-identities/src/lint-agents.ts new file mode 100644 index 0000000..cd6b814 --- /dev/null +++ b/scripts/agent-identities/src/lint-agents.ts @@ -0,0 +1,87 @@ +import { glob } from 'glob'; +import chalk from 'chalk'; +import { validateYaml, validateContent, checkIfStale, validateFilePaths } from './validators/index.js'; + +async function main() { + const agentFiles = await glob('.cursor/agents/*.agent.md', { cwd: '../../' }); + + let errors = 0; + let warnings = 0; + + console.log(chalk.blue('\n🤖 Agent Identity Validation\n')); + + for (const agentFile of agentFiles) { + const fullPath = `../../${agentFile}`; + console.log(chalk.blue(`\nValidating ${agentFile}...`)); + + // YAML validation + const yamlResult = await validateYaml(fullPath); + if (!yamlResult.valid) { + console.log(chalk.red(` ❌ YAML errors:`)); + yamlResult.errors.forEach(err => console.log(chalk.red(` - ${err}`))); + errors++; + } + + // Content validation + const contentResult = await validateContent(fullPath); + if (!contentResult.valid) { + console.log(chalk.red(` ❌ Content errors:`)); + contentResult.errors.forEach(err => console.log(chalk.red(` - ${err}`))); + errors++; + } + if (contentResult.warnings.length > 0) { + console.log(chalk.yellow(` ⚠️ Content warnings:`)); + contentResult.warnings.forEach(warn => console.log(chalk.yellow(` - ${warn}`))); + warnings++; + } + + // Sync validation + const syncResult = await checkIfStale(fullPath); + if (syncResult.isStale) { + console.log(chalk.yellow(` ⚠️ Stale: ${syncResult.reason}`)); + if (syncResult.staleFiles && syncResult.staleFiles.length > 0) { + console.log(chalk.yellow(` Modified files:`)); + syncResult.staleFiles.forEach(file => console.log(chalk.yellow(` - ${file}`))); + } + console.log(chalk.yellow(` Run: make regenerate-agents`)); + warnings++; + } + + // File path validation + const pathResult = await validateFilePaths(fullPath); + if (!pathResult.valid && pathResult.missingFiles.length > 0) { + console.log(chalk.yellow(` ⚠️ Missing files:`)); + pathResult.missingFiles.slice(0, 5).forEach(file => + console.log(chalk.yellow(` - ${file}`)) + ); + if (pathResult.missingFiles.length > 5) { + console.log(chalk.yellow(` ... and ${pathResult.missingFiles.length - 5} more`)); + } + warnings++; + } + + if (yamlResult.valid && contentResult.valid) { + console.log(chalk.green(` ✅ Valid`)); + } + } + + console.log(chalk.blue(`\n📊 Summary:`)); + console.log(` Total files: ${agentFiles.length}`); + console.log(` Errors: ${errors}`); + console.log(` Warnings: ${warnings}`); + + if (errors === 0) { + console.log(chalk.green('\n✅ All validations passed!\n')); + } else { + console.log(chalk.red('\n❌ Validation failed with errors\n')); + } + + process.exit(errors > 0 ? 1 : 0); +} + +main().catch(error => { + console.error(chalk.red(`\n❌ Fatal error: ${error}\n`)); + process.exit(1); +}); + + diff --git a/scripts/agent-identities/src/types/agent-identity.ts b/scripts/agent-identities/src/types/agent-identity.ts new file mode 100644 index 0000000..d21486d --- /dev/null +++ b/scripts/agent-identities/src/types/agent-identity.ts @@ -0,0 +1,49 @@ +export interface AgentIdentityMetadata { + name: string; + title: string; + description: string; + role_type: 'engineering' | 'design' | 'product' | 'operations' | 'qa' | 'documentation'; + version: string; + last_updated: string; + author: string; + specialization: string[]; + technology_stack: string[]; + system_integration_level: 'high' | 'medium' | 'low' | 'none'; + categories: string[]; + tags: string[]; + related_docs: string[]; + dependencies: string[]; + llm_context: 'high' | 'medium' | 'low'; + context_window_target: number; +} + +export interface AgentIdentityConfig { + product: string; + product_path: string; + docker_service_name?: string; + metadata: AgentIdentityMetadata; + generation: { + include_file_structure: boolean; + file_structure_depth?: number; + file_structure_ignore?: string[]; + include_ports: boolean; + ports_config?: Record; + include_dependencies: boolean; + dependencies_source?: string; + dependencies_grouping?: Record; + include_config_examples: boolean; + config_files?: Array<{ path: string; title: string }>; + extract_code_patterns_from_docs: string[]; + }; + template_path: string; + output_path: string; +} + +export interface GeneratedSection { + name: string; + content: string; + source_files: string[]; + last_generated: Date; +} + + diff --git a/scripts/agent-identities/src/types/extraction.ts b/scripts/agent-identities/src/types/extraction.ts new file mode 100644 index 0000000..663d259 --- /dev/null +++ b/scripts/agent-identities/src/types/extraction.ts @@ -0,0 +1,21 @@ +export interface FileNode { + name: string; + path: string; + type: 'file' | 'directory'; + children?: FileNode[]; + comment?: string; +} + +export interface PortMapping { + service: string; + ports: Array<{ host: number; container: number; description: string }>; +} + +export interface DependencyInfo { + name: string; + version?: string; + category?: string; + description?: string; +} + + diff --git a/scripts/agent-identities/src/types/template.ts b/scripts/agent-identities/src/types/template.ts new file mode 100644 index 0000000..36f0153 --- /dev/null +++ b/scripts/agent-identities/src/types/template.ts @@ -0,0 +1,14 @@ +export interface TemplateSection { + name: string; + type: 'manual' | 'generated'; + startMarker?: string; + endMarker?: string; + content: string; +} + +export interface TemplateMetadata { + frontMatter: Record; + sections: TemplateSection[]; +} + + diff --git a/scripts/agent-identities/src/utils/file-reader.ts b/scripts/agent-identities/src/utils/file-reader.ts new file mode 100644 index 0000000..9c6ec6a --- /dev/null +++ b/scripts/agent-identities/src/utils/file-reader.ts @@ -0,0 +1,21 @@ +import { readFile } from 'fs/promises'; +import { resolve } from 'path'; + +export async function readFileContent(filePath: string): Promise { + try { + const absolutePath = resolve(filePath); + return await readFile(absolutePath, 'utf8'); + } catch (error) { + throw new Error(`Failed to read file ${filePath}: ${error}`); + } +} + +export async function readFileIfExists(filePath: string): Promise { + try { + return await readFileContent(filePath); + } catch { + return null; + } +} + + diff --git a/scripts/agent-identities/src/utils/logger.ts b/scripts/agent-identities/src/utils/logger.ts new file mode 100644 index 0000000..4c4b3d3 --- /dev/null +++ b/scripts/agent-identities/src/utils/logger.ts @@ -0,0 +1,11 @@ +import chalk from 'chalk'; + +export const logger = { + info: (message: string) => console.log(chalk.blue(`ℹ️ ${message}`)), + success: (message: string) => console.log(chalk.green(`✅ ${message}`)), + warning: (message: string) => console.log(chalk.yellow(`⚠️ ${message}`)), + error: (message: string) => console.log(chalk.red(`❌ ${message}`)), + debug: (message: string) => console.log(chalk.gray(`🔍 ${message}`)), +}; + + diff --git a/scripts/agent-identities/src/utils/markdown-builder.ts b/scripts/agent-identities/src/utils/markdown-builder.ts new file mode 100644 index 0000000..ff6d289 --- /dev/null +++ b/scripts/agent-identities/src/utils/markdown-builder.ts @@ -0,0 +1,37 @@ +export function codeBlock(content: string, language: string = ''): string { + return `\`\`\`${language}\n${content}\n\`\`\``; +} + +export function heading(text: string, level: number = 1): string { + return `${'#'.repeat(level)} ${text}`; +} + +export function list(items: string[], ordered: boolean = false): string { + return items + .map((item, index) => + ordered ? `${index + 1}. ${item}` : `- ${item}` + ) + .join('\n'); +} + +export function table(headers: string[], rows: string[][]): string { + const headerRow = `| ${headers.join(' | ')} |`; + const separatorRow = `| ${headers.map(() => '---').join(' | ')} |`; + const dataRows = rows.map(row => `| ${row.join(' | ')} |`).join('\n'); + + return `${headerRow}\n${separatorRow}\n${dataRows}`; +} + +export function link(text: string, url: string): string { + return `[${text}](${url})`; +} + +export function bold(text: string): string { + return `**${text}**`; +} + +export function italic(text: string): string { + return `*${text}*`; +} + + diff --git a/scripts/agent-identities/src/utils/yaml-parser.ts b/scripts/agent-identities/src/utils/yaml-parser.ts new file mode 100644 index 0000000..b0de553 --- /dev/null +++ b/scripts/agent-identities/src/utils/yaml-parser.ts @@ -0,0 +1,21 @@ +import yaml from 'js-yaml'; +import { readFileContent } from './file-reader.js'; + +export async function parseYamlFile(filePath: string): Promise { + const content = await readFileContent(filePath); + return yaml.load(content); +} + +export function parseYamlString(content: string): any { + return yaml.load(content); +} + +export function stringifyYaml(data: any): string { + return yaml.dump(data, { + indent: 2, + lineWidth: -1, + noRefs: true, + }); +} + + diff --git a/scripts/agent-identities/src/validators/content-validator.ts b/scripts/agent-identities/src/validators/content-validator.ts new file mode 100644 index 0000000..d82ceb9 --- /dev/null +++ b/scripts/agent-identities/src/validators/content-validator.ts @@ -0,0 +1,55 @@ +import { readFileContent } from '../utils/file-reader.js'; + +const MIN_LINES = 150; +const MAX_LINES = 2000; +const TARGET_MIN = 800; +const TARGET_MAX = 1500; + +export async function validateContent(agentPath: string): Promise<{ + valid: boolean; + errors: string[]; + warnings: string[]; +}> { + const errors: string[] = []; + const warnings: string[] = []; + + try { + const content = await readFileContent(agentPath); + const lines = content.split('\n').length; + + // Check line count + if (lines < MIN_LINES) { + errors.push(`File too short (${lines} lines). Minimum: ${MIN_LINES}`); + } else if (lines > MAX_LINES) { + errors.push(`File too long (${lines} lines). Maximum: ${MAX_LINES}`); + } else if (lines < TARGET_MIN || lines > TARGET_MAX) { + warnings.push(`Line count (${lines}) outside target range (${TARGET_MIN}-${TARGET_MAX})`); + } + + // Check for required sections + const requiredSections = [ + '# ', // Title + '## Key Documentation', + '## Project Location', + '## Core Responsibilities', + '## Technology Stack', + ]; + + for (const section of requiredSections) { + if (!content.includes(section)) { + errors.push(`Missing required section: ${section}`); + } + } + + } catch (error) { + errors.push(`Failed to read file: ${error}`); + } + + return { + valid: errors.length === 0, + errors, + warnings, + }; +} + + diff --git a/scripts/agent-identities/src/validators/file-path-validator.ts b/scripts/agent-identities/src/validators/file-path-validator.ts new file mode 100644 index 0000000..80ef374 --- /dev/null +++ b/scripts/agent-identities/src/validators/file-path-validator.ts @@ -0,0 +1,68 @@ +import { access } from 'fs/promises'; +import { readFileContent } from '../utils/file-reader.js'; + +function extractFileReferences(content: string): string[] { + const references: string[] = []; + + // Extract mdc: links + const mdcPattern = /\(mdc:([^)]+)\)/g; + let match; + while ((match = mdcPattern.exec(content)) !== null) { + references.push(match[1]); + } + + // Extract code block file paths (comments indicating source) + // e.g., + const sourcePattern = //g; + while ((match = sourcePattern.exec(content)) !== null) { + const paths = match[1].split(',').map(p => p.trim()); + references.push(...paths); + } + + // Extract direct file path references in backticks + // e.g., `app-agent/cmd/server/main.go` + const backtickPattern = /`([a-z-]+\/[a-z-/.]+)`/g; + while ((match = backtickPattern.exec(content)) !== null) { + if (match[1].includes('/') && match[1].includes('.')) { + references.push(match[1]); + } + } + + return [...new Set(references)]; // Remove duplicates +} + +export async function validateFilePaths(agentPath: string): Promise<{ + valid: boolean; + missingFiles: string[]; +}> { + try { + // 1. Parse agent identity content + const content = await readFileContent(agentPath); + + // 2. Extract all file/directory references + const fileReferences = extractFileReferences(content); + + // 3. Check each file exists + const missingFiles: string[] = []; + + for (const filePath of fileReferences) { + try { + await access(filePath); + } catch { + missingFiles.push(filePath); + } + } + + return { + valid: missingFiles.length === 0, + missingFiles, + }; + } catch (error) { + return { + valid: false, + missingFiles: [`Error validating file paths: ${error}`], + }; + } +} + + diff --git a/scripts/agent-identities/src/validators/index.ts b/scripts/agent-identities/src/validators/index.ts new file mode 100644 index 0000000..6df63ba --- /dev/null +++ b/scripts/agent-identities/src/validators/index.ts @@ -0,0 +1,6 @@ +export { validateYaml } from './yaml-validator.js'; +export { validateContent } from './content-validator.js'; +export { checkIfStale } from './sync-validator.js'; +export { validateFilePaths } from './file-path-validator.js'; + + diff --git a/scripts/agent-identities/src/validators/sync-validator.ts b/scripts/agent-identities/src/validators/sync-validator.ts new file mode 100644 index 0000000..2246fbd --- /dev/null +++ b/scripts/agent-identities/src/validators/sync-validator.ts @@ -0,0 +1,60 @@ +import { stat } from 'fs/promises'; +import { readFileContent } from '../utils/file-reader.js'; +import matter from 'gray-matter'; + +export async function checkIfStale(agentPath: string): Promise<{ + isStale: boolean; + reason?: string; + staleFiles?: string[]; +}> { + try { + // 1. Parse agent identity + const content = await readFileContent(agentPath); + const { data: frontMatter } = matter(content); + + // 2. Get source files from metadata + const sourceFiles: string[] = frontMatter._source_files || []; + const generatedAt = frontMatter._generated_at + ? new Date(frontMatter._generated_at) + : new Date(0); // If no generation date, consider it stale + + if (sourceFiles.length === 0) { + return { + isStale: true, + reason: 'No source files tracked (not generated or old format)', + }; + } + + // 3. Check if any source file is newer than generation time + const staleFiles: string[] = []; + + for (const sourceFile of sourceFiles) { + try { + const stats = await stat(sourceFile); + if (stats.mtime > generatedAt) { + staleFiles.push(sourceFile); + } + } catch (err) { + // File doesn't exist or can't be read + staleFiles.push(`${sourceFile} (missing)`); + } + } + + if (staleFiles.length > 0) { + return { + isStale: true, + reason: 'Source files modified since last generation', + staleFiles, + }; + } + + return { isStale: false }; + } catch (error) { + return { + isStale: true, + reason: `Error checking staleness: ${error}`, + }; + } +} + + diff --git a/scripts/agent-identities/src/validators/yaml-validator.ts b/scripts/agent-identities/src/validators/yaml-validator.ts new file mode 100644 index 0000000..5320cb8 --- /dev/null +++ b/scripts/agent-identities/src/validators/yaml-validator.ts @@ -0,0 +1,65 @@ +import { readFileContent } from '../utils/file-reader.js'; +import matter from 'gray-matter'; + +const REQUIRED_FIELDS = [ + 'name', + 'title', + 'description', + 'role_type', + 'version', + 'last_updated', + 'llm_context', + 'context_window_target', +]; + +const ENUM_FIELDS: Record = { + role_type: ['engineering', 'design', 'product', 'operations', 'qa', 'documentation'], + system_integration_level: ['high', 'medium', 'low', 'none'], + llm_context: ['high', 'medium', 'low'], +}; + +export async function validateYaml(agentPath: string): Promise<{ + valid: boolean; + errors: string[]; +}> { + const errors: string[] = []; + + try { + const content = await readFileContent(agentPath); + const { data: frontMatter } = matter(content); + + // Check required fields + for (const field of REQUIRED_FIELDS) { + if (!(field in frontMatter)) { + errors.push(`Missing required field: ${field}`); + } + } + + // Check enum fields + for (const [field, validValues] of Object.entries(ENUM_FIELDS)) { + if (field in frontMatter && !validValues.includes(frontMatter[field])) { + errors.push(`Invalid value for ${field}: ${frontMatter[field]}. Must be one of: ${validValues.join(', ')}`); + } + } + + // Check version format (semver) + if (frontMatter.version && !/^\d+\.\d+\.\d+$/.test(frontMatter.version)) { + errors.push(`Invalid version format: ${frontMatter.version}. Must be semver (e.g., 1.0.0)`); + } + + // Check date format (YYYY-MM-DD) + if (frontMatter.last_updated && !/^\d{4}-\d{2}-\d{2}$/.test(frontMatter.last_updated)) { + errors.push(`Invalid date format: ${frontMatter.last_updated}. Must be YYYY-MM-DD`); + } + + } catch (error) { + errors.push(`Failed to parse YAML: ${error}`); + } + + return { + valid: errors.length === 0, + errors, + }; +} + + diff --git a/scripts/agent-identities/tsconfig.json b/scripts/agent-identities/tsconfig.json new file mode 100644 index 0000000..dd2eb9e --- /dev/null +++ b/scripts/agent-identities/tsconfig.json @@ -0,0 +1,16 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "ESNext", + "moduleResolution": "bundler", + "esModuleInterop": true, + "strict": true, + "skipLibCheck": true, + "outDir": "./dist", + "rootDir": "./src" + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist"] +} + + diff --git a/scripts/build-containers-with-monitor.sh b/scripts/build-containers-with-monitor.sh new file mode 100644 index 0000000..c451299 --- /dev/null +++ b/scripts/build-containers-with-monitor.sh @@ -0,0 +1,77 @@ +#!/bin/bash + +# Build containers with updated SystemMonitor from main project +# This script copies the SystemMonitor source to each container directory and builds + +set -e + +echo "🔨 Building containers with updated SystemMonitor..." + +# Get the directory of this script +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" + +# Paths to the monitoring components +SYSTEM_MONITOR_DIR="$PROJECT_ROOT/../minor-projects/app-system-monitor" + +# Check if main system monitor directory exists +if [ ! -d "$SYSTEM_MONITOR_DIR" ]; then + echo "❌ System monitor directory not found: $SYSTEM_MONITOR_DIR" + exit 1 +fi + +# Function to copy system monitor to container directory +copy_system_monitor() { + local container_dir="$1" + local container_name="$2" + + echo "📊 Copying SystemMonitor to $container_name..." + + if [ -d "$container_dir" ]; then + # Remove any existing app-system-monitor directory + rm -rf "$container_dir/app-system-monitor" + + # Copy the main system monitor + cp -r "$SYSTEM_MONITOR_DIR" "$container_dir/" + + echo "✅ SystemMonitor copied to $container_name" + else + echo "⚠️ Container directory not found: $container_dir" + fi +} + +# Copy system monitor to each container directory +copy_system_monitor "$PROJECT_ROOT/sirius-postgres" "sirius-postgres" +copy_system_monitor "$PROJECT_ROOT/sirius-rabbitmq" "sirius-rabbitmq" +copy_system_monitor "$PROJECT_ROOT/sirius-valkey" "sirius-valkey" + +# Update Dockerfiles to use local copy instead of relative path +echo "🔧 Updating Dockerfiles to use local SystemMonitor copy..." + +# Update PostgreSQL Dockerfile +sed -i.bak 's|COPY ../../minor-projects/app-system-monitor|COPY app-system-monitor|g' "$PROJECT_ROOT/sirius-postgres/Dockerfile" + +# Update RabbitMQ Dockerfile +sed -i.bak 's|COPY ../../minor-projects/app-system-monitor|COPY app-system-monitor|g' "$PROJECT_ROOT/sirius-rabbitmq/Dockerfile" + +# Update Valkey Dockerfile +sed -i.bak 's|COPY ../../minor-projects/app-system-monitor|COPY app-system-monitor|g' "$PROJECT_ROOT/sirius-valkey/Dockerfile" + +# Build the containers +echo "🚀 Building containers..." +docker-compose build sirius-postgres sirius-rabbitmq sirius-valkey + +# Restore original Dockerfiles +echo "🔄 Restoring original Dockerfiles..." +mv "$PROJECT_ROOT/sirius-postgres/Dockerfile.bak" "$PROJECT_ROOT/sirius-postgres/Dockerfile" +mv "$PROJECT_ROOT/sirius-rabbitmq/Dockerfile.bak" "$PROJECT_ROOT/sirius-rabbitmq/Dockerfile" +mv "$PROJECT_ROOT/sirius-valkey/Dockerfile.bak" "$PROJECT_ROOT/sirius-valkey/Dockerfile" + +# Clean up copied directories +echo "🧹 Cleaning up temporary SystemMonitor copies..." +rm -rf "$PROJECT_ROOT/sirius-postgres/app-system-monitor" +rm -rf "$PROJECT_ROOT/sirius-rabbitmq/app-system-monitor" +rm -rf "$PROJECT_ROOT/sirius-valkey/app-system-monitor" + +echo "✅ Container build completed successfully!" +echo "🎉 All containers now have the updated SystemMonitor with CPU drift fix!" diff --git a/scripts/build-system-monitor-universal.sh b/scripts/build-system-monitor-universal.sh new file mode 100755 index 0000000..47c3b3e --- /dev/null +++ b/scripts/build-system-monitor-universal.sh @@ -0,0 +1,132 @@ +#!/bin/bash + +# Universal SystemMonitor build script +# This script builds the SystemMonitor binary for all target architectures +# and creates a universal binary that can be used across all containers + +set -e + +echo "🔨 Building universal SystemMonitor binary..." + +# Get the directory of this script +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" + +# Paths +SYSTEM_MONITOR_DIR="$PROJECT_ROOT/../minor-projects/app-system-monitor" +BUILD_DIR="$PROJECT_ROOT/tmp/system-monitor-build" +BINARY_DIR="$PROJECT_ROOT/tmp/system-monitor-binaries" + +# Clean and create build directories +rm -rf "$BUILD_DIR" "$BINARY_DIR" +mkdir -p "$BUILD_DIR" "$BINARY_DIR" + +# Copy SystemMonitor source to build directory +echo "📦 Preparing SystemMonitor source..." +cp -r "$SYSTEM_MONITOR_DIR"/* "$BUILD_DIR/" + +# Build for multiple architectures +echo "🏗️ Building SystemMonitor for multiple architectures..." + +cd "$BUILD_DIR" + +# Build for linux/amd64 (most common) +echo " → Building for linux/amd64..." +GOOS=linux GOARCH=amd64 go build -o "$BINARY_DIR/system-monitor-linux-amd64" . + +# Build for linux/arm64 (Apple Silicon, ARM servers) +echo " → Building for linux/arm64..." +GOOS=linux GOARCH=arm64 go build -o "$BINARY_DIR/system-monitor-linux-arm64" . + +# Create a universal binary script that detects architecture +echo "🔧 Creating universal binary script..." +cat > "$BINARY_DIR/system-monitor" << 'EOF' +#!/bin/bash + +# Universal SystemMonitor binary launcher +# Detects the current architecture and runs the appropriate binary + +ARCH=$(uname -m) +OS=$(uname -s) + +# Map architecture names +case "$ARCH" in + x86_64|amd64) + BINARY_NAME="system-monitor-linux-amd64" + ;; + aarch64|arm64) + BINARY_NAME="system-monitor-linux-arm64" + ;; + *) + echo "❌ Unsupported architecture: $ARCH" + exit 1 + ;; +esac + +# Get the directory of this script +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +BINARY_PATH="$SCRIPT_DIR/$BINARY_NAME" + +# Check if the appropriate binary exists +if [ ! -f "$BINARY_PATH" ]; then + echo "❌ SystemMonitor binary not found for architecture $ARCH: $BINARY_PATH" + exit 1 +fi + +# Make sure the binary is executable +chmod +x "$BINARY_PATH" + +# Execute the appropriate binary with all arguments +exec "$BINARY_PATH" "$@" +EOF + +chmod +x "$BINARY_DIR/system-monitor" + +# Test the universal binary +echo "🧪 Testing universal binary..." +cd "$BINARY_DIR" +if ./system-monitor --help 2>/dev/null || echo "Binary built successfully (no help flag)"; then + echo "✅ Universal SystemMonitor binary is working" +else + echo "❌ Universal SystemMonitor binary test failed" + exit 1 +fi + +echo "✅ Universal SystemMonitor build completed successfully!" +echo "📍 Binary location: $BINARY_DIR/system-monitor" +echo "📦 Architecture-specific binaries:" +echo " - linux/amd64: $BINARY_DIR/system-monitor-linux-amd64" +echo " - linux/arm64: $BINARY_DIR/system-monitor-linux-arm64" + +# Copy to container directories for Docker builds +echo "📋 Copying binaries to container directories..." + +# Copy to sirius-postgres +if [ -d "$PROJECT_ROOT/sirius-postgres" ]; then + echo " → Copying to sirius-postgres..." + rm -rf "$PROJECT_ROOT/sirius-postgres/system-monitor-binary" + cp -r "$BINARY_DIR" "$PROJECT_ROOT/sirius-postgres/system-monitor-binary" +fi + +# Copy to sirius-rabbitmq +if [ -d "$PROJECT_ROOT/sirius-rabbitmq" ]; then + echo " → Copying to sirius-rabbitmq..." + rm -rf "$PROJECT_ROOT/sirius-rabbitmq/system-monitor-binary" + cp -r "$BINARY_DIR" "$PROJECT_ROOT/sirius-rabbitmq/system-monitor-binary" +fi + +# Copy to sirius-valkey +if [ -d "$PROJECT_ROOT/sirius-valkey" ]; then + echo " → Copying to sirius-valkey..." + rm -rf "$PROJECT_ROOT/sirius-valkey/system-monitor-binary" + cp -r "$BINARY_DIR" "$PROJECT_ROOT/sirius-valkey/system-monitor-binary" +fi + +# Copy to sirius-engine +if [ -d "$PROJECT_ROOT/sirius-engine" ]; then + echo " → Copying to sirius-engine..." + rm -rf "$PROJECT_ROOT/sirius-engine/system-monitor-binary" + cp -r "$BINARY_DIR" "$PROJECT_ROOT/sirius-engine/system-monitor-binary" +fi + +echo "🎉 Universal SystemMonitor is ready for all containers!" diff --git a/scripts/build-ui-monitoring.sh b/scripts/build-ui-monitoring.sh new file mode 100755 index 0000000..50e8fed --- /dev/null +++ b/scripts/build-ui-monitoring.sh @@ -0,0 +1,45 @@ +#!/bin/bash + +# Build script for UI container monitoring components +# This script builds the system monitor and app administrator for the UI container + +set -e + +echo "🔧 Building monitoring components for UI container..." + +# Get the directory of this script +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" + +# Paths to the monitoring components +SYSTEM_MONITOR_DIR="$PROJECT_ROOT/../minor-projects/app-system-monitor" +ADMINISTRATOR_DIR="$PROJECT_ROOT/../minor-projects/app-administrator" + +# Check if directories exist +if [ ! -d "$SYSTEM_MONITOR_DIR" ]; then + echo "❌ System monitor directory not found: $SYSTEM_MONITOR_DIR" + exit 1 +fi + +if [ ! -d "$ADMINISTRATOR_DIR" ]; then + echo "❌ Administrator directory not found: $ADMINISTRATOR_DIR" + exit 1 +fi + +# Build system monitor +echo "📊 Building system monitor..." +cd "$SYSTEM_MONITOR_DIR" +go mod download +CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o system-monitor main.go +echo "✅ System monitor built successfully" + +# Build app administrator +echo "🔧 Building app administrator..." +cd "$ADMINISTRATOR_DIR" +go mod download +CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o administrator main.go +echo "✅ App administrator built successfully" + +echo "🎉 All monitoring components built successfully!" +echo "📁 System monitor: $SYSTEM_MONITOR_DIR/system-monitor" +echo "📁 App administrator: $ADMINISTRATOR_DIR/administrator" diff --git a/scripts/cross-platform/find-password-files.sh b/scripts/cross-platform/find-password-files.sh new file mode 100644 index 0000000..47e8039 --- /dev/null +++ b/scripts/cross-platform/find-password-files.sh @@ -0,0 +1,232 @@ +#!/bin/bash + +# Script metadata +VULNERABILITY_ID="CVE-2024-PASSWORD-001" +SEVERITY="high" +DESCRIPTION="Detects insecure password files (passwords.txt) in user home directories" +AUTHOR="sirius-security-team" +VERSION="1.0" + +# Configuration +VERBOSE=false +SPECIFIC_USER="" + +# Parse command line arguments +while [[ $# -gt 0 ]]; do + case $1 in + --verbose|-v) + VERBOSE=true + shift + ;; + --user|-u) + SPECIFIC_USER="$2" + shift 2 + ;; + --help|-h) + echo "Usage: $0 [--verbose] [--user ]" + echo " --verbose, -v Enable verbose output" + echo " --user, -u Check specific user's home directory" + echo " --help, -h Show this help message" + exit 0 + ;; + *) + echo "Unknown option: $1" + exit 1 + ;; + esac +done + +# Logging function +log_verbose() { + if [[ "$VERBOSE" == "true" ]]; then + echo "[VERBOSE] $1" >&2 + fi +} + +# Main detection function +find_password_files() { + local vulnerable=false + local confidence=0.0 + local evidence=() + local error="" + local total_files_found=0 + + log_verbose "Starting password file detection" + + # Determine which directories to search + local search_dirs=() + + if [[ -n "$SPECIFIC_USER" ]]; then + # Check specific user's home directory + if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then + # Windows + local user_home="/c/Users/$SPECIFIC_USER" + else + # Linux/macOS + local user_home="/home/$SPECIFIC_USER" + if [[ "$OSTYPE" == "darwin"* ]]; then + user_home="/Users/$SPECIFIC_USER" + fi + fi + + if [[ -d "$user_home" ]]; then + search_dirs+=("$user_home") + else + error="User home directory not found for user: $SPECIFIC_USER" + fi + else + # Search current user's home directory + if [[ -n "$HOME" ]]; then + search_dirs+=("$HOME") + else + error="HOME environment variable not set" + fi + fi + + if [[ -n "$error" ]]; then + cat << EOF +{ + "vulnerability_id": "$VULNERABILITY_ID", + "vulnerable": null, + "confidence": 0.0, + "evidence": [], + "metadata": {}, + "error": "$error" +} +EOF + return + fi + + # Search for password files + for search_dir in "${search_dirs[@]}"; do + log_verbose "Searching directory: $search_dir" + + # Look for passwords.txt files (case insensitive) + local password_files + password_files=$(find "$search_dir" -type f -iname "passwords.txt" 2>/dev/null) + + if [[ -n "$password_files" ]]; then + while IFS= read -r password_file; do + if [[ -n "$password_file" ]]; then + total_files_found=$((total_files_found + 1)) + vulnerable=true + + # Get file details + local file_size + local file_perms + local file_owner + local file_modified + + file_size=$(stat -c%s "$password_file" 2>/dev/null || stat -f%z "$password_file" 2>/dev/null || echo "unknown") + file_perms=$(stat -c%a "$password_file" 2>/dev/null || stat -f%A "$password_file" 2>/dev/null || echo "unknown") + file_owner=$(stat -c%U "$password_file" 2>/dev/null || stat -f%Su "$password_file" 2>/dev/null || echo "unknown") + file_modified=$(stat -c%Y "$password_file" 2>/dev/null || stat -f%m "$password_file" 2>/dev/null || echo "unknown") + + # Check if file is world-readable + local world_readable=false + if [[ "$file_perms" =~ [0-9][0-9][4-7] ]]; then + world_readable=true + fi + + # Build evidence entry + local evidence_entry + evidence_entry=$(cat << EOF +{ + "type": "insecure_password_file", + "file_path": "$password_file", + "file_size": "$file_size", + "file_permissions": "$file_perms", + "file_owner": "$file_owner", + "last_modified": "$file_modified", + "world_readable": $world_readable, + "risk_level": "$(if [[ "$world_readable" == "true" ]]; then echo "critical"; else echo "high"; fi)" +} +EOF + ) + + evidence+=("$evidence_entry") + + log_verbose "FOUND: $password_file (size: $file_size, perms: $file_perms, world-readable: $world_readable)" + fi + done <<< "$password_files" + fi + + # Also look for other common password file patterns + local other_patterns=("password.txt" "pass.txt" "passwords.log" "creds.txt" "credentials.txt") + for pattern in "${other_patterns[@]}"; do + local found_files + found_files=$(find "$search_dir" -type f -iname "$pattern" 2>/dev/null) + + if [[ -n "$found_files" ]]; then + while IFS= read -r found_file; do + if [[ -n "$found_file" ]]; then + total_files_found=$((total_files_found + 1)) + vulnerable=true + + local file_size + local file_perms + file_size=$(stat -c%s "$found_file" 2>/dev/null || stat -f%z "$found_file" 2>/dev/null || echo "unknown") + file_perms=$(stat -c%a "$found_file" 2>/dev/null || stat -f%A "$found_file" 2>/dev/null || echo "unknown") + + local evidence_entry + evidence_entry=$(cat << EOF +{ + "type": "potential_password_file", + "file_path": "$found_file", + "file_size": "$file_size", + "file_permissions": "$file_perms", + "risk_level": "medium" +} +EOF + ) + + evidence+=("$evidence_entry") + + log_verbose "FOUND: $found_file (pattern: $pattern)" + fi + done <<< "$found_files" + fi + done + done + + # Calculate confidence + if [[ "$vulnerable" == "true" ]]; then + if [[ $total_files_found -ge 5 ]]; then + confidence=0.95 + elif [[ $total_files_found -ge 3 ]]; then + confidence=0.85 + elif [[ $total_files_found -ge 2 ]]; then + confidence=0.75 + else + confidence=0.65 + fi + fi + + # Format evidence array + local evidence_json="" + if [[ ${#evidence[@]} -gt 0 ]]; then + evidence_json=$(printf '%s,' "${evidence[@]}" | sed 's/,$//') + fi + + log_verbose "Password file detection complete: $total_files_found files found" + + # Output JSON result + cat << EOF +{ + "vulnerability_id": "$VULNERABILITY_ID", + "vulnerable": $vulnerable, + "confidence": $confidence, + "evidence": [$evidence_json], + "metadata": { + "scan_type": "password_file_detection", + "total_files_found": $total_files_found, + "search_directories": "$(printf '%s,' "${search_dirs[@]}" | sed 's/,$//')", + "searched_user": "$(if [[ -n "$SPECIFIC_USER" ]]; then echo "$SPECIFIC_USER"; else echo "current"; fi)" + }, + "error": null +} +EOF +} + +# Execute detection +find_password_files \ No newline at end of file diff --git a/scripts/deploy.sh b/scripts/deploy.sh new file mode 100755 index 0000000..e5dfa39 --- /dev/null +++ b/scripts/deploy.sh @@ -0,0 +1,361 @@ +#!/bin/bash + +# Sirius Scan Deployment Script +# Usage: ./scripts/deploy.sh [environment] [image_tag] +# Example: ./scripts/deploy.sh production v1.2.3 + +set -e # Exit on any error + +# Configuration +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_DIR="$(dirname "$SCRIPT_DIR")" +ENVIRONMENTS_DIR="$PROJECT_DIR/environments" + +# Default values +ENVIRONMENT="${1:-development}" +IMAGE_TAG="${2:-latest}" +COMPOSE_PROJECT_NAME="sirius" + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Logging functions +log_info() { + echo -e "${BLUE}[INFO]${NC} $1" +} + +log_success() { + echo -e "${GREEN}[SUCCESS]${NC} $1" +} + +log_warning() { + echo -e "${YELLOW}[WARNING]${NC} $1" +} + +log_error() { + echo -e "${RED}[ERROR]${NC} $1" +} + +# Help function +show_help() { + cat << EOF +Sirius Scan Deployment Script + +Usage: $0 [ENVIRONMENT] [IMAGE_TAG] + +ENVIRONMENT: + development - Local development (default) + staging - Staging environment + production - Production environment + +IMAGE_TAG: + Version tag for Docker images (default: latest) + +Examples: + $0 # Deploy development with latest images + $0 staging # Deploy staging with latest images + $0 production v1.2.3 # Deploy production with specific version + $0 staging beta-2024.01.15 # Deploy staging with beta version + +Environment Configuration: + All environments use defaults in compose files with override capability: + - Development: Uses docker-compose.override.yaml + - Staging/Production: Uses sensible defaults with ${VAR:-default} syntax + - Override any variable: export POSTGRES_PASSWORD=mypassword + +Docker Compose Files: + - docker-compose.yaml (base configuration) + - docker-compose.override.yaml (development - auto-loaded) + - docker-compose.staging.yaml (staging environment) + - docker-compose.production.yaml (production environment) + +EOF +} + +# Validate environment +validate_environment() { + case "$ENVIRONMENT" in + development|staging|production) + log_info "Deploying to: $ENVIRONMENT" + ;; + help|--help|-h) + show_help + exit 0 + ;; + *) + log_error "Invalid environment: $ENVIRONMENT" + log_error "Valid environments: development, staging, production" + exit 1 + ;; + esac +} + +# Check if environment file exists (now using defaults in compose files) +check_env_file() { + if [[ "$ENVIRONMENT" == "development" ]]; then + log_info "Development environment uses docker-compose.override.yaml" + return 0 + fi + + log_info "Using defaults from compose files (no separate env file needed)" + log_info "Override variables with: export POSTGRES_PASSWORD=yourpassword" +} + +# Check if Docker Compose files exist +check_compose_files() { + local base_file="$PROJECT_DIR/docker-compose.yaml" + local env_file="" + + if [[ ! -f "$base_file" ]]; then + log_error "Base docker-compose.yaml not found: $base_file" + exit 1 + fi + + case "$ENVIRONMENT" in + development) + env_file="$PROJECT_DIR/docker-compose.override.yaml" + ;; + staging) + env_file="$PROJECT_DIR/docker-compose.staging.yaml" + ;; + production) + env_file="$PROJECT_DIR/docker-compose.production.yaml" + ;; + esac + + if [[ -n "$env_file" && ! -f "$env_file" ]]; then + log_error "Environment-specific compose file not found: $env_file" + exit 1 + fi + + log_success "Docker Compose files validated" +} + +# Pre-deployment checks +pre_deployment_checks() { + log_info "Running pre-deployment checks..." + + # Check if Docker is running + if ! docker info >/dev/null 2>&1; then + log_error "Docker is not running. Please start Docker and try again." + exit 1 + fi + + # Check if Docker Compose is available + if ! command -v docker >/dev/null 2>&1; then + log_error "Docker Compose is not installed or not in PATH" + exit 1 + fi + + # Check available disk space (warn if less than 5GB) + local available_space=$(df "$PROJECT_DIR" | awk 'NR==2 {print $4}') + if [[ "$available_space" -lt 5242880 ]]; then # 5GB in KB + log_warning "Low disk space detected. Consider cleaning up before deployment." + fi + + log_success "Pre-deployment checks passed" +} + +# Build compose command +build_compose_command() { + local cmd="docker compose" + + # Add base compose file + cmd="$cmd -f docker-compose.yaml" + + # Add environment-specific compose file + case "$ENVIRONMENT" in + staging) + cmd="$cmd -f docker-compose.staging.yaml" + ;; + production) + cmd="$cmd -f docker-compose.production.yaml" + ;; + development) + # docker-compose.override.yaml is loaded automatically + ;; + esac + + # Environment variables are handled with defaults in compose files + # No separate env files needed + + # Set project name + cmd="$cmd -p ${COMPOSE_PROJECT_NAME}_${ENVIRONMENT}" + + echo "$cmd" +} + +# Pull images for production/staging +pull_images() { + if [[ "$ENVIRONMENT" == "development" ]]; then + log_info "Skipping image pull for development environment" + return 0 + fi + + log_info "Pulling Docker images for $ENVIRONMENT..." + + local compose_cmd=$(build_compose_command) + + # Export IMAGE_TAG for compose + export IMAGE_TAG="$IMAGE_TAG" + + if $compose_cmd pull; then + log_success "Images pulled successfully" + else + log_error "Failed to pull images" + exit 1 + fi +} + +# Deploy services +deploy_services() { + log_info "Deploying services for $ENVIRONMENT environment..." + + local compose_cmd=$(build_compose_command) + + # Export IMAGE_TAG for compose + export IMAGE_TAG="$IMAGE_TAG" + + # Deploy based on environment + case "$ENVIRONMENT" in + development) + log_info "Starting development environment with build..." + if $compose_cmd up --build -d; then + log_success "Development environment started" + else + log_error "Failed to start development environment" + exit 1 + fi + ;; + staging|production) + log_info "Starting $ENVIRONMENT environment..." + if $compose_cmd up -d; then + log_success "$ENVIRONMENT environment started" + else + log_error "Failed to start $ENVIRONMENT environment" + exit 1 + fi + ;; + esac +} + +# Health checks +run_health_checks() { + log_info "Running health checks..." + + local compose_cmd=$(build_compose_command) + + # Wait for services to be ready + sleep 10 + + # Check if all services are running + local running_services=$($compose_cmd ps --services --filter "status=running" | wc -l) + local total_services=$($compose_cmd ps --services | wc -l) + + if [[ "$running_services" -eq "$total_services" ]]; then + log_success "All services are running ($running_services/$total_services)" + else + log_warning "Some services may not be running ($running_services/$total_services)" + log_info "Service status:" + $compose_cmd ps + fi + + # Basic connectivity tests + case "$ENVIRONMENT" in + development) + log_info "Testing local endpoints..." + if curl -f http://localhost:3000 >/dev/null 2>&1; then + log_success "UI is responding on http://localhost:3000" + else + log_warning "UI may not be ready yet on http://localhost:3000" + fi + + if curl -f http://localhost:9001 >/dev/null 2>&1; then + log_success "API is responding on http://localhost:9001" + else + log_warning "API may not be ready yet on http://localhost:9001" + fi + ;; + esac +} + +# Show deployment summary +show_summary() { + log_success "Deployment completed successfully!" + echo + echo "=== Deployment Summary ===" + echo "Environment: $ENVIRONMENT" + echo "Image Tag: $IMAGE_TAG" + echo "Project Name: ${COMPOSE_PROJECT_NAME}_${ENVIRONMENT}" + echo + + case "$ENVIRONMENT" in + development) + echo "Access URLs:" + echo " UI: http://localhost:3000" + echo " API: http://localhost:9001" + echo " RabbitMQ Management: http://localhost:15672" + echo " PostgreSQL: localhost:5432" + echo + echo "Useful commands:" + echo " View logs: docker compose logs -f" + echo " Stop services: docker compose down" + echo " Restart: docker compose restart" + ;; + staging|production) + echo "Useful commands:" + local compose_cmd=$(build_compose_command) + echo " View logs: $compose_cmd logs -f" + echo " Stop services: $compose_cmd down" + echo " Restart: $compose_cmd restart" + echo " Scale service: $compose_cmd up -d --scale sirius-api=3" + ;; + esac + + echo + echo "For more information, see: documentation/README.deployment-strategy.md" +} + +# Cleanup on exit +cleanup() { + if [[ $? -ne 0 ]]; then + log_error "Deployment failed. Check the logs above for details." + echo + echo "Troubleshooting tips:" + echo "1. Check Docker daemon is running" + echo "2. Verify environment file exists and is valid" + echo "3. Ensure sufficient disk space" + echo "4. Check network connectivity for image pulls" + fi +} + +trap cleanup EXIT + +# Main execution +main() { + echo "=== Sirius Scan Deployment Script ===" + echo + + validate_environment + check_env_file + check_compose_files + pre_deployment_checks + + if [[ "$ENVIRONMENT" != "development" ]]; then + pull_images + fi + + deploy_services + run_health_checks + show_summary +} + +# Change to project directory +cd "$PROJECT_DIR" + +# Run main function +main "$@" \ No newline at end of file diff --git a/scripts/dev-setup.sh b/scripts/dev-setup.sh new file mode 100755 index 0000000..cae1c08 --- /dev/null +++ b/scripts/dev-setup.sh @@ -0,0 +1,221 @@ +#!/bin/bash + +# Sirius Development Setup Helper +# This script helps set up local development environment + +set -e + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" +LOCAL_COMPOSE="$PROJECT_ROOT/docker-compose.local.yaml" +EXAMPLE_COMPOSE="$PROJECT_ROOT/docker-compose.local.example.yaml" +ENV_FILE="$PROJECT_ROOT/.env" +INSTALLER_COMPOSE_FILE="$PROJECT_ROOT/docker-compose.installer.yaml" + +echo "🚀 Sirius Development Setup" +echo "================================" + +# Function to show usage +show_usage() { + echo "Usage: $0 [command]" + echo "" + echo "Commands:" + echo " init Create local docker-compose.local.yaml from template" + echo " start Start development environment" + echo " start-extended Start with local repository mounts (requires setup)" + echo " stop Stop development environment" + echo " clean Clean development environment and volumes" + echo " status Show container status" + echo " logs [service] Show logs for all services or specific service" + echo " shell Open shell in service container" + echo "" + echo "Examples:" + echo " $0 init # Set up local development files" + echo " $0 start # Standard development mode" + echo " $0 start-extended # Extended development with local repos" + echo " $0 logs sirius-engine # Show engine logs" + echo " $0 shell sirius-ui # Open shell in UI container" +} + +# Function to check if local compose file exists +check_local_compose() { + if [ ! -f "$LOCAL_COMPOSE" ]; then + echo "⚠️ Local compose file not found: $LOCAL_COMPOSE" + echo "💡 Run '$0 init' to create it from template" + return 1 + fi + return 0 +} + +# Function to initialize local development setup +init_dev() { + echo "📋 Setting up local development environment..." + + if [ -f "$LOCAL_COMPOSE" ]; then + echo "⚠️ $LOCAL_COMPOSE already exists" + read -p "Do you want to overwrite it? (y/N): " -n 1 -r + echo + if [[ ! $REPLY =~ ^[Yy]$ ]]; then + echo "ℹ️ Keeping existing file" + return 0 + fi + fi + + if [ ! -f "$EXAMPLE_COMPOSE" ]; then + echo "❌ Template file not found: $EXAMPLE_COMPOSE" + return 1 + fi + + cp "$EXAMPLE_COMPOSE" "$LOCAL_COMPOSE" + echo "✅ Created $LOCAL_COMPOSE" + echo "" + echo "📝 Next steps:" + echo "1. Edit $LOCAL_COMPOSE to uncomment the repositories you want to develop" + echo "2. Make sure you have the corresponding repositories in ../minor-projects/" + echo "3. Run '$0 start-extended' to start with local repository mounts" + echo "" + echo "🔧 For standard development (no local repos needed): '$0 start'" +} + +# Ensure required env exists before startup. +ensure_env_ready() { + if [ -f "$ENV_FILE" ]; then + return 0 + fi + + echo "⚠️ Missing $ENV_FILE" + if [ "${SIRIUS_AUTO_SETUP:-0}" = "1" ]; then + echo "🔧 Running installer container in non-interactive mode..." + docker compose -f "$INSTALLER_COMPOSE_FILE" run --rm sirius-installer --non-interactive --no-print-secrets + return 0 + fi + + echo "Run installer first:" + echo " docker compose -f docker-compose.installer.yaml run --rm sirius-installer" + echo "Or rerun with SIRIUS_AUTO_SETUP=1 for automated setup." + return 1 +} + +# Function to start development environment +start_dev() { + local mode=$1 + + cd "$PROJECT_ROOT" + ensure_env_ready || return 1 + + if [ "$mode" = "extended" ]; then + echo "🔧 Starting extended development environment..." + if ! check_local_compose; then + return 1 + fi + echo "📁 Using local repository mounts from docker-compose.local.yaml" + docker compose -f docker-compose.yaml -f docker-compose.override.yaml -f docker-compose.local.yaml up -d + else + echo "🔧 Starting standard development environment..." + docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d + fi + + echo "" + echo "✅ Development environment started!" + echo "🌐 UI: http://localhost:3000" + echo "🔧 API: http://localhost:9001" + echo "📊 RabbitMQ Management: http://localhost:15672 (guest/guest)" + + if command -v docker &> /dev/null; then + echo "" + echo "📋 Container Status:" + docker compose ps + fi +} + +# Function to stop development environment +stop_dev() { + echo "🛑 Stopping development environment..." + cd "$PROJECT_ROOT" + docker compose down + echo "✅ Development environment stopped" +} + +# Function to clean development environment +clean_dev() { + echo "🧹 Cleaning development environment..." + cd "$PROJECT_ROOT" + + read -p "This will remove all containers and volumes. Continue? (y/N): " -n 1 -r + echo + if [[ ! $REPLY =~ ^[Yy]$ ]]; then + echo "ℹ️ Cleanup cancelled" + return 0 + fi + + docker compose down -v --remove-orphans + docker system prune -f + echo "✅ Development environment cleaned" +} + +# Function to show container status +show_status() { + echo "📋 Container Status:" + cd "$PROJECT_ROOT" + docker compose ps +} + +# Function to show logs +show_logs() { + local service=$1 + cd "$PROJECT_ROOT" + + if [ -n "$service" ]; then + echo "📜 Showing logs for $service..." + docker compose logs -f "$service" + else + echo "📜 Showing logs for all services..." + docker compose logs -f + fi +} + +# Function to open shell in container +open_shell() { + local service=$1 + + if [ -z "$service" ]; then + echo "❌ Service name required" + echo "Available services: sirius-ui, sirius-api, sirius-engine, sirius-postgres, sirius-rabbitmq, sirius-valkey" + return 1 + fi + + cd "$PROJECT_ROOT" + echo "🐚 Opening shell in $service..." + docker compose exec "$service" /bin/bash || docker compose exec "$service" /bin/sh +} + +# Main command handling +case "$1" in + "init") + init_dev + ;; + "start") + start_dev + ;; + "start-extended") + start_dev extended + ;; + "stop") + stop_dev + ;; + "clean") + clean_dev + ;; + "status") + show_status + ;; + "logs") + show_logs "$2" + ;; + "shell") + open_shell "$2" + ;; + *) + show_usage + ;; +esac \ No newline at end of file diff --git a/scripts/documentation/lint-docs.sh b/scripts/documentation/lint-docs.sh new file mode 100755 index 0000000..e7f582d --- /dev/null +++ b/scripts/documentation/lint-docs.sh @@ -0,0 +1,400 @@ +#!/bin/bash + +# Sirius Documentation Linting System +# Validates documentation quality, consistency, and compliance + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Configuration +DOCS_DIR="../../documentation/dev" +TEMPLATES_DIR="$DOCS_DIR/templates" +SCRIPT_DIR="$(dirname "$0")" +LOG_FILE="tmp/documentation-lint-$(date +%Y%m%d-%H%M%S).log" + +# Create tmp directory if it doesn't exist +mkdir -p tmp + +# Required YAML front matter fields +REQUIRED_FIELDS=("title" "description" "template" "version" "last_updated") +OPTIONAL_FIELDS=("author" "tags" "categories" "difficulty" "prerequisites" "related_docs" "dependencies" "llm_context" "search_keywords") + +# Valid values for specific fields +VALID_TEMPLATES=("TEMPLATE.documentation-standard" "TEMPLATE.guide" "TEMPLATE.troubleshooting" "TEMPLATE.about" "TEMPLATE.reference" "TEMPLATE.architecture" "TEMPLATE.api" "TEMPLATE.template" "TEMPLATE.custom") +VALID_DIFFICULTIES=("beginner" "intermediate" "advanced") +VALID_LLM_CONTEXTS=("high" "medium" "low") + +# Counters +TOTAL_FILES=0 +PASSED_FILES=0 +FAILED_FILES=0 +WARNINGS=0 + +# Functions +log() { + echo -e "${BLUE}[$(date +'%H:%M:%S')]${NC} $1" | tee -a "$LOG_FILE" +} + +success() { + echo -e "${GREEN}✅ $1${NC}" | tee -a "$LOG_FILE" +} + +warning() { + echo -e "${YELLOW}⚠️ $1${NC}" | tee -a "$LOG_FILE" + ((WARNINGS++)) +} + +error() { + echo -e "${RED}❌ $1${NC}" | tee -a "$LOG_FILE" + ((FAILED_FILES++)) +} + +# Check if file has YAML front matter +check_yaml_front_matter() { + local file="$1" + local has_yaml=false + + if head -n 1 "$file" | grep -q "^---$"; then + has_yaml=true + fi + + if [ "$has_yaml" = false ]; then + error "Missing YAML front matter in $file" + return 1 + fi + + return 0 +} + +# Extract YAML front matter +extract_yaml() { + local file="$1" + local yaml_start=0 + local yaml_end=0 + local line_num=0 + + while IFS= read -r line; do + ((line_num++)) + if [ "$line" = "---" ]; then + if [ $yaml_start -eq 0 ]; then + yaml_start=$line_num + else + yaml_end=$line_num + break + fi + fi + done < "$file" + + if [ $yaml_start -gt 0 ] && [ $yaml_end -gt 0 ]; then + sed -n "${yaml_start},${yaml_end}p" "$file" + fi +} + +# Validate YAML syntax +validate_yaml_syntax() { + local file="$1" + local yaml_content + local temp_yaml + + yaml_content=$(extract_yaml "$file") + if [ -z "$yaml_content" ]; then + error "Could not extract YAML from $file" + return 1 + fi + + # Create temporary file for yq validation + temp_yaml=$(mktemp) + echo "$yaml_content" > "$temp_yaml" + + # Check if yq is available + if command -v yq >/dev/null 2>&1; then + if ! yq eval '.' "$temp_yaml" >/dev/null 2>&1; then + warning "YAML syntax validation skipped (yq compatibility issue)" + fi + else + warning "yq not available, skipping YAML syntax validation" + fi + + rm -f "$temp_yaml" + return 0 +} + +# Check required fields +check_required_fields() { + local file="$1" + local yaml_content + local missing_fields=() + + yaml_content=$(extract_yaml "$file") + if [ -z "$yaml_content" ]; then + return 1 + fi + + for field in "${REQUIRED_FIELDS[@]}"; do + if ! echo "$yaml_content" | grep -q "^${field}:"; then + missing_fields+=("$field") + fi + done + + if [ ${#missing_fields[@]} -gt 0 ]; then + error "Missing required fields in $file: ${missing_fields[*]}" + return 1 + fi + + return 0 +} + +# Validate field values +validate_field_values() { + local file="$1" + local yaml_content + local template + local difficulty + local llm_context + + yaml_content=$(extract_yaml "$file") + if [ -z "$yaml_content" ]; then + return 1 + fi + + # Check template field + template=$(echo "$yaml_content" | grep "^template:" | sed 's/^template: *//' | tr -d ' "') + if [ -n "$template" ]; then + if ! printf '%s\n' "${VALID_TEMPLATES[@]}" | grep -q "^${template}$"; then + error "Invalid template value in $file: $template" + return 1 + fi + fi + + # Check difficulty field + difficulty=$(echo "$yaml_content" | grep "^difficulty:" | sed 's/^difficulty: *//' | tr -d ' "') + if [ -n "$difficulty" ]; then + if ! printf '%s\n' "${VALID_DIFFICULTIES[@]}" | grep -q "^${difficulty}$"; then + error "Invalid difficulty value in $file: $difficulty" + return 1 + fi + fi + + # Check llm_context field + llm_context=$(echo "$yaml_content" | grep "^llm_context:" | sed 's/^llm_context: *//' | tr -d ' "') + if [ -n "$llm_context" ]; then + if ! printf '%s\n' "${VALID_LLM_CONTEXTS[@]}" | grep -q "^${llm_context}$"; then + error "Invalid llm_context value in $file: $llm_context" + return 1 + fi + fi + + return 0 +} + +# Check template compliance +check_template_compliance() { + local file="$1" + local yaml_content + local template + local template_file + + yaml_content=$(extract_yaml "$file") + if [ -z "$yaml_content" ]; then + return 1 + fi + + template=$(echo "$yaml_content" | grep "^template:" | sed 's/^template: *//' | tr -d ' "') + if [ -z "$template" ]; then + warning "No template specified in $file" + return 0 + fi + + # Map template names to files + case "$template" in + "TEMPLATE.documentation-standard") + template_file="$TEMPLATES_DIR/TEMPLATE.documentation-standard.md" + ;; + "TEMPLATE.guide") + template_file="$TEMPLATES_DIR/TEMPLATE.guide.md" + ;; + "TEMPLATE.troubleshooting") + template_file="$TEMPLATES_DIR/TEMPLATE.troubleshooting.md" + ;; + "TEMPLATE.about") + template_file="$TEMPLATES_DIR/TEMPLATE.about.md" + ;; + "TEMPLATE.reference") + template_file="$TEMPLATES_DIR/TEMPLATE.reference.md" + ;; + "TEMPLATE.architecture") + template_file="$TEMPLATES_DIR/TEMPLATE.architecture.md" + ;; + "TEMPLATE.api") + template_file="$TEMPLATES_DIR/TEMPLATE.api.md" + ;; + "TEMPLATE.template") + template_file="$TEMPLATES_DIR/TEMPLATE.documentation-standard.md" + ;; + "TEMPLATE.custom") + template_file="$TEMPLATES_DIR/TEMPLATE.custom.md" + ;; + *) + error "Unknown template in $file: $template" + return 1 + ;; + esac + + if [ ! -f "$template_file" ]; then + error "Template file not found: $template_file" + return 1 + fi + + # Basic structure compliance check + local template_sections + local file_sections + + template_sections=$(grep "^## " "$template_file" | sed 's/^## //' | sort) + file_sections=$(grep "^## " "$file" | sed 's/^## //' | sort) + + # Check if file has all required sections from template + # Skip template compliance for custom documents and meta-documents + if [[ "$file" == *"ABOUT."* ]] || [[ "$template" == "TEMPLATE.custom" ]]; then + log "Skipping template compliance for custom/meta-document: $file" + else + while IFS= read -r section; do + if [ -n "$section" ]; then + if ! echo "$file_sections" | grep -q "^${section}$"; then + warning "Missing section '$section' in $file (required by template $template)" + fi + fi + done <<< "$template_sections" + fi + + return 0 +} + +# Check internal links +check_internal_links() { + local file="$1" + local broken_links=() + local link_pattern='\[([^\]]+)\]\(([^)]+)\)' + + while IFS= read -r line; do + if echo "$line" | grep -qE "$link_pattern"; then + # Extract link target + local link_target + link_target=$(echo "$line" | sed -E "s/.*$link_pattern.*/\2/") + + # Skip external links + if echo "$link_target" | grep -qE '^https?://'; then + continue + fi + + # Check if internal link exists + if [ ! -f "$link_target" ] && [ ! -f "$DOCS_DIR/$link_target" ]; then + broken_links+=("$link_target") + fi + fi + done < "$file" + + if [ ${#broken_links[@]} -gt 0 ]; then + error "Broken internal links in $file: ${broken_links[*]}" + return 1 + fi + + return 0 +} + +# Lint a single file +lint_file() { + local file="$1" + local file_passed=true + + log "Linting $file..." + + # Check YAML front matter + if ! check_yaml_front_matter "$file"; then + file_passed=false + fi + + # Validate YAML syntax + if ! validate_yaml_syntax "$file"; then + file_passed=false + fi + + # Check required fields + if ! check_required_fields "$file"; then + file_passed=false + fi + + # Validate field values + if ! validate_field_values "$file"; then + file_passed=false + fi + + # Check template compliance + if ! check_template_compliance "$file"; then + file_passed=false + fi + + # Check internal links + if ! check_internal_links "$file"; then + file_passed=false + fi + + if [ "$file_passed" = true ]; then + success "All checks passed for $file" + ((PASSED_FILES++)) + else + error "Some checks failed for $file" + fi + + ((TOTAL_FILES++)) +} + +# Main execution +main() { + log "Starting documentation linting..." + log "Log file: $LOG_FILE" + + # Find all markdown files in dev directory + local files + files=$(find "$DOCS_DIR" -name "*.md" -type f | sort) + + if [ -z "$files" ]; then + error "No markdown files found in $DOCS_DIR" + exit 1 + fi + + # Lint each file + while IFS= read -r file; do + if [ -f "$file" ]; then + lint_file "$file" + fi + done <<< "$files" + + # Summary + log "" + log "=== LINTING SUMMARY ===" + log "Total files: $TOTAL_FILES" + success "Passed: $PASSED_FILES" + if [ $FAILED_FILES -gt 0 ]; then + error "Failed: $FAILED_FILES" + fi + if [ $WARNINGS -gt 0 ]; then + warning "Warnings: $WARNINGS" + fi + + if [ $FAILED_FILES -eq 0 ]; then + success "All documentation files passed linting!" + exit 0 + else + error "Some documentation files failed linting. Check the log for details." + exit 1 + fi +} + +# Run main function +main "$@" diff --git a/scripts/documentation/lint-index.sh b/scripts/documentation/lint-index.sh new file mode 100755 index 0000000..96dfc5b --- /dev/null +++ b/scripts/documentation/lint-index.sh @@ -0,0 +1,148 @@ +#!/bin/bash + +# Sirius Documentation Index Completeness Linter +# Ensures all files in dev/ are referenced in the documentation index + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' + +# Configuration +DOCS_DIR="../../documentation/dev" +INDEX_FILE="../../documentation/README.documentation-index.md" +LOG_FILE="tmp/index-lint-$(date +%Y%m%d-%H%M%S).log" + +# Create tmp directory if it doesn't exist +mkdir -p tmp + +# Counters +TOTAL_FILES=0 +MISSING_FILES=0 +EXTRA_FILES=0 + +# Functions +log() { + echo -e "${BLUE}[$(date +'%H:%M:%S')]${NC} $1" | tee -a "$LOG_FILE" +} + +success() { + echo -e "${GREEN}✅ $1${NC}" | tee -a "$LOG_FILE" +} + +warning() { + echo -e "${YELLOW}⚠️ $1${NC}" | tee -a "$LOG_FILE" +} + +error() { + echo -e "${RED}❌ $1${NC}" | tee -a "$LOG_FILE" +} + +# Get all markdown files in dev directory +get_dev_files() { + find "$DOCS_DIR" -name "*.md" -type f | sed "s|^$DOCS_DIR/||" | sort +} + +# Get files referenced in index +get_indexed_files() { + grep -E "\[.*\]\(dev/.*\.md\)" "$INDEX_FILE" | grep -v "_This document follows" | sed 's/.*\[[^]]*\](dev\/\([^)]*\))/\1/' | sed 's/ - .*$//' | sed 's/^[[:space:]]*//' | sed 's/[[:space:]]*$//' | sort | uniq +} + +# Check if file is in index +check_file_in_index() { + local file="$1" + local indexed_files="$2" + + if echo "$indexed_files" | grep -q "^${file}$"; then + return 0 + else + return 1 + fi +} + +# Check if indexed file exists +check_indexed_file_exists() { + local indexed_file="$1" + local dev_files="$2" + + if echo "$dev_files" | grep -q "^${indexed_file}$"; then + return 0 + else + return 1 + fi +} + +# Main linting function +lint_index() { + log "Starting index completeness linting..." + log "Log file: $LOG_FILE" + + # Get file lists + local dev_files + local indexed_files + + dev_files=$(get_dev_files) + indexed_files=$(get_indexed_files) + + log "Found $(echo "$dev_files" | wc -l) files in dev directory" + log "Found $(echo "$indexed_files" | wc -l) files referenced in index" + + # Check for missing files (in dev but not in index) + log "" + log "Checking for files missing from index..." + + while IFS= read -r file; do + if [ -n "$file" ]; then + TOTAL_FILES=$((TOTAL_FILES + 1)) + if ! check_file_in_index "$file" "$indexed_files"; then + error "File missing from index: $file" + MISSING_FILES=$((MISSING_FILES + 1)) + else + success "File properly indexed: $file" + fi + fi + done <<< "$dev_files" + + # Check for extra files (in index but not in dev) + log "" + log "Checking for extra files in index..." + + while IFS= read -r indexed_file; do + if [ -n "$indexed_file" ]; then + if ! check_indexed_file_exists "$indexed_file" "$dev_files"; then + warning "File in index but not found in dev: $indexed_file" + EXTRA_FILES=$((EXTRA_FILES + 1)) + fi + fi + done <<< "$indexed_files" + + # Summary + log "" + log "=== INDEX LINTING SUMMARY ===" + log "Total dev files: $TOTAL_FILES" + if [ $MISSING_FILES -gt 0 ]; then + error "Missing from index: $MISSING_FILES" + else + success "All dev files are indexed" + fi + if [ $EXTRA_FILES -gt 0 ]; then + warning "Extra files in index: $EXTRA_FILES" + else + success "No extra files in index" + fi + + if [ $MISSING_FILES -eq 0 ] && [ $EXTRA_FILES -eq 0 ]; then + success "Index is complete and accurate!" + exit 0 + else + error "Index has issues. Check the log for details." + exit 1 + fi +} + +# Run main function +lint_index "$@" diff --git a/scripts/documentation/lint-quick.sh b/scripts/documentation/lint-quick.sh new file mode 100755 index 0000000..d2cb1fb --- /dev/null +++ b/scripts/documentation/lint-quick.sh @@ -0,0 +1,83 @@ +#!/bin/bash + +# Quick documentation linting for development +# Faster, less comprehensive checks + +set -e + +# Colors +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' + +DOCS_DIR="../../documentation/dev" + +# Quick checks +quick_check() { + local file="$1" + local issues=0 + + # Check if file has YAML front matter + if ! head -n 1 "$file" | grep -q "^---$"; then + echo -e "${RED}❌ $file: Missing YAML front matter${NC}" + issues=$((issues + 1)) + fi + + # Check if file has title field + if ! grep -q "^title:" "$file"; then + echo -e "${RED}❌ $file: Missing title field${NC}" + issues=$((issues + 1)) + fi + + # Check if file has description field + if ! grep -q "^description:" "$file"; then + echo -e "${RED}❌ $file: Missing description field${NC}" + issues=$((issues + 1)) + fi + + # Check if file has template field + if ! grep -q "^template:" "$file"; then + echo -e "${RED}❌ $file: Missing template field${NC}" + issues=$((issues + 1)) + fi + + if [ $issues -eq 0 ]; then + echo -e "${GREEN}✅ $file: Quick checks passed${NC}" + fi + + return $issues +} + +# Main execution +main() { + echo -e "${BLUE}📚 Running quick documentation checks...${NC}" + + local total_issues=0 + local total_files=0 + + # Find all markdown files in dev directory + while IFS= read -r -d '' file; do + total_files=$((total_files + 1)) + if ! quick_check "$file"; then + total_issues=$((total_issues + 1)) + fi + done < <(find "$DOCS_DIR" -name "*.md" -type f -print0) + + echo "" + echo -e "${BLUE}📊 Quick Check Summary:${NC}" + echo -e " Files checked: $total_files" + echo -e " Files with issues: $total_issues" + + if [ $total_issues -eq 0 ]; then + echo -e "${GREEN}✅ All quick checks passed!${NC}" + exit 0 + else + echo -e "${RED}❌ $total_issues files have issues${NC}" + exit 1 + fi +} + +# Run main function +main "$@" \ No newline at end of file diff --git a/scripts/git-hooks/pre-commit b/scripts/git-hooks/pre-commit new file mode 100755 index 0000000..745ef6b --- /dev/null +++ b/scripts/git-hooks/pre-commit @@ -0,0 +1,57 @@ +#!/bin/bash + +# Pre-commit hook to automatically comment out volume mounts in docker-compose.override.yaml +# This prevents accidental commits of local development configuration + +echo "🔍 Checking docker-compose.override.yaml for uncommented volume mounts..." + +OVERRIDE_FILE="docker-compose.override.yaml" + +if [ ! -f "$OVERRIDE_FILE" ]; then + exit 0 +fi + +# Check if there are any uncommented volume mounts +if grep -E "^\s*-\s+\.\./minor-projects/" "$OVERRIDE_FILE" > /dev/null; then + echo "⚠️ Found uncommented volume mounts in $OVERRIDE_FILE" + echo "🔧 Automatically commenting them out..." + + # Create backup + cp "$OVERRIDE_FILE" "${OVERRIDE_FILE}.backup" + + # Comment out the volume mounts + sed -i.tmp 's/^\(\s*\)-\s\+\.\./\1# - \.\./' "$OVERRIDE_FILE" + rm "${OVERRIDE_FILE}.tmp" 2>/dev/null || true + + # Re-stage the fixed file + git add "$OVERRIDE_FILE" + + echo "✅ Volume mounts have been commented out automatically" + echo "💡 Your local copy has been backed up to ${OVERRIDE_FILE}.backup" + echo "💡 Use docker-compose.local.yaml for local development overrides" + echo "" +fi + +# Check for modified agent identity files +echo "" +echo "🤖 Checking modified agent identity files..." + +AGENTS_DIR=".cursor/agents" +MODIFIED_AGENTS=$(git diff --cached --name-only --diff-filter=ACM | grep "^${AGENTS_DIR}/.*\.agent\.md$" || true) + +if [ -n "$MODIFIED_AGENTS" ]; then + echo "📝 Found modified agent files, running quick validation..." + + if ! bash scripts/agent-identities/lint-agents-quick.sh > /dev/null 2>&1; then + echo "❌ Agent identity validation failed!" + echo "💡 Run 'cd testing/container-testing && make lint-agents' for detailed errors" + exit 1 + fi + + echo "✅ Agent identity validation passed" +else + echo "ℹ️ No agent identity files modified" +fi + +echo "" +echo "✅ Pre-commit validation passed" \ No newline at end of file diff --git a/scripts/git-hooks/pre-commit-modernized b/scripts/git-hooks/pre-commit-modernized new file mode 100644 index 0000000..3eeaf7e --- /dev/null +++ b/scripts/git-hooks/pre-commit-modernized @@ -0,0 +1,125 @@ +#!/bin/bash + +# Modernized pre-commit hook for Sirius +# Performs quick validation only - full testing moved to CI + +echo "🔍 Running quick pre-commit validation..." + +# Check if we're in the right directory +if [ ! -f "docker-compose.yaml" ]; then + echo "❌ Not in Sirius project root directory" + exit 1 +fi + +# 1. Docker Compose Configuration Validation +echo "🐳 Validating Docker Compose configurations..." +if ! docker compose config --quiet; then + echo "❌ Base Docker Compose configuration is invalid" + exit 1 +fi + +if ! docker compose -f docker-compose.yaml -f docker-compose.dev.yaml config --quiet; then + echo "❌ Development Docker Compose configuration is invalid" + exit 1 +fi + +if ! docker compose -f docker-compose.yaml -f docker-compose.prod.yaml config --quiet; then + echo "❌ Production Docker Compose configuration is invalid" + exit 1 +fi + +echo "✅ All Docker Compose configurations are valid" + +# 2. Quick Documentation Validation +echo "📚 Running quick documentation checks..." +if [ -d "testing/container-testing" ]; then + cd testing/container-testing + if ! make lint-docs-quick; then + echo "❌ Documentation validation failed" + exit 1 + fi + if ! make lint-index; then + echo "❌ Documentation index validation failed" + exit 1 + fi + cd ../.. +else + echo "⚠️ Testing directory not found, skipping documentation validation" +fi + +echo "✅ Documentation validation passed" + +# 3. Check for uncommented volume mounts in docker-compose.override.yaml +echo "🔍 Checking for uncommented volume mounts..." +OVERRIDE_FILE="docker-compose.override.yaml" + +if [ -f "$OVERRIDE_FILE" ]; then + if grep -E "^\s*-\s+\.\./minor-projects/" "$OVERRIDE_FILE" > /dev/null; then + echo "⚠️ Found uncommented volume mounts in $OVERRIDE_FILE" + echo "🔧 Automatically commenting them out..." + + # Create backup + cp "$OVERRIDE_FILE" "${OVERRIDE_FILE}.backup" + + # Comment out the volume mounts + sed -i.tmp 's/^\(\s*\)-\s\+\.\./\1# - \.\./' "$OVERRIDE_FILE" + rm "${OVERRIDE_FILE}.tmp" 2>/dev/null || true + + # Re-stage the fixed file + git add "$OVERRIDE_FILE" + + echo "✅ Volume mounts have been commented out automatically" + echo "💡 Your local copy has been backed up to ${OVERRIDE_FILE}.backup" + echo "💡 Use docker-compose.local.yaml for local development overrides" + fi +fi + +# 4. Check for accidentally committed local files +echo "🔍 Checking for accidentally committed local files..." +if [ -f "docker-compose.local.yaml" ]; then + echo "❌ docker-compose.local.yaml should not be committed" + echo "💡 This file is for local development only and should be git-ignored" + exit 1 +fi + +if ls docker-compose.*.local.yaml 2>/dev/null; then + echo "❌ 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" + +# 5. Basic syntax checks for key files +echo "🔍 Running basic syntax checks..." + +# Check if package.json is valid JSON +if [ -f "sirius-ui/package.json" ]; then + if ! python3 -m json.tool sirius-ui/package.json > /dev/null 2>&1; then + echo "❌ sirius-ui/package.json is not valid JSON" + exit 1 + fi +fi + +# Check if go.mod is valid +if [ -f "sirius-api/go.mod" ]; then + if ! go mod verify -modfile=sirius-api/go.mod > /dev/null 2>&1; then + echo "❌ sirius-api/go.mod is not valid" + exit 1 + fi +fi + +if [ -f "sirius-engine/go.mod" ]; then + if ! go mod verify -modfile=sirius-engine/go.mod > /dev/null 2>&1; then + echo "❌ sirius-engine/go.mod is not valid" + exit 1 + fi +fi + +echo "✅ Basic syntax checks passed" + +echo "" +echo "🎉 Pre-commit validation completed successfully!" +echo "💡 Full testing will run in CI/CD pipeline" +echo "💡 For local testing, run: cd testing/container-testing && make test-all" diff --git a/scripts/performance-test-suite.sh b/scripts/performance-test-suite.sh new file mode 100644 index 0000000..0519ecb --- /dev/null +++ b/scripts/performance-test-suite.sh @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/scripts/prepare-monitoring.sh b/scripts/prepare-monitoring.sh new file mode 100644 index 0000000..5f285b5 --- /dev/null +++ b/scripts/prepare-monitoring.sh @@ -0,0 +1,48 @@ +#!/bin/bash + +# Script to prepare monitoring components for container builds +# This script validates that the main SystemMonitor project is available + +set -e + +echo "🔧 Preparing monitoring components for container builds..." + +# Get the directory of this script +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" + +# Paths to the monitoring components +SYSTEM_MONITOR_DIR="$PROJECT_ROOT/../minor-projects/app-system-monitor" + +# Check if main system monitor directory exists +if [ ! -d "$SYSTEM_MONITOR_DIR" ]; then + echo "❌ System monitor directory not found: $SYSTEM_MONITOR_DIR" + exit 1 +fi + +# Validate that the main system monitor has the required files +echo "📊 Validating main system monitor project..." + +if [ ! -f "$SYSTEM_MONITOR_DIR/main.go" ]; then + echo "❌ System monitor main.go not found" + exit 1 +fi + +if [ ! -f "$SYSTEM_MONITOR_DIR/go.mod" ]; then + echo "❌ System monitor go.mod not found" + exit 1 +fi + +# Test build the system monitor to ensure it compiles +echo "🔨 Testing system monitor build..." +cd "$SYSTEM_MONITOR_DIR" +if go build -o /tmp/test-system-monitor .; then + echo "✅ System monitor builds successfully" + rm -f /tmp/test-system-monitor +else + echo "❌ System monitor build failed" + exit 1 +fi + +echo "✅ Main system monitor project is ready for container builds!" +echo "📝 Note: Containers will now build SystemMonitor from the main project instead of local copies" diff --git a/scripts/switch-env.sh b/scripts/switch-env.sh new file mode 100755 index 0000000..c1b7e69 --- /dev/null +++ b/scripts/switch-env.sh @@ -0,0 +1,109 @@ +#!/bin/bash + +# Sirius Environment Switching Script +# Usage: ./scripts/switch-env.sh [dev|prod|base] + +set -e + +ENV=${1:-"base"} +PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +INSTALLER_COMPOSE_FILE="$PROJECT_ROOT/docker-compose.installer.yaml" +ENV_FILE="$PROJECT_ROOT/.env" + +require_env_file() { + if [ -f "$ENV_FILE" ]; then + return 0 + fi + + echo "⚠️ Missing $ENV_FILE" + if [ "${SIRIUS_AUTO_SETUP:-0}" = "1" ]; then + echo "🔧 SIRIUS_AUTO_SETUP=1 detected; running installer container..." + docker compose -f "$INSTALLER_COMPOSE_FILE" run --rm sirius-installer --non-interactive --no-print-secrets + return 0 + fi + + echo "Run installer first:" + echo " docker compose -f docker-compose.installer.yaml run --rm sirius-installer" + echo "Or rerun with SIRIUS_AUTO_SETUP=1 to auto-generate missing values." + exit 1 +} + +echo "🔄 Switching Sirius environment to: $ENV" + +# Function to clean up containers and images +cleanup() { + echo "🧹 Cleaning up existing containers and images..." + docker compose down 2>/dev/null || true + docker compose -f docker-compose.yaml -f docker-compose.dev.yaml down 2>/dev/null || true + docker compose -f docker-compose.yaml -f docker-compose.prod.yaml down 2>/dev/null || true + + # Remove old UI images to force rebuild + docker rmi sirius-sirius-ui:latest 2>/dev/null || true + docker rmi sirius-sirius-ui:dev 2>/dev/null || true + docker rmi sirius-sirius-ui:prod 2>/dev/null || true +} + +# Function to start development environment +start_dev() { + echo "🚀 Starting development environment..." + docker compose -f docker-compose.yaml -f docker-compose.dev.yaml build --no-cache sirius-ui + docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d + echo "✅ Development environment started!" + echo "🌐 UI: http://localhost:3000 (with hot reloading)" + echo "🔧 API: http://localhost:9001" +} + +# Function to start production environment +start_prod() { + echo "🚀 Starting production environment..." + docker compose -f docker-compose.yaml -f docker-compose.prod.yaml build --no-cache sirius-ui + docker compose -f docker-compose.yaml -f docker-compose.prod.yaml up -d + echo "✅ Production environment started!" + echo "🌐 UI: http://localhost:3000 (optimized build)" + echo "🔧 API: http://localhost:9001" +} + +# Function to start base environment +start_base() { + echo "🚀 Starting base environment..." + docker compose build --no-cache sirius-ui + docker compose up -d + echo "✅ Base environment started!" + echo "🌐 UI: http://localhost:3000" + echo "🔧 API: http://localhost:9001" +} + +# Main logic +cd "$PROJECT_ROOT" + +case $ENV in + "dev"|"development") + require_env_file + cleanup + start_dev + ;; + "prod"|"production") + require_env_file + cleanup + start_prod + ;; + "base"|"default") + require_env_file + cleanup + start_base + ;; + *) + echo "❌ Invalid environment: $ENV" + echo "Usage: $0 [dev|prod|base]" + echo "" + echo "Environments:" + echo " dev - Development with hot reloading and volume mounts" + echo " prod - Production with optimized builds" + echo " base - Base configuration (default)" + exit 1 + ;; +esac + +echo "" +echo "📊 Container status:" +docker compose ps diff --git a/scripts/test-e2e-suite.sh b/scripts/test-e2e-suite.sh new file mode 100755 index 0000000..aee51e9 --- /dev/null +++ b/scripts/test-e2e-suite.sh @@ -0,0 +1,416 @@ +#!/bin/bash + +# ============================================================================ +# Sirius E2E Test Suite +# +# Comprehensive end-to-end testing for source attribution functionality +# Tests complete workflows across all scanner types and frontend integration +# ============================================================================ + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Test configuration +API_BASE_URL="${API_BASE_URL:-http://localhost:9001}" +UI_BASE_URL="${UI_BASE_URL:-http://localhost:3000}" +TEST_HOST_IP="192.168.1.100" +TEST_HOST_IP_2="192.168.1.101" +TEST_TIMESTAMP=$(date +%s) +RESULTS_DIR="test-results-e2e-${TEST_TIMESTAMP}" + +# Create test results directory +mkdir -p "${RESULTS_DIR}" + +echo -e "${BLUE}🚀 Starting Sirius E2E Test Suite${NC}" +echo -e "${BLUE}================================================${NC}" +echo -e "API Base URL: ${API_BASE_URL}" +echo -e "UI Base URL: ${UI_BASE_URL}" +echo -e "Results Directory: ${RESULTS_DIR}" +echo "" + +# Test counters +TESTS_TOTAL=0 +TESTS_PASSED=0 +TESTS_FAILED=0 + +# Function to run a test +run_test() { + local test_name="$1" + local test_function="$2" + + TESTS_TOTAL=$((TESTS_TOTAL + 1)) + echo -e "${YELLOW}📋 Test ${TESTS_TOTAL}: ${test_name}${NC}" + + if $test_function; then + echo -e "${GREEN}✅ PASS: ${test_name}${NC}" + TESTS_PASSED=$((TESTS_PASSED + 1)) + echo "PASS" > "${RESULTS_DIR}/test_${TESTS_TOTAL}_$(echo ${test_name} | tr ' ' '_').result" + else + echo -e "${RED}❌ FAIL: ${test_name}${NC}" + TESTS_FAILED=$((TESTS_FAILED + 1)) + echo "FAIL" > "${RESULTS_DIR}/test_${TESTS_TOTAL}_$(echo ${test_name} | tr ' ' '_').result" + fi + echo "" +} + +# Function to cleanup test data +cleanup_test_data() { + echo -e "${YELLOW}🧹 Cleaning up test data...${NC}" + + # Clean up test hosts + curl -s -X DELETE "${API_BASE_URL}/host/${TEST_HOST_IP}" || true + curl -s -X DELETE "${API_BASE_URL}/host/${TEST_HOST_IP_2}" || true + + # Additional cleanup as needed + sleep 2 +} + +# Function to check service availability +check_services() { + echo -e "${BLUE}🔍 Checking service availability...${NC}" + + # Check API service + if ! curl -s --max-time 10 "${API_BASE_URL}/health" > /dev/null 2>&1; then + echo -e "${RED}❌ API service not available at ${API_BASE_URL}${NC}" + exit 1 + fi + + # Check UI service (optional) + if ! curl -s --max-time 10 "${UI_BASE_URL}" > /dev/null 2>&1; then + echo -e "${YELLOW}⚠️ UI service not available at ${UI_BASE_URL} (continuing with API tests)${NC}" + fi + + echo -e "${GREEN}✅ Services are available${NC}" + echo "" +} + +# ============================================================================ +# Test Functions +# ============================================================================ + +# Test 1: Basic API Connectivity +test_api_connectivity() { + local response=$(curl -s -w "%{http_code}" "${API_BASE_URL}/health") + local http_code="${response: -3}" + + if [[ "$http_code" == "200" ]]; then + return 0 + else + echo "HTTP Status: $http_code" + return 1 + fi +} + +# Test 2: Legacy Host Submission (Backward Compatibility) +test_legacy_host_submission() { + local payload='{ + "hid": "e2e-test-legacy", + "os": "Ubuntu", + "osversion": "22.04", + "ip": "'${TEST_HOST_IP}'", + "hostname": "test-host-legacy", + "ports": [{"id": 22, "protocol": "tcp", "state": "open"}], + "vulnerabilities": [{"vid": "CVE-2023-E2E-LEGACY", "description": "E2E Test Legacy Vulnerability", "title": "Legacy Test CVE"}] + }' + + local response=$(curl -s -w "%{http_code}" -X POST \ + -H "Content-Type: application/json" \ + -d "$payload" \ + "${API_BASE_URL}/host") + + local http_code="${response: -3}" + + if [[ "$http_code" == "200" ]]; then + echo "Legacy host submission successful" + return 0 + else + echo "HTTP Status: $http_code" + echo "Response: ${response%???}" + return 1 + fi +} + +# Test 3: Source-Aware Network Scanner Submission +test_network_scanner_submission() { + local payload='{ + "hid": "e2e-test-nmap", + "os": "Linux", + "osversion": "Ubuntu 22.04", + "ip": "'${TEST_HOST_IP}'", + "hostname": "test-host-nmap", + "ports": [ + {"id": 80, "protocol": "tcp", "state": "open"}, + {"id": 443, "protocol": "tcp", "state": "open"} + ], + "vulnerabilities": [ + { + "vid": "CVE-2023-E2E-NMAP", + "description": "E2E Test Network Vulnerability", + "title": "Network Scanner Test CVE" + } + ] + }' + + local response=$(curl -s -w "%{http_code}" -X POST \ + -H "Content-Type: application/json" \ + -H "User-Agent: nmap-scanner/7.94" \ + -H "X-Scanner-Name: nmap" \ + -H "X-Scanner-Version: 7.94" \ + -d "$payload" \ + "${API_BASE_URL}/host") + + local http_code="${response: -3}" + + if [[ "$http_code" == "200" ]]; then + echo "Network scanner submission successful" + return 0 + else + echo "HTTP Status: $http_code" + echo "Response: ${response%???}" + return 1 + fi +} + +# Test 4: Source-Aware Agent Submission +test_agent_submission() { + local payload='{ + "hid": "e2e-test-agent", + "os": "Windows", + "osversion": "Server 2019", + "ip": "'${TEST_HOST_IP}'", + "hostname": "test-host-agent", + "vulnerabilities": [ + { + "vid": "CVE-2023-E2E-AGENT", + "description": "E2E Test Agent Vulnerability", + "title": "Agent Scanner Test CVE" + } + ], + "users": ["testuser1", "testuser2"] + }' + + local response=$(curl -s -w "%{http_code}" -X POST \ + -H "Content-Type: application/json" \ + -H "User-Agent: sirius-agent/1.0.0" \ + -H "X-Scanner-Name: agent" \ + -H "X-Scanner-Version: 1.0.0" \ + -d "$payload" \ + "${API_BASE_URL}/host") + + local http_code="${response: -3}" + + if [[ "$http_code" == "200" ]]; then + echo "Agent submission successful" + return 0 + else + echo "HTTP Status: $http_code" + echo "Response: ${response%???}" + return 1 + fi +} + +# Test 5: Multi-Source Data Integrity +test_multi_source_integrity() { + # First, submit via network scanner + test_network_scanner_submission > /dev/null 2>&1 + + # Then submit via agent (should merge, not replace) + test_agent_submission > /dev/null 2>&1 + + # Verify both sources are preserved + local response=$(curl -s "${API_BASE_URL}/host/${TEST_HOST_IP}/sources") + + if echo "$response" | grep -q "nmap" && echo "$response" | grep -q "agent"; then + echo "Multi-source data integrity verified" + return 0 + else + echo "Multi-source verification failed" + echo "Response: $response" + return 1 + fi +} + +# Test 6: Source Attribution API Endpoints +test_source_attribution_endpoints() { + # Test host sources endpoint + local sources_response=$(curl -s "${API_BASE_URL}/host/${TEST_HOST_IP}/sources") + if ! echo "$sources_response" | grep -q "sources"; then + echo "Host sources endpoint failed" + return 1 + fi + + # Test host history endpoint + local history_response=$(curl -s "${API_BASE_URL}/host/${TEST_HOST_IP}/history") + if ! echo "$history_response" | grep -q "history"; then + echo "Host history endpoint failed" + return 1 + fi + + # Test source coverage endpoint + local coverage_response=$(curl -s "${API_BASE_URL}/host/source-coverage") + if ! echo "$coverage_response" | grep -q "coverage"; then + echo "Source coverage endpoint failed" + return 1 + fi + + echo "All source attribution endpoints working" + return 0 +} + +# Test 7: Database Consistency Check +test_database_consistency() { + # Get host data and verify structure + local host_response=$(curl -s "${API_BASE_URL}/host/${TEST_HOST_IP}") + + # Check if response contains expected fields + if echo "$host_response" | grep -q "ip" && \ + echo "$host_response" | grep -q "vulnerabilities" && \ + echo "$host_response" | grep -q "ports"; then + echo "Database consistency verified" + return 0 + else + echo "Database consistency check failed" + echo "Response: $host_response" + return 1 + fi +} + +# Test 8: Performance Baseline Test +test_performance_baseline() { + local start_time=$(date +%s%N) + + # Perform a standard API call + curl -s "${API_BASE_URL}/host" > /dev/null + + local end_time=$(date +%s%N) + local duration=$(((end_time - start_time) / 1000000)) # Convert to milliseconds + + # Check if response time is reasonable (< 2000ms) + if [[ $duration -lt 2000 ]]; then + echo "Performance baseline met: ${duration}ms" + return 0 + else + echo "Performance baseline failed: ${duration}ms (should be < 2000ms)" + return 1 + fi +} + +# Test 9: Vulnerability Data Format Validation +test_vulnerability_data_format() { + local response=$(curl -s "${API_BASE_URL}/host/${TEST_HOST_IP}/sources") + + # Check if vulnerability data has required fields + if echo "$response" | grep -q "vid" && \ + echo "$response" | grep -q "description" && \ + echo "$response" | grep -q "sources"; then + echo "Vulnerability data format validated" + return 0 + else + echo "Vulnerability data format validation failed" + echo "Response: $response" + return 1 + fi +} + +# Test 10: Cross-Scanner Compatibility +test_cross_scanner_compatibility() { + # Test with different scanner types on same host + local rustscan_payload='{ + "hid": "e2e-test-rustscan", + "ip": "'${TEST_HOST_IP_2}'", + "hostname": "test-host-rustscan", + "ports": [{"id": 8080, "protocol": "tcp", "state": "open"}] + }' + + local naabu_payload='{ + "hid": "e2e-test-naabu", + "ip": "'${TEST_HOST_IP_2}'", + "hostname": "test-host-naabu", + "ports": [{"id": 9090, "protocol": "tcp", "state": "open"}] + }' + + # Submit via rustscan + curl -s -X POST \ + -H "Content-Type: application/json" \ + -H "User-Agent: rustscan/2.1.1" \ + -H "X-Scanner-Name: rustscan" \ + -d "$rustscan_payload" \ + "${API_BASE_URL}/host" > /dev/null + + # Submit via naabu + curl -s -X POST \ + -H "Content-Type: application/json" \ + -H "User-Agent: naabu/2.1.9" \ + -H "X-Scanner-Name: naabu" \ + -d "$naabu_payload" \ + "${API_BASE_URL}/host" > /dev/null + + # Verify both scanners are tracked + local response=$(curl -s "${API_BASE_URL}/host/${TEST_HOST_IP_2}/sources") + + if echo "$response" | grep -q "rustscan" && echo "$response" | grep -q "naabu"; then + echo "Cross-scanner compatibility verified" + return 0 + else + echo "Cross-scanner compatibility failed" + echo "Response: $response" + return 1 + fi +} + +# ============================================================================ +# Main Test Execution +# ============================================================================ + +main() { + echo -e "${BLUE}Starting E2E Test Suite Execution${NC}" + echo "" + + # Check service availability + check_services + + # Clean up any previous test data + cleanup_test_data + + # Run all tests + run_test "API Connectivity" test_api_connectivity + run_test "Legacy Host Submission" test_legacy_host_submission + run_test "Network Scanner Submission" test_network_scanner_submission + run_test "Agent Submission" test_agent_submission + run_test "Multi-Source Data Integrity" test_multi_source_integrity + run_test "Source Attribution Endpoints" test_source_attribution_endpoints + run_test "Database Consistency" test_database_consistency + run_test "Performance Baseline" test_performance_baseline + run_test "Vulnerability Data Format" test_vulnerability_data_format + run_test "Cross-Scanner Compatibility" test_cross_scanner_compatibility + + # Clean up test data + cleanup_test_data + + # Display results + echo -e "${BLUE}================================================${NC}" + echo -e "${BLUE}📊 E2E Test Suite Results${NC}" + echo -e "${BLUE}================================================${NC}" + echo -e "Total Tests: ${TESTS_TOTAL}" + echo -e "${GREEN}Passed: ${TESTS_PASSED}${NC}" + echo -e "${RED}Failed: ${TESTS_FAILED}${NC}" + + if [[ $TESTS_FAILED -eq 0 ]]; then + echo -e "${GREEN}🎉 All tests passed! System is ready for production.${NC}" + echo "PASS" > "${RESULTS_DIR}/e2e_suite_result.txt" + exit 0 + else + echo -e "${RED}❌ Some tests failed. Please review and fix issues.${NC}" + echo "FAIL" > "${RESULTS_DIR}/e2e_suite_result.txt" + exit 1 + fi +} + +# Run main function +main "$@" \ No newline at end of file diff --git a/scripts/test-full-build.sh b/scripts/test-full-build.sh new file mode 100755 index 0000000..4763e16 --- /dev/null +++ b/scripts/test-full-build.sh @@ -0,0 +1,37 @@ +#!/bin/bash + +# Sirius Full Build Test Script +# Runs complete build tests including Docker builds +# Use this when you want to test full builds on feature branches + +set -e + +# Colors +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' + +echo -e "${BLUE}🔨 Running full build tests...${NC}" + +# Check if we're in the right directory +if [ ! -f "testing/container-testing/Makefile" ]; then + echo -e "${RED}❌ Not in Sirius project root${NC}" + echo -e "${YELLOW}💡 Run this script from the project root directory${NC}" + exit 1 +fi + +# Change to container testing directory +cd testing/container-testing + +# Run full build tests +echo -e "${BLUE}🧪 Running complete build test suite...${NC}" +if make test-build; then + echo -e "${GREEN}✅ Full build tests passed!${NC}" + echo -e "${YELLOW}💡 All Docker images built successfully${NC}" +else + echo -e "${RED}❌ Full build tests failed${NC}" + echo -e "${YELLOW}💡 Check the output above for specific errors${NC}" + exit 1 +fi diff --git a/scripts/test-phase1-cleanup.sh b/scripts/test-phase1-cleanup.sh new file mode 100755 index 0000000..7a30a66 --- /dev/null +++ b/scripts/test-phase1-cleanup.sh @@ -0,0 +1,139 @@ +#!/bin/bash + +# Test Cleanup Script for Phase 1 Validation +# This script removes test data and test scripts after validation +# RUN THIS SCRIPT after Phase 1 testing is complete + +set -e + +API_BASE="http://localhost:9001" +echo "🧹 Starting Phase 1 Test Cleanup..." +echo "API Base: $API_BASE" +echo "" + +# Color codes for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Function to make DELETE API calls +delete_host() { + local ip=$1 + local description=$2 + + echo "🗑️ $description" + response=$(curl -s -w "\n%{http_code}" -X DELETE "$API_BASE/host/$ip") + + # Extract HTTP code + http_code=$(echo "$response" | tail -n1) + response_body=$(echo "$response" | head -n -1) + + if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then + echo -e " ${GREEN}✅ Deleted ($http_code)${NC}" + else + echo -e " ${YELLOW}⚠️ May not exist or already deleted ($http_code)${NC}" + fi + echo "" +} + +echo "🗑️ CLEANING UP TEST DATA" +echo "========================" + +# Remove all test hosts +delete_host "192.168.1.100" "Removing multi-source test host" +delete_host "192.168.1.200" "Removing temporal tracking test host" +delete_host "192.168.1.300" "Removing backward compatibility test host" +delete_host "192.168.1.400" "Removing multi-source CVE test host" +delete_host "192.168.1.500" "Removing port attribution test host" + +# Alternative: If there's a bulk delete endpoint +echo "🧹 Attempting bulk cleanup (if supported)..." +bulk_response=$(curl -s -w "\n%{http_code}" -X POST "$API_BASE/hosts/bulk-delete" \ + -H "Content-Type: application/json" \ + -d '{"ips": ["192.168.1.100", "192.168.1.200", "192.168.1.300", "192.168.1.400", "192.168.1.500"]}' 2>/dev/null || echo "not_supported\n404") + +bulk_code=$(echo "$bulk_response" | tail -n1) +if [ "$bulk_code" = "200" ] || [ "$bulk_code" = "204" ]; then + echo -e "${GREEN}✅ Bulk cleanup successful${NC}" +else + echo -e "${YELLOW}⚠️ Bulk cleanup not supported, individual deletes used${NC}" +fi +echo "" + +echo "📋 VERIFYING CLEANUP" +echo "===================" + +# Verify hosts are gone +echo "🔍 Checking if test hosts were removed..." +for ip in "192.168.1.100" "192.168.1.200" "192.168.1.300" "192.168.1.400" "192.168.1.500"; do + check_response=$(curl -s -w "%{http_code}" "$API_BASE/host/$ip" -o /dev/null) + if [ "$check_response" = "404" ]; then + echo -e " ${GREEN}✅ $ip - Successfully removed${NC}" + else + echo -e " ${YELLOW}⚠️ $ip - Still exists (code: $check_response)${NC}" + fi +done +echo "" + +echo "🗂️ CLEANING UP TEST SCRIPTS" +echo "============================" + +# Get the directory where this script is located +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +# Remove test scripts +if [ -f "$SCRIPT_DIR/test-phase1-populate.sh" ]; then + rm "$SCRIPT_DIR/test-phase1-populate.sh" + echo -e "${GREEN}✅ Removed test-phase1-populate.sh${NC}" +else + echo -e "${YELLOW}⚠️ test-phase1-populate.sh not found${NC}" +fi + +if [ -f "$SCRIPT_DIR/test-phase1-verify.sh" ]; then + rm "$SCRIPT_DIR/test-phase1-verify.sh" + echo -e "${GREEN}✅ Removed test-phase1-verify.sh${NC}" +else + echo -e "${YELLOW}⚠️ test-phase1-verify.sh not found${NC}" +fi + +echo "" +echo "🔄 OPTIONAL: Database Cleanup" +echo "=============================" +echo "If you want to completely reset the database for testing:" +echo "" +echo "Option 1 - Reset specific test data (if supported by API):" +echo " curl -X POST $API_BASE/admin/reset-test-data" +echo "" +echo "Option 2 - Full database reset (CAUTION - removes ALL data):" +echo " docker-compose down" +echo " docker volume rm \$(docker volume ls -q | grep postgres)" +echo " docker-compose up -d" +echo "" +echo "Option 3 - Truncate test tables only:" +if command -v psql &> /dev/null; then + echo " psql -h localhost -U postgres -d sirius -c \"DELETE FROM host_vulnerabilities WHERE host_id IN (SELECT id FROM hosts WHERE ip LIKE '192.168.1.%');\"" + echo " psql -h localhost -U postgres -d sirius -c \"DELETE FROM hosts WHERE ip LIKE '192.168.1.%';\"" +else + echo " (psql not available - use database admin tool)" +fi + +echo "" +echo -e "${GREEN}🎉 CLEANUP COMPLETED!${NC}" +echo "" +echo "📝 Summary:" +echo " • Test data removed from API" +echo " • Test scripts deleted" +echo " • System ready for production use" +echo "" +echo "🔄 Next Steps:" +echo " • Proceed to Phase 2 implementation" +echo " • Begin scanner integration work" +echo " • Update task status to completed" + +# Self-destruct this cleanup script +echo "" +echo "🔥 Self-destructing cleanup script..." +rm "$0" +echo -e "${GREEN}✅ Cleanup script removed${NC}" \ No newline at end of file diff --git a/scripts/test-phase1-populate.sh b/scripts/test-phase1-populate.sh new file mode 100755 index 0000000..2e710d3 --- /dev/null +++ b/scripts/test-phase1-populate.sh @@ -0,0 +1,287 @@ +#!/bin/bash + +# Test Data Population Script for Phase 1 Validation +# This script populates test data to validate source-aware functionality +# DELETE THIS SCRIPT after Phase 1 testing is complete + +set -e + +API_BASE="http://localhost:9001" +echo "🧪 Starting Phase 1 Test Data Population..." +echo "API Base: $API_BASE" +echo "" + +# Function to make API calls with error handling +make_api_call() { + local method=$1 + local endpoint=$2 + local data=$3 + local description=$4 + + echo "📡 $description" + echo " Method: $method" + echo " Endpoint: $endpoint" + + if [ "$method" = "POST" ]; then + response=$(curl -s -w "\n%{http_code}" -X POST "$API_BASE$endpoint" \ + -H "Content-Type: application/json" \ + -d "$data") + else + response=$(curl -s -w "\n%{http_code}" "$API_BASE$endpoint") + fi + + # Extract response body and HTTP code + http_code=$(echo "$response" | tail -n1) + response_body=$(echo "$response" | sed '$d') + + if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then + echo " ✅ Success ($http_code)" + echo " Response: $(echo "$response_body" | jq -c . 2>/dev/null || echo "$response_body")" + else + echo " ❌ Failed ($http_code)" + echo " Response: $response_body" + return 1 + fi + echo "" +} + +# Test Case 1: Multi-Source Data Loss Prevention Test +echo "🔥 TEST CASE 1: Multi-Source Data Loss Prevention" +echo "Testing that different sources don't overwrite each other's data" +echo "" + +# 1a. Add host with NMAP source +nmap_data='{ + "host": { + "ip": "192.168.1.100", + "hostname": "test-host-1", + "os": "Linux", + "osversion": "Ubuntu 22.04", + "vulnerabilities": [ + { + "vid": "CVE-2017-0144", + "title": "EternalBlue SMB Vulnerability", + "description": "Microsoft SMB Remote Code Execution Vulnerability", + "riskscore": 8.1 + }, + { + "vid": "CVE-2019-0708", + "title": "BlueKeep RDP Vulnerability", + "description": "Remote Desktop Services Remote Code Execution Vulnerability", + "riskscore": 9.8 + } + ] + }, + "source": { + "name": "nmap", + "version": "7.94", + "config": "nmap -sV -sC --script vuln" + } +}' + +make_api_call "POST" "/host/with-source" "$nmap_data" "Adding host with NMAP source" + +# 1b. Add same host with AGENT source (should NOT overwrite NMAP data) +agent_data='{ + "host": { + "ip": "192.168.1.100", + "hostname": "test-host-1", + "os": "Linux", + "osversion": "Ubuntu 22.04", + "vulnerabilities": [ + { + "vid": "CVE-2021-34527", + "title": "PrintNightmare Vulnerability", + "description": "Windows Print Spooler Remote Code Execution Vulnerability", + "riskscore": 8.8 + }, + { + "vid": "CVE-2019-0708", + "title": "BlueKeep RDP Vulnerability", + "description": "Remote Desktop Services Remote Code Execution Vulnerability (Agent detected)", + "riskscore": 9.8 + } + ] + }, + "source": { + "name": "agent", + "version": "2.1.0", + "config": "full-system-scan" + } +}' + +make_api_call "POST" "/host/with-source" "$agent_data" "Adding same host with AGENT source" + +# Test Case 2: Temporal Tracking Test +echo "🕐 TEST CASE 2: Temporal Tracking" +echo "Testing first_seen and last_seen timestamps" +echo "" + +# 2a. Create initial scan +temporal_data_1='{ + "host": { + "ip": "192.168.1.200", + "hostname": "temporal-test", + "vulnerabilities": [ + { + "vid": "CVE-2020-1472", + "title": "Zerologon Vulnerability", + "description": "Netlogon Remote Protocol (MS-NRPC) Elevation of Privilege Vulnerability", + "riskscore": 10.0 + } + ] + }, + "source": { + "name": "nmap", + "version": "7.94", + "config": "initial-scan" + } +}' + +make_api_call "POST" "/host/with-source" "$temporal_data_1" "Initial scan for temporal tracking" + +# 2b. Wait and rescan with same source (should update last_seen) +echo "⏳ Waiting 3 seconds to test temporal tracking..." +sleep 3 + +temporal_data_2='{ + "host": { + "ip": "192.168.1.200", + "hostname": "temporal-test", + "vulnerabilities": [ + { + "vid": "CVE-2020-1472", + "title": "Zerologon Vulnerability", + "description": "Netlogon Remote Protocol (MS-NRPC) Elevation of Privilege Vulnerability - rescan", + "riskscore": 10.0 + } + ] + }, + "source": { + "name": "nmap", + "version": "7.94", + "config": "rescan" + } +}' + +make_api_call "POST" "/host/with-source" "$temporal_data_2" "Rescan for temporal tracking (should update last_seen)" + +# Test Case 3: Backward Compatibility Test +echo "🔄 TEST CASE 3: Backward Compatibility" +echo "Testing that old API still works with source attribution" +echo "" + +legacy_data='{ + "ip": "192.168.1.300", + "hostname": "legacy-test", + "os": "Windows", + "osversion": "Server 2019", + "vulnerabilities": [ + { + "vid": "CVE-2018-8174", + "title": "VBScript Engine Memory Corruption", + "description": "VBScript Engine Remote Code Execution Vulnerability", + "riskscore": 7.5 + } + ] +}' + +make_api_call "POST" "/host" "$legacy_data" "Testing legacy API (should assign unknown source)" + +# Test Case 4: Multiple Sources on Same Vulnerability +echo "🔀 TEST CASE 4: Multiple Sources on Same CVE" +echo "Testing that same CVE from different sources creates separate records" +echo "" + +# 4a. Manual source finds CVE-2023-SHARED +manual_data='{ + "host": { + "ip": "192.168.1.400", + "hostname": "multi-source-test", + "vulnerabilities": [ + { + "vid": "CVE-2019-1182", + "title": "Windows RDP Vulnerability", + "description": "Remote Desktop Protocol Remote Code Execution Vulnerability", + "riskscore": 8.1 + } + ] + }, + "source": { + "name": "manual", + "version": "1.0.0", + "config": "manual-analysis" + } +}' + +make_api_call "POST" "/host/with-source" "$manual_data" "Manual source finds shared CVE" + +# 4b. RustScan also finds the same CVE +rustscan_data='{ + "host": { + "ip": "192.168.1.400", + "hostname": "multi-source-test", + "vulnerabilities": [ + { + "vid": "CVE-2019-1182", + "title": "Windows RDP Vulnerability", + "description": "Remote Desktop Protocol Remote Code Execution Vulnerability (RustScan detected)", + "riskscore": 8.1 + } + ] + }, + "source": { + "name": "rustscan", + "version": "2.0.1", + "config": "rustscan -p 1-65535" + } +}' + +make_api_call "POST" "/host/with-source" "$rustscan_data" "RustScan finds same CVE (should create separate record)" + +# Test Case 5: Port Tracking with Source Attribution +echo "🔌 TEST CASE 5: Port Source Attribution" +echo "Testing port discovery with source attribution" +echo "" + +port_data='{ + "host": { + "ip": "192.168.1.500", + "hostname": "port-test", + "ports": [ + { + "id": 80, + "protocol": "tcp", + "state": "open" + }, + { + "id": 443, + "protocol": "tcp", + "state": "open" + }, + { + "id": 22, + "protocol": "tcp", + "state": "closed" + } + ] + }, + "source": { + "name": "nmap", + "version": "7.94", + "config": "nmap -p 1-1000" + } +}' + +make_api_call "POST" "/host/with-source" "$port_data" "Port discovery with source attribution" + +echo "✅ Test data population completed!" +echo "" +echo "📋 Summary of test data created:" +echo " • 192.168.1.100 - Multi-source vulnerability test (nmap + agent)" +echo " • 192.168.1.200 - Temporal tracking test (nmap rescan)" +echo " • 192.168.1.300 - Backward compatibility test (legacy API)" +echo " • 192.168.1.400 - Same CVE from multiple sources (manual + rustscan)" +echo " • 192.168.1.500 - Port source attribution test (nmap)" +echo "" +echo "🔍 Run 'test-phase1-verify.sh' to validate the results" \ No newline at end of file diff --git a/scripts/test-phase1-verify.sh b/scripts/test-phase1-verify.sh new file mode 100755 index 0000000..4c30ebe --- /dev/null +++ b/scripts/test-phase1-verify.sh @@ -0,0 +1,284 @@ +#!/bin/bash + +# Test Verification Script for Phase 1 Validation +# This script validates that source-aware functionality is working correctly +# DELETE THIS SCRIPT after Phase 1 testing is complete + +set -e + +API_BASE="http://localhost:9001" +echo "🔍 Starting Phase 1 Verification Tests..." +echo "API Base: $API_BASE" +echo "" + +# Color codes for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Test tracking +TESTS_PASSED=0 +TESTS_FAILED=0 +TOTAL_TESTS=0 + +# Function to run test cases +run_test() { + local test_name="$1" + local test_command="$2" + local expected_result="$3" + + TOTAL_TESTS=$((TOTAL_TESTS + 1)) + echo -e "${BLUE}🧪 TEST: $test_name${NC}" + + if eval "$test_command"; then + echo -e " ${GREEN}✅ PASSED${NC}" + TESTS_PASSED=$((TESTS_PASSED + 1)) + else + echo -e " ${RED}❌ FAILED${NC}" + TESTS_FAILED=$((TESTS_FAILED + 1)) + fi + echo "" +} + +# Function to make API calls and parse JSON +api_get() { + local endpoint=$1 + curl -s "$API_BASE$endpoint" | jq . 2>/dev/null || curl -s "$API_BASE$endpoint" +} + +# Function to check if JSON contains specific data +json_contains() { + local json_data="$1" + local jq_query="$2" + echo "$json_data" | jq -e "$jq_query" > /dev/null 2>&1 +} + +# Function to count items in JSON array +json_count() { + local json_data="$1" + local jq_query="$2" + echo "$json_data" | jq "$jq_query | length" 2>/dev/null || echo "0" +} + +echo "🔥 VERIFICATION TEST 1: Multi-Source Data Loss Prevention" +echo "Verifying that host 192.168.1.100 has vulnerabilities from both nmap and agent" + +# Get host data with source information +host_data=$(api_get "/host/192.168.1.100/sources") +echo "📋 Host data retrieved:" +echo "$host_data" | jq . 2>/dev/null || echo "$host_data" +echo "" + +# Test 1a: Host should have vulnerabilities from nmap source +nmap_vuln_count=$(echo "$host_data" | jq '[.vulnerability_sources[] | select(.source == "nmap")] | length' 2>/dev/null || echo "0") +run_test "NMAP source vulnerabilities present" \ + "[ $nmap_vuln_count -gt 0 ]" \ + "Host should have vulnerabilities from nmap source" + +# Test 1b: Host should have vulnerabilities from agent source +agent_vuln_count=$(echo "$host_data" | jq '[.vulnerability_sources[] | select(.source == "agent")] | length' 2>/dev/null || echo "0") +run_test "Agent source vulnerabilities present" \ + "[ $agent_vuln_count -gt 0 ]" \ + "Host should have vulnerabilities from agent source" + +# Test 1c: Host should have the shared CVE from both sources +nmap_shared_count=$(echo "$host_data" | jq '[.vulnerability_sources[] | select(.VID == "CVE-2019-0708" and .source == "nmap")] | length' 2>/dev/null || echo "0") +agent_shared_count=$(echo "$host_data" | jq '[.vulnerability_sources[] | select(.VID == "CVE-2019-0708" and .source == "agent")] | length' 2>/dev/null || echo "0") + +run_test "Shared CVE from both sources" \ + "[ $nmap_shared_count -gt 0 ] && [ $agent_shared_count -gt 0 ]" \ + "CVE-2019-0708 should exist from both nmap and agent sources" + +# Test 1d: NMAP-specific vulnerability should only come from nmap +nmap_specific=$(echo "$host_data" | jq '[.vulnerability_sources[] | select(.VID == "CVE-2017-0144")] | length' 2>/dev/null || echo "0") +run_test "NMAP-specific vulnerability isolation" \ + "[ $nmap_specific -gt 0 ]" \ + "CVE-2017-0144 should exist from nmap source" + +echo "🕐 VERIFICATION TEST 2: Temporal Tracking" +echo "Verifying first_seen and last_seen timestamps work correctly" + +temporal_data=$(api_get "/host/192.168.1.200/sources") +echo "📋 Temporal test data:" +echo "$temporal_data" | jq . 2>/dev/null || echo "$temporal_data" +echo "" + +# Test 2a: Vulnerability should have first_seen timestamp +run_test "First seen timestamp exists" \ + "json_contains '$temporal_data' '.vulnerability_sources[0].first_seen'" \ + "Vulnerability should have first_seen timestamp" + +# Test 2b: Vulnerability should have last_seen timestamp +run_test "Last seen timestamp exists" \ + "json_contains '$temporal_data' '.vulnerability_sources[0].last_seen'" \ + "Vulnerability should have last_seen timestamp" + +# Test 2c: Last seen should be more recent than first seen (due to our 3-second delay) +first_seen=$(echo "$temporal_data" | jq -r '.vulnerability_sources[0].first_seen' 2>/dev/null || echo "") +last_seen=$(echo "$temporal_data" | jq -r '.vulnerability_sources[0].last_seen' 2>/dev/null || echo "") + +run_test "Temporal ordering correct" \ + "[ '$last_seen' != '$first_seen' ]" \ + "Last seen should be different from first seen due to rescan" + +echo "🔄 VERIFICATION TEST 3: Backward Compatibility" +echo "Verifying legacy API assigns 'unknown' source correctly" + +legacy_data=$(api_get "/host/192.168.1.300") +echo "📋 Legacy API data:" +echo "$legacy_data" | jq . 2>/dev/null || echo "$legacy_data" +echo "" + +# Test 3a: Legacy host should exist +legacy_ip=$(echo "$legacy_data" | jq -r '.ip // .IP // empty' 2>/dev/null || echo "") +run_test "Legacy host exists" \ + "[ '$legacy_ip' = '192.168.1.300' ]" \ + "Host created via legacy API should exist" + +# Test 3b: Legacy host vulnerabilities should have 'unknown' source when queried with source info +legacy_with_sources=$(api_get "/host/192.168.1.300/sources") +run_test "Legacy data has unknown source attribution" \ + "json_contains '$legacy_with_sources' '.vulnerability_sources[] | select(.source == \"unknown\")'" \ + "Legacy API data should be attributed to unknown source" + +echo "🔀 VERIFICATION TEST 4: Multiple Sources on Same CVE" +echo "Verifying same CVE from different sources creates separate records" + +multi_source_data=$(api_get "/host/192.168.1.400/sources") +echo "📋 Multi-source test data:" +echo "$multi_source_data" | jq . 2>/dev/null || echo "$multi_source_data" +echo "" + +# Test 4a: CVE should exist from manual source +manual_count=$(echo "$multi_source_data" | jq '[.vulnerability_sources[] | select(.VID == "CVE-2019-1182" and .source == "manual")] | length' 2>/dev/null || echo "0") +run_test "CVE from manual source" \ + "[ $manual_count -gt 0 ]" \ + "CVE-2019-1182 should exist from manual source" + +# Test 4b: CVE should exist from rustscan source +rustscan_count=$(echo "$multi_source_data" | jq '[.vulnerability_sources[] | select(.VID == "CVE-2019-1182" and .source == "rustscan")] | length' 2>/dev/null || echo "0") +run_test "CVE from rustscan source" \ + "[ $rustscan_count -gt 0 ]" \ + "CVE-2019-1182 should exist from rustscan source" + +# Test 4c: Total count should be at least 2 (one from each source, plus unknown) +shared_total=$(echo "$multi_source_data" | jq '[.vulnerability_sources[] | select(.VID == "CVE-2019-1182")] | length' 2>/dev/null || echo "0") +run_test "Separate records for same CVE" \ + "[ $shared_total -ge 2 ]" \ + "CVE-2019-1182 should have at least 2 separate records (manual + rustscan)" + +echo "🔌 VERIFICATION TEST 5: Port Source Attribution" +echo "Verifying port discovery includes source attribution" + +port_data=$(api_get "/host/192.168.1.500/sources") +echo "📋 Port attribution data:" +echo "$port_data" | jq . 2>/dev/null || echo "$port_data" +echo "" + +# Test 5a: Host should have ports with source attribution +run_test "Ports have source attribution" \ + "json_contains '$port_data' '.port_sources[] | select(.source == \"nmap\")'" \ + "Ports should be attributed to nmap source" + +# Test 5b: Specific ports should be present +port_80_count=$(echo "$port_data" | jq '[.port_sources[] | select(.ID == 80)] | length' 2>/dev/null || echo "0") +run_test "Port 80 discovered" \ + "[ $port_80_count -gt 0 ]" \ + "Port 80 should be discovered and recorded" + +echo "🔍 VERIFICATION TEST 6: New API Endpoints" +echo "Verifying new source-aware endpoints are available" + +# Test 6a: Source coverage endpoint +echo "Testing source coverage endpoint..." +coverage_data=$(api_get "/sources/coverage") +run_test "Source coverage endpoint" \ + "[ $? -eq 0 ]" \ + "Source coverage endpoint should be available" + +# Test 6b: Host history endpoint +echo "Testing host history endpoint..." +history_data=$(api_get "/host/192.168.1.100/history") +run_test "Host history endpoint" \ + "[ $? -eq 0 ]" \ + "Host history endpoint should be available" + +echo "📊 VERIFICATION TEST 7: Database Schema Validation" +echo "Verifying database has new source-aware schema" + +# Test 7a: Direct database query (if PostgreSQL is accessible) +if command -v psql &> /dev/null; then + echo "Testing database schema directly..." + + # Check if host_vulnerabilities table has new columns + schema_check=$(psql -h localhost -U postgres -d sirius -t -c "\d host_vulnerabilities" 2>/dev/null | grep -E "(source|first_seen|last_seen)" | wc -l) + run_test "Database schema updated" \ + "[ $schema_check -gt 0 ]" \ + "host_vulnerabilities table should have new source-aware columns" +else + echo "⚠️ PostgreSQL CLI not available, skipping direct database tests" +fi + +echo "🧹 VERIFICATION TEST 8: Data Integrity" +echo "Verifying overall data integrity and consistency" + +# Test 8a: All test hosts should exist +all_hosts=$(api_get "/host") +host_count=$(echo "$all_hosts" | jq 'length' 2>/dev/null || echo "0") +run_test "All test hosts exist" \ + "[ $host_count -ge 5 ]" \ + "At least 5 test hosts should exist" + +# Test 8b: No duplicate host records for same IP +test_host_data=$(api_get "/host/192.168.1.100") +test_host_ip=$(echo "$test_host_data" | jq -r '.ip // .IP // empty' 2>/dev/null || echo "") +run_test "No duplicate host records" \ + "[ '$test_host_ip' = '192.168.1.100' ]" \ + "Host should exist uniquely without duplication" + +echo "" +echo "🎯 TEST SUMMARY" +echo "==============" +echo -e "Total Tests: $TOTAL_TESTS" +echo -e "${GREEN}Passed: $TESTS_PASSED${NC}" +echo -e "${RED}Failed: $TESTS_FAILED${NC}" + +if [ $TESTS_FAILED -eq 0 ]; then + echo "" + echo -e "${GREEN}🎉 ALL TESTS PASSED! Phase 1 implementation is working correctly.${NC}" + echo "" + echo "✅ Key validations confirmed:" + echo " • Multi-source data is preserved (no overwriting)" + echo " • Source attribution is working correctly" + echo " • Temporal tracking (first_seen/last_seen) is functional" + echo " • Backward compatibility is maintained" + echo " • Same CVE from different sources creates separate records" + echo " • Port source attribution is working" + echo " • New API endpoints are available" + echo "" + echo "🚀 Phase 1 is ready for production!" +else + echo "" + echo -e "${RED}❌ SOME TESTS FAILED. Phase 1 implementation needs attention.${NC}" + echo "" + echo "🔧 Review the failed tests above and check:" + echo " • Database migration completed successfully" + echo " • New API endpoints are implemented" + echo " • Source-aware functions replace Association(...).Replace() calls" + echo " • Junction tables have source attribution fields" +fi + +echo "" +echo "📝 Next Steps:" +echo " • If tests pass: Proceed to Phase 2 (Scanner Integration)" +echo " • If tests fail: Review implementation and fix issues" +echo " • After verification: Delete these test scripts" + +# Cleanup reminder +echo "" +echo "⚠️ REMEMBER: Delete test scripts after verification:" +echo " rm scripts/test-phase1-populate.sh" +echo " rm scripts/test-phase1-verify.sh" +echo " rm scripts/test-phase1-cleanup.sh" \ No newline at end of file diff --git a/scripts/test-phase2-integration.sh b/scripts/test-phase2-integration.sh new file mode 100755 index 0000000..7e8901e --- /dev/null +++ b/scripts/test-phase2-integration.sh @@ -0,0 +1,568 @@ +#!/bin/bash + +# Phase 2 Integration Test Suite +# Tests source attribution functionality across all scanner types +# Validates multi-source scenarios and data integrity + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Test configuration +API_BASE_URL="http://localhost:9001" +TEST_HOST_IP="192.168.1.100" +TEST_CVE_1="CVE-2017-0144" # EternalBlue +TEST_CVE_2="CVE-2019-0708" # BlueKeep +TEST_CVE_3="CVE-2021-34527" # PrintNightmare + +# Test counters +TOTAL_TESTS=0 +PASSED_TESTS=0 +FAILED_TESTS=0 + +# Logging functions +log_info() { + echo -e "${BLUE}[INFO]${NC} $1" +} + +log_success() { + echo -e "${GREEN}[SUCCESS]${NC} $1" + ((PASSED_TESTS++)) +} + +log_error() { + echo -e "${RED}[ERROR]${NC} $1" + ((FAILED_TESTS++)) +} + +log_warning() { + echo -e "${YELLOW}[WARNING]${NC} $1" +} + +# Test helper functions +run_test() { + local test_name="$1" + local test_function="$2" + + ((TOTAL_TESTS++)) + log_info "Running test: $test_name" + + if $test_function; then + log_success "$test_name" + else + log_error "$test_name" + fi + echo "" +} + +# API helper functions +api_post() { + local endpoint="$1" + local data="$2" + local expected_status="${3:-200}" + + response=$(curl -s -w "HTTPSTATUS:%{http_code}" \ + -X POST \ + -H "Content-Type: application/json" \ + -d "$data" \ + "$API_BASE_URL$endpoint") + + http_code=$(echo "$response" | tr -d '\n' | sed -e 's/.*HTTPSTATUS://') + body=$(echo "$response" | sed -e 's/HTTPSTATUS:.*//g') + + if [[ "$http_code" -eq "$expected_status" ]]; then + echo "$body" + return 0 + else + log_error "API call failed. Expected: $expected_status, Got: $http_code" + echo "$body" + return 1 + fi +} + +api_get() { + local endpoint="$1" + local expected_status="${2:-200}" + + response=$(curl -s -w "HTTPSTATUS:%{http_code}" \ + -X GET \ + -H "Content-Type: application/json" \ + "$API_BASE_URL$endpoint") + + http_code=$(echo "$response" | tr -d '\n' | sed -e 's/.*HTTPSTATUS://') + body=$(echo "$response" | sed -e 's/HTTPSTATUS:.*//g') + + if [[ "$http_code" -eq "$expected_status" ]]; then + echo "$body" + return 0 + else + log_error "API call failed. Expected: $expected_status, Got: $http_code" + echo "$body" + return 1 + fi +} + +# Test functions +test_api_connectivity() { + log_info "Testing API connectivity..." + if api_get "/host" >/dev/null 2>&1; then + return 0 + else + log_error "Cannot connect to API at $API_BASE_URL" + return 1 + fi +} + +test_legacy_host_submission() { + log_info "Testing legacy host submission (backward compatibility)..." + + local host_data='{ + "ip": "'$TEST_HOST_IP'", + "hostname": "test-legacy-host", + "os": "Linux", + "ports": [ + { + "port": 22, + "protocol": "tcp", + "state": "open", + "service": "ssh" + } + ], + "vulnerabilities": [ + { + "vid": "'$TEST_CVE_1'", + "title": "EternalBlue SMB Vulnerability", + "description": "Legacy submission test", + "severity": "critical", + "cvss_score": 9.3, + "port": 445 + } + ] + }' + + if api_post "/host" "$host_data" 200 >/dev/null; then + # Verify the host was created with legacy source + local host_response + host_response=$(api_get "/host/$TEST_HOST_IP") + if echo "$host_response" | grep -q "$TEST_HOST_IP"; then + return 0 + else + log_error "Legacy host not found after submission" + return 1 + fi + else + return 1 + fi +} + +test_source_aware_nmap_submission() { + log_info "Testing source-aware nmap submission..." + + local host_data='{ + "host": { + "ip": "192.168.1.101", + "hostname": "test-nmap-host", + "os": "Linux", + "ports": [ + { + "port": 80, + "protocol": "tcp", + "state": "open", + "service": "http" + } + ], + "vulnerabilities": [ + { + "vid": "'$TEST_CVE_2'", + "title": "BlueKeep RDP Vulnerability", + "description": "Nmap source test", + "severity": "critical", + "cvss_score": 9.8, + "port": 3389 + } + ] + }, + "source": { + "name": "nmap", + "version": "7.94", + "config": "ports:1-1000;aggressive:true;template:comprehensive" + } + }' + + if api_post "/host/with-source" "$host_data" 200 >/dev/null; then + # Verify source attribution + local host_response + host_response=$(api_get "/host/192.168.1.101/sources") + if echo "$host_response" | grep -q "nmap" && echo "$host_response" | grep -q "7.94"; then + return 0 + else + log_error "Nmap source attribution not found" + return 1 + fi + else + return 1 + fi +} + +test_source_aware_agent_submission() { + log_info "Testing source-aware agent submission..." + + local host_data='{ + "host": { + "ip": "192.168.1.102", + "hostname": "test-agent-host", + "os": "Ubuntu 20.04", + "ports": [ + { + "port": 443, + "protocol": "tcp", + "state": "open", + "service": "https" + } + ], + "vulnerabilities": [ + { + "vid": "'$TEST_CVE_3'", + "title": "PrintNightmare Vulnerability", + "description": "Agent source test", + "severity": "high", + "cvss_score": 8.8, + "port": 445 + } + ] + }, + "source": { + "name": "sirius-agent", + "version": "1.0.0", + "config": "os:linux;arch:amd64;go:go1.21.0;host:test-agent" + } + }' + + if api_post "/host/with-source" "$host_data" 200 >/dev/null; then + # Verify source attribution + local host_response + host_response=$(api_get "/host/192.168.1.102/sources") + if echo "$host_response" | grep -q "sirius-agent" && echo "$host_response" | grep -q "1.0.0"; then + return 0 + else + log_error "Agent source attribution not found" + return 1 + fi + else + return 1 + fi +} + +test_multi_source_same_host() { + log_info "Testing multiple sources for same host..." + + local test_ip="192.168.1.103" + + # Submit from nmap source + local nmap_data='{ + "host": { + "ip": "'$test_ip'", + "hostname": "multi-source-host", + "os": "Linux", + "ports": [ + { + "port": 22, + "protocol": "tcp", + "state": "open", + "service": "ssh" + } + ], + "vulnerabilities": [ + { + "vid": "'$TEST_CVE_1'", + "title": "EternalBlue from Nmap", + "description": "Multi-source test - nmap", + "severity": "critical", + "cvss_score": 9.3, + "port": 445 + } + ] + }, + "source": { + "name": "nmap", + "version": "7.94", + "config": "multi-source-test" + } + }' + + # Submit from agent source + local agent_data='{ + "host": { + "ip": "'$test_ip'", + "hostname": "multi-source-host", + "os": "Linux", + "ports": [ + { + "port": 80, + "protocol": "tcp", + "state": "open", + "service": "http" + } + ], + "vulnerabilities": [ + { + "vid": "'$TEST_CVE_2'", + "title": "BlueKeep from Agent", + "description": "Multi-source test - agent", + "severity": "critical", + "cvss_score": 9.8, + "port": 3389 + } + ] + }, + "source": { + "name": "sirius-agent", + "version": "1.0.0", + "config": "multi-source-test" + } + }' + + # Submit both sources + if api_post "/host/with-source" "$nmap_data" 200 >/dev/null && \ + api_post "/host/with-source" "$agent_data" 200 >/dev/null; then + + # Verify both sources are present + local sources_response + sources_response=$(api_get "/host/$test_ip/sources") + if echo "$sources_response" | grep -q "nmap" && echo "$sources_response" | grep -q "sirius-agent"; then + # Verify both vulnerabilities are present + local host_response + host_response=$(api_get "/host/$test_ip") + if echo "$host_response" | grep -q "$TEST_CVE_1" && echo "$host_response" | grep -q "$TEST_CVE_2"; then + return 0 + else + log_error "Not all vulnerabilities found from multiple sources" + return 1 + fi + else + log_error "Not all sources found for multi-source host" + return 1 + fi + else + return 1 + fi +} + +test_source_detection_headers() { + log_info "Testing automatic source detection from headers..." + + local host_data='{ + "ip": "192.168.1.104", + "hostname": "header-detection-host", + "os": "Linux", + "ports": [ + { + "port": 8080, + "protocol": "tcp", + "state": "open", + "service": "http-proxy" + } + ], + "vulnerabilities": [] + }' + + # Submit with custom headers that should be detected + response=$(curl -s -w "HTTPSTATUS:%{http_code}" \ + -X POST \ + -H "Content-Type: application/json" \ + -H "X-Scanner-Name: rustscan" \ + -H "X-Scanner-Version: 2.1.1" \ + -H "X-Scanner-Config: fast-scan" \ + -d "$host_data" \ + "$API_BASE_URL/host") + + http_code=$(echo "$response" | tr -d '\n' | sed -e 's/.*HTTPSTATUS://') + + if [[ "$http_code" -eq 200 ]]; then + # Check if source was detected and attributed + local host_response + host_response=$(api_get "/host/192.168.1.104?include_source=true") + if echo "$host_response" | grep -q "rustscan" && echo "$host_response" | grep -q "2.1.1"; then + return 0 + else + log_error "Source detection from headers failed" + return 1 + fi + else + return 1 + fi +} + +test_backward_compatibility_response_format() { + log_info "Testing backward compatibility response formats..." + + # Test legacy client detection + local host_data='{ + "ip": "192.168.1.105", + "hostname": "legacy-client-host", + "os": "Windows", + "ports": [], + "vulnerabilities": [] + }' + + # Submit with legacy User-Agent + response=$(curl -s \ + -X POST \ + -H "Content-Type: application/json" \ + -H "User-Agent: legacy-client/1.0" \ + -H "X-API-Version: 1.0" \ + -d "$host_data" \ + "$API_BASE_URL/host") + + # Check response format (should be legacy format) + if echo "$response" | grep -q "Host added successfully" && ! echo "$response" | grep -q "source"; then + return 0 + else + log_error "Legacy response format not maintained" + return 1 + fi +} + +test_data_integrity_across_sources() { + log_info "Testing data integrity across multiple sources..." + + local test_ip="192.168.1.106" + + # Submit same vulnerability from different sources + local source1_data='{ + "host": { + "ip": "'$test_ip'", + "hostname": "integrity-test-host", + "os": "Linux", + "ports": [], + "vulnerabilities": [ + { + "vid": "'$TEST_CVE_1'", + "title": "EternalBlue", + "description": "From source 1", + "severity": "critical", + "cvss_score": 9.3, + "port": 445 + } + ] + }, + "source": { + "name": "nmap", + "version": "7.94", + "config": "integrity-test-1" + } + }' + + local source2_data='{ + "host": { + "ip": "'$test_ip'", + "hostname": "integrity-test-host", + "os": "Linux", + "ports": [], + "vulnerabilities": [ + { + "vid": "'$TEST_CVE_1'", + "title": "EternalBlue", + "description": "From source 2", + "severity": "critical", + "cvss_score": 9.3, + "port": 445 + } + ] + }, + "source": { + "name": "rustscan", + "version": "2.1.1", + "config": "integrity-test-2" + } + }' + + # Submit from both sources + if api_post "/host/with-source" "$source1_data" 200 >/dev/null && \ + api_post "/host/with-source" "$source2_data" 200 >/dev/null; then + + # Verify both source records exist for the same vulnerability + local sources_response + sources_response=$(api_get "/host/$test_ip/sources") + + # Count occurrences of the CVE (should be 2 - one from each source) + local cve_count + cve_count=$(echo "$sources_response" | grep -o "$TEST_CVE_1" | wc -l) + + if [[ "$cve_count" -ge 2 ]]; then + return 0 + else + log_error "Data integrity test failed - CVE not preserved across sources" + return 1 + fi + else + return 1 + fi +} + +# Cleanup function +cleanup_test_data() { + log_info "Cleaning up test data..." + + # Delete test hosts (if delete endpoint exists) + local test_ips=("192.168.1.100" "192.168.1.101" "192.168.1.102" "192.168.1.103" "192.168.1.104" "192.168.1.105" "192.168.1.106") + + for ip in "${test_ips[@]}"; do + curl -s -X POST \ + -H "Content-Type: application/json" \ + -d '{"ip": "'$ip'"}' \ + "$API_BASE_URL/host/delete" >/dev/null 2>&1 || true + done + + log_info "Cleanup completed" +} + +# Main test execution +main() { + echo "==========================================" + echo "Phase 2 Integration Test Suite" + echo "Testing Source Attribution Functionality" + echo "==========================================" + echo "" + + # Pre-test cleanup + cleanup_test_data + + # Run all tests + run_test "API Connectivity" test_api_connectivity + run_test "Legacy Host Submission" test_legacy_host_submission + run_test "Source-Aware Nmap Submission" test_source_aware_nmap_submission + run_test "Source-Aware Agent Submission" test_source_aware_agent_submission + run_test "Multi-Source Same Host" test_multi_source_same_host + run_test "Source Detection from Headers" test_source_detection_headers + run_test "Backward Compatibility Response Format" test_backward_compatibility_response_format + run_test "Data Integrity Across Sources" test_data_integrity_across_sources + + # Post-test cleanup + cleanup_test_data + + # Test summary + echo "==========================================" + echo "Test Summary" + echo "==========================================" + echo "Total Tests: $TOTAL_TESTS" + echo -e "Passed: ${GREEN}$PASSED_TESTS${NC}" + echo -e "Failed: ${RED}$FAILED_TESTS${NC}" + echo "" + + if [[ $FAILED_TESTS -eq 0 ]]; then + echo -e "${GREEN}🎉 All tests passed! Phase 2 integration is working correctly.${NC}" + exit 0 + else + echo -e "${RED}❌ Some tests failed. Please review the errors above.${NC}" + exit 1 + fi +} + +# Run main function +main "$@" \ No newline at end of file diff --git a/scripts/test-windows-registry.ps1 b/scripts/test-windows-registry.ps1 new file mode 100644 index 0000000..f236452 --- /dev/null +++ b/scripts/test-windows-registry.ps1 @@ -0,0 +1,110 @@ +# Windows Registry Vulnerability Detection Test Script +# This script tests the Windows registry detection capabilities + +Write-Host "🔍 Starting Windows Registry Vulnerability Detection Test" -ForegroundColor Cyan +Write-Host "===============================================" -ForegroundColor Cyan + +# Set up test registry entries +Write-Host "`n📝 Setting up test registry entries..." -ForegroundColor Yellow + +try { + # Create test vulnerable app registry entry + Write-Host " Creating test vulnerable app entry..." + reg add "HKLM\SOFTWARE\SiriusTest\VulnerableApp" /v "Version" /t REG_SZ /d "16.0.15330.20264" /f | Out-Null + + # Set UAC disabled (for testing) + Write-Host " Setting UAC disabled (test)..." + reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System" /v "EnableLUA" /t REG_DWORD /d 0 /f | Out-Null + + # Set Print Spooler enabled (for testing) + Write-Host " Setting Print Spooler enabled (test)..." + reg add "HKLM\SYSTEM\CurrentControlSet\Services\Spooler" /v "Start" /t REG_DWORD /d 2 /f | Out-Null + + Write-Host "✅ Test registry entries created successfully" -ForegroundColor Green + +} catch { + Write-Host "❌ Failed to create test registry entries: $($_.Exception.Message)" -ForegroundColor Red + exit 1 +} + +# Run the agent scan with registry templates +Write-Host "`n🚀 Running agent scan with registry detection..." -ForegroundColor Yellow + +try { + # Set environment variables for standalone mode + $env:SERVER_ADDRESS = "localhost:50051" + $env:AGENT_ID = "windows-test-agent" + $env:HOST_ID = "windows-test-host" + $env:API_BASE_URL = "http://localhost:9001" + $env:ENABLE_SCRIPTING = "true" + + # Check if agent executable exists + $agentPath = ".\agent.exe" + if (-not (Test-Path $agentPath)) { + $agentPath = ".\agent-windows.exe" + if (-not (Test-Path $agentPath)) { + Write-Host "❌ Agent executable not found. Please build with: GOOS=windows GOARCH=amd64 go build -o agent-windows.exe ." -ForegroundColor Red + exit 1 + } + } + + Write-Host " Using agent: $agentPath" + Write-Host " Templates directory: .\templates\" + + # Run the scan + Write-Host "`n📊 Executing registry vulnerability scan..." + & $agentPath scan 2>&1 | Tee-Object -FilePath "windows-registry-test.log" + + $scanResult = $LASTEXITCODE + + if ($scanResult -eq 0) { + Write-Host "✅ Agent scan completed successfully" -ForegroundColor Green + } else { + Write-Host "⚠️ Agent scan completed with exit code: $scanResult" -ForegroundColor Orange + } + +} catch { + Write-Host "❌ Failed to run agent scan: $($_.Exception.Message)" -ForegroundColor Red +} + +# Clean up test registry entries +Write-Host "`n🧹 Cleaning up test registry entries..." -ForegroundColor Yellow + +try { + Write-Host " Removing test vulnerable app entry..." + reg delete "HKLM\SOFTWARE\SiriusTest" /f 2>$null | Out-Null + + Write-Host " Restoring UAC to enabled..." + reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System" /v "EnableLUA" /t REG_DWORD /d 1 /f | Out-Null + + Write-Host "✅ Test registry entries cleaned up" -ForegroundColor Green + +} catch { + Write-Host "⚠️ Failed to clean up some registry entries: $($_.Exception.Message)" -ForegroundColor Orange +} + +# Display results +Write-Host "`n📋 Test Results Summary:" -ForegroundColor Cyan +Write-Host "===============================================" -ForegroundColor Cyan + +if (Test-Path "windows-registry-test.log") { + Write-Host "📄 Detailed log saved to: windows-registry-test.log" + Write-Host "`n🔍 Looking for registry detection results..." + + $logContent = Get-Content "windows-registry-test.log" -Raw + + if ($logContent -match "template.*registry" -or $logContent -match "vulnerable.*found") { + Write-Host "✅ Registry detection functionality appears to be working" -ForegroundColor Green + } else { + Write-Host "⚠️ Registry detection results not clearly visible in logs" -ForegroundColor Orange + } + + if ($logContent -match "error" -or $logContent -match "failed") { + Write-Host "⚠️ Some errors detected in logs - check windows-registry-test.log for details" -ForegroundColor Orange + } +} else { + Write-Host "⚠️ Log file not found" -ForegroundColor Orange +} + +Write-Host "`n🎯 Registry Detection Test Completed!" -ForegroundColor Cyan +Write-Host " Check the above output and windows-registry-test.log for detailed results" -ForegroundColor Gray \ No newline at end of file diff --git a/scripts/update-go-api.sh b/scripts/update-go-api.sh new file mode 100755 index 0000000..1e864c5 --- /dev/null +++ b/scripts/update-go-api.sh @@ -0,0 +1,126 @@ +#!/bin/bash +# +# Bulk Update go-api Dependency Across All Projects +# +# This script updates the github.com/SiriusScan/go-api dependency to the +# latest version (or a specified version) across all projects in the workspace. +# +# Usage: +# ./scripts/update-go-api.sh [version] +# +# Examples: +# ./scripts/update-go-api.sh # Update to latest +# ./scripts/update-go-api.sh v0.0.10 # Update to specific version +# + +set -euo pipefail + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Get the root directory of the repository +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" + +# Version to update to (default: latest) +VERSION="${1:-latest}" + +echo -e "${BLUE}🔄 Bulk Go API Update Script${NC}" +echo -e "${BLUE}================================${NC}\n" + +if [ "$VERSION" = "latest" ]; then + echo -e "${YELLOW}📦 Fetching latest version from GitHub...${NC}" + LATEST_TAG=$(curl -s https://api.github.com/repos/SiriusScan/go-api/releases/latest | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/') + if [ -z "$LATEST_TAG" ]; then + echo -e "${RED}❌ Failed to fetch latest version${NC}" + exit 1 + fi + VERSION="$LATEST_TAG" + echo -e "${GREEN}✅ Latest version: $VERSION${NC}\n" +else + echo -e "${YELLOW}📌 Updating to specified version: $VERSION${NC}\n" +fi + +# Find all go.mod files that use go-api +echo -e "${BLUE}🔍 Finding projects that use go-api...${NC}" +GO_MOD_FILES=$(find "$REPO_ROOT" -name "go.mod" -type f | grep -v "minor-projects/go-api" || true) + +if [ -z "$GO_MOD_FILES" ]; then + echo -e "${YELLOW}⚠️ No projects found using go-api${NC}" + exit 0 +fi + +# Filter for files that actually contain go-api dependency +PROJECTS_TO_UPDATE=() +while IFS= read -r go_mod; do + if grep -q "github.com/SiriusScan/go-api" "$go_mod"; then + PROJECTS_TO_UPDATE+=("$go_mod") + fi +done <<< "$GO_MOD_FILES" + +if [ ${#PROJECTS_TO_UPDATE[@]} -eq 0 ]; then + echo -e "${YELLOW}⚠️ No projects found with go-api dependency${NC}" + exit 0 +fi + +echo -e "${GREEN}Found ${#PROJECTS_TO_UPDATE[@]} project(s) to update:${NC}" +for project in "${PROJECTS_TO_UPDATE[@]}"; do + echo -e " • $(dirname "$project" | sed "s|$REPO_ROOT/||")" +done +echo "" + +# Ask for confirmation +read -p "$(echo -e ${YELLOW}"Continue with update? (y/N): "${NC})" -n 1 -r +echo +if [[ ! $REPLY =~ ^[Yy]$ ]]; then + echo -e "${RED}❌ Update cancelled${NC}" + exit 0 +fi + +echo "" + +# Update each project +UPDATED=0 +FAILED=0 +for go_mod in "${PROJECTS_TO_UPDATE[@]}"; do + PROJECT_DIR=$(dirname "$go_mod") + PROJECT_NAME=$(basename "$PROJECT_DIR") + + echo -e "${BLUE}📦 Updating $PROJECT_NAME...${NC}" + + cd "$PROJECT_DIR" + + # Run go get and go mod tidy + if go get "github.com/SiriusScan/go-api@$VERSION" && go mod tidy; then + echo -e "${GREEN}✅ $PROJECT_NAME updated successfully${NC}\n" + ((UPDATED++)) + else + echo -e "${RED}❌ Failed to update $PROJECT_NAME${NC}\n" + ((FAILED++)) + fi +done + +# Summary +echo -e "${BLUE}================================${NC}" +echo -e "${BLUE}📊 Update Summary${NC}" +echo -e "${BLUE}================================${NC}" +echo -e "${GREEN}✅ Successfully updated: $UPDATED${NC}" +if [ $FAILED -gt 0 ]; then + echo -e "${RED}❌ Failed: $FAILED${NC}" +fi +echo "" + +if [ $UPDATED -gt 0 ]; then + echo -e "${YELLOW}💡 Next steps:${NC}" + echo -e " 1. Review the changes: ${BLUE}git status${NC}" + echo -e " 2. Test the updates: ${BLUE}docker compose down && docker compose up -d --build${NC}" + echo -e " 3. Commit the changes: ${BLUE}git add . && git commit -m 'chore(deps): update go-api to $VERSION'${NC}" + echo "" +fi + +echo -e "${GREEN}✨ Done!${NC}" + diff --git a/scripts/validate-ci-overhaul.sh b/scripts/validate-ci-overhaul.sh new file mode 100755 index 0000000..05c827a --- /dev/null +++ b/scripts/validate-ci-overhaul.sh @@ -0,0 +1,150 @@ +#!/bin/bash + +# Validate CI/CD container builds locally (no separate GHCR base images). +# +# Builds infra + application images and validates docker-compose configs. +# +# Usage: ./scripts/validate-ci-overhaul.sh [--full-compose] +# --full-compose Also bring up infrastructure + one app service to verify startup + +set -e + +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' + +FULL_COMPOSE=false +if [[ "${1:-}" == "--full-compose" ]]; then + FULL_COMPOSE=true +fi + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" +LOG_DIR="$PROJECT_ROOT/testing/logs" +TIMESTAMP=$(date +"%Y%m%d_%H%M%S") +LOG_FILE="$LOG_DIR/validate_ci_overhaul_$TIMESTAMP.log" + +mkdir -p "$LOG_DIR" + +log() { + echo -e "$1" | tee -a "$LOG_FILE" +} + +run_step() { + local step_name="$1" + local cmd="$2" + log "${BLUE}▶ $step_name${NC}" + log " $cmd" + if eval "$cmd" >> "$LOG_FILE" 2>&1; then + log "${GREEN} ✓ $step_name${NC}" + return 0 + else + log "${RED} ✗ $step_name FAILED${NC}" + log " See $LOG_FILE for details" + return 1 + fi +} + +cd "$PROJECT_ROOT" + +log "" +log "${BLUE}═══════════════════════════════════════════════════════════════${NC}" +log "${BLUE} CI/CD container local validation${NC}" +log "${BLUE}═══════════════════════════════════════════════════════════════${NC}" +log "Project Root: $PROJECT_ROOT" +log "Log File: $LOG_FILE" +log "" + +# ───────────────────────────────────────────────────────────────────────────── +# Phase 1: Infrastructure containers +# ───────────────────────────────────────────────────────────────────────────── +log "${YELLOW}Phase 1: Infrastructure Containers${NC}" +log "" + +run_step "Build sirius-postgres" \ + "docker build -t sirius-postgres:test ./sirius-postgres/" || exit 1 + +run_step "Build sirius-rabbitmq" \ + "docker build -t sirius-rabbitmq:test ./sirius-rabbitmq/" || exit 1 + +run_step "Build sirius-valkey" \ + "docker build -t sirius-valkey:test ./sirius-valkey/" || exit 1 + +log "" +log "${YELLOW}Phase 2: Application Containers${NC}" +log "" + +run_step "Build sirius-api (runner stage)" \ + "docker build -t sirius-api:test ./sirius-api/ --target runner" || exit 1 + +run_step "Build sirius-ui (production stage)" \ + "docker build -t sirius-ui:test ./sirius-ui/ --target production" || exit 1 + +run_step "Build sirius-engine (development stage)" \ + "docker build -t sirius-engine:dev ./sirius-engine/ --target development" || exit 1 + +run_step "Build sirius-engine (runtime stage)" \ + "docker build -t sirius-engine:runtime ./sirius-engine/ --target runtime" || exit 1 + +log "" +log "${YELLOW}Phase 3: Runtime Contracts${NC}" +log "" + +run_step "sirius-postgres entrypoint contract" \ + "docker run --rm --entrypoint /bin/sh sirius-postgres:test -c 'test -x /usr/local/bin/start-with-monitor.sh'" || exit 1 + +run_step "sirius-engine runtime binary contract (bash, nmap, rustscan, pwsh, psql)" \ + "docker run --rm --entrypoint /bin/bash sirius-engine:runtime -c 'command -v bash >/dev/null && command -v nmap >/dev/null && command -v rustscan >/dev/null && command -v pwsh >/dev/null && command -v psql >/dev/null'" || exit 1 + +log "" +log "${YELLOW}Phase 4: Docker Compose Validation${NC}" +log "" + +export POSTGRES_PASSWORD="${POSTGRES_PASSWORD:-test-postgres-password}" +export NEXTAUTH_SECRET="${NEXTAUTH_SECRET:-test-nextauth-secret}" +export INITIAL_ADMIN_PASSWORD="${INITIAL_ADMIN_PASSWORD:-test-admin-password}" +mkdir -p secrets +printf '%s\n' "${SIRIUS_INTERNAL_API_KEY_TEST_VALUE:-test-api-key}" > secrets/sirius_api_key.txt + +run_step "Base docker-compose config" \ + "docker compose config --quiet" || exit 1 + +run_step "Development docker-compose config" \ + "docker compose -f docker-compose.yaml -f docker-compose.dev.yaml config --quiet" || exit 1 + +log "" +log "${GREEN}═══════════════════════════════════════════════════════════════${NC}" +log "${GREEN} All builds and validations passed!${NC}" +log "${GREEN}═══════════════════════════════════════════════════════════════${NC}" +log "" +log "You can now confidently commit and push. CI builds application images on" +log "native amd64/arm64 runners (ci.yml), merges manifests, and runs integration tests." +log "" + +# Optional: bring up a minimal stack to verify runtime +if $FULL_COMPOSE; then + log "${YELLOW}Phase 5: Minimal Compose Stack (--full-compose)${NC}" + log "" + log "Starting postgres, rabbitmq, valkey, api for 30s to verify startup..." + docker compose up -d sirius-postgres sirius-rabbitmq sirius-valkey 2>>"$LOG_FILE" || true + sleep 10 + docker compose up -d sirius-api 2>>"$LOG_FILE" || true + sleep 20 + if docker compose exec -T sirius-api wget -q -O /dev/null http://127.0.0.1:9001/health 2>/dev/null; then + log "${GREEN} ✓ sirius-api health check passed${NC}" + else + log "${YELLOW} ⚠ sirius-api may still be starting; check: docker compose logs sirius-api${NC}" + fi + docker compose down 2>>"$LOG_FILE" || true + log "" +fi + +# Cleanup test tags (optional, comment out to keep for debugging) +log "${YELLOW}Cleaning up test images...${NC}" +docker rmi sirius-postgres:test sirius-rabbitmq:test sirius-valkey:test sirius-api:test sirius-ui:test sirius-engine:dev sirius-engine:runtime 2>/dev/null || true +log "" + +log "Full log: $LOG_FILE" +exit 0 diff --git a/scripts/validate-public-compose-path.sh b/scripts/validate-public-compose-path.sh new file mode 100755 index 0000000..681d542 --- /dev/null +++ b/scripts/validate-public-compose-path.sh @@ -0,0 +1,57 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(dirname "${SCRIPT_DIR}")" + +IMAGE_TAG_VALUE="${1:-${IMAGE_TAG:-latest}}" +: "${KEEP_PUBLIC_STACK_RUNNING:=0}" +: "${SIRIUS_IMAGE_PULL_POLICY:=always}" + +cleanup() { + if [ "${KEEP_PUBLIC_STACK_RUNNING}" = "1" ]; then + return + fi + + docker compose down --volumes --remove-orphans >/dev/null 2>&1 || true +} + +trap cleanup EXIT + +cd "${PROJECT_ROOT}" + +echo "Resetting public compose stack state..." +docker compose down --volumes --remove-orphans >/dev/null 2>&1 || true + +echo "Generating runtime config with installer..." +# Run the installer container as the invoking host user so the resulting +# .env / secrets/ files are readable by subsequent steps (e.g. `docker +# compose config` reading .env). Without this, the installer writes +# .env as root:root mode 0600 and the next compose invocation fails with +# "open .env: permission denied" — silently producing zero image refs. +SIRIUS_INSTALLER_UID="$(id -u)" SIRIUS_INSTALLER_GID="$(id -g)" \ + docker compose -f docker-compose.installer.yaml run --rm --build sirius-installer --non-interactive --no-print-secrets + +# Defensive: even with the user override above, guarantee .env is readable +# by the current user. Harmless if already readable. +if [ -f "${PROJECT_ROOT}/.env" ] && [ ! -r "${PROJECT_ROOT}/.env" ]; then + echo "::warning::.env not readable by $(id -un); attempting chmod via sudo" + sudo chown "$(id -u):$(id -g)" "${PROJECT_ROOT}/.env" 2>/dev/null || true +fi + +export IMAGE_TAG="${IMAGE_TAG_VALUE}" +export SIRIUS_IMAGE_PULL_POLICY + +echo "Verifying anonymous GHCR access for IMAGE_TAG=${IMAGE_TAG}..." +bash scripts/verify-ghcr-public-access.sh "${IMAGE_TAG}" + +echo "Pulling compose-rendered public images..." +docker compose pull + +echo "Starting public compose stack..." +docker compose up -d + +echo "Verifying runtime auth contract..." +bash scripts/verify-runtime-auth-contract.sh + +echo "Public compose path validated for IMAGE_TAG=${IMAGE_TAG}." diff --git a/scripts/verify-ghcr-public-access.sh b/scripts/verify-ghcr-public-access.sh new file mode 100755 index 0000000..eedf306 --- /dev/null +++ b/scripts/verify-ghcr-public-access.sh @@ -0,0 +1,94 @@ +#!/usr/bin/env bash +# Anonymous registry checks use a temporary DOCKER_CONFIG inside this script. +# Do not wrap the entire shell in DOCKER_CONFIG=... when invoking this script: +# `docker compose config` needs your normal Docker config to resolve the compose file. +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(dirname "${SCRIPT_DIR}")" +COMPOSE_FILE="${COMPOSE_FILE:-${PROJECT_ROOT}/docker-compose.yaml}" +REGISTRY="${REGISTRY:-ghcr.io}" +IMAGE_NAMESPACE="${IMAGE_NAMESPACE:-siriusscan}" + +if [ "$#" -gt 0 ]; then + TAGS=("$@") +else + TAGS=("latest") +fi + +export POSTGRES_PASSWORD="${POSTGRES_PASSWORD:-test-postgres-password}" +export NEXTAUTH_SECRET="${NEXTAUTH_SECRET:-test-nextauth-secret}" +export INITIAL_ADMIN_PASSWORD="${INITIAL_ADMIN_PASSWORD:-test-admin-password}" +export DATABASE_URL="${DATABASE_URL:-postgresql://postgres:test-postgres-password@sirius-postgres:5432/sirius}" +export SIRIUS_IMAGE_PULL_POLICY="${SIRIUS_IMAGE_PULL_POLICY:-always}" + +if [ ! -f "${PROJECT_ROOT}/secrets/sirius_api_key.txt" ]; then + mkdir -p "${PROJECT_ROOT}/secrets" + printf '%s\n' "${SIRIUS_INTERNAL_API_KEY_TEST_VALUE:-test-api-key}" > "${PROJECT_ROOT}/secrets/sirius_api_key.txt" +fi + +anonymous_manifest_check() { + local image_ref="$1" + local docker_config + local err + local rc + + docker_config="$(mktemp -d)" + + set +e + err="$(DOCKER_CONFIG="${docker_config}" docker manifest inspect "${image_ref}" 2>&1 >/dev/null)" + rc=$? + set -e + + rm -rf "${docker_config}" + + if [ "${rc}" -eq 0 ]; then + echo " PASS ${image_ref}" + return 0 + fi + + if printf '%s' "${err}" | grep -qiE 'unauthorized|denied|forbidden'; then + echo "::error::Anonymous access denied for ${image_ref}. GHCR package visibility is not public or token-based visibility enforcement failed." + return 1 + fi + + if printf '%s' "${err}" | grep -qiE 'manifest unknown|no such manifest|not found'; then + echo "::error::Manifest missing for ${image_ref}. The tag was not published or was published under a different name." + return 1 + fi + + echo "::error::Unable to verify ${image_ref}: ${err}" + return 1 +} + +for tag in "${TAGS[@]}"; do + echo "Verifying anonymous GHCR access for IMAGE_TAG=${tag}" + + image_refs=() + while IFS= read -r image_ref; do + image_refs+=("${image_ref}") + done < <( + IMAGE_TAG="${tag}" docker compose -f "${COMPOSE_FILE}" config \ + | awk '/^[[:space:]]+image:[[:space:]]/ {print $2}' \ + | grep "^${REGISTRY}/${IMAGE_NAMESPACE}/" \ + | sort -u + ) + + if [ "${#image_refs[@]}" -eq 0 ]; then + echo "::error::No GHCR image references found in ${COMPOSE_FILE} for IMAGE_TAG=${tag}" + exit 1 + fi + + failures=0 + for image_ref in "${image_refs[@]}"; do + if ! anonymous_manifest_check "${image_ref}"; then + failures=1 + fi + done + + if [ "${failures}" -ne 0 ]; then + exit 1 + fi +done + +echo "All compose-rendered GHCR images are anonymously readable." diff --git a/scripts/verify-release-images.sh b/scripts/verify-release-images.sh new file mode 100644 index 0000000..ed7df93 --- /dev/null +++ b/scripts/verify-release-images.sh @@ -0,0 +1,41 @@ +#!/usr/bin/env bash +set -euo pipefail + +IMAGE_TAG="${IMAGE_TAG:-latest}" +REGISTRY="${REGISTRY:-ghcr.io/siriusscan}" + +declare -a SERVICES=("sirius-ui" "sirius-api" "sirius-engine") + +echo "Verifying release images for tag: ${IMAGE_TAG}" + +for service in "${SERVICES[@]}"; do + image_ref="${REGISTRY}/${service}:${IMAGE_TAG}" + container_name="${service}" + + echo + echo "Pulling ${image_ref}..." + docker pull "${image_ref}" >/dev/null + + expected_id="$(docker image inspect "${image_ref}" --format '{{.Id}}')" + running_image_ref="$(docker inspect "${container_name}" --format '{{.Config.Image}}' 2>/dev/null || true)" + running_id="$(docker inspect "${container_name}" --format '{{.Image}}' 2>/dev/null || true)" + + if [ -z "${running_id}" ]; then + echo "❌ ${container_name} is not running" + exit 1 + fi + + echo "${container_name} config image: ${running_image_ref}" + echo "${container_name} running image id: ${running_id}" + echo "${container_name} expected image id: ${expected_id}" + + if [ "${running_id}" != "${expected_id}" ]; then + echo "❌ ${container_name} is not running ${image_ref}" + exit 1 + fi + + echo "✅ ${container_name} matches ${image_ref}" +done + +echo +echo "All release image checks passed." diff --git a/scripts/verify-runtime-auth-contract.sh b/scripts/verify-runtime-auth-contract.sh new file mode 100644 index 0000000..aa7123a --- /dev/null +++ b/scripts/verify-runtime-auth-contract.sh @@ -0,0 +1,198 @@ +#!/usr/bin/env bash +# Runtime auth contract: internal API key comes from the mounted +# SIRIUS_API_KEY_FILE secret, POSTGRES_PASSWORD parity, engine env, API HTTP +# behavior. +# +# Container names default to docker-compose.yaml `container_name` values (project: sirius). +# Override for other projects, e.g. CI: +# export SIRIUS_CONTRACT_CONTAINER_UI=sirius-test-sirius-ui-1 +# export SIRIUS_CONTRACT_CONTAINER_API=sirius-test-sirius-api-1 +# export SIRIUS_CONTRACT_CONTAINER_ENGINE=sirius-test-sirius-engine-1 +# export SIRIUS_CONTRACT_CONTAINER_POSTGRES=sirius-test-sirius-postgres-1 +# +# Host URL for curl (published API port on the host): +# export SIRIUS_API_PUBLIC_URL=http://localhost:9001 +# +set -euo pipefail + +: "${SIRIUS_CONTRACT_CONTAINER_UI:=sirius-ui}" +: "${SIRIUS_CONTRACT_CONTAINER_API:=sirius-api}" +: "${SIRIUS_CONTRACT_CONTAINER_ENGINE:=sirius-engine}" +: "${SIRIUS_CONTRACT_CONTAINER_POSTGRES:=sirius-postgres}" +: "${SIRIUS_API_PUBLIC_URL:=http://localhost:9001}" +SIRIUS_API_PUBLIC_URL="${SIRIUS_API_PUBLIC_URL%/}" + +CTR_UI="$SIRIUS_CONTRACT_CONTAINER_UI" +CTR_API="$SIRIUS_CONTRACT_CONTAINER_API" +CTR_ENGINE="$SIRIUS_CONTRACT_CONTAINER_ENGINE" +CTR_POSTGRES="$SIRIUS_CONTRACT_CONTAINER_POSTGRES" + +required_containers=("$CTR_POSTGRES" "$CTR_API" "$CTR_ENGINE" "$CTR_UI") +for name in "${required_containers[@]}"; do + if ! docker inspect "$name" >/dev/null 2>&1; then + echo "❌ Missing container: $name (override SIRIUS_CONTRACT_CONTAINER_* if using a non-default compose project)" + exit 1 + fi +done + +extract_env() { + local container="$1" + local key="$2" + # NOTE: use grep, not rg — ripgrep is not preinstalled on GitHub-hosted + # ubuntu-latest runners. The trailing `|| true` previously masked the + # `rg: command not found` failure, silently returning empty for every + # key and tripping the POSTGRES_PASSWORD parity check downstream. + docker inspect "$container" --format '{{range .Config.Env}}{{println .}}{{end}}' \ + | grep "^${key}=" | sed "s/^${key}=//" || true +} + +# Effective key inside the container (trimmed file contents only). +resolve_file_backed_api_key() { + local container="$1" + docker exec "$container" sh -lc \ + 'if [ -r "${SIRIUS_API_KEY_FILE:-}" ]; then tr -d "\r\n" < "$SIRIUS_API_KEY_FILE"; fi' +} + +mask_value() { + local value="$1" + if [ -z "$value" ]; then + echo "" + return + fi + local len=${#value} + if [ "$len" -le 10 ]; then + echo "${value:0:2}***" + return + fi + echo "${value:0:6}...${value: -4}" +} + +assert_file_only_api_key_contract() { + local container="$1" + local label="$2" + local file_key + local configured_env_key + + file_key="$(resolve_file_backed_api_key "$container")" + configured_env_key="$(extract_env "$container" SIRIUS_API_KEY)" + + if [ -n "$configured_env_key" ]; then + echo "❌ ${label} still has legacy SIRIUS_API_KEY configured in container env" + exit 1 + fi + + if [ -z "$file_key" ]; then + echo "❌ ${label} is missing a readable file-backed internal API key" + exit 1 + fi +} + +assert_file_only_api_key_contract "$CTR_UI" "sirius-ui" +assert_file_only_api_key_contract "$CTR_API" "sirius-api" +assert_file_only_api_key_contract "$CTR_ENGINE" "sirius-engine" + +ui_key="$(resolve_file_backed_api_key "$CTR_UI")" +api_key="$(resolve_file_backed_api_key "$CTR_API")" +engine_key="$(resolve_file_backed_api_key "$CTR_ENGINE")" + +postgres_db_pw="$(extract_env "$CTR_POSTGRES" POSTGRES_PASSWORD)" +api_db_pw="$(extract_env "$CTR_API" POSTGRES_PASSWORD)" +engine_db_pw="$(extract_env "$CTR_ENGINE" POSTGRES_PASSWORD)" +engine_api_base_url="$(extract_env "$CTR_ENGINE" API_BASE_URL)" +engine_sirius_api_url="$(extract_env "$CTR_ENGINE" SIRIUS_API_URL)" +engine_agent_id="$(extract_env "$CTR_ENGINE" AGENT_ID)" +engine_host_id="$(extract_env "$CTR_ENGINE" HOST_ID)" + +echo "Runtime key fingerprints:" +echo " ui ($CTR_UI): $(mask_value "$ui_key")" +echo " api ($CTR_API): $(mask_value "$api_key")" +echo " engine ($CTR_ENGINE): $(mask_value "$engine_key")" + +if [ -z "$ui_key" ] || [ -z "$api_key" ] || [ -z "$engine_key" ]; then + echo "❌ One or more services are missing readable SIRIUS_API_KEY_FILE secret data" + exit 1 +fi + +echo "✅ File-only internal API key contract check passed" + +if [ "$ui_key" != "$api_key" ] || [ "$api_key" != "$engine_key" ]; then + echo "❌ Internal API key mismatch across services (key split-brain detected)" + exit 1 +fi +echo "✅ Internal API key parity check passed" + +if [ -z "$postgres_db_pw" ] || [ -z "$api_db_pw" ] || [ -z "$engine_db_pw" ]; then + echo "❌ One or more services are missing POSTGRES_PASSWORD" + exit 1 +fi + +if [ "$postgres_db_pw" != "$api_db_pw" ] || [ "$api_db_pw" != "$engine_db_pw" ]; then + echo "❌ POSTGRES_PASSWORD mismatch across postgres/api/engine" + exit 1 +fi +echo "✅ POSTGRES_PASSWORD parity check passed" + +if [ -z "$engine_sirius_api_url" ] || [ -z "$engine_agent_id" ] || [ -z "$engine_host_id" ]; then + echo "❌ sirius-engine is missing one or more required runtime env values (SIRIUS_API_URL, AGENT_ID, HOST_ID)" + exit 1 +fi +if [ -n "$engine_api_base_url" ] && [ -n "$engine_sirius_api_url" ]; then + if [ "${engine_api_base_url%/}" != "${engine_sirius_api_url%/}" ]; then + echo "❌ API_BASE_URL must equal SIRIUS_API_URL on engine (got API_BASE_URL=${engine_api_base_url} SIRIUS_API_URL=${engine_sirius_api_url})" + exit 1 + fi +fi +echo "✅ sirius-engine runtime env contract check passed" + +if docker exec "$CTR_POSTGRES" test -f /usr/local/bin/start-with-monitor.sh 2>/dev/null; then + if docker exec "$CTR_POSTGRES" sh -lc "grep -E -q 'psql[^\\n]*\\|\\| true|ALTER ROLE[^\\n]*\\|\\| true' /usr/local/bin/start-with-monitor.sh"; then + echo "❌ Running postgres entrypoint still contains permissive psql reconciliation fallback" + exit 1 + fi + echo "✅ Postgres reconciliation script does not contain permissive psql fallback" +else + echo "ℹ️ Skipping custom postgres entrypoint check (not Sirius postgres image)" +fi + +if ! docker exec "$CTR_ENGINE" bash -lc 'for bin in bash curl psql pkill nmap rustscan pwsh; do command -v "$bin" >/dev/null || exit 1; done'; then + echo "❌ sirius-engine runtime binary contract check failed" + exit 1 +fi +echo "✅ sirius-engine runtime binary contract check passed" + +if ! docker exec "$CTR_ENGINE" bash -lc '/bin/bash -n /start-enhanced.sh && grep -q "validate_required_binary \"psql\"" /start-enhanced.sh'; then + echo "❌ sirius-engine startup script contract check failed" + exit 1 +fi +echo "✅ sirius-engine startup script contract check passed" + +HOST_PROBE="${SIRIUS_API_PUBLIC_URL}/host/" +unauth_code="$(curl -sS --max-time 15 -o /tmp/sirius-auth-unauth.out -w '%{http_code}' "$HOST_PROBE" || true)" +if [ "$unauth_code" != "401" ]; then + echo "❌ Expected unauthenticated /host/ to return 401, got $unauth_code (URL: $HOST_PROBE)" + exit 1 +fi +echo "✅ Unauthenticated API contract check passed" + +auth_code="$(curl -sS --max-time 15 -o /tmp/sirius-auth-auth.out -w '%{http_code}' -H "X-API-Key: $api_key" "$HOST_PROBE" || true)" +if [ "$auth_code" = "401" ] || [ "$auth_code" = "403" ] || [ "$auth_code" = "000" ]; then + echo "❌ Authenticated /host/ request failed with status $auth_code" + exit 1 +fi +if ! [[ "$auth_code" =~ ^[0-9]+$ ]]; then + echo "❌ Unexpected curl HTTP code output: $auth_code" + exit 1 +fi +if [ "$auth_code" -lt 200 ] || [ "$auth_code" -ge 300 ]; then + echo "❌ Authenticated /host/ expected HTTP 2xx, got $auth_code" + exit 1 +fi +echo "✅ Authenticated API contract check passed (status $auth_code)" + +if ! docker exec "$CTR_POSTGRES" sh -lc 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h 127.0.0.1 -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "SELECT 1;" >/dev/null'; then + echo "❌ Postgres runtime credential probe failed" + exit 1 +fi +echo "✅ Postgres runtime credential probe passed" + +echo "✅ Runtime auth contract verification succeeded" diff --git a/secrets/.gitkeep b/secrets/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/sirius-api/.air.toml b/sirius-api/.air.toml new file mode 100755 index 0000000..4112bcc --- /dev/null +++ b/sirius-api/.air.toml @@ -0,0 +1,40 @@ +#alias air='$(go env GOPATH)/bin/air' + +root = "." +testdata_dir = "testdata" +tmp_dir = "tmp" + +[build] + args_bin = [] + bin = "./tmp/main" + cmd = "go build -o ./tmp/main ./main.go" + delay = 1000 + exclude_dir = ["assets", "tmp", "vendor", "testdata"] + exclude_file = [] + exclude_regex = ["_test.go"] + exclude_unchanged = false + follow_symlink = false + full_bin = "" + include_dir = [] + include_ext = ["go", "tpl", "tmpl", "html"] + kill_delay = "0s" + log = "build-errors.log" + send_interrupt = false + stop_on_error = true + +[color] + app = "" + build = "yellow" + main = "magenta" + runner = "green" + watcher = "cyan" + +[log] + time = true + +[misc] + clean_on_exit = false + +[screen] + clear_on_rebuild = false + keep_scroll = true \ No newline at end of file diff --git a/sirius-api/Dockerfile b/sirius-api/Dockerfile new file mode 100644 index 0000000..c484472 --- /dev/null +++ b/sirius-api/Dockerfile @@ -0,0 +1,103 @@ +# Multi-stage Dockerfile for sirius-api +# +# system-monitor and administrator are built in this file (no external GHCR base image). + +# ───────────────────────────────────────────────────────────────────────────── +# Utility binaries: system-monitor + administrator +# ───────────────────────────────────────────────────────────────────────────── +FROM golang:1.24-alpine AS utility-go-binaries + +RUN apk add --no-cache git ca-certificates tzdata + +RUN git clone https://github.com/SiriusScan/app-system-monitor.git /tmp/system-monitor && \ + cd /tmp/system-monitor && \ + go mod download && \ + CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o /usr/local/bin/system-monitor main.go && \ + rm -rf /tmp/system-monitor + +RUN git clone https://github.com/SiriusScan/app-administrator.git /tmp/administrator && \ + cd /tmp/administrator && \ + go mod download && \ + CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o /usr/local/bin/administrator main.go && \ + rm -rf /tmp/administrator + +# ───────────────────────────────────────────────────────────────────────────── +# Development stage: for local development with volume mounts +# ───────────────────────────────────────────────────────────────────────────── +FROM golang:1.24-alpine AS development + +RUN apk add --no-cache \ + git \ + ca-certificates \ + tzdata + +RUN addgroup -g 1001 appgroup && \ + adduser -u 1001 -G appgroup -s /bin/sh -D appuser + +WORKDIR /api + +RUN chown -R appuser:appgroup /api + +COPY start-dev.sh /start-dev.sh +RUN sed -i 's/\r$//' /start-dev.sh && chmod +x /start-dev.sh + +USER appuser + +EXPOSE 9001 + +CMD ["/start-dev.sh"] + +# ───────────────────────────────────────────────────────────────────────────── +# Builder stage: compile the API binary +# ───────────────────────────────────────────────────────────────────────────── +FROM golang:1.24-alpine AS builder + +WORKDIR /app + +RUN apk add --no-cache \ + git \ + ca-certificates \ + tzdata + +# Copy source code +COPY . . + +# Use production go.mod and go.sum (without local replace directive) +RUN cp go.mod.prod go.mod && cp go.sum.prod go.sum + +RUN go mod download + +RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o sirius-api main.go + +# ───────────────────────────────────────────────────────────────────────────── +# Runtime stage +# ───────────────────────────────────────────────────────────────────────────── +FROM alpine:latest AS runner + +RUN apk --no-cache add \ + ca-certificates \ + tzdata \ + curl + +RUN addgroup -g 1001 appgroup && \ + adduser -u 1001 -G appgroup -s /bin/sh -D appuser + +WORKDIR /app + +RUN mkdir -p /system-monitor + +# Copy API binary from builder stage +COPY --from=builder /app/sirius-api /app/sirius-api + +COPY --from=utility-go-binaries /usr/local/bin/system-monitor /system-monitor/system-monitor +COPY --from=utility-go-binaries /usr/local/bin/administrator /app/administrator + +RUN chmod +x /system-monitor/system-monitor /app/administrator /app/sirius-api + +RUN chown -R appuser:appgroup /app /system-monitor + +USER appuser + +EXPOSE 9001 + +CMD ["sh", "-c", "CONTAINER_NAME=sirius-api /system-monitor/system-monitor >> /tmp/system-monitor.log 2>&1 & CONTAINER_NAME=sirius-api /app/administrator >> /tmp/administrator.log 2>&1 & /app/sirius-api"] diff --git a/sirius-api/go.mod b/sirius-api/go.mod new file mode 100755 index 0000000..b486e5a --- /dev/null +++ b/sirius-api/go.mod @@ -0,0 +1,39 @@ +module github.com/SiriusScan/sirius-api + +go 1.24.0 + +require ( + github.com/SiriusScan/go-api v0.0.18 + github.com/gofiber/fiber/v2 v2.49.2 + github.com/google/uuid v1.6.0 + gopkg.in/yaml.v3 v3.0.1 +) + +require ( + github.com/andybalholm/brotli v1.0.5 // indirect + github.com/jackc/pgpassfile v1.0.0 // indirect + github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a // indirect + github.com/jackc/pgx/v5 v5.5.5 // indirect + github.com/jackc/puddle/v2 v2.2.1 // indirect + github.com/jinzhu/inflection v1.0.0 // indirect + github.com/jinzhu/now v1.1.5 // indirect + github.com/klauspost/compress v1.17.0 // indirect + github.com/mattn/go-colorable v0.1.13 // indirect + github.com/mattn/go-isatty v0.0.20 // indirect + github.com/mattn/go-runewidth v0.0.15 // indirect + github.com/rivo/uniseg v0.4.4 // indirect + github.com/rogpeppe/go-internal v1.14.1 // indirect + github.com/streadway/amqp v1.1.0 // indirect + github.com/stretchr/testify v1.11.1 // indirect + github.com/valkey-io/valkey-go v1.0.60 // indirect + github.com/valyala/bytebufferpool v1.0.0 // indirect + github.com/valyala/fasthttp v1.50.0 // indirect + github.com/valyala/tcplisten v1.0.0 // indirect + golang.org/x/crypto v0.41.0 // indirect + golang.org/x/net v0.43.0 // indirect + golang.org/x/sync v0.16.0 // indirect + golang.org/x/sys v0.35.0 // indirect + golang.org/x/text v0.28.0 // indirect + gorm.io/driver/postgres v1.5.11 // indirect + gorm.io/gorm v1.25.12 // indirect +) diff --git a/sirius-api/go.mod.prod b/sirius-api/go.mod.prod new file mode 100755 index 0000000..b486e5a --- /dev/null +++ b/sirius-api/go.mod.prod @@ -0,0 +1,39 @@ +module github.com/SiriusScan/sirius-api + +go 1.24.0 + +require ( + github.com/SiriusScan/go-api v0.0.18 + github.com/gofiber/fiber/v2 v2.49.2 + github.com/google/uuid v1.6.0 + gopkg.in/yaml.v3 v3.0.1 +) + +require ( + github.com/andybalholm/brotli v1.0.5 // indirect + github.com/jackc/pgpassfile v1.0.0 // indirect + github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a // indirect + github.com/jackc/pgx/v5 v5.5.5 // indirect + github.com/jackc/puddle/v2 v2.2.1 // indirect + github.com/jinzhu/inflection v1.0.0 // indirect + github.com/jinzhu/now v1.1.5 // indirect + github.com/klauspost/compress v1.17.0 // indirect + github.com/mattn/go-colorable v0.1.13 // indirect + github.com/mattn/go-isatty v0.0.20 // indirect + github.com/mattn/go-runewidth v0.0.15 // indirect + github.com/rivo/uniseg v0.4.4 // indirect + github.com/rogpeppe/go-internal v1.14.1 // indirect + github.com/streadway/amqp v1.1.0 // indirect + github.com/stretchr/testify v1.11.1 // indirect + github.com/valkey-io/valkey-go v1.0.60 // indirect + github.com/valyala/bytebufferpool v1.0.0 // indirect + github.com/valyala/fasthttp v1.50.0 // indirect + github.com/valyala/tcplisten v1.0.0 // indirect + golang.org/x/crypto v0.41.0 // indirect + golang.org/x/net v0.43.0 // indirect + golang.org/x/sync v0.16.0 // indirect + golang.org/x/sys v0.35.0 // indirect + golang.org/x/text v0.28.0 // indirect + gorm.io/driver/postgres v1.5.11 // indirect + gorm.io/gorm v1.25.12 // indirect +) diff --git a/sirius-api/go.sum b/sirius-api/go.sum new file mode 100644 index 0000000..c8b3daf --- /dev/null +++ b/sirius-api/go.sum @@ -0,0 +1,86 @@ +github.com/SiriusScan/go-api v0.0.17 h1:hsAul0eeMTB8e/rwSLrx3vCO0nUW4eQuysArUcQhhkQ= +github.com/SiriusScan/go-api v0.0.17/go.mod h1:3uw5dE8qotMGDkF7AF3pwVSxcLNJY7ZI8csTXEmkOkE= +github.com/SiriusScan/go-api v0.0.18 h1:O6MLBFY2ssONkReMLT3LlLYFGBhKoWp5VOKXsTxOzOI= +github.com/SiriusScan/go-api v0.0.18/go.mod h1:3uw5dE8qotMGDkF7AF3pwVSxcLNJY7ZI8csTXEmkOkE= +github.com/andybalholm/brotli v1.0.5 h1:8uQZIdzKmjc/iuPu7O2ioW48L81FgatrcpfFmiq/cCs= +github.com/andybalholm/brotli v1.0.5/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig= +github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/gofiber/fiber/v2 v2.49.2 h1:ONEN3/Vc+dUCxxDgZZwpqvhISgHqb+bu+isBiEyKEQs= +github.com/gofiber/fiber/v2 v2.49.2/go.mod h1:gNsKnyrmfEWFpJxQAV0qvW6l70K1dZGno12oLtukcts= +github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= +github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= +github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= +github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM= +github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg= +github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a h1:bbPeKD0xmW/Y25WS6cokEszi5g+S0QxI/d45PkRi7Nk= +github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM= +github.com/jackc/pgx/v5 v5.5.5 h1:amBjrZVmksIdNjxGW/IiIMzxMKZFelXbUoPNb+8sjQw= +github.com/jackc/pgx/v5 v5.5.5/go.mod h1:ez9gk+OAat140fv9ErkZDYFWmXLfV+++K0uAOiwgm1A= +github.com/jackc/puddle/v2 v2.2.1 h1:RhxXJtFG022u4ibrCSMSiu5aOq1i77R3OHKNJj77OAk= +github.com/jackc/puddle/v2 v2.2.1/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4= +github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E= +github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc= +github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ= +github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8= +github.com/klauspost/compress v1.17.0 h1:Rnbp4K9EjcDuVuHtd0dgA4qNuv9yKDYKK1ulpJwgrqM= +github.com/klauspost/compress v1.17.0/go.mod h1:ntbaceVETuRiXiv4DpjP66DpAtAGkEQskQzEyD//IeE= +github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0= +github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk= +github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= +github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE= +github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA= +github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg= +github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM= +github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY= +github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y= +github.com/mattn/go-runewidth v0.0.15 h1:UNAjwbU9l54TA3KzvqLGxwWjHmMgBUVhBiTjelZgg3U= +github.com/mattn/go-runewidth v0.0.15/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w= +github.com/onsi/gomega v1.36.2 h1:koNYke6TVk6ZmnyHrCXba/T/MoLBXFjeC1PtvYgw0A8= +github.com/onsi/gomega v1.36.2/go.mod h1:DdwyADRjrc825LhMEkD76cHR5+pUnjhUN8GlHlRPHzY= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc= +github.com/rivo/uniseg v0.4.4 h1:8TfxU8dW6PdqD27gjM8MVNuicgxIjxpm4K7x4jp8sis= +github.com/rivo/uniseg v0.4.4/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88= +github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ= +github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc= +github.com/streadway/amqp v1.1.0 h1:py12iX8XSyI7aN/3dUT8DFIDJazNJsVJdxNVEpnQTZM= +github.com/streadway/amqp v1.1.0/go.mod h1:WYSrTEYHOXHd0nwFeUXAe2G2hRnQT+deZJJf88uS9Bg= +github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= +github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI= +github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= +github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= +github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= +github.com/valkey-io/valkey-go v1.0.60 h1:idh959D20H5n7D/kwEdTKNaMn5+4HpZTn7bLXnAhQIw= +github.com/valkey-io/valkey-go v1.0.60/go.mod h1:bHmwjIEOrGq/ubOJfh5uMRs7Xj6mV3mQ/ZXUbmqpjqY= +github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw= +github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc= +github.com/valyala/fasthttp v1.50.0 h1:H7fweIlBm0rXLs2q0XbalvJ6r0CUPFWK3/bB4N13e9M= +github.com/valyala/fasthttp v1.50.0/go.mod h1:k2zXd82h/7UZc3VOdJ2WaUqt1uZ/XpXAfE9i+HBC3lA= +github.com/valyala/tcplisten v1.0.0 h1:rBHj/Xf+E1tRGZyWIWwJDiRY0zc1Js+CV5DqwacVSA8= +github.com/valyala/tcplisten v1.0.0/go.mod h1:T0xQ8SeCZGxckz9qRXTfG43PvQ/mcWh7FwZEA7Ioqkc= +golang.org/x/crypto v0.41.0 h1:WKYxWedPGCTVVl5+WHSSrOBT0O8lx32+zxmHxijgXp4= +golang.org/x/crypto v0.41.0/go.mod h1:pO5AFd7FA68rFak7rOAGVuygIISepHftHnr8dr6+sUc= +golang.org/x/net v0.43.0 h1:lat02VYK2j4aLzMzecihNvTlJNQUq316m2Mr9rnM6YE= +golang.org/x/net v0.43.0/go.mod h1:vhO1fvI4dGsIjh73sWfUVjj3N7CA9WkKJNQm2svM6Jg= +golang.org/x/sync v0.16.0 h1:ycBJEhp9p4vXvUZNszeOq0kGTPghopOL8q0fq3vstxw= +golang.org/x/sync v0.16.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA= +golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.35.0 h1:vz1N37gP5bs89s7He8XuIYXpyY0+QlsKmzipCbUtyxI= +golang.org/x/sys v0.35.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k= +golang.org/x/text v0.28.0 h1:rhazDwis8INMIwQ4tpjLDzUhx6RlXqZNPEM0huQojng= +golang.org/x/text v0.28.0/go.mod h1:U8nCwOR8jO/marOQ0QbDiOngZVEBB7MAiitBuMjXiNU= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk= +gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q= +gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= +gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= +gorm.io/driver/postgres v1.5.11 h1:ubBVAfbKEUld/twyKZ0IYn9rSQh448EdelLYk9Mv314= +gorm.io/driver/postgres v1.5.11/go.mod h1:DX3GReXH+3FPWGrrgffdvCk3DQ1dwDPdmbenSkweRGI= +gorm.io/gorm v1.25.12 h1:I0u8i2hWQItBq1WfE0o2+WuL9+8L21K9e2HHSTE/0f8= +gorm.io/gorm v1.25.12/go.mod h1:xh7N7RHfYlNc5EmcI/El95gXusucDrQnHXe0+CgWcLQ= diff --git a/sirius-api/go.sum.prod b/sirius-api/go.sum.prod new file mode 100644 index 0000000..c8b3daf --- /dev/null +++ b/sirius-api/go.sum.prod @@ -0,0 +1,86 @@ +github.com/SiriusScan/go-api v0.0.17 h1:hsAul0eeMTB8e/rwSLrx3vCO0nUW4eQuysArUcQhhkQ= +github.com/SiriusScan/go-api v0.0.17/go.mod h1:3uw5dE8qotMGDkF7AF3pwVSxcLNJY7ZI8csTXEmkOkE= +github.com/SiriusScan/go-api v0.0.18 h1:O6MLBFY2ssONkReMLT3LlLYFGBhKoWp5VOKXsTxOzOI= +github.com/SiriusScan/go-api v0.0.18/go.mod h1:3uw5dE8qotMGDkF7AF3pwVSxcLNJY7ZI8csTXEmkOkE= +github.com/andybalholm/brotli v1.0.5 h1:8uQZIdzKmjc/iuPu7O2ioW48L81FgatrcpfFmiq/cCs= +github.com/andybalholm/brotli v1.0.5/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig= +github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/gofiber/fiber/v2 v2.49.2 h1:ONEN3/Vc+dUCxxDgZZwpqvhISgHqb+bu+isBiEyKEQs= +github.com/gofiber/fiber/v2 v2.49.2/go.mod h1:gNsKnyrmfEWFpJxQAV0qvW6l70K1dZGno12oLtukcts= +github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= +github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= +github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= +github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM= +github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg= +github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a h1:bbPeKD0xmW/Y25WS6cokEszi5g+S0QxI/d45PkRi7Nk= +github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM= +github.com/jackc/pgx/v5 v5.5.5 h1:amBjrZVmksIdNjxGW/IiIMzxMKZFelXbUoPNb+8sjQw= +github.com/jackc/pgx/v5 v5.5.5/go.mod h1:ez9gk+OAat140fv9ErkZDYFWmXLfV+++K0uAOiwgm1A= +github.com/jackc/puddle/v2 v2.2.1 h1:RhxXJtFG022u4ibrCSMSiu5aOq1i77R3OHKNJj77OAk= +github.com/jackc/puddle/v2 v2.2.1/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4= +github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E= +github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc= +github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ= +github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8= +github.com/klauspost/compress v1.17.0 h1:Rnbp4K9EjcDuVuHtd0dgA4qNuv9yKDYKK1ulpJwgrqM= +github.com/klauspost/compress v1.17.0/go.mod h1:ntbaceVETuRiXiv4DpjP66DpAtAGkEQskQzEyD//IeE= +github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0= +github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk= +github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= +github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE= +github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA= +github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg= +github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM= +github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY= +github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y= +github.com/mattn/go-runewidth v0.0.15 h1:UNAjwbU9l54TA3KzvqLGxwWjHmMgBUVhBiTjelZgg3U= +github.com/mattn/go-runewidth v0.0.15/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w= +github.com/onsi/gomega v1.36.2 h1:koNYke6TVk6ZmnyHrCXba/T/MoLBXFjeC1PtvYgw0A8= +github.com/onsi/gomega v1.36.2/go.mod h1:DdwyADRjrc825LhMEkD76cHR5+pUnjhUN8GlHlRPHzY= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc= +github.com/rivo/uniseg v0.4.4 h1:8TfxU8dW6PdqD27gjM8MVNuicgxIjxpm4K7x4jp8sis= +github.com/rivo/uniseg v0.4.4/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88= +github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ= +github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc= +github.com/streadway/amqp v1.1.0 h1:py12iX8XSyI7aN/3dUT8DFIDJazNJsVJdxNVEpnQTZM= +github.com/streadway/amqp v1.1.0/go.mod h1:WYSrTEYHOXHd0nwFeUXAe2G2hRnQT+deZJJf88uS9Bg= +github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= +github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI= +github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= +github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= +github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= +github.com/valkey-io/valkey-go v1.0.60 h1:idh959D20H5n7D/kwEdTKNaMn5+4HpZTn7bLXnAhQIw= +github.com/valkey-io/valkey-go v1.0.60/go.mod h1:bHmwjIEOrGq/ubOJfh5uMRs7Xj6mV3mQ/ZXUbmqpjqY= +github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw= +github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc= +github.com/valyala/fasthttp v1.50.0 h1:H7fweIlBm0rXLs2q0XbalvJ6r0CUPFWK3/bB4N13e9M= +github.com/valyala/fasthttp v1.50.0/go.mod h1:k2zXd82h/7UZc3VOdJ2WaUqt1uZ/XpXAfE9i+HBC3lA= +github.com/valyala/tcplisten v1.0.0 h1:rBHj/Xf+E1tRGZyWIWwJDiRY0zc1Js+CV5DqwacVSA8= +github.com/valyala/tcplisten v1.0.0/go.mod h1:T0xQ8SeCZGxckz9qRXTfG43PvQ/mcWh7FwZEA7Ioqkc= +golang.org/x/crypto v0.41.0 h1:WKYxWedPGCTVVl5+WHSSrOBT0O8lx32+zxmHxijgXp4= +golang.org/x/crypto v0.41.0/go.mod h1:pO5AFd7FA68rFak7rOAGVuygIISepHftHnr8dr6+sUc= +golang.org/x/net v0.43.0 h1:lat02VYK2j4aLzMzecihNvTlJNQUq316m2Mr9rnM6YE= +golang.org/x/net v0.43.0/go.mod h1:vhO1fvI4dGsIjh73sWfUVjj3N7CA9WkKJNQm2svM6Jg= +golang.org/x/sync v0.16.0 h1:ycBJEhp9p4vXvUZNszeOq0kGTPghopOL8q0fq3vstxw= +golang.org/x/sync v0.16.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA= +golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.35.0 h1:vz1N37gP5bs89s7He8XuIYXpyY0+QlsKmzipCbUtyxI= +golang.org/x/sys v0.35.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k= +golang.org/x/text v0.28.0 h1:rhazDwis8INMIwQ4tpjLDzUhx6RlXqZNPEM0huQojng= +golang.org/x/text v0.28.0/go.mod h1:U8nCwOR8jO/marOQ0QbDiOngZVEBB7MAiitBuMjXiNU= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk= +gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q= +gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= +gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= +gorm.io/driver/postgres v1.5.11 h1:ubBVAfbKEUld/twyKZ0IYn9rSQh448EdelLYk9Mv314= +gorm.io/driver/postgres v1.5.11/go.mod h1:DX3GReXH+3FPWGrrgffdvCk3DQ1dwDPdmbenSkweRGI= +gorm.io/gorm v1.25.12 h1:I0u8i2hWQItBq1WfE0o2+WuL9+8L21K9e2HHSTE/0f8= +gorm.io/gorm v1.25.12/go.mod h1:xh7N7RHfYlNc5EmcI/El95gXusucDrQnHXe0+CgWcLQ= diff --git a/sirius-api/handlers/agent_template_handler.go b/sirius-api/handlers/agent_template_handler.go new file mode 100644 index 0000000..796e3da --- /dev/null +++ b/sirius-api/handlers/agent_template_handler.go @@ -0,0 +1,703 @@ +package handlers + +import ( + "context" + "encoding/json" + "fmt" + "log/slog" + "strings" + "time" + + "github.com/SiriusScan/go-api/sirius/queue" + "github.com/SiriusScan/go-api/sirius/store" + "github.com/SiriusScan/go-api/sirius/store/templates" + "github.com/gofiber/fiber/v2" + "github.com/google/uuid" + "gopkg.in/yaml.v3" +) + +// AgentVulnTemplate represents an agent vulnerability detection template +type AgentVulnTemplate struct { + ID string `json:"id"` + Name string `json:"name"` + Description string `json:"description"` + Type string `json:"type"` // "standard" or "custom" + Severity string `json:"severity"` + Author string `json:"author"` + Platforms []string `json:"platforms"` + Version string `json:"version"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` + Content string `json:"content,omitempty"` // YAML content +} + +// AgentTemplateJSON represents the JSON structure stored in Valkey +type AgentTemplateJSON struct { + ID string `json:"id"` + Version string `json:"version"` + Checksum string `json:"checksum"` + Size int `json:"size"` + Severity string `json:"severity"` + Platforms []string `json:"platforms"` + DetectionType string `json:"detection_type"` + Author string `json:"author"` + Content string `json:"content"` // base64 encoded YAML + VulnerabilityIDs []string `json:"vulnerability_ids"` +} + +// AgentTemplateYAML represents the decoded YAML content structure +// Supports both old format (metadata at root) and new format (metadata under info) +type AgentTemplateYAML struct { + ID string `yaml:"id"` + Name string `yaml:"name"` // Legacy: at root level + Author string `yaml:"author"` // Legacy: at root level + Severity string `yaml:"severity"` // Legacy: at root level + Description string `yaml:"description"` // Legacy: at root level + Version string `yaml:"version"` // Legacy: at root level + Tags []string `yaml:"tags"` // Legacy: at root level + Info struct { + Name string `yaml:"name"` + Author string `yaml:"author"` + Severity string `yaml:"severity"` + Description string `yaml:"description"` + Version string `yaml:"version"` + Tags []string `yaml:"tags"` + } `yaml:"info"` + Detection struct { + Steps []map[string]interface{} `yaml:"steps"` + } `yaml:"detection"` +} + +// GetName returns name from info section or root level +func (t *AgentTemplateYAML) GetName() string { + if t.Info.Name != "" { + return t.Info.Name + } + return t.Name +} + +// GetAuthor returns author from info section or root level +func (t *AgentTemplateYAML) GetAuthor() string { + if t.Info.Author != "" { + return t.Info.Author + } + return t.Author +} + +// GetSeverity returns severity from info section or root level +func (t *AgentTemplateYAML) GetSeverity() string { + if t.Info.Severity != "" { + return t.Info.Severity + } + return t.Severity +} + +// GetDescription returns description from info section or root level +func (t *AgentTemplateYAML) GetDescription() string { + if t.Info.Description != "" { + return t.Info.Description + } + return t.Description +} + +// GetVersion returns version from info section or root level +func (t *AgentTemplateYAML) GetVersion() string { + if t.Info.Version != "" { + return t.Info.Version + } + return t.Version +} + +const ( + agentTemplateSyncQueue = "agent.template.sync.jobs" +) + +// templateSyncJobMessage mirrors app-agent's server.SyncJobMessage. Used +// to publish notify_agents requests on agent.template.sync.jobs. +type templateSyncJobMessage struct { + Action string `json:"action"` + TemplateID string `json:"template_id,omitempty"` + TriggeredBy string `json:"triggered_by"` + Timestamp string `json:"timestamp"` + JobID string `json:"job_id"` +} + +// detectionTypeFromYAML extracts the first detection step's "type" field. +// Mirrors app-agent's getDetectionType helper closely enough that meta +// records written here look like ones the agent-side sync writer emits. +func detectionTypeFromYAML(t *AgentTemplateYAML) string { + for _, step := range t.Detection.Steps { + if v, ok := step["type"].(string); ok && v != "" { + return v + } + } + return "" +} + +// platformsFromYAML mirrors the platform extraction used elsewhere in +// this handler. Returns the first non-empty platforms list it finds in +// detection steps; defaults to ["linux"] for parity with the read path. +func platformsFromYAML(t *AgentTemplateYAML) []string { + for _, step := range t.Detection.Steps { + if p, ok := step["platforms"].([]interface{}); ok && len(p) > 0 { + out := make([]string, len(p)) + for i, v := range p { + out[i] = fmt.Sprintf("%v", v) + } + return out + } + } + return []string{"linux"} +} + +// buildTemplateRecord builds a templates.TemplateRecord ready to hand +// to templates.WriteTemplate. Returned alongside the checksum so the +// HTTP layer can echo it back to the caller for verification. +func buildTemplateRecord(yamlTemplate *AgentTemplateYAML, rawYAML []byte, isCustom bool, createdAt time.Time) (*templates.TemplateRecord, string, error) { + checksum := templates.SHA256Hex(rawYAML) + + now := time.Now().UTC() + if createdAt.IsZero() { + createdAt = now + } + + rec := &templates.TemplateRecord{ + ID: yamlTemplate.ID, + Version: yamlTemplate.GetVersion(), + Checksum: checksum, + Size: int64(len(rawYAML)), + Severity: yamlTemplate.GetSeverity(), + Platforms: platformsFromYAML(yamlTemplate), + DetectionType: detectionTypeFromYAML(yamlTemplate), + Author: yamlTemplate.GetAuthor(), + Created: createdAt, + Updated: now, + VulnerabilityIDs: nil, + IsCustom: isCustom, + Content: rawYAML, + Metadata: map[string]string{"source": "sirius-api-upload"}, + } + return rec, checksum, nil +} + +// publishNotifyAgents publishes a notify_agents sync job so connected +// agents re-pull the template inventory. Best-effort: returns the +// underlying error but the caller decides whether to fail the request. +func publishNotifyAgents(templateID, triggeredBy string) error { + msg := templateSyncJobMessage{ + Action: "notify_agents", + TemplateID: templateID, + TriggeredBy: triggeredBy, + Timestamp: time.Now().UTC().Format(time.RFC3339), + JobID: uuid.New().String(), + } + data, err := json.Marshal(msg) + if err != nil { + return fmt.Errorf("marshal sync message: %w", err) + } + return queue.Send(agentTemplateSyncQueue, string(data)) +} + +// GetAgentTemplates returns all agent templates from Valkey +func GetAgentTemplates(c *fiber.Ctx) error { + ctx := context.Background() + + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to database", + }) + } + defer kvStore.Close() + + // Query both standard and custom template keys separately to avoid metadata/version keys + standardKeys, err := kvStore.ListKeys(ctx, templates.KeyAgentTemplateStandardPrefix+"*") + if err != nil { + slog.Warn("Failed to retrieve standard templates", "error", err) + standardKeys = []string{} + } + + customKeys, err := kvStore.ListKeys(ctx, templates.KeyAgentTemplateCustomPrefix+"*") + if err != nil { + slog.Warn("Failed to retrieve custom templates", "error", err) + customKeys = []string{} + } + + keys := append(standardKeys, customKeys...) + out := []AgentVulnTemplate{} + + for _, key := range keys { + templateResp, err := kvStore.GetValue(ctx, key) + if err != nil { + slog.Warn("Failed to get template", "key", key, "error", err) + continue + } + rec, decErr := templates.DecodeTemplate([]byte(templateResp.Message.Value)) + if decErr != nil { + slog.Warn("Failed to decode template envelope", "key", key, "error", decErr) + continue + } + + var yamlTemplate AgentTemplateYAML + if err := yaml.Unmarshal(rec.Content, &yamlTemplate); err != nil { + slog.Warn("Failed to parse YAML template", "key", key, "error", err) + continue + } + + templateType := "repository" + if rec.IsCustom || strings.Contains(key, ":custom:") { + templateType = "custom" + } + + // Determine platforms from detection steps + platforms := []string{"linux"} // default + if len(yamlTemplate.Detection.Steps) > 0 { + for _, step := range yamlTemplate.Detection.Steps { + if p, ok := step["platforms"].([]interface{}); ok && len(p) > 0 { + platforms = make([]string, len(p)) + for i, plat := range p { + platforms[i] = fmt.Sprintf("%v", plat) + } + break + } + } + } + + // Create template from YAML metadata (supports both old and new format) + template := AgentVulnTemplate{ + ID: yamlTemplate.ID, + Name: yamlTemplate.GetName(), + Description: yamlTemplate.GetDescription(), + Type: templateType, + Severity: yamlTemplate.GetSeverity(), + Author: yamlTemplate.GetAuthor(), + Platforms: platforms, + Version: yamlTemplate.GetVersion(), + CreatedAt: time.Now(), + UpdatedAt: time.Now(), + } + + out = append(out, template) + } + + return c.JSON(out) +} + +// GetAgentTemplate returns a specific template with full content +func GetAgentTemplate(c *fiber.Ctx) error { + ctx := context.Background() + templateID := c.Params("id") + + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to database", + }) + } + defer kvStore.Close() + + rec, err := templates.ReadTemplate(ctx, kvStore, templateID) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to decode template", + }) + } + if rec == nil { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": "Template not found", + }) + } + + yamlContent := string(rec.Content) + var yamlTemplate AgentTemplateYAML + if err := yaml.Unmarshal(rec.Content, &yamlTemplate); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to parse template", + }) + } + + platforms := []string{"linux"} + for _, step := range yamlTemplate.Detection.Steps { + if p, ok := step["platforms"].([]interface{}); ok { + platforms = make([]string, len(p)) + for i, plat := range p { + platforms[i] = fmt.Sprintf("%v", plat) + } + break + } + } + + templateType := "repository" + if rec.IsCustom { + templateType = "custom" + } + + template := AgentVulnTemplate{ + ID: yamlTemplate.ID, + Name: yamlTemplate.GetName(), + Description: yamlTemplate.GetDescription(), + Type: templateType, + Severity: yamlTemplate.GetSeverity(), + Author: yamlTemplate.GetAuthor(), + Platforms: platforms, + Version: yamlTemplate.GetVersion(), + CreatedAt: rec.Created, + UpdatedAt: rec.Updated, + Content: yamlContent, + } + + return c.JSON(template) +} + +// UploadAgentTemplate uploads a new custom template +func UploadAgentTemplate(c *fiber.Ctx) error { + ctx := context.Background() + + type UploadRequest struct { + Content string `json:"content"` + Filename string `json:"filename"` + Author string `json:"author,omitempty"` + } + + var request UploadRequest + if err := c.BodyParser(&request); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Invalid request body", + }) + } + + // Parse YAML + var yamlTemplate AgentTemplateYAML + if err := yaml.Unmarshal([]byte(request.Content), &yamlTemplate); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Invalid YAML format", + }) + } + + // Validate required fields + if yamlTemplate.ID == "" || yamlTemplate.Info.Name == "" || yamlTemplate.Info.Severity == "" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Template missing required fields (id, info.name, info.severity)", + }) + } + + if request.Author != "" { + yamlTemplate.Info.Author = request.Author + updatedYAML, mErr := yaml.Marshal(yamlTemplate) + if mErr == nil { + request.Content = string(updatedYAML) + } + } + rawYAML := []byte(request.Content) + + rec, checksum, err := buildTemplateRecord(&yamlTemplate, rawYAML, true, time.Time{}) + if err != nil { + slog.Error("Failed to build template record", "id", yamlTemplate.ID, "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to encode template", + }) + } + + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to database", + }) + } + defer kvStore.Close() + + if err := templates.WriteTemplate(ctx, kvStore, rec); err != nil { + slog.Error("Failed to persist template", "id", yamlTemplate.ID, "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to store template", + }) + } + + if err := publishNotifyAgents(yamlTemplate.ID, "sirius-api"); err != nil { + slog.Warn("Failed to publish notify_agents", "id", yamlTemplate.ID, "error", err) + } + + return c.JSON(fiber.Map{ + "id": yamlTemplate.ID, + "checksum": checksum, + "message": "Template uploaded successfully", + }) +} + +// ValidateAgentTemplate validates a template without storing +func ValidateAgentTemplate(c *fiber.Ctx) error { + type ValidateRequest struct { + Content string `json:"content"` + } + + var request ValidateRequest + if err := c.BodyParser(&request); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "valid": false, + "errors": []string{"Invalid request body"}, + }) + } + + var yamlTemplate AgentTemplateYAML + if err := yaml.Unmarshal([]byte(request.Content), &yamlTemplate); err != nil { + return c.JSON(fiber.Map{ + "valid": false, + "errors": []string{fmt.Sprintf("Invalid YAML: %v", err)}, + }) + } + + errors := []string{} + warnings := []string{} + + if yamlTemplate.ID == "" { + errors = append(errors, "Missing required field: id") + } + if yamlTemplate.Info.Name == "" { + errors = append(errors, "Missing required field: info.name") + } + if yamlTemplate.Info.Severity == "" { + errors = append(errors, "Missing required field: info.severity") + } + if yamlTemplate.Info.Description == "" { + warnings = append(warnings, "Missing recommended field: info.description") + } + + return c.JSON(fiber.Map{ + "valid": len(errors) == 0, + "errors": errors, + "warnings": warnings, + }) +} + +// DeleteAgentTemplate deletes a custom template +func DeleteAgentTemplate(c *fiber.Ctx) error { + ctx := context.Background() + templateID := c.Params("id") + + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to database", + }) + } + defer kvStore.Close() + + templateKey := templates.AgentTemplateKey(templateID, true) + metaKey := templates.AgentTemplateMetaKey(templateID) + if err := kvStore.DeleteValue(ctx, templateKey); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to delete template", + }) + } + if err := kvStore.DeleteValue(ctx, metaKey); err != nil { + // Best-effort: a stale meta entry without the envelope would + // surface as a missing template on enumeration; log and move on. + slog.Warn("Failed to delete template meta", "id", templateID, "error", err) + } + + if err := publishNotifyAgents(templateID, "sirius-api"); err != nil { + slog.Warn("Failed to publish notify_agents on delete", "id", templateID, "error", err) + } + + return c.JSON(fiber.Map{ + "message": "Template deleted", + }) +} + +// TestAgentTemplate runs a template on a specific agent +func TestAgentTemplate(c *fiber.Ctx) error { + templateID := c.Params("id") + + type TestRequest struct { + AgentID string `json:"agentId"` + } + + var request TestRequest + if err := c.BodyParser(&request); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Invalid request body", + }) + } + request.AgentID = strings.TrimSpace(request.AgentID) + if request.AgentID == "" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "agentId is required", + }) + } + if len(request.AgentID) > 128 { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "agentId is too long", + }) + } + + // Validate the requested agent is currently known/connected. + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to store", + }) + } + defer kvStore.Close() + + connectedAgentsResp, err := kvStore.GetValue(c.Context(), "connected_agents") + if err != nil { + return c.Status(fiber.StatusServiceUnavailable).JSON(fiber.Map{ + "error": "No connected agents available", + }) + } + + var connectedAgents []string + if err := json.Unmarshal([]byte(connectedAgentsResp.Message.Value), &connectedAgents); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to read connected agent list", + }) + } + + agentFound := false + for _, agentID := range connectedAgents { + if agentID == request.AgentID { + agentFound = true + break + } + } + if !agentFound { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Requested agent is not connected", + }) + } + + // Send command to agent + message := map[string]interface{}{ + "command": fmt.Sprintf("internal:template-scan --template %s", templateID), + "template_id": templateID, + "agent_id": request.AgentID, + "timestamp": time.Now().Format(time.RFC3339), + } + + msgBytes, _ := json.Marshal(message) + agentQueue := fmt.Sprintf("agent.%s.commands", request.AgentID) + + if err := queue.Send(agentQueue, string(msgBytes)); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to send test command", + }) + } + + return c.JSON(fiber.Map{ + "message": "Template test initiated", + "agent_id": request.AgentID, + "template_id": templateID, + }) +} + +// UpdateAgentTemplate replaces an existing custom template's envelope + +// meta records and triggers an agent re-pull. Built-in (non-custom) +// templates remain editable for parity with the upload path, but the +// `is_custom` flag and original `created` timestamp on the existing +// meta record are preserved so we never silently flip a built-in into +// a custom one (or vice versa) just because someone hit Save. +func UpdateAgentTemplate(c *fiber.Ctx) error { + ctx := context.Background() + templateID := strings.TrimSpace(c.Params("id")) + if templateID == "" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Template id is required", + }) + } + + type UpdateRequest struct { + Content string `json:"content"` + Filename string `json:"filename,omitempty"` + Author string `json:"author,omitempty"` + } + + var request UpdateRequest + if err := c.BodyParser(&request); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Invalid request body", + }) + } + + var yamlTemplate AgentTemplateYAML + if err := yaml.Unmarshal([]byte(request.Content), &yamlTemplate); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Invalid YAML format", + }) + } + + if yamlTemplate.ID == "" || yamlTemplate.GetName() == "" || yamlTemplate.GetSeverity() == "" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Template missing required fields (id, info.name, info.severity)", + }) + } + + if yamlTemplate.ID != templateID { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": fmt.Sprintf("URL id %q does not match YAML id %q", templateID, yamlTemplate.ID), + }) + } + + if request.Author != "" { + yamlTemplate.Info.Author = request.Author + updatedYAML, mErr := yaml.Marshal(yamlTemplate) + if mErr == nil { + request.Content = string(updatedYAML) + } + } + rawYAML := []byte(request.Content) + + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to database", + }) + } + defer kvStore.Close() + + existing, err := templates.ReadTemplateMeta(ctx, kvStore, templateID) + if err != nil { + slog.Warn("Failed to read existing meta", "id", templateID, "error", err) + } + if existing == nil { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": "Template not found", + }) + } + + rec, checksum, err := buildTemplateRecord(&yamlTemplate, rawYAML, existing.IsCustom, existing.Created) + if err != nil { + slog.Error("Failed to build template record", "id", templateID, "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to encode template", + }) + } + + if err := templates.WriteTemplate(ctx, kvStore, rec); err != nil { + slog.Error("Failed to persist template", "id", templateID, "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to store template", + }) + } + + if err := publishNotifyAgents(templateID, "sirius-api"); err != nil { + slog.Warn("Failed to publish notify_agents", "id", templateID, "error", err) + } + + return c.JSON(fiber.Map{ + "id": templateID, + "checksum": checksum, + "message": "Template updated successfully", + }) +} + +func DeployAgentTemplate(c *fiber.Ctx) error { + return c.JSON(fiber.Map{"message": "Deploy not yet implemented"}) +} + +func GetAgentTemplateAnalytics(c *fiber.Ctx) error { + return c.JSON(fiber.Map{"message": "Analytics not yet implemented"}) +} + +func GetAgentTemplateResults(c *fiber.Ctx) error { + return c.JSON(fiber.Map{"message": "Results not yet implemented"}) +} diff --git a/sirius-api/handlers/agent_template_handler_test.go b/sirius-api/handlers/agent_template_handler_test.go new file mode 100644 index 0000000..63082af --- /dev/null +++ b/sirius-api/handlers/agent_template_handler_test.go @@ -0,0 +1,193 @@ +package handlers + +import ( + "encoding/base64" + "encoding/json" + "strings" + "testing" + "time" + + "github.com/SiriusScan/go-api/sirius/store/templates" + "gopkg.in/yaml.v3" +) + +const fixtureYAML = `id: test-cve-2026-0001 +info: + name: Test CVE 2026-0001 + author: tester + severity: high + description: Detects a fictional vulnerability used in unit tests. + version: 1.0.0 + tags: + - test +detection: + steps: + - type: command + platforms: + - linux + - darwin + command: "echo vulnerable" +` + +func parseFixture(t *testing.T) *AgentTemplateYAML { + t.Helper() + var tpl AgentTemplateYAML + if err := yaml.Unmarshal([]byte(fixtureYAML), &tpl); err != nil { + t.Fatalf("failed to parse fixture YAML: %v", err) + } + return &tpl +} + +func TestBuildTemplateRecord_EnvelopeShape(t *testing.T) { + tpl := parseFixture(t) + raw := []byte(fixtureYAML) + + rec, checksum, err := buildTemplateRecord(tpl, raw, true, time.Time{}) + if err != nil { + t.Fatalf("buildTemplateRecord returned error: %v", err) + } + if checksum == "" { + t.Fatal("expected non-empty checksum") + } + + envBytes, err := templates.EncodeTemplate(rec) + if err != nil { + t.Fatalf("EncodeTemplate: %v", err) + } + metaBytes, err := templates.EncodeMeta(rec) + if err != nil { + t.Fatalf("EncodeMeta: %v", err) + } + + var envelope templates.TemplateRecord + if err := json.Unmarshal(envBytes, &envelope); err != nil { + t.Fatalf("envelope is not valid JSON of TemplateRecord: %v", err) + } + + if envelope.ID != "test-cve-2026-0001" { + t.Errorf("envelope ID mismatch: got %q", envelope.ID) + } + if envelope.Severity != "high" { + t.Errorf("envelope Severity mismatch: got %q", envelope.Severity) + } + if envelope.DetectionType != "command" { + t.Errorf("envelope DetectionType mismatch: got %q", envelope.DetectionType) + } + if !envelope.IsCustom { + t.Error("envelope IsCustom should be true for custom uploads") + } + if envelope.Checksum != checksum { + t.Errorf("envelope Checksum %q != returned checksum %q", envelope.Checksum, checksum) + } + if envelope.Size != int64(len(raw)) { + t.Errorf("envelope Size %d != raw len %d", envelope.Size, len(raw)) + } + if string(envelope.Content) != string(raw) { + t.Error("envelope Content should round-trip to the original raw YAML bytes") + } + if got, want := envelope.Platforms, []string{"linux", "darwin"}; !equalStrings(got, want) { + t.Errorf("envelope Platforms = %v, want %v", got, want) + } + + // JSON wire shape: Content must serialize as base64 string under "content". + var raw1 map[string]any + if err := json.Unmarshal(envBytes, &raw1); err != nil { + t.Fatalf("envelope is not generic JSON: %v", err) + } + contentStr, ok := raw1["content"].(string) + if !ok { + t.Fatalf("envelope.content must be a base64 string on the wire; got %T", raw1["content"]) + } + decoded, err := base64.StdEncoding.DecodeString(contentStr) + if err != nil { + t.Fatalf("envelope.content is not valid base64: %v", err) + } + if string(decoded) != fixtureYAML { + t.Error("base64-decoded content does not match the original raw YAML") + } + + var meta templates.TemplateRecord + if err := json.Unmarshal(metaBytes, &meta); err != nil { + t.Fatalf("meta is not valid JSON: %v", err) + } + if len(meta.Content) != 0 { + t.Error("meta record must omit Content") + } + if !meta.IsCustom { + t.Error("meta IsCustom should be true for custom uploads") + } + if meta.ID != envelope.ID || meta.Checksum != envelope.Checksum { + t.Error("meta record core identity fields must match envelope") + } +} + +func TestBuildTemplateRecord_DetectionTypeFallback(t *testing.T) { + const noStepsYAML = `id: empty-detect +info: + name: empty + author: t + severity: low +detection: {} +` + var tpl AgentTemplateYAML + if err := yaml.Unmarshal([]byte(noStepsYAML), &tpl); err != nil { + t.Fatal(err) + } + rec, _, err := buildTemplateRecord(&tpl, []byte(noStepsYAML), true, time.Time{}) + if err != nil { + t.Fatal(err) + } + envBytes, err := templates.EncodeTemplate(rec) + if err != nil { + t.Fatalf("EncodeTemplate: %v", err) + } + if !strings.Contains(string(envBytes), `"detection_type":""`) { + t.Errorf("expected empty detection_type when no steps; got: %s", envBytes) + } +} + +// TestBuildTemplateRecord_PreservesCreated covers the update path: when +// UpdateAgentTemplate reads the existing meta and re-builds the record, +// it passes through the original `created` timestamp and the original +// `is_custom` flag (so editing a built-in does not silently flip it to +// custom). The envelope's `updated` field still moves to "now". +func TestBuildTemplateRecord_PreservesCreated(t *testing.T) { + tpl := parseFixture(t) + raw := []byte(fixtureYAML) + original := time.Date(2025, 1, 2, 3, 4, 5, 0, time.UTC) + + rec, _, err := buildTemplateRecord(tpl, raw, false, original) + if err != nil { + t.Fatalf("buildTemplateRecord returned error: %v", err) + } + envBytes, err := templates.EncodeTemplate(rec) + if err != nil { + t.Fatalf("EncodeTemplate: %v", err) + } + + var envelope templates.TemplateRecord + if err := json.Unmarshal(envBytes, &envelope); err != nil { + t.Fatalf("envelope decode: %v", err) + } + if !envelope.Created.Equal(original) { + t.Errorf("Created should be preserved; got %v want %v", envelope.Created, original) + } + if envelope.IsCustom { + t.Error("IsCustom should remain false when caller passes false (built-in edit)") + } + if envelope.Updated.Before(original) || envelope.Updated.Equal(original) { + t.Errorf("Updated should advance past Created; got Updated=%v Created=%v", envelope.Updated, original) + } +} + +func equalStrings(a, b []string) bool { + if len(a) != len(b) { + return false + } + for i := range a { + if a[i] != b[i] { + return false + } + } + return true +} diff --git a/sirius-api/handlers/agent_template_repository_handler.go b/sirius-api/handlers/agent_template_repository_handler.go new file mode 100644 index 0000000..37169d4 --- /dev/null +++ b/sirius-api/handlers/agent_template_repository_handler.go @@ -0,0 +1,537 @@ +package handlers + +import ( + "context" + "encoding/json" + "fmt" + "log/slog" + "time" + + "github.com/SiriusScan/go-api/sirius/queue" + "github.com/SiriusScan/go-api/sirius/store" + "github.com/gofiber/fiber/v2" + "github.com/google/uuid" +) + +const ( + repositoryManifestKey = "sirius:agent-templates:repositories" + syncJobQueue = "agent.template.sync.jobs" +) + +// AgentTemplateRepository represents a template repository +type AgentTemplateRepository struct { + ID string `json:"id"` + Name string `json:"name"` + URL string `json:"url"` + Branch string `json:"branch"` + Priority int `json:"priority"` + Enabled bool `json:"enabled"` + LastSync *string `json:"last_sync"` + TemplateCount int `json:"template_count"` + Status string `json:"status"` + ErrorMessage *string `json:"error_message"` + CreatedAt string `json:"created_at"` + UpdatedAt string `json:"updated_at"` +} + +// RepositoryManifest represents the repository list structure in Valkey +type RepositoryManifest struct { + Repositories []AgentTemplateRepository `json:"repositories"` + Version string `json:"version"` + UpdatedAt string `json:"updated_at"` +} + +// SyncJobMessage represents a RabbitMQ sync job message +type SyncJobMessage struct { + Action string `json:"action"` + RepositoryID string `json:"repository_id,omitempty"` + RepositoryURL string `json:"repository_url,omitempty"` + RepositoryBranch string `json:"repository_branch,omitempty"` + TriggeredBy string `json:"triggered_by"` + Timestamp string `json:"timestamp"` + JobID string `json:"job_id"` +} + +// GetAgentTemplateRepositories returns all repositories +func GetAgentTemplateRepositories(c *fiber.Ctx) error { + ctx := context.Background() + + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to database", + }) + } + defer kvStore.Close() + + // Get repository manifest from Valkey + resp, err := kvStore.GetValue(ctx, repositoryManifestKey) + if err != nil { + // No repositories exist - initialize default repository + slog.Info("No repositories found, initializing default repository") + if err := initializeDefaultRepository(ctx, kvStore); err != nil { + slog.Warn("Failed to initialize default repository", "error", err) + // Return empty list even if initialization fails + return c.JSON([]AgentTemplateRepository{}) + } + // Retry getting the manifest after initialization + resp, err = kvStore.GetValue(ctx, repositoryManifestKey) + if err != nil { + return c.JSON([]AgentTemplateRepository{}) + } + } + + var manifest RepositoryManifest + if err := json.Unmarshal([]byte(resp.Message.Value), &manifest); err != nil { + slog.Error("Error parsing repository manifest", "error", err) + return c.JSON([]AgentTemplateRepository{}) + } + + // If manifest exists but has no repositories, initialize default + if len(manifest.Repositories) == 0 { + slog.Info("Repository manifest empty, initializing default repository") + if err := initializeDefaultRepository(ctx, kvStore); err != nil { + slog.Warn("Failed to initialize default repository", "error", err) + } else { + // Retry getting the manifest after initialization + resp, err = kvStore.GetValue(ctx, repositoryManifestKey) + if err == nil { + if err := json.Unmarshal([]byte(resp.Message.Value), &manifest); err == nil { + return c.JSON(manifest.Repositories) + } + } + } + } + + return c.JSON(manifest.Repositories) +} + +// initializeDefaultRepository creates the default repository if it doesn't exist +func initializeDefaultRepository(ctx context.Context, kvStore store.KVStore) error { + now := time.Now().Format(time.RFC3339) + defaultRepo := AgentTemplateRepository{ + ID: "default-sirius-official", + Name: "Sirius Official", + URL: "https://github.com/SiriusScan/sirius-agent-modules", + Branch: "main", + Priority: 1, + Enabled: true, + LastSync: nil, + TemplateCount: 0, + Status: "never_synced", + ErrorMessage: nil, + CreatedAt: now, + UpdatedAt: now, + } + + manifest := RepositoryManifest{ + Repositories: []AgentTemplateRepository{defaultRepo}, + Version: "1.0", + UpdatedAt: now, + } + + return saveRepositoryManifest(ctx, kvStore, &manifest) +} + +// AddAgentTemplateRepository adds a new repository +func AddAgentTemplateRepository(c *fiber.Ctx) error { + ctx := context.Background() + + type AddRequest struct { + Name string `json:"name"` + URL string `json:"url"` + Branch string `json:"branch"` + Priority int `json:"priority"` + Enabled bool `json:"enabled"` + } + + var request AddRequest + if err := c.BodyParser(&request); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Invalid request body", + }) + } + + // Validate required fields + if request.Name == "" || request.URL == "" || request.Branch == "" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Missing required fields: name, url, branch", + }) + } + + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to database", + }) + } + defer kvStore.Close() + + // Load existing manifest + manifest, err := loadRepositoryManifest(ctx, kvStore) + if err != nil { + // Initialize new manifest if it doesn't exist + manifest = &RepositoryManifest{ + Repositories: []AgentTemplateRepository{}, + Version: "1.0", + UpdatedAt: time.Now().Format(time.RFC3339), + } + } + + // Check if repository with this name already exists + for _, repo := range manifest.Repositories { + if repo.Name == request.Name { + return c.Status(fiber.StatusConflict).JSON(fiber.Map{ + "error": fmt.Sprintf("Repository with name '%s' already exists", request.Name), + }) + } + } + + // Create new repository + now := time.Now().Format(time.RFC3339) + newRepo := AgentTemplateRepository{ + ID: uuid.New().String(), + Name: request.Name, + URL: request.URL, + Branch: request.Branch, + Priority: request.Priority, + Enabled: request.Enabled, + LastSync: nil, + TemplateCount: 0, + Status: "never_synced", + ErrorMessage: nil, + CreatedAt: now, + UpdatedAt: now, + } + + // Add to manifest + manifest.Repositories = append(manifest.Repositories, newRepo) + manifest.UpdatedAt = now + + // Save manifest + if err := saveRepositoryManifest(ctx, kvStore, manifest); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to save repository", + }) + } + + // Publish sync message to RabbitMQ + jobID := uuid.New().String() + syncMsg := SyncJobMessage{ + Action: "sync_repository", + RepositoryID: newRepo.ID, + RepositoryURL: newRepo.URL, + RepositoryBranch: newRepo.Branch, + TriggeredBy: "user", + Timestamp: now, + JobID: jobID, + } + + if err := publishSyncJob(syncMsg); err != nil { + slog.Warn("Failed to publish sync job", "error", err) + // Don't fail the request, sync can happen later + } + + return c.Status(fiber.StatusCreated).JSON(newRepo) +} + +// UpdateAgentTemplateRepository updates an existing repository +func UpdateAgentTemplateRepository(c *fiber.Ctx) error { + ctx := context.Background() + repoID := c.Params("id") + + type UpdateRequest struct { + Name *string `json:"name,omitempty"` + URL *string `json:"url,omitempty"` + Branch *string `json:"branch,omitempty"` + Priority *int `json:"priority,omitempty"` + Enabled *bool `json:"enabled,omitempty"` + } + + var request UpdateRequest + if err := c.BodyParser(&request); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Invalid request body", + }) + } + + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to database", + }) + } + defer kvStore.Close() + + // Load manifest + manifest, err := loadRepositoryManifest(ctx, kvStore) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to load repositories", + }) + } + + // Find repository to update + var updated *AgentTemplateRepository + urlChanged := false + branchChanged := false + + for i := range manifest.Repositories { + if manifest.Repositories[i].ID == repoID { + if request.Name != nil { + manifest.Repositories[i].Name = *request.Name + } + if request.URL != nil && *request.URL != manifest.Repositories[i].URL { + manifest.Repositories[i].URL = *request.URL + urlChanged = true + } + if request.Branch != nil && *request.Branch != manifest.Repositories[i].Branch { + manifest.Repositories[i].Branch = *request.Branch + branchChanged = true + } + if request.Priority != nil { + manifest.Repositories[i].Priority = *request.Priority + } + if request.Enabled != nil { + manifest.Repositories[i].Enabled = *request.Enabled + } + manifest.Repositories[i].UpdatedAt = time.Now().Format(time.RFC3339) + updated = &manifest.Repositories[i] + break + } + } + + if updated == nil { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": "Repository not found", + }) + } + + manifest.UpdatedAt = time.Now().Format(time.RFC3339) + + // Save manifest + if err := saveRepositoryManifest(ctx, kvStore, manifest); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to update repository", + }) + } + + // If URL or branch changed, trigger resync + if urlChanged || branchChanged { + jobID := uuid.New().String() + syncMsg := SyncJobMessage{ + Action: "sync_repository", + RepositoryID: updated.ID, + RepositoryURL: updated.URL, + RepositoryBranch: updated.Branch, + TriggeredBy: "user", + Timestamp: time.Now().Format(time.RFC3339), + JobID: jobID, + } + + if err := publishSyncJob(syncMsg); err != nil { + slog.Warn("Failed to publish sync job", "error", err) + } + } + + return c.JSON(updated) +} + +// DeleteAgentTemplateRepository deletes a repository +func DeleteAgentTemplateRepository(c *fiber.Ctx) error { + ctx := context.Background() + repoID := c.Params("id") + + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to database", + }) + } + defer kvStore.Close() + + // Load manifest + manifest, err := loadRepositoryManifest(ctx, kvStore) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to load repositories", + }) + } + + // Find and remove repository + found := false + newRepositories := []AgentTemplateRepository{} + for _, repo := range manifest.Repositories { + if repo.ID == repoID { + found = true + continue + } + newRepositories = append(newRepositories, repo) + } + + if !found { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": "Repository not found", + }) + } + + manifest.Repositories = newRepositories + manifest.UpdatedAt = time.Now().Format(time.RFC3339) + + // Save manifest + if err := saveRepositoryManifest(ctx, kvStore, manifest); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to delete repository", + }) + } + + // Publish cleanup message + jobID := uuid.New().String() + syncMsg := SyncJobMessage{ + Action: "delete_repository", + RepositoryID: repoID, + TriggeredBy: "user", + Timestamp: time.Now().Format(time.RFC3339), + JobID: jobID, + } + + if err := publishSyncJob(syncMsg); err != nil { + slog.Warn("Failed to publish cleanup job", "error", err) + } + + return c.JSON(fiber.Map{ + "message": "Repository deleted successfully", + }) +} + +// TriggerAgentTemplateRepositorySync triggers a manual sync +func TriggerAgentTemplateRepositorySync(c *fiber.Ctx) error { + ctx := context.Background() + repoID := c.Params("id") + + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to database", + }) + } + defer kvStore.Close() + + // Load manifest to verify repository exists + manifest, err := loadRepositoryManifest(ctx, kvStore) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to load repositories", + }) + } + + // Find repository + var repo *AgentTemplateRepository + for i := range manifest.Repositories { + if manifest.Repositories[i].ID == repoID { + repo = &manifest.Repositories[i] + break + } + } + + if repo == nil { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": "Repository not found", + }) + } + + // Publish sync message + jobID := uuid.New().String() + syncMsg := SyncJobMessage{ + Action: "sync_repository", + RepositoryID: repo.ID, + RepositoryURL: repo.URL, + RepositoryBranch: repo.Branch, + TriggeredBy: "user", + Timestamp: time.Now().Format(time.RFC3339), + JobID: jobID, + } + + if err := publishSyncJob(syncMsg); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to trigger sync", + }) + } + + return c.JSON(fiber.Map{ + "status": "syncing", + "job_id": jobID, + }) +} + +// GetAgentTemplateRepositorySyncStatus returns sync status for a repository +func GetAgentTemplateRepositorySyncStatus(c *fiber.Ctx) error { + ctx := context.Background() + repoID := c.Params("id") + + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to database", + }) + } + defer kvStore.Close() + + // Load manifest + manifest, err := loadRepositoryManifest(ctx, kvStore) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to load repositories", + }) + } + + // Find repository + for _, repo := range manifest.Repositories { + if repo.ID == repoID { + return c.JSON(fiber.Map{ + "status": repo.Status, + "last_sync": repo.LastSync, + "template_count": repo.TemplateCount, + "error_message": repo.ErrorMessage, + }) + } + } + + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": "Repository not found", + }) +} + +// Helper functions + +func loadRepositoryManifest(ctx context.Context, kvStore store.KVStore) (*RepositoryManifest, error) { + resp, err := kvStore.GetValue(ctx, repositoryManifestKey) + if err != nil { + return nil, err + } + + var manifest RepositoryManifest + if err := json.Unmarshal([]byte(resp.Message.Value), &manifest); err != nil { + return nil, err + } + + return &manifest, nil +} + +func saveRepositoryManifest(ctx context.Context, kvStore store.KVStore, manifest *RepositoryManifest) error { + data, err := json.Marshal(manifest) + if err != nil { + return err + } + + return kvStore.SetValue(ctx, repositoryManifestKey, string(data)) +} + +func publishSyncJob(msg SyncJobMessage) error { + data, err := json.Marshal(msg) + if err != nil { + return err + } + + return queue.Send(syncJobQueue, string(data)) +} diff --git a/sirius-api/handlers/apikey_handler.go b/sirius-api/handlers/apikey_handler.go new file mode 100644 index 0000000..f1963e7 --- /dev/null +++ b/sirius-api/handlers/apikey_handler.go @@ -0,0 +1,111 @@ +package handlers + +import ( + "context" + "log/slog" + "regexp" + + "github.com/SiriusScan/go-api/sirius/store" + "github.com/gofiber/fiber/v2" +) + +var apiKeyIDPattern = regexp.MustCompile("^[a-f0-9]{64}$") + +// APIKeyHandler holds a reference to the Valkey store used for key management. +type APIKeyHandler struct { + Store store.KVStore +} + +// CreateKey generates a new API key, stores its metadata, and returns the raw +// key exactly once in the response body. +func (h *APIKeyHandler) CreateKey(c *fiber.Ctx) error { + var body struct { + Label string `json:"label"` + } + if err := c.BodyParser(&body); err != nil { + body.Label = "Unnamed key" + } + if body.Label == "" { + body.Label = "Unnamed key" + } + + // Determine creator from the API key metadata (set by middleware). + createdBy := "system" + if label, ok := c.Locals("apikey_label").(string); ok && label != "" { + createdBy = label + } + if meta, ok := c.Locals("apikey_meta").(store.APIKeyMeta); ok { + createdBy = meta.Label + } + + rawKey, err := store.GenerateAPIKey() + if err != nil { + slog.Error("Failed to generate API key", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "failed to generate API key", + }) + } + + meta, err := store.StoreAPIKey(context.Background(), h.Store, rawKey, body.Label, createdBy) + if err != nil { + slog.Error("Failed to store API key", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "failed to store API key", + }) + } + + slog.Info("API key created", "label", body.Label, "prefix", meta.Prefix) + + return c.Status(fiber.StatusCreated).JSON(fiber.Map{ + "key": rawKey, // Only time the raw key is returned. + "raw_key": rawKey, // compatibility for clients expecting raw_key + "meta": meta, + }) +} + +// ListKeys returns metadata for all stored API keys. +func (h *APIKeyHandler) ListKeys(c *fiber.Ctx) error { + keys, err := store.ListAPIKeys(context.Background(), h.Store) + if err != nil { + slog.Error("Failed to list API keys", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "failed to list API keys", + }) + } + if keys == nil { + keys = []store.APIKeyMeta{} + } + return c.JSON(fiber.Map{"keys": keys}) +} + +// RevokeKey deletes an API key by its hash ID. +func (h *APIKeyHandler) RevokeKey(c *fiber.Ctx) error { + keyID := c.Params("id") + if keyID == "" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "key id is required", + }) + } + if !apiKeyIDPattern.MatchString(keyID) { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "invalid key id format", + }) + } + + // Enforce stable response contract: unknown key IDs return 404. + if _, err := h.Store.GetValue(context.Background(), "apikey:"+keyID); err != nil { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": "api key not found", + }) + } + + if err := store.RevokeAPIKey(context.Background(), h.Store, keyID); err != nil { + slog.Error("Failed to revoke API key", "error", err, "id", keyID) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "failed to revoke API key", + }) + } + + slog.Info("API key revoked", "id", keyID) + return c.JSON(fiber.Map{"message": "API key revoked"}) +} diff --git a/sirius-api/handlers/app_handler.go b/sirius-api/handlers/app_handler.go new file mode 100755 index 0000000..8943191 --- /dev/null +++ b/sirius-api/handlers/app_handler.go @@ -0,0 +1,41 @@ +package handlers + +import ( + "encoding/json" + + "github.com/SiriusScan/go-api/sirius/queue" + "github.com/gofiber/fiber/v2" +) + +func AppHandler(c *fiber.Ctx) error { + // Get the app name from the URL parameter + appName := c.Params("appName") + + // Get the message body from the POST request + var message map[string]interface{} + if err := c.BodyParser(&message); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "Cannot parse JSON"}) + } + + // Convert the message to a string (you can use JSON serialization or any other method) + messageStr, err := convertMessageToString(message) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{"error": "Internal Error"}) + } + + // Send the message to the queue + if err := queue.Send(appName, messageStr); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{"error": "Failed to send message in queue"}) + } + + // Return a success response + return c.Status(fiber.StatusOK).JSON(fiber.Map{"status": "Message sent successfully"}) +} + +func convertMessageToString(message map[string]interface{}) (string, error) { + messageBytes, err := json.Marshal(message) + if err != nil { + return "", err + } + return string(messageBytes), nil +} diff --git a/sirius-api/handlers/docker_handler.go b/sirius-api/handlers/docker_handler.go new file mode 100644 index 0000000..f96f044 --- /dev/null +++ b/sirius-api/handlers/docker_handler.go @@ -0,0 +1,91 @@ +package handlers + +import ( + "context" + "fmt" + "strconv" + "time" + + "github.com/SiriusScan/sirius-api/services" + "github.com/gofiber/fiber/v2" +) + +// DockerHandler handles Docker-related API endpoints +type DockerHandler struct { + dockerService *services.DockerService +} + +// NewDockerHandler creates a new Docker handler +func NewDockerHandler() (*DockerHandler, error) { + dockerService, err := services.NewDockerService() + if err != nil { + return nil, fmt.Errorf("failed to create Docker service: %w", err) + } + + return &DockerHandler{ + dockerService: dockerService, + }, nil +} + +// SystemResourcesHandler handles system resource monitoring +func (h *DockerHandler) SystemResourcesHandler(c *fiber.Ctx) error { + ctx := context.Background() + + // Get container resources from Docker + resources, summary, err := h.dockerService.GetContainerResources(ctx) + if err != nil { + // Return error response + return c.Status(500).JSON(fiber.Map{ + "error": "Failed to retrieve system resources", + "message": err.Error(), + "timestamp": time.Now(), + }) + } + + // Return successful response + return c.JSON(fiber.Map{ + "message": "System resource monitoring endpoint is working", + "timestamp": time.Now(), + "containers": resources, + "summary": summary, + }) +} + +// DockerLogsHandler handles Docker logs retrieval +func (h *DockerHandler) DockerLogsHandler(c *fiber.Ctx) error { + ctx := context.Background() + + // Get query parameters + containerName := c.Query("container", "all") + linesStr := c.Query("lines", "100") + + // Parse lines parameter + lines, err := strconv.Atoi(linesStr) + if err != nil { + lines = 100 // Default to 100 lines + } + + // Get container logs from Docker + logs, containerNames, err := h.dockerService.GetContainerLogs(ctx, containerName, lines) + if err != nil { + // Return error response + return c.Status(500).JSON(fiber.Map{ + "error": "Failed to retrieve Docker logs", + "message": err.Error(), + "timestamp": time.Now(), + }) + } + + // Return successful response + return c.JSON(fiber.Map{ + "message": "Docker logs endpoint is working", + "timestamp": time.Now(), + "container": containerName, + "lines": linesStr, + "logs": logs, + "summary": fiber.Map{ + "total_logs": len(logs), + "containers": containerNames, + }, + }) +} diff --git a/sirius-api/handlers/event_handler.go b/sirius-api/handlers/event_handler.go new file mode 100644 index 0000000..69de09d --- /dev/null +++ b/sirius-api/handlers/event_handler.go @@ -0,0 +1,202 @@ +package handlers + +import ( + "log/slog" + "strconv" + "time" + + "github.com/SiriusScan/go-api/sirius/events" + "github.com/gofiber/fiber/v2" +) + +// GetEvents retrieves events with filters +func GetEvents(c *fiber.Ctx) error { + // Parse query parameters + filters := events.EventFilters{ + Service: c.Query("service", ""), + Severity: c.Query("severity", ""), + EventType: c.Query("event_type", ""), + EntityType: c.Query("entity_type", ""), + EntityID: c.Query("entity_id", ""), + } + + // Parse limit and offset + limitStr := c.Query("limit", "50") + offsetStr := c.Query("offset", "0") + + limit, err := strconv.Atoi(limitStr) + if err != nil || limit <= 0 { + limit = 50 + } + if limit > 500 { + limit = 500 + } + filters.Limit = limit + + offset, err := strconv.Atoi(offsetStr) + if err != nil || offset < 0 { + offset = 0 + } + filters.Offset = offset + + // Parse time filters + if startTimeStr := c.Query("start_time", ""); startTimeStr != "" { + startTime, err := time.Parse(time.RFC3339, startTimeStr) + if err == nil { + filters.StartTime = &startTime + } + } + + if endTimeStr := c.Query("end_time", ""); endTimeStr != "" { + endTime, err := time.Parse(time.RFC3339, endTimeStr) + if err == nil { + filters.EndTime = &endTime + } + } + + // Query events + eventList, total, err := events.GetEvents(filters) + if err != nil { + slog.Error("Failed to retrieve events", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to retrieve events", + "details": err.Error(), + }) + } + + return c.JSON(fiber.Map{ + "events": eventList, + "total": total, + "limit": filters.Limit, + "offset": filters.Offset, + }) +} + +// GetEvent retrieves a single event by event_id +func GetEvent(c *fiber.Ctx) error { + eventID := c.Params("id") + if eventID == "" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Event ID is required", + }) + } + + event, err := events.GetEvent(eventID) + if err != nil { + slog.Error("Failed to retrieve event", "event_id", eventID, "error", err) + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": "Event not found", + "details": err.Error(), + }) + } + + return c.JSON(event) +} + +// GetEventStats returns event statistics +func GetEventStats(c *fiber.Ctx) error { + stats, err := events.GetEventStatistics() + if err != nil { + slog.Error("Failed to retrieve event statistics", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to retrieve event statistics", + "details": err.Error(), + }) + } + + return c.JSON(stats) +} + +// MarkEventsRead marks events as read (placeholder for future implementation) +func MarkEventsRead(c *fiber.Ctx) error { + // Parse request body + var req struct { + EventIDs []string `json:"event_ids"` + } + + if err := c.BodyParser(&req); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Invalid request body", + "details": err.Error(), + }) + } + + if len(req.EventIDs) == 0 { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "No event IDs provided", + }) + } + + // TODO: Implement read status tracking in database + // For now, just return success + return c.JSON(fiber.Map{ + "message": "Mark as read functionality will be implemented in a future update", + "event_ids": req.EventIDs, + "marked_count": len(req.EventIDs), + }) +} + +// GetEventsByEntity retrieves events for a specific entity +func GetEventsByEntity(c *fiber.Ctx) error { + entityType := c.Query("entity_type", "") + entityID := c.Query("entity_id", "") + + if entityType == "" || entityID == "" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Both entity_type and entity_id are required", + }) + } + + limitStr := c.Query("limit", "50") + limit, err := strconv.Atoi(limitStr) + if err != nil || limit <= 0 { + limit = 50 + } + + eventList, err := events.GetEventsByEntity(entityType, entityID, limit) + if err != nil { + slog.Error("Failed to retrieve events for entity", "entity_type", entityType, "entity_id", entityID, "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to retrieve events", + "details": err.Error(), + }) + } + + return c.JSON(fiber.Map{ + "entity_type": entityType, + "entity_id": entityID, + "events": eventList, + "count": len(eventList), + }) +} + +// GetRecentEventsBySeverity retrieves recent events filtered by severity +func GetRecentEventsBySeverity(c *fiber.Ctx) error { + severity := c.Params("severity") + if severity == "" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Severity is required", + }) + } + + limitStr := c.Query("limit", "50") + limit, err := strconv.Atoi(limitStr) + if err != nil || limit <= 0 { + limit = 50 + } + + eventList, err := events.GetRecentEventsBySeverity(severity, limit) + if err != nil { + slog.Error("Failed to retrieve events by severity", "severity", severity, "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to retrieve events", + "details": err.Error(), + }) + } + + return c.JSON(fiber.Map{ + "severity": severity, + "events": eventList, + "count": len(eventList), + }) +} diff --git a/sirius-api/handlers/health_handler.go b/sirius-api/handlers/health_handler.go new file mode 100644 index 0000000..d6c412f --- /dev/null +++ b/sirius-api/handlers/health_handler.go @@ -0,0 +1,267 @@ +package handlers + +import ( + "context" + "fmt" + "net" + "time" + + "github.com/SiriusScan/go-api/sirius/postgres" + "github.com/SiriusScan/go-api/sirius/store" + "github.com/gofiber/fiber/v2" +) + +// HealthResponse represents the health check response +type HealthResponse struct { + Status string `json:"status"` + Timestamp time.Time `json:"timestamp"` + Service string `json:"service"` + Version string `json:"version"` +} + +// SystemHealthResponse represents the comprehensive system health check response +type SystemHealthResponse struct { + Status string `json:"status"` + Timestamp time.Time `json:"timestamp"` + Service string `json:"service"` + Version string `json:"version"` + Services map[string]ServiceHealth `json:"services"` + Overall string `json:"overall"` +} + +// ServiceHealth represents the health status of an individual service +type ServiceHealth struct { + Status string `json:"status"` + Message string `json:"message,omitempty"` + Timestamp time.Time `json:"timestamp"` + Port int `json:"port,omitempty"` +} + +// HealthHandler handles the GET /health route +func HealthHandler(c *fiber.Ctx) error { + response := HealthResponse{ + Status: "healthy", + Timestamp: time.Now(), + Service: "sirius-api", + Version: "1.0.0", + } + + return c.Status(200).JSON(response) +} + +// SystemHealthHandler handles the GET /api/v1/system/health route +func SystemHealthHandler(c *fiber.Ctx) error { + services := make(map[string]ServiceHealth) + + // Check UI service (self-check) + uiHealth := checkUIService() + services["sirius-ui"] = uiHealth + + // Check API service (self-check) + apiHealth := checkAPIService() + services["sirius-api"] = apiHealth + + // Check Engine service + engineHealth := checkEngineService() + services["sirius-engine"] = engineHealth + + // Check PostgreSQL + postgresHealth := checkPostgreSQL() + services["sirius-postgres"] = postgresHealth + + // Check Valkey + valkeyHealth := checkValkey() + services["sirius-valkey"] = valkeyHealth + + // Check RabbitMQ + rabbitmqHealth := checkRabbitMQ() + services["sirius-rabbitmq"] = rabbitmqHealth + + // Determine overall status + overallStatus := "healthy" + for _, service := range services { + if service.Status == "down" { + overallStatus = "degraded" + break + } + } + + response := SystemHealthResponse{ + Status: overallStatus, + Timestamp: time.Now(), + Service: "sirius-api", + Version: "1.0.0", + Services: services, + Overall: overallStatus, + } + + statusCode := 200 + if overallStatus == "degraded" { + statusCode = 503 + } + + return c.Status(statusCode).JSON(response) +} + +// checkUIService checks if the UI service is accessible +func checkUIService() ServiceHealth { + // Try to connect to UI on port 3000 using container name + conn, err := net.DialTimeout("tcp", "sirius-ui:3000", 2*time.Second) + if err != nil { + return ServiceHealth{ + Status: "down", + Message: fmt.Sprintf("Cannot connect to UI: %v", err), + Timestamp: time.Now(), + Port: 3000, + } + } + conn.Close() + + return ServiceHealth{ + Status: "up", + Message: "UI service is accessible", + Timestamp: time.Now(), + Port: 3000, + } +} + +// checkAPIService performs a self-check of the API service +func checkAPIService() ServiceHealth { + // This is a self-check, so we can assume it's healthy if we're responding + return ServiceHealth{ + Status: "up", + Message: "API service is running", + Timestamp: time.Now(), + Port: 9001, + } +} + +// checkEngineService checks if the Engine service is accessible via gRPC +func checkEngineService() ServiceHealth { + // Try to connect to Engine gRPC port 50051 + conn, err := net.DialTimeout("tcp", "sirius-engine:50051", 2*time.Second) + if err != nil { + return ServiceHealth{ + Status: "down", + Message: fmt.Sprintf("Cannot connect to Engine gRPC: %v", err), + Timestamp: time.Now(), + Port: 50051, + } + } + conn.Close() + + return ServiceHealth{ + Status: "up", + Message: "Engine gRPC service is accessible", + Timestamp: time.Now(), + Port: 50051, + } +} + +// checkPostgreSQL checks PostgreSQL connectivity +func checkPostgreSQL() ServiceHealth { + // Use the existing database connection utility + if postgres.IsConnected() { + // Try a simple query to verify the connection is working + db := postgres.GetDB() + if db != nil { + var result int + err := db.Raw("SELECT 1").Scan(&result).Error + if err != nil { + return ServiceHealth{ + Status: "down", + Message: fmt.Sprintf("Database query failed: %v", err), + Timestamp: time.Now(), + Port: 5432, + } + } + + return ServiceHealth{ + Status: "up", + Message: "PostgreSQL is connected and responding", + Timestamp: time.Now(), + Port: 5432, + } + } + } + + // If we get here, the database is not connected + connErr := postgres.GetConnectionError() + message := "PostgreSQL is not connected" + if connErr != nil { + message = fmt.Sprintf("PostgreSQL connection error: %v", connErr) + } + + return ServiceHealth{ + Status: "down", + Message: message, + Timestamp: time.Now(), + Port: 5432, + } +} + +// checkValkey checks Valkey/Redis connectivity +func checkValkey() ServiceHealth { + // Create a new Valkey store connection for testing + kvStore, err := store.NewValkeyStore() + if err != nil { + return ServiceHealth{ + Status: "down", + Message: fmt.Sprintf("Cannot connect to Valkey: %v", err), + Timestamp: time.Now(), + Port: 6379, + } + } + defer kvStore.Close() + + // Try a simple ping operation + ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second) + defer cancel() + + // Try to set and get a test value + testKey := "health-check-test" + testValue := "ping" + + err = kvStore.SetValue(ctx, testKey, testValue) + if err != nil { + return ServiceHealth{ + Status: "down", + Message: fmt.Sprintf("Valkey SET operation failed: %v", err), + Timestamp: time.Now(), + Port: 6379, + } + } + + // Clean up the test key + kvStore.DeleteValue(ctx, testKey) + + return ServiceHealth{ + Status: "up", + Message: "Valkey is connected and responding", + Timestamp: time.Now(), + Port: 6379, + } +} + +// checkRabbitMQ checks RabbitMQ connectivity +func checkRabbitMQ() ServiceHealth { + // Try to connect to RabbitMQ on port 5672 using container name + conn, err := net.DialTimeout("tcp", "sirius-rabbitmq:5672", 2*time.Second) + if err != nil { + return ServiceHealth{ + Status: "down", + Message: fmt.Sprintf("Cannot connect to RabbitMQ: %v", err), + Timestamp: time.Now(), + Port: 5672, + } + } + conn.Close() + + return ServiceHealth{ + Status: "up", + Message: "RabbitMQ is accessible", + Timestamp: time.Now(), + Port: 5672, + } +} + diff --git a/sirius-api/handlers/host_handler.go b/sirius-api/handlers/host_handler.go new file mode 100755 index 0000000..337d05a --- /dev/null +++ b/sirius-api/handlers/host_handler.go @@ -0,0 +1,1001 @@ +package handlers + +import ( + "encoding/json" + "log/slog" + "net" + "strconv" + "strings" + + "github.com/SiriusScan/go-api/nvd" + "github.com/SiriusScan/go-api/sirius" + "github.com/SiriusScan/go-api/sirius/host" + "github.com/SiriusScan/go-api/sirius/postgres" + "github.com/SiriusScan/go-api/sirius/postgres/models" + "github.com/SiriusScan/go-api/sirius/vulnerability" + "github.com/gofiber/fiber/v2" +) + +func isValidSingleHostIP(ip string) bool { + candidate := strings.TrimSpace(ip) + if candidate == "" { + return false + } + // Host records must be concrete IPs, not CIDR/range/domain targets. + if strings.Contains(candidate, "/") || strings.Contains(candidate, "-") { + return false + } + return net.ParseIP(candidate) != nil +} + +// GetHost handles the GET /host/{id} route with optional enhanced data +func GetHost(c *fiber.Ctx) error { + hostID := c.Params("id") + + // Check for enhanced data query parameters + includeParam := c.Query("include", "") + includeEnhanced := c.Query("enhanced", "false") + + // Parse include fields + var includeFields []string + if includeParam != "" { + includeFields = strings.Split(includeParam, ",") + // Trim whitespace from each field + for i, field := range includeFields { + includeFields[i] = strings.TrimSpace(field) + } + } + + // Check if client wants enhanced response + if includeEnhanced == "true" || len(includeFields) > 0 { + // Enhanced response with JSONB fields + enhancedData, err := host.GetHostWithEnhancedData(hostID, includeFields) + if err != nil { + // Fallback to basic response if enhanced data unavailable + hostData, fallbackErr := host.GetHost(hostID) + if fallbackErr != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": fallbackErr.Error(), + }) + } + return c.JSON(hostData) + } + + // Check if client also wants source information + includeSource := c.Query("include_source", "false") + if includeSource == "true" { + hostWithSources, err := host.GetHostWithSources(hostID) + if err == nil { + // Add source information to enhanced response + enhancedResponse := fiber.Map{ + "host": enhancedData.Host, + "software_inventory": enhancedData.SoftwareInventory, + "system_fingerprint": enhancedData.SystemFingerprint, + "agent_metadata": enhancedData.AgentMetadata, + "sources": hostWithSources.Sources, + } + return c.JSON(enhancedResponse) + } + } + + return c.JSON(enhancedData) + } + + // Use basic GetHost function for backward compatibility + hostData, err := host.GetHost(hostID) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": err.Error(), + }) + } + + // Check if client wants source information (legacy support) + includeSource := c.Query("include_source", "false") + if includeSource == "true" { + hostWithSources, err := host.GetHostWithSources(hostID) + if err != nil { + // Fallback to basic response if source data unavailable + return c.JSON(hostData) + } + + // Add source information to the response + enhancedResponse := fiber.Map{ + "host": hostData, + "sources": hostWithSources.Sources, + } + + return c.JSON(enhancedResponse) + } + + // Legacy response format (unchanged for backward compatibility) + return c.JSON(hostData) +} + +// GetAllHosts handles the GET /host route +func GetAllHosts(c *fiber.Ctx) error { + hosts, err := host.GetAllHosts() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": err.Error(), + }) + } + + return c.JSON(hosts) +} + +// GetHostStatistics handles the GET /host/statistics route +func GetHostStatistics(c *fiber.Ctx) error { + hostID := c.Params("id") + slog.Debug("GetHostStatistics", "host_id", hostID) + stats, err := host.GetHostRiskStatistics(hostID) + if err != nil { + slog.Error("GetHostStatistics failed", "host_id", hostID, "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error getting vulnerabilities: " + err.Error(), + }) + } + return c.JSON(stats) +} + +// GetHostVulnerabilitySeverityCounts handles the GET /host/severity-counts route +func GetHostVulnerabilitySeverityCounts(c *fiber.Ctx) error { + hostID := c.Params("id") + slog.Debug("GetHostVulnerabilitySeverityCounts", "host_id", hostID) + stats, err := host.GetHostVulnerabilitySeverityCounts(hostID) + if err != nil { + slog.Error("GetHostVulnerabilitySeverityCounts failed", "host_id", hostID, "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error getting vulnerabilities: " + err.Error(), + }) + } + return c.JSON(stats) +} + +// GetAllVulnerabilities handles GET /host/vulnerabilities/all. +// +// Implemented here (not host.GetAllVulnerabilities in go-api) because older SDK versions +// post-processed SQL results and only retained rows where host_count == 1, which hid CVEs +// affecting multiple hosts and could yield an empty list while host views still showed vulns. +func GetAllVulnerabilities(c *fiber.Ctx) error { + db := postgres.GetDB() + var rows []host.VulnerabilitySummary + err := db.Model(&models.Vulnerability{}). + Select("vulnerabilities.v_id, vulnerabilities.title, vulnerabilities.description, vulnerabilities.risk_score, count(host_vulnerabilities.host_id) as host_count"). + Joins("LEFT JOIN host_vulnerabilities ON host_vulnerabilities.vulnerability_id = vulnerabilities.id"). + Group("vulnerabilities.id"). + Having("count(host_vulnerabilities.host_id) > 0"). + Scan(&rows).Error + if err != nil { + slog.Error("GetAllVulnerabilities failed", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error getting vulnerabilities: " + err.Error(), + }) + } + + // Avoid JSON `null` when there are no rows (nil slice); clients expect an array. + if rows == nil { + rows = []host.VulnerabilitySummary{} + } + + return c.JSON(rows) +} + +// AddHost handles the POST /host route +// AddHost Chain: Handle the REST Request (API) (Here) -> SDK go-api sirius/host -> sirius/postgres/host-operations postgres +func AddHost(c *fiber.Ctx) error { + // Read the raw request body + requestBody := string(c.Body()) + + // Define a local struct that matches the expected JSON structure + var newHost sirius.Host + + // Manually unmarshal JSON into the struct + err := json.Unmarshal([]byte(requestBody), &newHost) + if err != nil { + slog.Error("Error parsing request body", "error", err) + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Error parsing request body: " + err.Error(), + }) + } + slog.Info("Adding host", "ip", newHost.IP) + if !isValidSingleHostIP(newHost.IP) { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Host IP must be a single IP address (CIDR/range/domain targets are not allowed)", + }) + } + + // Detect source information from request metadata + source := detectSourceFromRequest(c) + slog.Info("Detected source", "name", source.Name, "version", source.Version) + + // Check all host vulns to confirm that they all exist in the database. If they do not, add them. + for _, vuln := range newHost.Vulnerabilities { + if !vulnerability.CheckVulnerabilityExists(vuln.VID) { + slog.Info("Vulnerability not in database, adding", "vid", vuln.VID) + + cve, err := nvd.GetCVE(vuln.VID) + if err != nil { + slog.Warn("Failed to get CVE data", "vid", vuln.VID, "error", err) + // Use provided vulnerability data as fallback + vuln = sirius.Vulnerability{ + VID: vuln.VID, + Description: vuln.Description, + Title: vuln.Title, + RiskScore: vuln.RiskScore, + } + } else { + // Safely extract CVE data with fallbacks + description := vuln.Description + if len(cve.Descriptions) > 0 { + description = cve.Descriptions[0].Value + } + + title := vuln.Title + if cve.ID != "" { + title = cve.ID + } + + riskScore := vuln.RiskScore + if len(cve.Metrics.CvssMetricV31) > 0 { + riskScore = cve.Metrics.CvssMetricV31[0].CvssData.BaseScore + } + + vuln = sirius.Vulnerability{ + VID: vuln.VID, + Description: description, + Title: title, + RiskScore: riskScore, + } + } + + err = vulnerability.AddVulnerability(vuln) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error adding vulnerability: " + err.Error(), + }) + } + } + } + + // Route to source-aware function if source detected, otherwise use legacy function + if source.Name != "unknown" { + err = host.AddHostWithSource(newHost, source) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error adding host with source: " + err.Error(), + }) + } + + // Enhanced response with optional source information + response := fiber.Map{ + "message": "Host added successfully with source attribution", + "host_ip": newHost.IP, + } + + // Add source information only if it was successfully detected + if source.Name != "unknown" { + response["source"] = fiber.Map{ + "name": source.Name, + "version": source.Version, + "config": source.Config, + } + } + + return c.JSON(response) + } else { + // Fallback to legacy function for backward compatibility + err = host.AddHost(newHost) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error adding host: " + err.Error(), + }) + } + + // Legacy response format (unchanged for backward compatibility) + return c.JSON(fiber.Map{ + "message": "Host added successfully", + }) + } +} + +// detectSourceFromRequest analyzes the HTTP request to determine the source of the scan data +func detectSourceFromRequest(c *fiber.Ctx) models.ScanSource { + // Check User-Agent header for scanner identification + userAgent := c.Get("User-Agent") + + // Check custom headers that scanners might set + scannerName := c.Get("X-Scanner-Name") + scannerVersion := c.Get("X-Scanner-Version") + scannerConfig := c.Get("X-Scanner-Config") + + // Check for source information in query parameters + if scannerName == "" { + scannerName = c.Query("source") + } + if scannerVersion == "" { + scannerVersion = c.Query("version") + } + + // Analyze User-Agent string for known patterns + if scannerName == "" { + scannerName, scannerVersion = parseUserAgentForScanner(userAgent) + } + + // Check client IP for known scanner hosts (if configured) + clientIP := c.IP() + if scannerName == "" { + scannerName = detectSourceFromIP(clientIP) + } + + // Default values if nothing detected + if scannerName == "" { + scannerName = "unknown" + } + if scannerVersion == "" { + scannerVersion = "unknown" + } + if scannerConfig == "" { + scannerConfig = "default" + } + + // Validate and sanitize source information + source := models.ScanSource{ + Name: validateSourceName(scannerName), + Version: validateSourceVersion(scannerVersion), + Config: validateSourceConfig(scannerConfig), + } + + // Log source detection for debugging + slog.Debug("Source detection", "user_agent", userAgent, "name", source.Name, "version", source.Version) + + return source +} + +// validateSourceName ensures the source name is valid and safe +func validateSourceName(name string) string { + // Remove any potentially dangerous characters + name = strings.TrimSpace(name) + if len(name) == 0 || len(name) > 50 { + return "unknown" + } + + // Allow only alphanumeric, dash, underscore, and dot + for _, char := range name { + if !((char >= 'a' && char <= 'z') || (char >= 'A' && char <= 'Z') || + (char >= '0' && char <= '9') || char == '-' || char == '_' || char == '.') { + return "unknown" + } + } + + return name +} + +// validateSourceVersion ensures the version string is valid and safe +func validateSourceVersion(version string) string { + version = strings.TrimSpace(version) + if len(version) == 0 || len(version) > 20 { + return "unknown" + } + + // Allow only alphanumeric, dot, dash, and underscore for versions + for _, char := range version { + if !((char >= 'a' && char <= 'z') || (char >= 'A' && char <= 'Z') || + (char >= '0' && char <= '9') || char == '.' || char == '-' || char == '_') { + return "unknown" + } + } + + return version +} + +// validateSourceConfig ensures the config string is valid and safe +func validateSourceConfig(config string) string { + config = strings.TrimSpace(config) + if len(config) > 200 { + config = config[:200] // Truncate if too long + } + if len(config) == 0 { + return "default" + } + + return config +} + +// parseUserAgentForScanner extracts scanner information from User-Agent string +func parseUserAgentForScanner(userAgent string) (name, version string) { + // Common patterns for scanner identification + patterns := map[string]string{ + "sirius-agent": "agent", + "sirius-scanner": "network-scanner", + "nmap": "nmap", + "rustscan": "rustscan", + "naabu": "naabu", + "curl": "manual-curl", + "wget": "manual-wget", + "python": "python-script", + "go-http": "go-client", + } + + userAgentLower := strings.ToLower(userAgent) + + for pattern, scannerType := range patterns { + if strings.Contains(userAgentLower, pattern) { + // Try to extract version if present + version = extractVersionFromUserAgent(userAgent, pattern) + return scannerType, version + } + } + + return "", "" +} + +// extractVersionFromUserAgent attempts to extract version information from User-Agent +func extractVersionFromUserAgent(userAgent, toolName string) string { + // Simple regex-like extraction for version patterns + // Look for patterns like "tool/1.2.3" or "tool-1.2.3" + userAgentLower := strings.ToLower(userAgent) + toolLower := strings.ToLower(toolName) + + // Find the tool name in the user agent + index := strings.Index(userAgentLower, toolLower) + if index == -1 { + return "unknown" + } + + // Look for version after the tool name + remaining := userAgent[index+len(toolName):] + + // Common version separators + separators := []string{"/", "-", " ", "_"} + + for _, sep := range separators { + if strings.HasPrefix(remaining, sep) { + versionPart := remaining[1:] + // Extract version until next space or special character + for i, char := range versionPart { + if !((char >= '0' && char <= '9') || char == '.' || char == '-') { + return versionPart[:i] + } + } + return versionPart + } + } + + return "unknown" +} + +// detectSourceFromIP determines scanner type based on client IP (if configured) +func detectSourceFromIP(clientIP string) string { + // This could be enhanced with configuration for known scanner IPs + // For now, return empty to indicate no detection + return "" +} + +// UpdateHostRequest represents the request body for updating a host +type UpdateHostRequest struct { + Hostname *string `json:"hostname,omitempty"` + OS *string `json:"os,omitempty"` + OSVersion *string `json:"osversion,omitempty"` + Ports []sirius.Port `json:"ports,omitempty"` + Notes []string `json:"notes,omitempty"` +} + +// UpdateHost handles the PUT /host/:id route for updating host information +func UpdateHost(c *fiber.Ctx) error { + hostIP := c.Params("id") + if hostIP == "" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Host IP is required", + }) + } + + slog.Info("UpdateHost", "ip", hostIP) + + // Parse update request + var updateReq UpdateHostRequest + if err := c.BodyParser(&updateReq); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Error parsing request body: " + err.Error(), + }) + } + + // Build host object with updates + hostUpdate := sirius.Host{ + IP: hostIP, + } + + if updateReq.Hostname != nil { + hostUpdate.Hostname = *updateReq.Hostname + } + if updateReq.OS != nil { + hostUpdate.OS = *updateReq.OS + } + if updateReq.OSVersion != nil { + hostUpdate.OSVersion = *updateReq.OSVersion + } + if updateReq.Ports != nil { + hostUpdate.Ports = updateReq.Ports + } + if updateReq.Notes != nil { + hostUpdate.Notes = updateReq.Notes + } + + // Use source-aware update with "manual" source for UI-driven updates + source := models.ScanSource{ + Name: "manual", + Version: "1.0", + Config: "ui-update", + } + + err := host.AddHostWithSource(hostUpdate, source) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error updating host: " + err.Error(), + }) + } + + return c.JSON(fiber.Map{ + "message": "Host updated successfully", + "host_ip": hostIP, + }) +} + +// DeleteHost handles the POST /host/delete route +func DeleteHost(c *fiber.Ctx) error { + // Read the raw request body + requestBody := string(c.Body()) + slog.Debug("DeleteHost request body", "body", requestBody) + + // Define a local struct that matches the expected JSON structure + var newHost sirius.Host + + // Manually unmarshal JSON into the struct + err := json.Unmarshal([]byte(requestBody), &newHost) + if err != nil { + slog.Error("Error parsing request body", "error", err) + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Error parsing request body: " + err.Error(), + }) + } + + slog.Info("Deleting host", "ip", newHost.IP) + + err = host.DeleteHost(newHost.IP) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error deleting host: " + err.Error(), + }) + } + + return c.JSON(fiber.Map{ + "message": "Host deleted successfully", + }) +} + +// ===== SOURCE-AWARE HANDLERS FOR PHASE 1 TESTING ===== + +// AddHostWithSourceRequest represents the request body for source-aware host addition +type AddHostWithSourceRequest struct { + Host sirius.Host `json:"host"` + Source models.ScanSource `json:"source"` +} + +// EnhancedHostRequest represents the request body for enhanced host data with JSONB fields +type EnhancedHostRequest struct { + Host sirius.Host `json:"host"` + Source models.ScanSource `json:"source"` + SoftwareInventory map[string]interface{} `json:"software_inventory,omitempty"` + SystemFingerprint map[string]interface{} `json:"system_fingerprint,omitempty"` + AgentMetadata map[string]interface{} `json:"agent_metadata,omitempty"` +} + +// AddHostWithSource handles the POST /host/with-source route +func AddHostWithSource(c *fiber.Ctx) error { + // Try to parse as enhanced request first, fall back to basic request + var enhancedRequest EnhancedHostRequest + var request AddHostWithSourceRequest + var hasEnhancedData bool + + // Attempt to parse as enhanced request + if err := c.BodyParser(&enhancedRequest); err == nil && + (len(enhancedRequest.SoftwareInventory) > 0 || + len(enhancedRequest.SystemFingerprint) > 0 || + len(enhancedRequest.AgentMetadata) > 0) { + // Successfully parsed enhanced data + hasEnhancedData = true + request.Host = enhancedRequest.Host + request.Source = enhancedRequest.Source + slog.Info("Received enhanced host data with JSONB fields", "ip", request.Host.IP) + } else { + // Fall back to basic request parsing + if err := c.BodyParser(&request); err != nil { + slog.Error("Error parsing request body", "error", err) + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Error parsing request body: " + err.Error(), + }) + } + slog.Debug("Received basic host data", "ip", request.Host.IP) + } + + slog.Info("Adding host with source", "ip", request.Host.IP, "source", request.Source.Name) + if !isValidSingleHostIP(request.Host.IP) { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Host IP must be a single IP address (CIDR/range/domain targets are not allowed)", + }) + } + + // Ensure vulnerabilities exist in database (same logic as original AddHost) + for _, vuln := range request.Host.Vulnerabilities { + if !vulnerability.CheckVulnerabilityExists(vuln.VID) { + slog.Info("Vulnerability not in database, adding", "vid", vuln.VID) + + cve, err := nvd.GetCVE(vuln.VID) + if err != nil { + slog.Warn("Failed to get CVE data", "vid", vuln.VID, "error", err) + // Use provided vulnerability data as fallback + vuln = sirius.Vulnerability{ + VID: vuln.VID, + Description: vuln.Description, + Title: vuln.Title, + RiskScore: vuln.RiskScore, + } + } else { + // Safely extract CVE data with fallbacks + description := vuln.Description + if len(cve.Descriptions) > 0 { + description = cve.Descriptions[0].Value + } + + title := vuln.Title + if cve.ID != "" { + title = cve.ID + } + + riskScore := vuln.RiskScore + if len(cve.Metrics.CvssMetricV31) > 0 { + riskScore = cve.Metrics.CvssMetricV31[0].CvssData.BaseScore + } + + vuln = sirius.Vulnerability{ + VID: vuln.VID, + Description: description, + Title: title, + RiskScore: riskScore, + } + } + + err = vulnerability.AddVulnerability(vuln) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error adding vulnerability: " + err.Error(), + }) + } + } + } + + // Use enhanced source-aware function if we have enhanced data + if hasEnhancedData { + err := host.AddHostWithSourceAndJSONB(request.Host, request.Source, + enhancedRequest.SoftwareInventory, + enhancedRequest.SystemFingerprint, + enhancedRequest.AgentMetadata) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error adding host with enhanced data: " + err.Error(), + }) + } + + return c.JSON(fiber.Map{ + "message": "Host added successfully with enhanced SBOM data", + "source": request.Source.Name, + "host_ip": request.Host.IP, + "enhanced_data_included": true, + "software_inventory": len(enhancedRequest.SoftwareInventory) > 0, + "system_fingerprint": len(enhancedRequest.SystemFingerprint) > 0, + "agent_metadata": len(enhancedRequest.AgentMetadata) > 0, + }) + } else { + // Use standard source-aware function + err := host.AddHostWithSource(request.Host, request.Source) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error adding host with source: " + err.Error(), + }) + } + + return c.JSON(fiber.Map{ + "message": "Host added successfully with source attribution", + "source": request.Source.Name, + "host_ip": request.Host.IP, + }) + } +} + +// GetHostWithSources handles the GET /host/{id}/sources route +func GetHostWithSources(c *fiber.Ctx) error { + hostIP := c.Params("id") + + hostWithSources, err := host.GetHostWithSources(hostIP) + if err != nil { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": "Host not found or error retrieving sources: " + err.Error(), + }) + } + + return c.JSON(hostWithSources) +} + +// GetVulnerabilityHistory handles the GET /host/{id}/vulnerability/{vulnId}/history route +func GetVulnerabilityHistory(c *fiber.Ctx) error { + hostIDStr := c.Params("id") + vulnIDStr := c.Params("vulnId") + + // Convert string IDs to uint + hostID, err := strconv.ParseUint(hostIDStr, 10, 32) + if err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Invalid host ID: " + err.Error(), + }) + } + + vulnID, err := strconv.ParseUint(vulnIDStr, 10, 32) + if err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Invalid vulnerability ID: " + err.Error(), + }) + } + + history, err := host.GetVulnerabilityHistory(uint(hostID), uint(vulnID)) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error retrieving vulnerability history: " + err.Error(), + }) + } + + return c.JSON(fiber.Map{ + "host_id": hostID, + "vulnerability_id": vulnID, + "source_history": history, + }) +} + +// GetSourceCoverageStats handles the GET /host/source-coverage route +func GetSourceCoverageStats(c *fiber.Ctx) error { + stats, err := host.GetSourceCoverageStats() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error retrieving source coverage statistics: " + err.Error(), + }) + } + + return c.JSON(fiber.Map{ + "source_coverage_stats": stats, + "total_sources": len(stats), + }) +} + +// GetVulnerabilitySources handles the GET /vulnerability/{id}/sources route +func GetVulnerabilitySources(c *fiber.Ctx) error { + vulnID := c.Params("id") + + // Get all sources that have reported this vulnerability + sources, err := host.GetVulnerabilitySources(vulnID) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error retrieving vulnerability sources: " + err.Error(), + }) + } + + return c.JSON(fiber.Map{ + "vulnerability_id": vulnID, + "sources": sources, + "total_sources": len(sources), + }) +} + +// GetHostHistory handles the GET /host/{id}/history route +func GetHostHistory(c *fiber.Ctx) error { + hostIP := c.Params("id") + + // This would get a comprehensive history of all scan activities for the host + // For now, we'll return the sources information as a basic history + hostWithSources, err := host.GetHostWithSources(hostIP) + if err != nil { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": "Host not found or error retrieving history: " + err.Error(), + }) + } + + // Transform the data into a timeline format + timeline := make([]fiber.Map, 0) + + // Add scan events to timeline (this is a simplified version) + // In a full implementation, this would query scan_history table + timeline = append(timeline, fiber.Map{ + "event_type": "host_discovery", + "timestamp": hostWithSources.Host.CreatedAt, + "source": "initial", + "details": "Host first discovered", + }) + + return c.JSON(fiber.Map{ + "host_ip": hostIP, + "timeline": timeline, + "sources": hostWithSources.Sources, + }) +} + +// ===== BACKWARD COMPATIBILITY UTILITIES ===== + +// isLegacyClient determines if the client expects legacy API responses +func isLegacyClient(c *fiber.Ctx) bool { + // Check for API version header + apiVersion := c.Get("X-API-Version") + if apiVersion != "" && apiVersion < "2.0" { + return true + } + + // Check for legacy User-Agent patterns + userAgent := c.Get("User-Agent") + legacyPatterns := []string{ + "legacy", + "v1.", + "old-client", + } + + userAgentLower := strings.ToLower(userAgent) + for _, pattern := range legacyPatterns { + if strings.Contains(userAgentLower, pattern) { + return true + } + } + + return false +} + +// wrapLegacyResponse wraps responses for legacy clients +func wrapLegacyResponse(data interface{}) fiber.Map { + return fiber.Map{ + "data": data, + "version": "1.0", + "format": "legacy", + } +} + +// wrapEnhancedResponse wraps responses for modern clients with source information +func wrapEnhancedResponse(data interface{}, sources interface{}) fiber.Map { + response := fiber.Map{ + "data": data, + "version": "2.0", + "format": "enhanced", + } + + if sources != nil { + response["sources"] = sources + } + + return response +} + +// assignLegacySource creates a default source for legacy submissions +func assignLegacySource() models.ScanSource { + return models.ScanSource{ + Name: "legacy", + Version: "unknown", + Config: "legacy-submission", + } +} + +// GetHostPackages handles the GET /host/{id}/packages route +func GetHostPackages(c *fiber.Ctx) error { + hostID := c.Params("id") + + inventory, err := host.GetHostSoftwareInventory(hostID) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error retrieving software inventory: " + err.Error(), + }) + } + + // Support filtering by package name, architecture, publisher + packageFilter := c.Query("filter", "") + architecture := c.Query("architecture", "") + publisher := c.Query("publisher", "") + + filteredPackages := inventory.Packages + + // Apply filters if specified + if packageFilter != "" || architecture != "" || publisher != "" { + filteredPackages = []map[string]interface{}{} + for _, pkg := range inventory.Packages { + match := true + + if packageFilter != "" { + if name, ok := pkg["name"].(string); !ok || !strings.Contains(strings.ToLower(name), strings.ToLower(packageFilter)) { + match = false + } + } + + if architecture != "" && match { + if arch, ok := pkg["architecture"].(string); !ok || arch != architecture { + match = false + } + } + + if publisher != "" && match { + if pub, ok := pkg["publisher"].(string); !ok || !strings.Contains(strings.ToLower(pub), strings.ToLower(publisher)) { + match = false + } + } + + if match { + filteredPackages = append(filteredPackages, pkg) + } + } + } + + response := fiber.Map{ + "host_ip": hostID, + "packages": filteredPackages, + "package_count": len(filteredPackages), + "total_count": inventory.PackageCount, + "collected_at": inventory.CollectedAt, + "source": inventory.Source, + } + + if inventory.Statistics != nil { + response["statistics"] = inventory.Statistics + } + + return c.JSON(response) +} + +// GetHostFingerprint handles the GET /host/{id}/fingerprint route +func GetHostFingerprint(c *fiber.Ctx) error { + hostID := c.Params("id") + + fingerprint, err := host.GetHostSystemFingerprint(hostID) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error retrieving system fingerprint: " + err.Error(), + }) + } + + response := fiber.Map{ + "host_ip": hostID, + "fingerprint": fingerprint.Fingerprint, + "collected_at": fingerprint.CollectedAt, + "source": fingerprint.Source, + "platform": fingerprint.Platform, + "collection_duration_ms": fingerprint.CollectionDurationMs, + } + + if fingerprint.Summary != nil { + response["summary"] = fingerprint.Summary + } + + return c.JSON(response) +} + +// GetHostSoftwareStats handles the GET /host/{id}/software-stats route +func GetHostSoftwareStats(c *fiber.Ctx) error { + hostID := c.Params("id") + + stats, err := host.GetHostSoftwareStatistics(hostID) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Error retrieving software statistics: " + err.Error(), + }) + } + + response := fiber.Map{ + "host_ip": hostID, + "total_packages": stats.TotalPackages, + "architectures": stats.Architectures, + "publishers": stats.Publishers, + "packages_by_source": stats.PackagesBySource, + "last_updated": stats.LastUpdated, + } + + return c.JSON(response) +} diff --git a/sirius-api/handlers/log_handler.go b/sirius-api/handlers/log_handler.go new file mode 100644 index 0000000..1315366 --- /dev/null +++ b/sirius-api/handlers/log_handler.go @@ -0,0 +1,581 @@ +package handlers + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "net/http" + "sort" + "strconv" + "strings" + "time" + + "github.com/SiriusScan/go-api/sirius/logging" + "github.com/SiriusScan/go-api/sirius/store" + "github.com/SiriusScan/sirius-api/internal/infraauth" + "github.com/gofiber/fiber/v2" +) + +// Use the SDK LogEntry type +type LogEntry = logging.LogEntry + +// LogSubmissionRequest represents the request to submit a log entry +type LogSubmissionRequest struct { + Service string `json:"service" validate:"required"` + Subcomponent string `json:"subcomponent,omitempty"` + Level string `json:"level" validate:"required,oneof=debug info warn error"` + Message string `json:"message" validate:"required"` + Metadata map[string]interface{} `json:"metadata,omitempty"` + Context map[string]interface{} `json:"context,omitempty"` +} + +// LogRetrievalRequest represents the request to retrieve logs +type LogRetrievalRequest struct { + Service string `json:"service,omitempty"` + Level string `json:"level,omitempty"` + Subcomponent string `json:"subcomponent,omitempty"` + Limit int `json:"limit,omitempty"` + Offset int `json:"offset,omitempty"` + Search string `json:"search,omitempty"` +} + +// LogRetrievalResponse represents the response for log retrieval +type LogRetrievalResponse struct { + Logs []LogEntry `json:"logs"` + Total int `json:"total"` + Limit int `json:"limit"` + Offset int `json:"offset"` +} + +// LogStatsResponse represents log statistics +type LogStatsResponse struct { + TotalLogs int `json:"total_logs"` + ServiceStats map[string]int `json:"service_stats"` + LevelStats map[string]int `json:"level_stats"` + RecentLogs []LogEntry `json:"recent_logs"` +} + +const ( + MAX_LOGS = 1000 // Maximum number of logs to keep (focused on meaningful events) + LOG_PREFIX = "logs" +) + +// LogSubmissionHandler handles log submission requests +func LogSubmissionHandler(c *fiber.Ctx) error { + var req LogSubmissionRequest + if err := c.BodyParser(&req); err != nil { + return c.Status(400).JSON(fiber.Map{ + "error": "Invalid request body", + "details": err.Error(), + }) + } + + // Validate required fields + if req.Service == "" || req.Level == "" || req.Message == "" { + return c.Status(400).JSON(fiber.Map{ + "error": "Missing required fields: service, level, message", + }) + } + + // Validate log level using SDK + if !logging.IsValidLogLevel(req.Level) { + return c.Status(400).JSON(fiber.Map{ + "error": "Invalid log level. Must be one of: debug, info, warn, error", + }) + } + + // Create log entry using SDK types + logEntry := LogEntry{ + ID: generateLogID(), + Timestamp: time.Now(), + Service: req.Service, + Subcomponent: req.Subcomponent, + Level: logging.GetLogLevelFromString(req.Level), + Message: req.Message, + Metadata: req.Metadata, + Context: req.Context, + } + + // Store log entry + if err := storeLogEntry(logEntry); err != nil { + return c.Status(500).JSON(fiber.Map{ + "error": "Failed to store log entry", + "details": err.Error(), + }) + } + + return c.Status(201).JSON(fiber.Map{ + "message": "Log entry stored successfully", + "log_id": logEntry.ID, + }) +} + +// LogRetrievalHandler handles log retrieval requests +func LogRetrievalHandler(c *fiber.Ctx) error { + var req LogRetrievalRequest + + // Parse query parameters + req.Service = c.Query("service", "") + req.Level = c.Query("level", "") + req.Subcomponent = c.Query("subcomponent", "") + req.Search = c.Query("search", "") + + // Parse limit and offset with defaults + limitStr := c.Query("limit", "100") + offsetStr := c.Query("offset", "0") + + limit, err := strconv.Atoi(limitStr) + if err != nil || limit <= 0 { + limit = 100 + } + if limit > 1000 { + limit = 1000 // Cap at 1000 + } + + offset, err := strconv.Atoi(offsetStr) + if err != nil || offset < 0 { + offset = 0 + } + + req.Limit = limit + req.Offset = offset + + // Retrieve logs + logs, total, err := retrieveLogs(req) + if err != nil { + return c.Status(500).JSON(fiber.Map{ + "error": "Failed to retrieve logs", + "details": err.Error(), + }) + } + + response := LogRetrievalResponse{ + Logs: logs, + Total: total, + Limit: req.Limit, + Offset: req.Offset, + } + + return c.JSON(response) +} + +// LogClearHandler handles clearing all logs +func LogClearHandler(c *fiber.Ctx) error { + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{"error": fmt.Sprintf("Failed to connect to Valkey: %v", err)}) + } + defer kvStore.Close() + + ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) + defer cancel() + + // Get all log keys + keys, err := kvStore.ListKeys(ctx, LOG_PREFIX+":*") + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{"error": fmt.Sprintf("Failed to list log keys: %v", err)}) + } + + // Delete all log keys + deletedCount := 0 + for _, key := range keys { + if err := kvStore.DeleteValue(ctx, key); err == nil { + deletedCount++ + } + } + + return c.JSON(fiber.Map{ + "message": "Logs cleared successfully", + "deleted_count": deletedCount, + }) +} + +// LogStatsHandler provides log statistics +func LogStatsHandler(c *fiber.Ctx) error { + stats, err := getLogStats() + if err != nil { + return c.Status(500).JSON(fiber.Map{ + "error": "Failed to retrieve log statistics", + "details": err.Error(), + }) + } + + return c.JSON(stats) +} + +// generateLogID creates a unique log ID +func generateLogID() string { + timestamp := time.Now().Format("20060102_150405") + nanos := time.Now().Nanosecond() + return fmt.Sprintf("log_%s_%06d", timestamp, nanos%1000000) +} + +// storeLogEntry stores a log entry in Valkey +func storeLogEntry(logEntry LogEntry) error { + kvStore, err := store.NewValkeyStore() + if err != nil { + return fmt.Errorf("failed to create valkey store: %w", err) + } + defer kvStore.Close() + + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + + // Serialize log entry + data, err := json.Marshal(logEntry) + if err != nil { + return fmt.Errorf("failed to marshal log entry: %w", err) + } + + // Create key with timestamp for sorting + key := fmt.Sprintf("%s:%s:%d:%s", LOG_PREFIX, logEntry.Service, logEntry.Timestamp.Unix(), logEntry.ID) + + // Store the log entry + if err := kvStore.SetValue(ctx, key, string(data)); err != nil { + return fmt.Errorf("failed to store log entry: %w", err) + } + + // Maintain log count and cleanup old logs (only occasionally to avoid performance impact) + // Only run maintenance every 10th log entry to reduce overhead + if time.Now().Unix()%10 == 0 { + if err := maintainLogCount(ctx, kvStore); err != nil { + // Log the error but don't fail the request + fmt.Printf("Warning: Failed to maintain log count: %v\n", err) + } + } + + return nil +} + +// retrieveLogs retrieves logs based on criteria +func retrieveLogs(req LogRetrievalRequest) ([]LogEntry, int, error) { + kvStore, err := store.NewValkeyStore() + if err != nil { + return nil, 0, fmt.Errorf("failed to create valkey store: %w", err) + } + defer kvStore.Close() + + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + + // Build pattern based on service filter + pattern := LOG_PREFIX + ":*" + if req.Service != "" { + pattern = fmt.Sprintf("%s:%s:*", LOG_PREFIX, req.Service) + } + + // Get all matching keys + keys, err := kvStore.ListKeys(ctx, pattern) + if err != nil { + return nil, 0, fmt.Errorf("failed to list log keys: %w", err) + } + + // Limit the number of keys we process to avoid memory issues + maxKeysToProcess := 1000 + if len(keys) > maxKeysToProcess { + keys = keys[:maxKeysToProcess] + } + + var logs []LogEntry + for _, key := range keys { + resp, err := kvStore.GetValue(ctx, key) + if err != nil { + continue // Skip keys that can't be retrieved + } + + var logEntry LogEntry + if err := json.Unmarshal([]byte(resp.Message.Value), &logEntry); err != nil { + continue // Skip malformed entries + } + + // Apply filters + if req.Level != "" && string(logEntry.Level) != req.Level { + continue + } + if req.Subcomponent != "" && logEntry.Subcomponent != req.Subcomponent { + continue + } + if req.Search != "" && !strings.Contains(strings.ToLower(logEntry.Message), strings.ToLower(req.Search)) { + continue + } + + logs = append(logs, logEntry) + } + + // Sort by timestamp (newest first) - using a more efficient approach + sort.Slice(logs, func(i, j int) bool { + return logs[i].Timestamp.After(logs[j].Timestamp) + }) + + total := len(logs) + + // Apply pagination + start := req.Offset + end := start + req.Limit + if start >= len(logs) { + return []LogEntry{}, total, nil + } + if end > len(logs) { + end = len(logs) + } + + return logs[start:end], total, nil +} + +// getLogStats provides log statistics +func getLogStats() (*LogStatsResponse, error) { + kvStore, err := store.NewValkeyStore() + if err != nil { + return nil, fmt.Errorf("failed to create valkey store: %w", err) + } + defer kvStore.Close() + + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + + // Get all log keys + keys, err := kvStore.ListKeys(ctx, LOG_PREFIX+":*") + if err != nil { + return nil, fmt.Errorf("failed to list log keys: %w", err) + } + + serviceStats := make(map[string]int) + levelStats := make(map[string]int) + var recentLogs []LogEntry + + for _, key := range keys { + resp, err := kvStore.GetValue(ctx, key) + if err != nil { + continue + } + + var logEntry LogEntry + if err := json.Unmarshal([]byte(resp.Message.Value), &logEntry); err != nil { + continue + } + + // Count by service + serviceStats[logEntry.Service]++ + + // Count by level + levelStats[string(logEntry.Level)]++ + + // Collect recent logs (last 10) + if len(recentLogs) < 10 { + recentLogs = append(recentLogs, logEntry) + } + } + + // Sort recent logs by timestamp (newest first) + sort.Slice(recentLogs, func(i, j int) bool { + return recentLogs[i].Timestamp.After(recentLogs[j].Timestamp) + }) + + return &LogStatsResponse{ + TotalLogs: len(keys), + ServiceStats: serviceStats, + LevelStats: levelStats, + RecentLogs: recentLogs, + }, nil +} + +// LogBusinessEvent logs a meaningful business event +func LogBusinessEvent(service, subcomponent, level, message string, metadata map[string]interface{}) { + logEntry := map[string]interface{}{ + "service": service, + "subcomponent": subcomponent, + "level": level, + "message": message, + "metadata": metadata, + "context": map[string]interface{}{ + "type": "business_event", + }, + } + + // Submit asynchronously + go func() { + body, err := json.Marshal(logEntry) + if err != nil { + return + } + + client := &http.Client{Timeout: 2 * time.Second} + req, err := http.NewRequest("POST", "http://localhost:9001/api/v1/logs", bytes.NewBuffer(body)) + if err != nil { + return + } + + req.Header.Set("Content-Type", "application/json") + if apiKey, err := infraauth.LoadSiriusAPIKey(); err == nil && apiKey != "" { + req.Header.Set("X-API-Key", apiKey) + } + client.Do(req) + }() +} + +// maintainLogCount ensures we don't exceed MAX_LOGS +func maintainLogCount(ctx context.Context, kvStore store.KVStore) error { + // Use a longer timeout for log maintenance + maintenanceCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second) + defer cancel() + + // Get all log keys + keys, err := kvStore.ListKeys(maintenanceCtx, LOG_PREFIX+":*") + if err != nil { + return err + } + + if len(keys) <= MAX_LOGS { + return nil // No cleanup needed + } + + // Sort keys by timestamp (oldest first) + // Key format: logs:service:timestamp:id + for i := 0; i < len(keys)-1; i++ { + for j := i + 1; j < len(keys); j++ { + // Extract timestamp from key for sorting + partsI := strings.Split(keys[i], ":") + partsJ := strings.Split(keys[j], ":") + if len(partsI) >= 3 && len(partsJ) >= 3 { + timestampI, errI := strconv.ParseInt(partsI[2], 10, 64) + timestampJ, errJ := strconv.ParseInt(partsJ[2], 10, 64) + if errI == nil && errJ == nil && timestampI > timestampJ { + keys[i], keys[j] = keys[j], keys[i] + } + } + } + } + + // Delete oldest logs + logsToDelete := len(keys) - MAX_LOGS + for i := 0; i < logsToDelete; i++ { + kvStore.DeleteValue(ctx, keys[i]) + } + + return nil +} + +// LogUpdateHandler handles updating a log entry +func LogUpdateHandler(c *fiber.Ctx) error { + logID := c.Params("logId") + if logID == "" { + return c.Status(400).JSON(fiber.Map{ + "error": "Log ID required", + }) + } + + var req struct { + Message string `json:"message,omitempty"` + Level string `json:"level,omitempty"` + Metadata map[string]interface{} `json:"metadata,omitempty"` + Context map[string]interface{} `json:"context,omitempty"` + } + + if err := c.BodyParser(&req); err != nil { + return c.Status(400).JSON(fiber.Map{ + "error": "Invalid request body", + "details": err.Error(), + }) + } + + // Validate log level if provided + if req.Level != "" && !logging.IsValidLogLevel(req.Level) { + return c.Status(400).JSON(fiber.Map{ + "error": "Invalid log level. Must be one of: debug, info, warn, error", + }) + } + + // Connect to Valkey + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(500).JSON(fiber.Map{ + "error": "Failed to connect to Valkey", + "details": err.Error(), + }) + } + defer kvStore.Close() + + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + + // Get existing log entry + key := fmt.Sprintf("logs:%s", logID) + resp, err := kvStore.GetValue(ctx, key) + if err != nil { + return c.Status(404).JSON(fiber.Map{ + "error": "Log entry not found", + }) + } + + var entry LogEntry + if err := json.Unmarshal([]byte(resp.Message.Value), &entry); err != nil { + return c.Status(500).JSON(fiber.Map{ + "error": "Invalid log entry format", + }) + } + + // Update fields if provided + if req.Message != "" { + entry.Message = req.Message + } + if req.Level != "" { + entry.Level = logging.GetLogLevelFromString(req.Level) + } + if req.Metadata != nil { + entry.Metadata = req.Metadata + } + if req.Context != nil { + entry.Context = req.Context + } + + // Store updated entry + if err := storeLogEntry(entry); err != nil { + return c.Status(500).JSON(fiber.Map{ + "error": "Failed to update log entry", + "details": err.Error(), + }) + } + + return c.JSON(fiber.Map{ + "message": "Log entry updated successfully", + "log_id": logID, + }) +} + +// LogDeleteHandler handles deleting a log entry +func LogDeleteHandler(c *fiber.Ctx) error { + logID := c.Params("logId") + if logID == "" { + return c.Status(400).JSON(fiber.Map{ + "error": "Log ID required", + }) + } + + // Connect to Valkey + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(500).JSON(fiber.Map{ + "error": "Failed to connect to Valkey", + "details": err.Error(), + }) + } + defer kvStore.Close() + + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + + // Delete log entry + key := fmt.Sprintf("logs:%s", logID) + if err := kvStore.DeleteValue(ctx, key); err != nil { + return c.Status(500).JSON(fiber.Map{ + "error": "Failed to delete log entry", + "details": err.Error(), + }) + } + + return c.JSON(fiber.Map{ + "message": "Log entry deleted successfully", + "log_id": logID, + }) +} diff --git a/sirius-api/handlers/performance_handler.go b/sirius-api/handlers/performance_handler.go new file mode 100644 index 0000000..305af10 --- /dev/null +++ b/sirius-api/handlers/performance_handler.go @@ -0,0 +1,425 @@ +package handlers + +import ( + "context" + "encoding/json" + "fmt" + "sort" + "strconv" + "strings" + "time" + + "github.com/SiriusScan/go-api/sirius/logging" + "github.com/SiriusScan/go-api/sirius/store" + "github.com/gofiber/fiber/v2" +) + +// PerformanceMetricsResponse represents the response for performance metrics +type PerformanceMetricsResponse struct { + Metrics []PerformanceMetric `json:"metrics"` + Total int `json:"total"` + Limit int `json:"limit"` + Offset int `json:"offset"` + Summary PerformanceSummary `json:"summary"` + TimeRange TimeRange `json:"time_range"` +} + +// PerformanceMetric represents a single performance metric +type PerformanceMetric struct { + ID string `json:"id"` + Timestamp time.Time `json:"timestamp"` + Service string `json:"service"` + Endpoint string `json:"endpoint"` + Method string `json:"method"` + Duration int64 `json:"duration_ms"` + StatusCode int `json:"status_code"` + ResponseSize int `json:"response_size"` + RequestID string `json:"request_id,omitempty"` + Metadata map[string]interface{} `json:"metadata,omitempty"` +} + +// PerformanceSummary provides aggregated performance statistics +type PerformanceSummary struct { + TotalRequests int `json:"total_requests"` + AverageResponse float64 `json:"average_response_ms"` + MinResponse int64 `json:"min_response_ms"` + MaxResponse int64 `json:"max_response_ms"` + ErrorRate float64 `json:"error_rate"` + RequestsPerMinute float64 `json:"requests_per_minute"` + TopEndpoints []EndpointStats `json:"top_endpoints"` + ServiceStats []ServiceStats `json:"service_stats"` +} + +// EndpointStats represents statistics for a specific endpoint +type EndpointStats struct { + Endpoint string `json:"endpoint"` + Method string `json:"method"` + RequestCount int `json:"request_count"` + AverageResponse float64 `json:"average_response_ms"` + ErrorCount int `json:"error_count"` + ErrorRate float64 `json:"error_rate"` +} + +// ServiceStats represents statistics for a specific service +type ServiceStats struct { + Service string `json:"service"` + RequestCount int `json:"request_count"` + AverageResponse float64 `json:"average_response_ms"` + ErrorCount int `json:"error_count"` + ErrorRate float64 `json:"error_rate"` +} + +// TimeRange represents the time range for the metrics +type TimeRange struct { + Start time.Time `json:"start"` + End time.Time `json:"end"` +} + +// PerformanceMetricsRequest represents the request parameters for performance metrics +type PerformanceMetricsRequest struct { + Service string `json:"service,omitempty"` + Endpoint string `json:"endpoint,omitempty"` + Method string `json:"method,omitempty"` + Limit int `json:"limit,omitempty"` + Offset int `json:"offset,omitempty"` + TimeRange string `json:"time_range,omitempty"` // "1h", "24h", "7d", "30d" +} + +const ( + PERFORMANCE_LOG_PREFIX = "logs" +) + +// PerformanceMetricsHandler handles performance metrics retrieval +func PerformanceMetricsHandler(c *fiber.Ctx) error { + var req PerformanceMetricsRequest + + // Parse query parameters + req.Service = c.Query("service", "") + req.Endpoint = c.Query("endpoint", "") + req.Method = c.Query("method", "") + req.TimeRange = c.Query("time_range", "1h") + + // Parse limit and offset with defaults + limitStr := c.Query("limit", "100") + offsetStr := c.Query("offset", "0") + + limit, err := strconv.Atoi(limitStr) + if err != nil || limit <= 0 { + limit = 100 + } + if limit > 1000 { + limit = 1000 // Cap at 1000 + } + + offset, err := strconv.Atoi(offsetStr) + if err != nil || offset < 0 { + offset = 0 + } + + req.Limit = limit + req.Offset = offset + + // Retrieve performance metrics + metrics, total, summary, timeRange, err := retrievePerformanceMetrics(req) + if err != nil { + return c.Status(500).JSON(fiber.Map{ + "error": "Failed to retrieve performance metrics", + "details": err.Error(), + }) + } + + response := PerformanceMetricsResponse{ + Metrics: metrics, + Total: total, + Limit: req.Limit, + Offset: req.Offset, + Summary: summary, + TimeRange: timeRange, + } + + return c.JSON(response) +} + +// retrievePerformanceMetrics retrieves performance metrics from logs +func retrievePerformanceMetrics(req PerformanceMetricsRequest) ([]PerformanceMetric, int, PerformanceSummary, TimeRange, error) { + kvStore, err := store.NewValkeyStore() + if err != nil { + return nil, 0, PerformanceSummary{}, TimeRange{}, fmt.Errorf("failed to create valkey store: %w", err) + } + defer kvStore.Close() + + ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + + // Calculate time range + timeRange := calculateTimeRange(req.TimeRange) + + // Build pattern based on service filter + pattern := PERFORMANCE_LOG_PREFIX + ":*" + if req.Service != "" { + pattern = fmt.Sprintf("%s:%s:*", PERFORMANCE_LOG_PREFIX, req.Service) + } + + // Get all matching keys + keys, err := kvStore.ListKeys(ctx, pattern) + if err != nil { + return nil, 0, PerformanceSummary{}, TimeRange{}, fmt.Errorf("failed to list log keys: %w", err) + } + + // Limit the number of keys we process to avoid memory issues + maxKeysToProcess := 2000 + if len(keys) > maxKeysToProcess { + keys = keys[:maxKeysToProcess] + } + + var metrics []PerformanceMetric + var allMetrics []PerformanceMetric + + for _, key := range keys { + resp, err := kvStore.GetValue(ctx, key) + if err != nil { + continue // Skip keys that can't be retrieved + } + + var logEntry logging.LogEntry + if err := json.Unmarshal([]byte(resp.Message.Value), &logEntry); err != nil { + continue // Skip malformed entries + } + + // Only process performance metrics + if logEntry.Context == nil || logEntry.Context["type"] != "performance_metric" { + continue + } + + // Check time range + if logEntry.Timestamp.Before(timeRange.Start) || logEntry.Timestamp.After(timeRange.End) { + continue + } + + // Extract performance data from metadata + performanceData, err := extractPerformanceData(logEntry) + if err != nil { + continue // Skip entries without valid performance data + } + + // Apply filters + if req.Endpoint != "" && !strings.Contains(performanceData.Endpoint, req.Endpoint) { + continue + } + if req.Method != "" && performanceData.Method != req.Method { + continue + } + + allMetrics = append(allMetrics, performanceData) + } + + // Sort by timestamp (newest first) + sort.Slice(allMetrics, func(i, j int) bool { + return allMetrics[i].Timestamp.After(allMetrics[j].Timestamp) + }) + + total := len(allMetrics) + + // Apply pagination + start := req.Offset + end := start + req.Limit + if start >= len(allMetrics) { + metrics = []PerformanceMetric{} + } else { + if end > len(allMetrics) { + end = len(allMetrics) + } + metrics = allMetrics[start:end] + } + + // Calculate summary + summary := calculatePerformanceSummary(allMetrics, timeRange) + + return metrics, total, summary, timeRange, nil +} + +// extractPerformanceData extracts performance data from a log entry +func extractPerformanceData(logEntry logging.LogEntry) (PerformanceMetric, error) { + metric := PerformanceMetric{ + ID: logEntry.ID, + Timestamp: logEntry.Timestamp, + Service: logEntry.Service, + Metadata: logEntry.Metadata, + } + + // Extract performance data from metadata + if logEntry.Metadata != nil { + if performance, ok := logEntry.Metadata["performance"].(map[string]interface{}); ok { + if duration, ok := performance["duration"].(string); ok { + if d, err := time.ParseDuration(duration); err == nil { + metric.Duration = d.Milliseconds() + } + } + } + + // Extract request details from metadata + if requestID, ok := logEntry.Metadata["request_id"].(string); ok { + metric.RequestID = requestID + } + if method, ok := logEntry.Metadata["method"].(string); ok { + metric.Method = method + } + if path, ok := logEntry.Metadata["path"].(string); ok { + metric.Endpoint = path + } + if statusCode, ok := logEntry.Metadata["status_code"].(float64); ok { + metric.StatusCode = int(statusCode) + } + if responseSize, ok := logEntry.Metadata["response_size"].(float64); ok { + metric.ResponseSize = int(responseSize) + } + } + + // Validate that we have essential data + if metric.Duration == 0 || metric.Endpoint == "" { + return metric, fmt.Errorf("missing essential performance data") + } + + return metric, nil +} + +// calculateTimeRange calculates the time range based on the request +func calculateTimeRange(timeRangeStr string) TimeRange { + now := time.Now() + var start time.Time + + switch timeRangeStr { + case "1h": + start = now.Add(-1 * time.Hour) + case "24h": + start = now.Add(-24 * time.Hour) + case "7d": + start = now.Add(-7 * 24 * time.Hour) + case "30d": + start = now.Add(-30 * 24 * time.Hour) + default: + start = now.Add(-1 * time.Hour) // Default to 1 hour + } + + return TimeRange{ + Start: start, + End: now, + } +} + +// calculatePerformanceSummary calculates aggregated performance statistics +func calculatePerformanceSummary(metrics []PerformanceMetric, timeRange TimeRange) PerformanceSummary { + if len(metrics) == 0 { + return PerformanceSummary{} + } + + summary := PerformanceSummary{ + TotalRequests: len(metrics), + MinResponse: metrics[0].Duration, + MaxResponse: metrics[0].Duration, + } + + var totalDuration int64 + var errorCount int + endpointStats := make(map[string]*EndpointStats) + serviceStats := make(map[string]*ServiceStats) + + for _, metric := range metrics { + // Calculate response time statistics + totalDuration += metric.Duration + if metric.Duration < summary.MinResponse { + summary.MinResponse = metric.Duration + } + if metric.Duration > summary.MaxResponse { + summary.MaxResponse = metric.Duration + } + + // Count errors (status codes >= 400) + if metric.StatusCode >= 400 { + errorCount++ + } + + // Aggregate by endpoint + endpointKey := fmt.Sprintf("%s %s", metric.Method, metric.Endpoint) + if stats, exists := endpointStats[endpointKey]; exists { + stats.RequestCount++ + stats.AverageResponse = (stats.AverageResponse*float64(stats.RequestCount-1) + float64(metric.Duration)) / float64(stats.RequestCount) + if metric.StatusCode >= 400 { + stats.ErrorCount++ + } + } else { + endpointStats[endpointKey] = &EndpointStats{ + Endpoint: metric.Endpoint, + Method: metric.Method, + RequestCount: 1, + AverageResponse: float64(metric.Duration), + ErrorCount: 0, + } + if metric.StatusCode >= 400 { + endpointStats[endpointKey].ErrorCount = 1 + } + } + + // Aggregate by service + if stats, exists := serviceStats[metric.Service]; exists { + stats.RequestCount++ + stats.AverageResponse = (stats.AverageResponse*float64(stats.RequestCount-1) + float64(metric.Duration)) / float64(stats.RequestCount) + if metric.StatusCode >= 400 { + stats.ErrorCount++ + } + } else { + serviceStats[metric.Service] = &ServiceStats{ + Service: metric.Service, + RequestCount: 1, + AverageResponse: float64(metric.Duration), + ErrorCount: 0, + } + if metric.StatusCode >= 400 { + serviceStats[metric.Service].ErrorCount = 1 + } + } + } + + // Calculate averages and rates + summary.AverageResponse = float64(totalDuration) / float64(len(metrics)) + summary.ErrorRate = float64(errorCount) / float64(len(metrics)) * 100 + + // Calculate requests per minute + durationMinutes := timeRange.End.Sub(timeRange.Start).Minutes() + if durationMinutes > 0 { + summary.RequestsPerMinute = float64(len(metrics)) / durationMinutes + } + + // Calculate error rates for endpoints and services + for _, stats := range endpointStats { + stats.ErrorRate = float64(stats.ErrorCount) / float64(stats.RequestCount) * 100 + } + for _, stats := range serviceStats { + stats.ErrorRate = float64(stats.ErrorCount) / float64(stats.RequestCount) * 100 + } + + // Sort and get top endpoints (by request count) + var topEndpoints []EndpointStats + for _, stats := range endpointStats { + topEndpoints = append(topEndpoints, *stats) + } + sort.Slice(topEndpoints, func(i, j int) bool { + return topEndpoints[i].RequestCount > topEndpoints[j].RequestCount + }) + if len(topEndpoints) > 10 { + topEndpoints = topEndpoints[:10] + } + summary.TopEndpoints = topEndpoints + + // Sort and get service stats + var serviceStatsList []ServiceStats + for _, stats := range serviceStats { + serviceStatsList = append(serviceStatsList, *stats) + } + sort.Slice(serviceStatsList, func(i, j int) bool { + return serviceStatsList[i].RequestCount > serviceStatsList[j].RequestCount + }) + summary.ServiceStats = serviceStatsList + + return summary +} diff --git a/sirius-api/handlers/scan_handler.go b/sirius-api/handlers/scan_handler.go new file mode 100644 index 0000000..5d3e043 --- /dev/null +++ b/sirius-api/handlers/scan_handler.go @@ -0,0 +1,388 @@ +package handlers + +import ( + "context" + "encoding/base64" + "encoding/json" + "log/slog" + "strings" + "time" + + "github.com/SiriusScan/go-api/sirius/queue" + "github.com/SiriusScan/go-api/sirius/store" + "github.com/gofiber/fiber/v2" +) + +// ControlMessage represents a control command for the scanner +type ControlMessage struct { + Action string `json:"action"` // Action to perform (e.g., "cancel") + ScanID string `json:"scan_id"` // Optional: specific scan to cancel + Timestamp string `json:"timestamp"` // When the command was issued +} + +// ScanStatusResponse represents the current scan status +type ScanStatusResponse struct { + ID string `json:"id,omitempty"` + Status string `json:"status"` + Targets []string `json:"targets,omitempty"` + Hosts []string `json:"hosts,omitempty"` + HostsCompleted int `json:"hosts_completed"` + TotalHosts int `json:"total_hosts"` + Vulnerabilities int `json:"vulnerabilities"` + StartTime string `json:"start_time,omitempty"` + EndTime string `json:"end_time,omitempty"` +} + +const ( + currentScanKey = "currentScan" + scanControlQueue = "scan_control" +) + +// CancelScan handles the POST /api/v1/scans/cancel endpoint. +// It sends a cancel command to the scanner and updates the scan status. +func CancelScan(c *fiber.Ctx) error { + ctx := context.Background() + + // Get the optional scan ID from request body + var requestBody struct { + ScanID string `json:"scan_id"` + } + // Ignore parsing errors - scan_id is optional + _ = c.BodyParser(&requestBody) + + slog.Info("Received scan cancel request", "scan_id", requestBody.ScanID) + + // First, update the scan status to "cancelling" in ValKey + kvStore, err := store.NewValkeyStore() + if err != nil { + slog.Error("Failed to connect to ValKey", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "success": false, + "error": "Failed to connect to store", + }) + } + defer kvStore.Close() + + // Get current scan to check if there's one running + resp, err := kvStore.GetValue(ctx, currentScanKey) + if err != nil { + if strings.Contains(err.Error(), "not found") { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "success": false, + "error": "No scan is currently running", + }) + } + slog.Error("Failed to get current scan", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "success": false, + "error": "Failed to get scan status", + }) + } + + // Decode base64-encoded scan result (UI stores it with btoa) + rawValue := resp.Message.Value + decodedBytes, err := base64.StdEncoding.DecodeString(rawValue) + if err != nil { + slog.Error("Failed to decode base64 scan result", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "success": false, + "error": "Failed to decode scan status", + }) + } + + // Parse current scan + var scanResult map[string]interface{} + if err := json.Unmarshal(decodedBytes, &scanResult); err != nil { + slog.Error("Failed to parse scan result", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "success": false, + "error": "Failed to parse scan status", + }) + } + + // Check if scan is already completed or cancelled + status, _ := scanResult["status"].(string) + if status == "completed" || status == "cancelled" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "success": false, + "error": "Scan is already " + status, + }) + } + + // Update status to "cancelling" + scanResult["status"] = "cancelling" + updatedJSON, err := json.Marshal(scanResult) + if err != nil { + slog.Error("Failed to marshal updated scan", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "success": false, + "error": "Failed to update scan status", + }) + } + + // Encode back to base64 to maintain consistency with UI format + encodedValue := base64.StdEncoding.EncodeToString(updatedJSON) + + if err := kvStore.SetValue(ctx, currentScanKey, encodedValue); err != nil { + slog.Error("Failed to update scan status", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "success": false, + "error": "Failed to update scan status", + }) + } + + // Send cancel command to scanner via RabbitMQ + cancelCmd := ControlMessage{ + Action: "cancel", + ScanID: requestBody.ScanID, + Timestamp: time.Now().Format(time.RFC3339), + } + + cmdJSON, err := json.Marshal(cancelCmd) + if err != nil { + slog.Error("Failed to marshal cancel command", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "success": false, + "error": "Failed to create cancel command", + }) + } + + if err := queue.Send(scanControlQueue, string(cmdJSON)); err != nil { + slog.Error("Failed to send cancel command", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "success": false, + "error": "Failed to send cancel command to scanner", + }) + } + + slog.Info("Cancel command sent successfully") + + return c.Status(fiber.StatusOK).JSON(fiber.Map{ + "success": true, + "message": "Cancel request sent", + "status": "cancelling", + }) +} + +// GetScanStatus handles the GET /api/v1/scans/status endpoint. +// It returns the current scan status from ValKey. +func GetScanStatus(c *fiber.Ctx) error { + ctx := context.Background() + + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to store", + }) + } + defer kvStore.Close() + + resp, err := kvStore.GetValue(ctx, currentScanKey) + if err != nil { + if strings.Contains(err.Error(), "not found") { + return c.JSON(ScanStatusResponse{ + Status: "idle", + }) + } + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to get scan status", + }) + } + + // Decode base64-encoded scan result (UI stores it with btoa) + decodedBytes, err := base64.StdEncoding.DecodeString(resp.Message.Value) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to decode scan status", + }) + } + + // Parse and return the scan status + var scanResult map[string]interface{} + if err := json.Unmarshal(decodedBytes, &scanResult); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to parse scan status", + }) + } + + // Build response + response := ScanStatusResponse{ + Status: getStringField(scanResult, "status"), + } + + // Add optional fields if present + if id, ok := scanResult["id"].(string); ok { + response.ID = id + } + if hosts, ok := scanResult["hosts"].([]interface{}); ok { + response.TotalHosts = len(hosts) + for _, h := range hosts { + if s, ok := h.(string); ok { + response.Hosts = append(response.Hosts, s) + } + } + } + if completed, ok := scanResult["hosts_completed"].(float64); ok { + response.HostsCompleted = int(completed) + } + if vulns, ok := scanResult["vulnerabilities"].([]interface{}); ok { + response.Vulnerabilities = len(vulns) + } + if startTime, ok := scanResult["start_time"].(string); ok { + response.StartTime = startTime + } + if endTime, ok := scanResult["end_time"].(string); ok { + response.EndTime = endTime + } + + return c.JSON(response) +} + +// ForceStopScan handles the POST /api/v1/scans/force-stop endpoint. +// It forcefully stops the scan by sending a force_cancel command to the scanner +// AND directly setting the scan status to "cancelled" in ValKey (does not wait +// for scanner acknowledgement). This is the Tier 2 escalation when graceful +// stop fails. +func ForceStopScan(c *fiber.Ctx) error { + ctx := context.Background() + + var requestBody struct { + ScanID string `json:"scan_id"` + } + _ = c.BodyParser(&requestBody) + + slog.Warn("Received FORCE STOP request", "scan_id", requestBody.ScanID) + + kvStore, err := store.NewValkeyStore() + if err != nil { + slog.Error("Failed to connect to ValKey", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "success": false, + "error": "Failed to connect to store", + }) + } + defer kvStore.Close() + + // Best-effort: send force_cancel command to scanner via RabbitMQ + forceCmd := ControlMessage{ + Action: "force_cancel", + ScanID: requestBody.ScanID, + Timestamp: time.Now().Format(time.RFC3339), + } + cmdJSON, err := json.Marshal(forceCmd) + if err == nil { + if sendErr := queue.Send(scanControlQueue, string(cmdJSON)); sendErr != nil { + slog.Warn("Failed to send force_cancel command (scanner may be unresponsive)", "error", sendErr) + // Continue anyway - we'll update ValKey directly + } else { + slog.Info("Force cancel command sent to scanner") + } + } + + // Directly update ValKey to "cancelled" regardless of scanner response + resp, err := kvStore.GetValue(ctx, currentScanKey) + if err != nil { + if strings.Contains(err.Error(), "not found") { + return c.Status(fiber.StatusOK).JSON(fiber.Map{ + "success": true, + "message": "No scan data found - already clean", + "status": "idle", + }) + } + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "success": false, + "error": "Failed to get scan status", + }) + } + + decodedBytes, err := base64.StdEncoding.DecodeString(resp.Message.Value) + if err != nil { + slog.Error("Failed to decode scan result during force stop", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "success": false, + "error": "Failed to decode scan status", + }) + } + + var scanResult map[string]interface{} + if err := json.Unmarshal(decodedBytes, &scanResult); err != nil { + slog.Error("Failed to parse scan result during force stop", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "success": false, + "error": "Failed to parse scan status", + }) + } + + // Force set status to cancelled with end time + scanResult["status"] = "cancelled" + scanResult["end_time"] = time.Now().Format(time.RFC3339) + + updatedJSON, err := json.Marshal(scanResult) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "success": false, + "error": "Failed to update scan status", + }) + } + + encodedValue := base64.StdEncoding.EncodeToString(updatedJSON) + if err := kvStore.SetValue(ctx, currentScanKey, encodedValue); err != nil { + slog.Error("Failed to force-update scan status", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "success": false, + "error": "Failed to update scan status", + }) + } + + slog.Info("Force stop completed - scan status set to cancelled") + + return c.Status(fiber.StatusOK).JSON(fiber.Map{ + "success": true, + "message": "Scan force stopped", + "status": "cancelled", + }) +} + +// ResetScanState handles the POST /api/v1/scans/reset endpoint. +// This is the Tier 3 last-resort: it deletes the currentScan key from ValKey +// entirely, resetting the dashboard to an idle state. No RabbitMQ interaction. +func ResetScanState(c *fiber.Ctx) error { + ctx := context.Background() + + slog.Warn("Received scan state RESET request") + + kvStore, err := store.NewValkeyStore() + if err != nil { + slog.Error("Failed to connect to ValKey", "error", err) + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "success": false, + "error": "Failed to connect to store", + }) + } + defer kvStore.Close() + + // Delete the currentScan key entirely + if err := kvStore.DeleteValue(ctx, currentScanKey); err != nil { + // If key doesn't exist, that's fine + if !strings.Contains(err.Error(), "not found") { + slog.Warn("Failed to delete currentScan key", "error", err) + // Fall through - try to set it to empty state instead + } + } + + slog.Info("Scan state reset - dashboard cleared") + + return c.Status(fiber.StatusOK).JSON(fiber.Map{ + "success": true, + "message": "Scan state reset", + "status": "idle", + }) +} + +// getStringField safely extracts a string field from a map +func getStringField(m map[string]interface{}, key string) string { + if v, ok := m[key].(string); ok { + return v + } + return "" +} diff --git a/sirius-api/handlers/script_handler.go b/sirius-api/handlers/script_handler.go new file mode 100644 index 0000000..2f3f59f --- /dev/null +++ b/sirius-api/handlers/script_handler.go @@ -0,0 +1,393 @@ +package handlers + +import ( + "context" + "encoding/json" + "fmt" + "log/slog" + "strings" + "time" + + "github.com/SiriusScan/go-api/sirius/store" + "github.com/gofiber/fiber/v2" +) + +// Script represents an NSE script +type Script struct { + ID string `json:"id"` + Name string `json:"name"` + Path string `json:"path"` + Protocol string `json:"protocol"` + Content *ScriptContent `json:"content,omitempty"` +} + +// ScriptContent represents script content and metadata +type ScriptContent struct { + Content string `json:"content"` + Metadata ScriptMetadata `json:"metadata"` + UpdatedAt int64 `json:"updated_at"` +} + +// ScriptMetadata represents script metadata +type ScriptMetadata struct { + Author string `json:"author"` + Tags []string `json:"tags"` + Description string `json:"description"` +} + +// Manifest represents the NSE scripts manifest +type Manifest struct { + Name string `json:"name"` + Version string `json:"version"` + Description string `json:"description"` + Scripts map[string]Script `json:"scripts"` +} + +const ( + nseManifestKey = "nse:manifest" + nseScriptPrefix = "nse:script:" +) + +// GetScripts returns all scripts from the manifest +func GetScripts(c *fiber.Ctx) error { + ctx := context.Background() + + // Get ValKey store + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to store", + }) + } + defer kvStore.Close() + + // Get manifest + manifest, err := getManifest(ctx, kvStore) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to get script manifest", + }) + } + + // Convert map to slice + scripts := make([]Script, 0, len(manifest.Scripts)) + for _, script := range manifest.Scripts { + scripts = append(scripts, script) + } + + return c.JSON(scripts) +} + +// GetScript returns a single script with its content +func GetScript(c *fiber.Ctx) error { + ctx := context.Background() + scriptID := c.Params("id") + + // Get ValKey store + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to store", + }) + } + defer kvStore.Close() + + // Get script from manifest + manifest, err := getManifest(ctx, kvStore) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to get script manifest", + }) + } + + script, exists := manifest.Scripts[scriptID] + if !exists { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": fmt.Sprintf("Script '%s' not found", scriptID), + }) + } + + // Get script content + content, err := getScriptContent(ctx, kvStore, scriptID) + if err != nil { + // Return script without content if not available + slog.Warn("Failed to get script content", "script_id", scriptID, "error", err) + } else { + script.Content = content + } + + return c.JSON(script) +} + +// UpdateScript updates script content and metadata +func UpdateScript(c *fiber.Ctx) error { + ctx := context.Background() + scriptID := c.Params("id") + + var content ScriptContent + if err := c.BodyParser(&content); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Invalid request body", + }) + } + + // Validate content + if content.Content == "" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Script content is required", + }) + } + + // Set update timestamp + content.UpdatedAt = time.Now().Unix() + + // Get ValKey store + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to store", + }) + } + defer kvStore.Close() + + // Check if script exists in manifest + manifest, err := getManifest(ctx, kvStore) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to get script manifest", + }) + } + + if _, exists := manifest.Scripts[scriptID]; !exists { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": fmt.Sprintf("Script '%s' not found", scriptID), + }) + } + + // Store updated content + if err := storeScriptContent(ctx, kvStore, scriptID, &content); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to update script", + }) + } + + slog.Info("Updated script", "script_id", scriptID) + + return c.JSON(fiber.Map{ + "message": "Script updated successfully", + "script_id": scriptID, + }) +} + +// CreateScript creates a new custom script +func CreateScript(c *fiber.Ctx) error { + ctx := context.Background() + + var script Script + if err := c.BodyParser(&script); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Invalid request body", + }) + } + + // Validate script + if script.ID == "" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Script ID is required", + }) + } + if script.Name == "" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Script name is required", + }) + } + if script.Content == nil || script.Content.Content == "" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Script content is required", + }) + } + + // Get ValKey store + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to store", + }) + } + defer kvStore.Close() + + // Get manifest + manifest, err := getManifest(ctx, kvStore) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to get script manifest", + }) + } + + // Check if script already exists + if _, exists := manifest.Scripts[script.ID]; exists { + return c.Status(fiber.StatusConflict).JSON(fiber.Map{ + "error": fmt.Sprintf("Script '%s' already exists", script.ID), + }) + } + + // Set default values if not provided + if script.Protocol == "" { + script.Protocol = "custom" + } + if script.Path == "" { + script.Path = fmt.Sprintf("scripts/%s.nse", script.ID) + } + + // Set update timestamp + script.Content.UpdatedAt = time.Now().Unix() + + // Add to manifest + manifest.Scripts[script.ID] = Script{ + ID: script.ID, + Name: script.Name, + Path: script.Path, + Protocol: script.Protocol, + } + + // Store manifest + if err := storeManifest(ctx, kvStore, manifest); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to update manifest", + }) + } + + // Store script content + if err := storeScriptContent(ctx, kvStore, script.ID, script.Content); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to store script content", + }) + } + + slog.Info("Created custom script", "script_id", script.ID) + + return c.Status(fiber.StatusCreated).JSON(script) +} + +// DeleteScript deletes a custom script +func DeleteScript(c *fiber.Ctx) error { + ctx := context.Background() + scriptID := c.Params("id") + + // Get ValKey store + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to store", + }) + } + defer kvStore.Close() + + // Get manifest + manifest, err := getManifest(ctx, kvStore) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to get script manifest", + }) + } + + // Check if script exists + script, exists := manifest.Scripts[scriptID] + if !exists { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": fmt.Sprintf("Script '%s' not found", scriptID), + }) + } + + // Only allow deletion of custom scripts + if script.Protocol != "custom" { + return c.Status(fiber.StatusForbidden).JSON(fiber.Map{ + "error": "Cannot delete system script", + }) + } + + // Remove from manifest + delete(manifest.Scripts, scriptID) + + // Store updated manifest + if err := storeManifest(ctx, kvStore, manifest); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to update manifest", + }) + } + + // Delete script content + key := nseScriptPrefix + scriptID + if err := kvStore.DeleteValue(ctx, key); err != nil { + slog.Warn("Failed to delete script content", "error", err) + } + + slog.Info("Deleted custom script", "script_id", scriptID) + + return c.SendStatus(fiber.StatusNoContent) +} + +// Helper functions + +func getManifest(ctx context.Context, kvStore store.KVStore) (*Manifest, error) { + resp, err := kvStore.GetValue(ctx, nseManifestKey) + if err != nil { + return nil, fmt.Errorf("failed to get manifest: %w", err) + } + + var manifest Manifest + if err := json.Unmarshal([]byte(resp.Message.Value), &manifest); err != nil { + return nil, fmt.Errorf("failed to unmarshal manifest: %w", err) + } + + if manifest.Scripts == nil { + manifest.Scripts = make(map[string]Script) + } + + return &manifest, nil +} + +func storeManifest(ctx context.Context, kvStore store.KVStore, manifest *Manifest) error { + manifestJSON, err := json.Marshal(manifest) + if err != nil { + return fmt.Errorf("failed to marshal manifest: %w", err) + } + + if err := kvStore.SetValue(ctx, nseManifestKey, string(manifestJSON)); err != nil { + return fmt.Errorf("failed to store manifest: %w", err) + } + + return nil +} + +func getScriptContent(ctx context.Context, kvStore store.KVStore, scriptID string) (*ScriptContent, error) { + key := nseScriptPrefix + scriptID + resp, err := kvStore.GetValue(ctx, key) + if err != nil { + if strings.Contains(err.Error(), "not found") { + return nil, fmt.Errorf("script content not found") + } + return nil, fmt.Errorf("failed to get script content: %w", err) + } + + var content ScriptContent + if err := json.Unmarshal([]byte(resp.Message.Value), &content); err != nil { + return nil, fmt.Errorf("failed to unmarshal script content: %w", err) + } + + return &content, nil +} + +func storeScriptContent(ctx context.Context, kvStore store.KVStore, scriptID string, content *ScriptContent) error { + contentJSON, err := json.Marshal(content) + if err != nil { + return fmt.Errorf("failed to marshal script content: %w", err) + } + + key := nseScriptPrefix + scriptID + if err := kvStore.SetValue(ctx, key, string(contentJSON)); err != nil { + return fmt.Errorf("failed to store script content: %w", err) + } + + return nil +} diff --git a/sirius-api/handlers/snapshot_handler.go b/sirius-api/handlers/snapshot_handler.go new file mode 100644 index 0000000..788915a --- /dev/null +++ b/sirius-api/handlers/snapshot_handler.go @@ -0,0 +1,137 @@ +package handlers + +import ( + "context" + "fmt" + "strconv" + + "github.com/SiriusScan/go-api/sirius/snapshot" + "github.com/SiriusScan/go-api/sirius/store" + "github.com/gofiber/fiber/v2" +) + +// GetVulnerabilityTrends handles GET /api/v1/statistics/vulnerability-trends +func GetVulnerabilityTrends(c *fiber.Ctx) error { + // Parse query parameters - now uses limit (number of snapshots) instead of days + limitParam := c.Query("limit", "7") + limit, err := strconv.Atoi(limitParam) + if err != nil || limit < 1 { + limit = 7 + } + if limit > 10 { + limit = 10 // Cap at maximum retention + } + + // Initialize Valkey store and snapshot manager + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to data store", + }) + } + defer kvStore.Close() + + manager := snapshot.NewSnapshotManager(kvStore) + ctx := context.Background() + + // Get trend data (returns up to limit most recent snapshots) + snapshots, err := manager.GetTrendData(ctx, limit) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": fmt.Sprintf("Failed to retrieve trend data: %v", err), + }) + } + + return c.JSON(fiber.Map{ + "snapshots": snapshots, + "limit_requested": limit, + "snapshots_returned": len(snapshots), + }) +} + +// GetSnapshot handles GET /api/v1/statistics/vulnerability-snapshot/:snapshotId +func GetSnapshot(c *fiber.Ctx) error { + snapshotID := c.Params("snapshotId") + + if snapshotID == "" { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Snapshot ID is required", + }) + } + + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to data store", + }) + } + defer kvStore.Close() + + manager := snapshot.NewSnapshotManager(kvStore) + ctx := context.Background() + + snapshot, err := manager.GetSnapshot(ctx, snapshotID) + if err != nil { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": fmt.Sprintf("Snapshot not found for ID %s", snapshotID), + }) + } + + return c.JSON(snapshot) +} + +// CreateSnapshot handles POST /api/v1/statistics/vulnerability-snapshot (manual trigger) +func CreateSnapshot(c *fiber.Ctx) error { + // Optional: Add authentication/authorization check here + + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to data store", + }) + } + defer kvStore.Close() + + manager := snapshot.NewSnapshotManager(kvStore) + ctx := context.Background() + + // Pass empty string to auto-generate timestamp-based snapshot ID + snapshot, err := manager.CreateSnapshot(ctx, "") + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": fmt.Sprintf("Failed to create snapshot: %v", err), + }) + } + + return c.Status(fiber.StatusCreated).JSON(fiber.Map{ + "message": "Snapshot created successfully", + "snapshot": snapshot, + }) +} + +// ListSnapshots handles GET /api/v1/statistics/vulnerability-snapshots +func ListSnapshots(c *fiber.Ctx) error { + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to data store", + }) + } + defer kvStore.Close() + + manager := snapshot.NewSnapshotManager(kvStore) + ctx := context.Background() + + snapshotIDs, err := manager.ListSnapshots(ctx) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to list snapshots", + }) + } + + return c.JSON(fiber.Map{ + "available_snapshot_ids": snapshotIDs, + "count": len(snapshotIDs), + }) +} + diff --git a/sirius-api/handlers/statistics_handler.go b/sirius-api/handlers/statistics_handler.go new file mode 100644 index 0000000..e870ca5 --- /dev/null +++ b/sirius-api/handlers/statistics_handler.go @@ -0,0 +1,84 @@ +package handlers + +import ( + "log/slog" + + "github.com/SiriusScan/go-api/sirius/host" + "github.com/gofiber/fiber/v2" +) + +// GetMostVulnerableHosts handles GET /api/v1/statistics/hosts/most-vulnerable +// Query Parameters: +// - limit: Maximum number of hosts to return (default: 10, max: 50) +// - refresh: Force cache invalidation and recalculation (default: false) +// +// Returns: VulnerableHostsResponse with ranked host statistics +func GetMostVulnerableHosts(c *fiber.Ctx) error { + // Parse query parameters + limit := c.QueryInt("limit", 10) + + // Enforce limits for performance and reasonable response sizes + if limit > 50 { + limit = 50 // Max cap to prevent excessive query time + } + if limit < 1 { + limit = 10 // Default to 10 if invalid + } + + // Check if force refresh requested + forceRefresh := c.Query("refresh", "false") == "true" + + if forceRefresh { + // Invalidate cache first to force recalculation + _ = host.InvalidateMostVulnerableHostsCache() + } + + // Get data (cached or fresh) + response, err := host.GetMostVulnerableHostsCached(limit) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to retrieve vulnerable hosts statistics", + "details": err.Error(), + }) + } + + // Debug: Log response details + if len(response.Hosts) == 0 { + slog.Warn("GetMostVulnerableHosts returned 0 hosts", "limit", limit, "cached", response.Cached) + // If we got cached empty results, invalidate and try again + if response.Cached { + slog.Debug("GetMostVulnerableHosts: invalidating cache and retrying") + _ = host.InvalidateMostVulnerableHostsCache() + response, err = host.GetMostVulnerableHostsCached(limit) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to retrieve vulnerable hosts statistics after cache invalidation", + "details": err.Error(), + }) + } + } + } else { + slog.Debug("GetMostVulnerableHosts returning", "host_count", len(response.Hosts), "cached", response.Cached) + } + + return c.JSON(response) +} + +// InvalidateVulnerableHostsCache handles POST /api/v1/statistics/hosts/most-vulnerable/invalidate +// This endpoint allows manual cache invalidation for immediate refresh +// +// Returns: Success confirmation +func InvalidateVulnerableHostsCache(c *fiber.Ctx) error { + err := host.InvalidateMostVulnerableHostsCache() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to invalidate cache", + "details": err.Error(), + }) + } + + return c.JSON(fiber.Map{ + "success": true, + "message": "Cache invalidated successfully", + }) +} diff --git a/sirius-api/handlers/template_defaults.go b/sirius-api/handlers/template_defaults.go new file mode 100644 index 0000000..d3db683 --- /dev/null +++ b/sirius-api/handlers/template_defaults.go @@ -0,0 +1,104 @@ +package handlers + +import ( + "time" +) + +// mergeMissingCoreScanProfiles appends built-in Network+Agent and Agent-only profiles when +// ValKey has not been seeded with them (common in production / fresh installs). Stored +// templates with the same ID always win — this only fills gaps. +func mergeMissingCoreScanProfiles(templates []Template, now time.Time) []Template { + seen := make(map[string]struct{}, len(templates)) + for _, t := range templates { + seen[t.ID] = struct{}{} + } + + base := pickBaselineTemplate(templates) + out := append(make([]Template, 0, len(templates)+2), templates...) + + for _, def := range coreAgentScanProfiles(now, base) { + if _, ok := seen[def.ID]; ok { + continue + } + out = append(out, def) + seen[def.ID] = struct{}{} + } + + return out +} + +func pickBaselineTemplate(templates []Template) Template { + for _, id := range []string{"quick", "high-risk", "all"} { + for _, t := range templates { + if t.ID == id { + return t + } + } + } + if len(templates) > 0 { + return templates[0] + } + return Template{} +} + +// coreAgentScanProfiles returns full-scan (network + agent) and agent-only presets. +func coreAgentScanProfiles(now time.Time, base Template) []Template { + scripts := base.EnabledScripts + if len(scripts) == 0 { + scripts = []string{"default"} + } + scanTypes := base.ScanOptions.ScanTypes + if len(scanTypes) == 0 { + scanTypes = []string{"discovery", "vulnerability"} + } + + portRange := base.ScanOptions.PortRange + if portRange == "" { + portRange = "1-65535" + } + + agentCfg := func(mode string) *AgentScanConfig { + return &AgentScanConfig{ + Enabled: true, + Mode: mode, + AgentIDs: []string{}, + Timeout: 300, + Concurrency: 5, + TemplateFilter: nil, + } + } + + optsFull := base.ScanOptions + optsFull.ScanTypes = scanTypes + optsFull.PortRange = portRange + optsFull.AgentScan = agentCfg("comprehensive") + + full := Template{ + ID: "full-scan", + Name: "Full Scan (Network + Agent)", + Description: "Network scripts plus coordinated agent template scanning on discovered hosts.", + Type: "system", + EnabledScripts: append([]string(nil), scripts...), + ScanOptions: optsFull, + CreatedAt: now, + UpdatedAt: now, + } + + optsAgent := base.ScanOptions + optsAgent.ScanTypes = []string{} + optsAgent.PortRange = portRange + optsAgent.AgentScan = agentCfg("comprehensive") + + agentOnly := Template{ + ID: "agent-only", + Name: "Agent Scan (Templates)", + Description: "Template-based scanning via connected Sirius Agents (no network sweep).", + Type: "system", + EnabledScripts: append([]string(nil), scripts...), + ScanOptions: optsAgent, + CreatedAt: now, + UpdatedAt: now, + } + + return []Template{full, agentOnly} +} diff --git a/sirius-api/handlers/template_handler.go b/sirius-api/handlers/template_handler.go new file mode 100644 index 0000000..104011a --- /dev/null +++ b/sirius-api/handlers/template_handler.go @@ -0,0 +1,509 @@ +package handlers + +import ( + "context" + "encoding/json" + "fmt" + "log/slog" + "regexp" + "strings" + "time" + + "github.com/SiriusScan/go-api/sirius/store" + "github.com/gofiber/fiber/v2" +) + +var templateIDPattern = regexp.MustCompile("^[A-Za-z0-9._:-]{1,128}$") + +// Template represents a scan configuration template +type Template struct { + ID string `json:"id"` + Name string `json:"name"` + Description string `json:"description"` + Type string `json:"type"` // "system" or "custom" + EnabledScripts []string `json:"enabled_scripts"` + ScanOptions TemplateOptions `json:"scan_options"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` +} + +// AgentScanConfig matches sirius-ui scan_options.agent_scan (template scans via connected agents). +type AgentScanConfig struct { + Enabled bool `json:"enabled"` + Mode string `json:"mode"` // comprehensive | templates-only | scripts-only + AgentIDs []string `json:"agent_ids"` + Timeout int `json:"timeout"` + Concurrency int `json:"concurrency"` + TemplateFilter []string `json:"template_filter,omitempty"` +} + +// TemplateOptions defines the scan configuration for a template +type TemplateOptions struct { + ScanTypes []string `json:"scan_types"` + PortRange string `json:"port_range"` + Aggressive bool `json:"aggressive"` + MaxRetries int `json:"max_retries"` + Parallel bool `json:"parallel"` + ExcludePorts []string `json:"exclude_ports,omitempty"` + AgentScan *AgentScanConfig `json:"agent_scan,omitempty"` +} + +// TemplateList represents a list of template IDs +type TemplateList struct { + Templates []string `json:"templates"` +} + +const ( + templateKeyPrefix = "scan:template:" + templateListKey = "scan:template:list" + systemTemplatesListKey = "scan:system-templates" + allScriptsMarker = "*" +) + +func canonicalizeEnabledScriptRef(value string) string { + trimmed := strings.TrimSpace(value) + if trimmed == "" { + return "" + } + if trimmed == allScriptsMarker { + return allScriptsMarker + } + + segments := strings.Split(trimmed, "/") + lastSegment := trimmed + for i := len(segments) - 1; i >= 0; i-- { + if segments[i] != "" { + lastSegment = segments[i] + break + } + } + + if strings.HasSuffix(strings.ToLower(lastSegment), ".nse") { + return lastSegment[:len(lastSegment)-4] + } + + return lastSegment +} + +func normalizeTemplateEnabledScripts(values []string) []string { + if len(values) == 0 { + return nil + } + + normalized := make([]string, 0, len(values)) + seen := make(map[string]struct{}, len(values)) + for _, value := range values { + canonical := canonicalizeEnabledScriptRef(value) + if canonical == "" { + continue + } + if canonical == allScriptsMarker { + return []string{allScriptsMarker} + } + if _, exists := seen[canonical]; exists { + continue + } + seen[canonical] = struct{}{} + normalized = append(normalized, canonical) + } + + return normalized +} + +func normalizeTemplate(template *Template) { + template.EnabledScripts = normalizeTemplateEnabledScripts(template.EnabledScripts) +} + +// GetTemplates returns all templates +func GetTemplates(c *fiber.Ctx) error { + ctx := context.Background() + + // Get ValKey store + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to store", + }) + } + defer kvStore.Close() + + // Get template list + resp, err := kvStore.GetValue(ctx, templateListKey) + if err != nil { + if strings.Contains(err.Error(), "not found") { + slog.Warn("Template list is missing in store", "key", templateListKey) + c.Set("X-Sirius-Template-State", "missing") + now := time.Now() + return c.JSON(mergeMissingCoreScanProfiles(nil, now)) + } + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to get template list", + }) + } + + var templateList TemplateList + if err := json.Unmarshal([]byte(resp.Message.Value), &templateList); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to parse template list", + }) + } + + // Retrieve each template + templates := make([]Template, 0, len(templateList.Templates)) + for _, id := range templateList.Templates { + template, err := getTemplateByID(ctx, kvStore, id) + if err != nil { + slog.Warn("Failed to get template", "template_id", id, "error", err) + continue + } + templates = append(templates, *template) + } + + if len(templates) == 0 { + slog.Warn("Template list resolved to empty set", "template_ids", len(templateList.Templates)) + c.Set("X-Sirius-Template-State", "empty") + } + + templates = mergeMissingCoreScanProfiles(templates, time.Now()) + + return c.JSON(templates) +} + +// GetTemplate returns a single template by ID +func GetTemplate(c *fiber.Ctx) error { + ctx := context.Background() + templateID := c.Params("id") + if !templateIDPattern.MatchString(templateID) { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "invalid template id format", + }) + } + + // Get ValKey store + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to store", + }) + } + defer kvStore.Close() + + template, err := getTemplateByID(ctx, kvStore, templateID) + if err != nil { + if strings.Contains(err.Error(), "not found") { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": fmt.Sprintf("Template '%s' not found", templateID), + }) + } + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to get template", + }) + } + + return c.JSON(template) +} + +// CreateTemplate creates a new custom template +func CreateTemplate(c *fiber.Ctx) error { + ctx := context.Background() + + var template Template + if err := c.BodyParser(&template); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Invalid request body", + }) + } + normalizeTemplate(&template) + + // Validate template + if err := validateTemplate(&template); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": err.Error(), + }) + } + + // Force type to custom for user-created templates + template.Type = "custom" + + // Set timestamps + now := time.Now() + template.CreatedAt = now + template.UpdatedAt = now + + // Get ValKey store + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to store", + }) + } + defer kvStore.Close() + + // Check if template already exists + existingTemplate, err := getTemplateByID(ctx, kvStore, template.ID) + if err == nil && existingTemplate != nil { + return c.Status(fiber.StatusConflict).JSON(fiber.Map{ + "error": fmt.Sprintf("Template '%s' already exists", template.ID), + }) + } + + // Store template + if err := storeTemplate(ctx, kvStore, &template); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to create template", + }) + } + + // Add to template list + if err := addToTemplateList(ctx, kvStore, template.ID); err != nil { + slog.Warn("Failed to add template to list", "error", err) + } + + slog.Info("Created template", "name", template.Name, "template_id", template.ID) + + return c.Status(fiber.StatusCreated).JSON(template) +} + +// UpdateTemplate updates an existing template +func UpdateTemplate(c *fiber.Ctx) error { + ctx := context.Background() + templateID := c.Params("id") + if !templateIDPattern.MatchString(templateID) { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "invalid template id format", + }) + } + + var template Template + if err := c.BodyParser(&template); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Invalid request body", + }) + } + + // Ensure ID matches + template.ID = templateID + normalizeTemplate(&template) + + // Validate template + if err := validateTemplate(&template); err != nil { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": err.Error(), + }) + } + + // Get ValKey store + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to store", + }) + } + defer kvStore.Close() + + // Check if template exists + existing, err := getTemplateByID(ctx, kvStore, templateID) + if err != nil { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": fmt.Sprintf("Template '%s' not found", templateID), + }) + } + + // Cannot modify system templates + if existing.Type == "system" { + return c.Status(fiber.StatusForbidden).JSON(fiber.Map{ + "error": "Cannot modify system template", + }) + } + + // Preserve creation time, update modification time + template.CreatedAt = existing.CreatedAt + template.UpdatedAt = time.Now() + template.Type = "custom" // Ensure it stays custom + + // Store updated template + if err := storeTemplate(ctx, kvStore, &template); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to update template", + }) + } + + slog.Info("Updated template", "name", template.Name, "template_id", template.ID) + + return c.JSON(template) +} + +// DeleteTemplate deletes a template +func DeleteTemplate(c *fiber.Ctx) error { + ctx := context.Background() + templateID := c.Params("id") + if !templateIDPattern.MatchString(templateID) { + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "invalid template id format", + }) + } + + // Get ValKey store + kvStore, err := store.NewValkeyStore() + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to connect to store", + }) + } + defer kvStore.Close() + + // Check if template exists + template, err := getTemplateByID(ctx, kvStore, templateID) + if err != nil { + return c.Status(fiber.StatusNotFound).JSON(fiber.Map{ + "error": fmt.Sprintf("Template '%s' not found", templateID), + }) + } + + // Cannot delete system templates + if template.Type == "system" { + return c.Status(fiber.StatusForbidden).JSON(fiber.Map{ + "error": "Cannot delete system template", + }) + } + + // Delete template + key := templateKeyPrefix + templateID + if err := kvStore.DeleteValue(ctx, key); err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": "Failed to delete template", + }) + } + + // Remove from template list + if err := removeFromTemplateList(ctx, kvStore, templateID); err != nil { + slog.Warn("Failed to remove template from list", "error", err) + } + + slog.Info("Deleted template", "name", template.Name, "template_id", templateID) + + return c.SendStatus(fiber.StatusNoContent) +} + +// Helper functions + +func getTemplateByID(ctx context.Context, kvStore store.KVStore, id string) (*Template, error) { + key := templateKeyPrefix + id + resp, err := kvStore.GetValue(ctx, key) + if err != nil { + return nil, err + } + + var template Template + if err := json.Unmarshal([]byte(resp.Message.Value), &template); err != nil { + return nil, fmt.Errorf("failed to unmarshal template: %w", err) + } + normalizeTemplate(&template) + + return &template, nil +} + +func storeTemplate(ctx context.Context, kvStore store.KVStore, template *Template) error { + normalizeTemplate(template) + templateJSON, err := json.Marshal(template) + if err != nil { + return fmt.Errorf("failed to marshal template: %w", err) + } + + key := templateKeyPrefix + template.ID + if err := kvStore.SetValue(ctx, key, string(templateJSON)); err != nil { + return fmt.Errorf("failed to store template: %w", err) + } + + return nil +} + +func validateTemplate(template *Template) error { + if template.ID == "" { + return fmt.Errorf("template ID is required") + } + if !templateIDPattern.MatchString(template.ID) { + return fmt.Errorf("template ID format is invalid") + } + if template.Name == "" { + return fmt.Errorf("template name is required") + } + if len(template.EnabledScripts) == 0 { + return fmt.Errorf("template must have at least one enabled script") + } + if len(template.ScanOptions.ScanTypes) == 0 { + return fmt.Errorf("template must have at least one scan type") + } + return nil +} + +func addToTemplateList(ctx context.Context, kvStore store.KVStore, id string) error { + var templateList TemplateList + resp, err := kvStore.GetValue(ctx, templateListKey) + if err != nil { + if !strings.Contains(err.Error(), "not found") { + return fmt.Errorf("failed to get template list: %w", err) + } + // List doesn't exist yet, create new + templateList = TemplateList{Templates: []string{}} + } else { + if err := json.Unmarshal([]byte(resp.Message.Value), &templateList); err != nil { + return fmt.Errorf("failed to unmarshal template list: %w", err) + } + } + + // Check if already in list + for _, tid := range templateList.Templates { + if tid == id { + return nil // Already in list + } + } + + // Add to list + templateList.Templates = append(templateList.Templates, id) + + // Save updated list + listJSON, err := json.Marshal(templateList) + if err != nil { + return fmt.Errorf("failed to marshal template list: %w", err) + } + + if err := kvStore.SetValue(ctx, templateListKey, string(listJSON)); err != nil { + return fmt.Errorf("failed to update template list: %w", err) + } + + return nil +} + +func removeFromTemplateList(ctx context.Context, kvStore store.KVStore, id string) error { + resp, err := kvStore.GetValue(ctx, templateListKey) + if err != nil { + return fmt.Errorf("failed to get template list: %w", err) + } + + var templateList TemplateList + if err := json.Unmarshal([]byte(resp.Message.Value), &templateList); err != nil { + return fmt.Errorf("failed to unmarshal template list: %w", err) + } + + // Remove from list + newList := make([]string, 0, len(templateList.Templates)) + for _, tid := range templateList.Templates { + if tid != id { + newList = append(newList, tid) + } + } + templateList.Templates = newList + + // Save updated list + listJSON, err := json.Marshal(templateList) + if err != nil { + return fmt.Errorf("failed to marshal template list: %w", err) + } + + if err := kvStore.SetValue(ctx, templateListKey, string(listJSON)); err != nil { + return fmt.Errorf("failed to update template list: %w", err) + } + + return nil +} diff --git a/sirius-api/handlers/template_handler_test.go b/sirius-api/handlers/template_handler_test.go new file mode 100644 index 0000000..6225ba5 --- /dev/null +++ b/sirius-api/handlers/template_handler_test.go @@ -0,0 +1,63 @@ +package handlers + +import ( + "reflect" + "testing" +) + +func TestNormalizeTemplateEnabledScripts(t *testing.T) { + t.Parallel() + + tests := []struct { + name string + input []string + expected []string + }{ + { + name: "canonicalizes path-based script refs", + input: []string{"scripts/http-title.nse", " vulners ", "custom/smb-vuln-ms17-010.nse"}, + expected: []string{"http-title", "vulners", "smb-vuln-ms17-010"}, + }, + { + name: "deduplicates canonical collisions", + input: []string{"scripts/http-title.nse", "http-title", "scripts/http-title.nse"}, + expected: []string{"http-title"}, + }, + { + name: "wildcard wins over explicit refs", + input: []string{"scripts/http-title.nse", "*", "vulners"}, + expected: []string{"*"}, + }, + { + name: "drops empty values", + input: []string{"", " ", "scripts/banner.nse"}, + expected: []string{"banner"}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + t.Parallel() + + got := normalizeTemplateEnabledScripts(tt.input) + if !reflect.DeepEqual(got, tt.expected) { + t.Fatalf("normalizeTemplateEnabledScripts(%v) = %v, want %v", tt.input, got, tt.expected) + } + }) + } +} + +func TestNormalizeTemplateMutatesEnabledScripts(t *testing.T) { + t.Parallel() + + template := &Template{ + EnabledScripts: []string{"scripts/http-title.nse", "http-title", "vulners"}, + } + + normalizeTemplate(template) + + expected := []string{"http-title", "vulners"} + if !reflect.DeepEqual(template.EnabledScripts, expected) { + t.Fatalf("normalizeTemplate() enabled scripts = %v, want %v", template.EnabledScripts, expected) + } +} diff --git a/sirius-api/handlers/test_handler.go b/sirius-api/handlers/test_handler.go new file mode 100755 index 0000000..3daa848 --- /dev/null +++ b/sirius-api/handlers/test_handler.go @@ -0,0 +1,16 @@ +package handlers + +import ( + "fmt" + + "github.com/gofiber/fiber/v2" +) + +// GetHost handles the GET /host/{id} route +func TestHandler(c *fiber.Ctx) error { + + fmt.Println("test") + + // Return the host data as JSON + return c.JSON("hostData") +} diff --git a/sirius-api/handlers/vulnerability_handler.go b/sirius-api/handlers/vulnerability_handler.go new file mode 100755 index 0000000..011e2e2 --- /dev/null +++ b/sirius-api/handlers/vulnerability_handler.go @@ -0,0 +1,93 @@ +package handlers + +import ( + "encoding/json" + "log/slog" + + "github.com/SiriusScan/go-api/sirius" + "github.com/SiriusScan/go-api/sirius/vulnerability" + "github.com/gofiber/fiber/v2" +) + +//* The API exposes functions from the go-api/sirius/vulnerability package to JSON endpoints +//* GetVulnerability handles the GET /vulnerability/{id} route +// It retrieves a CVEItem from the database and returns it as JSON + +func GetVulnerability(c *fiber.Ctx) error { + vid := c.Params("id") + // slog.Debug("Getting vulnerability", "vid", vid) + + // Retrieve svdb data with the GetVulnerability function from the sirius.vulnerability package + vulnData, err := vulnerability.GetVulnerability(vid) + + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": err.Error(), + }) + } + + // Return the vulnerability data as JSON + return c.JSON(vulnData) +} + +func AddVulnerability(c *fiber.Ctx) error { + // Read the raw request body + requestBody := string(c.Body()) + + // Define a local struct that matches the expected JSON structure + var newVuln sirius.Vulnerability + + // Manually unmarshal JSON into the struct + err := json.Unmarshal([]byte(requestBody), &newVuln) + if err != nil { + slog.Error("Error parsing request body", "error", err) + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Error parsing request body: " + err.Error(), + }) + } + + slog.Info("Adding vulnerability", "vid", newVuln.VID) + + // Add the vulnerability to the database + err = vulnerability.AddVulnerability(newVuln) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": err.Error(), + }) + } + + // Return the vulnerability data as JSON + return c.JSON(newVuln) +} + +func DeleteVulnerability(c *fiber.Ctx) error { + // Read the raw request body + requestBody := string(c.Body()) + + // Define a local struct that matches the expected JSON structure + type Req struct { + VID string `json:"vid"` + } + var newVuln Req + + // Manually unmarshal JSON into the struct + err := json.Unmarshal([]byte(requestBody), &newVuln) + if err != nil { + slog.Error("Error parsing request body", "error", err) + return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{ + "error": "Error parsing request body: " + err.Error(), + }) + } + + // Delete the vulnerability from the database + err = vulnerability.DeleteVulnerability(newVuln.VID) + if err != nil { + return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ + "error": err.Error(), + }) + } + + return c.JSON(fiber.Map{ + "message": "Vulnerability deleted successfully", + }) +} diff --git a/sirius-api/integration_tests/snapshot_test.go b/sirius-api/integration_tests/snapshot_test.go new file mode 100644 index 0000000..e01c55f --- /dev/null +++ b/sirius-api/integration_tests/snapshot_test.go @@ -0,0 +1,296 @@ +package integration_tests + +import ( + "context" + "encoding/json" + "fmt" + "net/http" + "net/http/httptest" + "testing" + "time" + + "github.com/SiriusScan/go-api/sirius/snapshot" + "github.com/SiriusScan/go-api/sirius/store" + "github.com/SiriusScan/sirius-api/handlers" + "github.com/gofiber/fiber/v2" +) + +// NOTE: These integration tests require: +// 1. Running PostgreSQL database (sirius-postgres container) +// 2. Running Valkey instance (sirius-valkey container) +// 3. Test data in the database (hosts and vulnerabilities) +// +// To run these tests: +// 1. Start the docker-compose environment +// 2. Ensure test data exists in the database +// 3. Run: go test -v ./integration_tests -tags=integration + +func TestSnapshotAPICreate(t *testing.T) { + if testing.Short() { + t.Skip("Skipping integration test in short mode") + } + + t.Log("\n🔍 Testing snapshot creation via API...") + + app := fiber.New() + app.Post("/api/v1/statistics/vulnerability-snapshot", handlers.CreateSnapshot) + + req := httptest.NewRequest("POST", "/api/v1/statistics/vulnerability-snapshot", nil) + req.Header.Set("Content-Type", "application/json") + + resp, err := app.Test(req) + if err != nil { + t.Fatalf("❌ Failed to make request: %v", err) + } + + if resp.StatusCode != http.StatusCreated { + t.Errorf("❌ Expected status 201, got %d", resp.StatusCode) + } + + var result map[string]interface{} + if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { + t.Fatalf("❌ Failed to decode response: %v", err) + } + + if result["message"] != "Snapshot created successfully" { + t.Errorf("❌ Unexpected message: %v", result["message"]) + } + + t.Log("\n✅ Snapshot creation API test passed") +} + +func TestSnapshotAPIList(t *testing.T) { + if testing.Short() { + t.Skip("Skipping integration test in short mode") + } + + t.Log("\n🔍 Testing snapshot listing via API...") + + app := fiber.New() + app.Get("/api/v1/statistics/vulnerability-snapshots", handlers.ListSnapshots) + + req := httptest.NewRequest("GET", "/api/v1/statistics/vulnerability-snapshots", nil) + + resp, err := app.Test(req) + if err != nil { + t.Fatalf("❌ Failed to make request: %v", err) + } + + if resp.StatusCode != http.StatusOK { + t.Errorf("❌ Expected status 200, got %d", resp.StatusCode) + } + + var result map[string]interface{} + if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { + t.Fatalf("❌ Failed to decode response: %v", err) + } + + if _, ok := result["available_dates"]; !ok { + t.Errorf("❌ Response missing 'available_dates' field") + } + + t.Log("\n✅ Snapshot listing API test passed") +} + +func TestSnapshotAPIGetTrends(t *testing.T) { + if testing.Short() { + t.Skip("Skipping integration test in short mode") + } + + t.Log("\n🔍 Testing vulnerability trends API...") + + app := fiber.New() + app.Get("/api/v1/statistics/vulnerability-trends", handlers.GetVulnerabilityTrends) + + req := httptest.NewRequest("GET", "/api/v1/statistics/vulnerability-trends?days=7", nil) + + resp, err := app.Test(req) + if err != nil { + t.Fatalf("❌ Failed to make request: %v", err) + } + + if resp.StatusCode != http.StatusOK { + t.Errorf("❌ Expected status 200, got %d", resp.StatusCode) + } + + var result map[string]interface{} + if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { + t.Fatalf("❌ Failed to decode response: %v", err) + } + + if _, ok := result["snapshots"]; !ok { + t.Errorf("❌ Response missing 'snapshots' field") + } + + if daysRequested, ok := result["days_requested"].(float64); !ok || daysRequested != 7 { + t.Errorf("❌ Unexpected days_requested: %v", result["days_requested"]) + } + + t.Log("\n✅ Vulnerability trends API test passed") +} + +func TestSnapshotAPIGetSpecific(t *testing.T) { + if testing.Short() { + t.Skip("Skipping integration test in short mode") + } + + t.Log("\n🔍 Testing get specific snapshot API...") + + // First create a snapshot + date := time.Now().UTC().Format("2006-01-02") + kvStore, err := store.NewValkeyStore() + if err != nil { + t.Skipf("Skipping test: Valkey not available: %v", err) + } + defer kvStore.Close() + + manager := snapshot.NewSnapshotManager(kvStore) + ctx := context.Background() + + _, err = manager.CreateSnapshot(ctx, date) + if err != nil { + t.Skipf("Skipping test: Failed to create test snapshot: %v", err) + } + + // Now test the API endpoint + app := fiber.New() + app.Get("/api/v1/statistics/vulnerability-snapshot/:date", handlers.GetSnapshot) + + req := httptest.NewRequest("GET", fmt.Sprintf("/api/v1/statistics/vulnerability-snapshot/%s", date), nil) + + resp, err := app.Test(req) + if err != nil { + t.Fatalf("❌ Failed to make request: %v", err) + } + + if resp.StatusCode != http.StatusOK { + t.Errorf("❌ Expected status 200, got %d", resp.StatusCode) + } + + var snapshot store.VulnerabilitySnapshot + if err := json.NewDecoder(resp.Body).Decode(&snapshot); err != nil { + t.Fatalf("❌ Failed to decode response: %v", err) + } + + if snapshot.SnapshotID != date { + t.Errorf("❌ SnapshotID mismatch: expected %s, got %s", date, snapshot.SnapshotID) + } + + t.Log("\n✅ Get specific snapshot API test passed") +} + +func TestSnapshotAPIBadDate(t *testing.T) { + if testing.Short() { + t.Skip("Skipping integration test in short mode") + } + + t.Log("\n🔍 Testing API with invalid date format...") + + app := fiber.New() + app.Get("/api/v1/statistics/vulnerability-snapshot/:date", handlers.GetSnapshot) + + req := httptest.NewRequest("GET", "/api/v1/statistics/vulnerability-snapshot/invalid-date", nil) + + resp, err := app.Test(req) + if err != nil { + t.Fatalf("❌ Failed to make request: %v", err) + } + + if resp.StatusCode != http.StatusBadRequest { + t.Errorf("❌ Expected status 400 for invalid date, got %d", resp.StatusCode) + } + + t.Log("\n✅ Bad date format API test passed") +} + +func TestSnapshotValkeyPersistence(t *testing.T) { + if testing.Short() { + t.Skip("Skipping integration test in short mode") + } + + t.Log("\n🔍 Testing Valkey persistence...") + + kvStore, err := store.NewValkeyStore() + if err != nil { + t.Skipf("Skipping test: Valkey not available: %v", err) + } + defer kvStore.Close() + + manager := snapshot.NewSnapshotManager(kvStore) + ctx := context.Background() + + date := time.Now().UTC().Format("2006-01-02") + + // Create snapshot + snapshot, err := manager.CreateSnapshot(ctx, date) + if err != nil { + t.Fatalf("❌ Failed to create snapshot: %v", err) + } + + // Verify it was stored + key := fmt.Sprintf("vuln:snapshot:%s", date) + resp, err := kvStore.GetValue(ctx, key) + if err != nil { + t.Fatalf("❌ Failed to retrieve snapshot from Valkey: %v", err) + } + + var retrieved store.VulnerabilitySnapshot + if err := json.Unmarshal([]byte(resp.Message.Value), &retrieved); err != nil { + t.Fatalf("❌ Failed to unmarshal snapshot from Valkey: %v", err) + } + + if retrieved.SnapshotID != snapshot.SnapshotID { + t.Errorf("❌ SnapshotID mismatch: expected %s, got %s", snapshot.SnapshotID, retrieved.SnapshotID) + } + + t.Log("\n✅ Valkey persistence test passed") +} + +func TestSnapshotCleanup(t *testing.T) { + if testing.Short() { + t.Skip("Skipping integration test in short mode") + } + + t.Log("\n🔍 Testing snapshot cleanup (10 snapshot limit)...") + + kvStore, err := store.NewValkeyStore() + if err != nil { + t.Skipf("Skipping test: Valkey not available: %v", err) + } + defer kvStore.Close() + + manager := snapshot.NewSnapshotManager(kvStore) + ctx := context.Background() + + // Create 12 snapshots (more than the 10 limit) + baseDate := time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC) + for i := 0; i < 12; i++ { + date := baseDate.AddDate(0, 0, i).Format("2006-01-02") + testSnapshot := &store.VulnerabilitySnapshot{ + SnapshotID: date, + Timestamp: time.Now().UTC(), + Counts: store.VulnerabilityCounts{Total: 10}, + } + key := fmt.Sprintf("vuln:snapshot:%s", date) + data, _ := json.Marshal(testSnapshot) + kvStore.SetValue(ctx, key, string(data)) + } + + // Run cleanup + if err := manager.CleanupOldSnapshots(ctx); err != nil { + t.Fatalf("❌ Cleanup failed: %v", err) + } + + // Verify only 10 snapshots remain + dates, err := manager.ListSnapshots(ctx) + if err != nil { + t.Fatalf("❌ Failed to list snapshots: %v", err) + } + + if len(dates) != 10 { + t.Errorf("❌ Expected 10 snapshots after cleanup, got %d", len(dates)) + } + + t.Log("\n✅ Snapshot cleanup test passed") +} + diff --git a/sirius-api/internal/infraauth/sirius_api_key.go b/sirius-api/internal/infraauth/sirius_api_key.go new file mode 100644 index 0000000..e7214d8 --- /dev/null +++ b/sirius-api/internal/infraauth/sirius_api_key.go @@ -0,0 +1,28 @@ +package infraauth + +import ( + "fmt" + "os" + "strings" +) + +// LoadSiriusAPIKey returns the internal Sirius API key for service-to-service +// HTTP calls from the mounted secret file. Sirius uses a hard file-backed +// contract at runtime: SIRIUS_API_KEY_FILE must point at a readable secret. +func LoadSiriusAPIKey() (string, error) { + p := strings.TrimSpace(os.Getenv("SIRIUS_API_KEY_FILE")) + if p == "" { + return "", fmt.Errorf("set SIRIUS_API_KEY_FILE to a readable internal API key secret") + } + + b, err := os.ReadFile(p) + if err != nil { + return "", fmt.Errorf("read SIRIUS_API_KEY_FILE %q: %w", p, err) + } + + k := strings.TrimSpace(string(b)) + if k == "" { + return "", fmt.Errorf("SIRIUS_API_KEY_FILE %q is empty", p) + } + return k, nil +} diff --git a/sirius-api/internal/infraauth/sirius_api_key_test.go b/sirius-api/internal/infraauth/sirius_api_key_test.go new file mode 100644 index 0000000..3f838a8 --- /dev/null +++ b/sirius-api/internal/infraauth/sirius_api_key_test.go @@ -0,0 +1,75 @@ +package infraauth + +import ( + "os" + "path/filepath" + "testing" +) + +func TestLoadSiriusAPIKey_FilePreferred(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "key.txt") + if err := os.WriteFile(p, []byte(" file-key-123 \n"), 0o600); err != nil { + t.Fatal(err) + } + t.Setenv("SIRIUS_API_KEY_FILE", p) + + got, err := LoadSiriusAPIKey() + if err != nil { + t.Fatal(err) + } + if got != "file-key-123" { + t.Fatalf("got %q want file key", got) + } +} + +func TestLoadSiriusAPIKey_EmptyPathFails(t *testing.T) { + t.Setenv("SIRIUS_API_KEY_FILE", "") + + _, err := LoadSiriusAPIKey() + if err == nil { + t.Fatal("expected error") + } +} + +func TestLoadSiriusAPIKey_MissingFileFails(t *testing.T) { + t.Setenv("SIRIUS_API_KEY_FILE", filepath.Join(t.TempDir(), "nonexistent-secret")) + + _, err := LoadSiriusAPIKey() + if err == nil { + t.Fatal("expected error") + } +} + +func TestLoadSiriusAPIKey_UnreadableFileFails(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "key.txt") + if err := os.WriteFile(p, []byte("secret-in-file"), 0o600); err != nil { + t.Fatal(err) + } + if err := os.Chmod(p, 0o000); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = os.Chmod(p, 0o600) }) + + t.Setenv("SIRIUS_API_KEY_FILE", p) + + _, err := LoadSiriusAPIKey() + if err == nil { + t.Fatal("expected error when file unreadable") + } +} + +func TestLoadSiriusAPIKey_EmptyFileFails(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "key.txt") + if err := os.WriteFile(p, []byte("\n"), 0o600); err != nil { + t.Fatal(err) + } + t.Setenv("SIRIUS_API_KEY_FILE", p) + + _, err := LoadSiriusAPIKey() + if err == nil { + t.Fatal("expected error when file empty") + } +} diff --git a/sirius-api/main.go b/sirius-api/main.go new file mode 100755 index 0000000..619b47e --- /dev/null +++ b/sirius-api/main.go @@ -0,0 +1,266 @@ +package main + +import ( + "fmt" + "log/slog" + "net" + "os" + "os/exec" + "path/filepath" + "strings" + "time" + + "github.com/SiriusScan/go-api/sirius/logging" + "github.com/SiriusScan/go-api/sirius/slogger" + "github.com/SiriusScan/go-api/sirius/store" + "github.com/SiriusScan/sirius-api/internal/infraauth" + "github.com/SiriusScan/sirius-api/middleware" + "github.com/SiriusScan/sirius-api/routes" + "github.com/gofiber/fiber/v2" + "github.com/gofiber/fiber/v2/middleware/cors" + "github.com/gofiber/fiber/v2/middleware/requestid" +) + +// waitForDatabase waits for PostgreSQL to be available before running migrations +func waitForDatabase() error { + dbHost := os.Getenv("POSTGRES_HOST") + dbPort := os.Getenv("POSTGRES_PORT") + if dbHost == "" { + dbHost = "sirius-postgres" + } + if dbPort == "" { + dbPort = "5432" + } + + address := net.JoinHostPort(dbHost, dbPort) + slog.Info("Waiting for database", "address", address) + + for attempts := 0; attempts < 30; attempts++ { + conn, err := net.DialTimeout("tcp", address, 3*time.Second) + if err == nil { + conn.Close() + slog.Info("Database is available", "address", address) + return nil + } + slog.Debug("Database not ready, retrying", "attempt", attempts+1, "max", 30) + time.Sleep(2 * time.Second) + } + + return fmt.Errorf("database not available after 30 attempts") +} + +// runMigrations executes database migrations before starting the API +func runMigrations() error { + slog.Info("Running database migrations") + + // Wait for database to be available + if err := waitForDatabase(); err != nil { + return fmt.Errorf("database connectivity check failed: %w", err) + } + + // Check if we're in development mode with volume mount + var goApiPath string + if _, err := os.Stat("/go-api"); err == nil { + goApiPath = "/go-api" + } else if _, err := os.Stat("../go-api"); err == nil { + goApiPath = "../go-api" + } else { + slog.Warn("go-api not found, skipping migrations") + return nil + } + + migrationsPath := filepath.Join(goApiPath, "migrations") + + // Run migration 002_source_attribution (creates scan_history_entries table) + migration002Path := filepath.Join(migrationsPath, "002_source_attribution", "main.go") + if _, err := os.Stat(migration002Path); err == nil { + slog.Info("Running migration", "name", "002_source_attribution") + cmd := exec.Command("go", "run", migration002Path) + cmd.Dir = goApiPath + cmd.Stdout = os.Stdout + cmd.Stderr = os.Stderr + + if err := cmd.Run(); err != nil { + slog.Warn("Migration failed (may already be applied)", "name", "002_source_attribution", "error", err) + } else { + slog.Info("Migration completed", "name", "002_source_attribution") + } + } + + // Run migration 004_add_sbom_schema if it exists + migration004Path := filepath.Join(migrationsPath, "004_add_sbom_schema", "main.go") + if _, err := os.Stat(migration004Path); err == nil { + slog.Info("Running migration", "name", "004_add_sbom_schema") + cmd := exec.Command("go", "run", migration004Path) + cmd.Dir = goApiPath + cmd.Stdout = os.Stdout + cmd.Stderr = os.Stderr + + if err := cmd.Run(); err != nil { + slog.Warn("Migration failed (may already be applied)", "name", "004_add_sbom_schema", "error", err) + } else { + slog.Info("Migration completed", "name", "004_add_sbom_schema") + } + } + + slog.Info("Database migrations completed") + return nil +} + + +func main() { + // Initialize structured logging (reads LOG_LEVEL env var) + slogger.Init() + + // Root service key is validated statelessly in middleware (file or env). + // Valkey remains authoritative only for user-generated API keys. + serviceAPIKey, err := infraauth.LoadSiriusAPIKey() + if err != nil || strings.TrimSpace(serviceAPIKey) == "" { + slog.Error("internal API key is required for sirius-api startup (SIRIUS_API_KEY_FILE or SIRIUS_API_KEY)", "error", err) + os.Exit(1) + } + + // Initialize the logging SDK + logging.Init() + defer logging.Close() + + // Run database migrations before starting the API + if err := runMigrations(); err != nil { + slog.Error("Failed to run migrations", "error", err) + os.Exit(1) + } + + // Initialize Valkey store for dynamic API key management. + kvStore, err := store.NewValkeyStore() + if err != nil { + slog.Error("Failed to connect to Valkey", "error", err) + os.Exit(1) + } + defer kvStore.Close() + + app := fiber.New() + + // Add CORS middleware + allowedOrigins := os.Getenv("CORS_ALLOWED_ORIGINS") + if allowedOrigins == "" { + allowedOrigins = "*" // Default to allow all origins + } + app.Use(cors.New(cors.Config{ + AllowOrigins: allowedOrigins, + AllowMethods: "GET,POST,HEAD,PUT,DELETE,PATCH", + })) + + // Add request ID middleware + app.Use(requestid.New()) + + // Add level-aware request logging middleware + app.Use(requestLoggerMiddleware()) + + // Add API key authentication middleware + app.Use(middleware.APIKeyMiddleware(kvStore, serviceAPIKey)) + + // Add SDK-based logging middlewares + app.Use(middleware.SDKLoggingMiddleware()) + app.Use(middleware.SDKErrorLoggingMiddleware()) + app.Use(middleware.SDKPerformanceMetricsMiddleware()) + + vulnerabilityRouteSetter := &routes.VulnerabilityRouteSetter{} + templateRouteSetter := &routes.TemplateRouteSetter{} + scriptRouteSetter := &routes.ScriptRouteSetter{} + agentTemplateRouteSetter := &routes.AgentTemplateRouteSetter{} + agentTemplateRepositoryRouteSetter := &routes.AgentTemplateRepositoryRouteSetter{} + eventRouteSetter := &routes.EventRouteSetter{} + snapshotRouteSetter := &routes.SnapshotRouteSetter{} + statisticsRouteSetter := &routes.StatisticsRoutes{} + scanRouteSetter := &routes.ScanRouteSetter{} + apiKeyRouteSetter := &routes.APIKeyRouteSetter{Store: kvStore} + routes.SetupRoutes( + app, + &routes.HostRouteSetter{}, + &routes.AppRouteSetter{}, + vulnerabilityRouteSetter, + templateRouteSetter, + scriptRouteSetter, + agentTemplateRepositoryRouteSetter, // Must be before agentTemplateRouteSetter to avoid :id matching + agentTemplateRouteSetter, + eventRouteSetter, // Event routes for scan events + snapshotRouteSetter, // Snapshot and vulnerability trend routes + statisticsRouteSetter, // Statistics routes + scanRouteSetter, // Scan control routes (cancel, status) + apiKeyRouteSetter, // API key management routes + ) + + slog.Info("Sirius API starting", "port", 9001, "log_level", os.Getenv("LOG_LEVEL"), "auth_required", true) + app.Listen(":9001") +} + +// requestLoggerMiddleware returns a Fiber middleware that logs HTTP requests +// at a level appropriate to the configured LOG_LEVEL: +// +// - debug: logs every request +// - info: skips /health and routine polling endpoints (GET /host/, GET /host/statistics/*) +// - warn: only logs slow requests (>1s) or 4xx+ status codes +// - error: only logs 5xx status codes +func requestLoggerMiddleware() fiber.Handler { + return func(c *fiber.Ctx) error { + start := time.Now() + + err := c.Next() + + latency := time.Since(start) + status := c.Response().StatusCode() + method := c.Method() + path := c.Path() + + attrs := []any{ + "method", method, + "path", path, + "status", status, + "latency", latency.String(), + } + + // error level: only 5xx + if status >= 500 { + slog.Error("request", attrs...) + return err + } + + // warn level: 4xx or slow requests (>1s) + if status >= 400 { + slog.Warn("request", attrs...) + return err + } + if latency > 1*time.Second { + slog.Warn("slow request", attrs...) + return err + } + + // info level: skip health checks and high-frequency polling endpoints + if isNoisyEndpoint(method, path) { + slog.Debug("request", attrs...) + return err + } + + // Everything else at info + slog.Info("request", attrs...) + return err + } +} + +// isNoisyEndpoint returns true for endpoints that fire on a recurring polling +// interval and would flood the logs at info level. +func isNoisyEndpoint(method, path string) bool { + if method != "GET" { + return false + } + switch { + case path == "/health": + return true + case path == "/host/" || path == "/host": + return true + case strings.HasPrefix(path, "/host/statistics/"): + return true + default: + return false + } +} diff --git a/sirius-api/middleware/apikey_middleware.go b/sirius-api/middleware/apikey_middleware.go new file mode 100644 index 0000000..707f8fe --- /dev/null +++ b/sirius-api/middleware/apikey_middleware.go @@ -0,0 +1,60 @@ +package middleware + +import ( + "context" + "crypto/subtle" + "log/slog" + "strings" + + "github.com/SiriusScan/go-api/sirius/store" + "github.com/gofiber/fiber/v2" +) + +// skipPaths lists route prefixes that do not require API key authentication. +var skipPaths = []string{ + "/health", +} + +// APIKeyMiddleware returns a Fiber middleware that validates the X-API-Key +// header against keys stored in Valkey. Requests to health-check endpoints +// are allowed through without authentication. +// rootKey is the installer/internal service key (from SIRIUS_API_KEY_FILE or SIRIUS_API_KEY). +func APIKeyMiddleware(kvStore store.KVStore, rootKey string) fiber.Handler { + rootKey = strings.TrimSpace(rootKey) + return func(c *fiber.Ctx) error { + // Skip authentication for health and other excluded paths. + for _, p := range skipPaths { + if strings.HasPrefix(c.Path(), p) { + return c.Next() + } + } + + apiKey := c.Get("X-API-Key") + if apiKey == "" { + return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{ + "error": "missing API key – include X-API-Key header", + }) + } + + if rootKey != "" && subtle.ConstantTimeCompare([]byte(apiKey), []byte(rootKey)) == 1 { + c.Locals("auth_mode", "infra_env") + c.Locals("apikey_label", "Infrastructure Key") + slog.Debug("request authenticated with environment infrastructure key") + return c.Next() + } + + // Fallback: Check Valkey for dynamic, user-generated API keys + meta, err := store.ValidateAPIKey(context.Background(), kvStore, apiKey) + if err != nil { + return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{ + "error": "invalid API key", + }) + } + + // Store metadata in request locals for downstream handlers. + c.Locals("auth_mode", "valkey") + c.Locals("apikey_meta", meta) + return c.Next() + } +} + diff --git a/sirius-api/middleware/sdk_logging_middleware.go b/sirius-api/middleware/sdk_logging_middleware.go new file mode 100644 index 0000000..c1e15d1 --- /dev/null +++ b/sirius-api/middleware/sdk_logging_middleware.go @@ -0,0 +1,139 @@ +package middleware + +import ( + "fmt" + "strings" + "time" + + "github.com/SiriusScan/go-api/sirius/logging" + "github.com/gofiber/fiber/v2" +) + +// SDKLoggingMiddleware creates a middleware for automatic API logging using the SDK +func SDKLoggingMiddleware() fiber.Handler { + return func(c *fiber.Ctx) error { + start := time.Now() + + // Generate or get request ID + requestID := c.Get("X-Request-ID") + if requestID == "" { + requestID = fmt.Sprintf("req_%d", time.Now().UnixNano()) + c.Set("X-Request-ID", requestID) + } + + // Process request + err := c.Next() + + // Calculate duration + duration := time.Since(start) + durationMs := duration.Milliseconds() + + // Only log meaningful events (errors or very slow requests) + shouldLog := false + if c.Response().StatusCode() >= 400 { // Log all errors + shouldLog = true + } else if durationMs > 5000 { // Only log very slow requests (5+ seconds) + shouldLog = true + } + + if shouldLog && !strings.Contains(c.Path(), "/api/v1/logs") { + // Prepare metadata + metadata := map[string]interface{}{ + "request_id": requestID, + "method": c.Method(), + "path": c.Path(), + "status_code": c.Response().StatusCode(), + "duration_ms": durationMs, + "remote_ip": c.IP(), + "user_agent": c.Get("User-Agent"), + "content_length": c.Get("Content-Length"), + "response_size": len(c.Response().Body()), + } + + // Add request body for small requests + if c.Body() != nil && len(c.Body()) < 1024 { + metadata["request_body"] = string(c.Body()) + } + + // Prepare context + context := map[string]interface{}{ + "endpoint": c.Path(), + "method": c.Method(), + } + + // Determine log level + level := logging.LogLevelInfo + if c.Response().StatusCode() >= 500 { + level = logging.LogLevelError + } else if c.Response().StatusCode() >= 400 { + level = logging.LogLevelWarn + } + + // Create message + message := fmt.Sprintf("%s %s - %d", c.Method(), c.Path(), c.Response().StatusCode()) + if err != nil { + message = fmt.Sprintf("%s %s - %d (error: %v)", c.Method(), c.Path(), c.Response().StatusCode(), err) + } + + // Log using SDK + logging.Log("sirius-api", "http-middleware", level, message, metadata, context) + } + + return err + } +} + +// SDKErrorLoggingMiddleware creates middleware for comprehensive error logging using the SDK +func SDKErrorLoggingMiddleware() fiber.Handler { + return func(c *fiber.Ctx) error { + err := c.Next() + if err != nil { + // Log the error using SDK + requestID := c.Get("X-Request-ID") + + metadata := map[string]interface{}{ + "request_id": requestID, + "method": c.Method(), + "path": c.Path(), + } + + errorDetails := logging.ErrorDetails{ + ErrorMessage: err.Error(), + Source: "http-middleware", + Metadata: metadata, + } + + logging.LogError("sirius-api", "error-handler", err, errorDetails, metadata) + } + return err + } +} + +// SDKPerformanceMetricsMiddleware creates middleware for capturing performance metrics using the SDK +func SDKPerformanceMetricsMiddleware() fiber.Handler { + return func(c *fiber.Ctx) error { + start := time.Now() + err := c.Next() + duration := time.Since(start) + + // Only log performance for non-logging endpoints and slow requests + if !strings.Contains(c.Path(), "/api/v1/logs") && duration.Milliseconds() > 1000 { + requestID := c.Get("X-Request-ID") + + metadata := map[string]interface{}{ + "request_id": requestID, + "method": c.Method(), + "path": c.Path(), + "status_code": c.Response().StatusCode(), + } + + performanceMetric := logging.PerformanceMetric{ + Duration: duration, + Metadata: metadata, + } + + logging.LogPerformanceMetric("sirius-api", "performance-monitor", performanceMetric, metadata) + } + return err + } +} diff --git a/sirius-api/routes/agent_template_repository_routes.go b/sirius-api/routes/agent_template_repository_routes.go new file mode 100644 index 0000000..ae98426 --- /dev/null +++ b/sirius-api/routes/agent_template_repository_routes.go @@ -0,0 +1,25 @@ +package routes + +import ( + "github.com/SiriusScan/sirius-api/handlers" + "github.com/gofiber/fiber/v2" +) + +// AgentTemplateRepositoryRouteSetter sets up agent template repository routes +type AgentTemplateRepositoryRouteSetter struct{} + +func (r *AgentTemplateRepositoryRouteSetter) SetupRoutes(app *fiber.App) { + api := app.Group("/api") + repos := api.Group("/agent-templates/repositories") + + // Repository CRUD operations + repos.Get("/", handlers.GetAgentTemplateRepositories) // GET /api/agent-templates/repositories - List all + repos.Post("/", handlers.AddAgentTemplateRepository) // POST /api/agent-templates/repositories - Add new + repos.Put("/:id", handlers.UpdateAgentTemplateRepository) // PUT /api/agent-templates/repositories/:id - Update + repos.Delete("/:id", handlers.DeleteAgentTemplateRepository) // DELETE /api/agent-templates/repositories/:id - Delete + + // Repository sync operations + repos.Post("/:id/sync", handlers.TriggerAgentTemplateRepositorySync) // POST /api/agent-templates/repositories/:id/sync - Trigger sync + repos.Get("/:id/sync-status", handlers.GetAgentTemplateRepositorySyncStatus) // GET /api/agent-templates/repositories/:id/sync-status - Get sync status +} + diff --git a/sirius-api/routes/agent_template_routes.go b/sirius-api/routes/agent_template_routes.go new file mode 100644 index 0000000..bd77b08 --- /dev/null +++ b/sirius-api/routes/agent_template_routes.go @@ -0,0 +1,29 @@ +package routes + +import ( + "github.com/SiriusScan/sirius-api/handlers" + "github.com/gofiber/fiber/v2" +) + +// AgentTemplateRouteSetter implements the RouteSetter interface for agent template routes +type AgentTemplateRouteSetter struct{} + +func (s *AgentTemplateRouteSetter) SetupRoutes(app *fiber.App) { + api := app.Group("/api") + templates := api.Group("/agent-templates") + + // Template CRUD operations + templates.Get("/", handlers.GetAgentTemplates) // GET /api/agent-templates - List all + templates.Get("/:id", handlers.GetAgentTemplate) // GET /api/agent-templates/:id - Get one + templates.Post("/", handlers.UploadAgentTemplate) // POST /api/agent-templates - Upload custom + templates.Put("/:id", handlers.UpdateAgentTemplate) // PUT /api/agent-templates/:id - Update + templates.Delete("/:id", handlers.DeleteAgentTemplate) // DELETE /api/agent-templates/:id - Delete + + // Template operations + templates.Post("/validate", handlers.ValidateAgentTemplate) // POST /api/agent-templates/validate - Validate + templates.Post("/:id/test", handlers.TestAgentTemplate) // POST /api/agent-templates/:id/test - Test + templates.Post("/:id/deploy", handlers.DeployAgentTemplate) // POST /api/agent-templates/:id/deploy - Deploy + templates.Get("/analytics", handlers.GetAgentTemplateAnalytics) // GET /api/agent-templates/analytics - Analytics + templates.Get("/:id/results", handlers.GetAgentTemplateResults) // GET /api/agent-templates/:id/results - Results +} + diff --git a/sirius-api/routes/apikey_routes.go b/sirius-api/routes/apikey_routes.go new file mode 100644 index 0000000..67109d5 --- /dev/null +++ b/sirius-api/routes/apikey_routes.go @@ -0,0 +1,21 @@ +package routes + +import ( + "github.com/SiriusScan/go-api/sirius/store" + "github.com/SiriusScan/sirius-api/handlers" + "github.com/gofiber/fiber/v2" +) + +// APIKeyRouteSetter registers the API key management endpoints. +type APIKeyRouteSetter struct { + Store store.KVStore +} + +func (s *APIKeyRouteSetter) SetupRoutes(app *fiber.App) { + h := &handlers.APIKeyHandler{Store: s.Store} + + keys := app.Group("/api/v1/keys") + keys.Post("/", h.CreateKey) + keys.Get("/", h.ListKeys) + keys.Delete("/:id", h.RevokeKey) +} diff --git a/sirius-api/routes/app_routes.go b/sirius-api/routes/app_routes.go new file mode 100755 index 0000000..dab5564 --- /dev/null +++ b/sirius-api/routes/app_routes.go @@ -0,0 +1,336 @@ +// routes/app_routes.go +package routes + +import ( + "encoding/json" + "fmt" + "strconv" + "time" + + "github.com/SiriusScan/sirius-api/handlers" + "github.com/SiriusScan/sirius-api/services" + "github.com/gofiber/fiber/v2" +) + +type AppRouteSetter struct { + dockerHandler *handlers.DockerHandler + valkeyMonitorService *services.ValkeyMonitorService + rabbitMQService *services.RabbitMQService +} + +func (h *AppRouteSetter) SetupRoutes(app *fiber.App) { + // Initialize Docker handler + var err error + h.dockerHandler, err = handlers.NewDockerHandler() + if err != nil { + fmt.Printf("Warning: Failed to initialize Docker handler: %v\n", err) + fmt.Println("Falling back to mock data for Docker endpoints") + } + + // Initialize Valkey monitor service + h.valkeyMonitorService, err = services.NewValkeyMonitorService() + if err != nil { + fmt.Printf("Warning: Failed to initialize Valkey monitor service: %v\n", err) + fmt.Println("Falling back to mock data for system monitoring endpoints") + } + + // Initialize RabbitMQ service + h.rabbitMQService, err = services.NewRabbitMQService() + if err != nil { + fmt.Printf("Warning: Failed to initialize RabbitMQ service: %v\n", err) + fmt.Println("Admin commands will not be available") + } + // Health check route at root level + app.Get("/health", handlers.HealthHandler) + + // System health check route + app.Get("/api/v1/system/health", handlers.SystemHealthHandler) + + // Test route to verify route registration + app.Get("/api/v1/test", func(c *fiber.Ctx) error { + fmt.Println("🚀 Test endpoint called!") + return c.JSON(fiber.Map{"message": "Test endpoint working"}) + }) + + // Docker logs viewer route + app.Get("/api/v1/system/logs", func(c *fiber.Ctx) error { + + containerName := c.Query("container", "all") + linesStr := c.Query("lines", "100") + lines, _ := strconv.Atoi(linesStr) + + if h.valkeyMonitorService != nil { + // Use real Valkey integration + logs, containerNames, err := h.valkeyMonitorService.GetDockerLogs(c.Context(), containerName, lines) + if err != nil { + fmt.Printf("Error getting Docker logs: %v\n", err) + // Fall back to mock data on error + } else { + return c.JSON(fiber.Map{ + "message": "Docker logs endpoint is working (real data)", + "timestamp": time.Now(), + "container": containerName, + "lines": linesStr, + "logs": logs, + "summary": fiber.Map{ + "total_logs": len(logs), + "containers": containerNames, + }, + }) + } + } + + // Fallback to mock data + mockLogs := []fiber.Map{ + { + "container": "sirius-api", + "timestamp": time.Now().Add(-1 * time.Minute).Format("2006-01-02T15:04:05Z"), + "level": "INFO", + "message": "🚀 Sirius API starting on port 9001...", + }, + { + "container": "sirius-api", + "timestamp": time.Now().Add(-2 * time.Minute).Format("2006-01-02T15:04:05Z"), + "level": "INFO", + "message": "✅ PostgreSQL database connection established", + }, + { + "container": "sirius-ui", + "timestamp": time.Now().Add(-3 * time.Minute).Format("2006-01-02T15:04:05Z"), + "level": "INFO", + "message": "Ready - started server on 0.0.0.0:3000", + }, + { + "container": "sirius-engine", + "timestamp": time.Now().Add(-4 * time.Minute).Format("2006-01-02T15:04:05Z"), + "level": "INFO", + "message": "Scanner service initialized successfully", + }, + { + "container": "sirius-postgres", + "timestamp": time.Now().Add(-5 * time.Minute).Format("2006-01-02T15:04:05Z"), + "level": "INFO", + "message": "database system is ready to accept connections", + }, + } + + // Filter logs by container if specified + if containerName != "all" { + filteredLogs := []fiber.Map{} + for _, log := range mockLogs { + if log["container"] == containerName { + filteredLogs = append(filteredLogs, log) + } + } + mockLogs = filteredLogs + } + + return c.JSON(fiber.Map{ + "message": "Docker logs endpoint is working (mock data)", + "timestamp": time.Now(), + "container": containerName, + "lines": lines, + "logs": mockLogs, + "summary": fiber.Map{ + "total_logs": len(mockLogs), + "containers": []string{"sirius-api", "sirius-ui", "sirius-engine", "sirius-postgres", "sirius-valkey", "sirius-rabbitmq"}, + }, + }) + }) + + // System resource monitoring route + app.Get("/api/v1/system/resources", func(c *fiber.Ctx) error { + + if h.valkeyMonitorService != nil { + // Use real Valkey integration + resources, summary, err := h.valkeyMonitorService.GetContainerResources(c.Context()) + if err != nil { + fmt.Printf("Error getting container resources: %v\n", err) + // Fall back to mock data on error + } else { + return c.JSON(fiber.Map{ + "message": "System resource monitoring endpoint is working (real data)", + "timestamp": time.Now(), + "containers": resources, + "summary": summary, + }) + } + } + + // Fallback to mock data + return c.JSON(fiber.Map{ + "message": "System resource monitoring endpoint is working (mock data)", + "timestamp": time.Now(), + "containers": []fiber.Map{ + { + "name": "sirius-api", + "cpu_percent": 2.5, + "memory_usage": "45.2MB", + "memory_percent": 1.2, + "network_io": "1.2kB / 856B", + "block_io": "0B / 0B", + "status": "running", + }, + { + "name": "sirius-ui", + "cpu_percent": 1.8, + "memory_usage": "128.5MB", + "memory_percent": 3.4, + "network_io": "2.1kB / 1.2kB", + "block_io": "0B / 0B", + "status": "running", + }, + { + "name": "sirius-engine", + "cpu_percent": 0.5, + "memory_usage": "89.3MB", + "memory_percent": 2.1, + "network_io": "856B / 432B", + "block_io": "0B / 0B", + "status": "running", + }, + { + "name": "sirius-postgres", + "cpu_percent": 0.2, + "memory_usage": "156.7MB", + "memory_percent": 4.1, + "network_io": "3.2kB / 2.1kB", + "block_io": "1.2MB / 856kB", + "status": "running", + }, + { + "name": "sirius-valkey", + "cpu_percent": 0.1, + "memory_usage": "12.3MB", + "memory_percent": 0.3, + "network_io": "432B / 256B", + "block_io": "0B / 0B", + "status": "running", + }, + { + "name": "sirius-rabbitmq", + "cpu_percent": 0.3, + "memory_usage": "67.8MB", + "memory_percent": 1.8, + "network_io": "1.5kB / 1.1kB", + "block_io": "0B / 0B", + "status": "running", + }, + }, + "summary": fiber.Map{ + "total_containers": 6, + "running_containers": 6, + "total_cpu_percent": 5.4, + "total_memory_usage": "499.8MB", + "total_memory_percent": 13.1, + }, + }) + }) + + // Admin command route + app.Post("/api/v1/admin/command", func(c *fiber.Ctx) error { + + var request struct { + Action string `json:"action"` + ContainerName string `json:"container_name"` + } + + if err := c.BodyParser(&request); err != nil { + return c.Status(400).JSON(fiber.Map{ + "error": "Invalid request body", + }) + } + + // Validate required fields + if request.Action == "" || request.ContainerName == "" { + return c.Status(400).JSON(fiber.Map{ + "error": "Missing required fields: action, container_name", + }) + } + + // Generate request ID + requestID := fmt.Sprintf("req_%d", time.Now().UnixNano()) + + // Create admin command for RabbitMQ + command := fiber.Map{ + "action": request.Action, + "target": request.ContainerName, + "timestamp": time.Now(), + "request_id": requestID, + } + + // Marshal command to JSON + commandJSON, err := json.Marshal(command) + if err != nil { + return c.Status(500).JSON(fiber.Map{ + "error": "Failed to marshal command", + }) + } + + // Publish command to RabbitMQ admin queue + if h.rabbitMQService != nil { + if err := h.rabbitMQService.PublishMessage("admin_commands", commandJSON); err != nil { + return c.Status(500).JSON(fiber.Map{ + "error": "Failed to publish command to RabbitMQ", + }) + } + } else { + return c.Status(500).JSON(fiber.Map{ + "error": "RabbitMQ service not available", + }) + } + + return c.JSON(fiber.Map{ + "message": "Admin command sent successfully", + "request_id": requestID, + "action": request.Action, + "container": request.ContainerName, + "timestamp": time.Now(), + }) + }) + + // Performance metrics route (temporarily using health handler) + app.Get("/api/v1/performance/metrics", func(c *fiber.Ctx) error { + return c.JSON(fiber.Map{ + "message": "Performance metrics endpoint is working", + "timestamp": time.Now(), + "metrics": []fiber.Map{ + { + "endpoint": "/api/v1/system/health", + "method": "GET", + "duration_ms": 15, + "status_code": 200, + "timestamp": time.Now().Add(-1 * time.Minute), + }, + { + "endpoint": "/api/v1/logs/stats", + "method": "GET", + "duration_ms": 8, + "status_code": 200, + "timestamp": time.Now().Add(-2 * time.Minute), + }, + }, + "summary": fiber.Map{ + "total_requests": 2, + "average_response_ms": 11.5, + "error_rate": 0.0, + }, + }) + }) + + // Logging routes - specific routes first to avoid conflicts + app.Get("/api/v1/logs/stats", handlers.LogStatsHandler) + app.Delete("/api/v1/logs/clear", handlers.LogClearHandler) + + // Individual log operations (must come before general /api/v1/logs) + app.Put("/api/v1/logs/:logId", handlers.LogUpdateHandler) + app.Delete("/api/v1/logs/:logId", handlers.LogDeleteHandler) + + // General logging routes + app.Post("/api/v1/logs", handlers.LogSubmissionHandler) + app.Get("/api/v1/logs", handlers.LogRetrievalHandler) + + // App-specific routes + appRoutes := app.Group("/app") + appRoutes.Post("/:appName", handlers.AppHandler) +} diff --git a/sirius-api/routes/event_routes.go b/sirius-api/routes/event_routes.go new file mode 100644 index 0000000..3440ba7 --- /dev/null +++ b/sirius-api/routes/event_routes.go @@ -0,0 +1,23 @@ +package routes + +import ( + "github.com/SiriusScan/sirius-api/handlers" + "github.com/gofiber/fiber/v2" +) + +// EventRouteSetter sets up event-related routes +type EventRouteSetter struct{} + +// SetupRoutes sets up event endpoints +func (e *EventRouteSetter) SetupRoutes(app *fiber.App) { + // Create event API group + api := app.Group("/api/v1/events") + + // Event endpoints + api.Get("/", handlers.GetEvents) // List events with filters + api.Get("/:id", handlers.GetEvent) // Get single event by event_id + api.Get("/stats", handlers.GetEventStats) // Get event statistics + api.Get("/by-entity", handlers.GetEventsByEntity) // Get events by entity + api.Get("/by-severity/:severity", handlers.GetRecentEventsBySeverity) // Get events by severity +} + diff --git a/sirius-api/routes/host_routes.go b/sirius-api/routes/host_routes.go new file mode 100755 index 0000000..f2ca6e4 --- /dev/null +++ b/sirius-api/routes/host_routes.go @@ -0,0 +1,48 @@ +// routes/host_routes.go +package routes + +// GetHost handles the GET /host/{id} route +// GetAllHosts handles the GET /host route + +import ( + "github.com/SiriusScan/sirius-api/handlers" + "github.com/gofiber/fiber/v2" +) + +type HostRouteSetter struct{} + +// SetupRoutes sets up all the routes for the host package +func (h *HostRouteSetter) SetupRoutes(app *fiber.App) { + hostRoutes := app.Group("/host") + + // Specific routes first (before parameterized routes) + hostRoutes.Get("/", handlers.GetAllHosts) + hostRoutes.Post("/", handlers.AddHost) + hostRoutes.Put("/:id", handlers.UpdateHost) + hostRoutes.Post("/delete", handlers.DeleteHost) + hostRoutes.Get("/vulnerabilities/all", handlers.GetAllVulnerabilities) + hostRoutes.Get("/source-coverage", handlers.GetSourceCoverageStats) + + // Source-aware endpoints for Phase 1 testing + hostRoutes.Post("/with-source", handlers.AddHostWithSource) + + // SBOM and Enhanced Data endpoints (specific routes first) + hostRoutes.Get("/:id/packages", handlers.GetHostPackages) + hostRoutes.Get("/:id/fingerprint", handlers.GetHostFingerprint) + hostRoutes.Get("/:id/software-stats", handlers.GetHostSoftwareStats) + + // Parameterized routes last (these catch patterns) + hostRoutes.Get("/:id", handlers.GetHost) + hostRoutes.Get("/statistics/:id", handlers.GetHostStatistics) + hostRoutes.Get("/severity/:id", handlers.GetHostVulnerabilitySeverityCounts) + hostRoutes.Get("/:id/sources", handlers.GetHostWithSources) + hostRoutes.Get("/:id/history", handlers.GetHostHistory) + hostRoutes.Get("/:id/vulnerability/:vulnId/history", handlers.GetVulnerabilityHistory) + + // Source-aware endpoints + hostRoutes.Get("/:ip/sources", handlers.GetHostWithSources) + hostRoutes.Get("/source-coverage", handlers.GetSourceCoverageStats) + + // Vulnerability source endpoint (at app level, not host level) + app.Get("/vulnerability/:id/sources", handlers.GetVulnerabilitySources) +} diff --git a/sirius-api/routes/routes.go b/sirius-api/routes/routes.go new file mode 100755 index 0000000..f8ce297 --- /dev/null +++ b/sirius-api/routes/routes.go @@ -0,0 +1,16 @@ +package routes + +import ( + "github.com/gofiber/fiber/v2" +) + +type RouteSetter interface { + SetupRoutes(*fiber.App) +} + +// SetupRoutes sets up all the routes for the application +func SetupRoutes(app *fiber.App, setters ...RouteSetter) { + for _, setter := range setters { + setter.SetupRoutes(app) + } +} diff --git a/sirius-api/routes/scan_routes.go b/sirius-api/routes/scan_routes.go new file mode 100644 index 0000000..3cb147f --- /dev/null +++ b/sirius-api/routes/scan_routes.go @@ -0,0 +1,27 @@ +package routes + +import ( + "github.com/SiriusScan/sirius-api/handlers" + "github.com/gofiber/fiber/v2" +) + +// ScanRouteSetter implements RouteSetter for scan-related routes +type ScanRouteSetter struct{} + +// SetupRoutes registers scan control routes +func (s *ScanRouteSetter) SetupRoutes(app *fiber.App) { + // API v1 scan routes + api := app.Group("/api/v1/scans") + + // POST /api/v1/scans/cancel - Cancel the current running scan (graceful) + api.Post("/cancel", handlers.CancelScan) + + // POST /api/v1/scans/force-stop - Force stop the scan and reset state + api.Post("/force-stop", handlers.ForceStopScan) + + // POST /api/v1/scans/reset - Reset scan dashboard state (last resort) + api.Post("/reset", handlers.ResetScanState) + + // GET /api/v1/scans/status - Get the current scan status + api.Get("/status", handlers.GetScanStatus) +} diff --git a/sirius-api/routes/script_routes.go b/sirius-api/routes/script_routes.go new file mode 100644 index 0000000..6a3f2e1 --- /dev/null +++ b/sirius-api/routes/script_routes.go @@ -0,0 +1,12 @@ +package routes + +import "github.com/gofiber/fiber/v2" + +// ScriptRouteSetter sets up script routes +type ScriptRouteSetter struct{} + +func (s *ScriptRouteSetter) SetupRoutes(app *fiber.App) { + // Script routes will be implemented here + // Placeholder to satisfy RouteSetter interface +} + diff --git a/sirius-api/routes/snapshot_routes.go b/sirius-api/routes/snapshot_routes.go new file mode 100644 index 0000000..4440145 --- /dev/null +++ b/sirius-api/routes/snapshot_routes.go @@ -0,0 +1,22 @@ +package routes + +import ( + "github.com/SiriusScan/sirius-api/handlers" + "github.com/gofiber/fiber/v2" +) + +type SnapshotRouteSetter struct{} + +func (s *SnapshotRouteSetter) SetupRoutes(app *fiber.App) { + api := app.Group("/api/v1") + stats := api.Group("/statistics") + + // Trend retrieval + stats.Get("/vulnerability-trends", handlers.GetVulnerabilityTrends) + + // Snapshot management + stats.Get("/vulnerability-snapshots", handlers.ListSnapshots) + stats.Get("/vulnerability-snapshot/:snapshotId", handlers.GetSnapshot) + stats.Post("/vulnerability-snapshot", handlers.CreateSnapshot) +} + diff --git a/sirius-api/routes/statistics_routes.go b/sirius-api/routes/statistics_routes.go new file mode 100644 index 0000000..aa1e763 --- /dev/null +++ b/sirius-api/routes/statistics_routes.go @@ -0,0 +1,20 @@ +package routes + +import ( + "github.com/SiriusScan/sirius-api/handlers" + "github.com/gofiber/fiber/v2" +) + +// StatisticsRoutes implements RouteSetter for statistics-related endpoints +type StatisticsRoutes struct{} + +// SetupRoutes registers all statistics routes +func (StatisticsRoutes) SetupRoutes(app *fiber.App) { + // API v1 statistics group + api := app.Group("/api/v1/statistics") + + // Host statistics endpoints + hosts := api.Group("/hosts") + hosts.Get("/most-vulnerable", handlers.GetMostVulnerableHosts) +} + diff --git a/sirius-api/routes/template_routes.go b/sirius-api/routes/template_routes.go new file mode 100644 index 0000000..12c970c --- /dev/null +++ b/sirius-api/routes/template_routes.go @@ -0,0 +1,21 @@ +package routes + +import ( + "github.com/SiriusScan/sirius-api/handlers" + "github.com/gofiber/fiber/v2" +) + +// TemplateRouteSetter sets up template routes +type TemplateRouteSetter struct{} + +func (t *TemplateRouteSetter) SetupRoutes(app *fiber.App) { + templates := app.Group("/templates") + + // Template CRUD operations + templates.Get("/", handlers.GetTemplates) // GET /templates - List all + templates.Get("/:id", handlers.GetTemplate) // GET /templates/:id - Get one + templates.Post("/", handlers.CreateTemplate) // POST /templates - Create + templates.Put("/:id", handlers.UpdateTemplate) // PUT /templates/:id - Update + templates.Delete("/:id", handlers.DeleteTemplate) // DELETE /templates/:id - Delete +} + diff --git a/sirius-api/routes/vulnerability_routes.go b/sirius-api/routes/vulnerability_routes.go new file mode 100755 index 0000000..2377570 --- /dev/null +++ b/sirius-api/routes/vulnerability_routes.go @@ -0,0 +1,20 @@ +// routes/vulnerability_routes.go +package routes + +// GetVulnerability handles the GET /vulnerability/{id} route + +import ( + "github.com/SiriusScan/sirius-api/handlers" + "github.com/gofiber/fiber/v2" +) + +type VulnerabilityRouteSetter struct{} + +func (h *VulnerabilityRouteSetter) SetupRoutes(app *fiber.App) { + vulnerabilityRoutes := app.Group("/vulnerability") + vulnerabilityRoutes.Get("/:id", handlers.GetVulnerability) + vulnerabilityRoutes.Post("/", handlers.AddVulnerability) + vulnerabilityRoutes.Post("/delete", handlers.DeleteVulnerability) +} + +// Note: GetAllVulnerabilities is host/vulnerabilities/all \ No newline at end of file diff --git a/sirius-api/services/docker_service.go b/sirius-api/services/docker_service.go new file mode 100644 index 0000000..6b22507 --- /dev/null +++ b/sirius-api/services/docker_service.go @@ -0,0 +1,333 @@ +package services + +import ( + "context" + "fmt" + "os/exec" + "strconv" + "strings" + "time" +) + +// DockerService handles container monitoring using system commands +type DockerService struct{} + +// ContainerResource represents container resource usage +type ContainerResource struct { + Name string `json:"name"` + CPUPercent float64 `json:"cpu_percent"` + MemoryUsage string `json:"memory_usage"` + MemoryPercent float64 `json:"memory_percent"` + NetworkIO string `json:"network_io"` + BlockIO string `json:"block_io"` + Status string `json:"status"` +} + +// ContainerLog represents a container log entry +type ContainerLog struct { + Container string `json:"container"` + Timestamp string `json:"timestamp"` + Level string `json:"level"` + Message string `json:"message"` +} + +// SystemResourcesSummary represents system resource summary +type SystemResourcesSummary struct { + TotalContainers int `json:"total_containers"` + RunningContainers int `json:"running_containers"` + TotalCPUPercent float64 `json:"total_cpu_percent"` + TotalMemoryUsage string `json:"total_memory_usage"` + TotalMemoryPercent float64 `json:"total_memory_percent"` +} + +// NewDockerService creates a new Docker service instance +func NewDockerService() (*DockerService, error) { + // Test if we can access system information + _, err := exec.Command("ps", "aux").Output() + if err != nil { + return nil, fmt.Errorf("system commands not available: %w", err) + } + + return &DockerService{}, nil +} + +// GetContainerResources retrieves resource usage for all containers +func (d *DockerService) GetContainerResources(ctx context.Context) ([]ContainerResource, SystemResourcesSummary, error) { + // Get container information using system commands + // Since we're running inside a container, we'll simulate container data + // based on the current system state + + // Get system memory info + memInfo, err := d.getMemoryInfo() + if err != nil { + return nil, SystemResourcesSummary{}, fmt.Errorf("failed to get memory info: %w", err) + } + + // Get system CPU info + cpuInfo, err := d.getCPUInfo() + if err != nil { + return nil, SystemResourcesSummary{}, fmt.Errorf("failed to get CPU info: %w", err) + } + + // Simulate container data based on system state + containers := []string{"sirius-api", "sirius-ui", "sirius-engine", "sirius-postgres", "sirius-valkey", "sirius-rabbitmq"} + var resources []ContainerResource + var totalCPU, totalMemory float64 + var totalMemoryBytes int64 + + for i, containerName := range containers { + // Simulate realistic resource usage + cpuPercent := d.simulateCPUUsage(i, cpuInfo) + memoryUsage := d.simulateMemoryUsage(i, memInfo) + memoryPercent := d.simulateMemoryPercent(i, memInfo) + networkIO := d.simulateNetworkIO(i) + blockIO := d.simulateBlockIO(i) + + resource := ContainerResource{ + Name: containerName, + CPUPercent: cpuPercent, + MemoryUsage: memoryUsage, + MemoryPercent: memoryPercent, + NetworkIO: networkIO, + BlockIO: blockIO, + Status: "running", + } + + resources = append(resources, resource) + + // Update totals + totalCPU += cpuPercent + totalMemory += memoryPercent + if bytes := d.parseMemoryBytes(memoryUsage); bytes > 0 { + totalMemoryBytes += bytes + } + } + + summary := SystemResourcesSummary{ + TotalContainers: len(resources), + RunningContainers: len(resources), + TotalCPUPercent: totalCPU, + TotalMemoryUsage: d.formatBytes(totalMemoryBytes), + TotalMemoryPercent: totalMemory, + } + + return resources, summary, nil +} + +// GetContainerLogs retrieves logs for specified containers +func (d *DockerService) GetContainerLogs(ctx context.Context, containerName string, lines int) ([]ContainerLog, []string, error) { + // Get system logs and simulate container logs + containers := []string{"sirius-api", "sirius-ui", "sirius-engine", "sirius-postgres", "sirius-valkey", "sirius-rabbitmq"} + var logs []ContainerLog + + // Determine which containers to get logs from + var targetContainers []string + if containerName == "all" { + targetContainers = containers + } else { + for _, name := range containers { + if name == containerName { + targetContainers = append(targetContainers, name) + break + } + } + } + + // Generate realistic log entries + for _, container := range targetContainers { + containerLogs := d.generateContainerLogs(container, lines) + logs = append(logs, containerLogs...) + } + + return logs, containers, nil +} + +// Helper functions + +func (d *DockerService) getMemoryInfo() (map[string]string, error) { + // Read /proc/meminfo to get real memory information + cmd := exec.Command("cat", "/proc/meminfo") + output, err := cmd.Output() + if err != nil { + return nil, err + } + + memInfo := make(map[string]string) + lines := strings.Split(string(output), "\n") + for _, line := range lines { + if strings.Contains(line, ":") { + parts := strings.SplitN(line, ":", 2) + if len(parts) == 2 { + memInfo[strings.TrimSpace(parts[0])] = strings.TrimSpace(parts[1]) + } + } + } + return memInfo, nil +} + +func (d *DockerService) getCPUInfo() (map[string]string, error) { + // Read /proc/cpuinfo to get CPU information + cmd := exec.Command("cat", "/proc/cpuinfo") + output, err := cmd.Output() + if err != nil { + return nil, err + } + + cpuInfo := make(map[string]string) + lines := strings.Split(string(output), "\n") + for _, line := range lines { + if strings.Contains(line, ":") { + parts := strings.SplitN(line, ":", 2) + if len(parts) == 2 { + cpuInfo[strings.TrimSpace(parts[0])] = strings.TrimSpace(parts[1]) + } + } + } + return cpuInfo, nil +} + +func (d *DockerService) simulateCPUUsage(index int, cpuInfo map[string]string) float64 { + // Simulate realistic CPU usage based on container type + baseUsage := []float64{2.5, 1.8, 0.5, 0.2, 0.1, 0.3} + if index < len(baseUsage) { + return baseUsage[index] + } + return 0.5 +} + +func (d *DockerService) simulateMemoryUsage(index int, memInfo map[string]string) string { + // Simulate realistic memory usage + baseUsage := []string{"45.2MB", "128.5MB", "89.3MB", "156.7MB", "12.3MB", "67.8MB"} + if index < len(baseUsage) { + return baseUsage[index] + } + return "50.0MB" +} + +func (d *DockerService) simulateMemoryPercent(index int, memInfo map[string]string) float64 { + // Simulate realistic memory percentage + basePercent := []float64{1.2, 3.4, 2.1, 4.1, 0.3, 1.8} + if index < len(basePercent) { + return basePercent[index] + } + return 1.0 +} + +func (d *DockerService) simulateNetworkIO(index int) string { + // Simulate realistic network I/O + baseIO := []string{"1.2kB / 856B", "2.1kB / 1.2kB", "856B / 432B", "3.2kB / 2.1kB", "432B / 256B", "1.5kB / 1.1kB"} + if index < len(baseIO) { + return baseIO[index] + } + return "1.0kB / 500B" +} + +func (d *DockerService) simulateBlockIO(index int) string { + // Simulate realistic block I/O + baseIO := []string{"0B / 0B", "0B / 0B", "0B / 0B", "1.2MB / 856kB", "0B / 0B", "0B / 0B"} + if index < len(baseIO) { + return baseIO[index] + } + return "0B / 0B" +} + +func (d *DockerService) generateContainerLogs(containerName string, lines int) []ContainerLog { + // Generate realistic log entries for each container + logTemplates := map[string][]string{ + "sirius-api": { + "🚀 Sirius API starting on port 9001...", + "✅ PostgreSQL database connection established", + "📊 Health check endpoint responding", + "🔗 Connected to Valkey cache", + }, + "sirius-ui": { + "Ready - started server on 0.0.0.0:3000", + "📱 Next.js application compiled successfully", + "🎨 UI components loaded", + }, + "sirius-engine": { + "Scanner service initialized successfully", + "🔍 NSE scripts loaded", + "⚡ Engine ready for scanning", + }, + "sirius-postgres": { + "database system is ready to accept connections", + "📊 PostgreSQL server started", + }, + "sirius-valkey": { + "Valkey server started, ready to accept connections", + "💾 Cache system operational", + }, + "sirius-rabbitmq": { + "Server startup complete; 0 plugins started.", + "🐰 Message broker ready", + }, + } + + var logs []ContainerLog + templates, exists := logTemplates[containerName] + if !exists { + templates = []string{"Container running normally"} + } + + // Generate logs with timestamps + for i := 0; i < lines && i < len(templates); i++ { + timestamp := time.Now().Add(-time.Duration(i) * time.Minute).Format(time.RFC3339) + level := "INFO" + if i%5 == 0 { + level = "WARN" + } + if i%10 == 0 { + level = "ERROR" + } + + logs = append(logs, ContainerLog{ + Container: containerName, + Timestamp: timestamp, + Level: level, + Message: templates[i%len(templates)], + }) + } + + return logs +} + +func (d *DockerService) parseMemoryBytes(memoryUsage string) int64 { + // Parse memory usage like "45.2MB" or "1.2GB" + parts := strings.Fields(memoryUsage) + if len(parts) == 0 { + return 0 + } + + value := parts[0] + multiplier := int64(1) + + if strings.HasSuffix(value, "GB") { + multiplier = 1024 * 1024 * 1024 + value = strings.TrimSuffix(value, "GB") + } else if strings.HasSuffix(value, "MB") { + multiplier = 1024 * 1024 + value = strings.TrimSuffix(value, "MB") + } else if strings.HasSuffix(value, "KB") { + multiplier = 1024 + value = strings.TrimSuffix(value, "KB") + } else if strings.HasSuffix(value, "B") { + value = strings.TrimSuffix(value, "B") + } + + f, _ := strconv.ParseFloat(value, 64) + return int64(f * float64(multiplier)) +} + +func (d *DockerService) formatBytes(bytes int64) string { + const unit = 1024 + if bytes < unit { + return fmt.Sprintf("%d B", bytes) + } + div, exp := int64(unit), 0 + for n := bytes / unit; n >= unit; n /= unit { + div *= unit + exp++ + } + return fmt.Sprintf("%.1f %cB", float64(bytes)/float64(div), "KMGTPE"[exp]) +} diff --git a/sirius-api/services/rabbitmq_service.go b/sirius-api/services/rabbitmq_service.go new file mode 100644 index 0000000..7ed531d --- /dev/null +++ b/sirius-api/services/rabbitmq_service.go @@ -0,0 +1,34 @@ +package services + +import ( + "fmt" + "log/slog" + + "github.com/SiriusScan/go-api/sirius/queue" +) + +// RabbitMQService handles RabbitMQ operations for the API +type RabbitMQService struct { + // No client needed since we use the static queue functions +} + +// NewRabbitMQService creates a new RabbitMQ service +func NewRabbitMQService() (*RabbitMQService, error) { + return &RabbitMQService{}, nil +} + +// PublishMessage publishes a message to a RabbitMQ queue +func (r *RabbitMQService) PublishMessage(queueName string, message []byte) error { + // Use the existing queue.Send function + if err := queue.Send(queueName, string(message)); err != nil { + return fmt.Errorf("failed to send message to queue %s: %w", queueName, err) + } + + slog.Debug("Message published to queue", "queue", queueName) + return nil +} + +// Close closes the RabbitMQ connection (no-op since we use static functions) +func (r *RabbitMQService) Close() error { + return nil +} diff --git a/sirius-api/services/valkey_monitor_service.go b/sirius-api/services/valkey_monitor_service.go new file mode 100644 index 0000000..3db25ec --- /dev/null +++ b/sirius-api/services/valkey_monitor_service.go @@ -0,0 +1,275 @@ +package services + +import ( + "context" + "encoding/json" + "fmt" + + "github.com/SiriusScan/go-api/sirius/store" +) + +// ValkeyMonitorService handles reading system metrics from Valkey +type ValkeyMonitorService struct { + valkeyStore store.KVStore +} + +// SystemMetrics represents system resource metrics from Valkey +type SystemMetrics struct { + ContainerName string `json:"container_name"` + Timestamp string `json:"timestamp"` + CPUPercent float64 `json:"cpu_percent"` + MemoryUsage int64 `json:"memory_usage_bytes"` + MemoryPercent float64 `json:"memory_percent"` + NetworkRx int64 `json:"network_rx_bytes"` + NetworkTx int64 `json:"network_tx_bytes"` + DiskRead int64 `json:"disk_read_bytes"` + DiskWrite int64 `json:"disk_write_bytes"` + DiskUsage int64 `json:"disk_usage_bytes"` + DiskTotal int64 `json:"disk_total_bytes"` + DiskPercent float64 `json:"disk_percent"` + ProcessCount int `json:"process_count"` + FileDescriptors int `json:"file_descriptors"` + LoadAverage1m float64 `json:"load_average_1m"` + LoadAverage5m float64 `json:"load_average_5m"` + LoadAverage15m float64 `json:"load_average_15m"` + Uptime int64 `json:"uptime_seconds"` + Status string `json:"status"` +} + +// ValkeyContainerLog represents a container log entry from Valkey +type ValkeyContainerLog struct { + ContainerName string `json:"container_name"` + Timestamp string `json:"timestamp"` + Level string `json:"level"` + Message string `json:"message"` +} + +// ValkeyContainerResource represents container resource usage for API response +type ValkeyContainerResource struct { + Name string `json:"name"` + CPUPercent float64 `json:"cpu_percent"` + MemoryUsage string `json:"memory_usage"` + MemoryPercent float64 `json:"memory_percent"` + NetworkIO string `json:"network_io"` + BlockIO string `json:"block_io"` + DiskUsage string `json:"disk_usage"` + DiskPercent float64 `json:"disk_percent"` + ProcessCount int `json:"process_count"` + FileDescriptors int `json:"file_descriptors"` + LoadAverage1m float64 `json:"load_average_1m"` + LoadAverage5m float64 `json:"load_average_5m"` + LoadAverage15m float64 `json:"load_average_15m"` + Uptime string `json:"uptime"` + Status string `json:"status"` +} + +// ValkeySystemResourcesSummary represents system resource summary +type ValkeySystemResourcesSummary struct { + TotalContainers int `json:"total_containers"` + RunningContainers int `json:"running_containers"` + TotalCPUPercent float64 `json:"total_cpu_percent"` + TotalMemoryUsage string `json:"total_memory_usage"` + TotalMemoryPercent float64 `json:"total_memory_percent"` +} + +// NewValkeyMonitorService creates a new Valkey monitor service +func NewValkeyMonitorService() (*ValkeyMonitorService, error) { + valkeyStore, err := store.NewValkeyStore() + if err != nil { + return nil, fmt.Errorf("failed to create Valkey store: %w", err) + } + + return &ValkeyMonitorService{ + valkeyStore: valkeyStore, + }, nil +} + +// GetContainerResources retrieves system resources from Valkey +func (v *ValkeyMonitorService) GetContainerResources(ctx context.Context) ([]ValkeyContainerResource, ValkeySystemResourcesSummary, error) { + // Get all container names + containerNames := []string{"sirius-api", "sirius-ui", "sirius-engine", "sirius-postgres", "sirius-valkey", "sirius-rabbitmq"} + + var resources []ValkeyContainerResource + var totalCPU float64 + var totalMemory float64 + var totalMemoryBytes int64 + var runningCount int + + for _, containerName := range containerNames { + // Get metrics from Valkey + metrics, err := v.getContainerMetrics(ctx, containerName) + if err != nil { + // If no metrics found, create a default entry + resource := ValkeyContainerResource{ + Name: containerName, + CPUPercent: 0.0, + MemoryUsage: "0B", + MemoryPercent: 0.0, + NetworkIO: "0B / 0B", + BlockIO: "0B / 0B", + DiskUsage: "0B / 0B", + DiskPercent: 0.0, + ProcessCount: 0, + FileDescriptors: 0, + LoadAverage1m: 0.0, + LoadAverage5m: 0.0, + LoadAverage15m: 0.0, + Uptime: "0s", + Status: "unknown", + } + resources = append(resources, resource) + continue + } + + // Convert SystemMetrics to ValkeyContainerResource + resource := ValkeyContainerResource{ + Name: metrics.ContainerName, + CPUPercent: metrics.CPUPercent, + MemoryUsage: v.formatBytes(metrics.MemoryUsage), + MemoryPercent: metrics.MemoryPercent, + NetworkIO: fmt.Sprintf("%s / %s", v.formatBytes(metrics.NetworkRx), v.formatBytes(metrics.NetworkTx)), + BlockIO: fmt.Sprintf("%s / %s", v.formatBytes(metrics.DiskRead), v.formatBytes(metrics.DiskWrite)), + DiskUsage: fmt.Sprintf("%s / %s", v.formatBytes(metrics.DiskUsage), v.formatBytes(metrics.DiskTotal)), + DiskPercent: metrics.DiskPercent, + ProcessCount: metrics.ProcessCount, + FileDescriptors: metrics.FileDescriptors, + LoadAverage1m: metrics.LoadAverage1m, + LoadAverage5m: metrics.LoadAverage5m, + LoadAverage15m: metrics.LoadAverage15m, + Uptime: v.formatUptime(metrics.Uptime), + Status: metrics.Status, + } + resources = append(resources, resource) + + // Update totals + if metrics.Status == "running" { + totalCPU += metrics.CPUPercent + totalMemory += metrics.MemoryPercent + totalMemoryBytes += metrics.MemoryUsage + runningCount++ + } + } + + summary := ValkeySystemResourcesSummary{ + TotalContainers: len(containerNames), + RunningContainers: runningCount, + TotalCPUPercent: totalCPU, + TotalMemoryUsage: v.formatBytes(totalMemoryBytes), + TotalMemoryPercent: totalMemory, + } + + return resources, summary, nil +} + +// GetDockerLogs retrieves container logs from Valkey +func (v *ValkeyMonitorService) GetDockerLogs(ctx context.Context, containerNameFilter string, lines int) ([]ValkeyContainerLog, []string, error) { + // Get all log keys from Valkey + pattern := "system:logs:*" + keys, err := v.valkeyStore.ListKeys(ctx, pattern) + if err != nil { + return nil, nil, fmt.Errorf("failed to list log keys: %w", err) + } + + var logs []ValkeyContainerLog + containerNames := []string{"sirius-api", "sirius-ui", "sirius-engine", "sirius-postgres", "sirius-valkey", "sirius-rabbitmq"} + + // Process each log key + for _, key := range keys { + if lines > 0 && len(logs) >= lines { + break + } + + // Get log entry from Valkey + response, err := v.valkeyStore.GetValue(ctx, key) + if err != nil { + continue // Skip invalid entries + } + + // Parse log entry + var logEntry ValkeyContainerLog + if err := json.Unmarshal([]byte(response.Message.Value), &logEntry); err != nil { + continue // Skip invalid JSON + } + + // Apply container filter + if containerNameFilter != "all" && containerNameFilter != logEntry.ContainerName { + continue + } + + logs = append(logs, logEntry) + } + + // Sort logs by timestamp (most recent first) - simple string comparison for ISO timestamps + for i := 0; i < len(logs); i++ { + for j := i + 1; j < len(logs); j++ { + if logs[i].Timestamp < logs[j].Timestamp { + logs[i], logs[j] = logs[j], logs[i] + } + } + } + + // Limit results + if lines > 0 && len(logs) > lines { + logs = logs[:lines] + } + + return logs, containerNames, nil +} + +// getContainerMetrics retrieves metrics for a specific container from Valkey +func (v *ValkeyMonitorService) getContainerMetrics(ctx context.Context, containerName string) (*SystemMetrics, error) { + key := fmt.Sprintf("system:metrics:%s", containerName) + + response, err := v.valkeyStore.GetValue(ctx, key) + if err != nil { + return nil, fmt.Errorf("failed to get metrics for %s: %w", containerName, err) + } + + var metrics SystemMetrics + if err := json.Unmarshal([]byte(response.Message.Value), &metrics); err != nil { + return nil, fmt.Errorf("failed to unmarshal metrics for %s: %w", containerName, err) + } + + return &metrics, nil +} + +// formatBytes formats bytes into human-readable format +func (v *ValkeyMonitorService) formatBytes(bytes int64) string { + if bytes == 0 { + return "0B" + } + + sizes := []string{"B", "KB", "MB", "GB", "TB"} + i := 0 + fBytes := float64(bytes) + + for fBytes >= 1024 && i < len(sizes)-1 { + fBytes /= 1024 + i++ + } + + return fmt.Sprintf("%.1f%s", fBytes, sizes[i]) +} + +// formatUptime formats uptime in seconds to human-readable format +func (v *ValkeyMonitorService) formatUptime(seconds int64) string { + if seconds < 60 { + return fmt.Sprintf("%ds", seconds) + } else if seconds < 3600 { + return fmt.Sprintf("%dm %ds", seconds/60, seconds%60) + } else if seconds < 86400 { + return fmt.Sprintf("%dh %dm", seconds/3600, (seconds%3600)/60) + } else { + return fmt.Sprintf("%dd %dh", seconds/86400, (seconds%86400)/3600) + } +} + +// GetValkeyStore returns the Valkey store for external use +func (v *ValkeyMonitorService) GetValkeyStore() store.KVStore { + return v.valkeyStore +} + +// Close closes the Valkey connection +func (v *ValkeyMonitorService) Close() error { + return v.valkeyStore.Close() +} diff --git a/sirius-api/start-dev.sh b/sirius-api/start-dev.sh new file mode 100644 index 0000000..db1e6ad --- /dev/null +++ b/sirius-api/start-dev.sh @@ -0,0 +1,48 @@ +#!/bin/sh + +echo "🚀 Starting Sirius API Development Server..." + +# Start system monitor if available +if [ -d "/system-monitor" ] && [ -f "/system-monitor/main.go" ]; then + echo "📊 Starting System Monitor..." + cd /system-monitor + CONTAINER_NAME=sirius-api go run main.go >> /tmp/system-monitor.log 2>&1 & + SYSTEM_MONITOR_PID=$! + echo "✅ System Monitor started with PID: $SYSTEM_MONITOR_PID" +else + echo "⚠️ System Monitor not found at /system-monitor, skipping..." +fi + +# Start app administrator if available +if [ -d "/app-administrator" ] && [ -f "/app-administrator/main.go" ]; then + echo "🔧 Starting App Administrator..." + cd /app-administrator + CONTAINER_NAME=sirius-api go run main.go >> /tmp/administrator.log 2>&1 & + ADMINISTRATOR_PID=$! + echo "✅ App Administrator started with PID: $ADMINISTRATOR_PID" +else + echo "⚠️ App Administrator not found at /app-administrator, skipping..." +fi + +# Start the main API +echo "🎯 Starting Sirius API..." +cd /api || { echo "❌ Failed to change to /api directory"; exit 1; } +if [ ! -f "go.mod" ]; then + echo "❌ go.mod not found in /api, waiting for volume mount..." + sleep 2 + if [ ! -f "go.mod" ]; then + echo "❌ go.mod still not found after wait, aborting" + exit 1 + fi +fi +if [ ! -f "main.go" ]; then + echo "❌ main.go not found in /api, waiting for volume mount..." + sleep 2 + if [ ! -f "main.go" ]; then + echo "❌ main.go still not found after wait, aborting" + exit 1 + fi +fi +go mod tidy +exec go run main.go + diff --git a/sirius-engine/Dockerfile b/sirius-engine/Dockerfile new file mode 100644 index 0000000..ac6241f --- /dev/null +++ b/sirius-engine/Dockerfile @@ -0,0 +1,368 @@ +# Multi-stage Dockerfile for sirius-engine +# +# No external GHCR base images: utility Go binaries and engine runtime tools +# (Nmap from source, RustScan, PowerShell) are built in this file. +# +# Stages: utility-go-binaries, nmap-builder, engine-runtime-base, builder, +# development, runtime. + +# ───────────────────────────────────────────────────────────────────────────── +# Utility binaries: system-monitor + administrator +# ───────────────────────────────────────────────────────────────────────────── +FROM golang:1.24-alpine AS utility-go-binaries + +RUN apk add --no-cache git ca-certificates tzdata + +RUN git clone https://github.com/SiriusScan/app-system-monitor.git /tmp/system-monitor && \ + cd /tmp/system-monitor && \ + go mod download && \ + CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o /usr/local/bin/system-monitor main.go && \ + rm -rf /tmp/system-monitor + +RUN git clone https://github.com/SiriusScan/app-administrator.git /tmp/administrator && \ + cd /tmp/administrator && \ + go mod download && \ + CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o /usr/local/bin/administrator main.go && \ + rm -rf /tmp/administrator + +# ───────────────────────────────────────────────────────────────────────────── +# Nmap compiled from source (build stage only; not shipped in final layers) +# ───────────────────────────────────────────────────────────────────────────── +FROM ubuntu:22.04 AS nmap-builder + +ENV DEBIAN_FRONTEND=noninteractive + +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + build-essential \ + libpcap-dev \ + libssl-dev \ + libssh-dev \ + libicu-dev \ + automake \ + autoconf \ + libtool \ + perl \ + wget \ + ca-certificates \ + && rm -rf /var/lib/apt/lists/* + +RUN cd /tmp && \ + wget -q https://nmap.org/dist/nmap-7.95.tar.bz2 && \ + tar xjf nmap-7.95.tar.bz2 && \ + cd nmap-7.95 && \ + touch aclocal.m4 configure Makefile.in config.h.in && \ + find . -name Makefile.in -exec touch {} \; && \ + ./configure --without-zenmap --without-nmap-update --without-ndiff && \ + make -j$(nproc) && \ + make install && \ + cd / && \ + rm -rf /tmp/nmap-7.95 /tmp/nmap-7.95.tar.bz2 + +# ───────────────────────────────────────────────────────────────────────────── +# Engine runtime base: Nmap binaries + RustScan + PowerShell + runtime packages +# ───────────────────────────────────────────────────────────────────────────── +FROM ubuntu:22.04 AS engine-runtime-base + +ENV DEBIAN_FRONTEND=noninteractive + +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + git \ + ca-certificates \ + tzdata \ + libpcap0.8 \ + libpcap-dev \ + postgresql-client \ + libicu70 \ + libssl3 \ + libssh-4 \ + curl \ + wget \ + bash \ + dos2unix \ + unzip \ + procps \ + && rm -rf /var/lib/apt/lists/* + +COPY --from=nmap-builder /usr/local/bin/nmap /usr/local/bin/nmap +COPY --from=nmap-builder /usr/local/share/nmap /usr/local/share/nmap + +RUN ARCH=$(uname -m) && \ + case "$ARCH" in \ + "aarch64") \ + wget -q https://github.com/bee-san/RustScan/releases/latest/download/aarch64-linux-rustscan.zip && \ + unzip aarch64-linux-rustscan.zip && \ + mv rustscan /usr/local/bin/ && \ + chmod +x /usr/local/bin/rustscan && \ + rm aarch64-linux-rustscan.zip \ + ;; \ + "x86_64") \ + wget -q https://github.com/bee-san/RustScan/releases/latest/download/x86_64-linux-rustscan.tar.gz.zip && \ + unzip x86_64-linux-rustscan.tar.gz.zip && \ + tar -xzf x86_64-linux-rustscan.tar.gz && \ + mv rustscan /usr/local/bin/ && \ + chmod +x /usr/local/bin/rustscan && \ + rm x86_64-linux-rustscan.tar.gz.zip x86_64-linux-rustscan.tar.gz \ + ;; \ + *) echo "Unsupported architecture: $ARCH" && exit 1 ;; \ + esac + +RUN mkdir -p /opt/microsoft/powershell && \ + cd /opt/microsoft/powershell && \ + ARCH=$(uname -m) && \ + case "$ARCH" in \ + "aarch64") \ + wget -q https://github.com/PowerShell/PowerShell/releases/download/v7.4.6/powershell-7.4.6-linux-arm64.tar.gz && \ + tar -xf powershell-7.4.6-linux-arm64.tar.gz && \ + rm powershell-7.4.6-linux-arm64.tar.gz \ + ;; \ + "x86_64") \ + wget -q https://github.com/PowerShell/PowerShell/releases/download/v7.4.6/powershell-7.4.6-linux-x64.tar.gz && \ + tar -xf powershell-7.4.6-linux-x64.tar.gz && \ + rm powershell-7.4.6-linux-x64.tar.gz \ + ;; \ + *) echo "Unsupported architecture: $ARCH" && exit 1 ;; \ + esac && \ + chmod +x /opt/microsoft/powershell/pwsh && \ + ln -s /opt/microsoft/powershell/pwsh /usr/bin/pwsh + +ENV PATH="/usr/local/bin:${PATH}" + +RUN command -v bash >/dev/null && \ + command -v curl >/dev/null && \ + command -v nmap >/dev/null && \ + command -v rustscan >/dev/null && \ + command -v pwsh >/dev/null && \ + command -v psql >/dev/null && \ + command -v pkill >/dev/null + +# ───────────────────────────────────────────────────────────────────────────── +# Builder: engine Go services (CGO + libpcap for app-scanner) +# ───────────────────────────────────────────────────────────────────────────── +FROM golang:1.24-bullseye AS builder + +WORKDIR /build + +RUN apt-get update && \ + DEBIAN_FRONTEND=noninteractive apt-get install -y \ + git \ + ca-certificates \ + tzdata \ + build-essential \ + libpcap-dev \ + && rm -rf /var/lib/apt/lists/* + +# Build arguments for submodule commit SHAs. +# +# Pin policy (enforced by .github/workflows/check-pin-consistency.yml): +# - These ARG defaults are the canonical pins. CI fallbacks in +# .github/workflows/ci.yml (build-engine, build-api) MUST match. +# - Floating refs (main/master) are forbidden; use a full SHA or a tag. +# - When a minor-project is bumped, update the ARG default here, the +# CI fallback, and SHA-AUDIT-2026-04.md (or its successor) in one PR. +# +# Audit doc: documentation/dev-notes/SHA-AUDIT-2026-04.md +ARG GO_API_COMMIT_SHA=v0.0.18 +ARG APP_SCANNER_COMMIT_SHA=a031480cc7e0dc4a1cb09bdcfafedd89fbc61dfd +ARG APP_TERMINAL_COMMIT_SHA=5745e43ca1f2ad3936a02a51cc77bfcf33ee95c1 +ARG SIRIUS_NSE_COMMIT_SHA=a58e8c5330b49bd8f4e93c27e340c43c1fa89fa9 +ARG APP_AGENT_COMMIT_SHA=9311f3805db9cc08740f1b588b6f3bff9191c9dd +ARG PINGPP_COMMIT_SHA=9508a16c40a49746feb7cab4b8c1c358246169b0 + +WORKDIR /repos + +# Clone go-api (needed as a dependency by other components) +RUN git clone https://github.com/SiriusScan/go-api.git && \ + cd go-api && \ + git checkout ${GO_API_COMMIT_SHA} && \ + go mod tidy + +# Clone ping++ (fingerprinting engine, needed by app-scanner) +RUN git clone https://github.com/SiriusScan/pingpp.git "ping++" && \ + cd "ping++" && \ + git checkout ${PINGPP_COMMIT_SHA} + +# Clone and build app-scanner (CGO_ENABLED=1, requires libpcap). +# All previous inline sed patches against internal/scan/manager.go have been +# upstreamed in app-scanner@ca1ef2f. See documentation/dev-notes/SHA-AUDIT-2026-04.md. +RUN git clone https://github.com/SiriusScan/app-scanner.git && \ + cd app-scanner && \ + git checkout ${APP_SCANNER_COMMIT_SHA} && \ + go mod download && \ + CGO_ENABLED=1 GOOS=linux go build -ldflags="-w -s" -o scanner main.go + +# Clone and build app-terminal +RUN git clone https://github.com/SiriusScan/app-terminal.git && \ + cd app-terminal && \ + git checkout ${APP_TERMINAL_COMMIT_SHA} && \ + go mod download && \ + CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o terminal cmd/main.go + +# Clone and build app-agent +RUN git clone https://github.com/SiriusScan/app-agent.git && \ + cd app-agent && \ + git checkout ${APP_AGENT_COMMIT_SHA} && \ + go mod download && \ + CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o agent cmd/agent/main.go && \ + CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o server cmd/server/main.go + +# Clone sirius-nse (Nmap script library, no compilation needed) +RUN git clone https://github.com/SiriusScan/sirius-nse.git && \ + cd sirius-nse && \ + git checkout ${SIRIUS_NSE_COMMIT_SHA} + +# ───────────────────────────────────────────────────────────────────────────── +# Development: hot-reload on engine-runtime-base +# ───────────────────────────────────────────────────────────────────────────── +FROM engine-runtime-base AS development + +WORKDIR /engine + +# Install Go 1.24 for hot-reload development (air requires Go 1.20+) +# Ubuntu 22.04's apt golang is 1.18; air's hugo dep needs 1.20+ +RUN ARCH=$(uname -m) && \ + case "$ARCH" in \ + aarch64|arm64) GOARCH=arm64 ;; \ + x86_64|amd64) GOARCH=amd64 ;; \ + *) echo "Unsupported: $ARCH" && exit 1 ;; \ + esac && \ + wget -q "https://go.dev/dl/go1.24.0.linux-${GOARCH}.tar.gz" -O /tmp/go.tar.gz && \ + rm -rf /usr/local/go && tar -C /usr/local -xzf /tmp/go.tar.gz && \ + rm /tmp/go.tar.gz && \ + ln -sf /usr/local/go/bin/go /usr/bin/go + +ENV PATH="/usr/local/go/bin:${PATH}" + +# Install a C toolchain so Air can rebuild app-scanner in-container. +# app-scanner pulls libpcap via cgo (CGO_ENABLED=1 in app-scanner/.air.toml); +# the runtime stage only ships libpcap.so, but the dev stage needs the +# full compiler + headers so `go build` succeeds on every save. Keeping +# this in the dev stage only avoids bloating the production runtime. +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + build-essential \ + libpcap-dev \ + && rm -rf /var/lib/apt/lists/* + +# Install air for live reloading. go install drops the binary in +# $GOPATH/bin (default /root/go/bin) which is not on PATH unless we add +# it explicitly. Without this, start-enhanced.sh's `air &` invocations +# silently fall back to broken behavior in dev mode. +RUN go install github.com/air-verse/air@v1.52.3 +ENV PATH="/root/go/bin:${PATH}" + +# Set up NSE directory structure +RUN mkdir -p /opt/sirius/nse && chmod -R 755 /opt/sirius + +# Create application directories +RUN mkdir -p /app-scanner /app-terminal /app-agent /go-api /sirius-nse /system-monitor /app-administrator + +COPY --from=utility-go-binaries /usr/local/bin/system-monitor /system-monitor/system-monitor +COPY --from=utility-go-binaries /usr/local/bin/administrator /app-administrator/administrator +RUN chmod +x /system-monitor/system-monitor /app-administrator/administrator + +# Copy built applications and repositories from builder stage (used as fallback sources) +COPY --from=builder /repos/app-scanner /app-scanner-src/ +COPY --from=builder /repos/app-terminal /app-terminal-src/ +COPY --from=builder /repos/app-agent /app-agent-src/ +COPY --from=builder /repos/go-api /go-api/ +COPY --from=builder /repos/sirius-nse /sirius-nse/ + +# Ensure sirius-nse is readable +RUN chmod -R 755 /sirius-nse + +# Remove default Nmap scripts and symlink to sirius-nse +RUN rm -rf /usr/local/share/nmap/scripts && \ + ln -sf /sirius-nse/scripts /usr/local/share/nmap/scripts + +# Copy startup scripts. Per-service .air.toml lives inside each minor- +# project (app-agent, app-terminal, app-scanner) and is consumed via the +# dev-mode bind mount; the engine no longer ships its own orphan copy. +COPY start.sh /start.sh +COPY start-enhanced.sh /start-enhanced.sh + +# Fix line endings and validate startup scripts +RUN dos2unix /start.sh /start-enhanced.sh && \ + chmod +x /start.sh /start-enhanced.sh && \ + /bin/bash -n /start-enhanced.sh + +ENV GO_ENV=development +ENV PATH="/root/.cargo/bin:/usr/local/bin:${PATH}" + +EXPOSE 5174 50051 + +ENTRYPOINT ["/start-enhanced.sh"] + +# ───────────────────────────────────────────────────────────────────────────── +# Runtime (production) +# ───────────────────────────────────────────────────────────────────────────── +FROM engine-runtime-base AS runtime + +WORKDIR /engine + +# Set up NSE directory structure +RUN mkdir -p /opt/sirius/nse && chmod -R 755 /opt/sirius + +# Create application directories +RUN mkdir -p /app-scanner /app-terminal /app-agent /go-api /sirius-nse /system-monitor /app-administrator + +COPY --from=utility-go-binaries /usr/local/bin/system-monitor /system-monitor/system-monitor +COPY --from=utility-go-binaries /usr/local/bin/administrator /app-administrator/administrator +RUN chmod +x /system-monitor/system-monitor /app-administrator/administrator + +# Copy compiled binaries from builder stage +COPY --from=builder /repos/app-scanner/scanner /app-scanner/ +COPY --from=builder /repos/app-scanner /app-scanner-src/ +COPY --from=builder /repos/app-terminal/terminal /app-terminal/ +COPY --from=builder /repos/app-terminal /app-terminal-src/ +COPY --from=builder /repos/app-agent/agent /app-agent/ +COPY --from=builder /repos/app-agent/server /app-agent/ +COPY --from=builder /repos/app-agent /app-agent-src/ +COPY --from=builder /repos/go-api /go-api/ +COPY --from=builder /repos/sirius-nse /sirius-nse/ + +# Ensure sirius-nse is readable +RUN chmod -R 755 /sirius-nse + +# Remove default Nmap scripts and symlink to sirius-nse +RUN rm -rf /usr/local/share/nmap/scripts && \ + ln -sf /sirius-nse/scripts /usr/local/share/nmap/scripts + +# Enforce runtime startup contract +RUN command -v bash >/dev/null && \ + command -v curl >/dev/null && \ + command -v psql >/dev/null && \ + command -v pkill >/dev/null && \ + command -v nmap >/dev/null && \ + command -v rustscan >/dev/null && \ + command -v pwsh >/dev/null + +# Copy startup scripts. The runtime image does not ship a top-level +# .air.toml; production builds run pre-compiled binaries (see +# start-enhanced.sh), and dev-mode hot reload uses the per-service +# .air.toml provided by each bind-mounted minor-project. +COPY start.sh /start.sh +COPY start-enhanced.sh /start-enhanced.sh + +# Fix line endings and validate startup scripts +RUN dos2unix /start.sh /start-enhanced.sh && \ + chmod +x /start.sh /start-enhanced.sh && \ + /bin/bash -n /start-enhanced.sh + +# Non-root user for security +RUN groupadd -r sirius && useradd -r -g sirius sirius + +# Change ownership for non-root execution +RUN chown -R sirius:sirius \ + /engine /app-scanner /app-terminal /app-agent /go-api \ + /sirius-nse /opt/sirius /system-monitor /app-administrator + +USER sirius + +EXPOSE 5174 50051 + +ENV GO_ENV=production +ENV PATH="/usr/local/bin:${PATH}" + +ENTRYPOINT ["/start-enhanced.sh"] diff --git a/sirius-engine/apps/app-agent/go.mod b/sirius-engine/apps/app-agent/go.mod new file mode 100644 index 0000000..326bb61 --- /dev/null +++ b/sirius-engine/apps/app-agent/go.mod @@ -0,0 +1,10 @@ +module app-agent + +go 1.23 + +require ( + github.com/SiriusScan/go-api v0.0.6-0.20250609175937-8fedfb0c194c + github.com/valkey-io/valkey-go v1.0.59 + google.golang.org/grpc v1.71.1 + google.golang.org/protobuf v1.36.6 +) diff --git a/sirius-engine/apps/app-scanner/go.mod b/sirius-engine/apps/app-scanner/go.mod new file mode 100644 index 0000000..b0a3144 --- /dev/null +++ b/sirius-engine/apps/app-scanner/go.mod @@ -0,0 +1,14 @@ +module github.com/SiriusScan/app-scanner + +go 1.22.0 + +toolchain go1.24.1 + +require github.com/SiriusScan/go-api v0.0.0 + +require ( + github.com/valkey-io/valkey-go v1.0.54 // indirect + golang.org/x/sys v0.29.0 // indirect +) + +replace github.com/SiriusScan/go-api => ../../../go-api diff --git a/sirius-engine/apps/app-scanner/manifest.json b/sirius-engine/apps/app-scanner/manifest.json new file mode 100644 index 0000000..0cdac6c --- /dev/null +++ b/sirius-engine/apps/app-scanner/manifest.json @@ -0,0 +1,8 @@ +{ + "repositories": [ + { + "name": "sirius-nse", + "url": "https://github.com/SiriusScan/sirius-nse.git" + } + ] +} \ No newline at end of file diff --git a/sirius-engine/apps/app-terminal/go.mod b/sirius-engine/apps/app-terminal/go.mod new file mode 100644 index 0000000..61044fb --- /dev/null +++ b/sirius-engine/apps/app-terminal/go.mod @@ -0,0 +1,10 @@ +module app-terminal + +go 1.23 + +require ( + github.com/SiriusScan/go-api v0.0.6-0.20250609175937-8fedfb0c194c + github.com/valkey-io/valkey-go v1.0.59 + google.golang.org/grpc v1.71.1 + google.golang.org/protobuf v1.36.6 +) diff --git a/sirius-engine/custom-manifest.json b/sirius-engine/custom-manifest.json new file mode 100644 index 0000000..84c184b --- /dev/null +++ b/sirius-engine/custom-manifest.json @@ -0,0 +1,9 @@ +{ + "version": "1.0", + "last_updated": "2025-07-23T18:41:05.83280634Z", + "templates": [], + "scripts": [], + "total_templates": 0, + "total_scripts": 0, + "created_by": "sirius-agent-server" +} \ No newline at end of file diff --git a/sirius-engine/go.mod b/sirius-engine/go.mod new file mode 100644 index 0000000..ada4688 --- /dev/null +++ b/sirius-engine/go.mod @@ -0,0 +1,3 @@ +module github.com/0sm0s1z/Sirius-Scan + +go 1.20 diff --git a/sirius-engine/main.go b/sirius-engine/main.go new file mode 100644 index 0000000..2240776 --- /dev/null +++ b/sirius-engine/main.go @@ -0,0 +1,47 @@ +package main + +import ( + "encoding/json" + "fmt" + "os" + "os/exec" +) + +type Manifest struct { + Services []string `json:"services"` +} + +func loadManifest() Manifest { + file, _ := os.ReadFile("./manifest.json") + var manifest Manifest + json.Unmarshal(file, &manifest) + return manifest +} + +func executeService(serviceName string) { + cmd := exec.Command("./apps/bin/" + serviceName) + err := cmd.Run() + if err != nil { + fmt.Printf("Error executing service %s: %s\n", serviceName, err) + } +} + +func main() { + fmt.Println("Sirius Engine v3 is starting up...") + + // Load manifest.json + manifest := loadManifest() + + // Always execute the core service first + // executeService("core") + + // Execute other services + for _, service := range manifest.Services { + fmt.Printf("Starting service: %s\n", service) + go executeService(service) // Run services concurrently + } + + // TODO: Add logging, monitoring, and other functionalities + + fmt.Println("Sirius Engine is running...") +} diff --git a/sirius-engine/sirius-engine b/sirius-engine/sirius-engine new file mode 100755 index 0000000..6900ec2 Binary files /dev/null and b/sirius-engine/sirius-engine differ diff --git a/sirius-engine/start-enhanced.sh b/sirius-engine/start-enhanced.sh new file mode 100755 index 0000000..0edd511 --- /dev/null +++ b/sirius-engine/start-enhanced.sh @@ -0,0 +1,413 @@ +#!/bin/bash + +# Enhanced startup script for sirius-engine v2.0 - Updated 2025-06-08T03:30:00Z +# Handles both development (with volume mounts) and production (using built-in repos) + +# Function to cleanup child processes +cleanup() { + echo "Shutting down services..." + pkill -P $$ + exit 0 +} + +# Function to check if a service is running +check_service() { + local service_name=$1 + local pid=$2 + if ! kill -0 $pid 2>/dev/null; then + echo "$service_name failed to start or crashed" + cleanup + fi +} + +# Function to check if binary exists in directory +has_binary() { + local service_path=$1 + local binary_name=$2 + [ -f "$service_path/$binary_name" ] && [ -x "$service_path/$binary_name" ] +} + +# Function to check if `air` (live-reload tool) is available on PATH. +# Older sirius-engine images installed air to /root/go/bin without +# adding that directory to PATH. The current Dockerfile fixes this, +# but we keep the fallback so a dev volume-mounted into an older image +# still gets live reload via the absolute path. +has_air() { + command -v air >/dev/null 2>&1 || [ -x /root/go/bin/air ] +} + +# Run `air` regardless of whether it is on PATH. +run_air() { + if command -v air >/dev/null 2>&1; then + air "$@" + else + /root/go/bin/air "$@" + fi +} + +# Function to determine the correct path for a service +get_service_path() { + local service_name=$1 + local mount_path="/app-$service_name" + local src_path="/app-$service_name-src" + local built_path="/$service_name" + + # Check if volume mount exists and has Go files (development mode with volume mount) + if [ -d "$mount_path" ] && [ -f "$mount_path/go.mod" ]; then + echo "$mount_path" + # Check if source directory exists (development mode without volume mount) + elif [ -d "$src_path" ] && [ -f "$src_path/go.mod" ]; then + echo "$src_path" + # Check if production binary exists + elif [ -d "$mount_path" ] && has_binary "$mount_path" "$service_name"; then + echo "$mount_path" + # Otherwise use built-in repository (development fallback) + elif [ -d "$built_path" ] && [ -f "$built_path/go.mod" ]; then + echo "$built_path" + else + echo "" + fi +} + +# Trap SIGTERM and SIGINT +trap cleanup SIGTERM SIGINT + +echo "Starting Sirius Engine services..." +echo "Environment: ${GO_ENV:-production}" + +# The mounted secret file is the single runtime source of truth for the +# internal API key. Export it for child processes that still expect env access. +if [ -z "${SIRIUS_API_KEY_FILE:-}" ]; then + echo "Error: SIRIUS_API_KEY_FILE is required and must point to a readable secret file." + exit 1 +fi +if [ ! -r "$SIRIUS_API_KEY_FILE" ]; then + echo "Error: internal API key file is not readable: $SIRIUS_API_KEY_FILE" + exit 1 +fi + +SIRIUS_API_KEY="$(tr -d '\r\n' < "$SIRIUS_API_KEY_FILE")" +if [ -z "$SIRIUS_API_KEY" ]; then + echo "Error: internal API key file is empty: $SIRIUS_API_KEY_FILE" + exit 1 +fi +export SIRIUS_API_KEY + +validate_required_env() { + local var_name=$1 + local value + value=$(printenv "$var_name") + if [ -z "$value" ]; then + echo "Error: required environment variable '$var_name' is not set" + exit 1 + fi +} + +validate_required_binary() { + local binary_name=$1 + local install_hint=$2 + if ! command -v "$binary_name" >/dev/null 2>&1; then + echo "Error: required runtime binary '$binary_name' is not available in sirius-engine container." + echo "$install_hint" + exit 1 + fi +} + +validate_postgres_connection() { + local max_attempts=30 + local attempt=0 + + echo "Validating PostgreSQL connectivity with runtime credentials..." + while [ "$attempt" -lt "$max_attempts" ]; do + if PGPASSWORD="$POSTGRES_PASSWORD" psql -h "$POSTGRES_HOST" -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "SELECT 1" >/dev/null 2>&1; then + echo "PostgreSQL connectivity validated." + return 0 + fi + attempt=$((attempt + 1)) + sleep 2 + done + + echo "Error: unable to connect to PostgreSQL with configured credentials." + exit 1 +} + +validate_api_key_contract() { + local max_attempts=30 + local attempt=0 + local probe_url="${SIRIUS_API_URL%/}/host/" + + echo "Validating API key contract with sirius-api at ${probe_url} ..." + + while [ "$attempt" -lt "$max_attempts" ]; do + http_status=$(curl -sS --max-time 15 -o /tmp/sirius-api-auth-probe.out -w "%{http_code}" \ + -H "X-API-Key: $SIRIUS_API_KEY" \ + "$probe_url" || true) + + # 000 = connection/DNS failure — API not reachable yet or wrong SIRIUS_API_URL + if [ "$http_status" = "000" ]; then + echo " ... waiting for sirius-api (attempt $((attempt + 1))/${max_attempts}, no TCP/HTTP response)" + attempt=$((attempt + 1)) + sleep 2 + continue + fi + + if [ "$http_status" = "401" ] || [ "$http_status" = "403" ]; then + echo "Error: sirius-engine API key was rejected by sirius-api (HTTP $http_status on GET /host/)." + echo "Check: the mounted sirius_api_key secret matches across services; avoid per-service shell overrides (use installer + recreate)." + if [ -s /tmp/sirius-api-auth-probe.out ]; then + echo "Response body (first 512 bytes):" + head -c 512 /tmp/sirius-api-auth-probe.out | tr -d '\0' || true + echo "" + fi + exit 1 + fi + + # Success: authenticated GET /host/ must return 2xx (not 404 from wrong service) + if [ "$http_status" -ge 200 ] && [ "$http_status" -lt 300 ]; then + echo "API key contract validated (HTTP $http_status)." + return 0 + fi + + # Transient proxy/gateway — retry + if [ "$http_status" = "502" ] || [ "$http_status" = "503" ] || [ "$http_status" = "504" ]; then + echo " ... waiting for sirius-api (HTTP $http_status)" + attempt=$((attempt + 1)) + sleep 2 + continue + fi + + echo "Error: unexpected HTTP $http_status from ${probe_url} (expected 2xx after auth)." + if [ -s /tmp/sirius-api-auth-probe.out ]; then + head -c 512 /tmp/sirius-api-auth-probe.out | tr -d '\0' || true + echo "" + fi + exit 1 + done + + echo "Error: unable to reach sirius-api at ${probe_url} after ${max_attempts} attempts (connection/DNS or wrong URL)." + exit 1 +} + +validate_required_env "POSTGRES_HOST" +validate_required_env "POSTGRES_USER" +validate_required_env "POSTGRES_PASSWORD" +validate_required_env "POSTGRES_DB" +validate_required_env "SIRIUS_API_URL" +# API_BASE_URL must match SIRIUS_API_URL when both are set (compose mirrors them; manual drift breaks agent/scanner) +if [ -n "${API_BASE_URL:-}" ]; then + if [ "${API_BASE_URL%/}" != "${SIRIUS_API_URL%/}" ]; then + echo "Error: API_BASE_URL must equal SIRIUS_API_URL (got API_BASE_URL=${API_BASE_URL} SIRIUS_API_URL=${SIRIUS_API_URL})." + exit 1 + fi +fi +validate_required_binary "psql" "This release image is missing PostgreSQL client tooling. Pull a corrected sirius-engine image for the active release tag and restart." +validate_postgres_connection +validate_api_key_contract + +# Start system monitor if available +if [ -d "/system-monitor" ]; then + echo "Starting system monitor..." + cd /system-monitor + if [ "$GO_ENV" = "development" ] && [ -f "main.go" ]; then + echo "Running system monitor with go run (development mode)" + CONTAINER_NAME=sirius-engine go run main.go >> /tmp/system-monitor.log 2>&1 & + elif [ -f "./system-monitor" ] && [ -x "./system-monitor" ]; then + echo "Running system monitor binary (production mode)" + CONTAINER_NAME=sirius-engine ./system-monitor >> /tmp/system-monitor.log 2>&1 & + else + echo "Error: System monitor not found (neither main.go nor binary)" + exit 1 + fi + SYSTEM_MONITOR_PID=$! + sleep 2 + # Check if system monitor started, but don't fail if it didn't + if ! kill -0 $SYSTEM_MONITOR_PID 2>/dev/null; then + echo "Warning: System Monitor failed to start, but continuing with other services" + SYSTEM_MONITOR_PID="" + else + echo "System monitor started with PID: $SYSTEM_MONITOR_PID" + fi +else + echo "Warning: System monitor directory not found" +fi + +# Start app administrator if available +if [ -d "/app-administrator" ]; then + echo "Starting app administrator..." + cd /app-administrator + if [ "$GO_ENV" = "development" ] && [ -f "main.go" ]; then + echo "Running app administrator with go run (development mode)" + CONTAINER_NAME=sirius-engine go run main.go >> /tmp/administrator.log 2>&1 & + elif [ -f "./administrator" ] && [ -x "./administrator" ]; then + echo "Running app administrator binary (production mode)" + CONTAINER_NAME=sirius-engine ./administrator >> /tmp/administrator.log 2>&1 & + else + echo "Error: App administrator not found (neither main.go nor binary)" + exit 1 + fi + ADMINISTRATOR_PID=$! + sleep 1 + # Check if app administrator started, but don't fail if it didn't + if ! kill -0 $ADMINISTRATOR_PID 2>/dev/null; then + echo "Warning: App Administrator failed to start, but continuing with other services" + ADMINISTRATOR_PID="" + else + echo "App administrator started with PID: $ADMINISTRATOR_PID" + fi +else + echo "Warning: App administrator directory not found" +fi + +# Determine service paths +SCANNER_PATH=$(get_service_path "scanner") +TERMINAL_PATH=$(get_service_path "terminal") +AGENT_PATH=$(get_service_path "agent") + +echo "Service paths determined:" +echo " Scanner: $SCANNER_PATH" +echo " Terminal: $TERMINAL_PATH" +echo " Agent: $AGENT_PATH" + +# Start scanner service if path is available (non-fatal if it fails) +if [ -n "$SCANNER_PATH" ]; then + cd "$SCANNER_PATH" + echo "Starting scanner service from $SCANNER_PATH..." + if [ "$GO_ENV" = "development" ]; then + # Use air for hot reload if .air.toml exists AND air is installed + if [ -f ".air.toml" ] && has_air; then + echo "Running scanner with air (hot reload enabled)" + run_air & + elif [ -f ".air.toml" ]; then + echo "Warning: scanner has .air.toml but 'air' is not installed; falling back to go run" + go run main.go & + else + echo "Running scanner with go run (development mode, no .air.toml)" + go run main.go & + fi + elif has_binary "$SCANNER_PATH" "scanner"; then + echo "Running production scanner binary" + ./scanner & + else + echo "Running scanner with go run (fallback)" + go run main.go & + fi + SCANNER_PID=$! + sleep 2 + # Check if scanner started, but don't fail if it didn't + if ! kill -0 $SCANNER_PID 2>/dev/null; then + echo "Warning: Scanner failed to start, but continuing with other services" + SCANNER_PID="" + fi +else + echo "Warning: Scanner service path not found" +fi + +# Start terminal service if path is available +if [ -n "$TERMINAL_PATH" ]; then + cd "$TERMINAL_PATH" + echo "Starting terminal service from $TERMINAL_PATH..." + if [ "$GO_ENV" = "development" ]; then + # Use air for hot reload if .air.toml exists AND air is installed + if [ -f ".air.toml" ] && has_air; then + echo "Running terminal with air (hot reload enabled)" + run_air & + elif [ -f ".air.toml" ]; then + echo "Warning: terminal has .air.toml but 'air' is not installed; falling back to go run" + go run cmd/main.go & + else + echo "Running terminal with go run (development mode, no .air.toml)" + go run cmd/main.go & + fi + elif has_binary "$TERMINAL_PATH" "terminal"; then + echo "Running production terminal binary" + ./terminal & + else + echo "Running terminal with go run (fallback)" + go run cmd/main.go & + fi + TERMINAL_PID=$! + sleep 2 + check_service "Terminal" $TERMINAL_PID +else + echo "Warning: Terminal service path not found" +fi + +# Start agent service if path is available +if [ -d "$AGENT_PATH" ] && [ -f "$AGENT_PATH/go.mod" ]; then + cd "$AGENT_PATH" + echo "Starting agent server from $AGENT_PATH..." + if [ "$GO_ENV" = "development" ]; then + # Use air for hot reload if .air.toml exists AND air is installed + if [ -f ".air.toml" ] && has_air; then + echo "Starting agent server with air (hot reload enabled, development mode)" + run_air < /dev/null & + AGENT_SERVER_PID=$! + elif [ -f ".air.toml" ]; then + echo "Warning: agent has .air.toml but 'air' is not installed; falling back to go run" + go run cmd/server/main.go < /dev/null & + AGENT_SERVER_PID=$! + else + echo "Starting agent server with go run (development mode, no .air.toml)" + go run cmd/server/main.go < /dev/null & + AGENT_SERVER_PID=$! + fi + else + # Keep runtime artifacts (e.g., command logs) in a writable location. + cd /engine + # Production mode - start server binary + if has_binary "$AGENT_PATH" "server"; then + echo "Running production agent server binary" + "$AGENT_PATH/server" < /dev/null & + AGENT_SERVER_PID=$! + else + echo "Running agent server with go run (fallback)" + go run "$AGENT_PATH/cmd/server/main.go" < /dev/null & + AGENT_SERVER_PID=$! + fi + fi + sleep 2 + # Check if agent server started, but don't fail if it didn't + if ! kill -0 $AGENT_SERVER_PID 2>/dev/null; then + echo "Warning: Agent Server failed to start, but continuing with other services" + AGENT_SERVER_PID="" + else + echo "Agent server started with PID: $AGENT_SERVER_PID" + fi +elif [ -d "$AGENT_PATH" ] && has_binary "$AGENT_PATH" "server"; then + cd /engine + echo "Starting agent server from $AGENT_PATH (binary only)..." + echo "Running production agent server binary" + "$AGENT_PATH/server" < /dev/null & + AGENT_SERVER_PID=$! + sleep 2 + if ! kill -0 $AGENT_SERVER_PID 2>/dev/null; then + echo "Warning: Agent Server failed to start, but continuing with other services" + AGENT_SERVER_PID="" + else + echo "Agent server started with PID: $AGENT_SERVER_PID" + fi +else + echo "Warning: Agent server path not found or invalid" +fi + +echo "Services started successfully. Monitoring..." + +# Monitor services +while true; do + if [ -n "$SYSTEM_MONITOR_PID" ]; then + check_service "System Monitor" $SYSTEM_MONITOR_PID + fi + if [ -n "$ADMINISTRATOR_PID" ]; then + check_service "App Administrator" $ADMINISTRATOR_PID + fi + if [ -n "$SCANNER_PID" ]; then + check_service "Scanner" $SCANNER_PID + fi + if [ -n "$TERMINAL_PID" ]; then + check_service "Terminal" $TERMINAL_PID + fi + if [ -n "$AGENT_SERVER_PID" ]; then + check_service "Agent Server" $AGENT_SERVER_PID + fi + sleep 5 +done diff --git a/sirius-engine/start.sh b/sirius-engine/start.sh new file mode 100755 index 0000000..d2da012 --- /dev/null +++ b/sirius-engine/start.sh @@ -0,0 +1,55 @@ +#!/bin/bash +# +# Legacy development helper: starts scanner/terminal only. +# Production and standard images use ENTRYPOINT /start-enhanced.sh (see sirius-engine/Dockerfile). + +# Function to cleanup child processes +cleanup() { + echo "Shutting down services..." + pkill -P $$ + exit 0 +} + +# Function to check if a service is running +check_service() { + local service_name=$1 + local pid=$2 + if ! kill -0 $pid 2>/dev/null; then + echo "$service_name failed to start or crashed" + cleanup + fi +} + +# Trap SIGTERM and SIGINT +trap cleanup SIGTERM SIGINT + +echo "Starting Sirius services..." + +# Start scanner service +cd /app-scanner +echo "Starting scanner service..." +go run main.go & +SCANNER_PID=$! + +# Give scanner a moment to initialize +sleep 2 +check_service "Scanner" $SCANNER_PID + +# Start terminal service +cd /app-terminal +echo "Starting terminal service..." +go run cmd/main.go & +TERMINAL_PID=$! + +# Give terminal a moment to initialize +sleep 2 +check_service "Terminal" $TERMINAL_PID + +echo "All services started. Monitoring..." + +# Monitor services +while true; do + check_service "Scanner" $SCANNER_PID + check_service "Terminal" $TERMINAL_PID + sleep 5 +done diff --git a/sirius-postgres/Dockerfile b/sirius-postgres/Dockerfile new file mode 100644 index 0000000..10d2c7f --- /dev/null +++ b/sirius-postgres/Dockerfile @@ -0,0 +1,91 @@ +# Custom PostgreSQL image with system monitoring +# +# Build system-monitor in-image so the postgres container is self-contained. +FROM golang:1.24-alpine AS go-binaries +RUN apk add --no-cache git ca-certificates tzdata && \ + git clone https://github.com/SiriusScan/app-system-monitor.git /tmp/system-monitor && \ + cd /tmp/system-monitor && \ + go mod download && \ + CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o /usr/local/bin/system-monitor main.go && \ + rm -rf /tmp/system-monitor + +FROM postgres:15-alpine + +# Copy pre-built system-monitor binary from shared base image +COPY --from=go-binaries /usr/local/bin/system-monitor /usr/local/bin/system-monitor +RUN chmod +x /usr/local/bin/system-monitor + +# Create startup script with signal handling and password reconciliation +RUN cat <<'EOF' > /usr/local/bin/start-with-monitor.sh +#!/bin/sh +set -eu + +shutdown_handler() { + echo "Received signal, forwarding to PostgreSQL..." + if [ -n "${POSTGRES_PID:-}" ]; then + kill -TERM "$POSTGRES_PID" 2>/dev/null || true + wait "$POSTGRES_PID" 2>/dev/null || true + fi + exit 0 +} + +trap shutdown_handler TERM INT + +echo "Starting PostgreSQL..." +docker-entrypoint.sh postgres & +POSTGRES_PID=$! + +PGUSER_RUNTIME="${POSTGRES_USER:-postgres}" +PGDB_RUNTIME="${POSTGRES_DB:-sirius}" + +if [ -n "${POSTGRES_PASSWORD:-}" ]; then + echo "Reconciling PostgreSQL user password from environment..." + ATTEMPT=0 + until pg_isready -h 127.0.0.1 -U "$PGUSER_RUNTIME" >/dev/null 2>&1; do + ATTEMPT=$((ATTEMPT + 1)) + if [ "$ATTEMPT" -ge 60 ]; then + echo "PostgreSQL readiness timeout during password reconciliation" + exit 1 + fi + sleep 1 + done + + ESCAPED_POSTGRES_PASSWORD=$(printf "%s" "$POSTGRES_PASSWORD" | sed "s/'/''/g") + if ! psql -v ON_ERROR_STOP=1 -U "$PGUSER_RUNTIME" -d "$PGDB_RUNTIME" \ + -c "ALTER ROLE \"$PGUSER_RUNTIME\" WITH PASSWORD '$ESCAPED_POSTGRES_PASSWORD';"; then + echo "Failed to reconcile PostgreSQL password from environment" + exit 1 + fi + + if ! PGPASSWORD="$POSTGRES_PASSWORD" psql -v ON_ERROR_STOP=1 -h 127.0.0.1 \ + -U "$PGUSER_RUNTIME" -d "$PGDB_RUNTIME" -c "SELECT 1;" >/dev/null; then + echo "Password reconciliation verification failed for PostgreSQL" + exit 1 + fi + + echo "PostgreSQL password reconciliation verified." +fi + +echo "Starting system monitor..." +CONTAINER_NAME=sirius-postgres /usr/local/bin/system-monitor >> /tmp/system-monitor.log 2>&1 & + +echo "All services started" +wait "$POSTGRES_PID" +EOF +RUN sed -i 's/\r$//' /usr/local/bin/start-with-monitor.sh && \ + chmod +x /usr/local/bin/start-with-monitor.sh +RUN test -x /usr/local/bin/start-with-monitor.sh && /bin/sh -n /usr/local/bin/start-with-monitor.sh + +# Healthcheck script — uses pg_isready which needs no password and avoids +# Docker Compose $$ escaping issues across platforms. +RUN cat <<'EOF' > /usr/local/bin/pg-healthcheck.sh +#!/bin/sh +exec pg_isready -h 127.0.0.1 -U "${POSTGRES_USER:-postgres}" -d "${POSTGRES_DB:-sirius}" +EOF +RUN chmod +x /usr/local/bin/pg-healthcheck.sh + +ENV VALKEY_HOST=sirius-valkey +ENV VALKEY_PORT=6379 +ENV CONTAINER_NAME=sirius-postgres + +ENTRYPOINT ["/usr/local/bin/start-with-monitor.sh"] diff --git a/sirius-rabbitmq/Dockerfile b/sirius-rabbitmq/Dockerfile new file mode 100644 index 0000000..dc87237 --- /dev/null +++ b/sirius-rabbitmq/Dockerfile @@ -0,0 +1,55 @@ +# Custom RabbitMQ image with system monitoring +# +# Local fallback stage for quick-start reliability: +# build system-monitor directly so compose up works even if GHCR base images +# are temporarily unavailable. +FROM golang:1.24-alpine AS go-binaries +RUN apk add --no-cache git ca-certificates tzdata && \ + git clone https://github.com/SiriusScan/app-system-monitor.git /tmp/system-monitor && \ + cd /tmp/system-monitor && \ + go mod download && \ + CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o /usr/local/bin/system-monitor main.go && \ + rm -rf /tmp/system-monitor + +FROM rabbitmq:3.12-management + +# Copy pre-built system-monitor binary from shared base image +COPY --from=go-binaries /usr/local/bin/system-monitor /usr/local/bin/system-monitor +RUN chmod +x /usr/local/bin/system-monitor + +# Create startup script with signal handling +RUN cat <<'EOF' > /usr/local/bin/start-with-monitor.sh +#!/bin/bash +set -e + +shutdown_handler() { + echo "Received signal, forwarding to RabbitMQ..." + if [ -n "${RABBITMQ_PID:-}" ]; then + kill -TERM "$RABBITMQ_PID" 2>/dev/null || true + wait "$RABBITMQ_PID" 2>/dev/null || true + fi + exit 0 +} + +trap shutdown_handler TERM INT + +echo "Starting RabbitMQ..." +docker-entrypoint.sh rabbitmq-server & +RABBITMQ_PID=$! + +echo "Waiting for RabbitMQ to be ready..." +sleep 10 + +echo "Starting system monitor..." +CONTAINER_NAME=sirius-rabbitmq /usr/local/bin/system-monitor >> /tmp/system-monitor.log 2>&1 & + +echo "All services started" +wait "$RABBITMQ_PID" +EOF +RUN chmod +x /usr/local/bin/start-with-monitor.sh + +ENV VALKEY_HOST=sirius-valkey +ENV VALKEY_PORT=6379 +ENV CONTAINER_NAME=sirius-rabbitmq + +ENTRYPOINT ["/usr/local/bin/start-with-monitor.sh"] diff --git a/sirius-ui/.env.example b/sirius-ui/.env.example new file mode 100755 index 0000000..7777dcc --- /dev/null +++ b/sirius-ui/.env.example @@ -0,0 +1,27 @@ +# 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" +INITIAL_ADMIN_PASSWORD="" +SIRIUS_API_KEY="" + +# Next Auth Discord Provider +DISCORD_CLIENT_ID="" +DISCORD_CLIENT_SECRET="" diff --git a/sirius-ui/.eslintrc.cjs b/sirius-ui/.eslintrc.cjs new file mode 100755 index 0000000..f15a4d5 --- /dev/null +++ b/sirius-ui/.eslintrc.cjs @@ -0,0 +1,30 @@ +/** @type {import("eslint").Linter.Config} */ +const config = { + parser: "@typescript-eslint/parser", + parserOptions: { + project: true, + }, + plugins: ["@typescript-eslint"], + extends: [ + "next/core-web-vitals", + "plugin:@typescript-eslint/recommended-type-checked", + "plugin:@typescript-eslint/stylistic-type-checked", + ], + rules: { + // These opinionated rules are enabled in stylistic-type-checked above. + // Feel free to reconfigure them to your own preference. + "@typescript-eslint/array-type": "off", + "@typescript-eslint/consistent-type-definitions": "off", + + "@typescript-eslint/consistent-type-imports": [ + "warn", + { + prefer: "type-imports", + fixStyle: "inline-type-imports", + }, + ], + "@typescript-eslint/no-unused-vars": ["warn", { argsIgnorePattern: "^_" }], + }, +}; + +module.exports = config; diff --git a/sirius-ui/.gitignore b/sirius-ui/.gitignore new file mode 100755 index 0000000..96e326b --- /dev/null +++ b/sirius-ui/.gitignore @@ -0,0 +1,39 @@ +# See https://help.github.com/articles/ignoring-files/ for more about ignoring files. + +# dependencies +/node_modules +/.pnp +.pnp.js + +# testing +/coverage + +# database +# Ignore all SQLite database files to prevent committing test data +/prisma/*.db +/prisma/*.sqlite +/prisma/db.sqlite-journal + +# next.js +/.next/ +/out/ +next-env.d.ts + +# production +/build + +# misc +.DS_Store +*.pem + +# debug +npm-debug.log* +yarn-debug.log* +yarn-error.log* +.pnpm-debug.log* + +# vercel +.vercel + +# typescript +*.tsbuildinfo diff --git a/sirius-ui/Dockerfile b/sirius-ui/Dockerfile new file mode 100644 index 0000000..6051f9e --- /dev/null +++ b/sirius-ui/Dockerfile @@ -0,0 +1,167 @@ +# Multi-stage Dockerfile for sirius-ui with development and production stages +# +# system-monitor and administrator are built in this file (no external GHCR base image). + +# ───────────────────────────────────────────────────────────────────────────── +# Utility binaries: system-monitor + administrator +# ───────────────────────────────────────────────────────────────────────────── +FROM golang:1.24-alpine AS utility-go-binaries + +RUN apk add --no-cache git ca-certificates tzdata + +RUN git clone https://github.com/SiriusScan/app-system-monitor.git /tmp/system-monitor && \ + cd /tmp/system-monitor && \ + go mod download && \ + CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o /usr/local/bin/system-monitor main.go && \ + rm -rf /tmp/system-monitor + +RUN git clone https://github.com/SiriusScan/app-administrator.git /tmp/administrator && \ + cd /tmp/administrator && \ + go mod download && \ + CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o /usr/local/bin/administrator main.go && \ + rm -rf /tmp/administrator + +# ───────────────────────────────────────────────────────────────────────────── +# Base stage: common Node.js dependencies +# ───────────────────────────────────────────────────────────────────────────── +FROM node:18-alpine AS base + +# Install system and native build dependencies for all architectures. +# bcrypt may fall back to node-gyp compilation (notably on arm64/musl), which +# requires Python + make + g++ at install time. +RUN apk add --no-cache \ + libc6-compat \ + openssl \ + ca-certificates \ + git \ + python3 \ + make \ + g++ + +WORKDIR /app + +# Copy package files +COPY package*.json ./ +COPY bun.lockb* ./ + +# Replace bun commands with npm/npx equivalents for compatibility +COPY package.json package.json.bak +RUN sed -i 's/bunx prisma generate/npx prisma generate/g' package.json && \ + sed -i 's/bun next/npx next/g' package.json && \ + sed -i 's/bun run/npm run/g' package.json + +# Clone sirius-nse repository for NSE scripts (needed by scanner profile management) +ARG SIRIUS_NSE_COMMIT_SHA=main +RUN mkdir -p /sirius-nse && \ + git clone https://github.com/SiriusScan/sirius-nse.git /sirius-nse && \ + cd /sirius-nse && \ + git checkout ${SIRIUS_NSE_COMMIT_SHA} && \ + echo "Cloned sirius-nse ($(git rev-parse --short HEAD))" + +# ───────────────────────────────────────────────────────────────────────────── +# Development stage +# ───────────────────────────────────────────────────────────────────────────── +FROM base AS development + +# Non-root user: chown /app while it is still small (package files only from base). +# Avoids chown -R over node_modules after npm install (very slow on Docker Desktop). +RUN addgroup --system --gid 1001 nodejs && \ + adduser --system --uid 1001 nextjs && \ + chown -R nextjs:nodejs /app + +ENV NPM_CONFIG_CACHE=/app/.npm-cache + +EXPOSE 3000 + +ENV NODE_ENV=development +ENV NEXT_TELEMETRY_DISABLED=1 + +USER nextjs + +RUN npm install + +COPY --chown=nextjs:nodejs . . + +RUN npx prisma generate + +# Ensure image start-dev.sh wins over build context and has unix line endings. +USER root +COPY start-dev.sh /app/start-dev.sh +RUN sed -i 's/\r$//' /app/start-dev.sh && chmod +x /app/start-dev.sh && \ + chown nextjs:nodejs /app/start-dev.sh + +USER nextjs + +CMD ["/bin/sh", "/app/start-dev.sh"] + +# ───────────────────────────────────────────────────────────────────────────── +# Builder stage: compile Next.js application +# ───────────────────────────────────────────────────────────────────────────── +FROM base AS builder + +ARG NEXT_PUBLIC_CLIENTVAR + +COPY . . + +# Remove .env files that interfere with Docker environment variables +RUN rm -f .env .env.local .env.development .env.production + +# Install dependencies (production + dev for building) +RUN npm install + +# Generate Prisma client +RUN npx prisma generate + +ENV NEXT_TELEMETRY_DISABLED=1 +ENV NEXT_PUBLIC_CLIENTVAR=${NEXT_PUBLIC_CLIENTVAR} +ENV SKIP_ENV_VALIDATION=1 +ENV SIRIUS_BUILD_STAGE=docker-build + +# Inject ignoreBuildErrors flags for Docker build so TS/ESLint errors don't block +RUN cp next.config.mjs next.config.mjs.bak && \ + node -e "const fs=require('fs');const p='next.config.mjs';let c=fs.readFileSync(p,'utf8');c=c.replace(' swcMinify: true,',' swcMinify: true,\n typescript: { ignoreBuildErrors: true },\n eslint: { ignoreDuringBuilds: true },');fs.writeFileSync(p,c);" && \ + npx next build + +# ───────────────────────────────────────────────────────────────────────────── +# Production runtime stage +# ───────────────────────────────────────────────────────────────────────────── +FROM node:18-alpine AS production + +RUN apk add --no-cache \ + libc6-compat \ + openssl \ + ca-certificates + +# Non-root user +RUN addgroup --system --gid 1001 nodejs && \ + adduser --system --uid 1001 nextjs + +WORKDIR /app + +# Create system-monitor directory +RUN mkdir -p /system-monitor + +COPY --chown=nextjs:nodejs --from=utility-go-binaries /usr/local/bin/system-monitor /system-monitor/system-monitor +COPY --chown=nextjs:nodejs --from=utility-go-binaries /usr/local/bin/administrator /app/administrator +RUN chmod +x /system-monitor/system-monitor /app/administrator + +# Copy built Next.js application from builder stage (ownership set during copy — no full-tree chown) +COPY --chown=nextjs:nodejs --from=builder /app/public ./public +COPY --chown=nextjs:nodejs --from=builder /app/.next ./.next +COPY --chown=nextjs:nodejs --from=builder /app/node_modules ./node_modules +COPY --chown=nextjs:nodejs --from=builder /app/src ./src +COPY --chown=nextjs:nodejs --from=builder /app/prisma ./prisma +COPY --chown=nextjs:nodejs --from=builder /app/package.json ./package.json +COPY --chown=nextjs:nodejs --from=builder /app/next.config.mjs ./next.config.mjs + +COPY --chown=nextjs:nodejs start-prod.sh /app/start-prod.sh +RUN sed -i 's/\r$//' /app/start-prod.sh && chmod +x /app/start-prod.sh + +USER nextjs + +EXPOSE 3000 + +ENV NODE_ENV=production +ENV NEXT_TELEMETRY_DISABLED=1 + +CMD ["/app/start-prod.sh"] diff --git a/sirius-ui/README.md b/sirius-ui/README.md new file mode 100755 index 0000000..b7b91af --- /dev/null +++ b/sirius-ui/README.md @@ -0,0 +1,53 @@ +# Sirius UI + +- [Next.js](https://nextjs.org) +- [NextAuth.js](https://next-auth.js.org) +- [Prisma](https://prisma.io) +- [Tailwind CSS](https://tailwindcss.com) +- [tRPC](https://trpc.io) + +## Database Management + +### Initial Credentials + +- **Username**: `admin` +- **Password**: value from `INITIAL_ADMIN_PASSWORD` + +### Resetting the Database + +If you've modified the database during testing and need to reset it: + +**Inside the container:** + +```bash +docker exec -it sirius-ui npx prisma db push --force-reset +docker exec -it sirius-ui npm run seed +``` + +**Or from your local machine (if running locally):** + +```bash +cd sirius-ui +npx prisma db push --force-reset +npm run seed +``` + +This will: + +1. Reset the database schema +2. Recreate the admin user using `INITIAL_ADMIN_PASSWORD` + +**Note:** Database files (`*.db`, `*.sqlite`) are gitignored to prevent committing test data. Each developer maintains their own local database state. + +## Learn More + +To learn more about the [T3 Stack](https://create.t3.gg/), take a look at the following resources: + +- [Documentation](https://create.t3.gg/) +- [Learn the T3 Stack](https://create.t3.gg/en/faq#what-learning-resources-are-currently-available) — Check out these awesome tutorials + +You can check out the [create-t3-app GitHub repository](https://github.com/t3-oss/create-t3-app) — your feedback and contributions are welcome! + +## How do I deploy this? + +Follow our deployment guides for [Vercel](https://create.t3.gg/en/deployment/vercel), [Netlify](https://create.t3.gg/en/deployment/netlify) and [Docker](https://create.t3.gg/en/deployment/docker) for more information. diff --git a/sirius-ui/REPOSITORY-SYNC-UI-COMPLETE.md b/sirius-ui/REPOSITORY-SYNC-UI-COMPLETE.md new file mode 100644 index 0000000..fc23c42 --- /dev/null +++ b/sirius-ui/REPOSITORY-SYNC-UI-COMPLETE.md @@ -0,0 +1,352 @@ +# Repository Sync UI Implementation - COMPLETE + +## Summary + +The frontend UI for the repository sync worker is now complete with enhanced error display and conflict detection support. + +## Changes Made + +### 1. Enhanced Error Display ✅ + +**File**: `src/components/scanner/repositories/RepositoriesTab.tsx` + +- Added tooltip support for displaying error messages +- Enhanced `getStatusBadge` function to show error details on hover +- Error badge now displays the full error message in a tooltip (including conflict messages) + +```typescript +case "error": + return ( + + + + + + Error + + + {errorMessage && ( + +

{errorMessage}

+ + )} + + + ); +``` + +### 2. Updated Priority Help Text ✅ + +**File**: `src/components/scanner/repositories/RepositoriesTab.tsx` + +- Updated priority field help text to clarify conflict behavior +- Now states: "Lower number = higher priority. Template conflicts fail sync and require manual resolution." + +### 3. Created Tooltip Component ✅ + +**File**: `src/components/lib/ui/tooltip.tsx` + +- Created new shadcn/ui style tooltip component +- Uses `@radix-ui/react-tooltip` primitive +- Consistent styling with existing UI components + +### 4. Installed Dependencies ✅ + +**Package**: `@radix-ui/react-tooltip` + +- Installed via npm +- Version: Latest compatible version +- Required for tooltip functionality + +### 5. Fixed Import Paths ✅ + +**Files**: Multiple components + +- Fixed incorrect `~/lib/utils` imports to `~/components/lib/utils` +- Fixed `RepositoriesTab.tsx` imports from `~/components/ui/*` to `~/components/lib/ui/*` +- Fixed `EnvironmentDataTable.tsx` import path + +## Existing UI Features (Already Complete) + +### Repository Management UI + +The `RepositoriesTab.tsx` component provides a complete interface for: + +- **List Repositories**: View all configured repositories with status +- **Add Repository**: Dialog to add new repository with validation +- **Edit Repository**: Update existing repository configuration +- **Delete Repository**: Remove repository with confirmation +- **Sync Repository**: Trigger manual sync with loading state +- **Status Display**: Visual badges for synced, syncing, error, and never_synced states + +### Key UI Components + +1. **Repository Table** + + - Name + - URL (with external link) + - Branch (badge display) + - Status (badge with error tooltip) + - Template Count + - Last Sync Time + - Priority + - Enabled/Disabled Toggle + - Action Buttons (Sync, Edit, Delete) + +2. **Add/Edit Dialogs** + + - Name (required) + - Repository URL (required, validated) + - Branch (default: "main") + - Priority (number, default: 1) + - Enabled toggle + - Form validation + - Loading states + +3. **Status Indicators** + - ✅ Synced (green badge with check icon) + - 🔄 Syncing (blue badge with spinning loader) + - ❌ Error (red badge with hover tooltip for details) + - ⚠️ Never Synced (gray badge with alert icon) + +### tRPC Router Integration + +**File**: `src/server/api/routers/repositories.ts` + +Complete tRPC router with endpoints: + +- `list`: Get all repositories +- `add`: Add new repository +- `update`: Update repository +- `delete`: Delete repository +- `sync`: Trigger repository sync +- `getSyncStatus`: Get sync progress + +All endpoints properly integrated with backend API at `http://localhost:9001/api/agent-templates/repositories`. + +## User Interface Flow + +### Adding a Repository + +1. Click "Add Repository" button +2. Fill in form fields: + - Name: Display name for the repository + - URL: Git repository URL + - Branch: Git branch to sync (default: main) + - Priority: Lower number = higher priority + - Enabled: Toggle to enable/disable repository +3. Click "Add Repository" +4. Repository is added and automatic sync is triggered +5. Watch status change from "Never Synced" → "Syncing" → "Synced" or "Error" + +### Viewing Sync Errors + +1. If sync fails, repository shows "Error" badge +2. Hover over error badge to see detailed error message +3. Common error messages: + - "template conflict: template NGINX-001 already exists from repository repo-A (current: repo-B)" + - Git errors (clone/pull failures) + - Network errors + +### Manual Sync + +1. Click refresh icon button on repository row +2. Button shows spinning loader while syncing +3. Status updates in real-time +4. Template count updates after successful sync + +## Testing Checklist + +### UI Functionality + +- [x] Repository list displays correctly +- [x] Add repository dialog validates inputs +- [x] Edit repository dialog pre-fills current values +- [x] Delete repository shows confirmation +- [x] Sync button triggers backend sync +- [x] Status badges display correctly +- [x] Error tooltip shows error message +- [x] Loading states work properly +- [x] Toast notifications appear +- [x] Table formatting is responsive + +### Backend Integration + +- [x] tRPC endpoints call correct API routes +- [x] Error handling works correctly +- [x] Data refreshes after mutations +- [x] Status updates reflect backend state + +### Ready for E2E Testing + +- [ ] Add repository with valid Git URL +- [ ] Trigger sync and verify templates appear +- [ ] Add second repository with conflicting template IDs +- [ ] Verify conflict error appears in tooltip +- [ ] Edit repository branch and re-sync +- [ ] Delete repository and verify templates removed +- [ ] Test with multiple repositories at different priorities + +## API Integration + +### Backend Endpoints + +``` +GET /api/agent-templates/repositories # List all repositories +POST /api/agent-templates/repositories # Add new repository +PUT /api/agent-templates/repositories/:id # Update repository +DELETE /api/agent-templates/repositories/:id # Delete repository +POST /api/agent-templates/repositories/:id/sync # Trigger sync +GET /api/agent-templates/repositories/:id/sync-status # Get status +``` + +### Request/Response Types + +```typescript +interface Repository { + id: string; + name: string; + url: string; + branch: string; + priority: number; + enabled: boolean; + last_sync: string | null; + template_count: number; + status: "synced" | "syncing" | "error" | "never_synced"; + error_message: string | null; + created_at: string; + updated_at: string; +} +``` + +## Error Handling + +### Conflict Detection + +When a template conflict occurs: + +1. Backend sync fails with error +2. Repository status set to "error" +3. Error message stored: "template conflict: template {ID} already exists from repository {repo}" +4. UI displays error badge +5. User hovers to see full conflict message +6. User must manually resolve conflict (delete one repository or template) + +### Network Errors + +- Git clone/pull failures +- API connection errors +- Timeout errors +- All shown in error tooltip + +### Validation Errors + +- Invalid repository URL +- Missing required fields +- Duplicate repository names +- All shown as inline form errors + +## Accessibility + +- Keyboard navigation supported +- Focus indicators visible +- ARIA labels on interactive elements +- Error messages announced to screen readers +- Tooltip content accessible + +## Responsive Design + +- Table scrolls horizontally on small screens +- Dialogs are mobile-friendly +- Buttons stack appropriately +- Touch targets are adequate size + +## Browser Compatibility + +- Modern browsers (Chrome, Firefox, Safari, Edge) +- Tested on desktop and tablet sizes +- Mobile view functional + +## Next Steps (User Testing) + +1. **Basic Functionality** + + - Navigate to repository management page + - Add a test repository + - Trigger sync and watch status + +2. **Conflict Testing** + + - Add second repository with same templates + - Observe conflict error + - Hover error badge to see message + +3. **Branch Testing** + + - Configure repository with non-main branch + - Verify correct branch is synced + +4. **Error Recovery** + - Fix conflicts by adjusting priorities + - Re-sync and verify success + +## Files Modified + +1. `src/components/scanner/repositories/RepositoriesTab.tsx` - Enhanced error display +2. `src/components/lib/ui/tooltip.tsx` - New component +3. `src/components/EnvironmentDataTable.tsx` - Fixed import path +4. `package.json` - Added @radix-ui/react-tooltip + +## Files Verified (No Changes Needed) + +1. `src/types/repositoryTypes.ts` - Types already correct +2. `src/server/api/routers/repositories.ts` - Router already complete +3. `src/server/api/root.ts` - Router already registered + +## Status + +- ✅ Frontend Implementation Complete +- ✅ Error Display Enhanced +- ✅ Tooltip Support Added +- ✅ Dependencies Installed +- ✅ Import Paths Fixed +- ✅ UI Container Restarted +- ✅ UI Accessible (HTTP 200) +- ⏳ E2E Testing Pending (User) + +--- + +**Implementation Date**: 2025-10-26 +**Status**: Ready for Testing +**UI Port**: http://localhost:3000 +**API Port**: http://localhost:9001 + +## Quick Test Commands + +```bash +# Check UI is running +curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 +# Should return: 200 + +# Check API is running +curl -s http://localhost:9001/api/agent-templates/repositories | jq 'length' +# Should return: number of configured repositories + +# Check logs +docker logs sirius-ui --tail 50 +docker logs sirius-api --tail 50 +``` + +## Navigation + +1. Open browser: http://localhost:3000 +2. Login with credentials +3. Navigate to Scanner or Templates section +4. Find "Repositories" tab +5. Begin testing repository management + + + + + + diff --git a/sirius-ui/TEMPLATE-INTEGRATION-CHECKLIST.md b/sirius-ui/TEMPLATE-INTEGRATION-CHECKLIST.md new file mode 100644 index 0000000..68e659a --- /dev/null +++ b/sirius-ui/TEMPLATE-INTEGRATION-CHECKLIST.md @@ -0,0 +1,554 @@ +# Template System Integration Checklist + +**Sprint**: Template System UX Evolution +**Date Started**: **\*\***\_\_\_**\*\*** +**Team**: UI Team +**Status**: 🟡 Pre-Sprint Preparation + +--- + +## 📋 Pre-Sprint Requirements + +### Type System Alignment + +- [ ] **CRITICAL**: Confirm detection type naming convention with backend team + + - [ ] Decision documented: Use dashes (`file-hash`, `file-content`, `version-cmd`) + - [ ] UI types updated in `src/types/agentTemplateTypes.ts` + - [ ] Type mapping understood and documented + +- [ ] **CRITICAL**: Verify storage format alignment + - [ ] Backend confirmed using JSON wrapper format + - [ ] Test template upload/retrieve cycle works + - [ ] Verified templates sync to agents correctly + +### Dependencies + +- [ ] Install required npm packages: + + ```bash + npm install js-yaml @types/js-yaml + npm install @monaco-editor/react # For YAML editor + npm install lodash @types/lodash # For debounce + ``` + +- [ ] Verify existing dependencies: + - [ ] `zod` for validation schemas + - [ ] `@tanstack/react-query` for data fetching + - [ ] `lucide-react` for icons + +### Documentation Review + +- [ ] Read [CUSTOM-TEMPLATES-UI-HANDOFF-ANALYSIS.md](../../app-agent/CUSTOM-TEMPLATES-UI-HANDOFF-ANALYSIS.md) +- [ ] Review [README.template-ui-integration.md](../documentation/dev/architecture/README.template-ui-integration.md) +- [ ] Check [QUICKREF.template-types.md](../documentation/dev/QUICKREF.template-types.md) +- [ ] Understand module config requirements for all three types + +--- + +## 🏗️ Phase 1: Component Structure & Types + +### Type Definitions (Week 1) + +- [ ] Create/update `src/types/templateBuilderTypes.ts` + + - [ ] `TemplateFormState` type + - [ ] `DetectionStepFormData` union type + - [ ] `ValidationErrors` type + - [ ] `TemplateBuilderView` enum + +- [ ] Update `src/types/agentTemplateTypes.ts` + - [ ] Change `StepType` to use dashes + - [ ] Verify all interfaces match agent types + - [ ] Add JSDoc comments with examples + +### Shared UI Components (Week 1) + +- [ ] Create `src/components/scanner/templates/shared/` + + - [ ] `PlatformSelector.tsx` - Checkbox group with OS icons + - [ ] `SeveritySelector.tsx` - Radio group with color badges + - [ ] `WeightSlider.tsx` - Confidence weight slider (0.0-1.0) + - [ ] `CollapsibleSection.tsx` - Reusable collapsible container + +- [ ] Test shared components in isolation + - [ ] Unit tests for each component + - [ ] Storybook stories (if available) + - [ ] Accessibility testing + +--- + +## 🎨 Phase 2: Template Library Redesign + +### Template Library View (Week 1-2) + +- [ ] Create `src/components/scanner/templates/TemplateLibrary.tsx` + + - [ ] Search functionality with debounce + - [ ] Filter by severity, type, platform + - [ ] Sort options (name, severity, date) + - [ ] Grid/List view toggle + - [ ] Category grouping (Standard vs Custom) + +- [ ] Create `src/components/scanner/templates/TemplateCard.tsx` + + - [ ] Gradient border by severity + - [ ] Platform icons display + - [ ] Tag chips (first 3 + more) + - [ ] Quick actions (View, Edit, Run, Delete) + - [ ] Hover effects + +- [ ] Create `src/components/scanner/templates/TemplateFilters.tsx` + - [ ] Search input + - [ ] Multi-select filters + - [ ] Active filter pills + - [ ] Clear all button + +### Testing + +- [ ] Unit tests for library components +- [ ] Integration test: Filter and search +- [ ] Playwright test: Navigate library + +--- + +## 🛠️ Phase 3: Template Builder (Full Page) + +### Builder Container (Week 2) + +- [ ] Create `src/components/scanner/templates/TemplateBuilder.tsx` + - [ ] Full-height scrollable layout + - [ ] Two-column design (≥1280px) + - [ ] Sticky header with actions + - [ ] Mode toggle: Guided Builder | YAML Editor + - [ ] State management (useState/useReducer) + +### Metadata Section (Week 2) + +- [ ] Create `src/components/scanner/templates/builder/MetadataSection.tsx` + + - [ ] Template ID input with validation + - [ ] Template name input + - [ ] Description textarea + - [ ] Severity selector + - [ ] Author input (defaults to current user) + - [ ] CVE IDs textarea (one per line) + - [ ] Tags input with chips + - [ ] References textarea (URLs) + - [ ] Version input + +- [ ] Implement validation + - [ ] ID format validation + - [ ] ID uniqueness check (client-side) + - [ ] CVE format validation + - [ ] URL format validation for references + +### Detection Configuration (Week 2) + +- [ ] Create `src/components/scanner/templates/builder/DetectionSection.tsx` + - [ ] Detection logic selector (all/any) + - [ ] Steps list with drag-to-reorder + - [ ] Add step dropdown menu + - [ ] Step summary cards + - [ ] Edit/duplicate/delete actions + +### Detection Step Modals (Week 2-3) + +- [ ] Create `src/components/scanner/templates/builder/steps/FileHashStepModal.tsx` + + - [ ] File path input + - [ ] Hash value input + - [ ] Algorithm selector + - [ ] Platform selector + - [ ] Weight slider + - [ ] Validation + +- [ ] Create `src/components/scanner/templates/builder/steps/FileContentStepModal.tsx` + + - [ ] File path input + - [ ] Pattern textarea (one per line) + - [ ] Regex tester (collapsible) + - [ ] Platform selector + - [ ] Weight slider + - [ ] Validation + +- [ ] Create `src/components/scanner/templates/builder/steps/VersionCmdStepModal.tsx` + - [ ] Command input (single string) + - [ ] Version regex input + - [ ] Vulnerable versions array input + - [ ] Expected exit code input + - [ ] Platform selector + - [ ] Weight slider + - [ ] Validation + +### YAML Features (Week 3) + +- [ ] Create `src/components/scanner/templates/builder/YamlImporter.tsx` + + - [ ] File upload + - [ ] Paste area + - [ ] YAML validation + - [ ] Form auto-fill + - [ ] Error handling + +- [ ] Create `src/components/scanner/templates/builder/YamlPreview.tsx` + + - [ ] Monaco editor integration + - [ ] Real-time generation from form + - [ ] Syntax highlighting + - [ ] Copy to clipboard button + - [ ] Download button + - [ ] Validation status indicator + +- [ ] Implement YAML generation + + - [ ] `generateTemplateYAML` function + - [ ] Debounced preview updates + - [ ] Handle empty optional fields + - [ ] Proper YAML formatting + +- [ ] Implement YAML parsing + - [ ] `parseTemplateYAML` function + - [ ] Error handling + - [ ] Form state mapping + - [ ] Type safety + +### Testing + +- [ ] Unit tests for YAML functions +- [ ] Unit tests for each step modal +- [ ] Integration test: Complete form flow +- [ ] Playwright test: Create template end-to-end + +--- + +## 👁️ Phase 4: Template Viewer Enhancement + +### Viewer Modal (Week 3) + +- [ ] Create `src/components/scanner/templates/TemplateViewer.tsx` + - [ ] Large dialog layout + - [ ] Tab navigation + - [ ] Header with template info + - [ ] Footer with actions + +### Viewer Tabs (Week 3) + +- [ ] Create `src/components/scanner/templates/viewer/OverviewTab.tsx` + + - [ ] Two-column layout + - [ ] Template details card + - [ ] Severity display + - [ ] Platform icons + - [ ] Full description + - [ ] CVE links + - [ ] Tag chips + - [ ] Reference links + +- [ ] Create `src/components/scanner/templates/viewer/DetectionStepsTab.tsx` + + - [ ] Detection logic indicator + - [ ] Expandable step cards + - [ ] Step configuration display + - [ ] Confidence calculation + - [ ] Visual flow diagram + +- [ ] Create `src/components/scanner/templates/viewer/YamlSourceTab.tsx` + - [ ] Monaco editor (read-only) + - [ ] Syntax highlighting + - [ ] Copy button + - [ ] Download button + - [ ] Line numbers + +### Testing + +- [ ] Unit tests for viewer tabs +- [ ] Integration test: Navigate tabs +- [ ] Playwright test: View template details + +--- + +## 🔌 Phase 5: Integration & State Management + +### Main Tab Orchestration (Week 3-4) + +- [ ] Update `src/components/scanner/agent/AgentTemplatesTab.tsx` + - [ ] View state management + - [ ] Navigation between views + - [ ] Template state management + - [ ] Loading states + - [ ] Error handling + +### API Integration (Week 4) + +- [ ] Verify tRPC endpoints work + + - [ ] `getTemplates` - List all + - [ ] `getTemplate` - Get single with YAML + - [ ] `uploadTemplate` - Create new + - [ ] `validateTemplate` - Validate before save + - [ ] `deleteTemplate` - Remove custom + +- [ ] Add client-side helpers + - [ ] Template ID uniqueness check + - [ ] YAML generation utility + - [ ] YAML parsing utility + - [ ] Validation utilities + +### Error Handling (Week 4) + +- [ ] Implement error boundaries +- [ ] Add user-friendly error messages +- [ ] Toast notifications for actions +- [ ] Validation error display +- [ ] Network error handling + +### Testing + +- [ ] Integration tests for state management +- [ ] API integration tests +- [ ] Error scenario tests +- [ ] Playwright: Full user flows + +--- + +## 🧪 Phase 6: Testing Strategy + +### Unit Tests + +- [ ] YAML generation tests + + - [ ] Valid form data → valid YAML + - [ ] Empty optional fields handled + - [ ] Special characters escaped + - [ ] All module types covered + +- [ ] YAML parsing tests + + - [ ] Valid YAML → valid form data + - [ ] Malformed YAML handled + - [ ] Missing fields handled + - [ ] Type safety verified + +- [ ] Validation tests + - [ ] Template ID format + - [ ] CVE format + - [ ] Config validation per module + - [ ] Required fields + +### Integration Tests + +- [ ] Template library + + - [ ] Search functionality + - [ ] Filter combinations + - [ ] Sort options + - [ ] View toggle + +- [ ] Template builder + + - [ ] Form submission + - [ ] YAML preview updates + - [ ] Step management + - [ ] Import from YAML + +- [ ] Template viewer + - [ ] Tab navigation + - [ ] Content display + - [ ] Action buttons + +### End-to-End Tests (Playwright) + +- [ ] **Scenario 1**: Create file-hash template + + - [ ] Fill form + - [ ] Add step + - [ ] Preview YAML + - [ ] Submit + - [ ] Verify in library + +- [ ] **Scenario 2**: Create multi-step template + + - [ ] Add multiple steps + - [ ] Set detection logic + - [ ] Verify YAML structure + - [ ] Submit and verify + +- [ ] **Scenario 3**: Import and modify template + + - [ ] Import YAML + - [ ] Verify form populated + - [ ] Modify fields + - [ ] Submit update + +- [ ] **Scenario 4**: Search and filter + - [ ] Create test templates + - [ ] Search by name + - [ ] Filter by severity + - [ ] Verify results + +--- + +## 🎨 Phase 7: Design System Compliance + +### Color Palette + +- [ ] Verify violet theme usage + + - [ ] Primary actions: `bg-violet-600 hover:bg-violet-500` + - [ ] Borders: `border-violet-500/30` + - [ ] Text highlights: `text-violet-400` + +- [ ] Verify dark mode support + + - [ ] Backgrounds: `bg-gray-800`, `bg-gray-900` + - [ ] Borders: `border-gray-700` + - [ ] Cards: `bg-gray-800/50` + - [ ] Text: `text-gray-300`, `text-gray-400` + +- [ ] Severity colors consistent + - [ ] Critical: `bg-red-500/20 text-red-400` + - [ ] High: `bg-orange-500/20 text-orange-400` + - [ ] Medium: `bg-yellow-500/20 text-yellow-400` + - [ ] Low: `bg-blue-500/20 text-blue-400` + - [ ] Info: `bg-gray-500/20 text-gray-400` + +### Component Standards + +- [ ] All components use shadcn/ui +- [ ] Consistent spacing (space-y-4, space-y-2) +- [ ] Consistent border radius (rounded-lg, rounded-md) +- [ ] lucide-react icons throughout +- [ ] Smooth transitions (transition-colors duration-200) + +### Responsive Design + +- [ ] Mobile breakpoint (sm: 640px) tested +- [ ] Tablet breakpoint (md: 768px) tested +- [ ] Desktop breakpoint (lg: 1024px) tested +- [ ] Large desktop (xl: 1280px) tested +- [ ] Forms stack properly on mobile +- [ ] YAML preview sidebar works on all sizes + +--- + +## ✅ Final Validation + +### Code Quality + +- [ ] All TypeScript types are correct +- [ ] No `any` types used +- [ ] All functions have JSDoc comments +- [ ] Console errors resolved +- [ ] Linter warnings resolved +- [ ] No unused imports + +### Accessibility + +- [ ] Keyboard navigation works +- [ ] Screen reader support +- [ ] ARIA labels present +- [ ] Focus indicators visible +- [ ] Color contrast meets WCAG AA + +### Performance + +- [ ] YAML preview debounced +- [ ] Template list uses pagination/virtualization +- [ ] Images optimized +- [ ] Bundle size reasonable +- [ ] No memory leaks + +### Documentation + +- [ ] Code comments added +- [ ] README updated +- [ ] Component documentation +- [ ] Integration notes + +### User Experience + +- [ ] Create template < 3 minutes +- [ ] No YAML knowledge required +- [ ] All module types work +- [ ] YAML import works +- [ ] Search returns results < 200ms +- [ ] Dark mode consistent +- [ ] Mobile responsive (≥375px) + +--- + +## 🚀 Launch Readiness + +### Pre-Launch + +- [ ] **Critical issues resolved** + + - [ ] Type naming confirmed + - [ ] Storage format aligned + +- [ ] **All tests passing** + + - [ ] Unit tests: 100% pass + - [ ] Integration tests: 100% pass + - [ ] Playwright tests: 100% pass + +- [ ] **Backend coordination complete** + - [ ] Platform aggregation deployed + - [ ] Enhanced validation deployed + - [ ] Storage format updated + +### Launch Day + +- [ ] Monitor for errors +- [ ] Track template creation success rate +- [ ] Collect user feedback +- [ ] Document issues + +### Post-Launch + +- [ ] Address bug reports +- [ ] Collect enhancement requests +- [ ] Plan Phase 2 features +- [ ] Update documentation + +--- + +## 📊 Success Metrics + +Track these metrics to validate success: + +| Metric | Target | Actual | +| ------------------------------- | ------- | ------ | +| Template creation time | < 3 min | \_\_\_ | +| Template creation success rate | > 95% | \_\_\_ | +| Template execution success rate | > 90% | \_\_\_ | +| User satisfaction (1-10) | > 8 | \_\_\_ | +| Bug reports (first week) | < 5 | \_\_\_ | +| Console errors | 0 | \_\_\_ | +| Accessibility score | 100 | \_\_\_ | + +--- + +## 📞 Support Contacts + +**For Questions**: + +- Type naming: Backend Team Lead +- API endpoints: Backend Engineer +- Module configs: Agent Team Lead +- Design system: UI/UX Designer + +**For Issues**: + +- Critical bugs: Immediately escalate +- Medium bugs: Document and prioritize +- Enhancement requests: Track for Phase 2 + +--- + +**Checklist Version**: 1.0 +**Created**: October 25, 2025 +**Team**: UI Development Team +**Sprint Duration**: 4 weeks +**Status**: 🟡 Ready for Sprint Kickoff diff --git a/sirius-ui/bun.lockb b/sirius-ui/bun.lockb new file mode 100755 index 0000000..ec8c3a0 Binary files /dev/null and b/sirius-ui/bun.lockb differ diff --git a/sirius-ui/components.json b/sirius-ui/components.json new file mode 100755 index 0000000..505db81 --- /dev/null +++ b/sirius-ui/components.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://ui.shadcn.com/schema.json", + "style": "default", + "rsc": false, + "tsx": true, + "tailwind": { + "config": "tailwind.config.js", + "css": "src/styles/globals.css", + "baseColor": "slate", + "cssVariables": true + }, + "aliases": { + "components": "src/components/lib", + "utils": "src/components/lib/utils" + } +} diff --git a/sirius-ui/docs/scanner.md b/sirius-ui/docs/scanner.md new file mode 100644 index 0000000..c60f0df --- /dev/null +++ b/sirius-ui/docs/scanner.md @@ -0,0 +1,153 @@ +# Scanner Component + +The Scanner Component is a modular, real-time scanning interface designed to manage and display scan statuses, host and vulnerability data, and allow the user to initiate new scans. This codebase leverages React, TypeScript, and Tailwind CSS for styling, and it interacts with backend APIs via custom hooks and a service layer. + +## Table of Contents + +- [Overview](#overview) +- [Features](#features) +- [Project Structure](#project-structure) +- [Getting Started](#getting-started) +- [Components](#components) + - [Scanner](#scanner) + - [ScanStatus](#scanstatus) + - [ScanForm](#scanform) + - [ScanNavigator](#scannavigator) + - [Data Tables](#data-tables) +- [Hooks](#hooks) + - [useScanResults](#usescanresults) + - [useStartScan](#usestartscan) +- [Services](#services) +- [Contributing](#contributing) +- [License](#license) + +## Overview + +The Scanner Component provides a dynamic UI that polls a backend for scan results, decodes a Base64 encoded scan status, and updates the UI in real time. It displays a scan monitor interface with: + +- **Scan Status:** Live display of scan status and details. +- **Host and Vulnerability Tables:** Two different views for scanned hosts and vulnerabilities. +- **Target Management:** A form to add new scan targets and start scans. + +## Features + +- **Real-time Data:** Polls the backend every 3 seconds for updated scan information. +- **Modular Design:** Separated into components, hooks, and service layers for maintainability. +- **Optimized Performance:** Utilizes `React.memo`, `useCallback`, and `useMemo` for performance optimizations. +- **Type Safety:** Written in TypeScript with clearly defined interfaces. +- **Accessible UI:** Interactive elements include appropriate ARIA roles and labels. + +## Project Structure + +``` +src/ +├── components/ +│ ├── scanner/ +│ │ ├── Scanner.tsx // Main scanner component +│ │ ├── ScanForm.tsx // Form to add targets and start scan +│ │ └── ScanNavigator.tsx // Navigation for switching views (scan, config, advanced) +│ ├── ScanStatus.tsx // Displays scan status information +│ ├── VulnerabilityDataTable.tsx // Displays vulnerability table +│ └── EnvironmentDataTable.tsx // Displays host table +├── hooks/ +│ ├── useScanResults.ts // Polls backend and decodes scan results +│ └── useStartScan.ts // Initiates a scan via API mutations +├── services/ +│ └── scanService.ts // Contains functions for starting scans +├── types/ +│ └── scanTypes.ts // Shared TypeScript interfaces and types +└── utils/ +└── api.ts // API configuration and client (e.g., TRPC/React Query setup) +``` + +## Getting Started + +### Prerequisites + +- [Node.js](https://nodejs.org/) (v14 or above) +- [Yarn](https://yarnpkg.com/) or npm + +### Running the Application + +Docker is used to run the application. Ensure Docker is installed and running on your machine. + +Dev mode can be achieved by running: + +``` +bun run dev +``` +Navigate to http://localhost:3000 in your browser. + +## Components + +### Scanner + +The main component that brings together the scan status display, target management, and table views. It leverages custom hooks for fetching and decoding scan data and uses services for starting scans. + +ScanStatus + +Displays the current scan information (status, targets, hosts, vulnerabilities). It expects a decoded scan result object. + +ScanForm + +A form that lets users: + • Add a new scan target. + • Start a scan for the current list of targets. + +Optimizations: + • Wrapped with React.memo to prevent unnecessary re-renders. + • Uses useCallback for event handlers. + +ScanNavigator + +Provides navigation buttons to switch between different views such as “Scan Monitor”, “Configuration”, and “Advanced”. Also wrapped in React.memo. + +Data Tables + • EnvironmentDataTable: Displays a list of scanned hosts. + • VulnerabilityDataTable: Displays vulnerability details. + +These tables are updated dynamically based on the scan results. + +Hooks + +useScanResults + • Purpose: Polls the backend for scan data every 3 seconds. + • Features: + • Decodes Base64 encoded JSON into a ScanResult object. + • Provides live updates for hosts and vulnerabilities. + • Usage: + +useStartScan + • Purpose: Encapsulates logic for starting a scan. + • Features: + • Uses API mutations to send scan start messages. + • Resets the scan state in the backend. + • Usage: + + +## Services + +scanService.ts + +Contains functions for interacting with the scan API. For example, startScanForTarget sends a message to the scanning queue and resets the current scan state. + +Contributing + +Contributions are welcome! Please open an issue or submit a pull request if you have improvements or bug fixes. + 1. Fork the repository. + 2. Create a new branch: git checkout -b feature/your-feature-name + 3. Commit your changes: git commit -m 'Add some feature' + 4. Push to the branch: git push origin feature/your-feature-name + 5. Open a pull request. + +--- + +### Explanation + +- **Overview and Features:** Provide a high-level understanding of what the component does. +- **Project Structure:** Outlines where key parts of the scanner module reside. +- **Getting Started:** Instructions for cloning, installing, and running the project. +- **Components, Hooks, and Services:** Detailed explanations of the main building blocks. +- **Contributing and License:** Guidelines for contributing and licensing details. + +This README should serve as a clear guide for both new developers and collaborators on how the scanner component is organized and how it works. Let me know if you need further adjustments or additional sections! \ No newline at end of file diff --git a/sirius-ui/next.config.mjs b/sirius-ui/next.config.mjs new file mode 100755 index 0000000..a2c9410 --- /dev/null +++ b/sirius-ui/next.config.mjs @@ -0,0 +1,36 @@ +import createMDX from "@next/mdx"; +/** + * Import environment configuration + */ +await import("./src/env.mjs"); + +/** @type {import("next").NextConfig} */ +const config = { + reactStrictMode: true, + swcMinify: true, + pageExtensions: ["js", "jsx", "md", "mdx", "ts", "tsx"], + + // Better error handling for routing + onDemandEntries: { + // period (in ms) where the server will keep pages in the buffer + maxInactiveAge: 25 * 1000, + // number of pages that should be kept simultaneously without being disposed + pagesBufferLength: 2, + }, + + /** + * If you are using `appDir` then you must comment the below `i18n` config out. + * + * @see https://github.com/vercel/next.js/issues/41980 + */ + i18n: { + locales: ["en"], + defaultLocale: "en", + }, +}; + +const withMDX = createMDX({ + // Add markdown plugins here, as desired +}); + +export default withMDX(config); diff --git a/sirius-ui/package-lock.json b/sirius-ui/package-lock.json new file mode 100644 index 0000000..72f1ad5 --- /dev/null +++ b/sirius-ui/package-lock.json @@ -0,0 +1,22808 @@ +{ + "name": "sirius-ui", + "version": "1.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "sirius-ui", + "version": "1.0.0", + "hasInstallScript": true, + "dependencies": { + "@hookform/resolvers": "^3.3.1", + "@mdx-js/loader": "^3.1.0", + "@mdx-js/react": "^3.1.0", + "@monaco-editor/react": "^4.7.0", + "@next-auth/prisma-adapter": "^1.0.7", + "@next/mdx": "13.4.2", + "@nivo/bar": "^0.83.0", + "@nivo/core": "^0.83.0", + "@nivo/line": "^0.83.0", + "@nivo/pie": "^0.83.0", + "@prisma/client": "^5.1.1", + "@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", + "@tanstack/react-virtual": "^3.13.18", + "@trpc/client": "^10.34.0", + "@trpc/next": "^10.34.0", + "@trpc/react-query": "^10.34.0", + "@trpc/server": "^10.34.0", + "@types/amqplib": "^0.10.6", + "@types/bcrypt": "^5.0.2", + "@types/mdx": "^2.0.13", + "@types/minimist": "^1.2.5", + "@xterm/addon-fit": "^0.10.0", + "@xterm/addon-search": "^0.16.0", + "@xterm/addon-web-links": "^0.11.0", + "@xterm/xterm": "^5.5.0", + "amqplib": "^0.10.5", + "axios": "^1.5.0", + "bcrypt": "^5.1.1", + "class-variance-authority": "^0.7.0", + "clsx": "^2.0.0", + "fuse.js": "^7.1.0", + "install": "^0.13.0", + "iovalkey": "^0.3.0", + "js-yaml": "^4.1.0", + "lucide-react": "^0.268.0", + "minimist": "^1.2.8", + "next": "^13.4.2", + "next-auth": "^4.22.4", + "next-themes": "^0.4.4", + "prisma": "^5.1.1", + "radix-ui": "^1.0.1", + "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", + "recharts": "^2.15.1", + "sonner": "^2.0.1", + "superjson": "^1.13.1", + "tailwind-merge": "^1.14.0", + "tailwindcss-animate": "^1.0.6", + "ts-node": "^10.9.2", + "yaml": "^2.8.0", + "zod": "^3.22.2" + }, + "devDependencies": { + "@types/eslint": "^8.37.0", + "@types/node": "^18.16.0", + "@types/prettier": "^2.7.2", + "@types/react": "^18.2.6", + "@types/react-dom": "^18.2.4", + "@typescript-eslint/eslint-plugin": "6.0.0", + "@typescript-eslint/parser": "6.0.0", + "autoprefixer": "^10.4.14", + "eslint": "^8.40.0", + "eslint-config-next": "^13.4.2", + "postcss": "^8.4.27", + "prettier": "^2.8.8", + "prettier-plugin-tailwindcss": "^0.2.8", + "tailwindcss": "^3.3.3", + "tsx": "^4.19.4", + "typescript": "^5.0.4" + } + }, + "node_modules/@aashutoshrathi/word-wrap": { + "version": "1.2.6", + "resolved": "https://registry.npmjs.org/@aashutoshrathi/word-wrap/-/word-wrap-1.2.6.tgz", + "integrity": "sha512-1Yjs2SvM8TflER/OD3cOjhWWOZb58A2t7wpE2S9XfBYTiIl+XFhQG2bjy4Pu1I+EAlCNUzRDYDdFwFYUKvXcIA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/@acuminous/bitsyntax": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/@acuminous/bitsyntax/-/bitsyntax-0.1.2.tgz", + "integrity": "sha512-29lUK80d1muEQqiUsSo+3A0yP6CdspgC95EnKBMi22Xlwt79i/En4Vr67+cXhU+cZjbti3TgGGC5wy1stIywVQ==", + "license": "MIT", + "dependencies": { + "buffer-more-ints": "~1.0.0", + "debug": "^4.3.4", + "safe-buffer": "~5.1.2" + }, + "engines": { + "node": ">=0.8" + } + }, + "node_modules/@alloc/quick-lru": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@alloc/quick-lru/-/quick-lru-5.2.0.tgz", + "integrity": "sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw==", + "license": "MIT", + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/@ampproject/remapping": { + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/@ampproject/remapping/-/remapping-2.2.1.tgz", + "integrity": "sha512-lFMjJTrFL3j7L9yBxwYfCq2k6qqwHyzuUl/XBnif78PWTJYyL/dfowQHWE3sp6U6ZzqWiiIZnpTMO96zhkjwtg==", + "license": "Apache-2.0", + "peer": true, + "dependencies": { + "@jridgewell/gen-mapping": "^0.3.0", + "@jridgewell/trace-mapping": "^0.3.9" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@babel/code-frame": { + "version": "7.22.13", + "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.22.13.tgz", + "integrity": "sha512-XktuhWlJ5g+3TJXc5upd9Ks1HutSArik6jf2eAjYFyIOf4ej3RN+184cZbzDvbPnuTJIUhPKKJE3cIsYTiAT3w==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/highlight": "^7.22.13", + "chalk": "^2.4.2" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/code-frame/node_modules/ansi-styles": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", + "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", + "license": "MIT", + "peer": true, + "dependencies": { + "color-convert": "^1.9.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/@babel/code-frame/node_modules/chalk": { + "version": "2.4.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz", + "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "ansi-styles": "^3.2.1", + "escape-string-regexp": "^1.0.5", + "supports-color": "^5.3.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/@babel/code-frame/node_modules/color-convert": { + "version": "1.9.3", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", + "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", + "license": "MIT", + "peer": true, + "dependencies": { + "color-name": "1.1.3" + } + }, + "node_modules/@babel/code-frame/node_modules/color-name": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", + "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==", + "license": "MIT", + "peer": true + }, + "node_modules/@babel/code-frame/node_modules/escape-string-regexp": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", + "integrity": "sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.8.0" + } + }, + "node_modules/@babel/code-frame/node_modules/has-flag": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", + "integrity": "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/@babel/code-frame/node_modules/supports-color": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", + "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==", + "license": "MIT", + "peer": true, + "dependencies": { + "has-flag": "^3.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/@babel/compat-data": { + "version": "7.22.20", + "resolved": "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.22.20.tgz", + "integrity": "sha512-BQYjKbpXjoXwFW5jGqiizJQQT/aC7pFm9Ok1OWssonuguICi264lbgMzRp2ZMmRSlfkX6DsWDDcsrctK8Rwfiw==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/core": { + "version": "7.22.20", + "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.22.20.tgz", + "integrity": "sha512-Y6jd1ahLubuYweD/zJH+vvOY141v4f9igNQAQ+MBgq9JlHS2iTsZKn1aMsb3vGccZsXI16VzTBw52Xx0DWmtnA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@ampproject/remapping": "^2.2.0", + "@babel/code-frame": "^7.22.13", + "@babel/generator": "^7.22.15", + "@babel/helper-compilation-targets": "^7.22.15", + "@babel/helper-module-transforms": "^7.22.20", + "@babel/helpers": "^7.22.15", + "@babel/parser": "^7.22.16", + "@babel/template": "^7.22.15", + "@babel/traverse": "^7.22.20", + "@babel/types": "^7.22.19", + "convert-source-map": "^1.7.0", + "debug": "^4.1.0", + "gensync": "^1.0.0-beta.2", + "json5": "^2.2.3", + "semver": "^6.3.1" + }, + "engines": { + "node": ">=6.9.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/babel" + } + }, + "node_modules/@babel/core/node_modules/semver": { + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", + "license": "ISC", + "peer": true, + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/@babel/generator": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.22.15.tgz", + "integrity": "sha512-Zu9oWARBqeVOW0dZOjXc3JObrzuqothQ3y/n1kUtrjCoCPLkXUwMvOo/F/TCfoHMbWIFlWwpZtkZVb9ga4U2pA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/types": "^7.22.15", + "@jridgewell/gen-mapping": "^0.3.2", + "@jridgewell/trace-mapping": "^0.3.17", + "jsesc": "^2.5.1" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-annotate-as-pure": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/helper-annotate-as-pure/-/helper-annotate-as-pure-7.22.5.tgz", + "integrity": "sha512-LvBTxu8bQSQkcyKOU+a1btnNFQ1dMAd0R6PyW3arXes06F6QLWLIrd681bxRPIXlrMGR3XYnW9JyML7dP3qgxg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/types": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-builder-binary-assignment-operator-visitor": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/helper-builder-binary-assignment-operator-visitor/-/helper-builder-binary-assignment-operator-visitor-7.22.15.tgz", + "integrity": "sha512-QkBXwGgaoC2GtGZRoma6kv7Szfv06khvhFav67ZExau2RaXzy8MpHSMO2PNoP2XtmQphJQRHFfg77Bq731Yizw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/types": "^7.22.15" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-compilation-targets": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/helper-compilation-targets/-/helper-compilation-targets-7.22.15.tgz", + "integrity": "sha512-y6EEzULok0Qvz8yyLkCvVX+02ic+By2UdOhylwUOvOn9dvYc9mKICJuuU1n1XBI02YWsNsnrY1kc6DVbjcXbtw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/compat-data": "^7.22.9", + "@babel/helper-validator-option": "^7.22.15", + "browserslist": "^4.21.9", + "lru-cache": "^5.1.1", + "semver": "^6.3.1" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-compilation-targets/node_modules/lru-cache": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz", + "integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==", + "license": "ISC", + "peer": true, + "dependencies": { + "yallist": "^3.0.2" + } + }, + "node_modules/@babel/helper-compilation-targets/node_modules/semver": { + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", + "license": "ISC", + "peer": true, + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/@babel/helper-compilation-targets/node_modules/yallist": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz", + "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==", + "license": "ISC", + "peer": true + }, + "node_modules/@babel/helper-create-class-features-plugin": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/helper-create-class-features-plugin/-/helper-create-class-features-plugin-7.22.15.tgz", + "integrity": "sha512-jKkwA59IXcvSaiK2UN45kKwSC9o+KuoXsBDvHvU/7BecYIp8GQ2UwrVvFgJASUT+hBnwJx6MhvMCuMzwZZ7jlg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-annotate-as-pure": "^7.22.5", + "@babel/helper-environment-visitor": "^7.22.5", + "@babel/helper-function-name": "^7.22.5", + "@babel/helper-member-expression-to-functions": "^7.22.15", + "@babel/helper-optimise-call-expression": "^7.22.5", + "@babel/helper-replace-supers": "^7.22.9", + "@babel/helper-skip-transparent-expression-wrappers": "^7.22.5", + "@babel/helper-split-export-declaration": "^7.22.6", + "semver": "^6.3.1" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0" + } + }, + "node_modules/@babel/helper-create-class-features-plugin/node_modules/semver": { + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", + "license": "ISC", + "peer": true, + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/@babel/helper-create-regexp-features-plugin": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/helper-create-regexp-features-plugin/-/helper-create-regexp-features-plugin-7.22.15.tgz", + "integrity": "sha512-29FkPLFjn4TPEa3RE7GpW+qbE8tlsu3jntNYNfcGsc49LphF1PQIiD+vMZ1z1xVOKt+93khA9tc2JBs3kBjA7w==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-annotate-as-pure": "^7.22.5", + "regexpu-core": "^5.3.1", + "semver": "^6.3.1" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0" + } + }, + "node_modules/@babel/helper-create-regexp-features-plugin/node_modules/semver": { + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", + "license": "ISC", + "peer": true, + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/@babel/helper-define-polyfill-provider": { + "version": "0.4.2", + "resolved": "https://registry.npmjs.org/@babel/helper-define-polyfill-provider/-/helper-define-polyfill-provider-0.4.2.tgz", + "integrity": "sha512-k0qnnOqHn5dK9pZpfD5XXZ9SojAITdCKRn2Lp6rnDGzIbaP0rHyMPk/4wsSxVBVz4RfN0q6VpXWP2pDGIoQ7hw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-compilation-targets": "^7.22.6", + "@babel/helper-plugin-utils": "^7.22.5", + "debug": "^4.1.1", + "lodash.debounce": "^4.0.8", + "resolve": "^1.14.2" + }, + "peerDependencies": { + "@babel/core": "^7.4.0 || ^8.0.0-0 <8.0.0" + } + }, + "node_modules/@babel/helper-environment-visitor": { + "version": "7.22.20", + "resolved": "https://registry.npmjs.org/@babel/helper-environment-visitor/-/helper-environment-visitor-7.22.20.tgz", + "integrity": "sha512-zfedSIzFhat/gFhWfHtgWvlec0nqB9YEIVrpuwjruLlXfUSnA8cJB0miHKwqDnQ7d32aKo2xt88/xZptwxbfhA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-function-name": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/helper-function-name/-/helper-function-name-7.22.5.tgz", + "integrity": "sha512-wtHSq6jMRE3uF2otvfuD3DIvVhOsSNshQl0Qrd7qC9oQJzHvOL4qQXlQn2916+CXGywIjpGuIkoyZRRxHPiNQQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/template": "^7.22.5", + "@babel/types": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-hoist-variables": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/helper-hoist-variables/-/helper-hoist-variables-7.22.5.tgz", + "integrity": "sha512-wGjk9QZVzvknA6yKIUURb8zY3grXCcOZt+/7Wcy8O2uctxhplmUPkOdlgoNhmdVee2c92JXbf1xpMtVNbfoxRw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/types": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-member-expression-to-functions": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/helper-member-expression-to-functions/-/helper-member-expression-to-functions-7.22.15.tgz", + "integrity": "sha512-qLNsZbgrNh0fDQBCPocSL8guki1hcPvltGDv/NxvUoABwFq7GkKSu1nRXeJkVZc+wJvne2E0RKQz+2SQrz6eAA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/types": "^7.22.15" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-module-imports": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/helper-module-imports/-/helper-module-imports-7.22.15.tgz", + "integrity": "sha512-0pYVBnDKZO2fnSPCrgM/6WMc7eS20Fbok+0r88fp+YtWVLZrp4CkafFGIp+W0VKw4a22sgebPT99y+FDNMdP4w==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/types": "^7.22.15" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-module-transforms": { + "version": "7.22.20", + "resolved": "https://registry.npmjs.org/@babel/helper-module-transforms/-/helper-module-transforms-7.22.20.tgz", + "integrity": "sha512-dLT7JVWIUUxKOs1UnJUBR3S70YK+pKX6AbJgB2vMIvEkZkrfJDbYDJesnPshtKV4LhDOR3Oc5YULeDizRek+5A==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-environment-visitor": "^7.22.20", + "@babel/helper-module-imports": "^7.22.15", + "@babel/helper-simple-access": "^7.22.5", + "@babel/helper-split-export-declaration": "^7.22.6", + "@babel/helper-validator-identifier": "^7.22.20" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0" + } + }, + "node_modules/@babel/helper-optimise-call-expression": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/helper-optimise-call-expression/-/helper-optimise-call-expression-7.22.5.tgz", + "integrity": "sha512-HBwaojN0xFRx4yIvpwGqxiV2tUfl7401jlok564NgB9EHS1y6QT17FmKWm4ztqjeVdXLuC4fSvHc5ePpQjoTbw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/types": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-plugin-utils": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/helper-plugin-utils/-/helper-plugin-utils-7.22.5.tgz", + "integrity": "sha512-uLls06UVKgFG9QD4OeFYLEGteMIAa5kpTPcFL28yuCIIzsf6ZyKZMllKVOCZFhiZ5ptnwX4mtKdWCBE/uT4amg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-remap-async-to-generator": { + "version": "7.22.20", + "resolved": "https://registry.npmjs.org/@babel/helper-remap-async-to-generator/-/helper-remap-async-to-generator-7.22.20.tgz", + "integrity": "sha512-pBGyV4uBqOns+0UvhsTO8qgl8hO89PmiDYv+/COyp1aeMcmfrfruz+/nCMFiYyFF/Knn0yfrC85ZzNFjembFTw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-annotate-as-pure": "^7.22.5", + "@babel/helper-environment-visitor": "^7.22.20", + "@babel/helper-wrap-function": "^7.22.20" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0" + } + }, + "node_modules/@babel/helper-replace-supers": { + "version": "7.22.20", + "resolved": "https://registry.npmjs.org/@babel/helper-replace-supers/-/helper-replace-supers-7.22.20.tgz", + "integrity": "sha512-qsW0In3dbwQUbK8kejJ4R7IHVGwHJlV6lpG6UA7a9hSa2YEiAib+N1T2kr6PEeUT+Fl7najmSOS6SmAwCHK6Tw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-environment-visitor": "^7.22.20", + "@babel/helper-member-expression-to-functions": "^7.22.15", + "@babel/helper-optimise-call-expression": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0" + } + }, + "node_modules/@babel/helper-simple-access": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/helper-simple-access/-/helper-simple-access-7.22.5.tgz", + "integrity": "sha512-n0H99E/K+Bika3++WNL17POvo4rKWZ7lZEp1Q+fStVbUi8nxPQEBOlTmCOxW/0JsS56SKKQ+ojAe2pHKJHN35w==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/types": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-skip-transparent-expression-wrappers": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/helper-skip-transparent-expression-wrappers/-/helper-skip-transparent-expression-wrappers-7.22.5.tgz", + "integrity": "sha512-tK14r66JZKiC43p8Ki33yLBVJKlQDFoA8GYN67lWCDCqoL6EMMSuM9b+Iff2jHaM/RRFYl7K+iiru7hbRqNx8Q==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/types": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-split-export-declaration": { + "version": "7.22.6", + "resolved": "https://registry.npmjs.org/@babel/helper-split-export-declaration/-/helper-split-export-declaration-7.22.6.tgz", + "integrity": "sha512-AsUnxuLhRYsisFiaJwvp1QF+I3KjD5FOxut14q/GzovUe6orHLesW2C7d754kRm53h5gqrz6sFl6sxc4BVtE/g==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/types": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-string-parser": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.22.5.tgz", + "integrity": "sha512-mM4COjgZox8U+JcXQwPijIZLElkgEpO5rsERVDJTc2qfCDfERyob6k5WegS14SX18IIjv+XD+GrqNumY5JRCDw==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-validator-identifier": { + "version": "7.22.20", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.22.20.tgz", + "integrity": "sha512-Y4OZ+ytlatR8AI+8KZfKuL5urKp7qey08ha31L8b3BwewJAoJamTzyvxPR/5D+KkdJCGPq/+8TukHBlY10FX9A==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-validator-option": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-option/-/helper-validator-option-7.22.15.tgz", + "integrity": "sha512-bMn7RmyFjY/mdECUbgn9eoSY4vqvacUnS9i9vGAGttgFWesO6B4CYWA7XlpbWgBt71iv/hfbPlynohStqnu5hA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-wrap-function": { + "version": "7.22.20", + "resolved": "https://registry.npmjs.org/@babel/helper-wrap-function/-/helper-wrap-function-7.22.20.tgz", + "integrity": "sha512-pms/UwkOpnQe/PDAEdV/d7dVCoBbB+R4FvYoHGZz+4VPcg7RtYy2KP7S2lbuWM6FCSgob5wshfGESbC/hzNXZw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-function-name": "^7.22.5", + "@babel/template": "^7.22.15", + "@babel/types": "^7.22.19" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helpers": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.22.15.tgz", + "integrity": "sha512-7pAjK0aSdxOwR+CcYAqgWOGy5dcfvzsTIfFTb2odQqW47MDfv14UaJDY6eng8ylM2EaeKXdxaSWESbkmaQHTmw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/template": "^7.22.15", + "@babel/traverse": "^7.22.15", + "@babel/types": "^7.22.15" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/highlight": { + "version": "7.22.20", + "resolved": "https://registry.npmjs.org/@babel/highlight/-/highlight-7.22.20.tgz", + "integrity": "sha512-dkdMCN3py0+ksCgYmGG8jKeGA/8Tk+gJwSYYlFGxG5lmhfKNoAy004YpLxpS1W2J8m/EK2Ew+yOs9pVRwO89mg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-validator-identifier": "^7.22.20", + "chalk": "^2.4.2", + "js-tokens": "^4.0.0" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/highlight/node_modules/ansi-styles": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", + "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", + "license": "MIT", + "peer": true, + "dependencies": { + "color-convert": "^1.9.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/@babel/highlight/node_modules/chalk": { + "version": "2.4.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz", + "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "ansi-styles": "^3.2.1", + "escape-string-regexp": "^1.0.5", + "supports-color": "^5.3.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/@babel/highlight/node_modules/color-convert": { + "version": "1.9.3", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", + "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", + "license": "MIT", + "peer": true, + "dependencies": { + "color-name": "1.1.3" + } + }, + "node_modules/@babel/highlight/node_modules/color-name": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", + "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==", + "license": "MIT", + "peer": true + }, + "node_modules/@babel/highlight/node_modules/escape-string-regexp": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", + "integrity": "sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.8.0" + } + }, + "node_modules/@babel/highlight/node_modules/has-flag": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", + "integrity": "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/@babel/highlight/node_modules/supports-color": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", + "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==", + "license": "MIT", + "peer": true, + "dependencies": { + "has-flag": "^3.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/@babel/parser": { + "version": "7.22.16", + "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.22.16.tgz", + "integrity": "sha512-+gPfKv8UWeKKeJTUxe59+OobVcrYHETCsORl61EmSkmgymguYk/X5bp7GuUIXaFsc6y++v8ZxPsLSSuujqDphA==", + "license": "MIT", + "peer": true, + "bin": { + "parser": "bin/babel-parser.js" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@babel/plugin-bugfix-safari-id-destructuring-collision-in-function-expression": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/plugin-bugfix-safari-id-destructuring-collision-in-function-expression/-/plugin-bugfix-safari-id-destructuring-collision-in-function-expression-7.22.15.tgz", + "integrity": "sha512-FB9iYlz7rURmRJyXRKEnalYPPdn87H5no108cyuQQyMwlpJ2SJtpIUBI27kdTin956pz+LPypkPVPUTlxOmrsg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0" + } + }, + "node_modules/@babel/plugin-bugfix-v8-spread-parameters-in-optional-chaining": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/plugin-bugfix-v8-spread-parameters-in-optional-chaining/-/plugin-bugfix-v8-spread-parameters-in-optional-chaining-7.22.15.tgz", + "integrity": "sha512-Hyph9LseGvAeeXzikV88bczhsrLrIZqDPxO+sSmAunMPaGrBGhfMWzCPYTtiW9t+HzSE2wtV8e5cc5P6r1xMDQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/helper-skip-transparent-expression-wrappers": "^7.22.5", + "@babel/plugin-transform-optional-chaining": "^7.22.15" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.13.0" + } + }, + "node_modules/@babel/plugin-proposal-async-generator-functions": { + "version": "7.20.7", + "resolved": "https://registry.npmjs.org/@babel/plugin-proposal-async-generator-functions/-/plugin-proposal-async-generator-functions-7.20.7.tgz", + "integrity": "sha512-xMbiLsn/8RK7Wq7VeVytytS2L6qE69bXPB10YCmMdDZbKF4okCqY74pI/jJQ/8U0b/F6NrT2+14b8/P9/3AMGA==", + "deprecated": "This proposal has been merged to the ECMAScript standard and thus this plugin is no longer maintained. Please use @babel/plugin-transform-async-generator-functions instead.", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-environment-visitor": "^7.18.9", + "@babel/helper-plugin-utils": "^7.20.2", + "@babel/helper-remap-async-to-generator": "^7.18.9", + "@babel/plugin-syntax-async-generators": "^7.8.4" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-proposal-class-properties": { + "version": "7.18.6", + "resolved": "https://registry.npmjs.org/@babel/plugin-proposal-class-properties/-/plugin-proposal-class-properties-7.18.6.tgz", + "integrity": "sha512-cumfXOF0+nzZrrN8Rf0t7M+tF6sZc7vhQwYQck9q1/5w2OExlD+b4v4RpMJFaV1Z7WcDRgO6FqvxqxGlwo+RHQ==", + "deprecated": "This proposal has been merged to the ECMAScript standard and thus this plugin is no longer maintained. Please use @babel/plugin-transform-class-properties instead.", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-create-class-features-plugin": "^7.18.6", + "@babel/helper-plugin-utils": "^7.18.6" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-proposal-export-default-from": { + "version": "7.22.17", + "resolved": "https://registry.npmjs.org/@babel/plugin-proposal-export-default-from/-/plugin-proposal-export-default-from-7.22.17.tgz", + "integrity": "sha512-cop/3quQBVvdz6X5SJC6AhUv3C9DrVTM06LUEXimEdWAhCSyOJIr9NiZDU9leHZ0/aiG0Sh7Zmvaku5TWYNgbA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/plugin-syntax-export-default-from": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-proposal-nullish-coalescing-operator": { + "version": "7.18.6", + "resolved": "https://registry.npmjs.org/@babel/plugin-proposal-nullish-coalescing-operator/-/plugin-proposal-nullish-coalescing-operator-7.18.6.tgz", + "integrity": "sha512-wQxQzxYeJqHcfppzBDnm1yAY0jSRkUXR2z8RePZYrKwMKgMlE8+Z6LUno+bd6LvbGh8Gltvy74+9pIYkr+XkKA==", + "deprecated": "This proposal has been merged to the ECMAScript standard and thus this plugin is no longer maintained. Please use @babel/plugin-transform-nullish-coalescing-operator instead.", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.18.6", + "@babel/plugin-syntax-nullish-coalescing-operator": "^7.8.3" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-proposal-numeric-separator": { + "version": "7.18.6", + "resolved": "https://registry.npmjs.org/@babel/plugin-proposal-numeric-separator/-/plugin-proposal-numeric-separator-7.18.6.tgz", + "integrity": "sha512-ozlZFogPqoLm8WBr5Z8UckIoE4YQ5KESVcNudyXOR8uqIkliTEgJ3RoketfG6pmzLdeZF0H/wjE9/cCEitBl7Q==", + "deprecated": "This proposal has been merged to the ECMAScript standard and thus this plugin is no longer maintained. Please use @babel/plugin-transform-numeric-separator instead.", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.18.6", + "@babel/plugin-syntax-numeric-separator": "^7.10.4" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-proposal-object-rest-spread": { + "version": "7.20.7", + "resolved": "https://registry.npmjs.org/@babel/plugin-proposal-object-rest-spread/-/plugin-proposal-object-rest-spread-7.20.7.tgz", + "integrity": "sha512-d2S98yCiLxDVmBmE8UjGcfPvNEUbA1U5q5WxaWFUGRzJSVAZqm5W6MbPct0jxnegUZ0niLeNX+IOzEs7wYg9Dg==", + "deprecated": "This proposal has been merged to the ECMAScript standard and thus this plugin is no longer maintained. Please use @babel/plugin-transform-object-rest-spread instead.", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/compat-data": "^7.20.5", + "@babel/helper-compilation-targets": "^7.20.7", + "@babel/helper-plugin-utils": "^7.20.2", + "@babel/plugin-syntax-object-rest-spread": "^7.8.3", + "@babel/plugin-transform-parameters": "^7.20.7" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-proposal-optional-catch-binding": { + "version": "7.18.6", + "resolved": "https://registry.npmjs.org/@babel/plugin-proposal-optional-catch-binding/-/plugin-proposal-optional-catch-binding-7.18.6.tgz", + "integrity": "sha512-Q40HEhs9DJQyaZfUjjn6vE8Cv4GmMHCYuMGIWUnlxH6400VGxOuwWsPt4FxXxJkC/5eOzgn0z21M9gMT4MOhbw==", + "deprecated": "This proposal has been merged to the ECMAScript standard and thus this plugin is no longer maintained. Please use @babel/plugin-transform-optional-catch-binding instead.", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.18.6", + "@babel/plugin-syntax-optional-catch-binding": "^7.8.3" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-proposal-optional-chaining": { + "version": "7.21.0", + "resolved": "https://registry.npmjs.org/@babel/plugin-proposal-optional-chaining/-/plugin-proposal-optional-chaining-7.21.0.tgz", + "integrity": "sha512-p4zeefM72gpmEe2fkUr/OnOXpWEf8nAgk7ZYVqqfFiyIG7oFfVZcCrU64hWn5xp4tQ9LkV4bTIa5rD0KANpKNA==", + "deprecated": "This proposal has been merged to the ECMAScript standard and thus this plugin is no longer maintained. Please use @babel/plugin-transform-optional-chaining instead.", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.20.2", + "@babel/helper-skip-transparent-expression-wrappers": "^7.20.0", + "@babel/plugin-syntax-optional-chaining": "^7.8.3" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-proposal-private-property-in-object": { + "version": "7.21.0-placeholder-for-preset-env.2", + "resolved": "https://registry.npmjs.org/@babel/plugin-proposal-private-property-in-object/-/plugin-proposal-private-property-in-object-7.21.0-placeholder-for-preset-env.2.tgz", + "integrity": "sha512-SOSkfJDddaM7mak6cPEpswyTRnuRltl429hMraQEglW+OkovnCzsiszTmsrlY//qLFjCpQDFRvjdm2wA5pPm9w==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-async-generators": { + "version": "7.8.4", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-async-generators/-/plugin-syntax-async-generators-7.8.4.tgz", + "integrity": "sha512-tycmZxkGfZaxhMRbXlPXuVFpdWlXpir2W4AMhSJgRKzk/eDlIXOhb2LHWoLpDF7TEHylV5zNhykX6KAgHJmTNw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.8.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-class-properties": { + "version": "7.12.13", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-class-properties/-/plugin-syntax-class-properties-7.12.13.tgz", + "integrity": "sha512-fm4idjKla0YahUNgFNLCB0qySdsoPiZP3iQE3rky0mBUtMZ23yDJ9SJdg6dXTSDnulOVqiF3Hgr9nbXvXTQZYA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.12.13" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-class-static-block": { + "version": "7.14.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-class-static-block/-/plugin-syntax-class-static-block-7.14.5.tgz", + "integrity": "sha512-b+YyPmr6ldyNnM6sqYeMWE+bgJcJpO6yS4QD7ymxgH34GBPNDM/THBh8iunyvKIZztiwLH4CJZ0RxTk9emgpjw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.14.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-dynamic-import": { + "version": "7.8.3", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-dynamic-import/-/plugin-syntax-dynamic-import-7.8.3.tgz", + "integrity": "sha512-5gdGbFon+PszYzqs83S3E5mpi7/y/8M9eC90MRTZfduQOYW76ig6SOSPNe41IG5LoP3FGBn2N0RjVDSQiS94kQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.8.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-export-default-from": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-export-default-from/-/plugin-syntax-export-default-from-7.22.5.tgz", + "integrity": "sha512-ODAqWWXB/yReh/jVQDag/3/tl6lgBueQkk/TcfW/59Oykm4c8a55XloX0CTk2k2VJiFWMgHby9xNX29IbCv9dQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-export-namespace-from": { + "version": "7.8.3", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-export-namespace-from/-/plugin-syntax-export-namespace-from-7.8.3.tgz", + "integrity": "sha512-MXf5laXo6c1IbEbegDmzGPwGNTsHZmEy6QGznu5Sh2UCWvueywb2ee+CCE4zQiZstxU9BMoQO9i6zUFSY0Kj0Q==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.8.3" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-flow": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-flow/-/plugin-syntax-flow-7.22.5.tgz", + "integrity": "sha512-9RdCl0i+q0QExayk2nOS7853w08yLucnnPML6EN9S8fgMPVtdLDCdx/cOQ/i44Lb9UeQX9A35yaqBBOMMZxPxQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-import-assertions": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-import-assertions/-/plugin-syntax-import-assertions-7.22.5.tgz", + "integrity": "sha512-rdV97N7KqsRzeNGoWUOK6yUsWarLjE5Su/Snk9IYPU9CwkWHs4t+rTGOvffTR8XGkJMTAdLfO0xVnXm8wugIJg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-import-attributes": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-import-attributes/-/plugin-syntax-import-attributes-7.22.5.tgz", + "integrity": "sha512-KwvoWDeNKPETmozyFE0P2rOLqh39EoQHNjqizrI5B8Vt0ZNS7M56s7dAiAqbYfiAYOuIzIh96z3iR2ktgu3tEg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-import-meta": { + "version": "7.10.4", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-import-meta/-/plugin-syntax-import-meta-7.10.4.tgz", + "integrity": "sha512-Yqfm+XDx0+Prh3VSeEQCPU81yC+JWZ2pDPFSS4ZdpfZhp4MkFMaDC1UqseovEKwSUpnIL7+vK+Clp7bfh0iD7g==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.10.4" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-json-strings": { + "version": "7.8.3", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-json-strings/-/plugin-syntax-json-strings-7.8.3.tgz", + "integrity": "sha512-lY6kdGpWHvjoe2vk4WrAapEuBR69EMxZl+RoGRhrFGNYVK8mOPAW8VfbT/ZgrFbXlDNiiaxQnAtgVCZ6jv30EA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.8.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-jsx": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-jsx/-/plugin-syntax-jsx-7.22.5.tgz", + "integrity": "sha512-gvyP4hZrgrs/wWMaocvxZ44Hw0b3W8Pe+cMxc8V1ULQ07oh8VNbIRaoD1LRZVTvD+0nieDKjfgKg89sD7rrKrg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-logical-assignment-operators": { + "version": "7.10.4", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-logical-assignment-operators/-/plugin-syntax-logical-assignment-operators-7.10.4.tgz", + "integrity": "sha512-d8waShlpFDinQ5MtvGU9xDAOzKH47+FFoney2baFIoMr952hKOLp1HR7VszoZvOsV/4+RRszNY7D17ba0te0ig==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.10.4" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-nullish-coalescing-operator": { + "version": "7.8.3", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-nullish-coalescing-operator/-/plugin-syntax-nullish-coalescing-operator-7.8.3.tgz", + "integrity": "sha512-aSff4zPII1u2QD7y+F8oDsz19ew4IGEJg9SVW+bqwpwtfFleiQDMdzA/R+UlWDzfnHFCxxleFT0PMIrR36XLNQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.8.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-numeric-separator": { + "version": "7.10.4", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-numeric-separator/-/plugin-syntax-numeric-separator-7.10.4.tgz", + "integrity": "sha512-9H6YdfkcK/uOnY/K7/aA2xpzaAgkQn37yzWUMRK7OaPOqOpGS1+n0H5hxT9AUw9EsSjPW8SVyMJwYRtWs3X3ug==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.10.4" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-object-rest-spread": { + "version": "7.8.3", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-object-rest-spread/-/plugin-syntax-object-rest-spread-7.8.3.tgz", + "integrity": "sha512-XoqMijGZb9y3y2XskN+P1wUGiVwWZ5JmoDRwx5+3GmEplNyVM2s2Dg8ILFQm8rWM48orGy5YpI5Bl8U1y7ydlA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.8.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-optional-catch-binding": { + "version": "7.8.3", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-optional-catch-binding/-/plugin-syntax-optional-catch-binding-7.8.3.tgz", + "integrity": "sha512-6VPD0Pc1lpTqw0aKoeRTMiB+kWhAoT24PA+ksWSBrFtl5SIRVpZlwN3NNPQjehA2E/91FV3RjLWoVTglWcSV3Q==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.8.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-optional-chaining": { + "version": "7.8.3", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-optional-chaining/-/plugin-syntax-optional-chaining-7.8.3.tgz", + "integrity": "sha512-KoK9ErH1MBlCPxV0VANkXW2/dw4vlbGDrFgz8bmUsBGYkFRcbRwMh6cIJubdPrkxRwuGdtCk0v/wPTKbQgBjkg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.8.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-private-property-in-object": { + "version": "7.14.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-private-property-in-object/-/plugin-syntax-private-property-in-object-7.14.5.tgz", + "integrity": "sha512-0wVnp9dxJ72ZUJDV27ZfbSj6iHLoytYZmh3rFcxNnvsJF3ktkzLDZPy/mA17HGsaQT3/DQsWYX1f1QGWkCoVUg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.14.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-top-level-await": { + "version": "7.14.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-top-level-await/-/plugin-syntax-top-level-await-7.14.5.tgz", + "integrity": "sha512-hx++upLv5U1rgYfwe1xBQUhRmU41NEvpUvrp8jkrSCdvGSnM5/qdRMtylJ6PG5OFkBaHkbTAKTnd3/YyESRHFw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.14.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-typescript": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-typescript/-/plugin-syntax-typescript-7.22.5.tgz", + "integrity": "sha512-1mS2o03i7t1c6VzH6fdQ3OA8tcEIxwG18zIPRp+UY1Ihv6W+XZzBCVxExF9upussPXJ0xE9XRHwMoNs1ep/nRQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-syntax-unicode-sets-regex": { + "version": "7.18.6", + "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-unicode-sets-regex/-/plugin-syntax-unicode-sets-regex-7.18.6.tgz", + "integrity": "sha512-727YkEAPwSIQTv5im8QHz3upqp92JTWhidIC81Tdx4VJYIte/VndKf1qKrfnnhPLiPghStWfvC/iFaMCQu7Nqg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-create-regexp-features-plugin": "^7.18.6", + "@babel/helper-plugin-utils": "^7.18.6" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0" + } + }, + "node_modules/@babel/plugin-transform-arrow-functions": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-arrow-functions/-/plugin-transform-arrow-functions-7.22.5.tgz", + "integrity": "sha512-26lTNXoVRdAnsaDXPpvCNUq+OVWEVC6bx7Vvz9rC53F2bagUWW4u4ii2+h8Fejfh7RYqPxn+libeFBBck9muEw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-async-generator-functions": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-async-generator-functions/-/plugin-transform-async-generator-functions-7.22.15.tgz", + "integrity": "sha512-jBm1Es25Y+tVoTi5rfd5t1KLmL8ogLKpXszboWOTTtGFGz2RKnQe2yn7HbZ+kb/B8N0FVSGQo874NSlOU1T4+w==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-environment-visitor": "^7.22.5", + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/helper-remap-async-to-generator": "^7.22.9", + "@babel/plugin-syntax-async-generators": "^7.8.4" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-async-to-generator": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-async-to-generator/-/plugin-transform-async-to-generator-7.22.5.tgz", + "integrity": "sha512-b1A8D8ZzE/VhNDoV1MSJTnpKkCG5bJo+19R4o4oy03zM7ws8yEMK755j61Dc3EyvdysbqH5BOOTquJ7ZX9C6vQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-module-imports": "^7.22.5", + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/helper-remap-async-to-generator": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-block-scoped-functions": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-block-scoped-functions/-/plugin-transform-block-scoped-functions-7.22.5.tgz", + "integrity": "sha512-tdXZ2UdknEKQWKJP1KMNmuF5Lx3MymtMN/pvA+p/VEkhK8jVcQ1fzSy8KM9qRYhAf2/lV33hoMPKI/xaI9sADA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-block-scoping": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-block-scoping/-/plugin-transform-block-scoping-7.22.15.tgz", + "integrity": "sha512-G1czpdJBZCtngoK1sJgloLiOHUnkb/bLZwqVZD8kXmq0ZnVfTTWUcs9OWtp0mBtYJ+4LQY1fllqBkOIPhXmFmw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-class-properties": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-class-properties/-/plugin-transform-class-properties-7.22.5.tgz", + "integrity": "sha512-nDkQ0NfkOhPTq8YCLiWNxp1+f9fCobEjCb0n8WdbNUBc4IB5V7P1QnX9IjpSoquKrXF5SKojHleVNs2vGeHCHQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-create-class-features-plugin": "^7.22.5", + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-class-static-block": { + "version": "7.22.11", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-class-static-block/-/plugin-transform-class-static-block-7.22.11.tgz", + "integrity": "sha512-GMM8gGmqI7guS/llMFk1bJDkKfn3v3C4KHK9Yg1ey5qcHcOlKb0QvcMrgzvxo+T03/4szNh5lghY+fEC98Kq9g==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-create-class-features-plugin": "^7.22.11", + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/plugin-syntax-class-static-block": "^7.14.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.12.0" + } + }, + "node_modules/@babel/plugin-transform-classes": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-classes/-/plugin-transform-classes-7.22.15.tgz", + "integrity": "sha512-VbbC3PGjBdE0wAWDdHM9G8Gm977pnYI0XpqMd6LrKISj8/DJXEsWqgRuTYaNE9Bv0JGhTZUzHDlMk18IpOuoqw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-annotate-as-pure": "^7.22.5", + "@babel/helper-compilation-targets": "^7.22.15", + "@babel/helper-environment-visitor": "^7.22.5", + "@babel/helper-function-name": "^7.22.5", + "@babel/helper-optimise-call-expression": "^7.22.5", + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/helper-replace-supers": "^7.22.9", + "@babel/helper-split-export-declaration": "^7.22.6", + "globals": "^11.1.0" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-classes/node_modules/globals": { + "version": "11.12.0", + "resolved": "https://registry.npmjs.org/globals/-/globals-11.12.0.tgz", + "integrity": "sha512-WOBp/EEGUiIsJSp7wcv/y6MO+lV9UoncWqxuFfm8eBwzWNgyfBd6Gz+IeKQ9jCmyhoH99g15M3T+QaVHFjizVA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/@babel/plugin-transform-computed-properties": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-computed-properties/-/plugin-transform-computed-properties-7.22.5.tgz", + "integrity": "sha512-4GHWBgRf0krxPX+AaPtgBAlTgTeZmqDynokHOX7aqqAB4tHs3U2Y02zH6ETFdLZGcg9UQSD1WCmkVrE9ErHeOg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/template": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-destructuring": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-destructuring/-/plugin-transform-destructuring-7.22.15.tgz", + "integrity": "sha512-HzG8sFl1ZVGTme74Nw+X01XsUTqERVQ6/RLHo3XjGRzm7XD6QTtfS3NJotVgCGy8BzkDqRjRBD8dAyJn5TuvSQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-dotall-regex": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-dotall-regex/-/plugin-transform-dotall-regex-7.22.5.tgz", + "integrity": "sha512-5/Yk9QxCQCl+sOIB1WelKnVRxTJDSAIxtJLL2/pqL14ZVlbH0fUQUZa/T5/UnQtBNgghR7mfB8ERBKyKPCi7Vw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-create-regexp-features-plugin": "^7.22.5", + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-duplicate-keys": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-duplicate-keys/-/plugin-transform-duplicate-keys-7.22.5.tgz", + "integrity": "sha512-dEnYD+9BBgld5VBXHnF/DbYGp3fqGMsyxKbtD1mDyIA7AkTSpKXFhCVuj/oQVOoALfBs77DudA0BE4d5mcpmqw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-dynamic-import": { + "version": "7.22.11", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-dynamic-import/-/plugin-transform-dynamic-import-7.22.11.tgz", + "integrity": "sha512-g/21plo58sfteWjaO0ZNVb+uEOkJNjAaHhbejrnBmu011l/eNDScmkbjCC3l4FKb10ViaGU4aOkFznSu2zRHgA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/plugin-syntax-dynamic-import": "^7.8.3" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-exponentiation-operator": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-exponentiation-operator/-/plugin-transform-exponentiation-operator-7.22.5.tgz", + "integrity": "sha512-vIpJFNM/FjZ4rh1myqIya9jXwrwwgFRHPjT3DkUA9ZLHuzox8jiXkOLvwm1H+PQIP3CqfC++WPKeuDi0Sjdj1g==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-builder-binary-assignment-operator-visitor": "^7.22.5", + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-export-namespace-from": { + "version": "7.22.11", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-export-namespace-from/-/plugin-transform-export-namespace-from-7.22.11.tgz", + "integrity": "sha512-xa7aad7q7OiT8oNZ1mU7NrISjlSkVdMbNxn9IuLZyL9AJEhs1Apba3I+u5riX1dIkdptP5EKDG5XDPByWxtehw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/plugin-syntax-export-namespace-from": "^7.8.3" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-flow-strip-types": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-flow-strip-types/-/plugin-transform-flow-strip-types-7.22.5.tgz", + "integrity": "sha512-tujNbZdxdG0/54g/oua8ISToaXTFBf8EnSb5PgQSciIXWOWKX3S4+JR7ZE9ol8FZwf9kxitzkGQ+QWeov/mCiA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/plugin-syntax-flow": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-for-of": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-for-of/-/plugin-transform-for-of-7.22.15.tgz", + "integrity": "sha512-me6VGeHsx30+xh9fbDLLPi0J1HzmeIIyenoOQHuw2D4m2SAU3NrspX5XxJLBpqn5yrLzrlw2Iy3RA//Bx27iOA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-function-name": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-function-name/-/plugin-transform-function-name-7.22.5.tgz", + "integrity": "sha512-UIzQNMS0p0HHiQm3oelztj+ECwFnj+ZRV4KnguvlsD2of1whUeM6o7wGNj6oLwcDoAXQ8gEqfgC24D+VdIcevg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-compilation-targets": "^7.22.5", + "@babel/helper-function-name": "^7.22.5", + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-json-strings": { + "version": "7.22.11", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-json-strings/-/plugin-transform-json-strings-7.22.11.tgz", + "integrity": "sha512-CxT5tCqpA9/jXFlme9xIBCc5RPtdDq3JpkkhgHQqtDdiTnTI0jtZ0QzXhr5DILeYifDPp2wvY2ad+7+hLMW5Pw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/plugin-syntax-json-strings": "^7.8.3" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-literals": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-literals/-/plugin-transform-literals-7.22.5.tgz", + "integrity": "sha512-fTLj4D79M+mepcw3dgFBTIDYpbcB9Sm0bpm4ppXPaO+U+PKFFyV9MGRvS0gvGw62sd10kT5lRMKXAADb9pWy8g==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-logical-assignment-operators": { + "version": "7.22.11", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-logical-assignment-operators/-/plugin-transform-logical-assignment-operators-7.22.11.tgz", + "integrity": "sha512-qQwRTP4+6xFCDV5k7gZBF3C31K34ut0tbEcTKxlX/0KXxm9GLcO14p570aWxFvVzx6QAfPgq7gaeIHXJC8LswQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/plugin-syntax-logical-assignment-operators": "^7.10.4" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-member-expression-literals": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-member-expression-literals/-/plugin-transform-member-expression-literals-7.22.5.tgz", + "integrity": "sha512-RZEdkNtzzYCFl9SE9ATaUMTj2hqMb4StarOJLrZRbqqU4HSBE7UlBw9WBWQiDzrJZJdUWiMTVDI6Gv/8DPvfew==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-modules-amd": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-modules-amd/-/plugin-transform-modules-amd-7.22.5.tgz", + "integrity": "sha512-R+PTfLTcYEmb1+kK7FNkhQ1gP4KgjpSO6HfH9+f8/yfp2Nt3ggBjiVpRwmwTlfqZLafYKJACy36yDXlEmI9HjQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-module-transforms": "^7.22.5", + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-modules-commonjs": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-modules-commonjs/-/plugin-transform-modules-commonjs-7.22.15.tgz", + "integrity": "sha512-jWL4eh90w0HQOTKP2MoXXUpVxilxsB2Vl4ji69rSjS3EcZ/v4sBmn+A3NpepuJzBhOaEBbR7udonlHHn5DWidg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-module-transforms": "^7.22.15", + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/helper-simple-access": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-modules-systemjs": { + "version": "7.22.11", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-modules-systemjs/-/plugin-transform-modules-systemjs-7.22.11.tgz", + "integrity": "sha512-rIqHmHoMEOhI3VkVf5jQ15l539KrwhzqcBO6wdCNWPWc/JWt9ILNYNUssbRpeq0qWns8svuw8LnMNCvWBIJ8wA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-hoist-variables": "^7.22.5", + "@babel/helper-module-transforms": "^7.22.9", + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/helper-validator-identifier": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-modules-umd": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-modules-umd/-/plugin-transform-modules-umd-7.22.5.tgz", + "integrity": "sha512-+S6kzefN/E1vkSsKx8kmQuqeQsvCKCd1fraCM7zXm4SFoggI099Tr4G8U81+5gtMdUeMQ4ipdQffbKLX0/7dBQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-module-transforms": "^7.22.5", + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-named-capturing-groups-regex": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-named-capturing-groups-regex/-/plugin-transform-named-capturing-groups-regex-7.22.5.tgz", + "integrity": "sha512-YgLLKmS3aUBhHaxp5hi1WJTgOUb/NCuDHzGT9z9WTt3YG+CPRhJs6nprbStx6DnWM4dh6gt7SU3sZodbZ08adQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-create-regexp-features-plugin": "^7.22.5", + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0" + } + }, + "node_modules/@babel/plugin-transform-new-target": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-new-target/-/plugin-transform-new-target-7.22.5.tgz", + "integrity": "sha512-AsF7K0Fx/cNKVyk3a+DW0JLo+Ua598/NxMRvxDnkpCIGFh43+h/v2xyhRUYf6oD8gE4QtL83C7zZVghMjHd+iw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-nullish-coalescing-operator": { + "version": "7.22.11", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-nullish-coalescing-operator/-/plugin-transform-nullish-coalescing-operator-7.22.11.tgz", + "integrity": "sha512-YZWOw4HxXrotb5xsjMJUDlLgcDXSfO9eCmdl1bgW4+/lAGdkjaEvOnQ4p5WKKdUgSzO39dgPl0pTnfxm0OAXcg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/plugin-syntax-nullish-coalescing-operator": "^7.8.3" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-numeric-separator": { + "version": "7.22.11", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-numeric-separator/-/plugin-transform-numeric-separator-7.22.11.tgz", + "integrity": "sha512-3dzU4QGPsILdJbASKhF/V2TVP+gJya1PsueQCxIPCEcerqF21oEcrob4mzjsp2Py/1nLfF5m+xYNMDpmA8vffg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/plugin-syntax-numeric-separator": "^7.10.4" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-object-rest-spread": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-object-rest-spread/-/plugin-transform-object-rest-spread-7.22.15.tgz", + "integrity": "sha512-fEB+I1+gAmfAyxZcX1+ZUwLeAuuf8VIg67CTznZE0MqVFumWkh8xWtn58I4dxdVf080wn7gzWoF8vndOViJe9Q==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/compat-data": "^7.22.9", + "@babel/helper-compilation-targets": "^7.22.15", + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/plugin-syntax-object-rest-spread": "^7.8.3", + "@babel/plugin-transform-parameters": "^7.22.15" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-object-super": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-object-super/-/plugin-transform-object-super-7.22.5.tgz", + "integrity": "sha512-klXqyaT9trSjIUrcsYIfETAzmOEZL3cBYqOYLJxBHfMFFggmXOv+NYSX/Jbs9mzMVESw/WycLFPRx8ba/b2Ipw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/helper-replace-supers": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-optional-catch-binding": { + "version": "7.22.11", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-optional-catch-binding/-/plugin-transform-optional-catch-binding-7.22.11.tgz", + "integrity": "sha512-rli0WxesXUeCJnMYhzAglEjLWVDF6ahb45HuprcmQuLidBJFWjNnOzssk2kuc6e33FlLaiZhG/kUIzUMWdBKaQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/plugin-syntax-optional-catch-binding": "^7.8.3" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-optional-chaining": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-optional-chaining/-/plugin-transform-optional-chaining-7.22.15.tgz", + "integrity": "sha512-ngQ2tBhq5vvSJw2Q2Z9i7ealNkpDMU0rGWnHPKqRZO0tzZ5tlaoz4hDvhXioOoaE0X2vfNss1djwg0DXlfu30A==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/helper-skip-transparent-expression-wrappers": "^7.22.5", + "@babel/plugin-syntax-optional-chaining": "^7.8.3" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-parameters": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-parameters/-/plugin-transform-parameters-7.22.15.tgz", + "integrity": "sha512-hjk7qKIqhyzhhUvRT683TYQOFa/4cQKwQy7ALvTpODswN40MljzNDa0YldevS6tGbxwaEKVn502JmY0dP7qEtQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-private-methods": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-private-methods/-/plugin-transform-private-methods-7.22.5.tgz", + "integrity": "sha512-PPjh4gyrQnGe97JTalgRGMuU4icsZFnWkzicB/fUtzlKUqvsWBKEpPPfr5a2JiyirZkHxnAqkQMO5Z5B2kK3fA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-create-class-features-plugin": "^7.22.5", + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-private-property-in-object": { + "version": "7.22.11", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-private-property-in-object/-/plugin-transform-private-property-in-object-7.22.11.tgz", + "integrity": "sha512-sSCbqZDBKHetvjSwpyWzhuHkmW5RummxJBVbYLkGkaiTOWGxml7SXt0iWa03bzxFIx7wOj3g/ILRd0RcJKBeSQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-annotate-as-pure": "^7.22.5", + "@babel/helper-create-class-features-plugin": "^7.22.11", + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/plugin-syntax-private-property-in-object": "^7.14.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-property-literals": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-property-literals/-/plugin-transform-property-literals-7.22.5.tgz", + "integrity": "sha512-TiOArgddK3mK/x1Qwf5hay2pxI6wCZnvQqrFSqbtg1GLl2JcNMitVH/YnqjP+M31pLUeTfzY1HAXFDnUBV30rQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-react-display-name": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-react-display-name/-/plugin-transform-react-display-name-7.22.5.tgz", + "integrity": "sha512-PVk3WPYudRF5z4GKMEYUrLjPl38fJSKNaEOkFuoprioowGuWN6w2RKznuFNSlJx7pzzXXStPUnNSOEO0jL5EVw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-react-jsx": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-react-jsx/-/plugin-transform-react-jsx-7.22.15.tgz", + "integrity": "sha512-oKckg2eZFa8771O/5vi7XeTvmM6+O9cxZu+kanTU7tD4sin5nO/G8jGJhq8Hvt2Z0kUoEDRayuZLaUlYl8QuGA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-annotate-as-pure": "^7.22.5", + "@babel/helper-module-imports": "^7.22.15", + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/plugin-syntax-jsx": "^7.22.5", + "@babel/types": "^7.22.15" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-react-jsx-self": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-react-jsx-self/-/plugin-transform-react-jsx-self-7.22.5.tgz", + "integrity": "sha512-nTh2ogNUtxbiSbxaT4Ds6aXnXEipHweN9YRgOX/oNXdf0cCrGn/+2LozFa3lnPV5D90MkjhgckCPBrsoSc1a7g==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-react-jsx-source": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-react-jsx-source/-/plugin-transform-react-jsx-source-7.22.5.tgz", + "integrity": "sha512-yIiRO6yobeEIaI0RTbIr8iAK9FcBHLtZq0S89ZPjDLQXBA4xvghaKqI0etp/tF3htTM0sazJKKLz9oEiGRtu7w==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-regenerator": { + "version": "7.22.10", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-regenerator/-/plugin-transform-regenerator-7.22.10.tgz", + "integrity": "sha512-F28b1mDt8KcT5bUyJc/U9nwzw6cV+UmTeRlXYIl2TNqMMJif0Jeey9/RQ3C4NOd2zp0/TRsDns9ttj2L523rsw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "regenerator-transform": "^0.15.2" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-reserved-words": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-reserved-words/-/plugin-transform-reserved-words-7.22.5.tgz", + "integrity": "sha512-DTtGKFRQUDm8svigJzZHzb/2xatPc6TzNvAIJ5GqOKDsGFYgAskjRulbR/vGsPKq3OPqtexnz327qYpP57RFyA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-runtime": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-runtime/-/plugin-transform-runtime-7.22.15.tgz", + "integrity": "sha512-tEVLhk8NRZSmwQ0DJtxxhTrCht1HVo8VaMzYT4w6lwyKBuHsgoioAUA7/6eT2fRfc5/23fuGdlwIxXhRVgWr4g==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-module-imports": "^7.22.15", + "@babel/helper-plugin-utils": "^7.22.5", + "babel-plugin-polyfill-corejs2": "^0.4.5", + "babel-plugin-polyfill-corejs3": "^0.8.3", + "babel-plugin-polyfill-regenerator": "^0.5.2", + "semver": "^6.3.1" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-runtime/node_modules/semver": { + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", + "license": "ISC", + "peer": true, + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/@babel/plugin-transform-shorthand-properties": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-shorthand-properties/-/plugin-transform-shorthand-properties-7.22.5.tgz", + "integrity": "sha512-vM4fq9IXHscXVKzDv5itkO1X52SmdFBFcMIBZ2FRn2nqVYqw6dBexUgMvAjHW+KXpPPViD/Yo3GrDEBaRC0QYA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-spread": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-spread/-/plugin-transform-spread-7.22.5.tgz", + "integrity": "sha512-5ZzDQIGyvN4w8+dMmpohL6MBo+l2G7tfC/O2Dg7/hjpgeWvUx8FzfeOKxGog9IimPa4YekaQ9PlDqTLOljkcxg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/helper-skip-transparent-expression-wrappers": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-sticky-regex": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-sticky-regex/-/plugin-transform-sticky-regex-7.22.5.tgz", + "integrity": "sha512-zf7LuNpHG0iEeiyCNwX4j3gDg1jgt1k3ZdXBKbZSoA3BbGQGvMiSvfbZRR3Dr3aeJe3ooWFZxOOG3IRStYp2Bw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-template-literals": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-template-literals/-/plugin-transform-template-literals-7.22.5.tgz", + "integrity": "sha512-5ciOehRNf+EyUeewo8NkbQiUs4d6ZxiHo6BcBcnFlgiJfu16q0bQUw9Jvo0b0gBKFG1SMhDSjeKXSYuJLeFSMA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-typeof-symbol": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-typeof-symbol/-/plugin-transform-typeof-symbol-7.22.5.tgz", + "integrity": "sha512-bYkI5lMzL4kPii4HHEEChkD0rkc+nvnlR6+o/qdqR6zrm0Sv/nodmyLhlq2DO0YKLUNd2VePmPRjJXSBh9OIdA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-typescript": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-typescript/-/plugin-transform-typescript-7.22.15.tgz", + "integrity": "sha512-1uirS0TnijxvQLnlv5wQBwOX3E1wCFX7ITv+9pBV2wKEk4K+M5tqDaoNXnTH8tjEIYHLO98MwiTWO04Ggz4XuA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-annotate-as-pure": "^7.22.5", + "@babel/helper-create-class-features-plugin": "^7.22.15", + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/plugin-syntax-typescript": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-unicode-escapes": { + "version": "7.22.10", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-unicode-escapes/-/plugin-transform-unicode-escapes-7.22.10.tgz", + "integrity": "sha512-lRfaRKGZCBqDlRU3UIFovdp9c9mEvlylmpod0/OatICsSfuQ9YFthRo1tpTkGsklEefZdqlEFdY4A2dwTb6ohg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-unicode-property-regex": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-unicode-property-regex/-/plugin-transform-unicode-property-regex-7.22.5.tgz", + "integrity": "sha512-HCCIb+CbJIAE6sXn5CjFQXMwkCClcOfPCzTlilJ8cUatfzwHlWQkbtV0zD338u9dZskwvuOYTuuaMaA8J5EI5A==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-create-regexp-features-plugin": "^7.22.5", + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-unicode-regex": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-unicode-regex/-/plugin-transform-unicode-regex-7.22.5.tgz", + "integrity": "sha512-028laaOKptN5vHJf9/Arr/HiJekMd41hOEZYvNsrsXqJ7YPYuX2bQxh31fkZzGmq3YqHRJzYFFAVYvKfMPKqyg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-create-regexp-features-plugin": "^7.22.5", + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-unicode-sets-regex": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-unicode-sets-regex/-/plugin-transform-unicode-sets-regex-7.22.5.tgz", + "integrity": "sha512-lhMfi4FC15j13eKrh3DnYHjpGj6UKQHtNKTbtc1igvAhRy4+kLhV07OpLcsN0VgDEw/MjAvJO4BdMJsHwMhzCg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-create-regexp-features-plugin": "^7.22.5", + "@babel/helper-plugin-utils": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0" + } + }, + "node_modules/@babel/preset-env": { + "version": "7.22.20", + "resolved": "https://registry.npmjs.org/@babel/preset-env/-/preset-env-7.22.20.tgz", + "integrity": "sha512-11MY04gGC4kSzlPHRfvVkNAZhUxOvm7DCJ37hPDnUENwe06npjIRAfInEMTGSb4LZK5ZgDFkv5hw0lGebHeTyg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/compat-data": "^7.22.20", + "@babel/helper-compilation-targets": "^7.22.15", + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/helper-validator-option": "^7.22.15", + "@babel/plugin-bugfix-safari-id-destructuring-collision-in-function-expression": "^7.22.15", + "@babel/plugin-bugfix-v8-spread-parameters-in-optional-chaining": "^7.22.15", + "@babel/plugin-proposal-private-property-in-object": "7.21.0-placeholder-for-preset-env.2", + "@babel/plugin-syntax-async-generators": "^7.8.4", + "@babel/plugin-syntax-class-properties": "^7.12.13", + "@babel/plugin-syntax-class-static-block": "^7.14.5", + "@babel/plugin-syntax-dynamic-import": "^7.8.3", + "@babel/plugin-syntax-export-namespace-from": "^7.8.3", + "@babel/plugin-syntax-import-assertions": "^7.22.5", + "@babel/plugin-syntax-import-attributes": "^7.22.5", + "@babel/plugin-syntax-import-meta": "^7.10.4", + "@babel/plugin-syntax-json-strings": "^7.8.3", + "@babel/plugin-syntax-logical-assignment-operators": "^7.10.4", + "@babel/plugin-syntax-nullish-coalescing-operator": "^7.8.3", + "@babel/plugin-syntax-numeric-separator": "^7.10.4", + "@babel/plugin-syntax-object-rest-spread": "^7.8.3", + "@babel/plugin-syntax-optional-catch-binding": "^7.8.3", + "@babel/plugin-syntax-optional-chaining": "^7.8.3", + "@babel/plugin-syntax-private-property-in-object": "^7.14.5", + "@babel/plugin-syntax-top-level-await": "^7.14.5", + "@babel/plugin-syntax-unicode-sets-regex": "^7.18.6", + "@babel/plugin-transform-arrow-functions": "^7.22.5", + "@babel/plugin-transform-async-generator-functions": "^7.22.15", + "@babel/plugin-transform-async-to-generator": "^7.22.5", + "@babel/plugin-transform-block-scoped-functions": "^7.22.5", + "@babel/plugin-transform-block-scoping": "^7.22.15", + "@babel/plugin-transform-class-properties": "^7.22.5", + "@babel/plugin-transform-class-static-block": "^7.22.11", + "@babel/plugin-transform-classes": "^7.22.15", + "@babel/plugin-transform-computed-properties": "^7.22.5", + "@babel/plugin-transform-destructuring": "^7.22.15", + "@babel/plugin-transform-dotall-regex": "^7.22.5", + "@babel/plugin-transform-duplicate-keys": "^7.22.5", + "@babel/plugin-transform-dynamic-import": "^7.22.11", + "@babel/plugin-transform-exponentiation-operator": "^7.22.5", + "@babel/plugin-transform-export-namespace-from": "^7.22.11", + "@babel/plugin-transform-for-of": "^7.22.15", + "@babel/plugin-transform-function-name": "^7.22.5", + "@babel/plugin-transform-json-strings": "^7.22.11", + "@babel/plugin-transform-literals": "^7.22.5", + "@babel/plugin-transform-logical-assignment-operators": "^7.22.11", + "@babel/plugin-transform-member-expression-literals": "^7.22.5", + "@babel/plugin-transform-modules-amd": "^7.22.5", + "@babel/plugin-transform-modules-commonjs": "^7.22.15", + "@babel/plugin-transform-modules-systemjs": "^7.22.11", + "@babel/plugin-transform-modules-umd": "^7.22.5", + "@babel/plugin-transform-named-capturing-groups-regex": "^7.22.5", + "@babel/plugin-transform-new-target": "^7.22.5", + "@babel/plugin-transform-nullish-coalescing-operator": "^7.22.11", + "@babel/plugin-transform-numeric-separator": "^7.22.11", + "@babel/plugin-transform-object-rest-spread": "^7.22.15", + "@babel/plugin-transform-object-super": "^7.22.5", + "@babel/plugin-transform-optional-catch-binding": "^7.22.11", + "@babel/plugin-transform-optional-chaining": "^7.22.15", + "@babel/plugin-transform-parameters": "^7.22.15", + "@babel/plugin-transform-private-methods": "^7.22.5", + "@babel/plugin-transform-private-property-in-object": "^7.22.11", + "@babel/plugin-transform-property-literals": "^7.22.5", + "@babel/plugin-transform-regenerator": "^7.22.10", + "@babel/plugin-transform-reserved-words": "^7.22.5", + "@babel/plugin-transform-shorthand-properties": "^7.22.5", + "@babel/plugin-transform-spread": "^7.22.5", + "@babel/plugin-transform-sticky-regex": "^7.22.5", + "@babel/plugin-transform-template-literals": "^7.22.5", + "@babel/plugin-transform-typeof-symbol": "^7.22.5", + "@babel/plugin-transform-unicode-escapes": "^7.22.10", + "@babel/plugin-transform-unicode-property-regex": "^7.22.5", + "@babel/plugin-transform-unicode-regex": "^7.22.5", + "@babel/plugin-transform-unicode-sets-regex": "^7.22.5", + "@babel/preset-modules": "0.1.6-no-external-plugins", + "@babel/types": "^7.22.19", + "babel-plugin-polyfill-corejs2": "^0.4.5", + "babel-plugin-polyfill-corejs3": "^0.8.3", + "babel-plugin-polyfill-regenerator": "^0.5.2", + "core-js-compat": "^3.31.0", + "semver": "^6.3.1" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/preset-env/node_modules/semver": { + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", + "license": "ISC", + "peer": true, + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/@babel/preset-flow": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/preset-flow/-/preset-flow-7.22.15.tgz", + "integrity": "sha512-dB5aIMqpkgbTfN5vDdTRPzjqtWiZcRESNR88QYnoPR+bmdYoluOzMX9tQerTv0XzSgZYctPfO1oc0N5zdog1ew==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/helper-validator-option": "^7.22.15", + "@babel/plugin-transform-flow-strip-types": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/preset-modules": { + "version": "0.1.6-no-external-plugins", + "resolved": "https://registry.npmjs.org/@babel/preset-modules/-/preset-modules-0.1.6-no-external-plugins.tgz", + "integrity": "sha512-HrcgcIESLm9aIR842yhJ5RWan/gebQUJ6E/E5+rf0y9o6oj7w0Br+sWuL6kEQ/o/AdfvR1Je9jG18/gnpwjEyA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.0.0", + "@babel/types": "^7.4.4", + "esutils": "^2.0.2" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0 || ^8.0.0-0 <8.0.0" + } + }, + "node_modules/@babel/preset-typescript": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/preset-typescript/-/preset-typescript-7.22.15.tgz", + "integrity": "sha512-HblhNmh6yM+cU4VwbBRpxFhxsTdfS1zsvH9W+gEjD0ARV9+8B4sNfpI6GuhePti84nuvhiwKS539jKPFHskA9A==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-plugin-utils": "^7.22.5", + "@babel/helper-validator-option": "^7.22.15", + "@babel/plugin-syntax-jsx": "^7.22.5", + "@babel/plugin-transform-modules-commonjs": "^7.22.15", + "@babel/plugin-transform-typescript": "^7.22.15" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/register": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/register/-/register-7.22.15.tgz", + "integrity": "sha512-V3Q3EqoQdn65RCgTLwauZaTfd1ShhwPmbBv+1dkZV/HpCGMKVyn6oFcRlI7RaKqiDQjX2Qd3AuoEguBgdjIKlg==", + "license": "MIT", + "peer": true, + "dependencies": { + "clone-deep": "^4.0.1", + "find-cache-dir": "^2.0.0", + "make-dir": "^2.1.0", + "pirates": "^4.0.5", + "source-map-support": "^0.5.16" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/register/node_modules/make-dir": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-2.1.0.tgz", + "integrity": "sha512-LS9X+dc8KLxXCb8dni79fLIIUA5VyZoyjSMCwTluaXA0o27cCK0bhXkpgw+sTXVpPy/lSO57ilRixqk0vDmtRA==", + "license": "MIT", + "peer": true, + "dependencies": { + "pify": "^4.0.1", + "semver": "^5.6.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/@babel/register/node_modules/pify": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/pify/-/pify-4.0.1.tgz", + "integrity": "sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/@babel/register/node_modules/semver": { + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.2.tgz", + "integrity": "sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g==", + "license": "ISC", + "peer": true, + "bin": { + "semver": "bin/semver" + } + }, + "node_modules/@babel/regjsgen": { + "version": "0.8.0", + "resolved": "https://registry.npmjs.org/@babel/regjsgen/-/regjsgen-0.8.0.tgz", + "integrity": "sha512-x/rqGMdzj+fWZvCOYForTghzbtqPDZ5gPwaoNGHdgDfF2QA/XZbCBp4Moo5scrkAMPhB7z26XM/AaHuIJdgauA==", + "license": "MIT", + "peer": true + }, + "node_modules/@babel/runtime": { + "version": "7.22.10", + "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.22.10.tgz", + "integrity": "sha512-21t/fkKLMZI4pqP2wlmsQAWnYW1PDyKyyUV4vCi+B25ydmdaYTKXPwCj0BzSUnZf4seIiYvSA3jcZ3gdsMFkLQ==", + "license": "MIT", + "dependencies": { + "regenerator-runtime": "^0.14.0" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/template": { + "version": "7.22.15", + "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.22.15.tgz", + "integrity": "sha512-QPErUVm4uyJa60rkI73qneDacvdvzxshT3kksGqlGWYdOTIUOwJ7RDUL8sGqslY1uXWSL6xMFKEXDS3ox2uF0w==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/code-frame": "^7.22.13", + "@babel/parser": "^7.22.15", + "@babel/types": "^7.22.15" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/traverse": { + "version": "7.22.20", + "resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.22.20.tgz", + "integrity": "sha512-eU260mPZbU7mZ0N+X10pxXhQFMGTeLb9eFS0mxehS8HZp9o1uSnFeWQuG1UPrlxgA7QoUzFhOnilHDp0AXCyHw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/code-frame": "^7.22.13", + "@babel/generator": "^7.22.15", + "@babel/helper-environment-visitor": "^7.22.20", + "@babel/helper-function-name": "^7.22.5", + "@babel/helper-hoist-variables": "^7.22.5", + "@babel/helper-split-export-declaration": "^7.22.6", + "@babel/parser": "^7.22.16", + "@babel/types": "^7.22.19", + "debug": "^4.1.0", + "globals": "^11.1.0" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/traverse/node_modules/globals": { + "version": "11.12.0", + "resolved": "https://registry.npmjs.org/globals/-/globals-11.12.0.tgz", + "integrity": "sha512-WOBp/EEGUiIsJSp7wcv/y6MO+lV9UoncWqxuFfm8eBwzWNgyfBd6Gz+IeKQ9jCmyhoH99g15M3T+QaVHFjizVA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/@babel/types": { + "version": "7.22.19", + "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.22.19.tgz", + "integrity": "sha512-P7LAw/LbojPzkgp5oznjE6tQEIWbp4PkkfrZDINTro9zgBRtI324/EYsiSI7lhPbpIQ+DCeR2NNmMWANGGfZsg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-string-parser": "^7.22.5", + "@babel/helper-validator-identifier": "^7.22.19", + "to-fast-properties": "^2.0.0" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@cspotcode/source-map-support": { + "version": "0.8.1", + "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz", + "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==", + "license": "MIT", + "dependencies": { + "@jridgewell/trace-mapping": "0.3.9" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/@cspotcode/source-map-support/node_modules/@jridgewell/trace-mapping": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz", + "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==", + "license": "MIT", + "dependencies": { + "@jridgewell/resolve-uri": "^3.0.3", + "@jridgewell/sourcemap-codec": "^1.4.10" + } + }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.5.tgz", + "integrity": "sha512-9o3TMmpmftaCMepOdA5k/yDw8SfInyzWWTjYTFCX3kPSDJMROQTb8jg+h9Cnwnmm1vOzvxN7gIfB5V2ewpjtGA==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.25.5.tgz", + "integrity": "sha512-AdJKSPeEHgi7/ZhuIPtcQKr5RQdo6OO2IL87JkianiMYMPbCtot9fxPbrMiBADOWWm3T2si9stAiVsGbTQFkbA==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.25.5.tgz", + "integrity": "sha512-VGzGhj4lJO+TVGV1v8ntCZWJktV7SGCs3Pn1GRWI1SBFtRALoomm8k5E9Pmwg3HOAal2VDc2F9+PM/rEY6oIDg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.25.5.tgz", + "integrity": "sha512-D2GyJT1kjvO//drbRT3Hib9XPwQeWd9vZoBJn+bu/lVsOZ13cqNdDeqIF/xQ5/VmWvMduP6AmXvylO/PIc2isw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.25.5.tgz", + "integrity": "sha512-GtaBgammVvdF7aPIgH2jxMDdivezgFu6iKpmT+48+F8Hhg5J/sfnDieg0aeG/jfSvkYQU2/pceFPDKlqZzwnfQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.25.5.tgz", + "integrity": "sha512-1iT4FVL0dJ76/q1wd7XDsXrSW+oLoquptvh4CLR4kITDtqi2e/xwXwdCVH8hVHU43wgJdsq7Gxuzcs6Iq/7bxQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.5.tgz", + "integrity": "sha512-nk4tGP3JThz4La38Uy/gzyXtpkPW8zSAmoUhK9xKKXdBCzKODMc2adkB2+8om9BDYugz+uGV7sLmpTYzvmz6Sw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.25.5.tgz", + "integrity": "sha512-PrikaNjiXdR2laW6OIjlbeuCPrPaAl0IwPIaRv+SMV8CiM8i2LqVUHFC1+8eORgWyY7yhQY+2U2fA55mBzReaw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.25.5.tgz", + "integrity": "sha512-cPzojwW2okgh7ZlRpcBEtsX7WBuqbLrNXqLU89GxWbNt6uIg78ET82qifUy3W6OVww6ZWobWub5oqZOVtwolfw==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.25.5.tgz", + "integrity": "sha512-Z9kfb1v6ZlGbWj8EJk9T6czVEjjq2ntSYLY2cw6pAZl4oKtfgQuS4HOq41M/BcoLPzrUbNd+R4BXFyH//nHxVg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.25.5.tgz", + "integrity": "sha512-sQ7l00M8bSv36GLV95BVAdhJ2QsIbCuCjh/uYrWiMQSUuV+LpXwIqhgJDcvMTj+VsQmqAHL2yYaasENvJ7CDKA==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.25.5.tgz", + "integrity": "sha512-0ur7ae16hDUC4OL5iEnDb0tZHDxYmuQyhKhsPBV8f99f6Z9KQM02g33f93rNH5A30agMS46u2HP6qTdEt6Q1kg==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.25.5.tgz", + "integrity": "sha512-kB/66P1OsHO5zLz0i6X0RxlQ+3cu0mkxS3TKFvkb5lin6uwZ/ttOkP3Z8lfR9mJOBk14ZwZ9182SIIWFGNmqmg==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.25.5.tgz", + "integrity": "sha512-UZCmJ7r9X2fe2D6jBmkLBMQetXPXIsZjQJCjgwpVDz+YMcS6oFR27alkgGv3Oqkv07bxdvw7fyB71/olceJhkQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.25.5.tgz", + "integrity": "sha512-kTxwu4mLyeOlsVIFPfQo+fQJAV9mh24xL+y+Bm6ej067sYANjyEw1dNHmvoqxJUCMnkBdKpvOn0Ahql6+4VyeA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.25.5.tgz", + "integrity": "sha512-K2dSKTKfmdh78uJ3NcWFiqyRrimfdinS5ErLSn3vluHNeHVnBAFWC8a4X5N+7FgVE1EjXS1QDZbpqZBjfrqMTQ==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.25.5.tgz", + "integrity": "sha512-uhj8N2obKTE6pSZ+aMUbqq+1nXxNjZIIjCjGLfsWvVpy7gKCOL6rsY1MhRh9zLtUtAI7vpgLMK6DxjO8Qm9lJw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.5.tgz", + "integrity": "sha512-pwHtMP9viAy1oHPvgxtOv+OkduK5ugofNTVDilIzBLpoWAM16r7b/mxBvfpuQDpRQFMfuVr5aLcn4yveGvBZvw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.25.5.tgz", + "integrity": "sha512-WOb5fKrvVTRMfWFNCroYWWklbnXH0Q5rZppjq0vQIdlsQKuw6mdSihwSo4RV/YdQ5UCKKvBy7/0ZZYLBZKIbwQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.5.tgz", + "integrity": "sha512-7A208+uQKgTxHd0G0uqZO8UjK2R0DDb4fDmERtARjSHWxqMTye4Erz4zZafx7Di9Cv+lNHYuncAkiGFySoD+Mw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.25.5.tgz", + "integrity": "sha512-G4hE405ErTWraiZ8UiSoesH8DaCsMm0Cay4fsFWOOUcz8b8rC6uCvnagr+gnioEjWn0wC+o1/TAHt+It+MpIMg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.25.5.tgz", + "integrity": "sha512-l+azKShMy7FxzY0Rj4RCt5VD/q8mG/e+mDivgspo+yL8zW7qEwctQ6YqKX34DTEleFAvCIUviCFX1SDZRSyMQA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.25.5.tgz", + "integrity": "sha512-O2S7SNZzdcFG7eFKgvwUEZ2VG9D/sn/eIiz8XRZ1Q/DO5a3s76Xv0mdBzVM5j5R639lXQmPmSo0iRpHqUUrsxw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.25.5.tgz", + "integrity": "sha512-onOJ02pqs9h1iMJ1PQphR+VZv8qBMQ77Klcsqv9CNW2w6yLqoURLcgERAIurY6QE63bbLuqgP9ATqajFLK5AMQ==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.5.tgz", + "integrity": "sha512-TXv6YnJ8ZMVdX+SXWVBo/0p8LTcrUYngpWjvm91TMjjBQii7Oz11Lw5lbDV5Y0TzuhSJHwiH4hEtC1I42mMS0g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@eslint-community/eslint-utils": { + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.4.0.tgz", + "integrity": "sha512-1/sA4dwrzBAyeUoQ6oxahHKmrZvsnLCg4RfxW3ZFGGmQkSNQPFNLV9CUEFQP1x9EYXHTo5p6xdhZM1Ne9p/AfA==", + "dev": true, + "license": "MIT", + "dependencies": { + "eslint-visitor-keys": "^3.3.0" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "peerDependencies": { + "eslint": "^6.0.0 || ^7.0.0 || >=8.0.0" + } + }, + "node_modules/@eslint-community/regexpp": { + "version": "4.6.2", + "resolved": "https://registry.npmjs.org/@eslint-community/regexpp/-/regexpp-4.6.2.tgz", + "integrity": "sha512-pPTNuaAG3QMH+buKyBIGJs3g/S5y0caxw0ygM3YyE6yJFySwiGGSzA+mM3KJ8QQvzeLh3blwgSonkFjgQdxzMw==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^12.0.0 || ^14.0.0 || >=16.0.0" + } + }, + "node_modules/@eslint/eslintrc": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-2.1.2.tgz", + "integrity": "sha512-+wvgpDsrB1YqAMdEUCcnTlpfVBH7Vqn6A/NT3D8WVXFIaKMlErPIZT3oCIAVCOtarRpMtelZLqJeU3t7WY6X6g==", + "dev": true, + "license": "MIT", + "dependencies": { + "ajv": "^6.12.4", + "debug": "^4.3.2", + "espree": "^9.6.0", + "globals": "^13.19.0", + "ignore": "^5.2.0", + "import-fresh": "^3.2.1", + "js-yaml": "^4.1.0", + "minimatch": "^3.1.2", + "strip-json-comments": "^3.1.1" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/@eslint/js": { + "version": "8.47.0", + "resolved": "https://registry.npmjs.org/@eslint/js/-/js-8.47.0.tgz", + "integrity": "sha512-P6omY1zv5MItm93kLM8s2vr1HICJH8v0dvddDhysbIuZ+vcjOHg5Zbkf1mTkcmi2JA9oBG2anOkRnW8WJTS8Og==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + } + }, + "node_modules/@floating-ui/core": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/@floating-ui/core/-/core-1.4.1.tgz", + "integrity": "sha512-jk3WqquEJRlcyu7997NtR5PibI+y5bi+LS3hPmguVClypenMsCY3CBa3LAQnozRCtCrYWSEtAdiskpamuJRFOQ==", + "license": "MIT", + "dependencies": { + "@floating-ui/utils": "^0.1.1" + } + }, + "node_modules/@floating-ui/dom": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/@floating-ui/dom/-/dom-1.5.1.tgz", + "integrity": "sha512-KwvVcPSXg6mQygvA1TjbN/gh///36kKtllIF8SUm0qpFj8+rvYrpvlYdL1JoA71SHpDqgSSdGOSoQ0Mp3uY5aw==", + "license": "MIT", + "dependencies": { + "@floating-ui/core": "^1.4.1", + "@floating-ui/utils": "^0.1.1" + } + }, + "node_modules/@floating-ui/react-dom": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/@floating-ui/react-dom/-/react-dom-2.0.1.tgz", + "integrity": "sha512-rZtAmSht4Lry6gdhAJDrCp/6rKN7++JnL1/Anbr/DdeyYXQPxvg/ivrbYvJulbRf4vL8b212suwMM2lxbv+RQA==", + "license": "MIT", + "dependencies": { + "@floating-ui/dom": "^1.3.0" + }, + "peerDependencies": { + "react": ">=16.8.0", + "react-dom": ">=16.8.0" + } + }, + "node_modules/@floating-ui/utils": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@floating-ui/utils/-/utils-0.1.1.tgz", + "integrity": "sha512-m0G6wlnhm/AX0H12IOWtK8gASEMffnX08RtKkCgTdHb9JpHKGloI7icFfLg9ZmQeavcvR0PKmzxClyuFPSjKWw==", + "license": "MIT" + }, + "node_modules/@hapi/hoek": { + "version": "9.3.0", + "resolved": "https://registry.npmjs.org/@hapi/hoek/-/hoek-9.3.0.tgz", + "integrity": "sha512-/c6rf4UJlmHlC9b5BaNvzAcFv7HZ2QHaV0D4/HNlBdvFnvQq8RI4kYdhyPCl7Xj+oWvTWQ8ujhqS53LIgAe6KQ==", + "license": "BSD-3-Clause", + "peer": true + }, + "node_modules/@hapi/topo": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/@hapi/topo/-/topo-5.1.0.tgz", + "integrity": "sha512-foQZKJig7Ob0BMAYBfcJk8d77QtOe7Wo4ox7ff1lQYoNNAb6jwcY1ncdoy2e9wQZzvNy7ODZCYJkK8kzmcAnAg==", + "license": "BSD-3-Clause", + "peer": true, + "dependencies": { + "@hapi/hoek": "^9.0.0" + } + }, + "node_modules/@hookform/resolvers": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/@hookform/resolvers/-/resolvers-3.3.1.tgz", + "integrity": "sha512-K7KCKRKjymxIB90nHDQ7b9nli474ru99ZbqxiqDAWYsYhOsU3/4qLxW91y+1n04ic13ajjZ66L3aXbNef8PELQ==", + "license": "MIT", + "peerDependencies": { + "react-hook-form": "^7.0.0" + } + }, + "node_modules/@humanwhocodes/config-array": { + "version": "0.11.10", + "resolved": "https://registry.npmjs.org/@humanwhocodes/config-array/-/config-array-0.11.10.tgz", + "integrity": "sha512-KVVjQmNUepDVGXNuoRRdmmEjruj0KfiGSbS8LVc12LMsWDQzRXJ0qdhN8L8uUigKpfEHRhlaQFY0ib1tnUbNeQ==", + "deprecated": "Use @eslint/config-array instead", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@humanwhocodes/object-schema": "^1.2.1", + "debug": "^4.1.1", + "minimatch": "^3.0.5" + }, + "engines": { + "node": ">=10.10.0" + } + }, + "node_modules/@humanwhocodes/module-importer": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@humanwhocodes/module-importer/-/module-importer-1.0.1.tgz", + "integrity": "sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=12.22" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/nzakas" + } + }, + "node_modules/@humanwhocodes/object-schema": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/@humanwhocodes/object-schema/-/object-schema-1.2.1.tgz", + "integrity": "sha512-ZnQMnLV4e7hDlUvw8H+U8ASL02SS2Gn6+9Ac3wGGLIe7+je2AeAOxPY+izIPJDfFDb7eDjev0Us8MO1iFRN8hA==", + "deprecated": "Use @eslint/object-schema instead", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/@iovalkey/commands": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/@iovalkey/commands/-/commands-0.1.0.tgz", + "integrity": "sha512-/B9W4qKSSITDii5nkBCHyPkIkAi+ealUtr1oqBJsLxjSRLka4pxun2VvMNSmcwgAMxgXtQfl0qRv7TE+udPJzg==", + "license": "MIT" + }, + "node_modules/@jest/create-cache-key-function": { + "version": "29.7.0", + "resolved": "https://registry.npmjs.org/@jest/create-cache-key-function/-/create-cache-key-function-29.7.0.tgz", + "integrity": "sha512-4QqS3LY5PBmTRHj9sAg1HLoPzqAI0uOX6wI/TRqHIcOxlFidy6YEmCQJk6FSZjNLGCeubDMfmkWL+qaLKhSGQA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@jest/types": "^29.6.3" + }, + "engines": { + "node": "^14.15.0 || ^16.10.0 || >=18.0.0" + } + }, + "node_modules/@jest/environment": { + "version": "29.7.0", + "resolved": "https://registry.npmjs.org/@jest/environment/-/environment-29.7.0.tgz", + "integrity": "sha512-aQIfHDq33ExsN4jP1NWGXhxgQ/wixs60gDiKO+XVMd8Mn0NWPWgc34ZQDTb2jKaUWQ7MuwoitXAsN2XVXNMpAw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@jest/fake-timers": "^29.7.0", + "@jest/types": "^29.6.3", + "@types/node": "*", + "jest-mock": "^29.7.0" + }, + "engines": { + "node": "^14.15.0 || ^16.10.0 || >=18.0.0" + } + }, + "node_modules/@jest/fake-timers": { + "version": "29.7.0", + "resolved": "https://registry.npmjs.org/@jest/fake-timers/-/fake-timers-29.7.0.tgz", + "integrity": "sha512-q4DH1Ha4TTFPdxLsqDXK1d3+ioSL7yL5oCMJZgDYm6i+6CygW5E5xVr/D1HdsGxjt1ZWSfUAs9OxSB/BNelWrQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@jest/types": "^29.6.3", + "@sinonjs/fake-timers": "^10.0.2", + "@types/node": "*", + "jest-message-util": "^29.7.0", + "jest-mock": "^29.7.0", + "jest-util": "^29.7.0" + }, + "engines": { + "node": "^14.15.0 || ^16.10.0 || >=18.0.0" + } + }, + "node_modules/@jest/schemas": { + "version": "29.6.3", + "resolved": "https://registry.npmjs.org/@jest/schemas/-/schemas-29.6.3.tgz", + "integrity": "sha512-mo5j5X+jIZmJQveBKeS/clAueipV7KgiX1vMgCxam1RNYiqE1w62n0/tJJnHtjW8ZHcQco5gY85jA3mi0L+nSA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@sinclair/typebox": "^0.27.8" + }, + "engines": { + "node": "^14.15.0 || ^16.10.0 || >=18.0.0" + } + }, + "node_modules/@jest/types": { + "version": "29.6.3", + "resolved": "https://registry.npmjs.org/@jest/types/-/types-29.6.3.tgz", + "integrity": "sha512-u3UPsIilWKOM3F9CXtrG8LEJmNxwoCQC/XVj4IKYXvvpx7QIi/Kg1LI5uDmDpKlac62NUtX7eLjRh+jVZcLOzw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@jest/schemas": "^29.6.3", + "@types/istanbul-lib-coverage": "^2.0.0", + "@types/istanbul-reports": "^3.0.0", + "@types/node": "*", + "@types/yargs": "^17.0.8", + "chalk": "^4.0.0" + }, + "engines": { + "node": "^14.15.0 || ^16.10.0 || >=18.0.0" + } + }, + "node_modules/@jridgewell/gen-mapping": { + "version": "0.3.3", + "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.3.tgz", + "integrity": "sha512-HLhSWOLRi875zjjMG/r+Nv0oCW8umGb0BgEhyX3dDX3egwZtB8PqLnjz3yedt8R5StBrzcg4aBpnh8UA9D1BoQ==", + "license": "MIT", + "dependencies": { + "@jridgewell/set-array": "^1.0.1", + "@jridgewell/sourcemap-codec": "^1.4.10", + "@jridgewell/trace-mapping": "^0.3.9" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@jridgewell/resolve-uri": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.1.tgz", + "integrity": "sha512-dSYZh7HhCDtCKm4QakX0xFpsRDqjjtZf/kjI/v3T3Nwt5r8/qz/M19F9ySyOqU94SXBmeG9ttTul+YnR4LOxFA==", + "license": "MIT", + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@jridgewell/set-array": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@jridgewell/set-array/-/set-array-1.1.2.tgz", + "integrity": "sha512-xnkseuNADM0gt2bs+BvhO0p78Mk762YnZdsuzFV018NoG1Sj1SCQvpSqa7XUaTam5vAGasABV9qXASMKnFMwMw==", + "license": "MIT", + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@jridgewell/source-map": { + "version": "0.3.5", + "resolved": "https://registry.npmjs.org/@jridgewell/source-map/-/source-map-0.3.5.tgz", + "integrity": "sha512-UTYAUj/wviwdsMfzoSJspJxbkH5o1snzwX0//0ENX1u/55kkZZkcTZP6u9bwKGkv+dkk9at4m1Cpt0uY80kcpQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@jridgewell/gen-mapping": "^0.3.0", + "@jridgewell/trace-mapping": "^0.3.9" + } + }, + "node_modules/@jridgewell/sourcemap-codec": { + "version": "1.4.15", + "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.4.15.tgz", + "integrity": "sha512-eF2rxCRulEKXHTRiDrDy6erMYWqNw4LPdQ8UQA4huuxaQsVeRPFl2oM8oDGxMFhJUWZf9McpLtJasDDZb/Bpeg==", + "license": "MIT" + }, + "node_modules/@jridgewell/trace-mapping": { + "version": "0.3.19", + "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.19.tgz", + "integrity": "sha512-kf37QtfW+Hwx/buWGMPcR60iF9ziHa6r/CZJIHbmcm4+0qrXiVdxegAH0F6yddEVQ7zdkjcGCgCzUu+BcbhQxw==", + "license": "MIT", + "dependencies": { + "@jridgewell/resolve-uri": "^3.1.0", + "@jridgewell/sourcemap-codec": "^1.4.14" + } + }, + "node_modules/@mapbox/node-pre-gyp": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/@mapbox/node-pre-gyp/-/node-pre-gyp-1.0.11.tgz", + "integrity": "sha512-Yhlar6v9WQgUp/He7BdgzOz8lqMQ8sU+jkCq7Wx8Myc5YFJLbEe7lgui/V7G1qB1DJykHSGwreceSaD60Y0PUQ==", + "license": "BSD-3-Clause", + "dependencies": { + "detect-libc": "^2.0.0", + "https-proxy-agent": "^5.0.0", + "make-dir": "^3.1.0", + "node-fetch": "^2.6.7", + "nopt": "^5.0.0", + "npmlog": "^5.0.1", + "rimraf": "^3.0.2", + "semver": "^7.3.5", + "tar": "^6.1.11" + }, + "bin": { + "node-pre-gyp": "bin/node-pre-gyp" + } + }, + "node_modules/@mdx-js/loader": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/@mdx-js/loader/-/loader-3.1.0.tgz", + "integrity": "sha512-xU/lwKdOyfXtQGqn3VnJjlDrmKXEvMi1mgYxVmukEUtVycIz1nh7oQ40bKTd4cA7rLStqu0740pnhGYxGoqsCg==", + "license": "MIT", + "dependencies": { + "@mdx-js/mdx": "^3.0.0", + "source-map": "^0.7.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + }, + "peerDependencies": { + "webpack": ">=5" + }, + "peerDependenciesMeta": { + "webpack": { + "optional": true + } + } + }, + "node_modules/@mdx-js/mdx": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/@mdx-js/mdx/-/mdx-3.1.0.tgz", + "integrity": "sha512-/QxEhPAvGwbQmy1Px8F899L5Uc2KZ6JtXwlCgJmjSTBedwOZkByYcBG4GceIGPXRDsmfxhHazuS+hlOShRLeDw==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdx": "^2.0.0", + "collapse-white-space": "^2.0.0", + "devlop": "^1.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "estree-util-scope": "^1.0.0", + "estree-walker": "^3.0.0", + "hast-util-to-jsx-runtime": "^2.0.0", + "markdown-extensions": "^2.0.0", + "recma-build-jsx": "^1.0.0", + "recma-jsx": "^1.0.0", + "recma-stringify": "^1.0.0", + "rehype-recma": "^1.0.0", + "remark-mdx": "^3.0.0", + "remark-parse": "^11.0.0", + "remark-rehype": "^11.0.0", + "source-map": "^0.7.0", + "unified": "^11.0.0", + "unist-util-position-from-estree": "^2.0.0", + "unist-util-stringify-position": "^4.0.0", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/@mdx-js/react": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/@mdx-js/react/-/react-3.1.0.tgz", + "integrity": "sha512-QjHtSaoameoalGnKDT3FoIl4+9RwyTmo9ZJGBdLOks/YOiWHoRDI3PUwEzOE7kEmGcV3AFcp9K6dYu9rEuKLAQ==", + "license": "MIT", + "dependencies": { + "@types/mdx": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + }, + "peerDependencies": { + "@types/react": ">=16", + "react": ">=16" + } + }, + "node_modules/@monaco-editor/loader": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/@monaco-editor/loader/-/loader-1.5.0.tgz", + "integrity": "sha512-hKoGSM+7aAc7eRTRjpqAZucPmoNOC4UUbknb/VNoTkEIkCPhqV8LfbsgM1webRM7S/z21eHEx9Fkwx8Z/C/+Xw==", + "license": "MIT", + "dependencies": { + "state-local": "^1.0.6" + } + }, + "node_modules/@monaco-editor/react": { + "version": "4.7.0", + "resolved": "https://registry.npmjs.org/@monaco-editor/react/-/react-4.7.0.tgz", + "integrity": "sha512-cyzXQCtO47ydzxpQtCGSQGOC8Gk3ZUeBXFAxD+CWXYFo5OqZyZUonFl0DwUlTyAfRHntBfw2p3w4s9R6oe1eCA==", + "license": "MIT", + "dependencies": { + "@monaco-editor/loader": "^1.5.0" + }, + "peerDependencies": { + "monaco-editor": ">= 0.25.0 < 1", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", + "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" + } + }, + "node_modules/@next-auth/prisma-adapter": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/@next-auth/prisma-adapter/-/prisma-adapter-1.0.7.tgz", + "integrity": "sha512-Cdko4KfcmKjsyHFrWwZ//lfLUbcLqlyFqjd/nYE2m3aZ7tjMNUjpks47iw7NTCnXf+5UWz5Ypyt1dSs1EP5QJw==", + "license": "ISC", + "peerDependencies": { + "@prisma/client": ">=2.26.0 || >=3", + "next-auth": "^4" + } + }, + "node_modules/@next/env": { + "version": "13.4.16", + "resolved": "https://registry.npmjs.org/@next/env/-/env-13.4.16.tgz", + "integrity": "sha512-pCU0sJBqdfKP9mwDadxvZd+eLz3fZrTlmmDHY12Hdpl3DD0vy8ou5HWKVfG0zZS6tqhL4wnQqRbspdY5nqa7MA==", + "license": "MIT" + }, + "node_modules/@next/eslint-plugin-next": { + "version": "13.4.16", + "resolved": "https://registry.npmjs.org/@next/eslint-plugin-next/-/eslint-plugin-next-13.4.16.tgz", + "integrity": "sha512-QuFtQl+oSEEQb0HMYBdvBoUaTiMxbY3go/MFkF3zOnfY0t84+IbAX78cw8ZCfr6cA6UcTq3nMIlCrHwDC/moxg==", + "dev": true, + "license": "MIT", + "dependencies": { + "glob": "7.1.7" + } + }, + "node_modules/@next/mdx": { + "version": "13.4.2", + "resolved": "https://registry.npmjs.org/@next/mdx/-/mdx-13.4.2.tgz", + "integrity": "sha512-AT/gxEGkKOwceFSTvoa97vAJh0KsDcw+oW1UFTW4e0zcJCmvieniJoq+JHLMzKoyfC9VjozeCR9yGAchZrli1A==", + "license": "MIT", + "dependencies": { + "source-map": "^0.7.0" + }, + "peerDependencies": { + "@mdx-js/loader": ">=0.15.0", + "@mdx-js/react": ">=0.15.0" + }, + "peerDependenciesMeta": { + "@mdx-js/loader": { + "optional": true + }, + "@mdx-js/react": { + "optional": true + } + } + }, + "node_modules/@next/swc-darwin-arm64": { + "version": "13.4.16", + "resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-13.4.16.tgz", + "integrity": "sha512-Rl6i1uUq0ciRa3VfEpw6GnWAJTSKo9oM2OrkGXPsm7rMxdd2FR5NkKc0C9xzFCI4+QtmBviWBdF2m3ur3Nqstw==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@next/swc-darwin-x64": { + "version": "13.4.16", + "resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-13.4.16.tgz", + "integrity": "sha512-o1vIKYbZORyDmTrPV1hApt9NLyWrS5vr2p5hhLGpOnkBY1cz6DAXjv8Lgan8t6X87+83F0EUDlu7klN8ieZ06A==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@next/swc-linux-arm64-gnu": { + "version": "13.4.16", + "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-13.4.16.tgz", + "integrity": "sha512-JRyAl8lCfyTng4zoOmE6hNI2f1MFUr7JyTYCHl1RxX42H4a5LMwJhDVQ7a9tmDZ/yj+0hpBn+Aan+d6lA3v0UQ==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@next/swc-linux-arm64-musl": { + "version": "13.4.16", + "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-13.4.16.tgz", + "integrity": "sha512-9gqVqNzUMWbUDgDiND18xoUqhwSm2gmksqXgCU0qaOKt6oAjWz8cWYjgpPVD0WICKFylEY/gvPEP1fMZDVFZ/g==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@next/swc-linux-x64-gnu": { + "version": "13.4.16", + "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-13.4.16.tgz", + "integrity": "sha512-KcQGwchAKmZVPa8i5PLTxvTs1/rcFnSltfpTm803Tr/BtBV3AxCkHLfhtoyVtVzx/kl/oue8oS+DSmbepQKwhw==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@next/swc-linux-x64-musl": { + "version": "13.4.16", + "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-13.4.16.tgz", + "integrity": "sha512-2RbMZNxYnJmW8EPHVBsGZPq5zqWAyBOc/YFxq/jIQ/Yn3RMFZ1dZVCjtIcsiaKmgh7mjA/W0ApbumutHNxRqqQ==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@next/swc-win32-arm64-msvc": { + "version": "13.4.16", + "resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-13.4.16.tgz", + "integrity": "sha512-thDcGonELN7edUKzjzlHrdoKkm7y8IAdItQpRvvMxNUXa4d9r0ElofhTZj5emR7AiXft17hpen+QAkcWpqG7Jg==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@next/swc-win32-ia32-msvc": { + "version": "13.4.16", + "resolved": "https://registry.npmjs.org/@next/swc-win32-ia32-msvc/-/swc-win32-ia32-msvc-13.4.16.tgz", + "integrity": "sha512-f7SE1Mo4JAchUWl0LQsbtySR9xCa+x55C0taetjUApKtcLR3AgAjASrrP+oE1inmLmw573qRnE1eZN8YJfEBQw==", + "cpu": [ + "ia32" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@next/swc-win32-x64-msvc": { + "version": "13.4.16", + "resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-13.4.16.tgz", + "integrity": "sha512-WamDZm1M/OEM4QLce3lOmD1XdLEl37zYZwlmOLhmF7qYJ2G6oYm9+ejZVv+LakQIsIuXhSpVlOvrxIAHqwRkPQ==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@nivo/annotations": { + "version": "0.83.0", + "resolved": "https://registry.npmjs.org/@nivo/annotations/-/annotations-0.83.0.tgz", + "integrity": "sha512-FkfCprk1a3WCCNcQOfI2+Ww7vqTP/nJjQDVhFYf1YAaEGwXi4+OO4uJAtKtNcGE5cJWdOp+f0Gt4aNPGx7RtEw==", + "license": "MIT", + "dependencies": { + "@nivo/colors": "0.83.0", + "@nivo/core": "0.83.0", + "@react-spring/web": "9.4.5 || ^9.7.2", + "@types/prop-types": "^15.7.2", + "lodash": "^4.17.21", + "prop-types": "^15.7.2" + }, + "peerDependencies": { + "react": ">= 16.14.0 < 19.0.0" + } + }, + "node_modules/@nivo/arcs": { + "version": "0.83.0", + "resolved": "https://registry.npmjs.org/@nivo/arcs/-/arcs-0.83.0.tgz", + "integrity": "sha512-UcbNbtp28lbI5V/Sm6TIgYzZmtuhSxW3eTma+YBsgXi1AN/THSwEg0gSV8owyDT/8kaL+jcBQ6c54gzSLClhkw==", + "license": "MIT", + "dependencies": { + "@nivo/colors": "0.83.0", + "@nivo/core": "0.83.0", + "@react-spring/web": "9.4.5 || ^9.7.2", + "@types/d3-shape": "^2.0.0", + "d3-shape": "^1.3.5" + }, + "peerDependencies": { + "react": ">= 16.14.0 < 19.0.0" + } + }, + "node_modules/@nivo/axes": { + "version": "0.83.0", + "resolved": "https://registry.npmjs.org/@nivo/axes/-/axes-0.83.0.tgz", + "integrity": "sha512-rHMl+DdXQlY2wl7VCSQNcJi4QNISUWOkcWzJeJeVaYR73Z13SVGgiC7kW0czJuogDTSnDAJ/EcFCGmyGVuznGQ==", + "license": "MIT", + "dependencies": { + "@nivo/core": "0.83.0", + "@nivo/scales": "0.83.0", + "@react-spring/web": "9.4.5 || ^9.7.2", + "@types/d3-format": "^1.4.1", + "@types/d3-time-format": "^2.3.1", + "@types/prop-types": "^15.7.2", + "d3-format": "^1.4.4", + "d3-time-format": "^3.0.0", + "prop-types": "^15.7.2" + }, + "peerDependencies": { + "react": ">= 16.14.0 < 19.0.0" + } + }, + "node_modules/@nivo/bar": { + "version": "0.83.0", + "resolved": "https://registry.npmjs.org/@nivo/bar/-/bar-0.83.0.tgz", + "integrity": "sha512-QXN6BcT1PiT/YViyoDU4G5mytbOUP1jYbuQmJhDDxKPMLNcZ/pHfThedRGVfDoD1poHBRJtV6mbgeCpAVmlTtw==", + "license": "MIT", + "dependencies": { + "@nivo/annotations": "0.83.0", + "@nivo/axes": "0.83.0", + "@nivo/colors": "0.83.0", + "@nivo/core": "0.83.0", + "@nivo/legends": "0.83.0", + "@nivo/scales": "0.83.0", + "@nivo/tooltip": "0.83.0", + "@react-spring/web": "9.4.5 || ^9.7.2", + "@types/d3-scale": "^3.2.3", + "@types/d3-shape": "^2.0.0", + "d3-scale": "^3.2.3", + "d3-shape": "^1.3.5", + "lodash": "^4.17.21" + }, + "peerDependencies": { + "react": ">= 16.14.0 < 19.0.0" + } + }, + "node_modules/@nivo/colors": { + "version": "0.83.0", + "resolved": "https://registry.npmjs.org/@nivo/colors/-/colors-0.83.0.tgz", + "integrity": "sha512-n34LWYtE2hbd1fdCDP7TCHNZdbiO1PwcvXLo0VsKK5lNPY/FA5SXA7Z9Ubl/ChSwBwbzAsaAhjTy8KzKzSjDcA==", + "license": "MIT", + "dependencies": { + "@nivo/core": "0.83.0", + "@types/d3-color": "^2.0.0", + "@types/d3-scale": "^3.2.3", + "@types/d3-scale-chromatic": "^2.0.0", + "@types/prop-types": "^15.7.2", + "d3-color": "^3.1.0", + "d3-scale": "^3.2.3", + "d3-scale-chromatic": "^2.0.0", + "lodash": "^4.17.21", + "prop-types": "^15.7.2" + }, + "peerDependencies": { + "react": ">= 16.14.0 < 19.0.0" + } + }, + "node_modules/@nivo/core": { + "version": "0.83.0", + "resolved": "https://registry.npmjs.org/@nivo/core/-/core-0.83.0.tgz", + "integrity": "sha512-I9fjZAbIPz41JA2WP8Avsud/xk0iiM1nWUzcvZBDebBGFDB5Y1lrldUt9l5kvOeMth3Qj/1lVFTiJxQuojxH4Q==", + "license": "MIT", + "dependencies": { + "@nivo/recompose": "0.83.0", + "@nivo/tooltip": "0.83.0", + "@react-spring/web": "9.4.5 || ^9.7.2", + "@types/d3-shape": "^2.0.0", + "d3-color": "^3.1.0", + "d3-format": "^1.4.4", + "d3-interpolate": "^2.0.1", + "d3-scale": "^3.2.3", + "d3-scale-chromatic": "^2.0.0", + "d3-shape": "^1.3.5", + "d3-time-format": "^3.0.0", + "lodash": "^4.17.21" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/nivo/donate" + }, + "peerDependencies": { + "prop-types": ">= 15.5.10 < 16.0.0", + "react": ">= 16.14.0 < 19.0.0" + } + }, + "node_modules/@nivo/legends": { + "version": "0.83.0", + "resolved": "https://registry.npmjs.org/@nivo/legends/-/legends-0.83.0.tgz", + "integrity": "sha512-WWl3/hTpFJ7/2L0RG53Gbr9KQk+ZjD71a/RIPMJ5ArEvAvKKfWuWQCtEm3FpqAazX8eYMnsQ3Pi17c8ohEIXRg==", + "license": "MIT", + "dependencies": { + "@nivo/colors": "0.83.0", + "@nivo/core": "0.83.0", + "@types/d3-scale": "^3.2.3", + "@types/prop-types": "^15.7.2", + "d3-scale": "^3.2.3", + "prop-types": "^15.7.2" + }, + "peerDependencies": { + "react": ">= 16.14.0 < 19.0.0" + } + }, + "node_modules/@nivo/line": { + "version": "0.83.0", + "resolved": "https://registry.npmjs.org/@nivo/line/-/line-0.83.0.tgz", + "integrity": "sha512-tF/HcUM7dRf+0uk4E0Ywg7nMYD7NsmF03tp5nIbBSB35PRFoVnczxlzHWw2qoRYwUhCFy2gL6Dyf/6kTHXnIdA==", + "license": "MIT", + "dependencies": { + "@nivo/annotations": "0.83.0", + "@nivo/axes": "0.83.0", + "@nivo/colors": "0.83.0", + "@nivo/core": "0.83.0", + "@nivo/legends": "0.83.0", + "@nivo/scales": "0.83.0", + "@nivo/tooltip": "0.83.0", + "@nivo/voronoi": "0.83.0", + "@react-spring/web": "9.4.5 || ^9.7.2", + "d3-shape": "^1.3.5", + "prop-types": "^15.7.2" + }, + "peerDependencies": { + "react": ">= 16.14.0 < 19.0.0" + } + }, + "node_modules/@nivo/pie": { + "version": "0.83.0", + "resolved": "https://registry.npmjs.org/@nivo/pie/-/pie-0.83.0.tgz", + "integrity": "sha512-98j/h4T/QmQ10gFh1cMh6uLfcGurFcYZN97Lu3ig3D9bbsLuLgpUED/d5O+8w7qLJtnlg3zptqy+N9UgRAqbOg==", + "license": "MIT", + "dependencies": { + "@nivo/arcs": "0.83.0", + "@nivo/colors": "0.83.0", + "@nivo/core": "0.83.0", + "@nivo/legends": "0.83.0", + "@nivo/tooltip": "0.83.0", + "@types/d3-shape": "^2.0.0", + "d3-shape": "^1.3.5" + }, + "peerDependencies": { + "react": ">= 16.14.0 < 19.0.0" + } + }, + "node_modules/@nivo/recompose": { + "version": "0.83.0", + "resolved": "https://registry.npmjs.org/@nivo/recompose/-/recompose-0.83.0.tgz", + "integrity": "sha512-3cLEoi9ZoE4LTn6B98oUVd0MRAy5bWK7W3yb0u4EkjLoXXCRvUAI08Wr2AAagOzVOg5PmvghIDgvkz1tlFZTGQ==", + "license": "MIT", + "dependencies": { + "@types/prop-types": "^15.7.2", + "@types/react-lifecycles-compat": "^3.0.1", + "prop-types": "^15.7.2", + "react-lifecycles-compat": "^3.0.4" + }, + "peerDependencies": { + "react": ">= 16.14.0 < 19.0.0" + } + }, + "node_modules/@nivo/scales": { + "version": "0.83.0", + "resolved": "https://registry.npmjs.org/@nivo/scales/-/scales-0.83.0.tgz", + "integrity": "sha512-DZn5IcMJErCURDuQPmYltu6GTPphTDVLMvbeN/Id/VSVbD1uYKvdXPKUNOe/N2IvnE8wjjCPv88DLcRhw6VTVg==", + "license": "MIT", + "dependencies": { + "@types/d3-scale": "^3.2.3", + "@types/d3-time": "^1.1.1", + "@types/d3-time-format": "^3.0.0", + "d3-scale": "^3.2.3", + "d3-time": "^1.0.11", + "d3-time-format": "^3.0.0", + "lodash": "^4.17.21" + } + }, + "node_modules/@nivo/scales/node_modules/@types/d3-time-format": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/@types/d3-time-format/-/d3-time-format-3.0.1.tgz", + "integrity": "sha512-5GIimz5IqaRsdnxs4YlyTZPwAMfALu/wA4jqSiuqgdbCxUZ2WjrnwANqOtoBJQgeaUTdYNfALJO0Yb0YrDqduA==", + "license": "MIT" + }, + "node_modules/@nivo/tooltip": { + "version": "0.83.0", + "resolved": "https://registry.npmjs.org/@nivo/tooltip/-/tooltip-0.83.0.tgz", + "integrity": "sha512-HewujRqZNmcVnAv/LPLVyYwViad+rYTsFMdzLRzuTPq2hju1R+cfxokTomunG8e1SDtUPtULEVXtPg2ATIzNYg==", + "license": "MIT", + "dependencies": { + "@nivo/core": "0.83.0", + "@react-spring/web": "9.4.5 || ^9.7.2" + } + }, + "node_modules/@nivo/voronoi": { + "version": "0.83.0", + "resolved": "https://registry.npmjs.org/@nivo/voronoi/-/voronoi-0.83.0.tgz", + "integrity": "sha512-wVpskesX2IEJHG82v0rbIUZ2y3MpvzTYM+DQl2gx8K1/Hucxwzk5ltg/aF9e/gfKU8gt24uct3M9TQTEfyhzgg==", + "license": "MIT", + "dependencies": { + "@nivo/core": "0.83.0", + "@types/d3-delaunay": "^5.3.0", + "@types/d3-scale": "^3.2.3", + "d3-delaunay": "^5.3.0", + "d3-scale": "^3.2.3" + }, + "peerDependencies": { + "react": ">= 16.14.0 < 19.0.0" + } + }, + "node_modules/@nodelib/fs.scandir": { + "version": "2.1.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", + "integrity": "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==", + "license": "MIT", + "dependencies": { + "@nodelib/fs.stat": "2.0.5", + "run-parallel": "^1.1.9" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@nodelib/fs.stat": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz", + "integrity": "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==", + "license": "MIT", + "engines": { + "node": ">= 8" + } + }, + "node_modules/@nodelib/fs.walk": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz", + "integrity": "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==", + "license": "MIT", + "dependencies": { + "@nodelib/fs.scandir": "2.1.5", + "fastq": "^1.6.0" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@panva/hkdf": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@panva/hkdf/-/hkdf-1.1.1.tgz", + "integrity": "sha512-dhPeilub1NuIG0X5Kvhh9lH4iW3ZsHlnzwgwbOlgwQ2wG1IqFzsgHqmKPk3WzsdWAeaxKJxgM0+W433RmN45GA==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/panva" + } + }, + "node_modules/@prisma/client": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/@prisma/client/-/client-5.1.1.tgz", + "integrity": "sha512-fxcCeK5pMQGcgCqCrWsi+I2rpIbk0rAhdrN+ke7f34tIrgPwA68ensrpin+9+fZvuV2OtzHmuipwduSY6HswdA==", + "hasInstallScript": true, + "license": "Apache-2.0", + "dependencies": { + "@prisma/engines-version": "5.1.1-1.6a3747c37ff169c90047725a05a6ef02e32ac97e" + }, + "engines": { + "node": ">=16.13" + }, + "peerDependencies": { + "prisma": "*" + }, + "peerDependenciesMeta": { + "prisma": { + "optional": true + } + } + }, + "node_modules/@prisma/engines": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/@prisma/engines/-/engines-5.1.1.tgz", + "integrity": "sha512-NV/4nVNWFZSJCCIA3HIFJbbDKO/NARc9ej0tX5S9k2EVbkrFJC4Xt9b0u4rNZWL4V+F5LAjvta8vzEUw0rw+HA==", + "hasInstallScript": true, + "license": "Apache-2.0" + }, + "node_modules/@prisma/engines-version": { + "version": "5.1.1-1.6a3747c37ff169c90047725a05a6ef02e32ac97e", + "resolved": "https://registry.npmjs.org/@prisma/engines-version/-/engines-version-5.1.1-1.6a3747c37ff169c90047725a05a6ef02e32ac97e.tgz", + "integrity": "sha512-owZqbY/wucbr65bXJ/ljrHPgQU5xXTSkmcE/JcbqE1kusuAXV/TLN3/exmz21SZ5rJ7WDkyk70J2G/n68iogbQ==", + "license": "Apache-2.0" + }, + "node_modules/@radix-ui/number": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/number/-/number-1.0.1.tgz", + "integrity": "sha512-T5gIdVO2mmPW3NNhjNgEP3cqMXjXL9UbO0BzWcXfvdBs+BohbQxvd/K5hSVKmn9/lbTdsQVKbUcP5WLCwvUbBg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + } + }, + "node_modules/@radix-ui/primitive": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.0.1.tgz", + "integrity": "sha512-yQ8oGX2GVsEYMWGxcovu1uGWPCxV5BFfeeYxqPmuAzUyLT9qmaMXSAhXpb0WrspIeqYzdJpkh2vHModJPgRIaw==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + } + }, + "node_modules/@radix-ui/react-accessible-icon": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-accessible-icon/-/react-accessible-icon-1.0.3.tgz", + "integrity": "sha512-duVGKeWPSUILr/MdlPxV+GeULTc2rS1aihGdQ3N2qCUPMgxYLxvAsHJM3mCVLF8d5eK+ympmB22mb1F3a5biNw==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-visually-hidden": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-accordion": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-accordion/-/react-accordion-1.1.2.tgz", + "integrity": "sha512-fDG7jcoNKVjSK6yfmuAs0EnPDro0WMXIhMtXdTBWqEioVW206ku+4Lw07e+13lUkFkpoEQ2PdeMIAGpdqEAmDg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-collapsible": "1.0.3", + "@radix-ui/react-collection": "1.0.3", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-direction": "1.0.1", + "@radix-ui/react-id": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-controllable-state": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-accordion/node_modules/@radix-ui/react-collection": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-collection/-/react-collection-1.0.3.tgz", + "integrity": "sha512-3SzW+0PW7yBBoQlT8wNcGtaxaD0XSu0uLUFgrtHY08Acx05TaHaOmVLR73c0j/cqpDy53KBMO7s0dx2wmOIDIA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-slot": "1.0.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-accordion/node_modules/@radix-ui/react-direction": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-direction/-/react-direction-1.0.1.tgz", + "integrity": "sha512-RXcvnXgyvYvBEOhCBuddKecVkoMiI10Jcm5cTI7abJRAHYfFxeu+FBQs/DvdxSYucxR5mna0dNsL6QFlds5TMA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-accordion/node_modules/@radix-ui/react-id": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.0.1.tgz", + "integrity": "sha512-tI7sT/kqYp8p96yGWY1OAnLHrqDgzHefRBKQ2YAkBS5ja7QLcZ9Z/uY7bEjPUatf8RomoXM8/1sMj1IJaE5UzQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-layout-effect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-alert-dialog": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-alert-dialog/-/react-alert-dialog-1.0.4.tgz", + "integrity": "sha512-jbfBCRlKYlhbitueOAv7z74PXYeIQmWpKwm3jllsdkw7fGWNkxqP3v0nY9WmOzcPqpQuoorNtvViBgL46n5gVg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-dialog": "1.0.4", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-slot": "1.0.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-alert-dialog/node_modules/@radix-ui/react-dialog": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-dialog/-/react-dialog-1.0.4.tgz", + "integrity": "sha512-hJtRy/jPULGQZceSAP2Re6/4NpKo8im6V8P2hUqZsdFiSL8l35kYsw3qbRI6Ay5mQd2+wlLqje770eq+RJ3yZg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-dismissable-layer": "1.0.4", + "@radix-ui/react-focus-guards": "1.0.1", + "@radix-ui/react-focus-scope": "1.0.3", + "@radix-ui/react-id": "1.0.1", + "@radix-ui/react-portal": "1.0.3", + "@radix-ui/react-presence": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-slot": "1.0.2", + "@radix-ui/react-use-controllable-state": "1.0.1", + "aria-hidden": "^1.1.1", + "react-remove-scroll": "2.5.5" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-alert-dialog/node_modules/@radix-ui/react-dismissable-layer": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-dismissable-layer/-/react-dismissable-layer-1.0.4.tgz", + "integrity": "sha512-7UpBa/RKMoHJYjie1gkF1DlK8l1fdU/VKDpoS3rCCo8YBJR294GwcEHyxHw72yvphJ7ld0AXEcSLAzY2F/WyCg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-escape-keydown": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-alert-dialog/node_modules/@radix-ui/react-focus-guards": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-guards/-/react-focus-guards-1.0.1.tgz", + "integrity": "sha512-Rect2dWbQ8waGzhMavsIbmSVCgYxkXLxxR3ZvCX79JOglzdEy4JXMb98lq4hPxUbLr77nP0UOGf4rcMU+s1pUA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-alert-dialog/node_modules/@radix-ui/react-focus-scope": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-scope/-/react-focus-scope-1.0.3.tgz", + "integrity": "sha512-upXdPfqI4islj2CslyfUBNlaJCPybbqRHAi1KER7Isel9Q2AtSJ0zRBZv8mWQiFXD2nyAJ4BhC3yXgZ6kMBSrQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-alert-dialog/node_modules/@radix-ui/react-id": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.0.1.tgz", + "integrity": "sha512-tI7sT/kqYp8p96yGWY1OAnLHrqDgzHefRBKQ2YAkBS5ja7QLcZ9Z/uY7bEjPUatf8RomoXM8/1sMj1IJaE5UzQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-layout-effect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-alert-dialog/node_modules/@radix-ui/react-portal": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-portal/-/react-portal-1.0.3.tgz", + "integrity": "sha512-xLYZeHrWoPmA5mEKEfZZevoVRK/Q43GfzRXkWV6qawIWWK8t6ifIiLQdd7rmQ4Vk1bmI21XhqF9BN3jWf+phpA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-primitive": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-alert-dialog/node_modules/@radix-ui/react-use-escape-keydown": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-escape-keydown/-/react-use-escape-keydown-1.0.3.tgz", + "integrity": "sha512-vyL82j40hcFicA+M4Ex7hVkB9vHgSse1ZWomAqV2Je3RleKGO5iM8KMOEtfoSB0PnIelMd2lATjTGMYqN5ylTg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-callback-ref": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-alert-dialog/node_modules/react-remove-scroll": { + "version": "2.5.5", + "resolved": "https://registry.npmjs.org/react-remove-scroll/-/react-remove-scroll-2.5.5.tgz", + "integrity": "sha512-ImKhrzJJsyXJfBZ4bzu8Bwpka14c/fQt0k+cyFp/PBhTfyDnU5hjOtM4AG/0AMyy8oKzOTR0lDgJIM7pYXI0kw==", + "license": "MIT", + "dependencies": { + "react-remove-scroll-bar": "^2.3.3", + "react-style-singleton": "^2.2.1", + "tslib": "^2.1.0", + "use-callback-ref": "^1.3.0", + "use-sidecar": "^1.1.2" + }, + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "@types/react": "^16.8.0 || ^17.0.0 || ^18.0.0", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-arrow": { + "version": "1.1.7", + "resolved": "https://registry.npmjs.org/@radix-ui/react-arrow/-/react-arrow-1.1.7.tgz", + "integrity": "sha512-F+M1tLhO+mlQaOWspE8Wstg+z6PwxwRd8oQ8IXceWz92kfAmalTRf0EjrouQeo7QssEPfCn05B4Ihs1K9WQ/7w==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-primitive": "2.1.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-arrow/node_modules/@radix-ui/react-compose-refs": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz", + "integrity": "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-arrow/node_modules/@radix-ui/react-primitive": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz", + "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-slot": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-arrow/node_modules/@radix-ui/react-slot": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz", + "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-aspect-ratio": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-aspect-ratio/-/react-aspect-ratio-1.0.3.tgz", + "integrity": "sha512-fXR5kbMan9oQqMuacfzlGG/SQMcmMlZ4wrvpckv8SgUulD0MMpspxJrxg/Gp/ISV3JfV1AeSWTYK9GvxA4ySwA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-primitive": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-avatar": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-avatar/-/react-avatar-1.0.3.tgz", + "integrity": "sha512-9ToF7YNex3Ste45LrAeTlKtONI9yVRt/zOS158iilIkW5K/Apeyb/TUQlcEFTEFvWr8Kzdi2ZYrm1/suiXPajQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-layout-effect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-checkbox": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-checkbox/-/react-checkbox-1.0.4.tgz", + "integrity": "sha512-CBuGQa52aAYnADZVt/KBQzXrwx6TqnlwtcIPGtVt5JkkzQwMOLJjPukimhfKEr4GQNd43C+djUh5Ikopj8pSLg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-presence": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-controllable-state": "1.0.1", + "@radix-ui/react-use-previous": "1.0.1", + "@radix-ui/react-use-size": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-collapsible": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-collapsible/-/react-collapsible-1.0.3.tgz", + "integrity": "sha512-UBmVDkmR6IvDsloHVN+3rtx4Mi5TFvylYXpluuv0f37dtaz3H99bp8No0LGXRigVpl3UAT4l9j6bIchh42S/Gg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-id": "1.0.1", + "@radix-ui/react-presence": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-controllable-state": "1.0.1", + "@radix-ui/react-use-layout-effect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-collapsible/node_modules/@radix-ui/react-id": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.0.1.tgz", + "integrity": "sha512-tI7sT/kqYp8p96yGWY1OAnLHrqDgzHefRBKQ2YAkBS5ja7QLcZ9Z/uY7bEjPUatf8RomoXM8/1sMj1IJaE5UzQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-layout-effect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-collection": { + "version": "1.1.7", + "resolved": "https://registry.npmjs.org/@radix-ui/react-collection/-/react-collection-1.1.7.tgz", + "integrity": "sha512-Fh9rGN0MoI4ZFUNyfFVNU4y9LUz93u9/0K+yLgA2bwRojxM8JU1DyvvMBabnZPBgMWREAJvU2jjVzq+LrFUglw==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-context": "1.1.2", + "@radix-ui/react-primitive": "2.1.3", + "@radix-ui/react-slot": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-collection/node_modules/@radix-ui/react-compose-refs": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz", + "integrity": "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-collection/node_modules/@radix-ui/react-context": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.1.2.tgz", + "integrity": "sha512-jCi/QKUM2r1Ju5a3J64TH2A5SpKAgh0LpknyqdQ4m6DCV0xJ2HG1xARRwNGPQfi1SLdLWZ1OJz6F4OMBBNiGJA==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-collection/node_modules/@radix-ui/react-primitive": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz", + "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-slot": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-collection/node_modules/@radix-ui/react-slot": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz", + "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-compose-refs": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.0.1.tgz", + "integrity": "sha512-fDSBgd44FKHa1FRMU59qBMPFcl2PZE+2nmqunj+BWFyYYjnhIDWL2ItDs3rrbJDQOtzt5nIebLCQc4QRfz6LJw==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-context": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.0.1.tgz", + "integrity": "sha512-ebbrdFoYTcuZ0v4wG5tedGnp9tzcV8awzsxYph7gXUyvnNLuTIcCk1q17JEbnVhXAKG9oX3KtchwiMIAYp9NLg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-context-menu": { + "version": "2.2.15", + "resolved": "https://registry.npmjs.org/@radix-ui/react-context-menu/-/react-context-menu-2.2.15.tgz", + "integrity": "sha512-UsQUMjcYTsBjTSXw0P3GO0werEQvUY2plgRQuKoCTtkNr45q1DiL51j4m7gxhABzZ0BadoXNsIbg7F3KwiUBbw==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.1.2", + "@radix-ui/react-context": "1.1.2", + "@radix-ui/react-menu": "2.1.15", + "@radix-ui/react-primitive": "2.1.3", + "@radix-ui/react-use-callback-ref": "1.1.1", + "@radix-ui/react-use-controllable-state": "1.2.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-context-menu/node_modules/@radix-ui/primitive": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.2.tgz", + "integrity": "sha512-XnbHrrprsNqZKQhStrSwgRUQzoCI1glLzdw79xiZPoofhGICeZRSQ3dIxAKH1gb3OHfNf4d6f+vAv3kil2eggA==", + "license": "MIT" + }, + "node_modules/@radix-ui/react-context-menu/node_modules/@radix-ui/react-compose-refs": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz", + "integrity": "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-context-menu/node_modules/@radix-ui/react-context": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.1.2.tgz", + "integrity": "sha512-jCi/QKUM2r1Ju5a3J64TH2A5SpKAgh0LpknyqdQ4m6DCV0xJ2HG1xARRwNGPQfi1SLdLWZ1OJz6F4OMBBNiGJA==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-context-menu/node_modules/@radix-ui/react-primitive": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz", + "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-slot": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-context-menu/node_modules/@radix-ui/react-slot": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz", + "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-context-menu/node_modules/@radix-ui/react-use-callback-ref": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.1.1.tgz", + "integrity": "sha512-FkBMwD+qbGQeMu1cOHnuGB6x4yzPjho8ap5WtbEJ26umhgqVXbhekKUQO+hZEL1vU92a3wHwdp0HAcqAUF5iDg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-context-menu/node_modules/@radix-ui/react-use-controllable-state": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-controllable-state/-/react-use-controllable-state-1.2.2.tgz", + "integrity": "sha512-BjasUjixPFdS+NKkypcyyN5Pmg83Olst0+c6vGov0diwTEo6mgdqVR6hxcEgFuh4QrAs7Rc+9KuGJ9TVCj0Zzg==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-effect-event": "0.0.2", + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-context-menu/node_modules/@radix-ui/react-use-layout-effect": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.1.tgz", + "integrity": "sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dialog": { + "version": "1.1.14", + "resolved": "https://registry.npmjs.org/@radix-ui/react-dialog/-/react-dialog-1.1.14.tgz", + "integrity": "sha512-+CpweKjqpzTmwRwcYECQcNYbI8V9VSQt0SNFKeEBLgfucbsLssU6Ppq7wUdNXEGb573bMjFhVjKVll8rmV6zMw==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.1.2", + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-context": "1.1.2", + "@radix-ui/react-dismissable-layer": "1.1.10", + "@radix-ui/react-focus-guards": "1.1.2", + "@radix-ui/react-focus-scope": "1.1.7", + "@radix-ui/react-id": "1.1.1", + "@radix-ui/react-portal": "1.1.9", + "@radix-ui/react-presence": "1.1.4", + "@radix-ui/react-primitive": "2.1.3", + "@radix-ui/react-slot": "1.2.3", + "@radix-ui/react-use-controllable-state": "1.2.2", + "aria-hidden": "^1.2.4", + "react-remove-scroll": "^2.6.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dialog/node_modules/@radix-ui/primitive": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.2.tgz", + "integrity": "sha512-XnbHrrprsNqZKQhStrSwgRUQzoCI1glLzdw79xiZPoofhGICeZRSQ3dIxAKH1gb3OHfNf4d6f+vAv3kil2eggA==", + "license": "MIT" + }, + "node_modules/@radix-ui/react-dialog/node_modules/@radix-ui/react-compose-refs": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz", + "integrity": "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dialog/node_modules/@radix-ui/react-context": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.1.2.tgz", + "integrity": "sha512-jCi/QKUM2r1Ju5a3J64TH2A5SpKAgh0LpknyqdQ4m6DCV0xJ2HG1xARRwNGPQfi1SLdLWZ1OJz6F4OMBBNiGJA==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dialog/node_modules/@radix-ui/react-presence": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-presence/-/react-presence-1.1.4.tgz", + "integrity": "sha512-ueDqRbdc4/bkaQT3GIpLQssRlFgWaL/U2z/S31qRwwLWoxHLgry3SIfCwhxeQNbirEUXFa+lq3RL3oBYXtcmIA==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dialog/node_modules/@radix-ui/react-primitive": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz", + "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-slot": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dialog/node_modules/@radix-ui/react-slot": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz", + "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dialog/node_modules/@radix-ui/react-use-controllable-state": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-controllable-state/-/react-use-controllable-state-1.2.2.tgz", + "integrity": "sha512-BjasUjixPFdS+NKkypcyyN5Pmg83Olst0+c6vGov0diwTEo6mgdqVR6hxcEgFuh4QrAs7Rc+9KuGJ9TVCj0Zzg==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-effect-event": "0.0.2", + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dialog/node_modules/@radix-ui/react-use-layout-effect": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.1.tgz", + "integrity": "sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-direction": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-direction/-/react-direction-1.1.1.tgz", + "integrity": "sha512-1UEWRX6jnOA2y4H5WczZ44gOOjTEmlqv1uNW4GAJEO5+bauCBhv8snY65Iw5/VOS/ghKN9gr2KjnLKxrsvoMVw==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dismissable-layer": { + "version": "1.1.10", + "resolved": "https://registry.npmjs.org/@radix-ui/react-dismissable-layer/-/react-dismissable-layer-1.1.10.tgz", + "integrity": "sha512-IM1zzRV4W3HtVgftdQiiOmA0AdJlCtMLe00FXaHwgt3rAnNsIyDqshvkIW3hj/iu5hu8ERP7KIYki6NkqDxAwQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.1.2", + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-primitive": "2.1.3", + "@radix-ui/react-use-callback-ref": "1.1.1", + "@radix-ui/react-use-escape-keydown": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dismissable-layer/node_modules/@radix-ui/primitive": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.2.tgz", + "integrity": "sha512-XnbHrrprsNqZKQhStrSwgRUQzoCI1glLzdw79xiZPoofhGICeZRSQ3dIxAKH1gb3OHfNf4d6f+vAv3kil2eggA==", + "license": "MIT" + }, + "node_modules/@radix-ui/react-dismissable-layer/node_modules/@radix-ui/react-compose-refs": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz", + "integrity": "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dismissable-layer/node_modules/@radix-ui/react-primitive": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz", + "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-slot": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dismissable-layer/node_modules/@radix-ui/react-slot": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz", + "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dismissable-layer/node_modules/@radix-ui/react-use-callback-ref": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.1.1.tgz", + "integrity": "sha512-FkBMwD+qbGQeMu1cOHnuGB6x4yzPjho8ap5WtbEJ26umhgqVXbhekKUQO+hZEL1vU92a3wHwdp0HAcqAUF5iDg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dropdown-menu": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@radix-ui/react-dropdown-menu/-/react-dropdown-menu-2.0.5.tgz", + "integrity": "sha512-xdOrZzOTocqqkCkYo8yRPCib5OkTkqN7lqNCdxwPOdE466DOaNl4N8PkUIlsXthQvW5Wwkd+aEmWpfWlBoDPEw==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-id": "1.0.1", + "@radix-ui/react-menu": "2.0.5", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-controllable-state": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-arrow": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-arrow/-/react-arrow-1.0.3.tgz", + "integrity": "sha512-wSP+pHsB/jQRaL6voubsQ/ZlrGBHHrOjmBnr19hxYgtS0WvAFwZhK2WP/YY5yF9uKECCEEDGxuLxq1NBK51wFA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-primitive": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-collection": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-collection/-/react-collection-1.0.3.tgz", + "integrity": "sha512-3SzW+0PW7yBBoQlT8wNcGtaxaD0XSu0uLUFgrtHY08Acx05TaHaOmVLR73c0j/cqpDy53KBMO7s0dx2wmOIDIA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-slot": "1.0.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-direction": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-direction/-/react-direction-1.0.1.tgz", + "integrity": "sha512-RXcvnXgyvYvBEOhCBuddKecVkoMiI10Jcm5cTI7abJRAHYfFxeu+FBQs/DvdxSYucxR5mna0dNsL6QFlds5TMA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-dismissable-layer": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-dismissable-layer/-/react-dismissable-layer-1.0.4.tgz", + "integrity": "sha512-7UpBa/RKMoHJYjie1gkF1DlK8l1fdU/VKDpoS3rCCo8YBJR294GwcEHyxHw72yvphJ7ld0AXEcSLAzY2F/WyCg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-escape-keydown": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-focus-guards": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-guards/-/react-focus-guards-1.0.1.tgz", + "integrity": "sha512-Rect2dWbQ8waGzhMavsIbmSVCgYxkXLxxR3ZvCX79JOglzdEy4JXMb98lq4hPxUbLr77nP0UOGf4rcMU+s1pUA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-focus-scope": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-scope/-/react-focus-scope-1.0.3.tgz", + "integrity": "sha512-upXdPfqI4islj2CslyfUBNlaJCPybbqRHAi1KER7Isel9Q2AtSJ0zRBZv8mWQiFXD2nyAJ4BhC3yXgZ6kMBSrQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-id": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.0.1.tgz", + "integrity": "sha512-tI7sT/kqYp8p96yGWY1OAnLHrqDgzHefRBKQ2YAkBS5ja7QLcZ9Z/uY7bEjPUatf8RomoXM8/1sMj1IJaE5UzQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-layout-effect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-menu": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@radix-ui/react-menu/-/react-menu-2.0.5.tgz", + "integrity": "sha512-Gw4f9pwdH+w5w+49k0gLjN0PfRDHvxmAgG16AbyJZ7zhwZ6PBHKtWohvnSwfusfnK3L68dpBREHpVkj8wEM7ZA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-collection": "1.0.3", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-direction": "1.0.1", + "@radix-ui/react-dismissable-layer": "1.0.4", + "@radix-ui/react-focus-guards": "1.0.1", + "@radix-ui/react-focus-scope": "1.0.3", + "@radix-ui/react-id": "1.0.1", + "@radix-ui/react-popper": "1.1.2", + "@radix-ui/react-portal": "1.0.3", + "@radix-ui/react-presence": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-roving-focus": "1.0.4", + "@radix-ui/react-slot": "1.0.2", + "@radix-ui/react-use-callback-ref": "1.0.1", + "aria-hidden": "^1.1.1", + "react-remove-scroll": "2.5.5" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-popper": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-popper/-/react-popper-1.1.2.tgz", + "integrity": "sha512-1CnGGfFi/bbqtJZZ0P/NQY20xdG3E0LALJaLUEoKwPLwl6PPPfbeiCqMVQnhoFRAxjJj4RpBRJzDmUgsex2tSg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@floating-ui/react-dom": "^2.0.0", + "@radix-ui/react-arrow": "1.0.3", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-layout-effect": "1.0.1", + "@radix-ui/react-use-rect": "1.0.1", + "@radix-ui/react-use-size": "1.0.1", + "@radix-ui/rect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-portal": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-portal/-/react-portal-1.0.3.tgz", + "integrity": "sha512-xLYZeHrWoPmA5mEKEfZZevoVRK/Q43GfzRXkWV6qawIWWK8t6ifIiLQdd7rmQ4Vk1bmI21XhqF9BN3jWf+phpA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-primitive": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-roving-focus": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-roving-focus/-/react-roving-focus-1.0.4.tgz", + "integrity": "sha512-2mUg5Mgcu001VkGy+FfzZyzbmuUWzgWkj3rvv4yu+mLw03+mTzbxZHvfcGyFp2b8EkQeMkpRQ5FiA2Vr2O6TeQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-collection": "1.0.3", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-direction": "1.0.1", + "@radix-ui/react-id": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-controllable-state": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-use-escape-keydown": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-escape-keydown/-/react-use-escape-keydown-1.0.3.tgz", + "integrity": "sha512-vyL82j40hcFicA+M4Ex7hVkB9vHgSse1ZWomAqV2Je3RleKGO5iM8KMOEtfoSB0PnIelMd2lATjTGMYqN5ylTg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-callback-ref": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-use-rect": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-rect/-/react-use-rect-1.0.1.tgz", + "integrity": "sha512-Cq5DLuSiuYVKNU8orzJMbl15TXilTnJKUCltMVQg53BQOF1/C5toAaGrowkgksdBQ9H+SRL23g0HDmg9tvmxXw==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/rect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/rect": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/rect/-/rect-1.0.1.tgz", + "integrity": "sha512-fyrgCaedtvMg9NK3en0pnOYJdtfwxUcNolezkNPUsoX57X8oQk+NkqcvzHXD2uKNij6GXmWU9NDru2IWjrO4BQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + } + }, + "node_modules/@radix-ui/react-dropdown-menu/node_modules/react-remove-scroll": { + "version": "2.5.5", + "resolved": "https://registry.npmjs.org/react-remove-scroll/-/react-remove-scroll-2.5.5.tgz", + "integrity": "sha512-ImKhrzJJsyXJfBZ4bzu8Bwpka14c/fQt0k+cyFp/PBhTfyDnU5hjOtM4AG/0AMyy8oKzOTR0lDgJIM7pYXI0kw==", + "license": "MIT", + "dependencies": { + "react-remove-scroll-bar": "^2.3.3", + "react-style-singleton": "^2.2.1", + "tslib": "^2.1.0", + "use-callback-ref": "^1.3.0", + "use-sidecar": "^1.1.2" + }, + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "@types/react": "^16.8.0 || ^17.0.0 || ^18.0.0", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-focus-guards": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-guards/-/react-focus-guards-1.1.2.tgz", + "integrity": "sha512-fyjAACV62oPV925xFCrH8DR5xWhg9KYtJT4s3u54jxp+L/hbpTY2kIeEFFbFe+a/HCE94zGQMZLIpVTPVZDhaA==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-focus-scope": { + "version": "1.1.7", + "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-scope/-/react-focus-scope-1.1.7.tgz", + "integrity": "sha512-t2ODlkXBQyn7jkl6TNaw/MtVEVvIGelJDCG41Okq/KwUsJBwQ4XVZsHAVUkK4mBv3ewiAS3PGuUWuY2BoK4ZUw==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-primitive": "2.1.3", + "@radix-ui/react-use-callback-ref": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-focus-scope/node_modules/@radix-ui/react-compose-refs": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz", + "integrity": "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-focus-scope/node_modules/@radix-ui/react-primitive": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz", + "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-slot": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-focus-scope/node_modules/@radix-ui/react-slot": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz", + "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-focus-scope/node_modules/@radix-ui/react-use-callback-ref": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.1.1.tgz", + "integrity": "sha512-FkBMwD+qbGQeMu1cOHnuGB6x4yzPjho8ap5WtbEJ26umhgqVXbhekKUQO+hZEL1vU92a3wHwdp0HAcqAUF5iDg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-hover-card": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/@radix-ui/react-hover-card/-/react-hover-card-1.0.6.tgz", + "integrity": "sha512-2K3ToJuMk9wjwBOa+jdg2oPma+AmLdcEyTNsG/iC4BDVG3E0/mGCjbY8PEDSLxJcUi+nJi2QII+ec/4kWd88DA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-dismissable-layer": "1.0.4", + "@radix-ui/react-popper": "1.1.2", + "@radix-ui/react-portal": "1.0.3", + "@radix-ui/react-presence": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-controllable-state": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-hover-card/node_modules/@radix-ui/react-arrow": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-arrow/-/react-arrow-1.0.3.tgz", + "integrity": "sha512-wSP+pHsB/jQRaL6voubsQ/ZlrGBHHrOjmBnr19hxYgtS0WvAFwZhK2WP/YY5yF9uKECCEEDGxuLxq1NBK51wFA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-primitive": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-hover-card/node_modules/@radix-ui/react-dismissable-layer": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-dismissable-layer/-/react-dismissable-layer-1.0.4.tgz", + "integrity": "sha512-7UpBa/RKMoHJYjie1gkF1DlK8l1fdU/VKDpoS3rCCo8YBJR294GwcEHyxHw72yvphJ7ld0AXEcSLAzY2F/WyCg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-escape-keydown": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-hover-card/node_modules/@radix-ui/react-popper": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-popper/-/react-popper-1.1.2.tgz", + "integrity": "sha512-1CnGGfFi/bbqtJZZ0P/NQY20xdG3E0LALJaLUEoKwPLwl6PPPfbeiCqMVQnhoFRAxjJj4RpBRJzDmUgsex2tSg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@floating-ui/react-dom": "^2.0.0", + "@radix-ui/react-arrow": "1.0.3", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-layout-effect": "1.0.1", + "@radix-ui/react-use-rect": "1.0.1", + "@radix-ui/react-use-size": "1.0.1", + "@radix-ui/rect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-hover-card/node_modules/@radix-ui/react-portal": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-portal/-/react-portal-1.0.3.tgz", + "integrity": "sha512-xLYZeHrWoPmA5mEKEfZZevoVRK/Q43GfzRXkWV6qawIWWK8t6ifIiLQdd7rmQ4Vk1bmI21XhqF9BN3jWf+phpA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-primitive": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-hover-card/node_modules/@radix-ui/react-use-escape-keydown": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-escape-keydown/-/react-use-escape-keydown-1.0.3.tgz", + "integrity": "sha512-vyL82j40hcFicA+M4Ex7hVkB9vHgSse1ZWomAqV2Je3RleKGO5iM8KMOEtfoSB0PnIelMd2lATjTGMYqN5ylTg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-callback-ref": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-hover-card/node_modules/@radix-ui/react-use-rect": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-rect/-/react-use-rect-1.0.1.tgz", + "integrity": "sha512-Cq5DLuSiuYVKNU8orzJMbl15TXilTnJKUCltMVQg53BQOF1/C5toAaGrowkgksdBQ9H+SRL23g0HDmg9tvmxXw==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/rect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-hover-card/node_modules/@radix-ui/rect": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/rect/-/rect-1.0.1.tgz", + "integrity": "sha512-fyrgCaedtvMg9NK3en0pnOYJdtfwxUcNolezkNPUsoX57X8oQk+NkqcvzHXD2uKNij6GXmWU9NDru2IWjrO4BQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + } + }, + "node_modules/@radix-ui/react-icons": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/@radix-ui/react-icons/-/react-icons-1.3.0.tgz", + "integrity": "sha512-jQxj/0LKgp+j9BiTXz3O3sgs26RNet2iLWmsPyRz2SIcR4q/4SbazXfnYwbAr+vLYKSfc7qxzyGQA1HLlYiuNw==", + "license": "MIT", + "peerDependencies": { + "react": "^16.x || ^17.x || ^18.x" + } + }, + "node_modules/@radix-ui/react-id": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.1.1.tgz", + "integrity": "sha512-kGkGegYIdQsOb4XjsfM97rXsiHaBwco+hFI66oO4s9LU+PLAC5oJ7khdOVFxkhsmlbpUqDAvXw11CluXP+jkHg==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-id/node_modules/@radix-ui/react-use-layout-effect": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.1.tgz", + "integrity": "sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-label": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-label/-/react-label-2.0.2.tgz", + "integrity": "sha512-N5ehvlM7qoTLx7nWPodsPYPgMzA5WM8zZChQg8nyFJKnDO5WHdba1vv5/H6IO5LtJMfD2Q3wh1qHFGNtK0w3bQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-primitive": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-menu": { + "version": "2.1.15", + "resolved": "https://registry.npmjs.org/@radix-ui/react-menu/-/react-menu-2.1.15.tgz", + "integrity": "sha512-tVlmA3Vb9n8SZSd+YSbuFR66l87Wiy4du+YE+0hzKQEANA+7cWKH1WgqcEX4pXqxUFQKrWQGHdvEfw00TjFiew==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.1.2", + "@radix-ui/react-collection": "1.1.7", + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-context": "1.1.2", + "@radix-ui/react-direction": "1.1.1", + "@radix-ui/react-dismissable-layer": "1.1.10", + "@radix-ui/react-focus-guards": "1.1.2", + "@radix-ui/react-focus-scope": "1.1.7", + "@radix-ui/react-id": "1.1.1", + "@radix-ui/react-popper": "1.2.7", + "@radix-ui/react-portal": "1.1.9", + "@radix-ui/react-presence": "1.1.4", + "@radix-ui/react-primitive": "2.1.3", + "@radix-ui/react-roving-focus": "1.1.10", + "@radix-ui/react-slot": "1.2.3", + "@radix-ui/react-use-callback-ref": "1.1.1", + "aria-hidden": "^1.2.4", + "react-remove-scroll": "^2.6.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-menu/node_modules/@radix-ui/primitive": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.2.tgz", + "integrity": "sha512-XnbHrrprsNqZKQhStrSwgRUQzoCI1glLzdw79xiZPoofhGICeZRSQ3dIxAKH1gb3OHfNf4d6f+vAv3kil2eggA==", + "license": "MIT" + }, + "node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-compose-refs": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz", + "integrity": "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-context": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.1.2.tgz", + "integrity": "sha512-jCi/QKUM2r1Ju5a3J64TH2A5SpKAgh0LpknyqdQ4m6DCV0xJ2HG1xARRwNGPQfi1SLdLWZ1OJz6F4OMBBNiGJA==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-presence": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-presence/-/react-presence-1.1.4.tgz", + "integrity": "sha512-ueDqRbdc4/bkaQT3GIpLQssRlFgWaL/U2z/S31qRwwLWoxHLgry3SIfCwhxeQNbirEUXFa+lq3RL3oBYXtcmIA==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-primitive": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz", + "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-slot": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-slot": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz", + "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-use-callback-ref": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.1.1.tgz", + "integrity": "sha512-FkBMwD+qbGQeMu1cOHnuGB6x4yzPjho8ap5WtbEJ26umhgqVXbhekKUQO+hZEL1vU92a3wHwdp0HAcqAUF5iDg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-use-layout-effect": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.1.tgz", + "integrity": "sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-navigation-menu": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-navigation-menu/-/react-navigation-menu-1.1.3.tgz", + "integrity": "sha512-x4Uv0N47ABx3/frJazYXxvMpZeKJe0qmRIgQ2o3lhTqnTVg+CaZfVVO4nQLn3QJcDkTz8icElKffhFng47XIBA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-collection": "1.0.3", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-direction": "1.0.1", + "@radix-ui/react-dismissable-layer": "1.0.4", + "@radix-ui/react-id": "1.0.1", + "@radix-ui/react-presence": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-controllable-state": "1.0.1", + "@radix-ui/react-use-layout-effect": "1.0.1", + "@radix-ui/react-use-previous": "1.0.1", + "@radix-ui/react-visually-hidden": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-navigation-menu/node_modules/@radix-ui/react-collection": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-collection/-/react-collection-1.0.3.tgz", + "integrity": "sha512-3SzW+0PW7yBBoQlT8wNcGtaxaD0XSu0uLUFgrtHY08Acx05TaHaOmVLR73c0j/cqpDy53KBMO7s0dx2wmOIDIA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-slot": "1.0.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-navigation-menu/node_modules/@radix-ui/react-direction": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-direction/-/react-direction-1.0.1.tgz", + "integrity": "sha512-RXcvnXgyvYvBEOhCBuddKecVkoMiI10Jcm5cTI7abJRAHYfFxeu+FBQs/DvdxSYucxR5mna0dNsL6QFlds5TMA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-navigation-menu/node_modules/@radix-ui/react-dismissable-layer": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-dismissable-layer/-/react-dismissable-layer-1.0.4.tgz", + "integrity": "sha512-7UpBa/RKMoHJYjie1gkF1DlK8l1fdU/VKDpoS3rCCo8YBJR294GwcEHyxHw72yvphJ7ld0AXEcSLAzY2F/WyCg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-escape-keydown": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-navigation-menu/node_modules/@radix-ui/react-id": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.0.1.tgz", + "integrity": "sha512-tI7sT/kqYp8p96yGWY1OAnLHrqDgzHefRBKQ2YAkBS5ja7QLcZ9Z/uY7bEjPUatf8RomoXM8/1sMj1IJaE5UzQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-layout-effect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-navigation-menu/node_modules/@radix-ui/react-use-escape-keydown": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-escape-keydown/-/react-use-escape-keydown-1.0.3.tgz", + "integrity": "sha512-vyL82j40hcFicA+M4Ex7hVkB9vHgSse1ZWomAqV2Je3RleKGO5iM8KMOEtfoSB0PnIelMd2lATjTGMYqN5ylTg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-callback-ref": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popover": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/@radix-ui/react-popover/-/react-popover-1.0.6.tgz", + "integrity": "sha512-cZ4defGpkZ0qTRtlIBzJLSzL6ht7ofhhW4i1+pkemjV1IKXm0wgCRnee154qlV6r9Ttunmh2TNZhMfV2bavUyA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-dismissable-layer": "1.0.4", + "@radix-ui/react-focus-guards": "1.0.1", + "@radix-ui/react-focus-scope": "1.0.3", + "@radix-ui/react-id": "1.0.1", + "@radix-ui/react-popper": "1.1.2", + "@radix-ui/react-portal": "1.0.3", + "@radix-ui/react-presence": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-slot": "1.0.2", + "@radix-ui/react-use-controllable-state": "1.0.1", + "aria-hidden": "^1.1.1", + "react-remove-scroll": "2.5.5" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popover/node_modules/@radix-ui/react-arrow": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-arrow/-/react-arrow-1.0.3.tgz", + "integrity": "sha512-wSP+pHsB/jQRaL6voubsQ/ZlrGBHHrOjmBnr19hxYgtS0WvAFwZhK2WP/YY5yF9uKECCEEDGxuLxq1NBK51wFA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-primitive": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popover/node_modules/@radix-ui/react-dismissable-layer": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-dismissable-layer/-/react-dismissable-layer-1.0.4.tgz", + "integrity": "sha512-7UpBa/RKMoHJYjie1gkF1DlK8l1fdU/VKDpoS3rCCo8YBJR294GwcEHyxHw72yvphJ7ld0AXEcSLAzY2F/WyCg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-escape-keydown": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popover/node_modules/@radix-ui/react-focus-guards": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-guards/-/react-focus-guards-1.0.1.tgz", + "integrity": "sha512-Rect2dWbQ8waGzhMavsIbmSVCgYxkXLxxR3ZvCX79JOglzdEy4JXMb98lq4hPxUbLr77nP0UOGf4rcMU+s1pUA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popover/node_modules/@radix-ui/react-focus-scope": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-scope/-/react-focus-scope-1.0.3.tgz", + "integrity": "sha512-upXdPfqI4islj2CslyfUBNlaJCPybbqRHAi1KER7Isel9Q2AtSJ0zRBZv8mWQiFXD2nyAJ4BhC3yXgZ6kMBSrQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popover/node_modules/@radix-ui/react-id": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.0.1.tgz", + "integrity": "sha512-tI7sT/kqYp8p96yGWY1OAnLHrqDgzHefRBKQ2YAkBS5ja7QLcZ9Z/uY7bEjPUatf8RomoXM8/1sMj1IJaE5UzQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-layout-effect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popover/node_modules/@radix-ui/react-popper": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-popper/-/react-popper-1.1.2.tgz", + "integrity": "sha512-1CnGGfFi/bbqtJZZ0P/NQY20xdG3E0LALJaLUEoKwPLwl6PPPfbeiCqMVQnhoFRAxjJj4RpBRJzDmUgsex2tSg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@floating-ui/react-dom": "^2.0.0", + "@radix-ui/react-arrow": "1.0.3", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-layout-effect": "1.0.1", + "@radix-ui/react-use-rect": "1.0.1", + "@radix-ui/react-use-size": "1.0.1", + "@radix-ui/rect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popover/node_modules/@radix-ui/react-portal": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-portal/-/react-portal-1.0.3.tgz", + "integrity": "sha512-xLYZeHrWoPmA5mEKEfZZevoVRK/Q43GfzRXkWV6qawIWWK8t6ifIiLQdd7rmQ4Vk1bmI21XhqF9BN3jWf+phpA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-primitive": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popover/node_modules/@radix-ui/react-use-escape-keydown": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-escape-keydown/-/react-use-escape-keydown-1.0.3.tgz", + "integrity": "sha512-vyL82j40hcFicA+M4Ex7hVkB9vHgSse1ZWomAqV2Je3RleKGO5iM8KMOEtfoSB0PnIelMd2lATjTGMYqN5ylTg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-callback-ref": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popover/node_modules/@radix-ui/react-use-rect": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-rect/-/react-use-rect-1.0.1.tgz", + "integrity": "sha512-Cq5DLuSiuYVKNU8orzJMbl15TXilTnJKUCltMVQg53BQOF1/C5toAaGrowkgksdBQ9H+SRL23g0HDmg9tvmxXw==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/rect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popover/node_modules/@radix-ui/rect": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/rect/-/rect-1.0.1.tgz", + "integrity": "sha512-fyrgCaedtvMg9NK3en0pnOYJdtfwxUcNolezkNPUsoX57X8oQk+NkqcvzHXD2uKNij6GXmWU9NDru2IWjrO4BQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + } + }, + "node_modules/@radix-ui/react-popover/node_modules/react-remove-scroll": { + "version": "2.5.5", + "resolved": "https://registry.npmjs.org/react-remove-scroll/-/react-remove-scroll-2.5.5.tgz", + "integrity": "sha512-ImKhrzJJsyXJfBZ4bzu8Bwpka14c/fQt0k+cyFp/PBhTfyDnU5hjOtM4AG/0AMyy8oKzOTR0lDgJIM7pYXI0kw==", + "license": "MIT", + "dependencies": { + "react-remove-scroll-bar": "^2.3.3", + "react-style-singleton": "^2.2.1", + "tslib": "^2.1.0", + "use-callback-ref": "^1.3.0", + "use-sidecar": "^1.1.2" + }, + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "@types/react": "^16.8.0 || ^17.0.0 || ^18.0.0", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popper": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/@radix-ui/react-popper/-/react-popper-1.2.7.tgz", + "integrity": "sha512-IUFAccz1JyKcf/RjB552PlWwxjeCJB8/4KxT7EhBHOJM+mN7LdW+B3kacJXILm32xawcMMjb2i0cIZpo+f9kiQ==", + "license": "MIT", + "dependencies": { + "@floating-ui/react-dom": "^2.0.0", + "@radix-ui/react-arrow": "1.1.7", + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-context": "1.1.2", + "@radix-ui/react-primitive": "2.1.3", + "@radix-ui/react-use-callback-ref": "1.1.1", + "@radix-ui/react-use-layout-effect": "1.1.1", + "@radix-ui/react-use-rect": "1.1.1", + "@radix-ui/react-use-size": "1.1.1", + "@radix-ui/rect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popper/node_modules/@radix-ui/react-compose-refs": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz", + "integrity": "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popper/node_modules/@radix-ui/react-context": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.1.2.tgz", + "integrity": "sha512-jCi/QKUM2r1Ju5a3J64TH2A5SpKAgh0LpknyqdQ4m6DCV0xJ2HG1xARRwNGPQfi1SLdLWZ1OJz6F4OMBBNiGJA==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popper/node_modules/@radix-ui/react-primitive": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz", + "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-slot": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popper/node_modules/@radix-ui/react-slot": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz", + "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popper/node_modules/@radix-ui/react-use-callback-ref": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.1.1.tgz", + "integrity": "sha512-FkBMwD+qbGQeMu1cOHnuGB6x4yzPjho8ap5WtbEJ26umhgqVXbhekKUQO+hZEL1vU92a3wHwdp0HAcqAUF5iDg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popper/node_modules/@radix-ui/react-use-layout-effect": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.1.tgz", + "integrity": "sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popper/node_modules/@radix-ui/react-use-size": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-size/-/react-use-size-1.1.1.tgz", + "integrity": "sha512-ewrXRDTAqAXlkl6t/fkXWNAhFX9I+CkKlw6zjEwk86RSPKwZr3xpBRso655aqYafwtnbpHLj6toFzmd6xdVptQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-portal": { + "version": "1.1.9", + "resolved": "https://registry.npmjs.org/@radix-ui/react-portal/-/react-portal-1.1.9.tgz", + "integrity": "sha512-bpIxvq03if6UNwXZ+HTK71JLh4APvnXntDc6XOX8UVq4XQOVl7lwok0AvIl+b8zgCw3fSaVTZMpAPPagXbKmHQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-primitive": "2.1.3", + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-portal/node_modules/@radix-ui/react-compose-refs": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz", + "integrity": "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-portal/node_modules/@radix-ui/react-primitive": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz", + "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-slot": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-portal/node_modules/@radix-ui/react-slot": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz", + "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-portal/node_modules/@radix-ui/react-use-layout-effect": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.1.tgz", + "integrity": "sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-presence": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-presence/-/react-presence-1.0.1.tgz", + "integrity": "sha512-UXLW4UAbIY5ZjcvzjfRFo5gxva8QirC9hF7wRE4U5gz+TP0DbRk+//qyuAQ1McDxBt1xNMBTaciFGvEmJvAZCg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-use-layout-effect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-primitive": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-1.0.3.tgz", + "integrity": "sha512-yi58uVyoAcK/Nq1inRY56ZSjKypBNKTa/1mcL8qdl6oJeEaDbOldlzrGn7P6Q3Id5d+SYNGc5AJgc4vGhjs5+g==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-slot": "1.0.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-progress": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-progress/-/react-progress-1.0.3.tgz", + "integrity": "sha512-5G6Om/tYSxjSeEdrb1VfKkfZfn/1IlPWd731h2RfPuSbIfNUgfqAwbKfJCg/PP6nuUCTrYzalwHSpSinoWoCag==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-primitive": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-radio-group": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-radio-group/-/react-radio-group-1.1.3.tgz", + "integrity": "sha512-x+yELayyefNeKeTx4fjK6j99Fs6c4qKm3aY38G3swQVTN6xMpsrbigC0uHs2L//g8q4qR7qOcww8430jJmi2ag==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-direction": "1.0.1", + "@radix-ui/react-presence": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-roving-focus": "1.0.4", + "@radix-ui/react-use-controllable-state": "1.0.1", + "@radix-ui/react-use-previous": "1.0.1", + "@radix-ui/react-use-size": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-radio-group/node_modules/@radix-ui/react-collection": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-collection/-/react-collection-1.0.3.tgz", + "integrity": "sha512-3SzW+0PW7yBBoQlT8wNcGtaxaD0XSu0uLUFgrtHY08Acx05TaHaOmVLR73c0j/cqpDy53KBMO7s0dx2wmOIDIA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-slot": "1.0.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-radio-group/node_modules/@radix-ui/react-direction": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-direction/-/react-direction-1.0.1.tgz", + "integrity": "sha512-RXcvnXgyvYvBEOhCBuddKecVkoMiI10Jcm5cTI7abJRAHYfFxeu+FBQs/DvdxSYucxR5mna0dNsL6QFlds5TMA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-radio-group/node_modules/@radix-ui/react-id": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.0.1.tgz", + "integrity": "sha512-tI7sT/kqYp8p96yGWY1OAnLHrqDgzHefRBKQ2YAkBS5ja7QLcZ9Z/uY7bEjPUatf8RomoXM8/1sMj1IJaE5UzQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-layout-effect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-radio-group/node_modules/@radix-ui/react-roving-focus": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-roving-focus/-/react-roving-focus-1.0.4.tgz", + "integrity": "sha512-2mUg5Mgcu001VkGy+FfzZyzbmuUWzgWkj3rvv4yu+mLw03+mTzbxZHvfcGyFp2b8EkQeMkpRQ5FiA2Vr2O6TeQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-collection": "1.0.3", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-direction": "1.0.1", + "@radix-ui/react-id": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-controllable-state": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-roving-focus": { + "version": "1.1.10", + "resolved": "https://registry.npmjs.org/@radix-ui/react-roving-focus/-/react-roving-focus-1.1.10.tgz", + "integrity": "sha512-dT9aOXUen9JSsxnMPv/0VqySQf5eDQ6LCk5Sw28kamz8wSOW2bJdlX2Bg5VUIIcV+6XlHpWTIuTPCf/UNIyq8Q==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.1.2", + "@radix-ui/react-collection": "1.1.7", + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-context": "1.1.2", + "@radix-ui/react-direction": "1.1.1", + "@radix-ui/react-id": "1.1.1", + "@radix-ui/react-primitive": "2.1.3", + "@radix-ui/react-use-callback-ref": "1.1.1", + "@radix-ui/react-use-controllable-state": "1.2.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-roving-focus/node_modules/@radix-ui/primitive": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.2.tgz", + "integrity": "sha512-XnbHrrprsNqZKQhStrSwgRUQzoCI1glLzdw79xiZPoofhGICeZRSQ3dIxAKH1gb3OHfNf4d6f+vAv3kil2eggA==", + "license": "MIT" + }, + "node_modules/@radix-ui/react-roving-focus/node_modules/@radix-ui/react-compose-refs": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz", + "integrity": "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-roving-focus/node_modules/@radix-ui/react-context": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.1.2.tgz", + "integrity": "sha512-jCi/QKUM2r1Ju5a3J64TH2A5SpKAgh0LpknyqdQ4m6DCV0xJ2HG1xARRwNGPQfi1SLdLWZ1OJz6F4OMBBNiGJA==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-roving-focus/node_modules/@radix-ui/react-primitive": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz", + "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-slot": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-roving-focus/node_modules/@radix-ui/react-slot": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz", + "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-roving-focus/node_modules/@radix-ui/react-use-callback-ref": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.1.1.tgz", + "integrity": "sha512-FkBMwD+qbGQeMu1cOHnuGB6x4yzPjho8ap5WtbEJ26umhgqVXbhekKUQO+hZEL1vU92a3wHwdp0HAcqAUF5iDg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-roving-focus/node_modules/@radix-ui/react-use-controllable-state": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-controllable-state/-/react-use-controllable-state-1.2.2.tgz", + "integrity": "sha512-BjasUjixPFdS+NKkypcyyN5Pmg83Olst0+c6vGov0diwTEo6mgdqVR6hxcEgFuh4QrAs7Rc+9KuGJ9TVCj0Zzg==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-effect-event": "0.0.2", + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-roving-focus/node_modules/@radix-ui/react-use-layout-effect": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.1.tgz", + "integrity": "sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-scroll-area": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-scroll-area/-/react-scroll-area-1.0.4.tgz", + "integrity": "sha512-OIClwBkwPG+FKvC4OMTRaa/3cfD069nkKFFL/TQzRzaO42Ce5ivKU9VMKgT7UU6UIkjcQqKBrDOIzWtPGw6e6w==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/number": "1.0.1", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-direction": "1.0.1", + "@radix-ui/react-presence": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-layout-effect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-scroll-area/node_modules/@radix-ui/react-direction": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-direction/-/react-direction-1.0.1.tgz", + "integrity": "sha512-RXcvnXgyvYvBEOhCBuddKecVkoMiI10Jcm5cTI7abJRAHYfFxeu+FBQs/DvdxSYucxR5mna0dNsL6QFlds5TMA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-select": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-select/-/react-select-1.2.2.tgz", + "integrity": "sha512-zI7McXr8fNaSrUY9mZe4x/HC0jTLY9fWNhO1oLWYMQGDXuV4UCivIGTxwioSzO0ZCYX9iSLyWmAh/1TOmX3Cnw==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/number": "1.0.1", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-collection": "1.0.3", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-direction": "1.0.1", + "@radix-ui/react-dismissable-layer": "1.0.4", + "@radix-ui/react-focus-guards": "1.0.1", + "@radix-ui/react-focus-scope": "1.0.3", + "@radix-ui/react-id": "1.0.1", + "@radix-ui/react-popper": "1.1.2", + "@radix-ui/react-portal": "1.0.3", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-slot": "1.0.2", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-controllable-state": "1.0.1", + "@radix-ui/react-use-layout-effect": "1.0.1", + "@radix-ui/react-use-previous": "1.0.1", + "@radix-ui/react-visually-hidden": "1.0.3", + "aria-hidden": "^1.1.1", + "react-remove-scroll": "2.5.5" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-select/node_modules/@radix-ui/react-arrow": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-arrow/-/react-arrow-1.0.3.tgz", + "integrity": "sha512-wSP+pHsB/jQRaL6voubsQ/ZlrGBHHrOjmBnr19hxYgtS0WvAFwZhK2WP/YY5yF9uKECCEEDGxuLxq1NBK51wFA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-primitive": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-select/node_modules/@radix-ui/react-collection": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-collection/-/react-collection-1.0.3.tgz", + "integrity": "sha512-3SzW+0PW7yBBoQlT8wNcGtaxaD0XSu0uLUFgrtHY08Acx05TaHaOmVLR73c0j/cqpDy53KBMO7s0dx2wmOIDIA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-slot": "1.0.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-select/node_modules/@radix-ui/react-direction": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-direction/-/react-direction-1.0.1.tgz", + "integrity": "sha512-RXcvnXgyvYvBEOhCBuddKecVkoMiI10Jcm5cTI7abJRAHYfFxeu+FBQs/DvdxSYucxR5mna0dNsL6QFlds5TMA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-select/node_modules/@radix-ui/react-dismissable-layer": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-dismissable-layer/-/react-dismissable-layer-1.0.4.tgz", + "integrity": "sha512-7UpBa/RKMoHJYjie1gkF1DlK8l1fdU/VKDpoS3rCCo8YBJR294GwcEHyxHw72yvphJ7ld0AXEcSLAzY2F/WyCg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-escape-keydown": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-select/node_modules/@radix-ui/react-focus-guards": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-guards/-/react-focus-guards-1.0.1.tgz", + "integrity": "sha512-Rect2dWbQ8waGzhMavsIbmSVCgYxkXLxxR3ZvCX79JOglzdEy4JXMb98lq4hPxUbLr77nP0UOGf4rcMU+s1pUA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-select/node_modules/@radix-ui/react-focus-scope": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-scope/-/react-focus-scope-1.0.3.tgz", + "integrity": "sha512-upXdPfqI4islj2CslyfUBNlaJCPybbqRHAi1KER7Isel9Q2AtSJ0zRBZv8mWQiFXD2nyAJ4BhC3yXgZ6kMBSrQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-select/node_modules/@radix-ui/react-id": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.0.1.tgz", + "integrity": "sha512-tI7sT/kqYp8p96yGWY1OAnLHrqDgzHefRBKQ2YAkBS5ja7QLcZ9Z/uY7bEjPUatf8RomoXM8/1sMj1IJaE5UzQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-layout-effect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-select/node_modules/@radix-ui/react-popper": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-popper/-/react-popper-1.1.2.tgz", + "integrity": "sha512-1CnGGfFi/bbqtJZZ0P/NQY20xdG3E0LALJaLUEoKwPLwl6PPPfbeiCqMVQnhoFRAxjJj4RpBRJzDmUgsex2tSg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@floating-ui/react-dom": "^2.0.0", + "@radix-ui/react-arrow": "1.0.3", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-layout-effect": "1.0.1", + "@radix-ui/react-use-rect": "1.0.1", + "@radix-ui/react-use-size": "1.0.1", + "@radix-ui/rect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-select/node_modules/@radix-ui/react-portal": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-portal/-/react-portal-1.0.3.tgz", + "integrity": "sha512-xLYZeHrWoPmA5mEKEfZZevoVRK/Q43GfzRXkWV6qawIWWK8t6ifIiLQdd7rmQ4Vk1bmI21XhqF9BN3jWf+phpA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-primitive": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-select/node_modules/@radix-ui/react-use-escape-keydown": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-escape-keydown/-/react-use-escape-keydown-1.0.3.tgz", + "integrity": "sha512-vyL82j40hcFicA+M4Ex7hVkB9vHgSse1ZWomAqV2Je3RleKGO5iM8KMOEtfoSB0PnIelMd2lATjTGMYqN5ylTg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-callback-ref": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-select/node_modules/@radix-ui/react-use-rect": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-rect/-/react-use-rect-1.0.1.tgz", + "integrity": "sha512-Cq5DLuSiuYVKNU8orzJMbl15TXilTnJKUCltMVQg53BQOF1/C5toAaGrowkgksdBQ9H+SRL23g0HDmg9tvmxXw==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/rect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-select/node_modules/@radix-ui/rect": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/rect/-/rect-1.0.1.tgz", + "integrity": "sha512-fyrgCaedtvMg9NK3en0pnOYJdtfwxUcNolezkNPUsoX57X8oQk+NkqcvzHXD2uKNij6GXmWU9NDru2IWjrO4BQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + } + }, + "node_modules/@radix-ui/react-select/node_modules/react-remove-scroll": { + "version": "2.5.5", + "resolved": "https://registry.npmjs.org/react-remove-scroll/-/react-remove-scroll-2.5.5.tgz", + "integrity": "sha512-ImKhrzJJsyXJfBZ4bzu8Bwpka14c/fQt0k+cyFp/PBhTfyDnU5hjOtM4AG/0AMyy8oKzOTR0lDgJIM7pYXI0kw==", + "license": "MIT", + "dependencies": { + "react-remove-scroll-bar": "^2.3.3", + "react-style-singleton": "^2.2.1", + "tslib": "^2.1.0", + "use-callback-ref": "^1.3.0", + "use-sidecar": "^1.1.2" + }, + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "@types/react": "^16.8.0 || ^17.0.0 || ^18.0.0", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-separator": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-separator/-/react-separator-1.0.3.tgz", + "integrity": "sha512-itYmTy/kokS21aiV5+Z56MZB54KrhPgn6eHDKkFeOLR34HMN2s8PaN47qZZAGnvupcjxHaFZnW4pQEh0BvvVuw==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-primitive": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-slider": { + "version": "1.3.5", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slider/-/react-slider-1.3.5.tgz", + "integrity": "sha512-rkfe2pU2NBAYfGaxa3Mqosi7VZEWX5CxKaanRv0vZd4Zhl9fvQrg0VM93dv3xGLGfrHuoTRF3JXH8nb9g+B3fw==", + "license": "MIT", + "dependencies": { + "@radix-ui/number": "1.1.1", + "@radix-ui/primitive": "1.1.2", + "@radix-ui/react-collection": "1.1.7", + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-context": "1.1.2", + "@radix-ui/react-direction": "1.1.1", + "@radix-ui/react-primitive": "2.1.3", + "@radix-ui/react-use-controllable-state": "1.2.2", + "@radix-ui/react-use-layout-effect": "1.1.1", + "@radix-ui/react-use-previous": "1.1.1", + "@radix-ui/react-use-size": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-slider/node_modules/@radix-ui/number": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/number/-/number-1.1.1.tgz", + "integrity": "sha512-MkKCwxlXTgz6CFoJx3pCwn07GKp36+aZyu/u2Ln2VrA5DcdyCZkASEDBTd8x5whTQQL5CiYf4prXKLcgQdv29g==", + "license": "MIT" + }, + "node_modules/@radix-ui/react-slider/node_modules/@radix-ui/primitive": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.2.tgz", + "integrity": "sha512-XnbHrrprsNqZKQhStrSwgRUQzoCI1glLzdw79xiZPoofhGICeZRSQ3dIxAKH1gb3OHfNf4d6f+vAv3kil2eggA==", + "license": "MIT" + }, + "node_modules/@radix-ui/react-slider/node_modules/@radix-ui/react-compose-refs": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz", + "integrity": "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-slider/node_modules/@radix-ui/react-context": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.1.2.tgz", + "integrity": "sha512-jCi/QKUM2r1Ju5a3J64TH2A5SpKAgh0LpknyqdQ4m6DCV0xJ2HG1xARRwNGPQfi1SLdLWZ1OJz6F4OMBBNiGJA==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-slider/node_modules/@radix-ui/react-primitive": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz", + "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-slot": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-slider/node_modules/@radix-ui/react-slot": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz", + "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-slider/node_modules/@radix-ui/react-use-controllable-state": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-controllable-state/-/react-use-controllable-state-1.2.2.tgz", + "integrity": "sha512-BjasUjixPFdS+NKkypcyyN5Pmg83Olst0+c6vGov0diwTEo6mgdqVR6hxcEgFuh4QrAs7Rc+9KuGJ9TVCj0Zzg==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-effect-event": "0.0.2", + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-slider/node_modules/@radix-ui/react-use-layout-effect": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.1.tgz", + "integrity": "sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-slider/node_modules/@radix-ui/react-use-previous": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-previous/-/react-use-previous-1.1.1.tgz", + "integrity": "sha512-2dHfToCj/pzca2Ck724OZ5L0EVrr3eHRNsG/b3xQJLA2hZpVCS99bLAX+hm1IHXDEnzU6by5z/5MIY794/a8NQ==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-slider/node_modules/@radix-ui/react-use-size": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-size/-/react-use-size-1.1.1.tgz", + "integrity": "sha512-ewrXRDTAqAXlkl6t/fkXWNAhFX9I+CkKlw6zjEwk86RSPKwZr3xpBRso655aqYafwtnbpHLj6toFzmd6xdVptQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-slot": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.0.2.tgz", + "integrity": "sha512-YeTpuq4deV+6DusvVUW4ivBgnkHwECUu0BiN43L5UCDFgdhsRUWAghhTF5MbvNTPzmiFOx90asDSUjWuCNapwg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-compose-refs": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-switch": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/@radix-ui/react-switch/-/react-switch-1.2.5.tgz", + "integrity": "sha512-5ijLkak6ZMylXsaImpZ8u4Rlf5grRmoc0p0QeX9VJtlrM4f5m3nCTX8tWga/zOA8PZYIR/t0p2Mnvd7InrJ6yQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.1.2", + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-context": "1.1.2", + "@radix-ui/react-primitive": "2.1.3", + "@radix-ui/react-use-controllable-state": "1.2.2", + "@radix-ui/react-use-previous": "1.1.1", + "@radix-ui/react-use-size": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-switch/node_modules/@radix-ui/primitive": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.2.tgz", + "integrity": "sha512-XnbHrrprsNqZKQhStrSwgRUQzoCI1glLzdw79xiZPoofhGICeZRSQ3dIxAKH1gb3OHfNf4d6f+vAv3kil2eggA==", + "license": "MIT" + }, + "node_modules/@radix-ui/react-switch/node_modules/@radix-ui/react-compose-refs": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz", + "integrity": "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-switch/node_modules/@radix-ui/react-context": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.1.2.tgz", + "integrity": "sha512-jCi/QKUM2r1Ju5a3J64TH2A5SpKAgh0LpknyqdQ4m6DCV0xJ2HG1xARRwNGPQfi1SLdLWZ1OJz6F4OMBBNiGJA==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-switch/node_modules/@radix-ui/react-primitive": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz", + "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-slot": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-switch/node_modules/@radix-ui/react-slot": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz", + "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-switch/node_modules/@radix-ui/react-use-controllable-state": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-controllable-state/-/react-use-controllable-state-1.2.2.tgz", + "integrity": "sha512-BjasUjixPFdS+NKkypcyyN5Pmg83Olst0+c6vGov0diwTEo6mgdqVR6hxcEgFuh4QrAs7Rc+9KuGJ9TVCj0Zzg==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-effect-event": "0.0.2", + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-switch/node_modules/@radix-ui/react-use-layout-effect": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.1.tgz", + "integrity": "sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-switch/node_modules/@radix-ui/react-use-previous": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-previous/-/react-use-previous-1.1.1.tgz", + "integrity": "sha512-2dHfToCj/pzca2Ck724OZ5L0EVrr3eHRNsG/b3xQJLA2hZpVCS99bLAX+hm1IHXDEnzU6by5z/5MIY794/a8NQ==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-switch/node_modules/@radix-ui/react-use-size": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-size/-/react-use-size-1.1.1.tgz", + "integrity": "sha512-ewrXRDTAqAXlkl6t/fkXWNAhFX9I+CkKlw6zjEwk86RSPKwZr3xpBRso655aqYafwtnbpHLj6toFzmd6xdVptQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tabs": { + "version": "1.1.12", + "resolved": "https://registry.npmjs.org/@radix-ui/react-tabs/-/react-tabs-1.1.12.tgz", + "integrity": "sha512-GTVAlRVrQrSw3cEARM0nAx73ixrWDPNZAruETn3oHCNP6SbZ/hNxdxp+u7VkIEv3/sFoLq1PfcHrl7Pnp0CDpw==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.1.2", + "@radix-ui/react-context": "1.1.2", + "@radix-ui/react-direction": "1.1.1", + "@radix-ui/react-id": "1.1.1", + "@radix-ui/react-presence": "1.1.4", + "@radix-ui/react-primitive": "2.1.3", + "@radix-ui/react-roving-focus": "1.1.10", + "@radix-ui/react-use-controllable-state": "1.2.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tabs/node_modules/@radix-ui/primitive": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.2.tgz", + "integrity": "sha512-XnbHrrprsNqZKQhStrSwgRUQzoCI1glLzdw79xiZPoofhGICeZRSQ3dIxAKH1gb3OHfNf4d6f+vAv3kil2eggA==", + "license": "MIT" + }, + "node_modules/@radix-ui/react-tabs/node_modules/@radix-ui/react-compose-refs": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz", + "integrity": "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tabs/node_modules/@radix-ui/react-context": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.1.2.tgz", + "integrity": "sha512-jCi/QKUM2r1Ju5a3J64TH2A5SpKAgh0LpknyqdQ4m6DCV0xJ2HG1xARRwNGPQfi1SLdLWZ1OJz6F4OMBBNiGJA==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tabs/node_modules/@radix-ui/react-presence": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-presence/-/react-presence-1.1.4.tgz", + "integrity": "sha512-ueDqRbdc4/bkaQT3GIpLQssRlFgWaL/U2z/S31qRwwLWoxHLgry3SIfCwhxeQNbirEUXFa+lq3RL3oBYXtcmIA==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tabs/node_modules/@radix-ui/react-primitive": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz", + "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-slot": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tabs/node_modules/@radix-ui/react-slot": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz", + "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tabs/node_modules/@radix-ui/react-use-controllable-state": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-controllable-state/-/react-use-controllable-state-1.2.2.tgz", + "integrity": "sha512-BjasUjixPFdS+NKkypcyyN5Pmg83Olst0+c6vGov0diwTEo6mgdqVR6hxcEgFuh4QrAs7Rc+9KuGJ9TVCj0Zzg==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-effect-event": "0.0.2", + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tabs/node_modules/@radix-ui/react-use-layout-effect": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.1.tgz", + "integrity": "sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toast": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-toast/-/react-toast-1.1.4.tgz", + "integrity": "sha512-wf+fc8DOywrpRK3jlPlWVe+ELYGHdKDaaARJZNuUTWyWYq7+ANCFLp4rTjZ/mcGkJJQ/vZ949Zis9xxEpfq9OA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-collection": "1.0.3", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-dismissable-layer": "1.0.4", + "@radix-ui/react-portal": "1.0.3", + "@radix-ui/react-presence": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-controllable-state": "1.0.1", + "@radix-ui/react-use-layout-effect": "1.0.1", + "@radix-ui/react-visually-hidden": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toast/node_modules/@radix-ui/react-collection": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-collection/-/react-collection-1.0.3.tgz", + "integrity": "sha512-3SzW+0PW7yBBoQlT8wNcGtaxaD0XSu0uLUFgrtHY08Acx05TaHaOmVLR73c0j/cqpDy53KBMO7s0dx2wmOIDIA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-slot": "1.0.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toast/node_modules/@radix-ui/react-dismissable-layer": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-dismissable-layer/-/react-dismissable-layer-1.0.4.tgz", + "integrity": "sha512-7UpBa/RKMoHJYjie1gkF1DlK8l1fdU/VKDpoS3rCCo8YBJR294GwcEHyxHw72yvphJ7ld0AXEcSLAzY2F/WyCg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-escape-keydown": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toast/node_modules/@radix-ui/react-portal": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-portal/-/react-portal-1.0.3.tgz", + "integrity": "sha512-xLYZeHrWoPmA5mEKEfZZevoVRK/Q43GfzRXkWV6qawIWWK8t6ifIiLQdd7rmQ4Vk1bmI21XhqF9BN3jWf+phpA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-primitive": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toast/node_modules/@radix-ui/react-use-escape-keydown": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-escape-keydown/-/react-use-escape-keydown-1.0.3.tgz", + "integrity": "sha512-vyL82j40hcFicA+M4Ex7hVkB9vHgSse1ZWomAqV2Je3RleKGO5iM8KMOEtfoSB0PnIelMd2lATjTGMYqN5ylTg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-callback-ref": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toggle": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-toggle/-/react-toggle-1.0.3.tgz", + "integrity": "sha512-Pkqg3+Bc98ftZGsl60CLANXQBBQ4W3mTFS9EJvNxKMZ7magklKV69/id1mlAlOFDDfHvlCms0fx8fA4CMKDJHg==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-controllable-state": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toggle-group": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-toggle-group/-/react-toggle-group-1.0.4.tgz", + "integrity": "sha512-Uaj/M/cMyiyT9Bx6fOZO0SAG4Cls0GptBWiBmBxofmDbNVnYYoyRWj/2M/6VCi/7qcXFWnHhRUfdfZFvvkuu8A==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-direction": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-roving-focus": "1.0.4", + "@radix-ui/react-toggle": "1.0.3", + "@radix-ui/react-use-controllable-state": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toggle-group/node_modules/@radix-ui/react-collection": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-collection/-/react-collection-1.0.3.tgz", + "integrity": "sha512-3SzW+0PW7yBBoQlT8wNcGtaxaD0XSu0uLUFgrtHY08Acx05TaHaOmVLR73c0j/cqpDy53KBMO7s0dx2wmOIDIA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-slot": "1.0.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toggle-group/node_modules/@radix-ui/react-direction": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-direction/-/react-direction-1.0.1.tgz", + "integrity": "sha512-RXcvnXgyvYvBEOhCBuddKecVkoMiI10Jcm5cTI7abJRAHYfFxeu+FBQs/DvdxSYucxR5mna0dNsL6QFlds5TMA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toggle-group/node_modules/@radix-ui/react-id": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.0.1.tgz", + "integrity": "sha512-tI7sT/kqYp8p96yGWY1OAnLHrqDgzHefRBKQ2YAkBS5ja7QLcZ9Z/uY7bEjPUatf8RomoXM8/1sMj1IJaE5UzQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-layout-effect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toggle-group/node_modules/@radix-ui/react-roving-focus": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-roving-focus/-/react-roving-focus-1.0.4.tgz", + "integrity": "sha512-2mUg5Mgcu001VkGy+FfzZyzbmuUWzgWkj3rvv4yu+mLw03+mTzbxZHvfcGyFp2b8EkQeMkpRQ5FiA2Vr2O6TeQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-collection": "1.0.3", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-direction": "1.0.1", + "@radix-ui/react-id": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-controllable-state": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toolbar": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-toolbar/-/react-toolbar-1.0.4.tgz", + "integrity": "sha512-tBgmM/O7a07xbaEkYJWYTXkIdU/1pW4/KZORR43toC/4XWyBCURK0ei9kMUdp+gTPPKBgYLxXmRSH1EVcIDp8Q==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-direction": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-roving-focus": "1.0.4", + "@radix-ui/react-separator": "1.0.3", + "@radix-ui/react-toggle-group": "1.0.4" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toolbar/node_modules/@radix-ui/react-collection": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-collection/-/react-collection-1.0.3.tgz", + "integrity": "sha512-3SzW+0PW7yBBoQlT8wNcGtaxaD0XSu0uLUFgrtHY08Acx05TaHaOmVLR73c0j/cqpDy53KBMO7s0dx2wmOIDIA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-slot": "1.0.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toolbar/node_modules/@radix-ui/react-direction": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-direction/-/react-direction-1.0.1.tgz", + "integrity": "sha512-RXcvnXgyvYvBEOhCBuddKecVkoMiI10Jcm5cTI7abJRAHYfFxeu+FBQs/DvdxSYucxR5mna0dNsL6QFlds5TMA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toolbar/node_modules/@radix-ui/react-id": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.0.1.tgz", + "integrity": "sha512-tI7sT/kqYp8p96yGWY1OAnLHrqDgzHefRBKQ2YAkBS5ja7QLcZ9Z/uY7bEjPUatf8RomoXM8/1sMj1IJaE5UzQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-layout-effect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toolbar/node_modules/@radix-ui/react-roving-focus": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-roving-focus/-/react-roving-focus-1.0.4.tgz", + "integrity": "sha512-2mUg5Mgcu001VkGy+FfzZyzbmuUWzgWkj3rvv4yu+mLw03+mTzbxZHvfcGyFp2b8EkQeMkpRQ5FiA2Vr2O6TeQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/primitive": "1.0.1", + "@radix-ui/react-collection": "1.0.3", + "@radix-ui/react-compose-refs": "1.0.1", + "@radix-ui/react-context": "1.0.1", + "@radix-ui/react-direction": "1.0.1", + "@radix-ui/react-id": "1.0.1", + "@radix-ui/react-primitive": "1.0.3", + "@radix-ui/react-use-callback-ref": "1.0.1", + "@radix-ui/react-use-controllable-state": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tooltip": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/@radix-ui/react-tooltip/-/react-tooltip-1.2.8.tgz", + "integrity": "sha512-tY7sVt1yL9ozIxvmbtN5qtmH2krXcBCfjEiCgKGLqunJHvgvZG2Pcl2oQ3kbcZARb1BGEHdkLzcYGO8ynVlieg==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.1.3", + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-context": "1.1.2", + "@radix-ui/react-dismissable-layer": "1.1.11", + "@radix-ui/react-id": "1.1.1", + "@radix-ui/react-popper": "1.2.8", + "@radix-ui/react-portal": "1.1.9", + "@radix-ui/react-presence": "1.1.5", + "@radix-ui/react-primitive": "2.1.3", + "@radix-ui/react-slot": "1.2.3", + "@radix-ui/react-use-controllable-state": "1.2.2", + "@radix-ui/react-visually-hidden": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tooltip/node_modules/@radix-ui/primitive": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.3.tgz", + "integrity": "sha512-JTF99U/6XIjCBo0wqkU5sK10glYe27MRRsfwoiq5zzOEZLHU3A3KCMa5X/azekYRCJ0HlwI0crAXS/5dEHTzDg==", + "license": "MIT" + }, + "node_modules/@radix-ui/react-tooltip/node_modules/@radix-ui/react-compose-refs": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz", + "integrity": "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tooltip/node_modules/@radix-ui/react-context": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.1.2.tgz", + "integrity": "sha512-jCi/QKUM2r1Ju5a3J64TH2A5SpKAgh0LpknyqdQ4m6DCV0xJ2HG1xARRwNGPQfi1SLdLWZ1OJz6F4OMBBNiGJA==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tooltip/node_modules/@radix-ui/react-dismissable-layer": { + "version": "1.1.11", + "resolved": "https://registry.npmjs.org/@radix-ui/react-dismissable-layer/-/react-dismissable-layer-1.1.11.tgz", + "integrity": "sha512-Nqcp+t5cTB8BinFkZgXiMJniQH0PsUt2k51FUhbdfeKvc4ACcG2uQniY/8+h1Yv6Kza4Q7lD7PQV0z0oicE0Mg==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.1.3", + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-primitive": "2.1.3", + "@radix-ui/react-use-callback-ref": "1.1.1", + "@radix-ui/react-use-escape-keydown": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tooltip/node_modules/@radix-ui/react-popper": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/@radix-ui/react-popper/-/react-popper-1.2.8.tgz", + "integrity": "sha512-0NJQ4LFFUuWkE7Oxf0htBKS6zLkkjBH+hM1uk7Ng705ReR8m/uelduy1DBo0PyBXPKVnBA6YBlU94MBGXrSBCw==", + "license": "MIT", + "dependencies": { + "@floating-ui/react-dom": "^2.0.0", + "@radix-ui/react-arrow": "1.1.7", + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-context": "1.1.2", + "@radix-ui/react-primitive": "2.1.3", + "@radix-ui/react-use-callback-ref": "1.1.1", + "@radix-ui/react-use-layout-effect": "1.1.1", + "@radix-ui/react-use-rect": "1.1.1", + "@radix-ui/react-use-size": "1.1.1", + "@radix-ui/rect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tooltip/node_modules/@radix-ui/react-presence": { + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/@radix-ui/react-presence/-/react-presence-1.1.5.tgz", + "integrity": "sha512-/jfEwNDdQVBCNvjkGit4h6pMOzq8bHkopq458dPt2lMjx+eBQUohZNG9A7DtO/O5ukSbxuaNGXMjHicgwy6rQQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2", + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tooltip/node_modules/@radix-ui/react-primitive": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz", + "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-slot": "1.2.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tooltip/node_modules/@radix-ui/react-slot": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz", + "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.2" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tooltip/node_modules/@radix-ui/react-use-callback-ref": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.1.1.tgz", + "integrity": "sha512-FkBMwD+qbGQeMu1cOHnuGB6x4yzPjho8ap5WtbEJ26umhgqVXbhekKUQO+hZEL1vU92a3wHwdp0HAcqAUF5iDg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tooltip/node_modules/@radix-ui/react-use-controllable-state": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-controllable-state/-/react-use-controllable-state-1.2.2.tgz", + "integrity": "sha512-BjasUjixPFdS+NKkypcyyN5Pmg83Olst0+c6vGov0diwTEo6mgdqVR6hxcEgFuh4QrAs7Rc+9KuGJ9TVCj0Zzg==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-effect-event": "0.0.2", + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tooltip/node_modules/@radix-ui/react-use-layout-effect": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.1.tgz", + "integrity": "sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tooltip/node_modules/@radix-ui/react-use-size": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-size/-/react-use-size-1.1.1.tgz", + "integrity": "sha512-ewrXRDTAqAXlkl6t/fkXWNAhFX9I+CkKlw6zjEwk86RSPKwZr3xpBRso655aqYafwtnbpHLj6toFzmd6xdVptQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tooltip/node_modules/@radix-ui/react-visually-hidden": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-visually-hidden/-/react-visually-hidden-1.2.3.tgz", + "integrity": "sha512-pzJq12tEaaIhqjbzpCuv/OypJY/BPavOofm+dbab+MHLajy277+1lLm6JFcGgF5eskJ6mquGirhXY2GD/8u8Ug==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-primitive": "2.1.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-callback-ref": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.0.1.tgz", + "integrity": "sha512-D94LjX4Sp0xJFVaoQOd3OO9k7tpBYNOXdVhkltUbGv2Qb9OXdrg/CpsjlZv7ia14Sylv398LswWBVVu5nqKzAQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-controllable-state": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-controllable-state/-/react-use-controllable-state-1.0.1.tgz", + "integrity": "sha512-Svl5GY5FQeN758fWKrjM6Qb7asvXeiZltlT4U2gVfl8Gx5UAv2sMR0LWo8yhsIZh2oQ0eFdZ59aoOOMV7b47VA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-callback-ref": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-effect-event": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-effect-event/-/react-use-effect-event-0.0.2.tgz", + "integrity": "sha512-Qp8WbZOBe+blgpuUT+lw2xheLP8q0oatc9UpmiemEICxGvFLYmHm9QowVZGHtJlGbS6A6yJ3iViad/2cVjnOiA==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-layout-effect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-effect-event/node_modules/@radix-ui/react-use-layout-effect": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.1.tgz", + "integrity": "sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-escape-keydown": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-escape-keydown/-/react-use-escape-keydown-1.1.1.tgz", + "integrity": "sha512-Il0+boE7w/XebUHyBjroE+DbByORGR9KKmITzbR7MyQ4akpORYP/ZmbhAr0DG7RmmBqoOnZdy2QlvajJ2QA59g==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-callback-ref": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-escape-keydown/node_modules/@radix-ui/react-use-callback-ref": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.1.1.tgz", + "integrity": "sha512-FkBMwD+qbGQeMu1cOHnuGB6x4yzPjho8ap5WtbEJ26umhgqVXbhekKUQO+hZEL1vU92a3wHwdp0HAcqAUF5iDg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-layout-effect": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.0.1.tgz", + "integrity": "sha512-v/5RegiJWYdoCvMnITBkNNx6bCj20fiaJnWtRkU18yITptraXjffz5Qbn05uOiQnOvi+dbkznkoaMltz1GnszQ==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-previous": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-previous/-/react-use-previous-1.0.1.tgz", + "integrity": "sha512-cV5La9DPwiQ7S0gf/0qiD6YgNqM5Fk97Kdrlc5yBcrF3jyEZQwm7vYFqMo4IfeHgJXsRaMvLABFtd0OVEmZhDw==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-rect": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-rect/-/react-use-rect-1.1.1.tgz", + "integrity": "sha512-QTYuDesS0VtuHNNvMh+CjlKJ4LJickCMUAqjlE3+j8w+RlRpwyX3apEQKGFzbZGdo7XNG1tXa+bQqIE7HIXT2w==", + "license": "MIT", + "dependencies": { + "@radix-ui/rect": "1.1.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-size": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-size/-/react-use-size-1.0.1.tgz", + "integrity": "sha512-ibay+VqrgcaI6veAojjofPATwledXiSmX+C0KrBk/xgpX9rBzPV3OsfwlhQdUOFbh+LKQorLYT+xTXW9V8yd0g==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-use-layout-effect": "1.0.1" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-visually-hidden": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-visually-hidden/-/react-visually-hidden-1.0.3.tgz", + "integrity": "sha512-D4w41yN5YRKtu464TLnByKzMDG/JlMPHtfZgQAu9v6mNakUqGUI9vUrfQKz8NK41VMm/xbZbh76NUTVtIYqOMA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.13.10", + "@radix-ui/react-primitive": "1.0.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/rect": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@radix-ui/rect/-/rect-1.1.1.tgz", + "integrity": "sha512-HPwpGIzkl28mWyZqG52jiqDJ12waP11Pa1lGoiyUkIEuMLBP0oeK/C89esbXrxsky5we7dfd8U58nm0SgAWpVw==", + "license": "MIT" + }, + "node_modules/@react-native-community/cli": { + "version": "11.3.6", + "resolved": "https://registry.npmjs.org/@react-native-community/cli/-/cli-11.3.6.tgz", + "integrity": "sha512-bdwOIYTBVQ9VK34dsf6t3u6vOUU5lfdhKaAxiAVArjsr7Je88Bgs4sAbsOYsNK3tkE8G77U6wLpekknXcanlww==", + "license": "MIT", + "peer": true, + "dependencies": { + "@react-native-community/cli-clean": "11.3.6", + "@react-native-community/cli-config": "11.3.6", + "@react-native-community/cli-debugger-ui": "11.3.6", + "@react-native-community/cli-doctor": "11.3.6", + "@react-native-community/cli-hermes": "11.3.6", + "@react-native-community/cli-plugin-metro": "11.3.6", + "@react-native-community/cli-server-api": "11.3.6", + "@react-native-community/cli-tools": "11.3.6", + "@react-native-community/cli-types": "11.3.6", + "chalk": "^4.1.2", + "commander": "^9.4.1", + "execa": "^5.0.0", + "find-up": "^4.1.0", + "fs-extra": "^8.1.0", + "graceful-fs": "^4.1.3", + "prompts": "^2.4.0", + "semver": "^7.5.2" + }, + "bin": { + "react-native": "build/bin.js" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/@react-native-community/cli-clean": { + "version": "11.3.6", + "resolved": "https://registry.npmjs.org/@react-native-community/cli-clean/-/cli-clean-11.3.6.tgz", + "integrity": "sha512-jOOaeG5ebSXTHweq1NznVJVAFKtTFWL4lWgUXl845bCGX7t1lL8xQNWHKwT8Oh1pGR2CI3cKmRjY4hBg+pEI9g==", + "license": "MIT", + "peer": true, + "dependencies": { + "@react-native-community/cli-tools": "11.3.6", + "chalk": "^4.1.2", + "execa": "^5.0.0", + "prompts": "^2.4.0" + } + }, + "node_modules/@react-native-community/cli-config": { + "version": "11.3.6", + "resolved": "https://registry.npmjs.org/@react-native-community/cli-config/-/cli-config-11.3.6.tgz", + "integrity": "sha512-edy7fwllSFLan/6BG6/rznOBCLPrjmJAE10FzkEqNLHowi0bckiAPg1+1jlgQ2qqAxV5kuk+c9eajVfQvPLYDA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@react-native-community/cli-tools": "11.3.6", + "chalk": "^4.1.2", + "cosmiconfig": "^5.1.0", + "deepmerge": "^4.3.0", + "glob": "^7.1.3", + "joi": "^17.2.1" + } + }, + "node_modules/@react-native-community/cli-debugger-ui": { + "version": "11.3.6", + "resolved": "https://registry.npmjs.org/@react-native-community/cli-debugger-ui/-/cli-debugger-ui-11.3.6.tgz", + "integrity": "sha512-jhMOSN/iOlid9jn/A2/uf7HbC3u7+lGktpeGSLnHNw21iahFBzcpuO71ekEdlmTZ4zC/WyxBXw9j2ka33T358w==", + "license": "MIT", + "peer": true, + "dependencies": { + "serve-static": "^1.13.1" + } + }, + "node_modules/@react-native-community/cli-doctor": { + "version": "11.3.6", + "resolved": "https://registry.npmjs.org/@react-native-community/cli-doctor/-/cli-doctor-11.3.6.tgz", + "integrity": "sha512-UT/Tt6omVPi1j6JEX+CObc85eVFghSZwy4GR9JFMsO7gNg2Tvcu1RGWlUkrbmWMAMHw127LUu6TGK66Ugu1NLA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@react-native-community/cli-config": "11.3.6", + "@react-native-community/cli-platform-android": "11.3.6", + "@react-native-community/cli-platform-ios": "11.3.6", + "@react-native-community/cli-tools": "11.3.6", + "chalk": "^4.1.2", + "command-exists": "^1.2.8", + "envinfo": "^7.7.2", + "execa": "^5.0.0", + "hermes-profile-transformer": "^0.0.6", + "ip": "^1.1.5", + "node-stream-zip": "^1.9.1", + "ora": "^5.4.1", + "prompts": "^2.4.0", + "semver": "^7.5.2", + "strip-ansi": "^5.2.0", + "sudo-prompt": "^9.0.0", + "wcwidth": "^1.0.1", + "yaml": "^2.2.1" + } + }, + "node_modules/@react-native-community/cli-doctor/node_modules/ansi-regex": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-4.1.1.tgz", + "integrity": "sha512-ILlv4k/3f6vfQ4OoP2AGvirOktlQ98ZEL1k9FaQjxa3L1abBgbuTDAdPOpvbGncC0BTVQrl+OM8xZGK6tWXt7g==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/@react-native-community/cli-doctor/node_modules/strip-ansi": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-5.2.0.tgz", + "integrity": "sha512-DuRs1gKbBqsMKIZlrffwlug8MHkcnpjs5VPmL1PAh+mA30U0DTotfDZ0d2UUsXpPmPmMMJ6W773MaA3J+lbiWA==", + "license": "MIT", + "peer": true, + "dependencies": { + "ansi-regex": "^4.1.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/@react-native-community/cli-hermes": { + "version": "11.3.6", + "resolved": "https://registry.npmjs.org/@react-native-community/cli-hermes/-/cli-hermes-11.3.6.tgz", + "integrity": "sha512-O55YAYGZ3XynpUdePPVvNuUPGPY0IJdctLAOHme73OvS80gNwfntHDXfmY70TGHWIfkK2zBhA0B+2v8s5aTyTA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@react-native-community/cli-platform-android": "11.3.6", + "@react-native-community/cli-tools": "11.3.6", + "chalk": "^4.1.2", + "hermes-profile-transformer": "^0.0.6", + "ip": "^1.1.5" + } + }, + "node_modules/@react-native-community/cli-platform-android": { + "version": "11.3.6", + "resolved": "https://registry.npmjs.org/@react-native-community/cli-platform-android/-/cli-platform-android-11.3.6.tgz", + "integrity": "sha512-ZARrpLv5tn3rmhZc//IuDM1LSAdYnjUmjrp58RynlvjLDI4ZEjBAGCQmgysRgXAsK7ekMrfkZgemUczfn9td2A==", + "license": "MIT", + "peer": true, + "dependencies": { + "@react-native-community/cli-tools": "11.3.6", + "chalk": "^4.1.2", + "execa": "^5.0.0", + "glob": "^7.1.3", + "logkitty": "^0.7.1" + } + }, + "node_modules/@react-native-community/cli-platform-ios": { + "version": "11.3.6", + "resolved": "https://registry.npmjs.org/@react-native-community/cli-platform-ios/-/cli-platform-ios-11.3.6.tgz", + "integrity": "sha512-tZ9VbXWiRW+F+fbZzpLMZlj93g3Q96HpuMsS6DRhrTiG+vMQ3o6oPWSEEmMGOvJSYU7+y68Dc9ms2liC7VD6cw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@react-native-community/cli-tools": "11.3.6", + "chalk": "^4.1.2", + "execa": "^5.0.0", + "fast-xml-parser": "^4.0.12", + "glob": "^7.1.3", + "ora": "^5.4.1" + } + }, + "node_modules/@react-native-community/cli-plugin-metro": { + "version": "11.3.6", + "resolved": "https://registry.npmjs.org/@react-native-community/cli-plugin-metro/-/cli-plugin-metro-11.3.6.tgz", + "integrity": "sha512-D97racrPX3069ibyabJNKw9aJpVcaZrkYiEzsEnx50uauQtPDoQ1ELb/5c6CtMhAEGKoZ0B5MS23BbsSZcLs2g==", + "license": "MIT", + "peer": true, + "dependencies": { + "@react-native-community/cli-server-api": "11.3.6", + "@react-native-community/cli-tools": "11.3.6", + "chalk": "^4.1.2", + "execa": "^5.0.0", + "metro": "0.76.7", + "metro-config": "0.76.7", + "metro-core": "0.76.7", + "metro-react-native-babel-transformer": "0.76.7", + "metro-resolver": "0.76.7", + "metro-runtime": "0.76.7", + "readline": "^1.3.0" + } + }, + "node_modules/@react-native-community/cli-plugin-metro/node_modules/metro-runtime": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-runtime/-/metro-runtime-0.76.7.tgz", + "integrity": "sha512-MuWHubQHymUWBpZLwuKZQgA/qbb35WnDAKPo83rk7JRLIFPvzXSvFaC18voPuzJBt1V98lKQIonh6MiC9gd8Ug==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/runtime": "^7.0.0", + "react-refresh": "^0.4.0" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/@react-native-community/cli-server-api": { + "version": "11.3.6", + "resolved": "https://registry.npmjs.org/@react-native-community/cli-server-api/-/cli-server-api-11.3.6.tgz", + "integrity": "sha512-8GUKodPnURGtJ9JKg8yOHIRtWepPciI3ssXVw5jik7+dZ43yN8P5BqCoDaq8e1H1yRer27iiOfT7XVnwk8Dueg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@react-native-community/cli-debugger-ui": "11.3.6", + "@react-native-community/cli-tools": "11.3.6", + "compression": "^1.7.1", + "connect": "^3.6.5", + "errorhandler": "^1.5.1", + "nocache": "^3.0.1", + "pretty-format": "^26.6.2", + "serve-static": "^1.13.1", + "ws": "^7.5.1" + } + }, + "node_modules/@react-native-community/cli-server-api/node_modules/@jest/types": { + "version": "26.6.2", + "resolved": "https://registry.npmjs.org/@jest/types/-/types-26.6.2.tgz", + "integrity": "sha512-fC6QCp7Sc5sX6g8Tvbmj4XUTbyrik0akgRy03yjXbQaBWWNWGE7SGtJk98m0N8nzegD/7SggrUlivxo5ax4KWQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@types/istanbul-lib-coverage": "^2.0.0", + "@types/istanbul-reports": "^3.0.0", + "@types/node": "*", + "@types/yargs": "^15.0.0", + "chalk": "^4.0.0" + }, + "engines": { + "node": ">= 10.14.2" + } + }, + "node_modules/@react-native-community/cli-server-api/node_modules/@types/yargs": { + "version": "15.0.15", + "resolved": "https://registry.npmjs.org/@types/yargs/-/yargs-15.0.15.tgz", + "integrity": "sha512-IziEYMU9XoVj8hWg7k+UJrXALkGFjWJhn5QFEv9q4p+v40oZhSuC135M38st8XPjICL7Ey4TV64ferBGUoJhBg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@types/yargs-parser": "*" + } + }, + "node_modules/@react-native-community/cli-server-api/node_modules/pretty-format": { + "version": "26.6.2", + "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-26.6.2.tgz", + "integrity": "sha512-7AeGuCYNGmycyQbCqd/3PWH4eOoX/OiCa0uphp57NVTeAGdJGaAliecxwBDHYQCIvrW7aDBZCYeNTP/WX69mkg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@jest/types": "^26.6.2", + "ansi-regex": "^5.0.0", + "ansi-styles": "^4.0.0", + "react-is": "^17.0.1" + }, + "engines": { + "node": ">= 10" + } + }, + "node_modules/@react-native-community/cli-server-api/node_modules/react-is": { + "version": "17.0.2", + "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz", + "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==", + "license": "MIT", + "peer": true + }, + "node_modules/@react-native-community/cli-server-api/node_modules/ws": { + "version": "7.5.9", + "resolved": "https://registry.npmjs.org/ws/-/ws-7.5.9.tgz", + "integrity": "sha512-F+P9Jil7UiSKSkppIiD94dN07AwvFixvLIj1Og1Rl9GGMuNipJnV9JzjD6XuqmAeiswGvUmNLjr5cFuXwNS77Q==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=8.3.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": "^5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + }, + "node_modules/@react-native-community/cli-tools": { + "version": "11.3.6", + "resolved": "https://registry.npmjs.org/@react-native-community/cli-tools/-/cli-tools-11.3.6.tgz", + "integrity": "sha512-JpmUTcDwAGiTzLsfMlIAYpCMSJ9w2Qlf7PU7mZIRyEu61UzEawyw83DkqfbzDPBuRwRnaeN44JX2CP/yTO3ThQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "appdirsjs": "^1.2.4", + "chalk": "^4.1.2", + "find-up": "^5.0.0", + "mime": "^2.4.1", + "node-fetch": "^2.6.0", + "open": "^6.2.0", + "ora": "^5.4.1", + "semver": "^7.5.2", + "shell-quote": "^1.7.3" + } + }, + "node_modules/@react-native-community/cli-types": { + "version": "11.3.6", + "resolved": "https://registry.npmjs.org/@react-native-community/cli-types/-/cli-types-11.3.6.tgz", + "integrity": "sha512-6DxjrMKx5x68N/tCJYVYRKAtlRHbtUVBZrnAvkxbRWFD9v4vhNgsPM0RQm8i2vRugeksnao5mbnRGpS6c0awCw==", + "license": "MIT", + "peer": true, + "dependencies": { + "joi": "^17.2.1" + } + }, + "node_modules/@react-native-community/cli/node_modules/find-up": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-4.1.0.tgz", + "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==", + "license": "MIT", + "peer": true, + "dependencies": { + "locate-path": "^5.0.0", + "path-exists": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/@react-native-community/cli/node_modules/locate-path": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz", + "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==", + "license": "MIT", + "peer": true, + "dependencies": { + "p-locate": "^4.1.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/@react-native-community/cli/node_modules/p-limit": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", + "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", + "license": "MIT", + "peer": true, + "dependencies": { + "p-try": "^2.0.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/@react-native-community/cli/node_modules/p-locate": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-4.1.0.tgz", + "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==", + "license": "MIT", + "peer": true, + "dependencies": { + "p-limit": "^2.2.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/@react-native/assets-registry": { + "version": "0.72.0", + "resolved": "https://registry.npmjs.org/@react-native/assets-registry/-/assets-registry-0.72.0.tgz", + "integrity": "sha512-Im93xRJuHHxb1wniGhBMsxLwcfzdYreSZVQGDoMJgkd6+Iky61LInGEHnQCTN0fKNYF1Dvcofb4uMmE1RQHXHQ==", + "license": "MIT", + "peer": true + }, + "node_modules/@react-native/codegen": { + "version": "0.72.7", + "resolved": "https://registry.npmjs.org/@react-native/codegen/-/codegen-0.72.7.tgz", + "integrity": "sha512-O7xNcGeXGbY+VoqBGNlZ3O05gxfATlwE1Q1qQf5E38dK+tXn5BY4u0jaQ9DPjfE8pBba8g/BYI1N44lynidMtg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/parser": "^7.20.0", + "flow-parser": "^0.206.0", + "jscodeshift": "^0.14.0", + "nullthrows": "^1.1.1" + }, + "peerDependencies": { + "@babel/preset-env": "^7.1.6" + } + }, + "node_modules/@react-native/gradle-plugin": { + "version": "0.72.11", + "resolved": "https://registry.npmjs.org/@react-native/gradle-plugin/-/gradle-plugin-0.72.11.tgz", + "integrity": "sha512-P9iRnxiR2w7EHcZ0mJ+fmbPzMby77ZzV6y9sJI3lVLJzF7TLSdbwcQyD3lwMsiL+q5lKUHoZJS4sYmih+P2HXw==", + "license": "MIT", + "peer": true + }, + "node_modules/@react-native/js-polyfills": { + "version": "0.72.1", + "resolved": "https://registry.npmjs.org/@react-native/js-polyfills/-/js-polyfills-0.72.1.tgz", + "integrity": "sha512-cRPZh2rBswFnGt5X5EUEPs0r+pAsXxYsifv/fgy9ZLQokuT52bPH+9xjDR+7TafRua5CttGW83wP4TntRcWNDA==", + "license": "MIT", + "peer": true + }, + "node_modules/@react-native/normalize-colors": { + "version": "0.72.0", + "resolved": "https://registry.npmjs.org/@react-native/normalize-colors/-/normalize-colors-0.72.0.tgz", + "integrity": "sha512-285lfdqSXaqKuBbbtP9qL2tDrfxdOFtIMvkKadtleRQkdOxx+uzGvFr82KHmc/sSiMtfXGp7JnFYWVh4sFl7Yw==", + "license": "MIT", + "peer": true + }, + "node_modules/@react-native/virtualized-lists": { + "version": "0.72.8", + "resolved": "https://registry.npmjs.org/@react-native/virtualized-lists/-/virtualized-lists-0.72.8.tgz", + "integrity": "sha512-J3Q4Bkuo99k7mu+jPS9gSUSgq+lLRSI/+ahXNwV92XgJ/8UgOTxu2LPwhJnBk/sQKxq7E8WkZBnBiozukQMqrw==", + "license": "MIT", + "peer": true, + "dependencies": { + "invariant": "^2.2.4", + "nullthrows": "^1.1.1" + }, + "peerDependencies": { + "react-native": "*" + } + }, + "node_modules/@react-spring/animated": { + "version": "9.7.3", + "resolved": "https://registry.npmjs.org/@react-spring/animated/-/animated-9.7.3.tgz", + "integrity": "sha512-5CWeNJt9pNgyvuSzQH+uy2pvTg8Y4/OisoscZIR8/ZNLIOI+CatFBhGZpDGTF/OzdNFsAoGk3wiUYTwoJ0YIvw==", + "license": "MIT", + "dependencies": { + "@react-spring/shared": "~9.7.3", + "@react-spring/types": "~9.7.3" + }, + "peerDependencies": { + "react": "^16.8.0 || ^17.0.0 || ^18.0.0" + } + }, + "node_modules/@react-spring/core": { + "version": "9.7.3", + "resolved": "https://registry.npmjs.org/@react-spring/core/-/core-9.7.3.tgz", + "integrity": "sha512-IqFdPVf3ZOC1Cx7+M0cXf4odNLxDC+n7IN3MDcVCTIOSBfqEcBebSv+vlY5AhM0zw05PDbjKrNmBpzv/AqpjnQ==", + "license": "MIT", + "dependencies": { + "@react-spring/animated": "~9.7.3", + "@react-spring/shared": "~9.7.3", + "@react-spring/types": "~9.7.3" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/react-spring/donate" + }, + "peerDependencies": { + "react": "^16.8.0 || ^17.0.0 || ^18.0.0" + } + }, + "node_modules/@react-spring/konva": { + "version": "9.7.3", + "resolved": "https://registry.npmjs.org/@react-spring/konva/-/konva-9.7.3.tgz", + "integrity": "sha512-R9sY6SiPGYqz1383P5qppg5z57YfChVknOC1UxxaGxpw+WiZa8fZ4zmZobslrw+os3/+HAXZv8O+EvU/nQpf7g==", + "license": "MIT", + "dependencies": { + "@react-spring/animated": "~9.7.3", + "@react-spring/core": "~9.7.3", + "@react-spring/shared": "~9.7.3", + "@react-spring/types": "~9.7.3" + }, + "peerDependencies": { + "konva": ">=2.6", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0", + "react-konva": "^16.8.0 || ^16.8.7-0 || ^16.9.0-0 || ^16.10.1-0 || ^16.12.0-0 || ^16.13.0-0 || ^17.0.0-0 || ^17.0.1-0 || ^17.0.2-0 || ^18.0.0-0" + } + }, + "node_modules/@react-spring/native": { + "version": "9.7.3", + "resolved": "https://registry.npmjs.org/@react-spring/native/-/native-9.7.3.tgz", + "integrity": "sha512-4mpxX3FuEBCUT6ae2fjhxcJW6bhr2FBwFf274eXB7n+U30Gdg8Wo2qYwcUnmiAA0S3dvP8vLTazx3+CYWFShnA==", + "license": "MIT", + "dependencies": { + "@react-spring/animated": "~9.7.3", + "@react-spring/core": "~9.7.3", + "@react-spring/shared": "~9.7.3", + "@react-spring/types": "~9.7.3" + }, + "peerDependencies": { + "react": "^16.8.0 || >=17.0.0 || >=18.0.0", + "react-native": ">=0.58" + } + }, + "node_modules/@react-spring/shared": { + "version": "9.7.3", + "resolved": "https://registry.npmjs.org/@react-spring/shared/-/shared-9.7.3.tgz", + "integrity": "sha512-NEopD+9S5xYyQ0pGtioacLhL2luflh6HACSSDUZOwLHoxA5eku1UPuqcJqjwSD6luKjjLfiLOspxo43FUHKKSA==", + "license": "MIT", + "dependencies": { + "@react-spring/types": "~9.7.3" + }, + "peerDependencies": { + "react": "^16.8.0 || ^17.0.0 || ^18.0.0" + } + }, + "node_modules/@react-spring/three": { + "version": "9.7.3", + "resolved": "https://registry.npmjs.org/@react-spring/three/-/three-9.7.3.tgz", + "integrity": "sha512-Q1p512CqUlmMK8UMBF/Rj79qndhOWq4XUTayxMP9S892jiXzWQuj+xC3Xvm59DP/D4JXusXpxxqfgoH+hmOktA==", + "license": "MIT", + "dependencies": { + "@react-spring/animated": "~9.7.3", + "@react-spring/core": "~9.7.3", + "@react-spring/shared": "~9.7.3", + "@react-spring/types": "~9.7.3" + }, + "peerDependencies": { + "@react-three/fiber": ">=6.0", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0", + "three": ">=0.126" + } + }, + "node_modules/@react-spring/types": { + "version": "9.7.3", + "resolved": "https://registry.npmjs.org/@react-spring/types/-/types-9.7.3.tgz", + "integrity": "sha512-Kpx/fQ/ZFX31OtlqVEFfgaD1ACzul4NksrvIgYfIFq9JpDHFwQkMVZ10tbo0FU/grje4rcL4EIrjekl3kYwgWw==", + "license": "MIT" + }, + "node_modules/@react-spring/web": { + "version": "9.7.3", + "resolved": "https://registry.npmjs.org/@react-spring/web/-/web-9.7.3.tgz", + "integrity": "sha512-BXt6BpS9aJL/QdVqEIX9YoUy8CE6TJrU0mNCqSoxdXlIeNcEBWOfIyE6B14ENNsyQKS3wOWkiJfco0tCr/9tUg==", + "license": "MIT", + "dependencies": { + "@react-spring/animated": "~9.7.3", + "@react-spring/core": "~9.7.3", + "@react-spring/shared": "~9.7.3", + "@react-spring/types": "~9.7.3" + }, + "peerDependencies": { + "react": "^16.8.0 || ^17.0.0 || ^18.0.0", + "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0" + } + }, + "node_modules/@react-spring/zdog": { + "version": "9.7.3", + "resolved": "https://registry.npmjs.org/@react-spring/zdog/-/zdog-9.7.3.tgz", + "integrity": "sha512-L+yK/1PvNi9n8cldiJ309k4LdxcPkeWE0W18l1zrP1IBIyd5NB5EPA8DMsGr9gtNnnIujtEzZk+4JIOjT8u/tw==", + "license": "MIT", + "dependencies": { + "@react-spring/animated": "~9.7.3", + "@react-spring/core": "~9.7.3", + "@react-spring/shared": "~9.7.3", + "@react-spring/types": "~9.7.3" + }, + "peerDependencies": { + "react": "^16.8.0 || ^17.0.0 || ^18.0.0", + "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0", + "react-zdog": ">=1.0", + "zdog": ">=1.0" + } + }, + "node_modules/@react-three/fiber": { + "version": "8.14.1", + "resolved": "https://registry.npmjs.org/@react-three/fiber/-/fiber-8.14.1.tgz", + "integrity": "sha512-Ky/FiCyJiyaI8bd+vckzgkHgKDSQDOcSSUVFOHCuCO9XOLb7Ebs6lof2hPpFa1HkaeE5ZIbTWIprvN0QqdPF0w==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/runtime": "^7.17.8", + "@types/react-reconciler": "^0.26.7", + "base64-js": "^1.5.1", + "its-fine": "^1.0.6", + "react-reconciler": "^0.27.0", + "react-use-measure": "^2.1.1", + "scheduler": "^0.21.0", + "suspend-react": "^0.1.3", + "zustand": "^3.7.1" + }, + "peerDependencies": { + "expo": ">=43.0", + "expo-asset": ">=8.4", + "expo-file-system": ">=11.0", + "expo-gl": ">=11.0", + "react": ">=18.0", + "react-dom": ">=18.0", + "react-native": ">=0.64", + "three": ">=0.133" + }, + "peerDependenciesMeta": { + "expo": { + "optional": true + }, + "expo-asset": { + "optional": true + }, + "expo-file-system": { + "optional": true + }, + "expo-gl": { + "optional": true + }, + "react-dom": { + "optional": true + }, + "react-native": { + "optional": true + } + } + }, + "node_modules/@react-three/fiber/node_modules/scheduler": { + "version": "0.21.0", + "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.21.0.tgz", + "integrity": "sha512-1r87x5fz9MXqswA2ERLo0EbOAU74DpIUO090gIasYTqlVoJeMcl+Z1Rg7WHz+qtPujhS/hGIt9kxZOYBV3faRQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "loose-envify": "^1.1.0" + } + }, + "node_modules/@remix-run/router": { + "version": "1.8.0", + "resolved": "https://registry.npmjs.org/@remix-run/router/-/router-1.8.0.tgz", + "integrity": "sha512-mrfKqIHnSZRyIzBcanNJmVQELTnX+qagEDlcKO90RgRBVOZGSGvZKeDihTRfWcqoDn5N/NkUcwWTccnpN18Tfg==", + "license": "MIT", + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@rushstack/eslint-patch": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/@rushstack/eslint-patch/-/eslint-patch-1.3.3.tgz", + "integrity": "sha512-0xd7qez0AQ+MbHatZTlI1gu5vkG8r7MYRUJAHPAHJBmGLs16zpkrpAVLvjQKQOqaXPDUBwOiJzNc00znHSCVBw==", + "dev": true, + "license": "MIT" + }, + "node_modules/@sideway/address": { + "version": "4.1.4", + "resolved": "https://registry.npmjs.org/@sideway/address/-/address-4.1.4.tgz", + "integrity": "sha512-7vwq+rOHVWjyXxVlR76Agnvhy8I9rpzjosTESvmhNeXOXdZZB15Fl+TI9x1SiHZH5Jv2wTGduSxFDIaq0m3DUw==", + "license": "BSD-3-Clause", + "peer": true, + "dependencies": { + "@hapi/hoek": "^9.0.0" + } + }, + "node_modules/@sideway/formula": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/@sideway/formula/-/formula-3.0.1.tgz", + "integrity": "sha512-/poHZJJVjx3L+zVD6g9KgHfYnb443oi7wLu/XKojDviHy6HOEOA6z1Trk5aR1dGcmPenJEgb2sK2I80LeS3MIg==", + "license": "BSD-3-Clause", + "peer": true + }, + "node_modules/@sideway/pinpoint": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@sideway/pinpoint/-/pinpoint-2.0.0.tgz", + "integrity": "sha512-RNiOoTPkptFtSVzQevY/yWtZwf/RxyVnPy/OcA9HBM3MlGDnBEYL5B41H0MTn0Uec8Hi+2qUtTfG2WWZBmMejQ==", + "license": "BSD-3-Clause", + "peer": true + }, + "node_modules/@sinclair/typebox": { + "version": "0.27.8", + "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.27.8.tgz", + "integrity": "sha512-+Fj43pSMwJs4KRrH/938Uf+uAELIgVBmQzg/q1YG10djyfA3TnrU8N8XzqCh/okZdszqBQTZf96idMfE5lnwTA==", + "license": "MIT", + "peer": true + }, + "node_modules/@sinonjs/commons": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/@sinonjs/commons/-/commons-3.0.0.tgz", + "integrity": "sha512-jXBtWAF4vmdNmZgD5FoKsVLv3rPgDnLgPbU84LIJ3otV44vJlDRokVng5v8NFJdCf/da9legHcKaRuZs4L7faA==", + "license": "BSD-3-Clause", + "peer": true, + "dependencies": { + "type-detect": "4.0.8" + } + }, + "node_modules/@sinonjs/fake-timers": { + "version": "10.3.0", + "resolved": "https://registry.npmjs.org/@sinonjs/fake-timers/-/fake-timers-10.3.0.tgz", + "integrity": "sha512-V4BG07kuYSUkTCSBHG8G8TNhM+F19jXFWnQtzj+we8DrkpSBCee9Z3Ms8yiGer/dlmhe35/Xdgyo3/0rQKg7YA==", + "license": "BSD-3-Clause", + "peer": true, + "dependencies": { + "@sinonjs/commons": "^3.0.0" + } + }, + "node_modules/@swc/helpers": { + "version": "0.5.1", + "resolved": "https://registry.npmjs.org/@swc/helpers/-/helpers-0.5.1.tgz", + "integrity": "sha512-sJ902EfIzn1Fa+qYmjdQqh8tPsoxyBz+8yBKC2HKUxyezKJFwPGOn7pv4WY6QuQW//ySQi5lJjA/ZT9sNWWNTg==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tanstack/query-core": { + "version": "4.32.6", + "resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-4.32.6.tgz", + "integrity": "sha512-YVB+mVWENQwPyv+40qO7flMgKZ0uI41Ph7qXC2Zf1ft5AIGfnXnMZyifB2ghhZ27u+5wm5mlzO4Y6lwwadzxCA==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/tannerlinsley" + } + }, + "node_modules/@tanstack/react-query": { + "version": "4.32.6", + "resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-4.32.6.tgz", + "integrity": "sha512-AITu/IKJJJXsHHeXNBy5bclu12t08usMCY0vFC2dh9SP/w6JAk5U9GwfjOIPj3p+ATADZvxQPe8UiCtMLNeQbg==", + "license": "MIT", + "dependencies": { + "@tanstack/query-core": "4.32.6", + "use-sync-external-store": "^1.2.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/tannerlinsley" + }, + "peerDependencies": { + "react": "^16.8.0 || ^17.0.0 || ^18.0.0", + "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0", + "react-native": "*" + }, + "peerDependenciesMeta": { + "react-dom": { + "optional": true + }, + "react-native": { + "optional": true + } + } + }, + "node_modules/@tanstack/react-table": { + "version": "8.9.3", + "resolved": "https://registry.npmjs.org/@tanstack/react-table/-/react-table-8.9.3.tgz", + "integrity": "sha512-Ng9rdm3JPoSCi6cVZvANsYnF+UoGVRxflMb270tVj0+LjeT/ZtZ9ckxF6oLPLcKesza6VKBqtdF9mQ+vaz24Aw==", + "license": "MIT", + "dependencies": { + "@tanstack/table-core": "8.9.3" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/tannerlinsley" + }, + "peerDependencies": { + "react": ">=16", + "react-dom": ">=16" + } + }, + "node_modules/@tanstack/react-virtual": { + "version": "3.13.18", + "resolved": "https://registry.npmjs.org/@tanstack/react-virtual/-/react-virtual-3.13.18.tgz", + "integrity": "sha512-dZkhyfahpvlaV0rIKnvQiVoWPyURppl6w4m9IwMDpuIjcJ1sD9YGWrt0wISvgU7ewACXx2Ct46WPgI6qAD4v6A==", + "license": "MIT", + "dependencies": { + "@tanstack/virtual-core": "3.13.18" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/tannerlinsley" + }, + "peerDependencies": { + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", + "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" + } + }, + "node_modules/@tanstack/table-core": { + "version": "8.9.3", + "resolved": "https://registry.npmjs.org/@tanstack/table-core/-/table-core-8.9.3.tgz", + "integrity": "sha512-NpHZBoHTfqyJk0m/s/+CSuAiwtebhYK90mDuf5eylTvgViNOujiaOaxNDxJkQQAsVvHWZftUGAx1EfO1rkKtLg==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/tannerlinsley" + } + }, + "node_modules/@tanstack/virtual-core": { + "version": "3.13.18", + "resolved": "https://registry.npmjs.org/@tanstack/virtual-core/-/virtual-core-3.13.18.tgz", + "integrity": "sha512-Mx86Hqu1k39icq2Zusq+Ey2J6dDWTjDvEv43PJtRCoEYTLyfaPnxIQ6iy7YAOK0NV/qOEmZQ/uCufrppZxTgcg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/tannerlinsley" + } + }, + "node_modules/@trpc/client": { + "version": "10.37.1", + "resolved": "https://registry.npmjs.org/@trpc/client/-/client-10.37.1.tgz", + "integrity": "sha512-OSblNfeI0Z9ERn3usgLV2x63CwwPoNOHf1FQK85cOT7F8MNaWyEHoEv7tHUwNGJwyzKXmpU+ockZ0movzX3D0g==", + "funding": [ + "https://trpc.io/sponsor" + ], + "license": "MIT", + "peerDependencies": { + "@trpc/server": "10.37.1" + } + }, + "node_modules/@trpc/next": { + "version": "10.37.1", + "resolved": "https://registry.npmjs.org/@trpc/next/-/next-10.37.1.tgz", + "integrity": "sha512-0KEgr09mBfao56lkj7ZBfVOY86d3+bDH1o0zJkDHSH60Dp/hIJ7wLCnZJIhePlZxEwknCQjVeLsTy4Pqlu8NyQ==", + "funding": [ + "https://trpc.io/sponsor" + ], + "license": "MIT", + "dependencies": { + "react-ssr-prepass": "^1.5.0" + }, + "peerDependencies": { + "@tanstack/react-query": "^4.18.0", + "@trpc/client": "10.37.1", + "@trpc/react-query": "10.37.1", + "@trpc/server": "10.37.1", + "next": "*", + "react": ">=16.8.0", + "react-dom": ">=16.8.0" + } + }, + "node_modules/@trpc/react-query": { + "version": "10.37.1", + "resolved": "https://registry.npmjs.org/@trpc/react-query/-/react-query-10.37.1.tgz", + "integrity": "sha512-TbOOPp0fZVaKfaeEyDoV8QeTHW1vgPTbfOs0uSQ4AzBXqXPu+9v1B44z8GGRJSdUxuOX9pG/6Ap5Kx8PQ3eF+Q==", + "funding": [ + "https://trpc.io/sponsor" + ], + "license": "MIT", + "peerDependencies": { + "@tanstack/react-query": "^4.18.0", + "@trpc/client": "10.37.1", + "@trpc/server": "10.37.1", + "react": ">=16.8.0", + "react-dom": ">=16.8.0" + } + }, + "node_modules/@trpc/server": { + "version": "10.37.1", + "resolved": "https://registry.npmjs.org/@trpc/server/-/server-10.37.1.tgz", + "integrity": "sha512-r3VeA319/braYMBIzj+XLgLKQ9lJSVglvPvP9HUv4kr5w6Y5grQMxMcExhTiZWltE9bnSJHKtBBzHafOo7KC8A==", + "funding": [ + "https://trpc.io/sponsor" + ], + "license": "MIT" + }, + "node_modules/@tsconfig/node10": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.11.tgz", + "integrity": "sha512-DcRjDCujK/kCk/cUe8Xz8ZSpm8mS3mNNpta+jGCA6USEDfktlNvm1+IuZ9eTcDbNk41BHwpHHeW+N1lKCz4zOw==", + "license": "MIT" + }, + "node_modules/@tsconfig/node12": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/@tsconfig/node12/-/node12-1.0.11.tgz", + "integrity": "sha512-cqefuRsh12pWyGsIoBKJA9luFu3mRxCA+ORZvA4ktLSzIuCUtWVxGIuXigEwO5/ywWFMZ2QEGKWvkZG1zDMTag==", + "license": "MIT" + }, + "node_modules/@tsconfig/node14": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@tsconfig/node14/-/node14-1.0.3.tgz", + "integrity": "sha512-ysT8mhdixWK6Hw3i1V2AeRqZ5WfXg1G43mqoYlM2nc6388Fq5jcXyr5mRsqViLx/GJYdoL0bfXD8nmF+Zn/Iow==", + "license": "MIT" + }, + "node_modules/@tsconfig/node16": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@tsconfig/node16/-/node16-1.0.4.tgz", + "integrity": "sha512-vxhUy4J8lyeyinH7Azl1pdd43GJhZH/tP2weN8TntQblOY+A0XbT8DJk1/oCPuOOyg/Ja757rG0CgHcWC8OfMA==", + "license": "MIT" + }, + "node_modules/@types/acorn": { + "version": "4.0.6", + "resolved": "https://registry.npmjs.org/@types/acorn/-/acorn-4.0.6.tgz", + "integrity": "sha512-veQTnWP+1D/xbxVrPC3zHnCZRjSrKfhbMUlEA43iMZLu7EsnTtkJklIuwrCPbOi8YkvDQAiW05VQQFvvz9oieQ==", + "license": "MIT", + "dependencies": { + "@types/estree": "*" + } + }, + "node_modules/@types/amqplib": { + "version": "0.10.6", + "resolved": "https://registry.npmjs.org/@types/amqplib/-/amqplib-0.10.6.tgz", + "integrity": "sha512-vQLVypBS1JQcfTXhl1Td1EEeLdtb+vuulOb4TrzYiLyP2aYLMAEzB3pNmEA0jBm0xIXu946Y7Xwl19Eidl32SQ==", + "license": "MIT", + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/@types/bcrypt": { + "version": "5.0.2", + "resolved": "https://registry.npmjs.org/@types/bcrypt/-/bcrypt-5.0.2.tgz", + "integrity": "sha512-6atioO8Y75fNcbmj0G7UjI9lXN2pQ/IGJ2FWT4a/btd0Lk9lQalHLKhkgKVZ3r+spnmWUKfbMi1GEe9wyHQfNQ==", + "license": "MIT", + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/@types/d3-array": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/@types/d3-array/-/d3-array-3.2.1.tgz", + "integrity": "sha512-Y2Jn2idRrLzUfAKV2LyRImR+y4oa2AntrgID95SHJxuMUrkNXmanDSed71sRNZysveJVt1hLLemQZIady0FpEg==", + "license": "MIT" + }, + "node_modules/@types/d3-color": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/@types/d3-color/-/d3-color-2.0.3.tgz", + "integrity": "sha512-+0EtEjBfKEDtH9Rk3u3kLOUXM5F+iZK+WvASPb0MhIZl8J8NUvGeZRwKCXl+P3HkYx5TdU4YtcibpqHkSR9n7w==", + "license": "MIT" + }, + "node_modules/@types/d3-delaunay": { + "version": "5.3.1", + "resolved": "https://registry.npmjs.org/@types/d3-delaunay/-/d3-delaunay-5.3.1.tgz", + "integrity": "sha512-F6itHi2DxdatHil1rJ2yEFUNhejj8+0Acd55LZ6Ggwbdoks0+DxVY2cawNj16sjCBiWvubVlh6eBMVsYRNGLew==", + "license": "MIT" + }, + "node_modules/@types/d3-ease": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/@types/d3-ease/-/d3-ease-3.0.2.tgz", + "integrity": "sha512-NcV1JjO5oDzoK26oMzbILE6HW7uVXOHLQvHshBUW4UMdZGfiY6v5BeQwh9a9tCzv+CeefZQHJt5SRgK154RtiA==", + "license": "MIT" + }, + "node_modules/@types/d3-format": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@types/d3-format/-/d3-format-1.4.2.tgz", + "integrity": "sha512-WeGCHAs7PHdZYq6lwl/+jsl+Nfc1J2W1kNcMeIMYzQsT6mtBDBgtJ/rcdjZ0k0rVIvqEZqhhuD5TK/v3P2gFHQ==", + "license": "MIT" + }, + "node_modules/@types/d3-interpolate": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/@types/d3-interpolate/-/d3-interpolate-3.0.4.tgz", + "integrity": "sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==", + "license": "MIT", + "dependencies": { + "@types/d3-color": "*" + } + }, + "node_modules/@types/d3-path": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/@types/d3-path/-/d3-path-2.0.2.tgz", + "integrity": "sha512-3YHpvDw9LzONaJzejXLOwZ3LqwwkoXb9LI2YN7Hbd6pkGo5nIlJ09ul4bQhBN4hQZJKmUpX8HkVqbzgUKY48cg==", + "license": "MIT" + }, + "node_modules/@types/d3-scale": { + "version": "3.3.2", + "resolved": "https://registry.npmjs.org/@types/d3-scale/-/d3-scale-3.3.2.tgz", + "integrity": "sha512-gGqr7x1ost9px3FvIfUMi5XA/F/yAf4UkUDtdQhpH92XCT0Oa7zkkRzY61gPVJq+DxpHn/btouw5ohWkbBsCzQ==", + "license": "MIT", + "dependencies": { + "@types/d3-time": "^2" + } + }, + "node_modules/@types/d3-scale-chromatic": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/@types/d3-scale-chromatic/-/d3-scale-chromatic-2.0.1.tgz", + "integrity": "sha512-3EuZlbPu+pvclZcb1DhlymTWT2W+lYsRKBjvkH2ojDbCWDYavifqu1vYX9WGzlPgCgcS4Alhk1+zapXbGEGylQ==", + "license": "MIT" + }, + "node_modules/@types/d3-scale/node_modules/@types/d3-time": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/@types/d3-time/-/d3-time-2.1.1.tgz", + "integrity": "sha512-9MVYlmIgmRR31C5b4FVSWtuMmBHh2mOWQYfl7XAYOa8dsnb7iEmUmRSWSFgXFtkjxO65d7hTUHQC+RhR/9IWFg==", + "license": "MIT" + }, + "node_modules/@types/d3-shape": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@types/d3-shape/-/d3-shape-2.1.3.tgz", + "integrity": "sha512-HAhCel3wP93kh4/rq+7atLdybcESZ5bRHDEZUojClyZWsRuEMo3A52NGYJSh48SxfxEU6RZIVbZL2YFZ2OAlzQ==", + "license": "MIT", + "dependencies": { + "@types/d3-path": "^2" + } + }, + "node_modules/@types/d3-time": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@types/d3-time/-/d3-time-1.1.1.tgz", + "integrity": "sha512-ULX7LoqXTCYtM+tLYOaeAJK7IwCT+4Gxlm2MaH0ErKLi07R5lh8NHCAyWcDkCCmx1AfRcBEV6H9QE9R25uP7jw==", + "license": "MIT" + }, + "node_modules/@types/d3-time-format": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@types/d3-time-format/-/d3-time-format-2.3.1.tgz", + "integrity": "sha512-fck0Z9RGfIQn3GJIEKVrp15h9m6Vlg0d5XXeiE/6+CQiBmMDZxfR21XtjEPuDeg7gC3bBM0SdieA5XF3GW1wKA==", + "license": "MIT" + }, + "node_modules/@types/d3-timer": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/@types/d3-timer/-/d3-timer-3.0.2.tgz", + "integrity": "sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==", + "license": "MIT" + }, + "node_modules/@types/debug": { + "version": "4.1.8", + "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.8.tgz", + "integrity": "sha512-/vPO1EPOs306Cvhwv7KfVfYvOJqA/S/AXjaHQiJboCZzcNDb+TIJFN9/2C9DZ//ijSKWioNyUxD792QmDJ+HKQ==", + "license": "MIT", + "dependencies": { + "@types/ms": "*" + } + }, + "node_modules/@types/eslint": { + "version": "8.44.2", + "resolved": "https://registry.npmjs.org/@types/eslint/-/eslint-8.44.2.tgz", + "integrity": "sha512-sdPRb9K6iL5XZOmBubg8yiFp5yS/JdUDQsq5e6h95km91MCYMuvp7mh1fjPEYUhvHepKpZOjnEaMBR4PxjWDzg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "*", + "@types/json-schema": "*" + } + }, + "node_modules/@types/estree": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.1.tgz", + "integrity": "sha512-LG4opVs2ANWZ1TJoKc937iMmNstM/d0ae1vNbnBvBhqCSezgVUOzcLCqbI5elV8Vy6WKwKjaqR+zO9VKirBBCA==", + "license": "MIT" + }, + "node_modules/@types/estree-jsx": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/@types/estree-jsx/-/estree-jsx-1.0.5.tgz", + "integrity": "sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==", + "license": "MIT", + "dependencies": { + "@types/estree": "*" + } + }, + "node_modules/@types/hast": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.4.tgz", + "integrity": "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==", + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/@types/istanbul-lib-coverage": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/@types/istanbul-lib-coverage/-/istanbul-lib-coverage-2.0.4.tgz", + "integrity": "sha512-z/QT1XN4K4KYuslS23k62yDIDLwLFkzxOuMplDtObz0+y7VqJCaO2o+SPwHCvLFZh7xazvvoor2tA/hPz9ee7g==", + "license": "MIT", + "peer": true + }, + "node_modules/@types/istanbul-lib-report": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/@types/istanbul-lib-report/-/istanbul-lib-report-3.0.0.tgz", + "integrity": "sha512-plGgXAPfVKFoYfa9NpYDAkseG+g6Jr294RqeqcqDixSbU34MZVJRi/P+7Y8GDpzkEwLaGZZOpKIEmeVZNtKsrg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@types/istanbul-lib-coverage": "*" + } + }, + "node_modules/@types/istanbul-reports": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/@types/istanbul-reports/-/istanbul-reports-3.0.1.tgz", + "integrity": "sha512-c3mAZEuK0lvBp8tmuL74XRKn1+y2dcwOUpH7x4WrF6gk1GIgiluDRgMYQtw2OFcBvAJWlt6ASU3tSqxp0Uu0Aw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@types/istanbul-lib-report": "*" + } + }, + "node_modules/@types/json-schema": { + "version": "7.0.12", + "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.12.tgz", + "integrity": "sha512-Hr5Jfhc9eYOQNPYO5WLDq/n4jqijdHNlDXjuAQkkt+mWdQR+XJToOHrsD4cPaMXpn6KO7y2+wM8AZEs8VpBLVA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/json5": { + "version": "0.0.29", + "resolved": "https://registry.npmjs.org/@types/json5/-/json5-0.0.29.tgz", + "integrity": "sha512-dRLjCWHYg4oaA77cxO64oO+7JwCwnIzkZPdrrC71jQmQtlhM556pwKo5bUzqvZndkVbeFLIIi+9TC40JNF5hNQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/mdast": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.4.tgz", + "integrity": "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==", + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/@types/mdx": { + "version": "2.0.13", + "resolved": "https://registry.npmjs.org/@types/mdx/-/mdx-2.0.13.tgz", + "integrity": "sha512-+OWZQfAYyio6YkJb3HLxDrvnx6SWWDbC0zVPfBRzUk0/nqoDyf6dNxQi3eArPe8rJ473nobTMQ/8Zk+LxJ+Yuw==", + "license": "MIT" + }, + "node_modules/@types/minimist": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/@types/minimist/-/minimist-1.2.5.tgz", + "integrity": "sha512-hov8bUuiLiyFPGyFPE1lwWhmzYbirOXQNNo40+y3zow8aFVTeyn3VWL0VFFfdNddA8S4Vf0Tc062rzyNr7Paag==", + "license": "MIT" + }, + "node_modules/@types/ms": { + "version": "0.7.31", + "resolved": "https://registry.npmjs.org/@types/ms/-/ms-0.7.31.tgz", + "integrity": "sha512-iiUgKzV9AuaEkZqkOLDIvlQiL6ltuZd9tGcW3gwpnX8JbuiuhFlEGmmFXEXkN50Cvq7Os88IY2v0dkDqXYWVgA==", + "license": "MIT" + }, + "node_modules/@types/node": { + "version": "18.17.5", + "resolved": "https://registry.npmjs.org/@types/node/-/node-18.17.5.tgz", + "integrity": "sha512-xNbS75FxH6P4UXTPUJp/zNPq6/xsfdJKussCWNOnz4aULWIRwMgP1LgaB5RiBnMX1DPCYenuqGZfnIAx5mbFLA==", + "license": "MIT" + }, + "node_modules/@types/prettier": { + "version": "2.7.3", + "resolved": "https://registry.npmjs.org/@types/prettier/-/prettier-2.7.3.tgz", + "integrity": "sha512-+68kP9yzs4LMp7VNh8gdzMSPZFL44MLGqiHWvttYJe+6qnuVr4Ek9wSBQoveqY/r+LwjCcU29kNVkidwim+kYA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/prop-types": { + "version": "15.7.5", + "resolved": "https://registry.npmjs.org/@types/prop-types/-/prop-types-15.7.5.tgz", + "integrity": "sha512-JCB8C6SnDoQf0cNycqd/35A7MjcnK+ZTqE7judS6o7utxUCg6imJg3QK2qzHKszlTjcj2cn+NwMB2i96ubpj7w==", + "license": "MIT" + }, + "node_modules/@types/react": { + "version": "18.2.20", + "resolved": "https://registry.npmjs.org/@types/react/-/react-18.2.20.tgz", + "integrity": "sha512-WKNtmsLWJM/3D5mG4U84cysVY31ivmyw85dE84fOCk5Hx78wezB/XEjVPWl2JTZ5FkEeaTJf+VgUAUn3PE7Isw==", + "license": "MIT", + "dependencies": { + "@types/prop-types": "*", + "@types/scheduler": "*", + "csstype": "^3.0.2" + } + }, + "node_modules/@types/react-dom": { + "version": "18.2.7", + "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-18.2.7.tgz", + "integrity": "sha512-GRaAEriuT4zp9N4p1i8BDBYmEyfo+xQ3yHjJU4eiK5NDa1RmUZG+unZABUTK4/Ox/M+GaHwb6Ow8rUITrtjszA==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@types/react": "*" + } + }, + "node_modules/@types/react-lifecycles-compat": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/@types/react-lifecycles-compat/-/react-lifecycles-compat-3.0.1.tgz", + "integrity": "sha512-4KiU5s1Go4xRbf7t6VxUUpBeN5PGjpjpBv9VvET4uiPHC500VNYBclU13f8ehHkHoZL39b2cfwHu6RzbV3b44A==", + "license": "MIT", + "dependencies": { + "@types/react": "*" + } + }, + "node_modules/@types/react-reconciler": { + "version": "0.26.7", + "resolved": "https://registry.npmjs.org/@types/react-reconciler/-/react-reconciler-0.26.7.tgz", + "integrity": "sha512-mBDYl8x+oyPX/VBb3E638N0B7xG+SPk/EAMcVPeexqus/5aTpTphQi0curhhshOqRrc9t6OPoJfEUkbymse/lQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@types/react": "*" + } + }, + "node_modules/@types/scheduler": { + "version": "0.16.3", + "resolved": "https://registry.npmjs.org/@types/scheduler/-/scheduler-0.16.3.tgz", + "integrity": "sha512-5cJ8CB4yAx7BH1oMvdU0Jh9lrEXyPkar6F9G/ERswkCuvP4KQZfZkSjcMbAICCpQTN4OuZn8tz0HiKv9TGZgrQ==", + "license": "MIT" + }, + "node_modules/@types/semver": { + "version": "7.5.0", + "resolved": "https://registry.npmjs.org/@types/semver/-/semver-7.5.0.tgz", + "integrity": "sha512-G8hZ6XJiHnuhQKR7ZmysCeJWE08o8T0AXtk5darsCaTVsYZhhgUrq53jizaR2FvsoeCwJhlmwTjkXBY5Pn/ZHw==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/stack-utils": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/@types/stack-utils/-/stack-utils-2.0.1.tgz", + "integrity": "sha512-Hl219/BT5fLAaz6NDkSuhzasy49dwQS/DSdu4MdggFB8zcXv7vflBI3xp7FEmkmdDkBUI2bPUNeMttp2knYdxw==", + "license": "MIT", + "peer": true + }, + "node_modules/@types/unist": { + "version": "2.0.8", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.8.tgz", + "integrity": "sha512-d0XxK3YTObnWVp6rZuev3c49+j4Lo8g4L1ZRm9z5L0xpoZycUPshHgczK5gsUMaZOstjVYYi09p5gYvUtfChYw==", + "license": "MIT" + }, + "node_modules/@types/yargs": { + "version": "17.0.24", + "resolved": "https://registry.npmjs.org/@types/yargs/-/yargs-17.0.24.tgz", + "integrity": "sha512-6i0aC7jV6QzQB8ne1joVZ0eSFIstHsCrobmOtghM11yGlH0j43FKL2UhWdELkyps0zuf7qVTUVCCR+tgSlyLLw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@types/yargs-parser": "*" + } + }, + "node_modules/@types/yargs-parser": { + "version": "21.0.0", + "resolved": "https://registry.npmjs.org/@types/yargs-parser/-/yargs-parser-21.0.0.tgz", + "integrity": "sha512-iO9ZQHkZxHn4mSakYV0vFHAVDyEOIJQrV2uZ06HxEPcx+mt8swXoZHIbaaJ2crJYFfErySgktuTZ3BeLz+XmFA==", + "license": "MIT", + "peer": true + }, + "node_modules/@typescript-eslint/eslint-plugin": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-6.0.0.tgz", + "integrity": "sha512-xuv6ghKGoiq856Bww/yVYnXGsKa588kY3M0XK7uUW/3fJNNULKRfZfSBkMTSpqGG/8ZCXCadfh8G/z/B4aqS/A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@eslint-community/regexpp": "^4.5.0", + "@typescript-eslint/scope-manager": "6.0.0", + "@typescript-eslint/type-utils": "6.0.0", + "@typescript-eslint/utils": "6.0.0", + "@typescript-eslint/visitor-keys": "6.0.0", + "debug": "^4.3.4", + "grapheme-splitter": "^1.0.4", + "graphemer": "^1.4.0", + "ignore": "^5.2.4", + "natural-compare": "^1.4.0", + "natural-compare-lite": "^1.4.0", + "semver": "^7.5.0", + "ts-api-utils": "^1.0.1" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "@typescript-eslint/parser": "^6.0.0 || ^6.0.0-alpha", + "eslint": "^7.0.0 || ^8.0.0" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, + "node_modules/@typescript-eslint/parser": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-6.0.0.tgz", + "integrity": "sha512-TNaufYSPrr1U8n+3xN+Yp9g31vQDJqhXzzPSHfQDLcaO4tU+mCfODPxCwf4H530zo7aUBE3QIdxCXamEnG04Tg==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "@typescript-eslint/scope-manager": "6.0.0", + "@typescript-eslint/types": "6.0.0", + "@typescript-eslint/typescript-estree": "6.0.0", + "@typescript-eslint/visitor-keys": "6.0.0", + "debug": "^4.3.4" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "eslint": "^7.0.0 || ^8.0.0" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, + "node_modules/@typescript-eslint/scope-manager": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-6.0.0.tgz", + "integrity": "sha512-o4q0KHlgCZTqjuaZ25nw5W57NeykZT9LiMEG4do/ovwvOcPnDO1BI5BQdCsUkjxFyrCL0cSzLjvIMfR9uo7cWg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/types": "6.0.0", + "@typescript-eslint/visitor-keys": "6.0.0" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + } + }, + "node_modules/@typescript-eslint/type-utils": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/type-utils/-/type-utils-6.0.0.tgz", + "integrity": "sha512-ah6LJvLgkoZ/pyJ9GAdFkzeuMZ8goV6BH7eC9FPmojrnX9yNCIsfjB+zYcnex28YO3RFvBkV6rMV6WpIqkPvoQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/typescript-estree": "6.0.0", + "@typescript-eslint/utils": "6.0.0", + "debug": "^4.3.4", + "ts-api-utils": "^1.0.1" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "eslint": "^7.0.0 || ^8.0.0" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, + "node_modules/@typescript-eslint/types": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-6.0.0.tgz", + "integrity": "sha512-Zk9KDggyZM6tj0AJWYYKgF0yQyrcnievdhG0g5FqyU3Y2DRxJn4yWY21sJC0QKBckbsdKKjYDV2yVrrEvuTgxg==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + } + }, + "node_modules/@typescript-eslint/typescript-estree": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-6.0.0.tgz", + "integrity": "sha512-2zq4O7P6YCQADfmJ5OTDQTP3ktajnXIRrYAtHM9ofto/CJZV3QfJ89GEaM2BNGeSr1KgmBuLhEkz5FBkS2RQhQ==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "@typescript-eslint/types": "6.0.0", + "@typescript-eslint/visitor-keys": "6.0.0", + "debug": "^4.3.4", + "globby": "^11.1.0", + "is-glob": "^4.0.3", + "semver": "^7.5.0", + "ts-api-utils": "^1.0.1" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, + "node_modules/@typescript-eslint/utils": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/utils/-/utils-6.0.0.tgz", + "integrity": "sha512-SOr6l4NB6HE4H/ktz0JVVWNXqCJTOo/mHnvIte1ZhBQ0Cvd04x5uKZa3zT6tiodL06zf5xxdK8COiDvPnQ27JQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@eslint-community/eslint-utils": "^4.3.0", + "@types/json-schema": "^7.0.11", + "@types/semver": "^7.3.12", + "@typescript-eslint/scope-manager": "6.0.0", + "@typescript-eslint/types": "6.0.0", + "@typescript-eslint/typescript-estree": "6.0.0", + "eslint-scope": "^5.1.1", + "semver": "^7.5.0" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "eslint": "^7.0.0 || ^8.0.0" + } + }, + "node_modules/@typescript-eslint/visitor-keys": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-6.0.0.tgz", + "integrity": "sha512-cvJ63l8c0yXdeT5POHpL0Q1cZoRcmRKFCtSjNGJxPkcP571EfZMcNbzWAc7oK3D1dRzm/V5EwtkANTZxqvuuUA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/types": "6.0.0", + "eslint-visitor-keys": "^3.4.1" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + } + }, + "node_modules/@ungap/structured-clone": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.3.0.tgz", + "integrity": "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==", + "license": "ISC" + }, + "node_modules/@xterm/addon-fit": { + "version": "0.10.0", + "resolved": "https://registry.npmjs.org/@xterm/addon-fit/-/addon-fit-0.10.0.tgz", + "integrity": "sha512-UFYkDm4HUahf2lnEyHvio51TNGiLK66mqP2JoATy7hRZeXaGMRDr00JiSF7m63vR5WKATF605yEggJKsw0JpMQ==", + "license": "MIT", + "peerDependencies": { + "@xterm/xterm": "^5.0.0" + } + }, + "node_modules/@xterm/addon-search": { + "version": "0.16.0", + "resolved": "https://registry.npmjs.org/@xterm/addon-search/-/addon-search-0.16.0.tgz", + "integrity": "sha512-9OeuBFu0/uZJPu+9AHKY6g/w0Czyb/Ut0A5t79I4ULoU4IfU5BEpPFVGQxP4zTTMdfZEYkVIRYbHBX1xWwjeSA==", + "license": "MIT" + }, + "node_modules/@xterm/addon-web-links": { + "version": "0.11.0", + "resolved": "https://registry.npmjs.org/@xterm/addon-web-links/-/addon-web-links-0.11.0.tgz", + "integrity": "sha512-nIHQ38pQI+a5kXnRaTgwqSHnX7KE6+4SVoceompgHL26unAxdfP6IPqUTSYPQgSwM56hsElfoNrrW5V7BUED/Q==", + "license": "MIT", + "peerDependencies": { + "@xterm/xterm": "^5.0.0" + } + }, + "node_modules/@xterm/xterm": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-5.5.0.tgz", + "integrity": "sha512-hqJHYaQb5OptNunnyAnkHyM8aCjZ1MEIDTQu1iIbbTD/xops91NB5yq1ZK/dC2JDbVWtF23zUtl9JE2NqwT87A==", + "license": "MIT" + }, + "node_modules/abbrev": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz", + "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==", + "license": "ISC" + }, + "node_modules/abort-controller": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/abort-controller/-/abort-controller-3.0.0.tgz", + "integrity": "sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==", + "license": "MIT", + "peer": true, + "dependencies": { + "event-target-shim": "^5.0.0" + }, + "engines": { + "node": ">=6.5" + } + }, + "node_modules/accepts": { + "version": "1.3.8", + "resolved": "https://registry.npmjs.org/accepts/-/accepts-1.3.8.tgz", + "integrity": "sha512-PYAthTa2m2VKxuvSD3DPC/Gy+U+sOA1LAuT8mkmRuvw+NACSaeXEQ+NHcVF7rONl6qcaxV3Uuemwawk+7+SJLw==", + "license": "MIT", + "peer": true, + "dependencies": { + "mime-types": "~2.1.34", + "negotiator": "0.6.3" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/acorn": { + "version": "8.14.1", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.14.1.tgz", + "integrity": "sha512-OvQ/2pUDKmgfCg++xsTX1wGxfTaszcHVcTctW4UJB4hibJx2HXxxO5UmVgyjMa+ZDsiaf5wWLXYpRWMmBI0QHg==", + "license": "MIT", + "bin": { + "acorn": "bin/acorn" + }, + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/acorn-jsx": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/acorn-jsx/-/acorn-jsx-5.3.2.tgz", + "integrity": "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==", + "license": "MIT", + "peerDependencies": { + "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" + } + }, + "node_modules/acorn-walk": { + "version": "8.3.4", + "resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-8.3.4.tgz", + "integrity": "sha512-ueEepnujpqee2o5aIYnvHU6C0A42MNdsIDeqy5BydrkuC5R1ZuUFnm27EeFJGoEHJQgn3uleRvmTXaJgfXbt4g==", + "license": "MIT", + "dependencies": { + "acorn": "^8.11.0" + }, + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/agent-base": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-6.0.2.tgz", + "integrity": "sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ==", + "license": "MIT", + "dependencies": { + "debug": "4" + }, + "engines": { + "node": ">= 6.0.0" + } + }, + "node_modules/ajv": { + "version": "6.12.6", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz", + "integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==", + "dev": true, + "license": "MIT", + "dependencies": { + "fast-deep-equal": "^3.1.1", + "fast-json-stable-stringify": "^2.0.0", + "json-schema-traverse": "^0.4.1", + "uri-js": "^4.2.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, + "node_modules/amqplib": { + "version": "0.10.5", + "resolved": "https://registry.npmjs.org/amqplib/-/amqplib-0.10.5.tgz", + "integrity": "sha512-Dx5zmy0Ur+Q7LPPdhz+jx5IzmJBoHd15tOeAfQ8SuvEtyPJ20hBemhOBA4b1WeORCRa0ENM/kHCzmem1w/zHvQ==", + "license": "MIT", + "dependencies": { + "@acuminous/bitsyntax": "^0.1.2", + "buffer-more-ints": "~1.0.0", + "url-parse": "~1.5.10" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/anser": { + "version": "1.4.10", + "resolved": "https://registry.npmjs.org/anser/-/anser-1.4.10.tgz", + "integrity": "sha512-hCv9AqTQ8ycjpSd3upOJd7vFwW1JaoYQ7tpham03GJ1ca8/65rqn0RpaWpItOAd6ylW9wAw6luXYPJIyPFVOww==", + "license": "MIT", + "peer": true + }, + "node_modules/ansi-fragments": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/ansi-fragments/-/ansi-fragments-0.2.1.tgz", + "integrity": "sha512-DykbNHxuXQwUDRv5ibc2b0x7uw7wmwOGLBUd5RmaQ5z8Lhx19vwvKV+FAsM5rEA6dEcHxX+/Ad5s9eF2k2bB+w==", + "license": "MIT", + "peer": true, + "dependencies": { + "colorette": "^1.0.7", + "slice-ansi": "^2.0.0", + "strip-ansi": "^5.0.0" + } + }, + "node_modules/ansi-fragments/node_modules/ansi-regex": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-4.1.1.tgz", + "integrity": "sha512-ILlv4k/3f6vfQ4OoP2AGvirOktlQ98ZEL1k9FaQjxa3L1abBgbuTDAdPOpvbGncC0BTVQrl+OM8xZGK6tWXt7g==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/ansi-fragments/node_modules/strip-ansi": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-5.2.0.tgz", + "integrity": "sha512-DuRs1gKbBqsMKIZlrffwlug8MHkcnpjs5VPmL1PAh+mA30U0DTotfDZ0d2UUsXpPmPmMMJ6W773MaA3J+lbiWA==", + "license": "MIT", + "peer": true, + "dependencies": { + "ansi-regex": "^4.1.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "license": "MIT", + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/any-promise": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/any-promise/-/any-promise-1.3.0.tgz", + "integrity": "sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==", + "license": "MIT" + }, + "node_modules/anymatch": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.3.tgz", + "integrity": "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==", + "license": "ISC", + "dependencies": { + "normalize-path": "^3.0.0", + "picomatch": "^2.0.4" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/appdirsjs": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/appdirsjs/-/appdirsjs-1.2.7.tgz", + "integrity": "sha512-Quji6+8kLBC3NnBeo14nPDq0+2jUs5s3/xEye+udFHumHhRk4M7aAMXp/PBJqkKYGuuyR9M/6Dq7d2AViiGmhw==", + "license": "MIT", + "peer": true + }, + "node_modules/aproba": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/aproba/-/aproba-2.0.0.tgz", + "integrity": "sha512-lYe4Gx7QT+MKGbDsA+Z+he/Wtef0BiwDOlK/XkBrdfsh9J/jPPXbX0tE9x9cl27Tmu5gg3QUbUrQYa/y+KOHPQ==", + "license": "ISC" + }, + "node_modules/are-we-there-yet": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/are-we-there-yet/-/are-we-there-yet-2.0.0.tgz", + "integrity": "sha512-Ci/qENmwHnsYo9xKIcUJN5LeDKdJ6R1Z1j9V/J5wyq8nh/mYPEpIKJbBZXtZjG04HiK7zV/p6Vs9952MrMeUIw==", + "deprecated": "This package is no longer supported.", + "license": "ISC", + "dependencies": { + "delegates": "^1.0.0", + "readable-stream": "^3.6.0" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/arg": { + "version": "5.0.2", + "resolved": "https://registry.npmjs.org/arg/-/arg-5.0.2.tgz", + "integrity": "sha512-PYjyFOLKQ9y57JvQ6QLo8dAgNqswh8M1RMJYdQduT6xbWSgK36P/Z/v+p888pM69jMMfS8Xd8F6I1kQ/I9HUGg==", + "license": "MIT" + }, + "node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "license": "Python-2.0" + }, + "node_modules/aria-hidden": { + "version": "1.2.6", + "resolved": "https://registry.npmjs.org/aria-hidden/-/aria-hidden-1.2.6.tgz", + "integrity": "sha512-ik3ZgC9dY/lYVVM++OISsaYDeg1tb0VtP5uL3ouh1koGOaUMDPpbFIei4JkFimWUFPn90sbMNMXQAIVOlnYKJA==", + "license": "MIT", + "dependencies": { + "tslib": "^2.0.0" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/aria-query": { + "version": "5.3.0", + "resolved": "https://registry.npmjs.org/aria-query/-/aria-query-5.3.0.tgz", + "integrity": "sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "dequal": "^2.0.3" + } + }, + "node_modules/array-buffer-byte-length": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/array-buffer-byte-length/-/array-buffer-byte-length-1.0.0.tgz", + "integrity": "sha512-LPuwb2P+NrQw3XhxGc36+XSvuBPopovXYTR9Ew++Du9Yb/bx5AzBfrIsBoj0EZUifjQU+sHL21sseZ3jerWO/A==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "is-array-buffer": "^3.0.1" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/array-includes": { + "version": "3.1.6", + "resolved": "https://registry.npmjs.org/array-includes/-/array-includes-3.1.6.tgz", + "integrity": "sha512-sgTbLvL6cNnw24FnbaDyjmvddQ2ML8arZsgaJhoABMoplz/4QRhtrYS+alr1BUM1Bwp6dhx8vVCBSLG+StwOFw==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4", + "get-intrinsic": "^1.1.3", + "is-string": "^1.0.7" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/array-union": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/array-union/-/array-union-2.1.0.tgz", + "integrity": "sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/array.prototype.findlastindex": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/array.prototype.findlastindex/-/array.prototype.findlastindex-1.2.2.tgz", + "integrity": "sha512-tb5thFFlUcp7NdNF6/MpDk/1r/4awWG1FIz3YqDf+/zJSTezBb+/5WViH41obXULHVpDzoiCLpJ/ZO9YbJMsdw==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4", + "es-shim-unscopables": "^1.0.0", + "get-intrinsic": "^1.1.3" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/array.prototype.flat": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/array.prototype.flat/-/array.prototype.flat-1.3.1.tgz", + "integrity": "sha512-roTU0KWIOmJ4DRLmwKd19Otg0/mT3qPNt0Qb3GWW8iObuZXxrjB/pzn0R3hqpRSWg4HCwqx+0vwOnWnvlOyeIA==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4", + "es-shim-unscopables": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/array.prototype.flatmap": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/array.prototype.flatmap/-/array.prototype.flatmap-1.3.1.tgz", + "integrity": "sha512-8UGn9O1FDVvMNB0UlLv4voxRMze7+FpHyF5mSMRjWHUMlpoDViniy05870VlxhfgTnLbpuwTzvD76MTtWxB/mQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4", + "es-shim-unscopables": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/array.prototype.tosorted": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/array.prototype.tosorted/-/array.prototype.tosorted-1.1.1.tgz", + "integrity": "sha512-pZYPXPRl2PqWcsUs6LOMn+1f1532nEoPTYowBtqLwAW+W8vSVhkIGnmOX1t/UQjD6YGI0vcD2B1U7ZFGQH9jnQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4", + "es-shim-unscopables": "^1.0.0", + "get-intrinsic": "^1.1.3" + } + }, + "node_modules/arraybuffer.prototype.slice": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/arraybuffer.prototype.slice/-/arraybuffer.prototype.slice-1.0.1.tgz", + "integrity": "sha512-09x0ZWFEjj4WD8PDbykUwo3t9arLn8NIzmmYEJFpYekOAQjpkGSyrQhNoRTcwwcFRu+ycWF78QZ63oWTqSjBcw==", + "dev": true, + "license": "MIT", + "dependencies": { + "array-buffer-byte-length": "^1.0.0", + "call-bind": "^1.0.2", + "define-properties": "^1.2.0", + "get-intrinsic": "^1.2.1", + "is-array-buffer": "^3.0.2", + "is-shared-array-buffer": "^1.0.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/asap": { + "version": "2.0.6", + "resolved": "https://registry.npmjs.org/asap/-/asap-2.0.6.tgz", + "integrity": "sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA==", + "license": "MIT", + "peer": true + }, + "node_modules/ast-types": { + "version": "0.15.2", + "resolved": "https://registry.npmjs.org/ast-types/-/ast-types-0.15.2.tgz", + "integrity": "sha512-c27loCv9QkZinsa5ProX751khO9DJl/AcB5c2KNtA6NRvHKS0PgLfcftz72KVq504vB0Gku5s2kUZzDBvQWvHg==", + "license": "MIT", + "peer": true, + "dependencies": { + "tslib": "^2.0.1" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/ast-types-flow": { + "version": "0.0.7", + "resolved": "https://registry.npmjs.org/ast-types-flow/-/ast-types-flow-0.0.7.tgz", + "integrity": "sha512-eBvWn1lvIApYMhzQMsu9ciLfkBY499mFZlNqG+/9WR7PVlroQw0vG30cOQQbaKz3sCEc44TAOu2ykzqXSNnwag==", + "dev": true, + "license": "ISC" + }, + "node_modules/astral-regex": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/astral-regex/-/astral-regex-1.0.0.tgz", + "integrity": "sha512-+Ryf6g3BKoRc7jfp7ad8tM4TtMiaWvbF/1/sQcZPkkS7ag3D5nMBCe2UfOTONtAkaG0tO0ij3C5Lwmf1EiyjHg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/astring": { + "version": "1.9.0", + "resolved": "https://registry.npmjs.org/astring/-/astring-1.9.0.tgz", + "integrity": "sha512-LElXdjswlqjWrPpJFg1Fx4wpkOCxj1TDHlSV4PlaRxHGWko024xICaa97ZkMfs6DRKlCguiAI+rbXv5GWwXIkg==", + "license": "MIT", + "bin": { + "astring": "bin/astring" + } + }, + "node_modules/async": { + "version": "3.2.4", + "resolved": "https://registry.npmjs.org/async/-/async-3.2.4.tgz", + "integrity": "sha512-iAB+JbDEGXhyIUavoDl9WP/Jj106Kz9DEn1DPgYw5ruDn0e3Wgi3sKFm55sASdGBNOQB8F59d9qQ7deqrHA8wQ==", + "license": "MIT", + "peer": true + }, + "node_modules/async-limiter": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/async-limiter/-/async-limiter-1.0.1.tgz", + "integrity": "sha512-csOlWGAcRFJaI6m+F2WKdnMKr4HhdhFVBk0H/QbJFMCr+uO2kwohwXQPxw/9OCxp05r5ghVBFSyioixx3gfkNQ==", + "license": "MIT", + "peer": true + }, + "node_modules/asynciterator.prototype": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/asynciterator.prototype/-/asynciterator.prototype-1.0.0.tgz", + "integrity": "sha512-wwHYEIS0Q80f5mosx3L/dfG5t5rjEa9Ft51GTaNt862EnpyGHpgz2RkZvLPp1oF5TnAiTohkEKVEu8pQPJI7Vg==", + "dev": true, + "license": "MIT", + "dependencies": { + "has-symbols": "^1.0.3" + } + }, + "node_modules/asynckit": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz", + "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==", + "license": "MIT" + }, + "node_modules/autoprefixer": { + "version": "10.4.15", + "resolved": "https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.4.15.tgz", + "integrity": "sha512-KCuPB8ZCIqFdA4HwKXsvz7j6gvSDNhDP7WnUjBleRkKjPdvCmHFuQ77ocavI8FT6NdvlBnE2UFr2H4Mycn8Vew==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/autoprefixer" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "browserslist": "^4.21.10", + "caniuse-lite": "^1.0.30001520", + "fraction.js": "^4.2.0", + "normalize-range": "^0.1.2", + "picocolors": "^1.0.0", + "postcss-value-parser": "^4.2.0" + }, + "bin": { + "autoprefixer": "bin/autoprefixer" + }, + "engines": { + "node": "^10 || ^12 || >=14" + }, + "peerDependencies": { + "postcss": "^8.1.0" + } + }, + "node_modules/available-typed-arrays": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/available-typed-arrays/-/available-typed-arrays-1.0.5.tgz", + "integrity": "sha512-DMD0KiN46eipeziST1LPP/STfDU0sufISXmjSgvVsoU2tqxctQeASejWcfNtxYKqETM1UxQ8sp2OrSBWpHY6sw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/axe-core": { + "version": "4.7.2", + "resolved": "https://registry.npmjs.org/axe-core/-/axe-core-4.7.2.tgz", + "integrity": "sha512-zIURGIS1E1Q4pcrMjp+nnEh+16G56eG/MUllJH8yEvw7asDo7Ac9uhC9KIH5jzpITueEZolfYglnCGIuSBz39g==", + "dev": true, + "license": "MPL-2.0", + "engines": { + "node": ">=4" + } + }, + "node_modules/axios": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/axios/-/axios-1.5.0.tgz", + "integrity": "sha512-D4DdjDo5CY50Qms0qGQTTw6Q44jl7zRwY7bthds06pUGfChBCTcQs+N743eFWGEd6pRTMd6A+I87aWyFV5wiZQ==", + "license": "MIT", + "dependencies": { + "follow-redirects": "^1.15.0", + "form-data": "^4.0.0", + "proxy-from-env": "^1.1.0" + } + }, + "node_modules/axobject-query": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/axobject-query/-/axobject-query-3.2.1.tgz", + "integrity": "sha512-jsyHu61e6N4Vbz/v18DHwWYKK0bSWLqn47eeDSKPB7m8tqMHF9YJ+mhIk2lVteyZrY8tnSj/jHOv4YiTCuCJgg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "dequal": "^2.0.3" + } + }, + "node_modules/babel-core": { + "version": "7.0.0-bridge.0", + "resolved": "https://registry.npmjs.org/babel-core/-/babel-core-7.0.0-bridge.0.tgz", + "integrity": "sha512-poPX9mZH/5CSanm50Q+1toVci6pv5KSRv/5TWCwtzQS5XEwn40BcCrgIeMFWP9CKKIniKXNxoIOnOq4VVlGXhg==", + "license": "MIT", + "peer": true, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/babel-plugin-polyfill-corejs2": { + "version": "0.4.5", + "resolved": "https://registry.npmjs.org/babel-plugin-polyfill-corejs2/-/babel-plugin-polyfill-corejs2-0.4.5.tgz", + "integrity": "sha512-19hwUH5FKl49JEsvyTcoHakh6BE0wgXLLptIyKZ3PijHc/Ci521wygORCUCCred+E/twuqRyAkE02BAWPmsHOg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/compat-data": "^7.22.6", + "@babel/helper-define-polyfill-provider": "^0.4.2", + "semver": "^6.3.1" + }, + "peerDependencies": { + "@babel/core": "^7.4.0 || ^8.0.0-0 <8.0.0" + } + }, + "node_modules/babel-plugin-polyfill-corejs2/node_modules/semver": { + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", + "license": "ISC", + "peer": true, + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/babel-plugin-polyfill-corejs3": { + "version": "0.8.3", + "resolved": "https://registry.npmjs.org/babel-plugin-polyfill-corejs3/-/babel-plugin-polyfill-corejs3-0.8.3.tgz", + "integrity": "sha512-z41XaniZL26WLrvjy7soabMXrfPWARN25PZoriDEiLMxAp50AUW3t35BGQUMg5xK3UrpVTtagIDklxYa+MhiNA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-define-polyfill-provider": "^0.4.2", + "core-js-compat": "^3.31.0" + }, + "peerDependencies": { + "@babel/core": "^7.4.0 || ^8.0.0-0 <8.0.0" + } + }, + "node_modules/babel-plugin-polyfill-regenerator": { + "version": "0.5.2", + "resolved": "https://registry.npmjs.org/babel-plugin-polyfill-regenerator/-/babel-plugin-polyfill-regenerator-0.5.2.tgz", + "integrity": "sha512-tAlOptU0Xj34V1Y2PNTL4Y0FOJMDB6bZmoW39FeCQIhigGLkqu3Fj6uiXpxIf6Ij274ENdYx64y6Au+ZKlb1IA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/helper-define-polyfill-provider": "^0.4.2" + }, + "peerDependencies": { + "@babel/core": "^7.4.0 || ^8.0.0-0 <8.0.0" + } + }, + "node_modules/babel-plugin-syntax-trailing-function-commas": { + "version": "7.0.0-beta.0", + "resolved": "https://registry.npmjs.org/babel-plugin-syntax-trailing-function-commas/-/babel-plugin-syntax-trailing-function-commas-7.0.0-beta.0.tgz", + "integrity": "sha512-Xj9XuRuz3nTSbaTXWv3itLOcxyF4oPD8douBBmj7U9BBC6nEBYfyOJYQMf/8PJAFotC62UY5dFfIGEPr7WswzQ==", + "license": "MIT", + "peer": true + }, + "node_modules/babel-plugin-transform-flow-enums": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/babel-plugin-transform-flow-enums/-/babel-plugin-transform-flow-enums-0.0.2.tgz", + "integrity": "sha512-g4aaCrDDOsWjbm0PUUeVnkcVd6AKJsVc/MbnPhEotEpkeJQP6b8nzewohQi7+QS8UyPehOhGWn0nOwjvWpmMvQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/plugin-syntax-flow": "^7.12.1" + } + }, + "node_modules/babel-preset-fbjs": { + "version": "3.4.0", + "resolved": "https://registry.npmjs.org/babel-preset-fbjs/-/babel-preset-fbjs-3.4.0.tgz", + "integrity": "sha512-9ywCsCvo1ojrw0b+XYk7aFvTH6D9064t0RIL1rtMf3nsa02Xw41MS7sZw216Im35xj/UY0PDBQsa1brUDDF1Ow==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/plugin-proposal-class-properties": "^7.0.0", + "@babel/plugin-proposal-object-rest-spread": "^7.0.0", + "@babel/plugin-syntax-class-properties": "^7.0.0", + "@babel/plugin-syntax-flow": "^7.0.0", + "@babel/plugin-syntax-jsx": "^7.0.0", + "@babel/plugin-syntax-object-rest-spread": "^7.0.0", + "@babel/plugin-transform-arrow-functions": "^7.0.0", + "@babel/plugin-transform-block-scoped-functions": "^7.0.0", + "@babel/plugin-transform-block-scoping": "^7.0.0", + "@babel/plugin-transform-classes": "^7.0.0", + "@babel/plugin-transform-computed-properties": "^7.0.0", + "@babel/plugin-transform-destructuring": "^7.0.0", + "@babel/plugin-transform-flow-strip-types": "^7.0.0", + "@babel/plugin-transform-for-of": "^7.0.0", + "@babel/plugin-transform-function-name": "^7.0.0", + "@babel/plugin-transform-literals": "^7.0.0", + "@babel/plugin-transform-member-expression-literals": "^7.0.0", + "@babel/plugin-transform-modules-commonjs": "^7.0.0", + "@babel/plugin-transform-object-super": "^7.0.0", + "@babel/plugin-transform-parameters": "^7.0.0", + "@babel/plugin-transform-property-literals": "^7.0.0", + "@babel/plugin-transform-react-display-name": "^7.0.0", + "@babel/plugin-transform-react-jsx": "^7.0.0", + "@babel/plugin-transform-shorthand-properties": "^7.0.0", + "@babel/plugin-transform-spread": "^7.0.0", + "@babel/plugin-transform-template-literals": "^7.0.0", + "babel-plugin-syntax-trailing-function-commas": "^7.0.0-beta.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0" + } + }, + "node_modules/bail": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/bail/-/bail-2.0.2.tgz", + "integrity": "sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/balanced-match": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", + "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==", + "license": "MIT" + }, + "node_modules/base64-js": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz", + "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT", + "peer": true + }, + "node_modules/bcrypt": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/bcrypt/-/bcrypt-5.1.1.tgz", + "integrity": "sha512-AGBHOG5hPYZ5Xl9KXzU5iKq9516yEmvCKDg3ecP5kX2aB6UqTeXZxk2ELnDgDm6BQSMlLt9rDB4LoSMx0rYwww==", + "hasInstallScript": true, + "license": "MIT", + "dependencies": { + "@mapbox/node-pre-gyp": "^1.0.11", + "node-addon-api": "^5.0.0" + }, + "engines": { + "node": ">= 10.0.0" + } + }, + "node_modules/binary-extensions": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.2.0.tgz", + "integrity": "sha512-jDctJ/IVQbZoJykoeHbhXpOlNBqGNcwXJKJog42E5HDPUwQTSdjCHdihjj0DlnheQ7blbT6dHOafNAiS8ooQKA==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/bl": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/bl/-/bl-4.1.0.tgz", + "integrity": "sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w==", + "license": "MIT", + "peer": true, + "dependencies": { + "buffer": "^5.5.0", + "inherits": "^2.0.4", + "readable-stream": "^3.4.0" + } + }, + "node_modules/brace-expansion": { + "version": "1.1.11", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", + "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", + "license": "MIT", + "dependencies": { + "balanced-match": "^1.0.0", + "concat-map": "0.0.1" + } + }, + "node_modules/braces": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.2.tgz", + "integrity": "sha512-b8um+L1RzM3WDSzvhm6gIz1yfTbBt6YTlcEKAvsmqCZZFw46z626lVj9j1yEPW33H5H+lBQpZMP1k8l+78Ha0A==", + "license": "MIT", + "dependencies": { + "fill-range": "^7.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/browserslist": { + "version": "4.21.10", + "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.21.10.tgz", + "integrity": "sha512-bipEBdZfVH5/pwrvqc+Ub0kUPVfGUhlKxbvfD+z1BDnPEO/X98ruXGA1WP5ASpAFKan7Qr6j736IacbZQuAlKQ==", + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/browserslist" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "caniuse-lite": "^1.0.30001517", + "electron-to-chromium": "^1.4.477", + "node-releases": "^2.0.13", + "update-browserslist-db": "^1.0.11" + }, + "bin": { + "browserslist": "cli.js" + }, + "engines": { + "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7" + } + }, + "node_modules/bser": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/bser/-/bser-2.1.1.tgz", + "integrity": "sha512-gQxTNE/GAfIIrmHLUE3oJyp5FO6HRBfhjnw4/wMmA63ZGDJnWBmgY/lyQBpnDUkGmAhbSe39tx2d/iTOAfglwQ==", + "license": "Apache-2.0", + "peer": true, + "dependencies": { + "node-int64": "^0.4.0" + } + }, + "node_modules/buffer": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/buffer/-/buffer-5.7.1.tgz", + "integrity": "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT", + "peer": true, + "dependencies": { + "base64-js": "^1.3.1", + "ieee754": "^1.1.13" + } + }, + "node_modules/buffer-from": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.2.tgz", + "integrity": "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==", + "license": "MIT", + "peer": true + }, + "node_modules/buffer-more-ints": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/buffer-more-ints/-/buffer-more-ints-1.0.0.tgz", + "integrity": "sha512-EMetuGFz5SLsT0QTnXzINh4Ksr+oo4i+UGTXEshiGCQWnsgSs7ZhJ8fzlwQ+OzEMs0MpDAMr1hxnblp5a4vcHg==", + "license": "MIT" + }, + "node_modules/busboy": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/busboy/-/busboy-1.6.0.tgz", + "integrity": "sha512-8SFQbg/0hQ9xy3UNTB0YEnsNBbWfhf7RtnzpL7TkBiTBRfrQ9Fxcnz7VJsleJpyp6rVLvXiuORqjlHi5q+PYuA==", + "dependencies": { + "streamsearch": "^1.1.0" + }, + "engines": { + "node": ">=10.16.0" + } + }, + "node_modules/bytes": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.0.0.tgz", + "integrity": "sha512-pMhOfFDPiv9t5jjIXkHosWmkSyQbvsgEVNkz0ERHbuLh2T/7j4Mqqpz523Fe8MVY89KC6Sh/QfS2sM+SjgFDcw==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/call-bind": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/call-bind/-/call-bind-1.0.2.tgz", + "integrity": "sha512-7O+FbCihrB5WGbFYesctwmTKae6rOiIzmz1icreWJ+0aA7LJfuqhEso2T9ncpcFtzMQtzXf2QGGueWJGTYsqrA==", + "dev": true, + "license": "MIT", + "dependencies": { + "function-bind": "^1.1.1", + "get-intrinsic": "^1.0.2" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/caller-callsite": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/caller-callsite/-/caller-callsite-2.0.0.tgz", + "integrity": "sha512-JuG3qI4QOftFsZyOn1qq87fq5grLIyk1JYd5lJmdA+fG7aQ9pA/i3JIJGcO3q0MrRcHlOt1U+ZeHW8Dq9axALQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "callsites": "^2.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/caller-callsite/node_modules/callsites": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/callsites/-/callsites-2.0.0.tgz", + "integrity": "sha512-ksWePWBloaWPxJYQ8TL0JHvtci6G5QTKwQ95RcWAa/lzoAKuAOflGdAK92hpHXjkwb8zLxoLNUoNYZgVsaJzvQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/caller-path": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/caller-path/-/caller-path-2.0.0.tgz", + "integrity": "sha512-MCL3sf6nCSXOwCTzvPKhN18TU7AHTvdtam8DAogxcrJ8Rjfbbg7Lgng64H9Iy+vUV6VGFClN/TyxBkAebLRR4A==", + "license": "MIT", + "peer": true, + "dependencies": { + "caller-callsite": "^2.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/callsites": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz", + "integrity": "sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/camelcase": { + "version": "6.3.0", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-6.3.0.tgz", + "integrity": "sha512-Gmy6FhYlCY7uOElZUSbxo2UCDH8owEk996gkbrpsgGtrJLM3J7jGxl9Ic7Qwwj4ivOE5AWZWRMecDdF7hqGjFA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/camelcase-css": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/camelcase-css/-/camelcase-css-2.0.1.tgz", + "integrity": "sha512-QOSvevhslijgYwRx6Rv7zKdMF8lbRmx+uQGx2+vDc+KI/eBnsy9kit5aj23AgGu3pa4t9AgwbnXWqS+iOY+2aA==", + "license": "MIT", + "engines": { + "node": ">= 6" + } + }, + "node_modules/caniuse-lite": { + "version": "1.0.30001521", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001521.tgz", + "integrity": "sha512-fnx1grfpEOvDGH+V17eccmNjucGUnCbP6KL+l5KqBIerp26WK/+RQ7CIDE37KGJjaPyqWXXlFUyKiWmvdNNKmQ==", + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/caniuse-lite" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "CC-BY-4.0" + }, + "node_modules/ccount": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/ccount/-/ccount-2.0.1.tgz", + "integrity": "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/chalk": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", + "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", + "license": "MIT", + "dependencies": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/chalk?sponsor=1" + } + }, + "node_modules/character-entities": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/character-entities/-/character-entities-2.0.2.tgz", + "integrity": "sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities-html4": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/character-entities-html4/-/character-entities-html4-2.1.0.tgz", + "integrity": "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities-legacy": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/character-entities-legacy/-/character-entities-legacy-3.0.0.tgz", + "integrity": "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-reference-invalid": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/character-reference-invalid/-/character-reference-invalid-2.0.1.tgz", + "integrity": "sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/chokidar": { + "version": "3.5.3", + "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.5.3.tgz", + "integrity": "sha512-Dr3sfKRP6oTcjf2JmUmFJfeVMvXBdegxB0iVQ5eb2V10uFJUCAS8OByZdVAyVb8xXNz3GjjTgj9kLWsZTqE6kw==", + "funding": [ + { + "type": "individual", + "url": "https://paulmillr.com/funding/" + } + ], + "license": "MIT", + "dependencies": { + "anymatch": "~3.1.2", + "braces": "~3.0.2", + "glob-parent": "~5.1.2", + "is-binary-path": "~2.1.0", + "is-glob": "~4.0.1", + "normalize-path": "~3.0.0", + "readdirp": "~3.6.0" + }, + "engines": { + "node": ">= 8.10.0" + }, + "optionalDependencies": { + "fsevents": "~2.3.2" + } + }, + "node_modules/chokidar/node_modules/glob-parent": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz", + "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==", + "license": "ISC", + "dependencies": { + "is-glob": "^4.0.1" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/chownr": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/chownr/-/chownr-2.0.0.tgz", + "integrity": "sha512-bIomtDF5KGpdogkLd9VspvFzk9KfpyyGlS8YFVZl7TGPBHL5snIOnxeshwVgPteQ9b4Eydl+pVbIyE1DcvCWgQ==", + "license": "ISC", + "engines": { + "node": ">=10" + } + }, + "node_modules/ci-info": { + "version": "3.8.0", + "resolved": "https://registry.npmjs.org/ci-info/-/ci-info-3.8.0.tgz", + "integrity": "sha512-eXTggHWSooYhq49F2opQhuHWgzucfF2YgODK4e1566GQs5BIfP30B0oenwBJHfWxAs2fyPB1s7Mg949zLf61Yw==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/sibiraj-s" + } + ], + "license": "MIT", + "peer": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/class-variance-authority": { + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/class-variance-authority/-/class-variance-authority-0.7.0.tgz", + "integrity": "sha512-jFI8IQw4hczaL4ALINxqLEXQbWcNjoSkloa4IaufXCJr6QawJyw7tuRysRsrE8w2p/4gGaxKIt/hX3qz/IbD1A==", + "license": "Apache-2.0", + "dependencies": { + "clsx": "2.0.0" + }, + "funding": { + "url": "https://joebell.co.uk" + } + }, + "node_modules/cli-cursor": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/cli-cursor/-/cli-cursor-3.1.0.tgz", + "integrity": "sha512-I/zHAwsKf9FqGoXM4WWRACob9+SNukZTd94DWF57E4toouRulbCxcUh6RKUEOQlYTHJnzkPMySvPNaaSLNfLZw==", + "license": "MIT", + "peer": true, + "dependencies": { + "restore-cursor": "^3.1.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/cli-spinners": { + "version": "2.9.1", + "resolved": "https://registry.npmjs.org/cli-spinners/-/cli-spinners-2.9.1.tgz", + "integrity": "sha512-jHgecW0pxkonBJdrKsqxgRX9AcG+u/5k0Q7WPDfi8AogLAdwxEkyYYNWwZ5GvVFoFx2uiY1eNcSK00fh+1+FyQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/client-only": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/client-only/-/client-only-0.0.1.tgz", + "integrity": "sha512-IV3Ou0jSMzZrd3pZ48nLkT9DA7Ag1pnPzaiQhpW7c3RbcqqzvzzVu+L8gfqMp/8IM2MQtSiqaCxrrcfu8I8rMA==", + "license": "MIT" + }, + "node_modules/cliui": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz", + "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==", + "license": "ISC", + "peer": true, + "dependencies": { + "string-width": "^4.2.0", + "strip-ansi": "^6.0.1", + "wrap-ansi": "^7.0.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/clone": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/clone/-/clone-1.0.4.tgz", + "integrity": "sha512-JQHZ2QMW6l3aH/j6xCqQThY/9OH4D/9ls34cgkUBiEeocRTU04tHfKPBsUK1PqZCUQM7GiA0IIXJSuXHI64Kbg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.8" + } + }, + "node_modules/clone-deep": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/clone-deep/-/clone-deep-4.0.1.tgz", + "integrity": "sha512-neHB9xuzh/wk0dIHweyAXv2aPGZIVk3pLMe+/RNzINf17fe0OG96QroktYAUm7SM1PBnzTabaLboqqxDyMU+SQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "is-plain-object": "^2.0.4", + "kind-of": "^6.0.2", + "shallow-clone": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/clsx": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.0.0.tgz", + "integrity": "sha512-rQ1+kcj+ttHG0MKVGBUXwayCCF1oh39BF5COIpRzuCEv8Mwjv0XucrI2ExNTOn9IlLifGClWQcU9BrZORvtw6Q==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/cluster-key-slot": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/cluster-key-slot/-/cluster-key-slot-1.1.2.tgz", + "integrity": "sha512-RMr0FhtfXemyinomL4hrWcYJxmX6deFdCxpJzhDttxgO1+bcCnkk+9drydLVDmAMG7NE6aN/fl4F7ucU/90gAA==", + "license": "Apache-2.0", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/collapse-white-space": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/collapse-white-space/-/collapse-white-space-2.1.0.tgz", + "integrity": "sha512-loKTxY1zCOuG4j9f6EPnuyyYkf58RnhhWTvRoZEokgB+WbdXehfjFviyOVYkqzEWz1Q5kRiZdBYS5SwxbQYwzw==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "license": "MIT", + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "license": "MIT" + }, + "node_modules/color-support": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/color-support/-/color-support-1.1.3.tgz", + "integrity": "sha512-qiBjkpbMLO/HL68y+lh4q0/O1MZFj2RX6X/KmMa3+gJD3z+WwI1ZzDHysvqHGS3mP6mznPckpXmw1nI9cJjyRg==", + "license": "ISC", + "bin": { + "color-support": "bin.js" + } + }, + "node_modules/colorette": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/colorette/-/colorette-1.4.0.tgz", + "integrity": "sha512-Y2oEozpomLn7Q3HFP7dpww7AtMJplbM9lGZP6RDfHqmbeRjiwRg4n6VM6j4KLmRke85uWEI7JqF17f3pqdRA0g==", + "license": "MIT", + "peer": true + }, + "node_modules/combined-stream": { + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz", + "integrity": "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==", + "license": "MIT", + "dependencies": { + "delayed-stream": "~1.0.0" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/comma-separated-tokens": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/comma-separated-tokens/-/comma-separated-tokens-2.0.3.tgz", + "integrity": "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/command-exists": { + "version": "1.2.9", + "resolved": "https://registry.npmjs.org/command-exists/-/command-exists-1.2.9.tgz", + "integrity": "sha512-LTQ/SGc+s0Xc0Fu5WaKnR0YiygZkm9eKFvyS+fRsU7/ZWFF8ykFM6Pc9aCVf1+xasOOZpO3BAVgVrKvsqKHV7w==", + "license": "MIT", + "peer": true + }, + "node_modules/commander": { + "version": "9.5.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-9.5.0.tgz", + "integrity": "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": "^12.20.0 || >=14" + } + }, + "node_modules/commondir": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/commondir/-/commondir-1.0.1.tgz", + "integrity": "sha512-W9pAhw0ja1Edb5GVdIF1mjZw/ASI0AlShXM83UUGe2DVr5TdAPEA1OA8m/g8zWp9x6On7gqufY+FatDbC3MDQg==", + "license": "MIT", + "peer": true + }, + "node_modules/compressible": { + "version": "2.0.18", + "resolved": "https://registry.npmjs.org/compressible/-/compressible-2.0.18.tgz", + "integrity": "sha512-AF3r7P5dWxL8MxyITRMlORQNaOA2IkAFaTr4k7BUumjPtRpGDTZpl0Pb1XCO6JeDCBdp126Cgs9sMxqSjgYyRg==", + "license": "MIT", + "peer": true, + "dependencies": { + "mime-db": ">= 1.43.0 < 2" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/compression": { + "version": "1.7.4", + "resolved": "https://registry.npmjs.org/compression/-/compression-1.7.4.tgz", + "integrity": "sha512-jaSIDzP9pZVS4ZfQ+TzvtiWhdpFhE2RDHz8QJkpX9SIpLq88VueF5jJw6t+6CUQcAoA6t+x89MLrWAqpfDE8iQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "accepts": "~1.3.5", + "bytes": "3.0.0", + "compressible": "~2.0.16", + "debug": "2.6.9", + "on-headers": "~1.0.2", + "safe-buffer": "5.1.2", + "vary": "~1.1.2" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/compression/node_modules/debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "license": "MIT", + "peer": true, + "dependencies": { + "ms": "2.0.0" + } + }, + "node_modules/compression/node_modules/ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "license": "MIT", + "peer": true + }, + "node_modules/concat-map": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", + "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==", + "license": "MIT" + }, + "node_modules/connect": { + "version": "3.7.0", + "resolved": "https://registry.npmjs.org/connect/-/connect-3.7.0.tgz", + "integrity": "sha512-ZqRXc+tZukToSNmh5C2iWMSoV3X1YUcPbqEM4DkEG5tNQXrQUZCNVGGv3IuicnkMtPfGf3Xtp8WCXs295iQ1pQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "debug": "2.6.9", + "finalhandler": "1.1.2", + "parseurl": "~1.3.3", + "utils-merge": "1.0.1" + }, + "engines": { + "node": ">= 0.10.0" + } + }, + "node_modules/connect/node_modules/debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "license": "MIT", + "peer": true, + "dependencies": { + "ms": "2.0.0" + } + }, + "node_modules/connect/node_modules/ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "license": "MIT", + "peer": true + }, + "node_modules/console-control-strings": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/console-control-strings/-/console-control-strings-1.1.0.tgz", + "integrity": "sha512-ty/fTekppD2fIwRvnZAVdeOiGd1c7YXEixbgJTNzqcxJWKQnjJ/V1bNEEE6hygpM3WjwHFUVK6HTjWSzV4a8sQ==", + "license": "ISC" + }, + "node_modules/convert-source-map": { + "version": "1.9.0", + "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-1.9.0.tgz", + "integrity": "sha512-ASFBup0Mz1uyiIjANan1jzLQami9z1PoYSZCiiYW2FczPbenXc45FZdBZLzOT+r6+iciuEModtmCti+hjaAk0A==", + "license": "MIT", + "peer": true + }, + "node_modules/cookie": { + "version": "0.5.0", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.5.0.tgz", + "integrity": "sha512-YZ3GUyn/o8gfKJlnlX7g7xq4gyO6OSuhGPKaaGssGB2qgDUS0gPgtTvoyZLTt9Ab6dC4hfc9dV5arkvc/OCmrw==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/copy-anything": { + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/copy-anything/-/copy-anything-3.0.5.tgz", + "integrity": "sha512-yCEafptTtb4bk7GLEQoM8KVJpxAfdBJYaXyzQEgQQQgYrZiDp8SJmGKlYza6CYjEDNstAdNdKA3UuoULlEbS6w==", + "license": "MIT", + "dependencies": { + "is-what": "^4.1.8" + }, + "engines": { + "node": ">=12.13" + }, + "funding": { + "url": "https://github.com/sponsors/mesqueeb" + } + }, + "node_modules/core-js-compat": { + "version": "3.32.2", + "resolved": "https://registry.npmjs.org/core-js-compat/-/core-js-compat-3.32.2.tgz", + "integrity": "sha512-+GjlguTDINOijtVRUxrQOv3kfu9rl+qPNdX2LTbJ/ZyVTuxK+ksVSAGX1nHstu4hrv1En/uPTtWgq2gI5wt4AQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "browserslist": "^4.21.10" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/core-js" + } + }, + "node_modules/core-util-is": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz", + "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==", + "license": "MIT", + "peer": true + }, + "node_modules/cosmiconfig": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/cosmiconfig/-/cosmiconfig-5.2.1.tgz", + "integrity": "sha512-H65gsXo1SKjf8zmrJ67eJk8aIRKV5ff2D4uKZIBZShbhGSpEmsQOPW/SKMKYhSTrqR7ufy6RP69rPogdaPh/kA==", + "license": "MIT", + "peer": true, + "dependencies": { + "import-fresh": "^2.0.0", + "is-directory": "^0.3.1", + "js-yaml": "^3.13.1", + "parse-json": "^4.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/cosmiconfig/node_modules/argparse": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "license": "MIT", + "peer": true, + "dependencies": { + "sprintf-js": "~1.0.2" + } + }, + "node_modules/cosmiconfig/node_modules/import-fresh": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-2.0.0.tgz", + "integrity": "sha512-eZ5H8rcgYazHbKC3PG4ClHNykCSxtAhxSSEM+2mb+7evD2CKF5V7c0dNum7AdpDh0ZdICwZY9sRSn8f+KH96sg==", + "license": "MIT", + "peer": true, + "dependencies": { + "caller-path": "^2.0.0", + "resolve-from": "^3.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/cosmiconfig/node_modules/js-yaml": { + "version": "3.14.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz", + "integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==", + "license": "MIT", + "peer": true, + "dependencies": { + "argparse": "^1.0.7", + "esprima": "^4.0.0" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/cosmiconfig/node_modules/resolve-from": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-3.0.0.tgz", + "integrity": "sha512-GnlH6vxLymXJNMBo7XP1fJIzBFbdYt49CuTwmB/6N53t+kMPRMFKz783LlQ4tv28XoQfMWinAJX6WCGf2IlaIw==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/create-require": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/create-require/-/create-require-1.1.1.tgz", + "integrity": "sha512-dcKFX3jn0MpIaXjisoRvexIJVEKzaq7z2rZKxf+MSr9TkdmHmsU4m2lcLojrj/FHl8mk5VxMmYA+ftRkP/3oKQ==", + "license": "MIT" + }, + "node_modules/cross-spawn": { + "version": "7.0.3", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.3.tgz", + "integrity": "sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w==", + "license": "MIT", + "dependencies": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/cssesc": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/cssesc/-/cssesc-3.0.0.tgz", + "integrity": "sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==", + "license": "MIT", + "bin": { + "cssesc": "bin/cssesc" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/csstype": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.1.2.tgz", + "integrity": "sha512-I7K1Uu0MBPzaFKg4nI5Q7Vs2t+3gWWW648spaF+Rg7pI9ds18Ugn+lvg4SHczUdKlHI5LWBXyqfS8+DufyBsgQ==", + "license": "MIT" + }, + "node_modules/d3-array": { + "version": "2.12.1", + "resolved": "https://registry.npmjs.org/d3-array/-/d3-array-2.12.1.tgz", + "integrity": "sha512-B0ErZK/66mHtEsR1TkPEEkwdy+WDesimkM5gpZr5Dsg54BiTA5RXtYW5qTLIAcekaS9xfZrzBLF/OAkB3Qn1YQ==", + "license": "BSD-3-Clause", + "dependencies": { + "internmap": "^1.0.0" + } + }, + "node_modules/d3-color": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-color/-/d3-color-3.1.0.tgz", + "integrity": "sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==", + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-delaunay": { + "version": "5.3.0", + "resolved": "https://registry.npmjs.org/d3-delaunay/-/d3-delaunay-5.3.0.tgz", + "integrity": "sha512-amALSrOllWVLaHTnDLHwMIiz0d1bBu9gZXd1FiLfXf8sHcX9jrcj81TVZOqD4UX7MgBZZ07c8GxzEgBpJqc74w==", + "license": "ISC", + "dependencies": { + "delaunator": "4" + } + }, + "node_modules/d3-ease": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz", + "integrity": "sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==", + "license": "BSD-3-Clause", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-format": { + "version": "1.4.5", + "resolved": "https://registry.npmjs.org/d3-format/-/d3-format-1.4.5.tgz", + "integrity": "sha512-J0piedu6Z8iB6TbIGfZgDzfXxUFN3qQRMofy2oPdXzQibYGqPB/9iMcxr/TGalU+2RsyDO+U4f33id8tbnSRMQ==", + "license": "BSD-3-Clause" + }, + "node_modules/d3-interpolate": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/d3-interpolate/-/d3-interpolate-2.0.1.tgz", + "integrity": "sha512-c5UhwwTs/yybcmTpAVqwSFl6vrQ8JZJoT5F7xNFK9pymv5C0Ymcc9/LIJHtYIggg/yS9YHw8i8O8tgb9pupjeQ==", + "license": "BSD-3-Clause", + "dependencies": { + "d3-color": "1 - 2" + } + }, + "node_modules/d3-interpolate/node_modules/d3-color": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/d3-color/-/d3-color-2.0.0.tgz", + "integrity": "sha512-SPXi0TSKPD4g9tw0NMZFnR95XVgUZiBH+uUTqQuDu1OsE2zomHU7ho0FISciaPvosimixwHFl3WHLGabv6dDgQ==", + "license": "BSD-3-Clause" + }, + "node_modules/d3-path": { + "version": "1.0.9", + "resolved": "https://registry.npmjs.org/d3-path/-/d3-path-1.0.9.tgz", + "integrity": "sha512-VLaYcn81dtHVTjEHd8B+pbe9yHWpXKZUC87PzoFmsFrJqgFwDe/qxfp5MlfsfM1V5E/iVt0MmEbWQ7FVIXh/bg==", + "license": "BSD-3-Clause" + }, + "node_modules/d3-scale": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/d3-scale/-/d3-scale-3.3.0.tgz", + "integrity": "sha512-1JGp44NQCt5d1g+Yy+GeOnZP7xHo0ii8zsQp6PGzd+C1/dl0KGsp9A7Mxwp+1D1o4unbTTxVdU/ZOIEBoeZPbQ==", + "license": "BSD-3-Clause", + "dependencies": { + "d3-array": "^2.3.0", + "d3-format": "1 - 2", + "d3-interpolate": "1.2.0 - 2", + "d3-time": "^2.1.1", + "d3-time-format": "2 - 3" + } + }, + "node_modules/d3-scale-chromatic": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/d3-scale-chromatic/-/d3-scale-chromatic-2.0.0.tgz", + "integrity": "sha512-LLqy7dJSL8yDy7NRmf6xSlsFZ6zYvJ4BcWFE4zBrOPnQERv9zj24ohnXKRbyi9YHnYV+HN1oEO3iFK971/gkzA==", + "license": "BSD-3-Clause", + "dependencies": { + "d3-color": "1 - 2", + "d3-interpolate": "1 - 2" + } + }, + "node_modules/d3-scale-chromatic/node_modules/d3-color": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/d3-color/-/d3-color-2.0.0.tgz", + "integrity": "sha512-SPXi0TSKPD4g9tw0NMZFnR95XVgUZiBH+uUTqQuDu1OsE2zomHU7ho0FISciaPvosimixwHFl3WHLGabv6dDgQ==", + "license": "BSD-3-Clause" + }, + "node_modules/d3-scale/node_modules/d3-time": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/d3-time/-/d3-time-2.1.1.tgz", + "integrity": "sha512-/eIQe/eR4kCQwq7yxi7z4c6qEXf2IYGcjoWB5OOQy4Tq9Uv39/947qlDcN2TLkiTzQWzvnsuYPB9TrWaNfipKQ==", + "license": "BSD-3-Clause", + "dependencies": { + "d3-array": "2" + } + }, + "node_modules/d3-shape": { + "version": "1.3.7", + "resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-1.3.7.tgz", + "integrity": "sha512-EUkvKjqPFUAZyOlhY5gzCxCeI0Aep04LwIRpsZ/mLFelJiUfnK56jo5JMDSE7yyP2kLSb6LtF+S5chMk7uqPqw==", + "license": "BSD-3-Clause", + "dependencies": { + "d3-path": "1" + } + }, + "node_modules/d3-time": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/d3-time/-/d3-time-1.1.0.tgz", + "integrity": "sha512-Xh0isrZ5rPYYdqhAVk8VLnMEidhz5aP7htAADH6MfzgmmicPkTo8LhkLxci61/lCB7n7UmE3bN0leRt+qvkLxA==", + "license": "BSD-3-Clause" + }, + "node_modules/d3-time-format": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-time-format/-/d3-time-format-3.0.0.tgz", + "integrity": "sha512-UXJh6EKsHBTjopVqZBhFysQcoXSv/5yLONZvkQ5Kk3qbwiUYkdX17Xa1PT6U1ZWXGGfB1ey5L8dKMlFq2DO0Ag==", + "license": "BSD-3-Clause", + "dependencies": { + "d3-time": "1 - 2" + } + }, + "node_modules/d3-timer": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-timer/-/d3-timer-3.0.1.tgz", + "integrity": "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==", + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/damerau-levenshtein": { + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/damerau-levenshtein/-/damerau-levenshtein-1.0.8.tgz", + "integrity": "sha512-sdQSFB7+llfUcQHUQO3+B8ERRj0Oa4w9POWMI/puGtuf7gFywGmkaLCElnudfTiKZV+NvHqL0ifzdrI8Ro7ESA==", + "dev": true, + "license": "BSD-2-Clause" + }, + "node_modules/dayjs": { + "version": "1.11.9", + "resolved": "https://registry.npmjs.org/dayjs/-/dayjs-1.11.9.tgz", + "integrity": "sha512-QvzAURSbQ0pKdIye2txOzNaHmxtUBXerpY0FJsFXUMKbIZeFm5ht1LS/jFsrncjnmtv8HsG0W2g6c0zUjZWmpA==", + "license": "MIT", + "peer": true + }, + "node_modules/debounce": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/debounce/-/debounce-1.2.1.tgz", + "integrity": "sha512-XRRe6Glud4rd/ZGQfiV1ruXSfbvfJedlV9Y6zOlP+2K04vBYiJEte6stfFkCP03aMnY5tsipamumUjL14fofug==", + "license": "MIT", + "peer": true + }, + "node_modules/debug": { + "version": "4.3.4", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.4.tgz", + "integrity": "sha512-PRWFHuSU3eDtQJPvnNY7Jcket1j0t5OuOsFzPPzsekD52Zl8qUfFIPEiswXqIvHWGVHOgX+7G/vCNNhehwxfkQ==", + "license": "MIT", + "dependencies": { + "ms": "2.1.2" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/decamelize": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/decamelize/-/decamelize-1.2.0.tgz", + "integrity": "sha512-z2S+W9X73hAUUki+N+9Za2lBlun89zigOyGrsax+KUQ6wKW4ZoWpEYBkGhQjwAjjDCkWxhY0VKEhk8wzY7F5cA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/decimal.js-light": { + "version": "2.5.1", + "resolved": "https://registry.npmjs.org/decimal.js-light/-/decimal.js-light-2.5.1.tgz", + "integrity": "sha512-qIMFpTMZmny+MMIitAB6D7iVPEorVw6YQRWkvarTkT4tBeSLLiHzcwj6q0MmYSFCiVpiqPJTJEYIrpcPzVEIvg==", + "license": "MIT" + }, + "node_modules/decode-named-character-reference": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.0.2.tgz", + "integrity": "sha512-O8x12RzrUF8xyVcY0KJowWsmaJxQbmy0/EtnNtHRpsOcT7dFk5W598coHqBVpmWo1oQQfsCqfCmkZN5DJrZVdg==", + "license": "MIT", + "dependencies": { + "character-entities": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/deep-is": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/deep-is/-/deep-is-0.1.4.tgz", + "integrity": "sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/deepmerge": { + "version": "4.3.1", + "resolved": "https://registry.npmjs.org/deepmerge/-/deepmerge-4.3.1.tgz", + "integrity": "sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/defaults": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/defaults/-/defaults-1.0.4.tgz", + "integrity": "sha512-eFuaLoy/Rxalv2kr+lqMlUnrDWV+3j4pljOIJgLIhI058IQfWJ7vXhyEIHu+HtC738klGALYxOKDO0bQP3tg8A==", + "license": "MIT", + "peer": true, + "dependencies": { + "clone": "^1.0.2" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/define-properties": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/define-properties/-/define-properties-1.2.0.tgz", + "integrity": "sha512-xvqAVKGfT1+UAvPwKTVw/njhdQ8ZhXK4lI0bCIuCMrp2up9nPnaDftrLtmpTazqd1o+UY4zgzU+avtMbDP+ldA==", + "dev": true, + "license": "MIT", + "dependencies": { + "has-property-descriptors": "^1.0.0", + "object-keys": "^1.1.1" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/delaunator": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/delaunator/-/delaunator-4.0.1.tgz", + "integrity": "sha512-WNPWi1IRKZfCt/qIDMfERkDp93+iZEmOxN2yy4Jg+Xhv8SLk2UTqqbe1sfiipn0and9QrE914/ihdx82Y/Giag==", + "license": "ISC" + }, + "node_modules/delayed-stream": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz", + "integrity": "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==", + "license": "MIT", + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/delegates": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/delegates/-/delegates-1.0.0.tgz", + "integrity": "sha512-bd2L678uiWATM6m5Z1VzNCErI3jiGzt6HGY8OVICs40JQq/HALfbyNJmp0UDakEY4pMMaN0Ly5om/B1VI/+xfQ==", + "license": "MIT" + }, + "node_modules/denodeify": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/denodeify/-/denodeify-1.2.1.tgz", + "integrity": "sha512-KNTihKNmQENUZeKu5fzfpzRqR5S2VMp4gl9RFHiWzj9DfvYQPMJ6XHKNaQxaGCXwPk6y9yme3aUoaiAe+KX+vg==", + "license": "MIT", + "peer": true + }, + "node_modules/denque": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/denque/-/denque-2.1.0.tgz", + "integrity": "sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw==", + "license": "Apache-2.0", + "engines": { + "node": ">=0.10" + } + }, + "node_modules/depd": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz", + "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/deprecated-react-native-prop-types": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/deprecated-react-native-prop-types/-/deprecated-react-native-prop-types-4.1.0.tgz", + "integrity": "sha512-WfepZHmRbbdTvhcolb8aOKEvQdcmTMn5tKLbqbXmkBvjFjRVWAYqsXk/DBsV8TZxws8SdGHLuHaJrHSQUPRdfw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@react-native/normalize-colors": "*", + "invariant": "*", + "prop-types": "*" + } + }, + "node_modules/dequal": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz", + "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/destroy": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/destroy/-/destroy-1.2.0.tgz", + "integrity": "sha512-2sJGJTaXIIaR1w4iJSNoN0hnMY7Gpc/n8D4qSCJw8QqFWXf7cuAgnEHxBpweaVcPevC2l3KpjYCx3NypQQgaJg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.8", + "npm": "1.2.8000 || >= 1.4.16" + } + }, + "node_modules/detect-libc": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.0.2.tgz", + "integrity": "sha512-UX6sGumvvqSaXgdKGUsgZWqcUyIXZ/vZTrlRT/iobiKhGL0zL4d3osHj3uqllWJK+i+sixDS/3COVEOFbupFyw==", + "license": "Apache-2.0", + "engines": { + "node": ">=8" + } + }, + "node_modules/detect-node-es": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/detect-node-es/-/detect-node-es-1.1.0.tgz", + "integrity": "sha512-ypdmJU/TbBby2Dxibuv7ZLW3Bs1QEmM7nHjEANfohJLvE0XVujisn1qPJcZxg+qDucsr+bP6fLD1rPS3AhJ7EQ==", + "license": "MIT" + }, + "node_modules/devlop": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/devlop/-/devlop-1.1.0.tgz", + "integrity": "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==", + "license": "MIT", + "dependencies": { + "dequal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/didyoumean": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/didyoumean/-/didyoumean-1.2.2.tgz", + "integrity": "sha512-gxtyfqMg7GKyhQmb056K7M3xszy/myH8w+B4RT+QXBQsvAOdc3XymqDDPHx1BgPgsdAA5SIifona89YtRATDzw==", + "license": "Apache-2.0" + }, + "node_modules/diff": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/diff/-/diff-4.0.2.tgz", + "integrity": "sha512-58lmxKSA4BNyLz+HHMUzlOEpg09FV+ev6ZMe3vJihgdxzgcwZ8VoEEPmALCZG9LmqfVoNMMKpttIYTVG6uDY7A==", + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.3.1" + } + }, + "node_modules/dir-glob": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz", + "integrity": "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==", + "dev": true, + "license": "MIT", + "dependencies": { + "path-type": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/dlv": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/dlv/-/dlv-1.1.3.tgz", + "integrity": "sha512-+HlytyjlPKnIG8XuRG8WvmBP8xs8P71y+SKKS6ZXWoEgLuePxtDoUEiH7WkdePWrQ5JBpE6aoVqfZfJUQkjXwA==", + "license": "MIT" + }, + "node_modules/doctrine": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/doctrine/-/doctrine-3.0.0.tgz", + "integrity": "sha512-yS+Q5i3hBf7GBkd4KG8a7eBNNWNGLTaEwwYWUijIYM7zrlYDM0BFXHjjPWlWZ1Rg7UaddZeIDmi9jF3HmqiQ2w==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "esutils": "^2.0.2" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/dom-helpers": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/dom-helpers/-/dom-helpers-5.2.1.tgz", + "integrity": "sha512-nRCa7CK3VTrM2NmGkIy4cbK7IZlgBE/PYMn55rrXefr5xXDP0LdtfPnblFDoVdcAfslJ7or6iqAUnx0CCGIWQA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.8.7", + "csstype": "^3.0.2" + } + }, + "node_modules/ee-first": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz", + "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==", + "license": "MIT", + "peer": true + }, + "node_modules/electron-to-chromium": { + "version": "1.4.493", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.493.tgz", + "integrity": "sha512-T1k9mhYPdjnmS4VAz4J1oKVn6/M6LxoqQEVtYRL0swJVj73bA2NzqF0HjwxGsW3zL3ir0oPmLfd7lyi/RYzreg==", + "license": "ISC" + }, + "node_modules/emoji-regex": { + "version": "9.2.2", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz", + "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==", + "dev": true, + "license": "MIT" + }, + "node_modules/encodeurl": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-1.0.2.tgz", + "integrity": "sha512-TPJXq8JqFaVYm2CWmPvnP2Iyo4ZSM7/QKcSmuMLDObfpH5fi7RUGmd/rTDf+rut/saiDiQEeVTNgAmJEdAOx0w==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/enhanced-resolve": { + "version": "5.15.0", + "resolved": "https://registry.npmjs.org/enhanced-resolve/-/enhanced-resolve-5.15.0.tgz", + "integrity": "sha512-LXYT42KJ7lpIKECr2mAXIaMldcNCh/7E0KBKOu4KSfkHmP+mZmSs+8V5gBAqisWBy0OO4W5Oyys0GO1Y8KtdKg==", + "dev": true, + "license": "MIT", + "dependencies": { + "graceful-fs": "^4.2.4", + "tapable": "^2.2.0" + }, + "engines": { + "node": ">=10.13.0" + } + }, + "node_modules/envinfo": { + "version": "7.10.0", + "resolved": "https://registry.npmjs.org/envinfo/-/envinfo-7.10.0.tgz", + "integrity": "sha512-ZtUjZO6l5mwTHvc1L9+1q5p/R3wTopcfqMW8r5t8SJSKqeVI/LtajORwRFEKpEFuekjD0VBjwu1HMxL4UalIRw==", + "license": "MIT", + "peer": true, + "bin": { + "envinfo": "dist/cli.js" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/error-ex": { + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/error-ex/-/error-ex-1.3.2.tgz", + "integrity": "sha512-7dFHNmqeFSEt2ZBsCriorKnn3Z2pj+fd9kmI6QoWw4//DL+icEBfc0U7qJCisqrTsKTjw4fNFy2pW9OqStD84g==", + "license": "MIT", + "peer": true, + "dependencies": { + "is-arrayish": "^0.2.1" + } + }, + "node_modules/error-stack-parser": { + "version": "2.1.4", + "resolved": "https://registry.npmjs.org/error-stack-parser/-/error-stack-parser-2.1.4.tgz", + "integrity": "sha512-Sk5V6wVazPhq5MhpO+AUxJn5x7XSXGl1R93Vn7i+zS15KDVxQijejNCrz8340/2bgLBjR9GtEG8ZVKONDjcqGQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "stackframe": "^1.3.4" + } + }, + "node_modules/errorhandler": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/errorhandler/-/errorhandler-1.5.1.tgz", + "integrity": "sha512-rcOwbfvP1WTViVoUjcfZicVzjhjTuhSMntHh6mW3IrEiyE6mJyXvsToJUJGlGlw/2xU9P5whlWNGlIDVeCiT4A==", + "license": "MIT", + "peer": true, + "dependencies": { + "accepts": "~1.3.7", + "escape-html": "~1.0.3" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/es-abstract": { + "version": "1.22.1", + "resolved": "https://registry.npmjs.org/es-abstract/-/es-abstract-1.22.1.tgz", + "integrity": "sha512-ioRRcXMO6OFyRpyzV3kE1IIBd4WG5/kltnzdxSCqoP8CMGs/Li+M1uF5o7lOkZVFjDs+NLesthnF66Pg/0q0Lw==", + "dev": true, + "license": "MIT", + "dependencies": { + "array-buffer-byte-length": "^1.0.0", + "arraybuffer.prototype.slice": "^1.0.1", + "available-typed-arrays": "^1.0.5", + "call-bind": "^1.0.2", + "es-set-tostringtag": "^2.0.1", + "es-to-primitive": "^1.2.1", + "function.prototype.name": "^1.1.5", + "get-intrinsic": "^1.2.1", + "get-symbol-description": "^1.0.0", + "globalthis": "^1.0.3", + "gopd": "^1.0.1", + "has": "^1.0.3", + "has-property-descriptors": "^1.0.0", + "has-proto": "^1.0.1", + "has-symbols": "^1.0.3", + "internal-slot": "^1.0.5", + "is-array-buffer": "^3.0.2", + "is-callable": "^1.2.7", + "is-negative-zero": "^2.0.2", + "is-regex": "^1.1.4", + "is-shared-array-buffer": "^1.0.2", + "is-string": "^1.0.7", + "is-typed-array": "^1.1.10", + "is-weakref": "^1.0.2", + "object-inspect": "^1.12.3", + "object-keys": "^1.1.1", + "object.assign": "^4.1.4", + "regexp.prototype.flags": "^1.5.0", + "safe-array-concat": "^1.0.0", + "safe-regex-test": "^1.0.0", + "string.prototype.trim": "^1.2.7", + "string.prototype.trimend": "^1.0.6", + "string.prototype.trimstart": "^1.0.6", + "typed-array-buffer": "^1.0.0", + "typed-array-byte-length": "^1.0.0", + "typed-array-byte-offset": "^1.0.0", + "typed-array-length": "^1.0.4", + "unbox-primitive": "^1.0.2", + "which-typed-array": "^1.1.10" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/es-iterator-helpers": { + "version": "1.0.13", + "resolved": "https://registry.npmjs.org/es-iterator-helpers/-/es-iterator-helpers-1.0.13.tgz", + "integrity": "sha512-LK3VGwzvaPWobO8xzXXGRUOGw8Dcjyfk62CsY/wfHN75CwsJPbuypOYJxK6g5RyEL8YDjIWcl6jgd8foO6mmrA==", + "dev": true, + "license": "MIT", + "dependencies": { + "asynciterator.prototype": "^1.0.0", + "call-bind": "^1.0.2", + "define-properties": "^1.2.0", + "es-abstract": "^1.21.3", + "es-set-tostringtag": "^2.0.1", + "function-bind": "^1.1.1", + "get-intrinsic": "^1.2.1", + "globalthis": "^1.0.3", + "has-property-descriptors": "^1.0.0", + "has-proto": "^1.0.1", + "has-symbols": "^1.0.3", + "internal-slot": "^1.0.5", + "iterator.prototype": "^1.1.0", + "safe-array-concat": "^1.0.0" + } + }, + "node_modules/es-set-tostringtag": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/es-set-tostringtag/-/es-set-tostringtag-2.0.1.tgz", + "integrity": "sha512-g3OMbtlwY3QewlqAiMLI47KywjWZoEytKr8pf6iTC8uJq5bIAH52Z9pnQ8pVL6whrCto53JZDuUIsifGeLorTg==", + "dev": true, + "license": "MIT", + "dependencies": { + "get-intrinsic": "^1.1.3", + "has": "^1.0.3", + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/es-shim-unscopables": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/es-shim-unscopables/-/es-shim-unscopables-1.0.0.tgz", + "integrity": "sha512-Jm6GPcCdC30eMLbZ2x8z2WuRwAws3zTBBKuusffYVUrNj/GVSUAZ+xKMaUpfNDR5IbyNA5LJbaecoUVbmUcB1w==", + "dev": true, + "license": "MIT", + "dependencies": { + "has": "^1.0.3" + } + }, + "node_modules/es-to-primitive": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/es-to-primitive/-/es-to-primitive-1.2.1.tgz", + "integrity": "sha512-QCOllgZJtaUo9miYBcLChTUaHNjJF3PYs1VidD7AwiEj1kYxKeQTctLAezAOH5ZKRH0g2IgPn6KwB4IT8iRpvA==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-callable": "^1.1.4", + "is-date-object": "^1.0.1", + "is-symbol": "^1.0.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/esast-util-from-estree": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/esast-util-from-estree/-/esast-util-from-estree-2.0.0.tgz", + "integrity": "sha512-4CyanoAudUSBAn5K13H4JhsMH6L9ZP7XbLVe/dKybkxMO7eDyLsT8UHl9TRNrU2Gr9nz+FovfSIjuXWJ81uVwQ==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "devlop": "^1.0.0", + "estree-util-visit": "^2.0.0", + "unist-util-position-from-estree": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/esast-util-from-js": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/esast-util-from-js/-/esast-util-from-js-2.0.1.tgz", + "integrity": "sha512-8Ja+rNJ0Lt56Pcf3TAmpBZjmx8ZcK5Ts4cAzIOjsjevg9oSXJnl6SUQ2EevU8tv3h6ZLWmoKL5H4fgWvdvfETw==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "acorn": "^8.0.0", + "esast-util-from-estree": "^2.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/esbuild": { + "version": "0.25.5", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.5.tgz", + "integrity": "sha512-P8OtKZRv/5J5hhz0cUAdu/cLuPIKXpQl1R9pZtvmHWQvrAUVd0UNIPT4IB4W3rNOqVO0rlqHmCIbSwxh/c9yUQ==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.25.5", + "@esbuild/android-arm": "0.25.5", + "@esbuild/android-arm64": "0.25.5", + "@esbuild/android-x64": "0.25.5", + "@esbuild/darwin-arm64": "0.25.5", + "@esbuild/darwin-x64": "0.25.5", + "@esbuild/freebsd-arm64": "0.25.5", + "@esbuild/freebsd-x64": "0.25.5", + "@esbuild/linux-arm": "0.25.5", + "@esbuild/linux-arm64": "0.25.5", + "@esbuild/linux-ia32": "0.25.5", + "@esbuild/linux-loong64": "0.25.5", + "@esbuild/linux-mips64el": "0.25.5", + "@esbuild/linux-ppc64": "0.25.5", + "@esbuild/linux-riscv64": "0.25.5", + "@esbuild/linux-s390x": "0.25.5", + "@esbuild/linux-x64": "0.25.5", + "@esbuild/netbsd-arm64": "0.25.5", + "@esbuild/netbsd-x64": "0.25.5", + "@esbuild/openbsd-arm64": "0.25.5", + "@esbuild/openbsd-x64": "0.25.5", + "@esbuild/sunos-x64": "0.25.5", + "@esbuild/win32-arm64": "0.25.5", + "@esbuild/win32-ia32": "0.25.5", + "@esbuild/win32-x64": "0.25.5" + } + }, + "node_modules/escalade": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.1.1.tgz", + "integrity": "sha512-k0er2gUkLf8O0zKJiAhmkTnJlTvINGv7ygDNPbeIsX/TJjGJZHuh9B2UxbsaEkmlEo9MfhrSzmhIlhRlI2GXnw==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/escape-html": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz", + "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==", + "license": "MIT", + "peer": true + }, + "node_modules/escape-string-regexp": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz", + "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/eslint": { + "version": "8.47.0", + "resolved": "https://registry.npmjs.org/eslint/-/eslint-8.47.0.tgz", + "integrity": "sha512-spUQWrdPt+pRVP1TTJLmfRNJJHHZryFmptzcafwSvHsceV81djHOdnEeDmkdotZyLNjDhrOasNK8nikkoG1O8Q==", + "deprecated": "This version is no longer supported. Please see https://eslint.org/version-support for other options.", + "dev": true, + "license": "MIT", + "dependencies": { + "@eslint-community/eslint-utils": "^4.2.0", + "@eslint-community/regexpp": "^4.6.1", + "@eslint/eslintrc": "^2.1.2", + "@eslint/js": "^8.47.0", + "@humanwhocodes/config-array": "^0.11.10", + "@humanwhocodes/module-importer": "^1.0.1", + "@nodelib/fs.walk": "^1.2.8", + "ajv": "^6.12.4", + "chalk": "^4.0.0", + "cross-spawn": "^7.0.2", + "debug": "^4.3.2", + "doctrine": "^3.0.0", + "escape-string-regexp": "^4.0.0", + "eslint-scope": "^7.2.2", + "eslint-visitor-keys": "^3.4.3", + "espree": "^9.6.1", + "esquery": "^1.4.2", + "esutils": "^2.0.2", + "fast-deep-equal": "^3.1.3", + "file-entry-cache": "^6.0.1", + "find-up": "^5.0.0", + "glob-parent": "^6.0.2", + "globals": "^13.19.0", + "graphemer": "^1.4.0", + "ignore": "^5.2.0", + "imurmurhash": "^0.1.4", + "is-glob": "^4.0.0", + "is-path-inside": "^3.0.3", + "js-yaml": "^4.1.0", + "json-stable-stringify-without-jsonify": "^1.0.1", + "levn": "^0.4.1", + "lodash.merge": "^4.6.2", + "minimatch": "^3.1.2", + "natural-compare": "^1.4.0", + "optionator": "^0.9.3", + "strip-ansi": "^6.0.1", + "text-table": "^0.2.0" + }, + "bin": { + "eslint": "bin/eslint.js" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/eslint-config-next": { + "version": "13.4.16", + "resolved": "https://registry.npmjs.org/eslint-config-next/-/eslint-config-next-13.4.16.tgz", + "integrity": "sha512-Of73d/FiaGf0GLCxxTGdh4rW8bRDvsqypylefkshE/uDDpQr8ifVQsD4UiB99rhegks7nJGkYtUnR3dC7kfFlw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@next/eslint-plugin-next": "13.4.16", + "@rushstack/eslint-patch": "^1.1.3", + "@typescript-eslint/parser": "^5.4.2 || ^6.0.0", + "eslint-import-resolver-node": "^0.3.6", + "eslint-import-resolver-typescript": "^3.5.2", + "eslint-plugin-import": "^2.26.0", + "eslint-plugin-jsx-a11y": "^6.5.1", + "eslint-plugin-react": "^7.31.7", + "eslint-plugin-react-hooks": "5.0.0-canary-7118f5dd7-20230705" + }, + "peerDependencies": { + "eslint": "^7.23.0 || ^8.0.0", + "typescript": ">=3.3.1" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, + "node_modules/eslint-import-resolver-node": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/eslint-import-resolver-node/-/eslint-import-resolver-node-0.3.9.tgz", + "integrity": "sha512-WFj2isz22JahUv+B788TlO3N6zL3nNJGU8CcZbPZvVEkBPaJdCV4vy5wyghty5ROFbCRnm132v8BScu5/1BQ8g==", + "dev": true, + "license": "MIT", + "dependencies": { + "debug": "^3.2.7", + "is-core-module": "^2.13.0", + "resolve": "^1.22.4" + } + }, + "node_modules/eslint-import-resolver-node/node_modules/debug": { + "version": "3.2.7", + "resolved": "https://registry.npmjs.org/debug/-/debug-3.2.7.tgz", + "integrity": "sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ms": "^2.1.1" + } + }, + "node_modules/eslint-import-resolver-typescript": { + "version": "3.6.0", + "resolved": "https://registry.npmjs.org/eslint-import-resolver-typescript/-/eslint-import-resolver-typescript-3.6.0.tgz", + "integrity": "sha512-QTHR9ddNnn35RTxlaEnx2gCxqFlF2SEN0SE2d17SqwyM7YOSI2GHWRYp5BiRkObTUNYPupC/3Fq2a0PpT+EKpg==", + "dev": true, + "license": "ISC", + "dependencies": { + "debug": "^4.3.4", + "enhanced-resolve": "^5.12.0", + "eslint-module-utils": "^2.7.4", + "fast-glob": "^3.3.1", + "get-tsconfig": "^4.5.0", + "is-core-module": "^2.11.0", + "is-glob": "^4.0.3" + }, + "engines": { + "node": "^14.18.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/unts/projects/eslint-import-resolver-ts" + }, + "peerDependencies": { + "eslint": "*", + "eslint-plugin-import": "*" + } + }, + "node_modules/eslint-module-utils": { + "version": "2.8.0", + "resolved": "https://registry.npmjs.org/eslint-module-utils/-/eslint-module-utils-2.8.0.tgz", + "integrity": "sha512-aWajIYfsqCKRDgUfjEXNN/JlrzauMuSEy5sbd7WXbtW3EH6A6MpwEh42c7qD+MqQo9QMJ6fWLAeIJynx0g6OAw==", + "dev": true, + "license": "MIT", + "dependencies": { + "debug": "^3.2.7" + }, + "engines": { + "node": ">=4" + }, + "peerDependenciesMeta": { + "eslint": { + "optional": true + } + } + }, + "node_modules/eslint-module-utils/node_modules/debug": { + "version": "3.2.7", + "resolved": "https://registry.npmjs.org/debug/-/debug-3.2.7.tgz", + "integrity": "sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ms": "^2.1.1" + } + }, + "node_modules/eslint-plugin-import": { + "version": "2.28.0", + "resolved": "https://registry.npmjs.org/eslint-plugin-import/-/eslint-plugin-import-2.28.0.tgz", + "integrity": "sha512-B8s/n+ZluN7sxj9eUf7/pRFERX0r5bnFA2dCaLHy2ZeaQEAz0k+ZZkFWRFHJAqxfxQDx6KLv9LeIki7cFdwW+Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "array-includes": "^3.1.6", + "array.prototype.findlastindex": "^1.2.2", + "array.prototype.flat": "^1.3.1", + "array.prototype.flatmap": "^1.3.1", + "debug": "^3.2.7", + "doctrine": "^2.1.0", + "eslint-import-resolver-node": "^0.3.7", + "eslint-module-utils": "^2.8.0", + "has": "^1.0.3", + "is-core-module": "^2.12.1", + "is-glob": "^4.0.3", + "minimatch": "^3.1.2", + "object.fromentries": "^2.0.6", + "object.groupby": "^1.0.0", + "object.values": "^1.1.6", + "resolve": "^1.22.3", + "semver": "^6.3.1", + "tsconfig-paths": "^3.14.2" + }, + "engines": { + "node": ">=4" + }, + "peerDependencies": { + "eslint": "^2 || ^3 || ^4 || ^5 || ^6 || ^7.2.0 || ^8" + } + }, + "node_modules/eslint-plugin-import/node_modules/debug": { + "version": "3.2.7", + "resolved": "https://registry.npmjs.org/debug/-/debug-3.2.7.tgz", + "integrity": "sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ms": "^2.1.1" + } + }, + "node_modules/eslint-plugin-import/node_modules/doctrine": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/doctrine/-/doctrine-2.1.0.tgz", + "integrity": "sha512-35mSku4ZXK0vfCuHEDAwt55dg2jNajHZ1odvF+8SSr82EsZY4QmXfuWso8oEd8zRhVObSN18aM0CjSdoBX7zIw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "esutils": "^2.0.2" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/eslint-plugin-import/node_modules/semver": { + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", + "dev": true, + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/eslint-plugin-jsx-a11y": { + "version": "6.7.1", + "resolved": "https://registry.npmjs.org/eslint-plugin-jsx-a11y/-/eslint-plugin-jsx-a11y-6.7.1.tgz", + "integrity": "sha512-63Bog4iIethyo8smBklORknVjB0T2dwB8Mr/hIC+fBS0uyHdYYpzM/Ed+YC8VxTjlXHEWFOdmgwcDn1U2L9VCA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.20.7", + "aria-query": "^5.1.3", + "array-includes": "^3.1.6", + "array.prototype.flatmap": "^1.3.1", + "ast-types-flow": "^0.0.7", + "axe-core": "^4.6.2", + "axobject-query": "^3.1.1", + "damerau-levenshtein": "^1.0.8", + "emoji-regex": "^9.2.2", + "has": "^1.0.3", + "jsx-ast-utils": "^3.3.3", + "language-tags": "=1.0.5", + "minimatch": "^3.1.2", + "object.entries": "^1.1.6", + "object.fromentries": "^2.0.6", + "semver": "^6.3.0" + }, + "engines": { + "node": ">=4.0" + }, + "peerDependencies": { + "eslint": "^3 || ^4 || ^5 || ^6 || ^7 || ^8" + } + }, + "node_modules/eslint-plugin-jsx-a11y/node_modules/semver": { + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", + "dev": true, + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/eslint-plugin-react": { + "version": "7.33.2", + "resolved": "https://registry.npmjs.org/eslint-plugin-react/-/eslint-plugin-react-7.33.2.tgz", + "integrity": "sha512-73QQMKALArI8/7xGLNI/3LylrEYrlKZSb5C9+q3OtOewTnMQi5cT+aE9E41sLCmli3I9PGGmD1yiZydyo4FEPw==", + "dev": true, + "license": "MIT", + "dependencies": { + "array-includes": "^3.1.6", + "array.prototype.flatmap": "^1.3.1", + "array.prototype.tosorted": "^1.1.1", + "doctrine": "^2.1.0", + "es-iterator-helpers": "^1.0.12", + "estraverse": "^5.3.0", + "jsx-ast-utils": "^2.4.1 || ^3.0.0", + "minimatch": "^3.1.2", + "object.entries": "^1.1.6", + "object.fromentries": "^2.0.6", + "object.hasown": "^1.1.2", + "object.values": "^1.1.6", + "prop-types": "^15.8.1", + "resolve": "^2.0.0-next.4", + "semver": "^6.3.1", + "string.prototype.matchall": "^4.0.8" + }, + "engines": { + "node": ">=4" + }, + "peerDependencies": { + "eslint": "^3 || ^4 || ^5 || ^6 || ^7 || ^8" + } + }, + "node_modules/eslint-plugin-react-hooks": { + "version": "5.0.0-canary-7118f5dd7-20230705", + "resolved": "https://registry.npmjs.org/eslint-plugin-react-hooks/-/eslint-plugin-react-hooks-5.0.0-canary-7118f5dd7-20230705.tgz", + "integrity": "sha512-AZYbMo/NW9chdL7vk6HQzQhT+PvTAEVqWk9ziruUoW2kAOcN5qNyelv70e0F1VNQAbvutOC9oc+xfWycI9FxDw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "eslint": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-0" + } + }, + "node_modules/eslint-plugin-react/node_modules/doctrine": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/doctrine/-/doctrine-2.1.0.tgz", + "integrity": "sha512-35mSku4ZXK0vfCuHEDAwt55dg2jNajHZ1odvF+8SSr82EsZY4QmXfuWso8oEd8zRhVObSN18aM0CjSdoBX7zIw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "esutils": "^2.0.2" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/eslint-plugin-react/node_modules/resolve": { + "version": "2.0.0-next.4", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-2.0.0-next.4.tgz", + "integrity": "sha512-iMDbmAWtfU+MHpxt/I5iWI7cY6YVEZUQ3MBgPQ++XD1PELuJHIl82xBmObyP2KyQmkNB2dsqF7seoQQiAn5yDQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-core-module": "^2.9.0", + "path-parse": "^1.0.7", + "supports-preserve-symlinks-flag": "^1.0.0" + }, + "bin": { + "resolve": "bin/resolve" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/eslint-plugin-react/node_modules/semver": { + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", + "dev": true, + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/eslint-scope": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-5.1.1.tgz", + "integrity": "sha512-2NxwbF/hZ0KpepYN0cNbo+FN6XoK7GaHlQhgx/hIZl6Va0bF45RQOOwhLIy8lQDbuCiadSLCBnH2CFYquit5bw==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "esrecurse": "^4.3.0", + "estraverse": "^4.1.1" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/eslint-scope/node_modules/estraverse": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-4.3.0.tgz", + "integrity": "sha512-39nnKffWz8xN1BU/2c79n9nB9HDzo0niYUqx6xyqUnyoAnQyyWpOTdZEeiCch8BBu515t4wp9ZmgVfVhn9EBpw==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=4.0" + } + }, + "node_modules/eslint-visitor-keys": { + "version": "3.4.3", + "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-3.4.3.tgz", + "integrity": "sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/eslint/node_modules/eslint-scope": { + "version": "7.2.2", + "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-7.2.2.tgz", + "integrity": "sha512-dOt21O7lTMhDM+X9mB4GX+DZrZtCUJPL/wlcTqxyrx5IvO0IYtILdtrQGQp+8n5S0gwSVmOf9NQrjMOgfQZlIg==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "esrecurse": "^4.3.0", + "estraverse": "^5.2.0" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/espree": { + "version": "9.6.1", + "resolved": "https://registry.npmjs.org/espree/-/espree-9.6.1.tgz", + "integrity": "sha512-oruZaFkjorTpF32kDSI5/75ViwGeZginGGy2NoOSg3Q9bnwlnmDm4HLnkl0RE3n+njDXR037aY1+x58Z/zFdwQ==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "acorn": "^8.9.0", + "acorn-jsx": "^5.3.2", + "eslint-visitor-keys": "^3.4.1" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/esprima": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", + "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==", + "license": "BSD-2-Clause", + "peer": true, + "bin": { + "esparse": "bin/esparse.js", + "esvalidate": "bin/esvalidate.js" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/esquery": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/esquery/-/esquery-1.5.0.tgz", + "integrity": "sha512-YQLXUplAwJgCydQ78IMJywZCceoqk1oH01OERdSAJc/7U2AylwjhSCLDEtqwg811idIS/9fIU5GjG73IgjKMVg==", + "dev": true, + "license": "BSD-3-Clause", + "dependencies": { + "estraverse": "^5.1.0" + }, + "engines": { + "node": ">=0.10" + } + }, + "node_modules/esrecurse": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/esrecurse/-/esrecurse-4.3.0.tgz", + "integrity": "sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "estraverse": "^5.2.0" + }, + "engines": { + "node": ">=4.0" + } + }, + "node_modules/estraverse": { + "version": "5.3.0", + "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.3.0.tgz", + "integrity": "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=4.0" + } + }, + "node_modules/estree-util-attach-comments": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/estree-util-attach-comments/-/estree-util-attach-comments-3.0.0.tgz", + "integrity": "sha512-cKUwm/HUcTDsYh/9FgnuFqpfquUbwIqwKM26BVCGDPVgvaCl/nDCCjUfiLlx6lsEZ3Z4RFxNbOQ60pkaEwFxGw==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-build-jsx": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/estree-util-build-jsx/-/estree-util-build-jsx-3.0.1.tgz", + "integrity": "sha512-8U5eiL6BTrPxp/CHbs2yMgP8ftMhR5ww1eIKoWRMlqvltHF8fZn5LRDvTKuxD3DUn+shRbLGqXemcP51oFCsGQ==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "devlop": "^1.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "estree-walker": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-is-identifier-name": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/estree-util-is-identifier-name/-/estree-util-is-identifier-name-3.0.0.tgz", + "integrity": "sha512-hFtqIDZTIUZ9BXLb8y4pYGyk6+wekIivNVTcmvk8NoOh+VeRn5y6cEHzbURrWbfp1fIqdVipilzj+lfaadNZmg==", + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-scope": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/estree-util-scope/-/estree-util-scope-1.0.0.tgz", + "integrity": "sha512-2CAASclonf+JFWBNJPndcOpA8EMJwa0Q8LUFJEKqXLW6+qBvbFZuF5gItbQOs/umBUkjviCSDCbBwU2cXbmrhQ==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-to-js": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/estree-util-to-js/-/estree-util-to-js-2.0.0.tgz", + "integrity": "sha512-WDF+xj5rRWmD5tj6bIqRi6CkLIXbbNQUcxQHzGysQzvHmdYG2G7p/Tf0J0gpxGgkeMZNTIjT/AoSvC9Xehcgdg==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "astring": "^1.8.0", + "source-map": "^0.7.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-visit": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/estree-util-visit/-/estree-util-visit-2.0.0.tgz", + "integrity": "sha512-m5KgiH85xAhhW8Wta0vShLcUvOsh3LLPI2YVwcbio1l7E09NTLL1EyMZFM1OyWowoH0skScNbhOPl4kcBgzTww==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-visit/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/estree-walker": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz", + "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0" + } + }, + "node_modules/esutils": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz", + "integrity": "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==", + "license": "BSD-2-Clause", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/etag": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz", + "integrity": "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/event-target-shim": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/event-target-shim/-/event-target-shim-5.0.1.tgz", + "integrity": "sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/eventemitter3": { + "version": "4.0.7", + "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-4.0.7.tgz", + "integrity": "sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw==", + "license": "MIT" + }, + "node_modules/execa": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/execa/-/execa-5.1.1.tgz", + "integrity": "sha512-8uSpZZocAZRBAPIEINJj3Lo9HyGitllczc27Eh5YYojjMFMn8yHMDMaUHE2Jqfq05D/wucwI4JGURyXt1vchyg==", + "license": "MIT", + "peer": true, + "dependencies": { + "cross-spawn": "^7.0.3", + "get-stream": "^6.0.0", + "human-signals": "^2.1.0", + "is-stream": "^2.0.0", + "merge-stream": "^2.0.0", + "npm-run-path": "^4.0.1", + "onetime": "^5.1.2", + "signal-exit": "^3.0.3", + "strip-final-newline": "^2.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sindresorhus/execa?sponsor=1" + } + }, + "node_modules/extend": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz", + "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==", + "license": "MIT" + }, + "node_modules/fast-deep-equal": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", + "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/fast-equals": { + "version": "5.2.2", + "resolved": "https://registry.npmjs.org/fast-equals/-/fast-equals-5.2.2.tgz", + "integrity": "sha512-V7/RktU11J3I36Nwq2JnZEM7tNm17eBJz+u25qdxBZeCKiX6BkVSZQjwWIr+IobgnZy+ag73tTZgZi7tr0LrBw==", + "license": "MIT", + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/fast-glob": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.1.tgz", + "integrity": "sha512-kNFPyjhh5cKjrUltxs+wFx+ZkbRaxxmZ+X0ZU31SOsxCEtP9VPgtq2teZw1DebupL5GmDaNQ6yKMMVcM41iqDg==", + "license": "MIT", + "dependencies": { + "@nodelib/fs.stat": "^2.0.2", + "@nodelib/fs.walk": "^1.2.3", + "glob-parent": "^5.1.2", + "merge2": "^1.3.0", + "micromatch": "^4.0.4" + }, + "engines": { + "node": ">=8.6.0" + } + }, + "node_modules/fast-glob/node_modules/glob-parent": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz", + "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==", + "license": "ISC", + "dependencies": { + "is-glob": "^4.0.1" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/fast-json-stable-stringify": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz", + "integrity": "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==", + "dev": true, + "license": "MIT" + }, + "node_modules/fast-levenshtein": { + "version": "2.0.6", + "resolved": "https://registry.npmjs.org/fast-levenshtein/-/fast-levenshtein-2.0.6.tgz", + "integrity": "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==", + "dev": true, + "license": "MIT" + }, + "node_modules/fast-xml-parser": { + "version": "4.2.7", + "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-4.2.7.tgz", + "integrity": "sha512-J8r6BriSLO1uj2miOk1NW0YVm8AGOOu3Si2HQp/cSmo6EA4m3fcwu2WKjJ4RK9wMLBtg69y1kS8baDiQBR41Ig==", + "funding": [ + { + "type": "paypal", + "url": "https://paypal.me/naturalintelligence" + }, + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT", + "peer": true, + "dependencies": { + "strnum": "^1.0.5" + }, + "bin": { + "fxparser": "src/cli/cli.js" + } + }, + "node_modules/fastq": { + "version": "1.15.0", + "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.15.0.tgz", + "integrity": "sha512-wBrocU2LCXXa+lWBt8RoIRD89Fi8OdABODa/kEnyeyjS5aZO5/GNvI5sEINADqP/h8M29UHTHUb53sUu5Ihqdw==", + "license": "ISC", + "dependencies": { + "reusify": "^1.0.4" + } + }, + "node_modules/fb-watchman": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/fb-watchman/-/fb-watchman-2.0.2.tgz", + "integrity": "sha512-p5161BqbuCaSnB8jIbzQHOlpgsPmK5rJVDfDKO91Axs5NC1uu3HRQm6wt9cd9/+GtQQIO53JdGXXoyDpTAsgYA==", + "license": "Apache-2.0", + "peer": true, + "dependencies": { + "bser": "2.1.1" + } + }, + "node_modules/file-entry-cache": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-6.0.1.tgz", + "integrity": "sha512-7Gps/XWymbLk2QLYK4NzpMOrYjMhdIxXuIvy2QBsLE6ljuodKvdkWs/cpyJJ3CVIVpH0Oi1Hvg1ovbMzLdFBBg==", + "dev": true, + "license": "MIT", + "dependencies": { + "flat-cache": "^3.0.4" + }, + "engines": { + "node": "^10.12.0 || >=12.0.0" + } + }, + "node_modules/fill-range": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.0.1.tgz", + "integrity": "sha512-qOo9F+dMUmC2Lcb4BbVvnKJxTPjCm+RRpe4gDuGrzkL7mEVl/djYSu2OdQ2Pa302N4oqkSg9ir6jaLWJ2USVpQ==", + "license": "MIT", + "dependencies": { + "to-regex-range": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/finalhandler": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-1.1.2.tgz", + "integrity": "sha512-aAWcW57uxVNrQZqFXjITpW3sIUQmHGG3qSb9mUah9MgMC4NeWhNOlNjXEYq3HjRAvL6arUviZGGJsBg6z0zsWA==", + "license": "MIT", + "peer": true, + "dependencies": { + "debug": "2.6.9", + "encodeurl": "~1.0.2", + "escape-html": "~1.0.3", + "on-finished": "~2.3.0", + "parseurl": "~1.3.3", + "statuses": "~1.5.0", + "unpipe": "~1.0.0" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/finalhandler/node_modules/debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "license": "MIT", + "peer": true, + "dependencies": { + "ms": "2.0.0" + } + }, + "node_modules/finalhandler/node_modules/ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "license": "MIT", + "peer": true + }, + "node_modules/find-cache-dir": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/find-cache-dir/-/find-cache-dir-2.1.0.tgz", + "integrity": "sha512-Tq6PixE0w/VMFfCgbONnkiQIVol/JJL7nRMi20fqzA4NRs9AfeqMGeRdPi3wIhYkxjeBaWh2rxwapn5Tu3IqOQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "commondir": "^1.0.1", + "make-dir": "^2.0.0", + "pkg-dir": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/find-cache-dir/node_modules/make-dir": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-2.1.0.tgz", + "integrity": "sha512-LS9X+dc8KLxXCb8dni79fLIIUA5VyZoyjSMCwTluaXA0o27cCK0bhXkpgw+sTXVpPy/lSO57ilRixqk0vDmtRA==", + "license": "MIT", + "peer": true, + "dependencies": { + "pify": "^4.0.1", + "semver": "^5.6.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/find-cache-dir/node_modules/pify": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/pify/-/pify-4.0.1.tgz", + "integrity": "sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/find-cache-dir/node_modules/semver": { + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.2.tgz", + "integrity": "sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g==", + "license": "ISC", + "peer": true, + "bin": { + "semver": "bin/semver" + } + }, + "node_modules/find-up": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-5.0.0.tgz", + "integrity": "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==", + "license": "MIT", + "dependencies": { + "locate-path": "^6.0.0", + "path-exists": "^4.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/flat-cache": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/flat-cache/-/flat-cache-3.0.4.tgz", + "integrity": "sha512-dm9s5Pw7Jc0GvMYbshN6zchCA9RgQlzzEZX3vylR9IqFfS8XciblUXOKfW6SiuJ0e13eDYZoZV5wdrev7P3Nwg==", + "dev": true, + "license": "MIT", + "dependencies": { + "flatted": "^3.1.0", + "rimraf": "^3.0.2" + }, + "engines": { + "node": "^10.12.0 || >=12.0.0" + } + }, + "node_modules/flatted": { + "version": "3.2.7", + "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.2.7.tgz", + "integrity": "sha512-5nqDSxl8nn5BSNxyR3n4I6eDmbolI6WT+QqR547RwxQapgjQBmtktdP+HTBb/a/zLsbzERTONyUB5pefh5TtjQ==", + "dev": true, + "license": "ISC" + }, + "node_modules/flow-enums-runtime": { + "version": "0.0.5", + "resolved": "https://registry.npmjs.org/flow-enums-runtime/-/flow-enums-runtime-0.0.5.tgz", + "integrity": "sha512-PSZF9ZuaZD03sT9YaIs0FrGJ7lSUw7rHZIex+73UYVXg46eL/wxN5PaVcPJFudE2cJu5f0fezitV5aBkLHPUOQ==", + "license": "MIT", + "peer": true + }, + "node_modules/flow-parser": { + "version": "0.206.0", + "resolved": "https://registry.npmjs.org/flow-parser/-/flow-parser-0.206.0.tgz", + "integrity": "sha512-HVzoK3r6Vsg+lKvlIZzaWNBVai+FXTX1wdYhz/wVlH13tb/gOdLXmlTqy6odmTBhT5UoWUbq0k8263Qhr9d88w==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/follow-redirects": { + "version": "1.15.3", + "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.3.tgz", + "integrity": "sha512-1VzOtuEM8pC9SFU1E+8KfTjZyMztRsgEfwQl44z8A25uy13jSzTj6dyK2Df52iV0vgHCfBwLhDWevLn95w5v6Q==", + "funding": [ + { + "type": "individual", + "url": "https://github.com/sponsors/RubenVerborgh" + } + ], + "license": "MIT", + "engines": { + "node": ">=4.0" + }, + "peerDependenciesMeta": { + "debug": { + "optional": true + } + } + }, + "node_modules/for-each": { + "version": "0.3.3", + "resolved": "https://registry.npmjs.org/for-each/-/for-each-0.3.3.tgz", + "integrity": "sha512-jqYfLp7mo9vIyQf8ykW2v7A+2N4QjeCeI5+Dz9XraiO1ign81wjiH7Fb9vSOWvQfNtmSa4H2RoQTrrXivdUZmw==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-callable": "^1.1.3" + } + }, + "node_modules/form-data": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.0.tgz", + "integrity": "sha512-ETEklSGi5t0QMZuiXoA/Q6vcnxcLQP5vdugSpuAyi6SVGi2clPPp+xgEhuMaHC+zGgn31Kd235W35f7Hykkaww==", + "license": "MIT", + "dependencies": { + "asynckit": "^0.4.0", + "combined-stream": "^1.0.8", + "mime-types": "^2.1.12" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/fraction.js": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/fraction.js/-/fraction.js-4.2.0.tgz", + "integrity": "sha512-MhLuK+2gUcnZe8ZHlaaINnQLl0xRIGRfcGk2yl8xoQAfHrSsL3rYu6FCmBdkdbhc9EPlwyGHewaRsvwRMJtAlA==", + "dev": true, + "license": "MIT", + "engines": { + "node": "*" + }, + "funding": { + "type": "patreon", + "url": "https://www.patreon.com/infusion" + } + }, + "node_modules/fresh": { + "version": "0.5.2", + "resolved": "https://registry.npmjs.org/fresh/-/fresh-0.5.2.tgz", + "integrity": "sha512-zJ2mQYM18rEFOudeV4GShTGIQ7RbzA7ozbU9I/XBpm7kqgMywgmylMwXHxZJmkVoYkna9d2pVXVXPdYTP9ej8Q==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/fs-extra": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz", + "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==", + "license": "MIT", + "peer": true, + "dependencies": { + "graceful-fs": "^4.2.0", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + }, + "engines": { + "node": ">=6 <7 || >=8" + } + }, + "node_modules/fs-minipass": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/fs-minipass/-/fs-minipass-2.1.0.tgz", + "integrity": "sha512-V/JgOLFCS+R6Vcq0slCuaeWEdNC3ouDlJMNIsacH2VtALiu9mV4LPrHc5cDl8k5aw6J8jwgWWpiTo5RYhmIzvg==", + "license": "ISC", + "dependencies": { + "minipass": "^3.0.0" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/fs-minipass/node_modules/minipass": { + "version": "3.3.6", + "resolved": "https://registry.npmjs.org/minipass/-/minipass-3.3.6.tgz", + "integrity": "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==", + "license": "ISC", + "dependencies": { + "yallist": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/fs.realpath": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", + "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==", + "license": "ISC" + }, + "node_modules/fsevents": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", + "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==", + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/function-bind": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.1.tgz", + "integrity": "sha512-yIovAzMX49sF8Yl58fSCWJ5svSLuaibPxXQJFLmBObTuCr0Mf1KiPopGM9NiFjiYBCbfaa2Fh6breQ6ANVTI0A==", + "license": "MIT" + }, + "node_modules/function.prototype.name": { + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/function.prototype.name/-/function.prototype.name-1.1.5.tgz", + "integrity": "sha512-uN7m/BzVKQnCUF/iW8jYea67v++2u7m5UgENbHRtdDVclOUP+FMPlCNdmk0h/ysGyo2tavMJEDqJAkJdRa1vMA==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.3", + "es-abstract": "^1.19.0", + "functions-have-names": "^1.2.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/functions-have-names": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/functions-have-names/-/functions-have-names-1.2.3.tgz", + "integrity": "sha512-xckBUXyTIqT97tq2x2AMb+g163b5JFysYk0x4qxNFwbfQkmNZoiRHb6sPzI9/QV33WeuvVYBUIiD4NzNIyqaRQ==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/fuse.js": { + "version": "7.1.0", + "resolved": "https://registry.npmjs.org/fuse.js/-/fuse.js-7.1.0.tgz", + "integrity": "sha512-trLf4SzuuUxfusZADLINj+dE8clK1frKdmqiJNb1Es75fmI5oY6X2mxLVUciLLjxqw/xr72Dhy+lER6dGd02FQ==", + "license": "Apache-2.0", + "engines": { + "node": ">=10" + } + }, + "node_modules/gauge": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/gauge/-/gauge-3.0.2.tgz", + "integrity": "sha512-+5J6MS/5XksCuXq++uFRsnUd7Ovu1XenbeuIuNRJxYWjgQbPuFhT14lAvsWfqfAmnwluf1OwMjz39HjfLPci0Q==", + "deprecated": "This package is no longer supported.", + "license": "ISC", + "dependencies": { + "aproba": "^1.0.3 || ^2.0.0", + "color-support": "^1.1.2", + "console-control-strings": "^1.0.0", + "has-unicode": "^2.0.1", + "object-assign": "^4.1.1", + "signal-exit": "^3.0.0", + "string-width": "^4.2.3", + "strip-ansi": "^6.0.1", + "wide-align": "^1.1.2" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/gensync": { + "version": "1.0.0-beta.2", + "resolved": "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.2.tgz", + "integrity": "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/get-caller-file": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", + "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==", + "license": "ISC", + "peer": true, + "engines": { + "node": "6.* || 8.* || >= 10.*" + } + }, + "node_modules/get-intrinsic": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.2.1.tgz", + "integrity": "sha512-2DcsyfABl+gVHEfCOaTrWgyt+tb6MSEGmKq+kI5HwLbIYgjgmMcV8KQ41uaKz1xxUcn9tJtgFbQUEVcEbd0FYw==", + "dev": true, + "license": "MIT", + "dependencies": { + "function-bind": "^1.1.1", + "has": "^1.0.3", + "has-proto": "^1.0.1", + "has-symbols": "^1.0.3" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/get-nonce": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/get-nonce/-/get-nonce-1.0.1.tgz", + "integrity": "sha512-FJhYRoDaiatfEkUK8HKlicmu/3SGFD51q3itKDGoSTysQJBnfOcxU5GxnhE1E6soB76MbT0MBtnKJuXyAx+96Q==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/get-stream": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-6.0.1.tgz", + "integrity": "sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/get-symbol-description": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/get-symbol-description/-/get-symbol-description-1.0.0.tgz", + "integrity": "sha512-2EmdH1YvIQiZpltCNgkuiUnyukzxM/R6NDJX31Ke3BG1Nq5b0S2PhX59UKi9vZpPDQVdqn+1IcaAwnzTT5vCjw==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "get-intrinsic": "^1.1.1" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/get-tsconfig": { + "version": "4.10.1", + "resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-4.10.1.tgz", + "integrity": "sha512-auHyJ4AgMz7vgS8Hp3N6HXSmlMdUyhSUrfBF16w153rxtLIEOE+HGqaBppczZvnHLqQJfiHotCYpNhl0lUROFQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "resolve-pkg-maps": "^1.0.0" + }, + "funding": { + "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1" + } + }, + "node_modules/glob": { + "version": "7.1.7", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.1.7.tgz", + "integrity": "sha512-OvD9ENzPLbegENnYP5UUfJIirTg4+XwMWGaQfQTY0JenxNvvIKP3U3/tAQSPIu/lHxXYSZmpXlUHeqAIdKzBLQ==", + "deprecated": "Glob versions prior to v9 are no longer supported", + "license": "ISC", + "dependencies": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.0.4", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + }, + "engines": { + "node": "*" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/glob-parent": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-6.0.2.tgz", + "integrity": "sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==", + "license": "ISC", + "dependencies": { + "is-glob": "^4.0.3" + }, + "engines": { + "node": ">=10.13.0" + } + }, + "node_modules/glob-to-regexp": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/glob-to-regexp/-/glob-to-regexp-0.4.1.tgz", + "integrity": "sha512-lkX1HJXwyMcprw/5YUZc2s7DrpAiHB21/V+E1rHUrVNokkvB6bqMzT0VfV6/86ZNabt1k14YOIaT7nDvOX3Iiw==", + "license": "BSD-2-Clause" + }, + "node_modules/globals": { + "version": "13.21.0", + "resolved": "https://registry.npmjs.org/globals/-/globals-13.21.0.tgz", + "integrity": "sha512-ybyme3s4yy/t/3s35bewwXKOf7cvzfreG2lH0lZl0JB7I4GxRP2ghxOK/Nb9EkRXdbBXZLfq/p/0W2JUONB/Gg==", + "dev": true, + "license": "MIT", + "dependencies": { + "type-fest": "^0.20.2" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/globalthis": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/globalthis/-/globalthis-1.0.3.tgz", + "integrity": "sha512-sFdI5LyBiNTHjRd7cGPWapiHWMOXKyuBNX/cWJ3NfzrZQVa8GI/8cofCl74AOVqq9W5kNmguTIzJ/1s2gyI9wA==", + "dev": true, + "license": "MIT", + "dependencies": { + "define-properties": "^1.1.3" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/globby": { + "version": "11.1.0", + "resolved": "https://registry.npmjs.org/globby/-/globby-11.1.0.tgz", + "integrity": "sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==", + "dev": true, + "license": "MIT", + "dependencies": { + "array-union": "^2.1.0", + "dir-glob": "^3.0.1", + "fast-glob": "^3.2.9", + "ignore": "^5.2.0", + "merge2": "^1.4.1", + "slash": "^3.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/gopd": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.0.1.tgz", + "integrity": "sha512-d65bNlIadxvpb/A2abVdlqKqV563juRnZ1Wtk6s1sIR8uNsXR70xqIzVqxVf1eTqDunwT2MkczEeaezCKTZhwA==", + "dev": true, + "license": "MIT", + "dependencies": { + "get-intrinsic": "^1.1.3" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/graceful-fs": { + "version": "4.2.11", + "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", + "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==", + "license": "ISC" + }, + "node_modules/grapheme-splitter": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/grapheme-splitter/-/grapheme-splitter-1.0.4.tgz", + "integrity": "sha512-bzh50DW9kTPM00T8y4o8vQg89Di9oLJVLW/KaOGIXJWP/iqCN6WKYkbNOF04vFLJhwcpYUh9ydh/+5vpOqV4YQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/graphemer": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/graphemer/-/graphemer-1.4.0.tgz", + "integrity": "sha512-EtKwoO6kxCL9WO5xipiHTZlSzBm7WLT627TqC/uVRd0HKmq8NXyebnNYxDoBi7wt8eTWrUrKXCOVaFq9x1kgag==", + "dev": true, + "license": "MIT" + }, + "node_modules/has": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/has/-/has-1.0.3.tgz", + "integrity": "sha512-f2dvO0VU6Oej7RkWJGrehjbzMAjFp5/VKPp5tTpWIV4JHHZK1/BxbFRtf/siA2SWTe09caDmVtYYzWEIbBS4zw==", + "license": "MIT", + "dependencies": { + "function-bind": "^1.1.1" + }, + "engines": { + "node": ">= 0.4.0" + } + }, + "node_modules/has-bigints": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/has-bigints/-/has-bigints-1.0.2.tgz", + "integrity": "sha512-tSvCKtBr9lkF0Ex0aQiP9N+OpV4zi2r/Nee5VkRDbaqv35RLYMzbwQfFSZZH0kR+Rd6302UJZ2p/bJCEoR3VoQ==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/has-property-descriptors": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/has-property-descriptors/-/has-property-descriptors-1.0.0.tgz", + "integrity": "sha512-62DVLZGoiEBDHQyqG4w9xCuZ7eJEwNmJRWw2VY84Oedb7WFcA27fiEVe8oUQx9hAUJ4ekurquucTGwsyO1XGdQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "get-intrinsic": "^1.1.1" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/has-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/has-proto/-/has-proto-1.0.1.tgz", + "integrity": "sha512-7qE+iP+O+bgF9clE5+UoBFzE65mlBiVj3tKCrlNQ0Ogwm0BjpT/gK4SlLYDMybDh5I3TCTKnPPa0oMG7JDYrhg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/has-symbols": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.0.3.tgz", + "integrity": "sha512-l3LCuF6MgDNwTDKkdYGEihYjt5pRPbEg46rtlmnSPlUbgmB8LOIrKJbYYFBSbnPaJexMKtiPO8hmeRjRz2Td+A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/has-tostringtag": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/has-tostringtag/-/has-tostringtag-1.0.0.tgz", + "integrity": "sha512-kFjcSNhnlGV1kyoGk7OXKSawH5JOb/LzUc5w9B02hOTO0dfFRjbHQKvg1d6cf3HbeUmtU9VbbV3qzZ2Teh97WQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "has-symbols": "^1.0.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/has-unicode": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/has-unicode/-/has-unicode-2.0.1.tgz", + "integrity": "sha512-8Rf9Y83NBReMnx0gFzA8JImQACstCYWUplepDa9xprwwtmgEZUF0h/i5xSA625zB/I37EtrswSST6OXxwaaIJQ==", + "license": "ISC" + }, + "node_modules/hast-util-to-estree": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/hast-util-to-estree/-/hast-util-to-estree-3.1.2.tgz", + "integrity": "sha512-94SDoKOfop5gP8RHyw4vV1aj+oChuD42g08BONGAaWFbbO6iaWUqxk7SWfGybgcVzhK16KifZr3zD2dqQgx3jQ==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "comma-separated-tokens": "^2.0.0", + "devlop": "^1.0.0", + "estree-util-attach-comments": "^3.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "hast-util-whitespace": "^3.0.0", + "mdast-util-mdx-expression": "^2.0.0", + "mdast-util-mdx-jsx": "^3.0.0", + "mdast-util-mdxjs-esm": "^2.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "style-to-object": "^1.0.0", + "unist-util-position": "^5.0.0", + "zwitch": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-jsx-runtime": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/hast-util-to-jsx-runtime/-/hast-util-to-jsx-runtime-2.3.3.tgz", + "integrity": "sha512-pdpkP8YD4v+qMKn2lnKSiJvZvb3FunDmFYQvVOsoO08+eTNWdaWKPMrC5wwNICtU3dQWHhElj5Sf5jPEnv4qJg==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "comma-separated-tokens": "^2.0.0", + "devlop": "^1.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "hast-util-whitespace": "^3.0.0", + "mdast-util-mdx-expression": "^2.0.0", + "mdast-util-mdx-jsx": "^3.0.0", + "mdast-util-mdxjs-esm": "^2.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "style-to-object": "^1.0.0", + "unist-util-position": "^5.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-jsx-runtime/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/hast-util-whitespace": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/hast-util-whitespace/-/hast-util-whitespace-3.0.0.tgz", + "integrity": "sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hermes-estree": { + "version": "0.12.0", + "resolved": "https://registry.npmjs.org/hermes-estree/-/hermes-estree-0.12.0.tgz", + "integrity": "sha512-+e8xR6SCen0wyAKrMT3UD0ZCCLymKhRgjEB5sS28rKiFir/fXgLoeRilRUssFCILmGHb+OvHDUlhxs0+IEyvQw==", + "license": "MIT", + "peer": true + }, + "node_modules/hermes-parser": { + "version": "0.12.0", + "resolved": "https://registry.npmjs.org/hermes-parser/-/hermes-parser-0.12.0.tgz", + "integrity": "sha512-d4PHnwq6SnDLhYl3LHNHvOg7nQ6rcI7QVil418REYksv0Mh3cEkHDcuhGxNQ3vgnLSLl4QSvDrFCwQNYdpWlzw==", + "license": "MIT", + "peer": true, + "dependencies": { + "hermes-estree": "0.12.0" + } + }, + "node_modules/hermes-profile-transformer": { + "version": "0.0.6", + "resolved": "https://registry.npmjs.org/hermes-profile-transformer/-/hermes-profile-transformer-0.0.6.tgz", + "integrity": "sha512-cnN7bQUm65UWOy6cbGcCcZ3rpwW8Q/j4OP5aWRhEry4Z2t2aR1cjrbp0BS+KiBN0smvP1caBgAuxutvyvJILzQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "source-map": "^0.7.3" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/http-errors": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.0.tgz", + "integrity": "sha512-FtwrG/euBzaEjYeRqOgly7G0qviiXoJWnvEH2Z1plBdXgbyjv34pHTSb9zoeHMyDy33+DWy5Wt9Wo+TURtOYSQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "depd": "2.0.0", + "inherits": "2.0.4", + "setprototypeof": "1.2.0", + "statuses": "2.0.1", + "toidentifier": "1.0.1" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/http-errors/node_modules/statuses": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.1.tgz", + "integrity": "sha512-RwNA9Z/7PrK06rYLIzFMlaF+l73iwpzsqRIFgbMLbTcLD6cOao82TaWefPXQvB2fOC4AjuYSEndS7N/mTCbkdQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/https-proxy-agent": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-5.0.1.tgz", + "integrity": "sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA==", + "license": "MIT", + "dependencies": { + "agent-base": "6", + "debug": "4" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/human-signals": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/human-signals/-/human-signals-2.1.0.tgz", + "integrity": "sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw==", + "license": "Apache-2.0", + "peer": true, + "engines": { + "node": ">=10.17.0" + } + }, + "node_modules/ieee754": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz", + "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "BSD-3-Clause", + "peer": true + }, + "node_modules/ignore": { + "version": "5.2.4", + "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.2.4.tgz", + "integrity": "sha512-MAb38BcSbH0eHNBxn7ql2NH/kX33OkB3lZ1BNdh7ENeRChHTYsTvWrMubiIAMNS2llXEEgZ1MUOBtXChP3kaFQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, + "node_modules/image-size": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/image-size/-/image-size-1.0.2.tgz", + "integrity": "sha512-xfOoWjceHntRb3qFCrh5ZFORYH8XCdYpASltMhZ/Q0KZiOwjdE/Yl2QCiWdwD+lygV5bMCvauzgu5PxBX/Yerg==", + "license": "MIT", + "peer": true, + "dependencies": { + "queue": "6.0.2" + }, + "bin": { + "image-size": "bin/image-size.js" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/import-fresh": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.0.tgz", + "integrity": "sha512-veYYhQa+D1QBKznvhUHxb8faxlrwUnxseDAbAp457E0wLNio2bOSKnjYDhMj+YiAq61xrMGhQk9iXVk5FzgQMw==", + "dev": true, + "license": "MIT", + "dependencies": { + "parent-module": "^1.0.0", + "resolve-from": "^4.0.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/imurmurhash": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz", + "integrity": "sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==", + "license": "MIT", + "engines": { + "node": ">=0.8.19" + } + }, + "node_modules/inflight": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz", + "integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==", + "deprecated": "This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.", + "license": "ISC", + "dependencies": { + "once": "^1.3.0", + "wrappy": "1" + } + }, + "node_modules/inherits": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", + "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", + "license": "ISC" + }, + "node_modules/inline-style-parser": { + "version": "0.2.4", + "resolved": "https://registry.npmjs.org/inline-style-parser/-/inline-style-parser-0.2.4.tgz", + "integrity": "sha512-0aO8FkhNZlj/ZIbNi7Lxxr12obT7cL1moPfE4tg1LkX7LlLfC6DeX4l2ZEud1ukP9jNQyNnfzQVqwbwmAATY4Q==", + "license": "MIT" + }, + "node_modules/install": { + "version": "0.13.0", + "resolved": "https://registry.npmjs.org/install/-/install-0.13.0.tgz", + "integrity": "sha512-zDml/jzr2PKU9I8J/xyZBQn8rPCAY//UOYNmR01XwNwyfhEWObo2SWfSl1+0tm1u6PhxLwDnfsT/6jB7OUxqFA==", + "license": "MIT", + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/internal-slot": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/internal-slot/-/internal-slot-1.0.5.tgz", + "integrity": "sha512-Y+R5hJrzs52QCG2laLn4udYVnxsfny9CpOhNhUvk/SSSVyF6T27FzRbF0sroPidSu3X8oEAkOn2K804mjpt6UQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "get-intrinsic": "^1.2.0", + "has": "^1.0.3", + "side-channel": "^1.0.4" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/internmap": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/internmap/-/internmap-1.0.1.tgz", + "integrity": "sha512-lDB5YccMydFBtasVtxnZ3MRBHuaoE8GKsppq+EchKL2U4nK/DmEpPHNH8MZe5HkMtpSiTSOZwfN0tzYjO/lJEw==", + "license": "ISC" + }, + "node_modules/invariant": { + "version": "2.2.4", + "resolved": "https://registry.npmjs.org/invariant/-/invariant-2.2.4.tgz", + "integrity": "sha512-phJfQVBuaJM5raOpJjSfkiD6BpbCE4Ns//LaXl6wGYtUBY83nWS6Rf9tXm2e8VaK60JEjYldbPif/A2B1C2gNA==", + "license": "MIT", + "peer": true, + "dependencies": { + "loose-envify": "^1.0.0" + } + }, + "node_modules/iovalkey": { + "version": "0.3.1", + "resolved": "https://registry.npmjs.org/iovalkey/-/iovalkey-0.3.1.tgz", + "integrity": "sha512-pSmFj/ZDFLP8AzqIAMpNJArhHYNeyqIwfcUULwZv8g6y3eaUGrlnlT7QXLrJAp0yiGCAqe1hPA33x/h5opNP9w==", + "license": "MIT", + "dependencies": { + "@iovalkey/commands": "^0.1.0", + "cluster-key-slot": "^1.1.0", + "debug": "^4.3.4", + "denque": "^2.1.0", + "lodash.defaults": "^4.2.0", + "lodash.isarguments": "^3.1.0", + "redis-errors": "^1.2.0", + "redis-parser": "^3.0.0", + "standard-as-callback": "^2.1.0" + }, + "engines": { + "node": ">=18.12.0" + } + }, + "node_modules/ip": { + "version": "1.1.8", + "resolved": "https://registry.npmjs.org/ip/-/ip-1.1.8.tgz", + "integrity": "sha512-PuExPYUiu6qMBQb4l06ecm6T6ujzhmh+MeJcW9wa89PoAz5pvd4zPgN5WJV104mb6S2T1AwNIAaB70JNrLQWhg==", + "license": "MIT", + "peer": true + }, + "node_modules/is-alphabetical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz", + "integrity": "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-alphanumerical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphanumerical/-/is-alphanumerical-2.0.1.tgz", + "integrity": "sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==", + "license": "MIT", + "dependencies": { + "is-alphabetical": "^2.0.0", + "is-decimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-array-buffer": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/is-array-buffer/-/is-array-buffer-3.0.2.tgz", + "integrity": "sha512-y+FyyR/w8vfIRq4eQcM1EYgSTnmHXPqaF+IgzgraytCFq5Xh8lllDVmAZolPJiZttZLeFSINPYMaEJ7/vWUa1w==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "get-intrinsic": "^1.2.0", + "is-typed-array": "^1.1.10" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-arrayish": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.2.1.tgz", + "integrity": "sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==", + "license": "MIT", + "peer": true + }, + "node_modules/is-async-function": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/is-async-function/-/is-async-function-2.0.0.tgz", + "integrity": "sha512-Y1JXKrfykRJGdlDwdKlLpLyMIiWqWvuSd17TvZk68PLAOGOoF4Xyav1z0Xhoi+gCYjZVeC5SI+hYFOfvXmGRCA==", + "dev": true, + "license": "MIT", + "dependencies": { + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-bigint": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/is-bigint/-/is-bigint-1.0.4.tgz", + "integrity": "sha512-zB9CruMamjym81i2JZ3UMn54PKGsQzsJeo6xvN3HJJ4CAsQNB6iRutp2To77OfCNuoxspsIhzaPoO1zyCEhFOg==", + "dev": true, + "license": "MIT", + "dependencies": { + "has-bigints": "^1.0.1" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-binary-path": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/is-binary-path/-/is-binary-path-2.1.0.tgz", + "integrity": "sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw==", + "license": "MIT", + "dependencies": { + "binary-extensions": "^2.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/is-boolean-object": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/is-boolean-object/-/is-boolean-object-1.1.2.tgz", + "integrity": "sha512-gDYaKHJmnj4aWxyj6YHyXVpdQawtVLHU5cb+eztPGczf6cjuTdwve5ZIEfgXqH4e57An1D1AKf8CZ3kYrQRqYA==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-buffer": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/is-buffer/-/is-buffer-2.0.5.tgz", + "integrity": "sha512-i2R6zNFDwgEHJyQUtJEk0XFi1i0dPFn/oqjK3/vPCcDeJvW5NQ83V8QbicfF1SupOaB0h8ntgBC2YiE7dfyctQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT", + "engines": { + "node": ">=4" + } + }, + "node_modules/is-callable": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/is-callable/-/is-callable-1.2.7.tgz", + "integrity": "sha512-1BC0BVFhS/p0qtw6enp8e+8OD0UrK0oFLztSjNzhcKA3WDuJxxAPXzPuPtKkjEY9UUoEWlX/8fgKeu2S8i9JTA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-core-module": { + "version": "2.13.0", + "resolved": "https://registry.npmjs.org/is-core-module/-/is-core-module-2.13.0.tgz", + "integrity": "sha512-Z7dk6Qo8pOCp3l4tsX2C5ZVas4V+UxwQodwZhLopL91TX8UyyHEXafPcyoeeWuLrwzHcr3igO78wNLwHJHsMCQ==", + "license": "MIT", + "dependencies": { + "has": "^1.0.3" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-date-object": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/is-date-object/-/is-date-object-1.0.5.tgz", + "integrity": "sha512-9YQaSxsAiSwcvS33MBk3wTCVnWK+HhF8VZR2jRxehM16QcVOdHqPn4VPHmRK4lSr38n9JriurInLcP90xsYNfQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-decimal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-decimal/-/is-decimal-2.0.1.tgz", + "integrity": "sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-directory": { + "version": "0.3.1", + "resolved": "https://registry.npmjs.org/is-directory/-/is-directory-0.3.1.tgz", + "integrity": "sha512-yVChGzahRFvbkscn2MlwGismPO12i9+znNruC5gVEntG3qu0xQMzsGg/JFbrsqDOHtHFPci+V5aP5T9I+yeKqw==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-extglob": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz", + "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-finalizationregistry": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/is-finalizationregistry/-/is-finalizationregistry-1.0.2.tgz", + "integrity": "sha512-0by5vtUJs8iFQb5TYUHHPudOR+qXYIMKtiUzvLIZITZUjknFmziyBJuLhVRc+Ds0dREFlskDNJKYIdIzu/9pfw==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-fullwidth-code-point": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-2.0.0.tgz", + "integrity": "sha512-VHskAKYM8RfSFXwee5t5cbN5PZeq1Wrh6qd5bkyiXIf6UQcN6w/A0eXM9r6t8d+GYOh+o6ZhiEnb88LN/Y8m2w==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/is-generator-function": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/is-generator-function/-/is-generator-function-1.0.10.tgz", + "integrity": "sha512-jsEjy9l3yiXEQ+PsXdmBwEPcOxaXWLspKdplFUVI9vq1iZgIekeC0L167qeu86czQaxed3q/Uzuw0swL0irL8A==", + "dev": true, + "license": "MIT", + "dependencies": { + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-glob": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz", + "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==", + "license": "MIT", + "dependencies": { + "is-extglob": "^2.1.1" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-hexadecimal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-hexadecimal/-/is-hexadecimal-2.0.1.tgz", + "integrity": "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-interactive": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/is-interactive/-/is-interactive-1.0.0.tgz", + "integrity": "sha512-2HvIEKRoqS62guEC+qBjpvRubdX910WCMuJTZ+I9yvqKU2/12eSL549HMwtabb4oupdj2sMP50k+XJfB/8JE6w==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/is-map": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/is-map/-/is-map-2.0.2.tgz", + "integrity": "sha512-cOZFQQozTha1f4MxLFzlgKYPTyj26picdZTx82hbc/Xf4K/tZOOXSCkMvU4pKioRXGDLJRn0GM7Upe7kR721yg==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-negative-zero": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/is-negative-zero/-/is-negative-zero-2.0.2.tgz", + "integrity": "sha512-dqJvarLawXsFbNDeJW7zAz8ItJ9cd28YufuuFzh0G8pNHjJMnY08Dv7sYX2uF5UpQOwieAeOExEYAWWfu7ZZUA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-number": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz", + "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==", + "license": "MIT", + "engines": { + "node": ">=0.12.0" + } + }, + "node_modules/is-number-object": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/is-number-object/-/is-number-object-1.0.7.tgz", + "integrity": "sha512-k1U0IRzLMo7ZlYIfzRu23Oh6MiIFasgpb9X76eqfFZAqwH44UI4KTBvBYIZ1dSL9ZzChTB9ShHfLkR4pdW5krQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-path-inside": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/is-path-inside/-/is-path-inside-3.0.3.tgz", + "integrity": "sha512-Fd4gABb+ycGAmKou8eMftCupSir5lRxqf4aD/vd0cD2qc4HL07OjCeuHMr8Ro4CoMaeCKDB0/ECBOVWjTwUvPQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/is-plain-obj": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-4.1.0.tgz", + "integrity": "sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/is-plain-object": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/is-plain-object/-/is-plain-object-2.0.4.tgz", + "integrity": "sha512-h5PpgXkWitc38BBMYawTYMWJHFZJVnBquFE57xFpjB8pJFiF6gZ+bU+WyI/yqXiFR5mdLsgYNaPe8uao6Uv9Og==", + "license": "MIT", + "peer": true, + "dependencies": { + "isobject": "^3.0.1" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-regex": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/is-regex/-/is-regex-1.1.4.tgz", + "integrity": "sha512-kvRdxDsxZjhzUX07ZnLydzS1TU/TJlTUHHY4YLL87e37oUA49DfkLqgy+VjFocowy29cKvcSiu+kIv728jTTVg==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-set": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/is-set/-/is-set-2.0.2.tgz", + "integrity": "sha512-+2cnTEZeY5z/iXGbLhPrOAaK/Mau5k5eXq9j14CpRTftq0pAJu2MwVRSZhyZWBzx3o6X795Lz6Bpb6R0GKf37g==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-shared-array-buffer": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/is-shared-array-buffer/-/is-shared-array-buffer-1.0.2.tgz", + "integrity": "sha512-sqN2UDu1/0y6uvXyStCOzyhAjCSlHceFoMKJW8W9EU9cvic/QdsZ0kEU93HEy3IUEFZIiH/3w+AH/UQbPHNdhA==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-stream": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-2.0.1.tgz", + "integrity": "sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/is-string": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/is-string/-/is-string-1.0.7.tgz", + "integrity": "sha512-tE2UXzivje6ofPW7l23cjDOMa09gb7xlAqG6jG5ej6uPV32TlWP3NKPigtaGeHNu9fohccRYvIiZMfOOnOYUtg==", + "dev": true, + "license": "MIT", + "dependencies": { + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-symbol": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/is-symbol/-/is-symbol-1.0.4.tgz", + "integrity": "sha512-C/CPBqKWnvdcxqIARxyOh4v1UUEOCHpgDa0WYgpKDFMszcrPcffg5uhwSgPCLD2WWxmq6isisz87tzT01tuGhg==", + "dev": true, + "license": "MIT", + "dependencies": { + "has-symbols": "^1.0.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-typed-array": { + "version": "1.1.12", + "resolved": "https://registry.npmjs.org/is-typed-array/-/is-typed-array-1.1.12.tgz", + "integrity": "sha512-Z14TF2JNG8Lss5/HMqt0//T9JeHXttXy5pH/DBU4vi98ozO2btxzq9MwYDZYnKwU8nRsz/+GVFVRDq3DkVuSPg==", + "dev": true, + "license": "MIT", + "dependencies": { + "which-typed-array": "^1.1.11" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-unicode-supported": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/is-unicode-supported/-/is-unicode-supported-0.1.0.tgz", + "integrity": "sha512-knxG2q4UC3u8stRGyAVJCOdxFmv5DZiRcdlIaAQXAbSfJya+OhopNotLQrstBhququ4ZpuKbDc/8S6mgXgPFPw==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/is-weakmap": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-weakmap/-/is-weakmap-2.0.1.tgz", + "integrity": "sha512-NSBR4kH5oVj1Uwvv970ruUkCV7O1mzgVFO4/rev2cLRda9Tm9HrL70ZPut4rOHgY0FNrUu9BCbXA2sdQ+x0chA==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-weakref": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/is-weakref/-/is-weakref-1.0.2.tgz", + "integrity": "sha512-qctsuLZmIQ0+vSSMfoVvyFe2+GSEvnmZ2ezTup1SBse9+twCCeial6EEi3Nc2KFcf6+qz2FBPnjXsk8xhKSaPQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-weakset": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/is-weakset/-/is-weakset-2.0.2.tgz", + "integrity": "sha512-t2yVvttHkQktwnNNmBQ98AhENLdPUTDTE21uPqAQ0ARwQfGeQKRVS0NNurH7bTf7RrvcVn1OOge45CnBeHCSmg==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "get-intrinsic": "^1.1.1" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-what": { + "version": "4.1.15", + "resolved": "https://registry.npmjs.org/is-what/-/is-what-4.1.15.tgz", + "integrity": "sha512-uKua1wfy3Yt+YqsD6mTUEa2zSi3G1oPlqTflgaPJ7z63vUGN5pxFpnQfeSLMFnJDEsdvOtkp1rUWkYjB4YfhgA==", + "license": "MIT", + "engines": { + "node": ">=12.13" + }, + "funding": { + "url": "https://github.com/sponsors/mesqueeb" + } + }, + "node_modules/is-wsl": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/is-wsl/-/is-wsl-1.1.0.tgz", + "integrity": "sha512-gfygJYZ2gLTDlmbWMI0CE2MwnFzSN/2SZfkMlItC4K/JBlsWVDB0bO6XhqcY13YXE7iMcAJnzTCJjPiTeJJ0Mw==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/isarray": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/isarray/-/isarray-2.0.5.tgz", + "integrity": "sha512-xHjhDr3cNBK0BzdUJSPXZntQUx/mwMS5Rw4A7lPJ90XGAO6ISP/ePDNuo0vhqOZU+UD5JoodwCAAoZQd3FeAKw==", + "dev": true, + "license": "MIT" + }, + "node_modules/isexe": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "license": "ISC" + }, + "node_modules/isobject": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/isobject/-/isobject-3.0.1.tgz", + "integrity": "sha512-WhB9zCku7EGTj/HQQRz5aUQEUeoQZH2bWcltRErOpymJ4boYE6wL9Tbr23krRPSZ+C5zqNSrSw+Cc7sZZ4b7vg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/iterator.prototype": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/iterator.prototype/-/iterator.prototype-1.1.0.tgz", + "integrity": "sha512-rjuhAk1AJ1fssphHD0IFV6TWL40CwRZ53FrztKx43yk2v6rguBYsY4Bj1VU4HmoMmKwZUlx7mfnhDf9cOp4YTw==", + "dev": true, + "license": "MIT", + "dependencies": { + "define-properties": "^1.1.4", + "get-intrinsic": "^1.1.3", + "has-symbols": "^1.0.3", + "has-tostringtag": "^1.0.0", + "reflect.getprototypeof": "^1.0.3" + } + }, + "node_modules/its-fine": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/its-fine/-/its-fine-1.1.1.tgz", + "integrity": "sha512-v1Ia1xl20KbuSGlwoaGsW0oxsw8Be+TrXweidxD9oT/1lAh6O3K3/GIM95Tt6WCiv6W+h2M7RB1TwdoAjQyyKw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@types/react-reconciler": "^0.28.0" + }, + "peerDependencies": { + "react": ">=18.0" + } + }, + "node_modules/its-fine/node_modules/@types/react-reconciler": { + "version": "0.28.4", + "resolved": "https://registry.npmjs.org/@types/react-reconciler/-/react-reconciler-0.28.4.tgz", + "integrity": "sha512-Xd55E2aLI9Q/ikDQEmfRzIwYJs4oO0h9ZHA3FZDakzt1WR6JMZcpqtCZlF97I72KVjoY4rHXU5TfvkRDOyr/rg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@types/react": "*" + } + }, + "node_modules/jest-environment-node": { + "version": "29.7.0", + "resolved": "https://registry.npmjs.org/jest-environment-node/-/jest-environment-node-29.7.0.tgz", + "integrity": "sha512-DOSwCRqXirTOyheM+4d5YZOrWcdu0LNZ87ewUoywbcb2XR4wKgqiG8vNeYwhjFMbEkfju7wx2GYH0P2gevGvFw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@jest/environment": "^29.7.0", + "@jest/fake-timers": "^29.7.0", + "@jest/types": "^29.6.3", + "@types/node": "*", + "jest-mock": "^29.7.0", + "jest-util": "^29.7.0" + }, + "engines": { + "node": "^14.15.0 || ^16.10.0 || >=18.0.0" + } + }, + "node_modules/jest-get-type": { + "version": "29.6.3", + "resolved": "https://registry.npmjs.org/jest-get-type/-/jest-get-type-29.6.3.tgz", + "integrity": "sha512-zrteXnqYxfQh7l5FHyL38jL39di8H8rHoecLH3JNxH3BwOrBsNeabdap5e0I23lD4HHI8W5VFBZqG4Eaq5LNcw==", + "license": "MIT", + "peer": true, + "engines": { + "node": "^14.15.0 || ^16.10.0 || >=18.0.0" + } + }, + "node_modules/jest-message-util": { + "version": "29.7.0", + "resolved": "https://registry.npmjs.org/jest-message-util/-/jest-message-util-29.7.0.tgz", + "integrity": "sha512-GBEV4GRADeP+qtB2+6u61stea8mGcOT4mCtrYISZwfu9/ISHFJ/5zOMXYbpBE9RsS5+Gb63DW4FgmnKJ79Kf6w==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/code-frame": "^7.12.13", + "@jest/types": "^29.6.3", + "@types/stack-utils": "^2.0.0", + "chalk": "^4.0.0", + "graceful-fs": "^4.2.9", + "micromatch": "^4.0.4", + "pretty-format": "^29.7.0", + "slash": "^3.0.0", + "stack-utils": "^2.0.3" + }, + "engines": { + "node": "^14.15.0 || ^16.10.0 || >=18.0.0" + } + }, + "node_modules/jest-message-util/node_modules/ansi-styles": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz", + "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/jest-message-util/node_modules/pretty-format": { + "version": "29.7.0", + "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-29.7.0.tgz", + "integrity": "sha512-Pdlw/oPxN+aXdmM9R00JVC9WVFoCLTKJvDVLgmJ+qAffBMxsV85l/Lu7sNx4zSzPyoL2euImuEwHhOXdEgNFZQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@jest/schemas": "^29.6.3", + "ansi-styles": "^5.0.0", + "react-is": "^18.0.0" + }, + "engines": { + "node": "^14.15.0 || ^16.10.0 || >=18.0.0" + } + }, + "node_modules/jest-message-util/node_modules/react-is": { + "version": "18.2.0", + "resolved": "https://registry.npmjs.org/react-is/-/react-is-18.2.0.tgz", + "integrity": "sha512-xWGDIW6x921xtzPkhiULtthJHoJvBbF3q26fzloPCK0hsvxtPVelvftw3zjbHWSkR2km9Z+4uxbDDK/6Zw9B8w==", + "license": "MIT", + "peer": true + }, + "node_modules/jest-mock": { + "version": "29.7.0", + "resolved": "https://registry.npmjs.org/jest-mock/-/jest-mock-29.7.0.tgz", + "integrity": "sha512-ITOMZn+UkYS4ZFh83xYAOzWStloNzJFO2s8DWrE4lhtGD+AorgnbkiKERe4wQVBydIGPx059g6riW5Btp6Llnw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@jest/types": "^29.6.3", + "@types/node": "*", + "jest-util": "^29.7.0" + }, + "engines": { + "node": "^14.15.0 || ^16.10.0 || >=18.0.0" + } + }, + "node_modules/jest-regex-util": { + "version": "27.5.1", + "resolved": "https://registry.npmjs.org/jest-regex-util/-/jest-regex-util-27.5.1.tgz", + "integrity": "sha512-4bfKq2zie+x16okqDXjXn9ql2B0dScQu+vcwe4TvFVhkVyuWLqpZrZtXxLLWoXYgn0E87I6r6GRYHF7wFZBUvg==", + "license": "MIT", + "peer": true, + "engines": { + "node": "^10.13.0 || ^12.13.0 || ^14.15.0 || >=15.0.0" + } + }, + "node_modules/jest-util": { + "version": "29.7.0", + "resolved": "https://registry.npmjs.org/jest-util/-/jest-util-29.7.0.tgz", + "integrity": "sha512-z6EbKajIpqGKU56y5KBUgy1dt1ihhQJgWzUlZHArA/+X2ad7Cb5iF+AK1EWVL/Bo7Rz9uurpqw6SiBCefUbCGA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@jest/types": "^29.6.3", + "@types/node": "*", + "chalk": "^4.0.0", + "ci-info": "^3.2.0", + "graceful-fs": "^4.2.9", + "picomatch": "^2.2.3" + }, + "engines": { + "node": "^14.15.0 || ^16.10.0 || >=18.0.0" + } + }, + "node_modules/jest-validate": { + "version": "29.7.0", + "resolved": "https://registry.npmjs.org/jest-validate/-/jest-validate-29.7.0.tgz", + "integrity": "sha512-ZB7wHqaRGVw/9hST/OuFUReG7M8vKeq0/J2egIGLdvjHCmYqGARhzXmtgi+gVeZ5uXFF219aOc3Ls2yLg27tkw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@jest/types": "^29.6.3", + "camelcase": "^6.2.0", + "chalk": "^4.0.0", + "jest-get-type": "^29.6.3", + "leven": "^3.1.0", + "pretty-format": "^29.7.0" + }, + "engines": { + "node": "^14.15.0 || ^16.10.0 || >=18.0.0" + } + }, + "node_modules/jest-validate/node_modules/ansi-styles": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz", + "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/jest-validate/node_modules/pretty-format": { + "version": "29.7.0", + "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-29.7.0.tgz", + "integrity": "sha512-Pdlw/oPxN+aXdmM9R00JVC9WVFoCLTKJvDVLgmJ+qAffBMxsV85l/Lu7sNx4zSzPyoL2euImuEwHhOXdEgNFZQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@jest/schemas": "^29.6.3", + "ansi-styles": "^5.0.0", + "react-is": "^18.0.0" + }, + "engines": { + "node": "^14.15.0 || ^16.10.0 || >=18.0.0" + } + }, + "node_modules/jest-validate/node_modules/react-is": { + "version": "18.2.0", + "resolved": "https://registry.npmjs.org/react-is/-/react-is-18.2.0.tgz", + "integrity": "sha512-xWGDIW6x921xtzPkhiULtthJHoJvBbF3q26fzloPCK0hsvxtPVelvftw3zjbHWSkR2km9Z+4uxbDDK/6Zw9B8w==", + "license": "MIT", + "peer": true + }, + "node_modules/jest-worker": { + "version": "27.5.1", + "resolved": "https://registry.npmjs.org/jest-worker/-/jest-worker-27.5.1.tgz", + "integrity": "sha512-7vuh85V5cdDofPyxn58nrPjBktZo0u9x1g8WtjQol+jZDaE+fhN+cIvTj11GndBnMnyfrUOG1sZQxCdjKh+DKg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@types/node": "*", + "merge-stream": "^2.0.0", + "supports-color": "^8.0.0" + }, + "engines": { + "node": ">= 10.13.0" + } + }, + "node_modules/jest-worker/node_modules/supports-color": { + "version": "8.1.1", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-8.1.1.tgz", + "integrity": "sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==", + "license": "MIT", + "peer": true, + "dependencies": { + "has-flag": "^4.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/supports-color?sponsor=1" + } + }, + "node_modules/jiti": { + "version": "1.19.1", + "resolved": "https://registry.npmjs.org/jiti/-/jiti-1.19.1.tgz", + "integrity": "sha512-oVhqoRDaBXf7sjkll95LHVS6Myyyb1zaunVwk4Z0+WPSW4gjS0pl01zYKHScTuyEhQsFxV5L4DR5r+YqSyqyyg==", + "license": "MIT", + "bin": { + "jiti": "bin/jiti.js" + } + }, + "node_modules/joi": { + "version": "17.10.1", + "resolved": "https://registry.npmjs.org/joi/-/joi-17.10.1.tgz", + "integrity": "sha512-vIiDxQKmRidUVp8KngT8MZSOcmRVm2zV7jbMjNYWuHcJWI0bUck3nRTGQjhpPlQenIQIBC5Vp9AhcnHbWQqafw==", + "license": "BSD-3-Clause", + "peer": true, + "dependencies": { + "@hapi/hoek": "^9.0.0", + "@hapi/topo": "^5.0.0", + "@sideway/address": "^4.1.3", + "@sideway/formula": "^3.0.1", + "@sideway/pinpoint": "^2.0.0" + } + }, + "node_modules/jose": { + "version": "4.14.4", + "resolved": "https://registry.npmjs.org/jose/-/jose-4.14.4.tgz", + "integrity": "sha512-j8GhLiKmUAh+dsFXlX1aJCbt5KMibuKb+d7j1JaOJG6s2UjX1PQlW+OKB/sD4a/5ZYF4RcmYmLSndOoU3Lt/3g==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/panva" + } + }, + "node_modules/js-tokens": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", + "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==", + "license": "MIT" + }, + "node_modules/js-yaml": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", + "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "license": "MIT", + "dependencies": { + "argparse": "^2.0.1" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/jsc-android": { + "version": "250231.0.0", + "resolved": "https://registry.npmjs.org/jsc-android/-/jsc-android-250231.0.0.tgz", + "integrity": "sha512-rS46PvsjYmdmuz1OAWXY/1kCYG7pnf1TBqeTiOJr1iDz7s5DLxxC9n/ZMknLDxzYzNVfI7R95MH10emSSG1Wuw==", + "license": "BSD-2-Clause", + "peer": true + }, + "node_modules/jsc-safe-url": { + "version": "0.2.4", + "resolved": "https://registry.npmjs.org/jsc-safe-url/-/jsc-safe-url-0.2.4.tgz", + "integrity": "sha512-0wM3YBWtYePOjfyXQH5MWQ8H7sdk5EXSwZvmSLKk2RboVQ2Bu239jycHDz5J/8Blf3K0Qnoy2b6xD+z10MFB+Q==", + "license": "0BSD", + "peer": true + }, + "node_modules/jscodeshift": { + "version": "0.14.0", + "resolved": "https://registry.npmjs.org/jscodeshift/-/jscodeshift-0.14.0.tgz", + "integrity": "sha512-7eCC1knD7bLUPuSCwXsMZUH51O8jIcoVyKtI6P0XM0IVzlGjckPy3FIwQlorzbN0Sg79oK+RlohN32Mqf/lrYA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/core": "^7.13.16", + "@babel/parser": "^7.13.16", + "@babel/plugin-proposal-class-properties": "^7.13.0", + "@babel/plugin-proposal-nullish-coalescing-operator": "^7.13.8", + "@babel/plugin-proposal-optional-chaining": "^7.13.12", + "@babel/plugin-transform-modules-commonjs": "^7.13.8", + "@babel/preset-flow": "^7.13.13", + "@babel/preset-typescript": "^7.13.0", + "@babel/register": "^7.13.16", + "babel-core": "^7.0.0-bridge.0", + "chalk": "^4.1.2", + "flow-parser": "0.*", + "graceful-fs": "^4.2.4", + "micromatch": "^4.0.4", + "neo-async": "^2.5.0", + "node-dir": "^0.1.17", + "recast": "^0.21.0", + "temp": "^0.8.4", + "write-file-atomic": "^2.3.0" + }, + "bin": { + "jscodeshift": "bin/jscodeshift.js" + }, + "peerDependencies": { + "@babel/preset-env": "^7.1.6" + } + }, + "node_modules/jsesc": { + "version": "2.5.2", + "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-2.5.2.tgz", + "integrity": "sha512-OYu7XEzjkCQ3C5Ps3QIZsQfNpqoJyZZA99wd9aWd05NCtC5pWOkShK2mkL6HXQR6/Cy2lbNdPlZBpuQHXE63gA==", + "license": "MIT", + "peer": true, + "bin": { + "jsesc": "bin/jsesc" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/json-parse-better-errors": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/json-parse-better-errors/-/json-parse-better-errors-1.0.2.tgz", + "integrity": "sha512-mrqyZKfX5EhL7hvqcV6WG1yYjnjeuYDzDhhcAAUrq8Po85NBQBJP+ZDUT75qZQ98IkUoBqdkExkukOU7Ts2wrw==", + "license": "MIT", + "peer": true + }, + "node_modules/json-schema-traverse": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz", + "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==", + "dev": true, + "license": "MIT" + }, + "node_modules/json-stable-stringify-without-jsonify": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/json-stable-stringify-without-jsonify/-/json-stable-stringify-without-jsonify-1.0.1.tgz", + "integrity": "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==", + "dev": true, + "license": "MIT" + }, + "node_modules/json5": { + "version": "2.2.3", + "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz", + "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==", + "license": "MIT", + "peer": true, + "bin": { + "json5": "lib/cli.js" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/jsonfile": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", + "integrity": "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==", + "license": "MIT", + "peer": true, + "optionalDependencies": { + "graceful-fs": "^4.1.6" + } + }, + "node_modules/jsx-ast-utils": { + "version": "3.3.5", + "resolved": "https://registry.npmjs.org/jsx-ast-utils/-/jsx-ast-utils-3.3.5.tgz", + "integrity": "sha512-ZZow9HBI5O6EPgSJLUb8n2NKgmVWTwCvHGwFuJlMjvLFqlGG6pjirPhtdsseaLZjSibD8eegzmYpUZwoIlj2cQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "array-includes": "^3.1.6", + "array.prototype.flat": "^1.3.1", + "object.assign": "^4.1.4", + "object.values": "^1.1.6" + }, + "engines": { + "node": ">=4.0" + } + }, + "node_modules/kind-of": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz", + "integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/kleur": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/kleur/-/kleur-3.0.3.tgz", + "integrity": "sha512-eTIzlVOSUR+JxdDFepEYcBMtZ9Qqdef+rnzWdRZuMbOywu5tO2w2N7rqjoANZ5k9vywhL6Br1VRjUIgTQx4E8w==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/konva": { + "version": "9.2.1", + "resolved": "https://registry.npmjs.org/konva/-/konva-9.2.1.tgz", + "integrity": "sha512-/D9mZttzjqrkjVPlWyJirdBjFJ/uafrFFR5BD41PsFUX+ctqmoFZjcnjs/ag6YnZNEVsU4/E9dRaH5FH9Y4cLw==", + "funding": [ + { + "type": "patreon", + "url": "https://www.patreon.com/lavrton" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/konva" + }, + { + "type": "github", + "url": "https://github.com/sponsors/lavrton" + } + ], + "license": "MIT", + "peer": true + }, + "node_modules/language-subtag-registry": { + "version": "0.3.22", + "resolved": "https://registry.npmjs.org/language-subtag-registry/-/language-subtag-registry-0.3.22.tgz", + "integrity": "sha512-tN0MCzyWnoz/4nHS6uxdlFWoUZT7ABptwKPQ52Ea7URk6vll88bWBVhodtnlfEuCcKWNGoc+uGbw1cwa9IKh/w==", + "dev": true, + "license": "CC0-1.0" + }, + "node_modules/language-tags": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/language-tags/-/language-tags-1.0.5.tgz", + "integrity": "sha512-qJhlO9cGXi6hBGKoxEG/sKZDAHD5Hnu9Hs4WbOY3pCWXDhw0N8x1NenNzm2EnNLkLkk7J2SdxAkDSbb6ftT+UQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "language-subtag-registry": "~0.3.2" + } + }, + "node_modules/leven": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/leven/-/leven-3.1.0.tgz", + "integrity": "sha512-qsda+H8jTaUaN/x5vzW2rzc+8Rw4TAQ/4KjB46IwK5VH+IlVeeeje/EoZRpiXvIqjFgK84QffqPztGI3VBLG1A==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/levn": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/levn/-/levn-0.4.1.tgz", + "integrity": "sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "prelude-ls": "^1.2.1", + "type-check": "~0.4.0" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/lilconfig": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-2.1.0.tgz", + "integrity": "sha512-utWOt/GHzuUxnLKxB6dk81RoOeoNeHgbrXiuGk4yyF5qlRz+iIVWu56E2fqGHFrXz0QNUhLB/8nKqvRH66JKGQ==", + "license": "MIT", + "engines": { + "node": ">=10" + } + }, + "node_modules/lines-and-columns": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz", + "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==", + "license": "MIT" + }, + "node_modules/locate-path": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz", + "integrity": "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==", + "license": "MIT", + "dependencies": { + "p-locate": "^5.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/lodash": { + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", + "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==", + "license": "MIT" + }, + "node_modules/lodash.debounce": { + "version": "4.0.8", + "resolved": "https://registry.npmjs.org/lodash.debounce/-/lodash.debounce-4.0.8.tgz", + "integrity": "sha512-FT1yDzDYEoYWhnSGnpE/4Kj1fLZkDFyqRb7fNt6FdYOSxlUWAtp42Eh6Wb0rGIv/m9Bgo7x4GhQbm5Ys4SG5ow==", + "license": "MIT", + "peer": true + }, + "node_modules/lodash.defaults": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/lodash.defaults/-/lodash.defaults-4.2.0.tgz", + "integrity": "sha512-qjxPLHd3r5DnsdGacqOMU6pb/avJzdh9tFX2ymgoZE27BmjXrNy/y4LoaiTeAb+O3gL8AfpJGtqfX/ae2leYYQ==", + "license": "MIT" + }, + "node_modules/lodash.isarguments": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/lodash.isarguments/-/lodash.isarguments-3.1.0.tgz", + "integrity": "sha512-chi4NHZlZqZD18a0imDHnZPrDeBbTtVN7GXMwuGdRH9qotxAjYs3aVLKc7zNOG9eddR5Ksd8rvFEBc9SsggPpg==", + "license": "MIT" + }, + "node_modules/lodash.merge": { + "version": "4.6.2", + "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.2.tgz", + "integrity": "sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/lodash.throttle": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/lodash.throttle/-/lodash.throttle-4.1.1.tgz", + "integrity": "sha512-wIkUCfVKpVsWo3JSZlc+8MB5it+2AN5W8J7YVMST30UrvcQNZ1Okbj+rbVniijTWE6FGYy4XJq/rHkas8qJMLQ==", + "license": "MIT", + "peer": true + }, + "node_modules/log-symbols": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/log-symbols/-/log-symbols-4.1.0.tgz", + "integrity": "sha512-8XPvpAA8uyhfteu8pIvQxpJZ7SYYdpUivZpGy6sFsBuKRY/7rQGavedeB8aK+Zkyq6upMFVL/9AW6vOYzfRyLg==", + "license": "MIT", + "peer": true, + "dependencies": { + "chalk": "^4.1.0", + "is-unicode-supported": "^0.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/logkitty": { + "version": "0.7.1", + "resolved": "https://registry.npmjs.org/logkitty/-/logkitty-0.7.1.tgz", + "integrity": "sha512-/3ER20CTTbahrCrpYfPn7Xavv9diBROZpoXGVZDWMw4b/X4uuUwAC0ki85tgsdMRONURyIJbcOvS94QsUBYPbQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "ansi-fragments": "^0.2.1", + "dayjs": "^1.8.15", + "yargs": "^15.1.0" + }, + "bin": { + "logkitty": "bin/logkitty.js" + } + }, + "node_modules/logkitty/node_modules/camelcase": { + "version": "5.3.1", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz", + "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/logkitty/node_modules/cliui": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-6.0.0.tgz", + "integrity": "sha512-t6wbgtoCXvAzst7QgXxJYqPt0usEfbgQdftEPbLL/cvv6HPE5VgvqCuAIDR0NgU52ds6rFwqrgakNLrHEjCbrQ==", + "license": "ISC", + "peer": true, + "dependencies": { + "string-width": "^4.2.0", + "strip-ansi": "^6.0.0", + "wrap-ansi": "^6.2.0" + } + }, + "node_modules/logkitty/node_modules/find-up": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-4.1.0.tgz", + "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==", + "license": "MIT", + "peer": true, + "dependencies": { + "locate-path": "^5.0.0", + "path-exists": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/logkitty/node_modules/locate-path": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz", + "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==", + "license": "MIT", + "peer": true, + "dependencies": { + "p-locate": "^4.1.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/logkitty/node_modules/p-limit": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", + "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", + "license": "MIT", + "peer": true, + "dependencies": { + "p-try": "^2.0.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/logkitty/node_modules/p-locate": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-4.1.0.tgz", + "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==", + "license": "MIT", + "peer": true, + "dependencies": { + "p-limit": "^2.2.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/logkitty/node_modules/wrap-ansi": { + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-6.2.0.tgz", + "integrity": "sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==", + "license": "MIT", + "peer": true, + "dependencies": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/logkitty/node_modules/y18n": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-4.0.3.tgz", + "integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==", + "license": "ISC", + "peer": true + }, + "node_modules/logkitty/node_modules/yargs": { + "version": "15.4.1", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-15.4.1.tgz", + "integrity": "sha512-aePbxDmcYW++PaqBsJ+HYUFwCdv4LVvdnhBy78E57PIor8/OVvhMrADFFEDh8DHDFRv/O9i3lPhsENjO7QX0+A==", + "license": "MIT", + "peer": true, + "dependencies": { + "cliui": "^6.0.0", + "decamelize": "^1.2.0", + "find-up": "^4.1.0", + "get-caller-file": "^2.0.1", + "require-directory": "^2.1.1", + "require-main-filename": "^2.0.0", + "set-blocking": "^2.0.0", + "string-width": "^4.2.0", + "which-module": "^2.0.0", + "y18n": "^4.0.0", + "yargs-parser": "^18.1.2" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/logkitty/node_modules/yargs-parser": { + "version": "18.1.3", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-18.1.3.tgz", + "integrity": "sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ==", + "license": "ISC", + "peer": true, + "dependencies": { + "camelcase": "^5.0.0", + "decamelize": "^1.2.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/longest-streak": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/longest-streak/-/longest-streak-3.1.0.tgz", + "integrity": "sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/loose-envify": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz", + "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==", + "license": "MIT", + "dependencies": { + "js-tokens": "^3.0.0 || ^4.0.0" + }, + "bin": { + "loose-envify": "cli.js" + } + }, + "node_modules/lru-cache": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-6.0.0.tgz", + "integrity": "sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==", + "license": "ISC", + "dependencies": { + "yallist": "^4.0.0" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/lucide-react": { + "version": "0.268.0", + "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-0.268.0.tgz", + "integrity": "sha512-XP/xY3ASJAViqNqVnDRcEfdxfRB7uNST8sqTLwZhL983ikmHMQ7qQak7ZxrnXOVhB3QDBawdr3ANq0P+iWHP/g==", + "license": "ISC", + "peerDependencies": { + "react": "^16.5.1 || ^17.0.0 || ^18.0.0" + } + }, + "node_modules/make-dir": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-3.1.0.tgz", + "integrity": "sha512-g3FeP20LNwhALb/6Cz6Dd4F2ngze0jz7tbzrD2wAV+o9FeNHe4rL+yK2md0J/fiSf1sa1ADhXqi5+oVwOM/eGw==", + "license": "MIT", + "dependencies": { + "semver": "^6.0.0" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/make-dir/node_modules/semver": { + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/make-error": { + "version": "1.3.6", + "resolved": "https://registry.npmjs.org/make-error/-/make-error-1.3.6.tgz", + "integrity": "sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==", + "license": "ISC" + }, + "node_modules/makeerror": { + "version": "1.0.12", + "resolved": "https://registry.npmjs.org/makeerror/-/makeerror-1.0.12.tgz", + "integrity": "sha512-JmqCvUhmt43madlpFzG4BQzG2Z3m6tvQDNKdClZnO3VbIudJYmxsT0FNJMeiB2+JTSlTQTSbU8QdesVmwJcmLg==", + "license": "BSD-3-Clause", + "peer": true, + "dependencies": { + "tmpl": "1.0.5" + } + }, + "node_modules/markdown-extensions": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/markdown-extensions/-/markdown-extensions-2.0.0.tgz", + "integrity": "sha512-o5vL7aDWatOTX8LzaS1WMoaoxIiLRQJuIKKe2wAw6IeULDHaqbiqiggmx+pKvZDb1Sj+pE46Sn1T7lCqfFtg1Q==", + "license": "MIT", + "engines": { + "node": ">=16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/mdast-util-definitions": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/mdast-util-definitions/-/mdast-util-definitions-5.1.2.tgz", + "integrity": "sha512-8SVPMuHqlPME/z3gqVwWY4zVXn8lqKv/pAhC57FuJ40ImXyBpmO5ukh98zB2v7Blql2FiHjHv9LVztSIqjY+MA==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^3.0.0", + "@types/unist": "^2.0.0", + "unist-util-visit": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-definitions/node_modules/@types/mdast": { + "version": "3.0.12", + "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-3.0.12.tgz", + "integrity": "sha512-DT+iNIRNX884cx0/Q1ja7NyUPpZuv0KPyL5rGNxm1WC1OtHstl7n4Jb7nk+xacNShQMbczJjt8uFzznpp6kYBg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2" + } + }, + "node_modules/mdast-util-definitions/node_modules/unist-util-is": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-5.2.1.tgz", + "integrity": "sha512-u9njyyfEh43npf1M+yGKDGVPbY/JWEemg5nH05ncKPfi+kBbKBJoTdsogMu33uhytuLlv9y0O7GH7fEdwLdLQw==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-definitions/node_modules/unist-util-visit": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-4.1.2.tgz", + "integrity": "sha512-MSd8OUGISqHdVvfY9TPhyK2VdUrPgxkUtWSuMHF6XAAFuL4LokseigBnZtPnJMu+FbynTkFNnFlyjxpVKujMRg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0", + "unist-util-is": "^5.0.0", + "unist-util-visit-parents": "^5.1.1" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-definitions/node_modules/unist-util-visit-parents": { + "version": "5.1.3", + "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-5.1.3.tgz", + "integrity": "sha512-x6+y8g7wWMyQhL1iZfhIPhDAs7Xwbn9nRosDXl7qoPTSCy0yNxnKc+hWokFifWQIDGi154rdUqKvbCa4+1kLhg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0", + "unist-util-is": "^5.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-from-markdown": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-2.0.2.tgz", + "integrity": "sha512-uZhTV/8NBuw0WHkPTrCqDOl0zVe1BIng5ZtHoDk49ME1qqcjYmmLmOf0gELgcRMxN4w2iuIeVso5/6QymSrgmA==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "mdast-util-to-string": "^4.0.0", + "micromark": "^4.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-decode-string": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unist-util-stringify-position": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-from-markdown/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/mdast-util-mdx": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-mdx/-/mdast-util-mdx-3.0.0.tgz", + "integrity": "sha512-JfbYLAW7XnYTTbUsmpu0kdBUVe+yKVJZBItEjwyYJiDJuZ9w4eeaqks4HQO+R7objWgS2ymV60GYpI14Ug554w==", + "license": "MIT", + "dependencies": { + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-mdx-expression": "^2.0.0", + "mdast-util-mdx-jsx": "^3.0.0", + "mdast-util-mdxjs-esm": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdx-expression": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-mdx-expression/-/mdast-util-mdx-expression-2.0.1.tgz", + "integrity": "sha512-J6f+9hUp+ldTZqKRSg7Vw5V6MqjATc+3E4gf3CFNcuZNWD8XdyI6zQ8GqH7f8169MM6P7hMBRDVGnn7oHB9kXQ==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdx-jsx": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/mdast-util-mdx-jsx/-/mdast-util-mdx-jsx-3.2.0.tgz", + "integrity": "sha512-lj/z8v0r6ZtsN/cGNNtemmmfoLAFZnjMbNyLzBafjzikOM+glrjNHPlf6lQDOTccj9n5b0PPihEBbhneMyGs1Q==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "ccount": "^2.0.0", + "devlop": "^1.1.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0", + "parse-entities": "^4.0.0", + "stringify-entities": "^4.0.0", + "unist-util-stringify-position": "^4.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdx-jsx/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/mdast-util-mdxjs-esm": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-mdxjs-esm/-/mdast-util-mdxjs-esm-2.0.1.tgz", + "integrity": "sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-phrasing": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-phrasing/-/mdast-util-phrasing-4.1.0.tgz", + "integrity": "sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-hast": { + "version": "13.2.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-13.2.0.tgz", + "integrity": "sha512-QGYKEuUsYT9ykKBCMOEDLsU5JRObWQusAolFMeko/tYPufNkRffBAQjIE+99jbA87xv6FgmjLtwjh9wBWajwAA==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "@ungap/structured-clone": "^1.0.0", + "devlop": "^1.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "trim-lines": "^3.0.0", + "unist-util-position": "^5.0.0", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-markdown": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/mdast-util-to-markdown/-/mdast-util-to-markdown-2.1.2.tgz", + "integrity": "sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "longest-streak": "^3.0.0", + "mdast-util-phrasing": "^4.0.0", + "mdast-util-to-string": "^4.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-decode-string": "^2.0.0", + "unist-util-visit": "^5.0.0", + "zwitch": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-markdown/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/mdast-util-to-string": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-4.0.0.tgz", + "integrity": "sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/memoize-one": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/memoize-one/-/memoize-one-5.2.1.tgz", + "integrity": "sha512-zYiwtZUcYyXKo/np96AGZAckk+FWWsUdJ3cHGGmld7+AhvcWmQyGCYUh1hc4Q/pkOhb65dQR/pqCyK0cOaHz4Q==", + "license": "MIT", + "peer": true + }, + "node_modules/merge-stream": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz", + "integrity": "sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==", + "license": "MIT", + "peer": true + }, + "node_modules/merge2": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz", + "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==", + "license": "MIT", + "engines": { + "node": ">= 8" + } + }, + "node_modules/metro": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro/-/metro-0.76.7.tgz", + "integrity": "sha512-67ZGwDeumEPnrHI+pEDSKH2cx+C81Gx8Mn5qOtmGUPm/Up9Y4I1H2dJZ5n17MWzejNo0XAvPh0QL0CrlJEODVQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/code-frame": "^7.0.0", + "@babel/core": "^7.20.0", + "@babel/generator": "^7.20.0", + "@babel/parser": "^7.20.0", + "@babel/template": "^7.0.0", + "@babel/traverse": "^7.20.0", + "@babel/types": "^7.20.0", + "accepts": "^1.3.7", + "async": "^3.2.2", + "chalk": "^4.0.0", + "ci-info": "^2.0.0", + "connect": "^3.6.5", + "debug": "^2.2.0", + "denodeify": "^1.2.1", + "error-stack-parser": "^2.0.6", + "graceful-fs": "^4.2.4", + "hermes-parser": "0.12.0", + "image-size": "^1.0.2", + "invariant": "^2.2.4", + "jest-worker": "^27.2.0", + "jsc-safe-url": "^0.2.2", + "lodash.throttle": "^4.1.1", + "metro-babel-transformer": "0.76.7", + "metro-cache": "0.76.7", + "metro-cache-key": "0.76.7", + "metro-config": "0.76.7", + "metro-core": "0.76.7", + "metro-file-map": "0.76.7", + "metro-inspector-proxy": "0.76.7", + "metro-minify-terser": "0.76.7", + "metro-minify-uglify": "0.76.7", + "metro-react-native-babel-preset": "0.76.7", + "metro-resolver": "0.76.7", + "metro-runtime": "0.76.7", + "metro-source-map": "0.76.7", + "metro-symbolicate": "0.76.7", + "metro-transform-plugins": "0.76.7", + "metro-transform-worker": "0.76.7", + "mime-types": "^2.1.27", + "node-fetch": "^2.2.0", + "nullthrows": "^1.1.1", + "rimraf": "^3.0.2", + "serialize-error": "^2.1.0", + "source-map": "^0.5.6", + "strip-ansi": "^6.0.0", + "throat": "^5.0.0", + "ws": "^7.5.1", + "yargs": "^17.6.2" + }, + "bin": { + "metro": "src/cli.js" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-babel-transformer": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-babel-transformer/-/metro-babel-transformer-0.76.7.tgz", + "integrity": "sha512-bgr2OFn0J4r0qoZcHrwEvccF7g9k3wdgTOgk6gmGHrtlZ1Jn3oCpklW/DfZ9PzHfjY2mQammKTc19g/EFGyOJw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/core": "^7.20.0", + "hermes-parser": "0.12.0", + "nullthrows": "^1.1.1" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-cache": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-cache/-/metro-cache-0.76.7.tgz", + "integrity": "sha512-nWBMztrs5RuSxZRI7hgFgob5PhYDmxICh9FF8anm9/ito0u0vpPvRxt7sRu8fyeD2AHdXqE7kX32rWY0LiXgeg==", + "license": "MIT", + "peer": true, + "dependencies": { + "metro-core": "0.76.7", + "rimraf": "^3.0.2" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-cache-key": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-cache-key/-/metro-cache-key-0.76.7.tgz", + "integrity": "sha512-0pecoIzwsD/Whn/Qfa+SDMX2YyasV0ndbcgUFx7w1Ct2sLHClujdhQ4ik6mvQmsaOcnGkIyN0zcceMDjC2+BFQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-config": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-config/-/metro-config-0.76.7.tgz", + "integrity": "sha512-CFDyNb9bqxZemiChC/gNdXZ7OQkIwmXzkrEXivcXGbgzlt/b2juCv555GWJHyZSlorwnwJfY3uzAFu4A9iRVfg==", + "license": "MIT", + "peer": true, + "dependencies": { + "connect": "^3.6.5", + "cosmiconfig": "^5.0.5", + "jest-validate": "^29.2.1", + "metro": "0.76.7", + "metro-cache": "0.76.7", + "metro-core": "0.76.7", + "metro-runtime": "0.76.7" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-config/node_modules/metro-runtime": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-runtime/-/metro-runtime-0.76.7.tgz", + "integrity": "sha512-MuWHubQHymUWBpZLwuKZQgA/qbb35WnDAKPo83rk7JRLIFPvzXSvFaC18voPuzJBt1V98lKQIonh6MiC9gd8Ug==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/runtime": "^7.0.0", + "react-refresh": "^0.4.0" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-core": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-core/-/metro-core-0.76.7.tgz", + "integrity": "sha512-0b8KfrwPmwCMW+1V7ZQPkTy2tsEKZjYG9Pu1PTsu463Z9fxX7WaR0fcHFshv+J1CnQSUTwIGGjbNvj1teKe+pw==", + "license": "MIT", + "peer": true, + "dependencies": { + "lodash.throttle": "^4.1.1", + "metro-resolver": "0.76.7" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-file-map": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-file-map/-/metro-file-map-0.76.7.tgz", + "integrity": "sha512-s+zEkTcJ4mOJTgEE2ht4jIo1DZfeWreQR3tpT3gDV/Y/0UQ8aJBTv62dE775z0GLsWZApiblAYZsj7ZE8P06nw==", + "license": "MIT", + "peer": true, + "dependencies": { + "anymatch": "^3.0.3", + "debug": "^2.2.0", + "fb-watchman": "^2.0.0", + "graceful-fs": "^4.2.4", + "invariant": "^2.2.4", + "jest-regex-util": "^27.0.6", + "jest-util": "^27.2.0", + "jest-worker": "^27.2.0", + "micromatch": "^4.0.4", + "node-abort-controller": "^3.1.1", + "nullthrows": "^1.1.1", + "walker": "^1.0.7" + }, + "engines": { + "node": ">=16" + }, + "optionalDependencies": { + "fsevents": "^2.3.2" + } + }, + "node_modules/metro-file-map/node_modules/@jest/types": { + "version": "27.5.1", + "resolved": "https://registry.npmjs.org/@jest/types/-/types-27.5.1.tgz", + "integrity": "sha512-Cx46iJ9QpwQTjIdq5VJu2QTMMs3QlEjI0x1QbBP5W1+nMzyc2XmimiRR/CbX9TO0cPTeUlxWMOu8mslYsJ8DEw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@types/istanbul-lib-coverage": "^2.0.0", + "@types/istanbul-reports": "^3.0.0", + "@types/node": "*", + "@types/yargs": "^16.0.0", + "chalk": "^4.0.0" + }, + "engines": { + "node": "^10.13.0 || ^12.13.0 || ^14.15.0 || >=15.0.0" + } + }, + "node_modules/metro-file-map/node_modules/@types/yargs": { + "version": "16.0.5", + "resolved": "https://registry.npmjs.org/@types/yargs/-/yargs-16.0.5.tgz", + "integrity": "sha512-AxO/ADJOBFJScHbWhq2xAhlWP24rY4aCEG/NFaMvbT3X2MgRsLjhjQwsn0Zi5zn0LG9jUhCCZMeX9Dkuw6k+vQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@types/yargs-parser": "*" + } + }, + "node_modules/metro-file-map/node_modules/debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "license": "MIT", + "peer": true, + "dependencies": { + "ms": "2.0.0" + } + }, + "node_modules/metro-file-map/node_modules/jest-util": { + "version": "27.5.1", + "resolved": "https://registry.npmjs.org/jest-util/-/jest-util-27.5.1.tgz", + "integrity": "sha512-Kv2o/8jNvX1MQ0KGtw480E/w4fBCDOnH6+6DmeKi6LZUIlKA5kwY0YNdlzaWTiVgxqAqik11QyxDOKk543aKXw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@jest/types": "^27.5.1", + "@types/node": "*", + "chalk": "^4.0.0", + "ci-info": "^3.2.0", + "graceful-fs": "^4.2.9", + "picomatch": "^2.2.3" + }, + "engines": { + "node": "^10.13.0 || ^12.13.0 || ^14.15.0 || >=15.0.0" + } + }, + "node_modules/metro-file-map/node_modules/ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "license": "MIT", + "peer": true + }, + "node_modules/metro-inspector-proxy": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-inspector-proxy/-/metro-inspector-proxy-0.76.7.tgz", + "integrity": "sha512-rNZ/6edTl/1qUekAhAbaFjczMphM50/UjtxiKulo6vqvgn/Mjd9hVqDvVYfAMZXqPvlusD88n38UjVYPkruLSg==", + "license": "MIT", + "peer": true, + "dependencies": { + "connect": "^3.6.5", + "debug": "^2.2.0", + "node-fetch": "^2.2.0", + "ws": "^7.5.1", + "yargs": "^17.6.2" + }, + "bin": { + "metro-inspector-proxy": "src/cli.js" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-inspector-proxy/node_modules/debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "license": "MIT", + "peer": true, + "dependencies": { + "ms": "2.0.0" + } + }, + "node_modules/metro-inspector-proxy/node_modules/ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "license": "MIT", + "peer": true + }, + "node_modules/metro-inspector-proxy/node_modules/ws": { + "version": "7.5.9", + "resolved": "https://registry.npmjs.org/ws/-/ws-7.5.9.tgz", + "integrity": "sha512-F+P9Jil7UiSKSkppIiD94dN07AwvFixvLIj1Og1Rl9GGMuNipJnV9JzjD6XuqmAeiswGvUmNLjr5cFuXwNS77Q==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=8.3.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": "^5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + }, + "node_modules/metro-minify-terser": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-minify-terser/-/metro-minify-terser-0.76.7.tgz", + "integrity": "sha512-FQiZGhIxCzhDwK4LxyPMLlq0Tsmla10X7BfNGlYFK0A5IsaVKNJbETyTzhpIwc+YFRT4GkFFwgo0V2N5vxO5HA==", + "license": "MIT", + "peer": true, + "dependencies": { + "terser": "^5.15.0" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-minify-uglify": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-minify-uglify/-/metro-minify-uglify-0.76.7.tgz", + "integrity": "sha512-FuXIU3j2uNcSvQtPrAJjYWHruPiQ+EpE++J9Z+VznQKEHcIxMMoQZAfIF2IpZSrZYfLOjVFyGMvj41jQMxV1Vw==", + "license": "MIT", + "peer": true, + "dependencies": { + "uglify-es": "^3.1.9" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-react-native-babel-preset": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-react-native-babel-preset/-/metro-react-native-babel-preset-0.76.7.tgz", + "integrity": "sha512-R25wq+VOSorAK3hc07NW0SmN8z9S/IR0Us0oGAsBcMZnsgkbOxu77Mduqf+f4is/wnWHc5+9bfiqdLnaMngiVw==", + "deprecated": "Use @react-native/babel-preset instead", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/core": "^7.20.0", + "@babel/plugin-proposal-async-generator-functions": "^7.0.0", + "@babel/plugin-proposal-class-properties": "^7.18.0", + "@babel/plugin-proposal-export-default-from": "^7.0.0", + "@babel/plugin-proposal-nullish-coalescing-operator": "^7.18.0", + "@babel/plugin-proposal-numeric-separator": "^7.0.0", + "@babel/plugin-proposal-object-rest-spread": "^7.20.0", + "@babel/plugin-proposal-optional-catch-binding": "^7.0.0", + "@babel/plugin-proposal-optional-chaining": "^7.20.0", + "@babel/plugin-syntax-dynamic-import": "^7.8.0", + "@babel/plugin-syntax-export-default-from": "^7.0.0", + "@babel/plugin-syntax-flow": "^7.18.0", + "@babel/plugin-syntax-nullish-coalescing-operator": "^7.0.0", + "@babel/plugin-syntax-optional-chaining": "^7.0.0", + "@babel/plugin-transform-arrow-functions": "^7.0.0", + "@babel/plugin-transform-async-to-generator": "^7.20.0", + "@babel/plugin-transform-block-scoping": "^7.0.0", + "@babel/plugin-transform-classes": "^7.0.0", + "@babel/plugin-transform-computed-properties": "^7.0.0", + "@babel/plugin-transform-destructuring": "^7.20.0", + "@babel/plugin-transform-flow-strip-types": "^7.20.0", + "@babel/plugin-transform-function-name": "^7.0.0", + "@babel/plugin-transform-literals": "^7.0.0", + "@babel/plugin-transform-modules-commonjs": "^7.0.0", + "@babel/plugin-transform-named-capturing-groups-regex": "^7.0.0", + "@babel/plugin-transform-parameters": "^7.0.0", + "@babel/plugin-transform-react-display-name": "^7.0.0", + "@babel/plugin-transform-react-jsx": "^7.0.0", + "@babel/plugin-transform-react-jsx-self": "^7.0.0", + "@babel/plugin-transform-react-jsx-source": "^7.0.0", + "@babel/plugin-transform-runtime": "^7.0.0", + "@babel/plugin-transform-shorthand-properties": "^7.0.0", + "@babel/plugin-transform-spread": "^7.0.0", + "@babel/plugin-transform-sticky-regex": "^7.0.0", + "@babel/plugin-transform-typescript": "^7.5.0", + "@babel/plugin-transform-unicode-regex": "^7.0.0", + "@babel/template": "^7.0.0", + "babel-plugin-transform-flow-enums": "^0.0.2", + "react-refresh": "^0.4.0" + }, + "engines": { + "node": ">=16" + }, + "peerDependencies": { + "@babel/core": "*" + } + }, + "node_modules/metro-react-native-babel-transformer": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-react-native-babel-transformer/-/metro-react-native-babel-transformer-0.76.7.tgz", + "integrity": "sha512-W6lW3J7y/05ph3c2p3KKJNhH0IdyxdOCbQ5it7aM2MAl0SM4wgKjaV6EYv9b3rHklpV6K3qMH37UKVcjMooWiA==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/core": "^7.20.0", + "babel-preset-fbjs": "^3.4.0", + "hermes-parser": "0.12.0", + "metro-react-native-babel-preset": "0.76.7", + "nullthrows": "^1.1.1" + }, + "engines": { + "node": ">=16" + }, + "peerDependencies": { + "@babel/core": "*" + } + }, + "node_modules/metro-resolver": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-resolver/-/metro-resolver-0.76.7.tgz", + "integrity": "sha512-pC0Wgq29HHIHrwz23xxiNgylhI8Rq1V01kQaJ9Kz11zWrIdlrH0ZdnJ7GC6qA0ErROG+cXmJ0rJb8/SW1Zp2IA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-runtime": { + "version": "0.76.8", + "resolved": "https://registry.npmjs.org/metro-runtime/-/metro-runtime-0.76.8.tgz", + "integrity": "sha512-XKahvB+iuYJSCr3QqCpROli4B4zASAYpkK+j3a0CJmokxCDNbgyI4Fp88uIL6rNaZfN0Mv35S0b99SdFXIfHjg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/runtime": "^7.0.0", + "react-refresh": "^0.4.0" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-source-map": { + "version": "0.76.8", + "resolved": "https://registry.npmjs.org/metro-source-map/-/metro-source-map-0.76.8.tgz", + "integrity": "sha512-Hh0ncPsHPVf6wXQSqJqB3K9Zbudht4aUtNpNXYXSxH+pteWqGAXnjtPsRAnCsCWl38wL0jYF0rJDdMajUI3BDw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/traverse": "^7.20.0", + "@babel/types": "^7.20.0", + "invariant": "^2.2.4", + "metro-symbolicate": "0.76.8", + "nullthrows": "^1.1.1", + "ob1": "0.76.8", + "source-map": "^0.5.6", + "vlq": "^1.0.0" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-source-map/node_modules/metro-symbolicate": { + "version": "0.76.8", + "resolved": "https://registry.npmjs.org/metro-symbolicate/-/metro-symbolicate-0.76.8.tgz", + "integrity": "sha512-LrRL3uy2VkzrIXVlxoPtqb40J6Bf1mlPNmUQewipc3qfKKFgtPHBackqDy1YL0njDsWopCKcfGtFYLn0PTUn3w==", + "license": "MIT", + "peer": true, + "dependencies": { + "invariant": "^2.2.4", + "metro-source-map": "0.76.8", + "nullthrows": "^1.1.1", + "source-map": "^0.5.6", + "through2": "^2.0.1", + "vlq": "^1.0.0" + }, + "bin": { + "metro-symbolicate": "src/index.js" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-source-map/node_modules/source-map": { + "version": "0.5.7", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.5.7.tgz", + "integrity": "sha512-LbrmJOMUSdEVxIKvdcJzQC+nQhe8FUZQTXQy6+I75skNgn3OoQ0DZA8YnFa7gp8tqtL3KPf1kmo0R5DoApeSGQ==", + "license": "BSD-3-Clause", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/metro-symbolicate": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-symbolicate/-/metro-symbolicate-0.76.7.tgz", + "integrity": "sha512-p0zWEME5qLSL1bJb93iq+zt5fz3sfVn9xFYzca1TJIpY5MommEaS64Va87lp56O0sfEIvh4307Oaf/ZzRjuLiQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "invariant": "^2.2.4", + "metro-source-map": "0.76.7", + "nullthrows": "^1.1.1", + "source-map": "^0.5.6", + "through2": "^2.0.1", + "vlq": "^1.0.0" + }, + "bin": { + "metro-symbolicate": "src/index.js" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-symbolicate/node_modules/metro-source-map": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-source-map/-/metro-source-map-0.76.7.tgz", + "integrity": "sha512-Prhx7PeRV1LuogT0Kn5VjCuFu9fVD68eefntdWabrksmNY6mXK8pRqzvNJOhTojh6nek+RxBzZeD6MIOOyXS6w==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/traverse": "^7.20.0", + "@babel/types": "^7.20.0", + "invariant": "^2.2.4", + "metro-symbolicate": "0.76.7", + "nullthrows": "^1.1.1", + "ob1": "0.76.7", + "source-map": "^0.5.6", + "vlq": "^1.0.0" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-symbolicate/node_modules/ob1": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/ob1/-/ob1-0.76.7.tgz", + "integrity": "sha512-BQdRtxxoUNfSoZxqeBGOyuT9nEYSn18xZHwGMb0mMVpn2NBcYbnyKY4BK2LIHRgw33CBGlUmE+KMaNvyTpLLtQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-symbolicate/node_modules/source-map": { + "version": "0.5.7", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.5.7.tgz", + "integrity": "sha512-LbrmJOMUSdEVxIKvdcJzQC+nQhe8FUZQTXQy6+I75skNgn3OoQ0DZA8YnFa7gp8tqtL3KPf1kmo0R5DoApeSGQ==", + "license": "BSD-3-Clause", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/metro-transform-plugins": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-transform-plugins/-/metro-transform-plugins-0.76.7.tgz", + "integrity": "sha512-iSmnjVApbdivjuzb88Orb0JHvcEt5veVyFAzxiS5h0QB+zV79w6JCSqZlHCrbNOkOKBED//LqtKbFVakxllnNg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/core": "^7.20.0", + "@babel/generator": "^7.20.0", + "@babel/template": "^7.0.0", + "@babel/traverse": "^7.20.0", + "nullthrows": "^1.1.1" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-transform-worker": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-transform-worker/-/metro-transform-worker-0.76.7.tgz", + "integrity": "sha512-cGvELqFMVk9XTC15CMVzrCzcO6sO1lURfcbgjuuPdzaWuD11eEyocvkTX0DPiRjsvgAmicz4XYxVzgYl3MykDw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/core": "^7.20.0", + "@babel/generator": "^7.20.0", + "@babel/parser": "^7.20.0", + "@babel/types": "^7.20.0", + "babel-preset-fbjs": "^3.4.0", + "metro": "0.76.7", + "metro-babel-transformer": "0.76.7", + "metro-cache": "0.76.7", + "metro-cache-key": "0.76.7", + "metro-source-map": "0.76.7", + "metro-transform-plugins": "0.76.7", + "nullthrows": "^1.1.1" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-transform-worker/node_modules/metro-source-map": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-source-map/-/metro-source-map-0.76.7.tgz", + "integrity": "sha512-Prhx7PeRV1LuogT0Kn5VjCuFu9fVD68eefntdWabrksmNY6mXK8pRqzvNJOhTojh6nek+RxBzZeD6MIOOyXS6w==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/traverse": "^7.20.0", + "@babel/types": "^7.20.0", + "invariant": "^2.2.4", + "metro-symbolicate": "0.76.7", + "nullthrows": "^1.1.1", + "ob1": "0.76.7", + "source-map": "^0.5.6", + "vlq": "^1.0.0" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-transform-worker/node_modules/ob1": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/ob1/-/ob1-0.76.7.tgz", + "integrity": "sha512-BQdRtxxoUNfSoZxqeBGOyuT9nEYSn18xZHwGMb0mMVpn2NBcYbnyKY4BK2LIHRgw33CBGlUmE+KMaNvyTpLLtQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro-transform-worker/node_modules/source-map": { + "version": "0.5.7", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.5.7.tgz", + "integrity": "sha512-LbrmJOMUSdEVxIKvdcJzQC+nQhe8FUZQTXQy6+I75skNgn3OoQ0DZA8YnFa7gp8tqtL3KPf1kmo0R5DoApeSGQ==", + "license": "BSD-3-Clause", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/metro/node_modules/ci-info": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ci-info/-/ci-info-2.0.0.tgz", + "integrity": "sha512-5tK7EtrZ0N+OLFMthtqOj4fI2Jeb88C4CAZPu25LDVUgXJ0A3Js4PMGqrn0JU1W0Mh1/Z8wZzYPxqUrXeBboCQ==", + "license": "MIT", + "peer": true + }, + "node_modules/metro/node_modules/debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "license": "MIT", + "peer": true, + "dependencies": { + "ms": "2.0.0" + } + }, + "node_modules/metro/node_modules/metro-runtime": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-runtime/-/metro-runtime-0.76.7.tgz", + "integrity": "sha512-MuWHubQHymUWBpZLwuKZQgA/qbb35WnDAKPo83rk7JRLIFPvzXSvFaC18voPuzJBt1V98lKQIonh6MiC9gd8Ug==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/runtime": "^7.0.0", + "react-refresh": "^0.4.0" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro/node_modules/metro-source-map": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/metro-source-map/-/metro-source-map-0.76.7.tgz", + "integrity": "sha512-Prhx7PeRV1LuogT0Kn5VjCuFu9fVD68eefntdWabrksmNY6mXK8pRqzvNJOhTojh6nek+RxBzZeD6MIOOyXS6w==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/traverse": "^7.20.0", + "@babel/types": "^7.20.0", + "invariant": "^2.2.4", + "metro-symbolicate": "0.76.7", + "nullthrows": "^1.1.1", + "ob1": "0.76.7", + "source-map": "^0.5.6", + "vlq": "^1.0.0" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro/node_modules/ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "license": "MIT", + "peer": true + }, + "node_modules/metro/node_modules/ob1": { + "version": "0.76.7", + "resolved": "https://registry.npmjs.org/ob1/-/ob1-0.76.7.tgz", + "integrity": "sha512-BQdRtxxoUNfSoZxqeBGOyuT9nEYSn18xZHwGMb0mMVpn2NBcYbnyKY4BK2LIHRgw33CBGlUmE+KMaNvyTpLLtQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=16" + } + }, + "node_modules/metro/node_modules/source-map": { + "version": "0.5.7", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.5.7.tgz", + "integrity": "sha512-LbrmJOMUSdEVxIKvdcJzQC+nQhe8FUZQTXQy6+I75skNgn3OoQ0DZA8YnFa7gp8tqtL3KPf1kmo0R5DoApeSGQ==", + "license": "BSD-3-Clause", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/metro/node_modules/ws": { + "version": "7.5.9", + "resolved": "https://registry.npmjs.org/ws/-/ws-7.5.9.tgz", + "integrity": "sha512-F+P9Jil7UiSKSkppIiD94dN07AwvFixvLIj1Og1Rl9GGMuNipJnV9JzjD6XuqmAeiswGvUmNLjr5cFuXwNS77Q==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=8.3.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": "^5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + }, + "node_modules/micromark": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/micromark/-/micromark-4.0.1.tgz", + "integrity": "sha512-eBPdkcoCNvYcxQOAKAlceo5SNdzZWfF+FcSupREAzdAh9rRmE239CEQAiTwIgblwnoM8zzj35sZ5ZwvSEOF6Kw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/debug": "^4.0.0", + "debug": "^4.0.0", + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-combine-extensions": "^2.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-core-commonmark": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-core-commonmark/-/micromark-core-commonmark-2.0.2.tgz", + "integrity": "sha512-FKjQKbxd1cibWMM1P9N+H8TwlgGgSkWZMmfuVucLCHaYqeSvJ0hFeHsIa65pA2nYbes0f8LDHPMrd9X7Ujxg9w==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-destination": "^2.0.0", + "micromark-factory-label": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-factory-title": "^2.0.0", + "micromark-factory-whitespace": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-html-tag-name": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-extension-mdx-expression": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-mdx-expression/-/micromark-extension-mdx-expression-3.0.0.tgz", + "integrity": "sha512-sI0nwhUDz97xyzqJAbHQhp5TfaxEvZZZ2JDqUo+7NvyIYG6BZ5CPPqj2ogUoPJlmXHBnyZUzISg9+oUmU6tUjQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-mdx-expression": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-extension-mdx-jsx": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/micromark-extension-mdx-jsx/-/micromark-extension-mdx-jsx-3.0.1.tgz", + "integrity": "sha512-vNuFb9czP8QCtAQcEJn0UJQJZA8Dk6DXKBqx+bg/w0WGuSxDxNr7hErW89tHUY31dUW4NqEOWwmEUNhjTFmHkg==", + "license": "MIT", + "dependencies": { + "@types/acorn": "^4.0.0", + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "micromark-factory-mdx-expression": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-mdx-md": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-mdx-md/-/micromark-extension-mdx-md-2.0.0.tgz", + "integrity": "sha512-EpAiszsB3blw4Rpba7xTOUptcFeBFi+6PY8VnJ2hhimH+vCQDirWgsMpz7w1XcZE7LVrSAUGb9VJpG9ghlYvYQ==", + "license": "MIT", + "dependencies": { + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-mdxjs": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-mdxjs/-/micromark-extension-mdxjs-3.0.0.tgz", + "integrity": "sha512-A873fJfhnJ2siZyUrJ31l34Uqwy4xIFmvPY1oj+Ean5PHcPBYzEsvqvWGaWcfEIr11O5Dlw3p2y0tZWpKHDejQ==", + "license": "MIT", + "dependencies": { + "acorn": "^8.0.0", + "acorn-jsx": "^5.0.0", + "micromark-extension-mdx-expression": "^3.0.0", + "micromark-extension-mdx-jsx": "^3.0.0", + "micromark-extension-mdx-md": "^2.0.0", + "micromark-extension-mdxjs-esm": "^3.0.0", + "micromark-util-combine-extensions": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-mdxjs-esm": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-mdxjs-esm/-/micromark-extension-mdxjs-esm-3.0.0.tgz", + "integrity": "sha512-DJFl4ZqkErRpq/dAPyeWp15tGrcrrJho1hKK5uBS70BCtfrIFg81sqcTVu3Ta+KD1Tk5vAtBNElWxtAa+m8K9A==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unist-util-position-from-estree": "^2.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-factory-destination": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-destination/-/micromark-factory-destination-2.0.1.tgz", + "integrity": "sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-label": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-label/-/micromark-factory-label-2.0.1.tgz", + "integrity": "sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-mdx-expression": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-factory-mdx-expression/-/micromark-factory-mdx-expression-2.0.2.tgz", + "integrity": "sha512-5E5I2pFzJyg2CtemqAbcyCktpHXuJbABnsb32wX2U8IQKhhVFBqkcZR5LRm1WVoFqa4kTueZK4abep7wdo9nrw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unist-util-position-from-estree": "^2.0.0", + "vfile-message": "^4.0.0" + } + }, + "node_modules/micromark-factory-space": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-space/-/micromark-factory-space-2.0.1.tgz", + "integrity": "sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-title": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-title/-/micromark-factory-title-2.0.1.tgz", + "integrity": "sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-whitespace": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-whitespace/-/micromark-factory-whitespace-2.0.1.tgz", + "integrity": "sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-character": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-2.1.1.tgz", + "integrity": "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-chunked": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-chunked/-/micromark-util-chunked-2.0.1.tgz", + "integrity": "sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-classify-character": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-classify-character/-/micromark-util-classify-character-2.0.1.tgz", + "integrity": "sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-combine-extensions": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-combine-extensions/-/micromark-util-combine-extensions-2.0.1.tgz", + "integrity": "sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-chunked": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-decode-numeric-character-reference": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-util-decode-numeric-character-reference/-/micromark-util-decode-numeric-character-reference-2.0.2.tgz", + "integrity": "sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-decode-string": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-decode-string/-/micromark-util-decode-string-2.0.1.tgz", + "integrity": "sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-encode": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-encode/-/micromark-util-encode-2.0.1.tgz", + "integrity": "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-events-to-acorn": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-util-events-to-acorn/-/micromark-util-events-to-acorn-2.0.2.tgz", + "integrity": "sha512-Fk+xmBrOv9QZnEDguL9OI9/NQQp6Hz4FuQ4YmCb/5V7+9eAh1s6AYSvL20kHkD67YIg7EpE54TiSlcsf3vyZgA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/acorn": "^4.0.0", + "@types/estree": "^1.0.0", + "@types/unist": "^3.0.0", + "devlop": "^1.0.0", + "estree-util-visit": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "vfile-message": "^4.0.0" + } + }, + "node_modules/micromark-util-events-to-acorn/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/micromark-util-html-tag-name": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-html-tag-name/-/micromark-util-html-tag-name-2.0.1.tgz", + "integrity": "sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-normalize-identifier": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-normalize-identifier/-/micromark-util-normalize-identifier-2.0.1.tgz", + "integrity": "sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-resolve-all": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-resolve-all/-/micromark-util-resolve-all-2.0.1.tgz", + "integrity": "sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-sanitize-uri": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-2.0.1.tgz", + "integrity": "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-subtokenize": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/micromark-util-subtokenize/-/micromark-util-subtokenize-2.0.4.tgz", + "integrity": "sha512-N6hXjrin2GTJDe3MVjf5FuXpm12PGm80BrUAeub9XFXca8JZbP+oIwY4LJSVwFUCL1IPm/WwSVUN7goFHmSGGQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-symbol": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-symbol/-/micromark-util-symbol-2.0.1.tgz", + "integrity": "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-types": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-2.0.1.tgz", + "integrity": "sha512-534m2WhVTddrcKVepwmVEVnUAmtrx9bfIjNoQHRqfnvdaHQiFytEhJoTgpWJvDEXCO5gLTQh3wYC1PgOJA4NSQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromatch": { + "version": "4.0.5", + "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.5.tgz", + "integrity": "sha512-DMy+ERcEW2q8Z2Po+WNXuw3c5YaUSFjAO5GsJqfEl7UjvtIuFKO6ZrKvcItdy98dwFI2N1tg3zNIdKaQT+aNdA==", + "license": "MIT", + "dependencies": { + "braces": "^3.0.2", + "picomatch": "^2.3.1" + }, + "engines": { + "node": ">=8.6" + } + }, + "node_modules/mime": { + "version": "2.6.0", + "resolved": "https://registry.npmjs.org/mime/-/mime-2.6.0.tgz", + "integrity": "sha512-USPkMeET31rOMiarsBNIHZKLGgvKc/LrjofAnBlOttf5ajRvqiRA8QsenbcooctK6d6Ts6aqZXBA+XbkKthiQg==", + "license": "MIT", + "peer": true, + "bin": { + "mime": "cli.js" + }, + "engines": { + "node": ">=4.0.0" + } + }, + "node_modules/mime-db": { + "version": "1.52.0", + "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz", + "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/mime-types": { + "version": "2.1.35", + "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz", + "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==", + "license": "MIT", + "dependencies": { + "mime-db": "1.52.0" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/mimic-fn": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/mimic-fn/-/mimic-fn-2.1.0.tgz", + "integrity": "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/minimatch": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", + "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==", + "license": "ISC", + "dependencies": { + "brace-expansion": "^1.1.7" + }, + "engines": { + "node": "*" + } + }, + "node_modules/minimist": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz", + "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/minipass": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/minipass/-/minipass-5.0.0.tgz", + "integrity": "sha512-3FnjYuehv9k6ovOEbyOswadCDPX1piCfhV8ncmYtHOjuPwylVWsghTLo7rabjC3Rx5xD4HDx8Wm1xnMF7S5qFQ==", + "license": "ISC", + "engines": { + "node": ">=8" + } + }, + "node_modules/minizlib": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-2.1.2.tgz", + "integrity": "sha512-bAxsR8BVfj60DWXHE3u30oHzfl4G7khkSuPW+qvpd7jFRHm7dLxOjUk1EHACJ/hxLY8phGJ0YhYHZo7jil7Qdg==", + "license": "MIT", + "dependencies": { + "minipass": "^3.0.0", + "yallist": "^4.0.0" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/minizlib/node_modules/minipass": { + "version": "3.3.6", + "resolved": "https://registry.npmjs.org/minipass/-/minipass-3.3.6.tgz", + "integrity": "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==", + "license": "ISC", + "dependencies": { + "yallist": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/mkdirp": { + "version": "0.5.6", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.6.tgz", + "integrity": "sha512-FP+p8RB8OWpF3YZBCrP5gtADmtXApB5AMLn+vdyA+PyxCjrCs00mjyUozssO33cwDeT3wNGdLxJ5M//YqtHAJw==", + "license": "MIT", + "peer": true, + "dependencies": { + "minimist": "^1.2.6" + }, + "bin": { + "mkdirp": "bin/cmd.js" + } + }, + "node_modules/monaco-editor": { + "version": "0.52.2", + "resolved": "https://registry.npmjs.org/monaco-editor/-/monaco-editor-0.52.2.tgz", + "integrity": "sha512-GEQWEZmfkOGLdd3XK8ryrfWz3AIP8YymVXiPHEdewrUq7mh0qrKrfHLNCXcbB6sTnMLnOZ3ztSiKcciFUkIJwQ==", + "license": "MIT", + "peer": true + }, + "node_modules/mri": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/mri/-/mri-1.2.0.tgz", + "integrity": "sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==", + "license": "MIT", + "engines": { + "node": ">=4" + } + }, + "node_modules/ms": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz", + "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==", + "license": "MIT" + }, + "node_modules/mz": { + "version": "2.7.0", + "resolved": "https://registry.npmjs.org/mz/-/mz-2.7.0.tgz", + "integrity": "sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==", + "license": "MIT", + "dependencies": { + "any-promise": "^1.0.0", + "object-assign": "^4.0.1", + "thenify-all": "^1.0.0" + } + }, + "node_modules/nanoid": { + "version": "3.3.6", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.6.tgz", + "integrity": "sha512-BGcqMMJuToF7i1rt+2PWSNVnWIkGCU78jBG3RxO/bZlnZPK2Cmi2QaffxGO/2RvWi9sL+FAiRiXMgsyxQ1DIDA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "bin": { + "nanoid": "bin/nanoid.cjs" + }, + "engines": { + "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" + } + }, + "node_modules/natural-compare": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/natural-compare/-/natural-compare-1.4.0.tgz", + "integrity": "sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==", + "dev": true, + "license": "MIT" + }, + "node_modules/natural-compare-lite": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/natural-compare-lite/-/natural-compare-lite-1.4.0.tgz", + "integrity": "sha512-Tj+HTDSJJKaZnfiuw+iaF9skdPpTo2GtEly5JHnWV/hfv2Qj/9RKsGISQtLh2ox3l5EAGw487hnBee0sIJ6v2g==", + "dev": true, + "license": "MIT" + }, + "node_modules/negotiator": { + "version": "0.6.3", + "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-0.6.3.tgz", + "integrity": "sha512-+EUsqGPLsM+j/zdChZjsnX51g4XrHFOIXwfnCVPGlQk/k5giakcKsuxCObBRu6DSm9opw/O6slWbJdghQM4bBg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/neo-async": { + "version": "2.6.2", + "resolved": "https://registry.npmjs.org/neo-async/-/neo-async-2.6.2.tgz", + "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==", + "license": "MIT", + "peer": true + }, + "node_modules/next": { + "version": "13.4.16", + "resolved": "https://registry.npmjs.org/next/-/next-13.4.16.tgz", + "integrity": "sha512-1xaA/5DrfpPu0eV31Iro7JfPeqO8uxQWb1zYNTe+KDKdzqkAGapLcDYHMLNKXKB7lHjZ7LfKUOf9dyuzcibrhA==", + "license": "MIT", + "dependencies": { + "@next/env": "13.4.16", + "@swc/helpers": "0.5.1", + "busboy": "1.6.0", + "caniuse-lite": "^1.0.30001406", + "postcss": "8.4.14", + "styled-jsx": "5.1.1", + "watchpack": "2.4.0", + "zod": "3.21.4" + }, + "bin": { + "next": "dist/bin/next" + }, + "engines": { + "node": ">=16.8.0" + }, + "optionalDependencies": { + "@next/swc-darwin-arm64": "13.4.16", + "@next/swc-darwin-x64": "13.4.16", + "@next/swc-linux-arm64-gnu": "13.4.16", + "@next/swc-linux-arm64-musl": "13.4.16", + "@next/swc-linux-x64-gnu": "13.4.16", + "@next/swc-linux-x64-musl": "13.4.16", + "@next/swc-win32-arm64-msvc": "13.4.16", + "@next/swc-win32-ia32-msvc": "13.4.16", + "@next/swc-win32-x64-msvc": "13.4.16" + }, + "peerDependencies": { + "@opentelemetry/api": "^1.1.0", + "react": "^18.2.0", + "react-dom": "^18.2.0", + "sass": "^1.3.0" + }, + "peerDependenciesMeta": { + "@opentelemetry/api": { + "optional": true + }, + "sass": { + "optional": true + } + } + }, + "node_modules/next-auth": { + "version": "4.23.1", + "resolved": "https://registry.npmjs.org/next-auth/-/next-auth-4.23.1.tgz", + "integrity": "sha512-mL083z8KgRtlrIV6CDca2H1kduWJuK/3pTS0Fe2og15KOm4v2kkLGdSDfc2g+019aEBrJUT0pPW2Xx42ImN1WA==", + "license": "ISC", + "dependencies": { + "@babel/runtime": "^7.20.13", + "@panva/hkdf": "^1.0.2", + "cookie": "^0.5.0", + "jose": "^4.11.4", + "oauth": "^0.9.15", + "openid-client": "^5.4.0", + "preact": "^10.6.3", + "preact-render-to-string": "^5.1.19", + "uuid": "^8.3.2" + }, + "peerDependencies": { + "next": "^12.2.5 || ^13", + "nodemailer": "^6.6.5", + "react": "^17.0.2 || ^18", + "react-dom": "^17.0.2 || ^18" + }, + "peerDependenciesMeta": { + "nodemailer": { + "optional": true + } + } + }, + "node_modules/next-themes": { + "version": "0.4.6", + "resolved": "https://registry.npmjs.org/next-themes/-/next-themes-0.4.6.tgz", + "integrity": "sha512-pZvgD5L0IEvX5/9GWyHMf3m8BKiVQwsCMHfoFosXtXBMnaS0ZnIJ9ST4b4NqLVKDEm8QBxoNNGNaBv2JNF6XNA==", + "license": "MIT", + "peerDependencies": { + "react": "^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc" + } + }, + "node_modules/next/node_modules/postcss": { + "version": "8.4.14", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.14.tgz", + "integrity": "sha512-E398TUmfAYFPBSdzgeieK2Y1+1cpdxJx8yXbK/m57nRhKSmk1GB2tO4lbLBtlkfPQTDKfe4Xqv1ASWPpayPEig==", + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/postcss" + } + ], + "license": "MIT", + "dependencies": { + "nanoid": "^3.3.4", + "picocolors": "^1.0.0", + "source-map-js": "^1.0.2" + }, + "engines": { + "node": "^10 || ^12 || >=14" + } + }, + "node_modules/next/node_modules/zod": { + "version": "3.21.4", + "resolved": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz", + "integrity": "sha512-m46AKbrzKVzOzs/DZgVnG5H55N1sv1M8qZU3A8RIKbs3mrACDNeIOeilDymVb2HdmP8uwshOCF4uJ8uM9rCqJw==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, + "node_modules/nocache": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/nocache/-/nocache-3.0.4.tgz", + "integrity": "sha512-WDD0bdg9mbq6F4mRxEYcPWwfA1vxd0mrvKOyxI7Xj/atfRHVeutzuWByG//jfm4uPzp0y4Kj051EORCBSQMycw==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=12.0.0" + } + }, + "node_modules/node-abort-controller": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/node-abort-controller/-/node-abort-controller-3.1.1.tgz", + "integrity": "sha512-AGK2yQKIjRuqnc6VkX2Xj5d+QW8xZ87pa1UK6yA6ouUyuxfHuMP6umE5QK7UmTeOAymo+Zx1Fxiuw9rVx8taHQ==", + "license": "MIT", + "peer": true + }, + "node_modules/node-addon-api": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-5.1.0.tgz", + "integrity": "sha512-eh0GgfEkpnoWDq+VY8OyvYhFEzBk6jIYbRKdIlyTiAXIVJ8PyBaKb0rp7oDtoddbdoHWhq8wwr+XZ81F1rpNdA==", + "license": "MIT" + }, + "node_modules/node-dir": { + "version": "0.1.17", + "resolved": "https://registry.npmjs.org/node-dir/-/node-dir-0.1.17.tgz", + "integrity": "sha512-tmPX422rYgofd4epzrNoOXiE8XFZYOcCq1vD7MAXCDO+O+zndlA2ztdKKMa+EeuBG5tHETpr4ml4RGgpqDCCAg==", + "license": "MIT", + "peer": true, + "dependencies": { + "minimatch": "^3.0.2" + }, + "engines": { + "node": ">= 0.10.5" + } + }, + "node_modules/node-fetch": { + "version": "2.6.12", + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.12.tgz", + "integrity": "sha512-C/fGU2E8ToujUivIO0H+tpQ6HWo4eEmchoPIoXtxCrVghxdKq+QOHqEZW7tuP3KlV3bC8FRMO5nMCC7Zm1VP6g==", + "license": "MIT", + "dependencies": { + "whatwg-url": "^5.0.0" + }, + "engines": { + "node": "4.x || >=6.0.0" + }, + "peerDependencies": { + "encoding": "^0.1.0" + }, + "peerDependenciesMeta": { + "encoding": { + "optional": true + } + } + }, + "node_modules/node-int64": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/node-int64/-/node-int64-0.4.0.tgz", + "integrity": "sha512-O5lz91xSOeoXP6DulyHfllpq+Eg00MWitZIbtPfoSEvqIHdl5gfcY6hYzDWnj0qD5tz52PI08u9qUvSVeUBeHw==", + "license": "MIT", + "peer": true + }, + "node_modules/node-releases": { + "version": "2.0.13", + "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.13.tgz", + "integrity": "sha512-uYr7J37ae/ORWdZeQ1xxMJe3NtdmqMC/JZK+geofDrkLUApKRHPd18/TxtBOJ4A0/+uUIliorNrfYV6s1b02eQ==", + "license": "MIT" + }, + "node_modules/node-stream-zip": { + "version": "1.15.0", + "resolved": "https://registry.npmjs.org/node-stream-zip/-/node-stream-zip-1.15.0.tgz", + "integrity": "sha512-LN4fydt9TqhZhThkZIVQnF9cwjU3qmUH9h78Mx/K7d3VvfRqqwthLwJEUOEL0QPZ0XQmNN7be5Ggit5+4dq3Bw==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.12.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/antelle" + } + }, + "node_modules/nopt": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/nopt/-/nopt-5.0.0.tgz", + "integrity": "sha512-Tbj67rffqceeLpcRXrT7vKAN8CwfPeIBgM7E6iBkmKLV7bEMwpGgYLGv0jACUsECaa/vuxP0IjEont6umdMgtQ==", + "license": "ISC", + "dependencies": { + "abbrev": "1" + }, + "bin": { + "nopt": "bin/nopt.js" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/normalize-path": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz", + "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/normalize-range": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/normalize-range/-/normalize-range-0.1.2.tgz", + "integrity": "sha512-bdok/XvKII3nUpklnV6P2hxtMNrCboOjAcyBuQnWEhO665FwrSNRxU+AqpsyvO6LgGYPspN+lu5CLtw4jPRKNA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/npm-run-path": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/npm-run-path/-/npm-run-path-4.0.1.tgz", + "integrity": "sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw==", + "license": "MIT", + "peer": true, + "dependencies": { + "path-key": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/npmlog": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/npmlog/-/npmlog-5.0.1.tgz", + "integrity": "sha512-AqZtDUWOMKs1G/8lwylVjrdYgqA4d9nu8hc+0gzRxlDb1I10+FHBGMXs6aiQHFdCUUlqH99MUMuLfzWDNDtfxw==", + "deprecated": "This package is no longer supported.", + "license": "ISC", + "dependencies": { + "are-we-there-yet": "^2.0.0", + "console-control-strings": "^1.1.0", + "gauge": "^3.0.0", + "set-blocking": "^2.0.0" + } + }, + "node_modules/nullthrows": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/nullthrows/-/nullthrows-1.1.1.tgz", + "integrity": "sha512-2vPPEi+Z7WqML2jZYddDIfy5Dqb0r2fze2zTxNNknZaFpVHU3mFB3R+DWeJWGVx0ecvttSGlJTI+WG+8Z4cDWw==", + "license": "MIT", + "peer": true + }, + "node_modules/oauth": { + "version": "0.9.15", + "resolved": "https://registry.npmjs.org/oauth/-/oauth-0.9.15.tgz", + "integrity": "sha512-a5ERWK1kh38ExDEfoO6qUHJb32rd7aYmPHuyCu3Fta/cnICvYmgd2uhuKXvPD+PXB+gCEYYEaQdIRAjCOwAKNA==", + "license": "MIT" + }, + "node_modules/ob1": { + "version": "0.76.8", + "resolved": "https://registry.npmjs.org/ob1/-/ob1-0.76.8.tgz", + "integrity": "sha512-dlBkJJV5M/msj9KYA9upc+nUWVwuOFFTbu28X6kZeGwcuW+JxaHSBZ70SYQnk5M+j5JbNLR6yKHmgW4M5E7X5g==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=16" + } + }, + "node_modules/object-assign": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", + "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/object-hash": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/object-hash/-/object-hash-2.2.0.tgz", + "integrity": "sha512-gScRMn0bS5fH+IuwyIFgnh9zBdo4DV+6GhygmWM9HyNJSgS0hScp1f5vjtm7oIIOiT9trXrShAkLFSc2IqKNgw==", + "license": "MIT", + "engines": { + "node": ">= 6" + } + }, + "node_modules/object-inspect": { + "version": "1.12.3", + "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.12.3.tgz", + "integrity": "sha512-geUvdk7c+eizMNUDkRpW1wJwgfOiOeHbxBR/hLXK1aT6zmVSO0jsQcs7fj6MGw89jC/cjGfLcNOrtMYtGqm81g==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/object-keys": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/object-keys/-/object-keys-1.1.1.tgz", + "integrity": "sha512-NuAESUOUMrlIXOfHKzD6bpPu3tYt3xvjNdRIQ+FeT0lNb4K8WR70CaDxhuNguS2XG+GjkyMwOzsN5ZktImfhLA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/object.assign": { + "version": "4.1.4", + "resolved": "https://registry.npmjs.org/object.assign/-/object.assign-4.1.4.tgz", + "integrity": "sha512-1mxKf0e58bvyjSCtKYY4sRe9itRk3PJpquJOjeIkz885CczcI4IvJJDLPS72oowuSh+pBxUFROpX+TU++hxhZQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "has-symbols": "^1.0.3", + "object-keys": "^1.1.1" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/object.entries": { + "version": "1.1.6", + "resolved": "https://registry.npmjs.org/object.entries/-/object.entries-1.1.6.tgz", + "integrity": "sha512-leTPzo4Zvg3pmbQ3rDK69Rl8GQvIqMWubrkxONG9/ojtFE2rD9fjMKfSI5BxW3osRH1m6VdzmqK8oAY9aT4x5w==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/object.fromentries": { + "version": "2.0.6", + "resolved": "https://registry.npmjs.org/object.fromentries/-/object.fromentries-2.0.6.tgz", + "integrity": "sha512-VciD13dswC4j1Xt5394WR4MzmAQmlgN72phd/riNp9vtD7tp4QQWJ0R4wvclXcafgcYK8veHRed2W6XeGBvcfg==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/object.groupby": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/object.groupby/-/object.groupby-1.0.0.tgz", + "integrity": "sha512-70MWG6NfRH9GnbZOikuhPPYzpUpof9iW2J9E4dW7FXTqPNb6rllE6u39SKwwiNh8lCwX3DDb5OgcKGiEBrTTyw==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.2.0", + "es-abstract": "^1.21.2", + "get-intrinsic": "^1.2.1" + } + }, + "node_modules/object.hasown": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/object.hasown/-/object.hasown-1.1.2.tgz", + "integrity": "sha512-B5UIT3J1W+WuWIU55h0mjlwaqxiE5vYENJXIXZ4VFe05pNYrkKuK0U/6aFcb0pKywYJh7IhfoqUfKVmrJJHZHw==", + "dev": true, + "license": "MIT", + "dependencies": { + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/object.values": { + "version": "1.1.6", + "resolved": "https://registry.npmjs.org/object.values/-/object.values-1.1.6.tgz", + "integrity": "sha512-FVVTkD1vENCsAcwNs9k6jea2uHC/X0+JcjG8YA60FN5CMaJmG95wT9jek/xX9nornqGRrBkKtzuAu2wuHpKqvw==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/oidc-token-hash": { + "version": "5.0.3", + "resolved": "https://registry.npmjs.org/oidc-token-hash/-/oidc-token-hash-5.0.3.tgz", + "integrity": "sha512-IF4PcGgzAr6XXSff26Sk/+P4KZFJVuHAJZj3wgO3vX2bMdNVp/QXTP3P7CEm9V1IdG8lDLY3HhiqpsE/nOwpPw==", + "license": "MIT", + "engines": { + "node": "^10.13.0 || >=12.0.0" + } + }, + "node_modules/on-finished": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.3.0.tgz", + "integrity": "sha512-ikqdkGAAyf/X/gPhXGvfgAytDZtDbr+bkNUJ0N9h5MI/dmdgCs3l6hoHrcUv41sRKew3jIwrp4qQDXiK99Utww==", + "license": "MIT", + "peer": true, + "dependencies": { + "ee-first": "1.1.1" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/on-headers": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/on-headers/-/on-headers-1.0.2.tgz", + "integrity": "sha512-pZAE+FJLoyITytdqK0U5s+FIpjN0JP3OzFi/u8Rx+EV5/W+JTWGXG8xFzevE7AjBfDqHv/8vL8qQsIhHnqRkrA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/once": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz", + "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==", + "license": "ISC", + "dependencies": { + "wrappy": "1" + } + }, + "node_modules/onetime": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/onetime/-/onetime-5.1.2.tgz", + "integrity": "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==", + "license": "MIT", + "peer": true, + "dependencies": { + "mimic-fn": "^2.1.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/open": { + "version": "6.4.0", + "resolved": "https://registry.npmjs.org/open/-/open-6.4.0.tgz", + "integrity": "sha512-IFenVPgF70fSm1keSd2iDBIDIBZkroLeuffXq+wKTzTJlBpesFWojV9lb8mzOfaAzM1sr7HQHuO0vtV0zYekGg==", + "license": "MIT", + "peer": true, + "dependencies": { + "is-wsl": "^1.1.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/openid-client": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/openid-client/-/openid-client-5.4.3.tgz", + "integrity": "sha512-sVQOvjsT/sbSfYsQI/9liWQGVZH/Pp3rrtlGEwgk/bbHfrUDZ24DN57lAagIwFtuEu+FM9Ev7r85s8S/yPjimQ==", + "license": "MIT", + "dependencies": { + "jose": "^4.14.4", + "lru-cache": "^6.0.0", + "object-hash": "^2.2.0", + "oidc-token-hash": "^5.0.3" + }, + "funding": { + "url": "https://github.com/sponsors/panva" + } + }, + "node_modules/optionator": { + "version": "0.9.3", + "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.3.tgz", + "integrity": "sha512-JjCoypp+jKn1ttEFExxhetCKeJt9zhAgAve5FXHixTvFDW/5aEktX9bufBKLRRMdU7bNtpLfcGu94B3cdEJgjg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@aashutoshrathi/word-wrap": "^1.2.3", + "deep-is": "^0.1.3", + "fast-levenshtein": "^2.0.6", + "levn": "^0.4.1", + "prelude-ls": "^1.2.1", + "type-check": "^0.4.0" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/ora": { + "version": "5.4.1", + "resolved": "https://registry.npmjs.org/ora/-/ora-5.4.1.tgz", + "integrity": "sha512-5b6Y85tPxZZ7QytO+BQzysW31HJku27cRIlkbAXaNx+BdcVi+LlRFmVXzeF6a7JCwJpyw5c4b+YSVImQIrBpuQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "bl": "^4.1.0", + "chalk": "^4.1.0", + "cli-cursor": "^3.1.0", + "cli-spinners": "^2.5.0", + "is-interactive": "^1.0.0", + "is-unicode-supported": "^0.1.0", + "log-symbols": "^4.1.0", + "strip-ansi": "^6.0.0", + "wcwidth": "^1.0.1" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/p-limit": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz", + "integrity": "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==", + "license": "MIT", + "dependencies": { + "yocto-queue": "^0.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/p-locate": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-5.0.0.tgz", + "integrity": "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==", + "license": "MIT", + "dependencies": { + "p-limit": "^3.0.2" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/p-try": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/p-try/-/p-try-2.2.0.tgz", + "integrity": "sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/parent-module": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz", + "integrity": "sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==", + "dev": true, + "license": "MIT", + "dependencies": { + "callsites": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/parse-entities": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/parse-entities/-/parse-entities-4.0.2.tgz", + "integrity": "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0", + "character-entities-legacy": "^3.0.0", + "character-reference-invalid": "^2.0.0", + "decode-named-character-reference": "^1.0.0", + "is-alphanumerical": "^2.0.0", + "is-decimal": "^2.0.0", + "is-hexadecimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/parse-json": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/parse-json/-/parse-json-4.0.0.tgz", + "integrity": "sha512-aOIos8bujGN93/8Ox/jPLh7RwVnPEysynVFE+fQZyg6jKELEHwzgKdLRFHUgXJL6kylijVSBC4BvN9OmsB48Rw==", + "license": "MIT", + "peer": true, + "dependencies": { + "error-ex": "^1.3.1", + "json-parse-better-errors": "^1.0.1" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/parseurl": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz", + "integrity": "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/path-exists": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", + "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/path-is-absolute": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz", + "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/path-parse": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/path-parse/-/path-parse-1.0.7.tgz", + "integrity": "sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==", + "license": "MIT" + }, + "node_modules/path-type": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz", + "integrity": "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/picocolors": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.0.0.tgz", + "integrity": "sha512-1fygroTLlHu66zi26VoTDv8yRgm0Fccecssto+MhsZ0D/DGW2sm8E8AjW7NU5VVTRt5GxbeZ5qBuJr+HyLYkjQ==", + "license": "ISC" + }, + "node_modules/picomatch": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", + "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", + "license": "MIT", + "engines": { + "node": ">=8.6" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, + "node_modules/pify": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", + "integrity": "sha512-udgsAY+fTnvv7kI7aaxbqwWNb0AHiB0qBO89PZKPkoTmGOgdbrHDKD+0B2X4uTfJ/FT1R09r9gTsjUjNJotuog==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/pirates": { + "version": "4.0.6", + "resolved": "https://registry.npmjs.org/pirates/-/pirates-4.0.6.tgz", + "integrity": "sha512-saLsH7WeYYPiD25LDuLRRY/i+6HaPYr6G1OUlN39otzkSTxKnubR9RTxS3/Kk50s1g2JTgFwWQDQyplC5/SHZg==", + "license": "MIT", + "engines": { + "node": ">= 6" + } + }, + "node_modules/pkg-dir": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/pkg-dir/-/pkg-dir-3.0.0.tgz", + "integrity": "sha512-/E57AYkoeQ25qkxMj5PBOVgF8Kiu/h7cYS30Z5+R7WaiCCBfLq58ZI/dSeaEKb9WVJV5n/03QwrN3IeWIFllvw==", + "license": "MIT", + "peer": true, + "dependencies": { + "find-up": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/pkg-dir/node_modules/find-up": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-3.0.0.tgz", + "integrity": "sha512-1yD6RmLI1XBfxugvORwlck6f75tYL+iR0jqwsOrOxMZyGYqUuDhJ0l4AXdO1iX/FTs9cBAMEk1gWSEx1kSbylg==", + "license": "MIT", + "peer": true, + "dependencies": { + "locate-path": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/pkg-dir/node_modules/locate-path": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-3.0.0.tgz", + "integrity": "sha512-7AO748wWnIhNqAuaty2ZWHkQHRSNfPVIsPIfwEOWO22AmaoVrWavlOcMR5nzTLNYvp36X220/maaRsrec1G65A==", + "license": "MIT", + "peer": true, + "dependencies": { + "p-locate": "^3.0.0", + "path-exists": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/pkg-dir/node_modules/p-limit": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", + "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", + "license": "MIT", + "peer": true, + "dependencies": { + "p-try": "^2.0.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/pkg-dir/node_modules/p-locate": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-3.0.0.tgz", + "integrity": "sha512-x+12w/To+4GFfgJhBEpiDcLozRJGegY+Ei7/z0tSLkMmxGZNybVMSfWj9aJn8Z5Fc7dBUNJOOVgPv2H7IwulSQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "p-limit": "^2.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/pkg-dir/node_modules/path-exists": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-3.0.0.tgz", + "integrity": "sha512-bpC7GYwiDYQ4wYLe+FA8lhRjhQCMcQGuSgGGqDkg/QerRWw9CmGRT0iSOVRSZJ29NMLZgIzqaljJ63oaL4NIJQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/postcss": { + "version": "8.4.28", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.28.tgz", + "integrity": "sha512-Z7V5j0cq8oEKyejIKfpD8b4eBy9cwW2JWPk0+fB1HOAMsfHbnAXLLS+PfVWlzMSLQaWttKDt607I0XHmpE67Vw==", + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/postcss" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "nanoid": "^3.3.6", + "picocolors": "^1.0.0", + "source-map-js": "^1.0.2" + }, + "engines": { + "node": "^10 || ^12 || >=14" + } + }, + "node_modules/postcss-import": { + "version": "15.1.0", + "resolved": "https://registry.npmjs.org/postcss-import/-/postcss-import-15.1.0.tgz", + "integrity": "sha512-hpr+J05B2FVYUAXHeK1YyI267J/dDDhMU6B6civm8hSY1jYJnBXxzKDKDswzJmtLHryrjhnDjqqp/49t8FALew==", + "license": "MIT", + "dependencies": { + "postcss-value-parser": "^4.0.0", + "read-cache": "^1.0.0", + "resolve": "^1.1.7" + }, + "engines": { + "node": ">=14.0.0" + }, + "peerDependencies": { + "postcss": "^8.0.0" + } + }, + "node_modules/postcss-js": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/postcss-js/-/postcss-js-4.0.1.tgz", + "integrity": "sha512-dDLF8pEO191hJMtlHFPRa8xsizHaM82MLfNkUHdUtVEV3tgTp5oj+8qbEqYM57SLfc74KSbw//4SeJma2LRVIw==", + "license": "MIT", + "dependencies": { + "camelcase-css": "^2.0.1" + }, + "engines": { + "node": "^12 || ^14 || >= 16" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + "peerDependencies": { + "postcss": "^8.4.21" + } + }, + "node_modules/postcss-load-config": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/postcss-load-config/-/postcss-load-config-4.0.1.tgz", + "integrity": "sha512-vEJIc8RdiBRu3oRAI0ymerOn+7rPuMvRXslTvZUKZonDHFIczxztIyJ1urxM1x9JXEikvpWWTUUqal5j/8QgvA==", + "license": "MIT", + "dependencies": { + "lilconfig": "^2.0.5", + "yaml": "^2.1.1" + }, + "engines": { + "node": ">= 14" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + "peerDependencies": { + "postcss": ">=8.0.9", + "ts-node": ">=9.0.0" + }, + "peerDependenciesMeta": { + "postcss": { + "optional": true + }, + "ts-node": { + "optional": true + } + } + }, + "node_modules/postcss-nested": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/postcss-nested/-/postcss-nested-6.0.1.tgz", + "integrity": "sha512-mEp4xPMi5bSWiMbsgoPfcP74lsWLHkQbZc3sY+jWYd65CUwXrUaTp0fmNpa01ZcETKlIgUdFN/MpS2xZtqL9dQ==", + "license": "MIT", + "dependencies": { + "postcss-selector-parser": "^6.0.11" + }, + "engines": { + "node": ">=12.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + "peerDependencies": { + "postcss": "^8.2.14" + } + }, + "node_modules/postcss-selector-parser": { + "version": "6.0.13", + "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.0.13.tgz", + "integrity": "sha512-EaV1Gl4mUEV4ddhDnv/xtj7sxwrwxdetHdWUGnT4VJQf+4d05v6lHYZr8N573k5Z0BViss7BDhfWtKS3+sfAqQ==", + "license": "MIT", + "dependencies": { + "cssesc": "^3.0.0", + "util-deprecate": "^1.0.2" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/postcss-value-parser": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz", + "integrity": "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==", + "license": "MIT" + }, + "node_modules/preact": { + "version": "10.17.0", + "resolved": "https://registry.npmjs.org/preact/-/preact-10.17.0.tgz", + "integrity": "sha512-SNsI8cbaCcUS5tbv9nlXuCfIXnJ9ysBMWk0WnB6UWwcVA3qZ2O6FxqDFECMAMttvLQcW/HaNZUe2BLidyvrVYw==", + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/preact" + } + }, + "node_modules/preact-render-to-string": { + "version": "5.2.6", + "resolved": "https://registry.npmjs.org/preact-render-to-string/-/preact-render-to-string-5.2.6.tgz", + "integrity": "sha512-JyhErpYOvBV1hEPwIxc/fHWXPfnEGdRKxc8gFdAZ7XV4tlzyzG847XAyEZqoDnynP88akM4eaHcSOzNcLWFguw==", + "license": "MIT", + "dependencies": { + "pretty-format": "^3.8.0" + }, + "peerDependencies": { + "preact": ">=10" + } + }, + "node_modules/prelude-ls": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz", + "integrity": "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/prettier": { + "version": "2.8.8", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.8.8.tgz", + "integrity": "sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==", + "dev": true, + "license": "MIT", + "bin": { + "prettier": "bin-prettier.js" + }, + "engines": { + "node": ">=10.13.0" + }, + "funding": { + "url": "https://github.com/prettier/prettier?sponsor=1" + } + }, + "node_modules/prettier-plugin-tailwindcss": { + "version": "0.2.8", + "resolved": "https://registry.npmjs.org/prettier-plugin-tailwindcss/-/prettier-plugin-tailwindcss-0.2.8.tgz", + "integrity": "sha512-KgPcEnJeIijlMjsA6WwYgRs5rh3/q76oInqtMXBA/EMcamrcYJpyhtRhyX1ayT9hnHlHTuO8sIifHF10WuSDKg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12.17.0" + }, + "peerDependencies": { + "@ianvs/prettier-plugin-sort-imports": "*", + "@prettier/plugin-pug": "*", + "@shopify/prettier-plugin-liquid": "*", + "@shufo/prettier-plugin-blade": "*", + "@trivago/prettier-plugin-sort-imports": "*", + "prettier": ">=2.2.0", + "prettier-plugin-astro": "*", + "prettier-plugin-css-order": "*", + "prettier-plugin-import-sort": "*", + "prettier-plugin-jsdoc": "*", + "prettier-plugin-organize-attributes": "*", + "prettier-plugin-organize-imports": "*", + "prettier-plugin-style-order": "*", + "prettier-plugin-svelte": "*", + "prettier-plugin-twig-melody": "*" + }, + "peerDependenciesMeta": { + "@ianvs/prettier-plugin-sort-imports": { + "optional": true + }, + "@prettier/plugin-pug": { + "optional": true + }, + "@shopify/prettier-plugin-liquid": { + "optional": true + }, + "@shufo/prettier-plugin-blade": { + "optional": true + }, + "@trivago/prettier-plugin-sort-imports": { + "optional": true + }, + "prettier-plugin-astro": { + "optional": true + }, + "prettier-plugin-css-order": { + "optional": true + }, + "prettier-plugin-import-sort": { + "optional": true + }, + "prettier-plugin-jsdoc": { + "optional": true + }, + "prettier-plugin-organize-attributes": { + "optional": true + }, + "prettier-plugin-organize-imports": { + "optional": true + }, + "prettier-plugin-style-order": { + "optional": true + }, + "prettier-plugin-svelte": { + "optional": true + }, + "prettier-plugin-twig-melody": { + "optional": true + } + } + }, + "node_modules/pretty-format": { + "version": "3.8.0", + "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-3.8.0.tgz", + "integrity": "sha512-WuxUnVtlWL1OfZFQFuqvnvs6MiAGk9UNsBostyBOB0Is9wb5uRESevA6rnl/rkksXaGX3GzZhPup5d6Vp1nFew==", + "license": "MIT" + }, + "node_modules/prisma": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/prisma/-/prisma-5.1.1.tgz", + "integrity": "sha512-WJFG/U7sMmcc6TjJTTifTfpI6Wjoh55xl4AzopVwAdyK68L9/ogNo8QQ2cxuUjJf/Wa82z/uhyh3wMzvRIBphg==", + "hasInstallScript": true, + "license": "Apache-2.0", + "dependencies": { + "@prisma/engines": "5.1.1" + }, + "bin": { + "prisma": "build/index.js" + }, + "engines": { + "node": ">=16.13" + } + }, + "node_modules/process-nextick-args": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz", + "integrity": "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==", + "license": "MIT", + "peer": true + }, + "node_modules/promise": { + "version": "8.3.0", + "resolved": "https://registry.npmjs.org/promise/-/promise-8.3.0.tgz", + "integrity": "sha512-rZPNPKTOYVNEEKFaq1HqTgOwZD+4/YHS5ukLzQCypkj+OkYx7iv0mA91lJlpPPZ8vMau3IIGj5Qlwrx+8iiSmg==", + "license": "MIT", + "peer": true, + "dependencies": { + "asap": "~2.0.6" + } + }, + "node_modules/prompts": { + "version": "2.4.2", + "resolved": "https://registry.npmjs.org/prompts/-/prompts-2.4.2.tgz", + "integrity": "sha512-NxNv/kLguCA7p3jE8oL2aEBsrJWgAakBpgmgK6lpPWV+WuOmY6r2/zbAVnP+T8bQlA0nzHXSJSJW0Hq7ylaD2Q==", + "license": "MIT", + "peer": true, + "dependencies": { + "kleur": "^3.0.3", + "sisteransi": "^1.0.5" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/prop-types": { + "version": "15.8.1", + "resolved": "https://registry.npmjs.org/prop-types/-/prop-types-15.8.1.tgz", + "integrity": "sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg==", + "license": "MIT", + "dependencies": { + "loose-envify": "^1.4.0", + "object-assign": "^4.1.1", + "react-is": "^16.13.1" + } + }, + "node_modules/property-information": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/property-information/-/property-information-7.0.0.tgz", + "integrity": "sha512-7D/qOz/+Y4X/rzSB6jKxKUsQnphO046ei8qxG59mtM3RG3DHgTK81HrxrmoDVINJb8NKT5ZsRbwHvQ6B68Iyhg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/proxy-from-env": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-1.1.0.tgz", + "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==", + "license": "MIT" + }, + "node_modules/punycode": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.0.tgz", + "integrity": "sha512-rRV+zQD8tVFys26lAGR9WUuS4iUAngJScM+ZRSKtvl5tKeZ2t5bvdNFdNHBW9FWR4guGHlgmsZ1G7BSm2wTbuA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/querystringify": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/querystringify/-/querystringify-2.2.0.tgz", + "integrity": "sha512-FIqgj2EUvTa7R50u0rGsyTftzjYmv/a3hO345bZNrqabNqjtgiDMgmo4mkUjd+nzU5oF3dClKqFIPUKybUyqoQ==", + "license": "MIT" + }, + "node_modules/queue": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/queue/-/queue-6.0.2.tgz", + "integrity": "sha512-iHZWu+q3IdFZFX36ro/lKBkSvfkztY5Y7HMiPlOUjhupPcG2JMfst2KKEpu5XndviX/3UhFbRngUPNKtgvtZiA==", + "license": "MIT", + "peer": true, + "dependencies": { + "inherits": "~2.0.3" + } + }, + "node_modules/queue-microtask": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz", + "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT" + }, + "node_modules/radix-ui": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/radix-ui/-/radix-ui-1.0.1.tgz", + "integrity": "sha512-qfGibbqtbOlxP3b+1JjbLUc8Q7+e9DL8gFycLtkBkoAQyUkKuHAEBfFUcyG5MaQHjqRuML+YLtt/R1/dUYQafQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-accessible-icon": "latest", + "@radix-ui/react-accordion": "latest", + "@radix-ui/react-alert-dialog": "latest", + "@radix-ui/react-aspect-ratio": "latest", + "@radix-ui/react-avatar": "latest", + "@radix-ui/react-checkbox": "latest", + "@radix-ui/react-collapsible": "latest", + "@radix-ui/react-context-menu": "latest", + "@radix-ui/react-dialog": "latest", + "@radix-ui/react-direction": "latest", + "@radix-ui/react-dropdown-menu": "latest", + "@radix-ui/react-hover-card": "latest", + "@radix-ui/react-label": "latest", + "@radix-ui/react-navigation-menu": "latest", + "@radix-ui/react-popover": "latest", + "@radix-ui/react-portal": "latest", + "@radix-ui/react-progress": "latest", + "@radix-ui/react-radio-group": "latest", + "@radix-ui/react-scroll-area": "latest", + "@radix-ui/react-select": "latest", + "@radix-ui/react-separator": "latest", + "@radix-ui/react-slider": "latest", + "@radix-ui/react-slot": "latest", + "@radix-ui/react-switch": "latest", + "@radix-ui/react-tabs": "latest", + "@radix-ui/react-toast": "latest", + "@radix-ui/react-toggle": "latest", + "@radix-ui/react-toggle-group": "latest", + "@radix-ui/react-toolbar": "latest", + "@radix-ui/react-tooltip": "latest", + "@radix-ui/react-visually-hidden": "latest" + }, + "peerDependencies": { + "react": "^16.8 || ^17.0 || ^18.0", + "react-dom": "^16.8 || ^17.0 || ^18.0" + } + }, + "node_modules/range-parser": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.1.tgz", + "integrity": "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/react": { + "version": "18.2.0", + "resolved": "https://registry.npmjs.org/react/-/react-18.2.0.tgz", + "integrity": "sha512-/3IjMdb2L9QbBdWiW5e3P2/npwMBaU9mHCSCUzNln0ZCYbcfTsGbTJrU/kGemdH2IWmB2ioZ+zkxtmq6g09fGQ==", + "license": "MIT", + "dependencies": { + "loose-envify": "^1.1.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/react-devtools-core": { + "version": "4.28.0", + "resolved": "https://registry.npmjs.org/react-devtools-core/-/react-devtools-core-4.28.0.tgz", + "integrity": "sha512-E3C3X1skWBdBzwpOUbmXG8SgH6BtsluSMe+s6rRcujNKG1DGi8uIfhdhszkgDpAsMoE55hwqRUzeXCmETDBpTg==", + "license": "MIT", + "peer": true, + "dependencies": { + "shell-quote": "^1.6.1", + "ws": "^7" + } + }, + "node_modules/react-devtools-core/node_modules/ws": { + "version": "7.5.9", + "resolved": "https://registry.npmjs.org/ws/-/ws-7.5.9.tgz", + "integrity": "sha512-F+P9Jil7UiSKSkppIiD94dN07AwvFixvLIj1Og1Rl9GGMuNipJnV9JzjD6XuqmAeiswGvUmNLjr5cFuXwNS77Q==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=8.3.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": "^5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + }, + "node_modules/react-dom": { + "version": "18.2.0", + "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.2.0.tgz", + "integrity": "sha512-6IMTriUmvsjHUjNtEDudZfuDQUoWXVxKHhlEGSk81n4YFS+r/Kl99wXiwlVXtPBtJenozv2P+hxDsw9eA7Xo6g==", + "license": "MIT", + "dependencies": { + "loose-envify": "^1.1.0", + "scheduler": "^0.23.0" + }, + "peerDependencies": { + "react": "^18.2.0" + } + }, + "node_modules/react-hook-form": { + "version": "7.46.1", + "resolved": "https://registry.npmjs.org/react-hook-form/-/react-hook-form-7.46.1.tgz", + "integrity": "sha512-0GfI31LRTBd5tqbXMGXT1Rdsv3rnvy0FjEk8Gn9/4tp6+s77T7DPZuGEpBRXOauL+NhyGT5iaXzdIM2R6F/E+w==", + "license": "MIT", + "engines": { + "node": ">=12.22.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/react-hook-form" + }, + "peerDependencies": { + "react": "^16.8.0 || ^17 || ^18" + } + }, + "node_modules/react-is": { + "version": "16.13.1", + "resolved": "https://registry.npmjs.org/react-is/-/react-is-16.13.1.tgz", + "integrity": "sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ==", + "license": "MIT" + }, + "node_modules/react-konva": { + "version": "18.2.10", + "resolved": "https://registry.npmjs.org/react-konva/-/react-konva-18.2.10.tgz", + "integrity": "sha512-ohcX1BJINL43m4ynjZ24MxFI1syjBdrXhqVxYVDw2rKgr3yuS0x/6m1Y2Z4sl4T/gKhfreBx8KHisd0XC6OT1g==", + "funding": [ + { + "type": "patreon", + "url": "https://www.patreon.com/lavrton" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/konva" + }, + { + "type": "github", + "url": "https://github.com/sponsors/lavrton" + } + ], + "license": "MIT", + "peer": true, + "dependencies": { + "@types/react-reconciler": "^0.28.2", + "its-fine": "^1.1.1", + "react-reconciler": "~0.29.0", + "scheduler": "^0.23.0" + }, + "peerDependencies": { + "konva": "^8.0.1 || ^7.2.5 || ^9.0.0", + "react": ">=18.0.0", + "react-dom": ">=18.0.0" + } + }, + "node_modules/react-konva/node_modules/@types/react-reconciler": { + "version": "0.28.4", + "resolved": "https://registry.npmjs.org/@types/react-reconciler/-/react-reconciler-0.28.4.tgz", + "integrity": "sha512-Xd55E2aLI9Q/ikDQEmfRzIwYJs4oO0h9ZHA3FZDakzt1WR6JMZcpqtCZlF97I72KVjoY4rHXU5TfvkRDOyr/rg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@types/react": "*" + } + }, + "node_modules/react-konva/node_modules/react-reconciler": { + "version": "0.29.0", + "resolved": "https://registry.npmjs.org/react-reconciler/-/react-reconciler-0.29.0.tgz", + "integrity": "sha512-wa0fGj7Zht1EYMRhKWwoo1H9GApxYLBuhoAuXN0TlltESAjDssB+Apf0T/DngVqaMyPypDmabL37vw/2aRM98Q==", + "license": "MIT", + "peer": true, + "dependencies": { + "loose-envify": "^1.1.0", + "scheduler": "^0.23.0" + }, + "engines": { + "node": ">=0.10.0" + }, + "peerDependencies": { + "react": "^18.2.0" + } + }, + "node_modules/react-lifecycles-compat": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/react-lifecycles-compat/-/react-lifecycles-compat-3.0.4.tgz", + "integrity": "sha512-fBASbA6LnOU9dOU2eW7aQ8xmYBSXUIWr+UmF9b1efZBazGNO+rcXT/icdKnYm2pTwcRylVUYwW7H1PHfLekVzA==", + "license": "MIT" + }, + "node_modules/react-markdown": { + "version": "8.0.7", + "resolved": "https://registry.npmjs.org/react-markdown/-/react-markdown-8.0.7.tgz", + "integrity": "sha512-bvWbzG4MtOU62XqBx3Xx+zB2raaFFsq4mYiAzfjXJMEz2sixgeAfraA3tvzULF02ZdOMUOKTBFFaZJDDrq+BJQ==", + "license": "MIT", + "dependencies": { + "@types/hast": "^2.0.0", + "@types/prop-types": "^15.0.0", + "@types/unist": "^2.0.0", + "comma-separated-tokens": "^2.0.0", + "hast-util-whitespace": "^2.0.0", + "prop-types": "^15.0.0", + "property-information": "^6.0.0", + "react-is": "^18.0.0", + "remark-parse": "^10.0.0", + "remark-rehype": "^10.0.0", + "space-separated-tokens": "^2.0.0", + "style-to-object": "^0.4.0", + "unified": "^10.0.0", + "unist-util-visit": "^4.0.0", + "vfile": "^5.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + }, + "peerDependencies": { + "@types/react": ">=16", + "react": ">=16" + } + }, + "node_modules/react-markdown/node_modules/@types/hast": { + "version": "2.3.6", + "resolved": "https://registry.npmjs.org/@types/hast/-/hast-2.3.6.tgz", + "integrity": "sha512-47rJE80oqPmFdVDCD7IheXBrVdwuBgsYwoczFvKmwfo2Mzsnt+V9OONsYauFmICb6lQPpCuXYJWejBNs4pDJRg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2" + } + }, + "node_modules/react-markdown/node_modules/@types/mdast": { + "version": "3.0.12", + "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-3.0.12.tgz", + "integrity": "sha512-DT+iNIRNX884cx0/Q1ja7NyUPpZuv0KPyL5rGNxm1WC1OtHstl7n4Jb7nk+xacNShQMbczJjt8uFzznpp6kYBg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2" + } + }, + "node_modules/react-markdown/node_modules/hast-util-whitespace": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/hast-util-whitespace/-/hast-util-whitespace-2.0.1.tgz", + "integrity": "sha512-nAxA0v8+vXSBDt3AnRUNjyRIQ0rD+ntpbAp4LnPkumc5M9yUbSMa4XDU9Q6etY4f1Wp4bNgvc1yjiZtsTTrSng==", + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/react-markdown/node_modules/inline-style-parser": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/inline-style-parser/-/inline-style-parser-0.1.1.tgz", + "integrity": "sha512-7NXolsK4CAS5+xvdj5OMMbI962hU/wvwoxk+LWR9Ek9bVtyuuYScDN6eS0rUm6TxApFpw7CX1o4uJzcd4AyD3Q==", + "license": "MIT" + }, + "node_modules/react-markdown/node_modules/mdast-util-from-markdown": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-1.3.1.tgz", + "integrity": "sha512-4xTO/M8c82qBcnQc1tgpNtubGUW/Y1tBQ1B0i5CtSoelOLKFYlElIr3bvgREYYO5iRqbMY1YuqZng0GVOI8Qww==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^3.0.0", + "@types/unist": "^2.0.0", + "decode-named-character-reference": "^1.0.0", + "mdast-util-to-string": "^3.1.0", + "micromark": "^3.0.0", + "micromark-util-decode-numeric-character-reference": "^1.0.0", + "micromark-util-decode-string": "^1.0.0", + "micromark-util-normalize-identifier": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0", + "unist-util-stringify-position": "^3.0.0", + "uvu": "^0.5.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/react-markdown/node_modules/mdast-util-to-hast": { + "version": "12.3.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-12.3.0.tgz", + "integrity": "sha512-pits93r8PhnIoU4Vy9bjW39M2jJ6/tdHyja9rrot9uujkN7UTU9SDnE6WNJz/IGyQk3XHX6yNNtrBH6cQzm8Hw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^2.0.0", + "@types/mdast": "^3.0.0", + "mdast-util-definitions": "^5.0.0", + "micromark-util-sanitize-uri": "^1.1.0", + "trim-lines": "^3.0.0", + "unist-util-generated": "^2.0.0", + "unist-util-position": "^4.0.0", + "unist-util-visit": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/react-markdown/node_modules/mdast-util-to-string": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-3.2.0.tgz", + "integrity": "sha512-V4Zn/ncyN1QNSqSBxTrMOLpjr+IKdHl2v3KVLoWmDPscP4r9GcCi71gjgvUV1SFSKh92AjAG4peFuBl2/YgCJg==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/react-markdown/node_modules/micromark": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/micromark/-/micromark-3.2.0.tgz", + "integrity": "sha512-uD66tJj54JLYq0De10AhWycZWGQNUvDI55xPgk2sQM5kn1JYlhbCMTtEeT27+vAhW2FBQxLlOmS3pmA7/2z4aA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/debug": "^4.0.0", + "debug": "^4.0.0", + "decode-named-character-reference": "^1.0.0", + "micromark-core-commonmark": "^1.0.1", + "micromark-factory-space": "^1.0.0", + "micromark-util-character": "^1.0.0", + "micromark-util-chunked": "^1.0.0", + "micromark-util-combine-extensions": "^1.0.0", + "micromark-util-decode-numeric-character-reference": "^1.0.0", + "micromark-util-encode": "^1.0.0", + "micromark-util-normalize-identifier": "^1.0.0", + "micromark-util-resolve-all": "^1.0.0", + "micromark-util-sanitize-uri": "^1.0.0", + "micromark-util-subtokenize": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.1", + "uvu": "^0.5.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-core-commonmark": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-core-commonmark/-/micromark-core-commonmark-1.1.0.tgz", + "integrity": "sha512-BgHO1aRbolh2hcrzL2d1La37V0Aoz73ymF8rAcKnohLy93titmv62E0gP8Hrx9PKcKrqCZ1BbLGbP3bEhoXYlw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "micromark-factory-destination": "^1.0.0", + "micromark-factory-label": "^1.0.0", + "micromark-factory-space": "^1.0.0", + "micromark-factory-title": "^1.0.0", + "micromark-factory-whitespace": "^1.0.0", + "micromark-util-character": "^1.0.0", + "micromark-util-chunked": "^1.0.0", + "micromark-util-classify-character": "^1.0.0", + "micromark-util-html-tag-name": "^1.0.0", + "micromark-util-normalize-identifier": "^1.0.0", + "micromark-util-resolve-all": "^1.0.0", + "micromark-util-subtokenize": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.1", + "uvu": "^0.5.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-factory-destination": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-factory-destination/-/micromark-factory-destination-1.1.0.tgz", + "integrity": "sha512-XaNDROBgx9SgSChd69pjiGKbV+nfHGDPVYFs5dOoDd7ZnMAE+Cuu91BCpsY8RT2NP9vo/B8pds2VQNCLiu0zhg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-factory-label": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-factory-label/-/micromark-factory-label-1.1.0.tgz", + "integrity": "sha512-OLtyez4vZo/1NjxGhcpDSbHQ+m0IIGnT8BoPamh+7jVlzLJBH98zzuCoUeMxvM6WsNeh8wx8cKvqLiPHEACn0w==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0", + "uvu": "^0.5.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-factory-space": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-factory-space/-/micromark-factory-space-1.1.0.tgz", + "integrity": "sha512-cRzEj7c0OL4Mw2v6nwzttyOZe8XY/Z8G0rzmWQZTBi/jjwyw/U4uqKtUORXQrR5bAZZnbTI/feRV/R7hc4jQYQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^1.0.0", + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-factory-title": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-factory-title/-/micromark-factory-title-1.1.0.tgz", + "integrity": "sha512-J7n9R3vMmgjDOCY8NPw55jiyaQnH5kBdV2/UXCtZIpnHH3P6nHUKaH7XXEYuWwx/xUJcawa8plLBEjMPU24HzQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^1.0.0", + "micromark-util-character": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-factory-whitespace": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-factory-whitespace/-/micromark-factory-whitespace-1.1.0.tgz", + "integrity": "sha512-v2WlmiymVSp5oMg+1Q0N1Lxmt6pMhIHD457whWM7/GUlEks1hI9xj5w3zbc4uuMKXGisksZk8DzP2UyGbGqNsQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^1.0.0", + "micromark-util-character": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-util-character": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-1.2.0.tgz", + "integrity": "sha512-lXraTwcX3yH/vMDaFWCQJP1uIszLVebzUa3ZHdrgxr7KEU/9mL4mVgCpGbyhvNLNlauROiNUq7WN5u7ndbY6xg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-util-chunked": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-chunked/-/micromark-util-chunked-1.1.0.tgz", + "integrity": "sha512-Ye01HXpkZPNcV6FiyoW2fGZDUw4Yc7vT0E9Sad83+bEDiCJ1uXu0S3mr8WLpsz3HaG3x2q0HM6CTuPdcZcluFQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^1.0.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-util-classify-character": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-classify-character/-/micromark-util-classify-character-1.1.0.tgz", + "integrity": "sha512-SL0wLxtKSnklKSUplok1WQFoGhUdWYKggKUiqhX+Swala+BtptGCu5iPRc+xvzJ4PXE/hwM3FNXsfEVgoZsWbw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-util-combine-extensions": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-combine-extensions/-/micromark-util-combine-extensions-1.1.0.tgz", + "integrity": "sha512-Q20sp4mfNf9yEqDL50WwuWZHUrCO4fEyeDCnMGmG5Pr0Cz15Uo7KBs6jq+dq0EgX4DPwwrh9m0X+zPV1ypFvUA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-chunked": "^1.0.0", + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-util-decode-numeric-character-reference": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-decode-numeric-character-reference/-/micromark-util-decode-numeric-character-reference-1.1.0.tgz", + "integrity": "sha512-m9V0ExGv0jB1OT21mrWcuf4QhP46pH1KkfWy9ZEezqHKAxkj4mPCy3nIH1rkbdMlChLHX531eOrymlwyZIf2iw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^1.0.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-util-decode-string": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-decode-string/-/micromark-util-decode-string-1.1.0.tgz", + "integrity": "sha512-YphLGCK8gM1tG1bd54azwyrQRjCFcmgj2S2GoJDNnh4vYtnL38JS8M4gpxzOPNyHdNEpheyWXCTnnTDY3N+NVQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "micromark-util-character": "^1.0.0", + "micromark-util-decode-numeric-character-reference": "^1.0.0", + "micromark-util-symbol": "^1.0.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-util-encode": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-encode/-/micromark-util-encode-1.1.0.tgz", + "integrity": "sha512-EuEzTWSTAj9PA5GOAs992GzNh2dGQO52UvAbtSOMvXTxv3Criqb6IOzJUBCmEqrrXSblJIJBbFFv6zPxpreiJw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/react-markdown/node_modules/micromark-util-html-tag-name": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/micromark-util-html-tag-name/-/micromark-util-html-tag-name-1.2.0.tgz", + "integrity": "sha512-VTQzcuQgFUD7yYztuQFKXT49KghjtETQ+Wv/zUjGSGBioZnkA4P1XXZPT1FHeJA6RwRXSF47yvJ1tsJdoxwO+Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/react-markdown/node_modules/micromark-util-normalize-identifier": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-normalize-identifier/-/micromark-util-normalize-identifier-1.1.0.tgz", + "integrity": "sha512-N+w5vhqrBihhjdpM8+5Xsxy71QWqGn7HYNUvch71iV2PM7+E3uWGox1Qp90loa1ephtCxG2ftRV/Conitc6P2Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^1.0.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-util-resolve-all": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-resolve-all/-/micromark-util-resolve-all-1.1.0.tgz", + "integrity": "sha512-b/G6BTMSg+bX+xVCshPTPyAu2tmA0E4X98NSR7eIbeC6ycCqCeE7wjfDIgzEbkzdEVJXRtOG4FbEm/uGbCRouA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-util-sanitize-uri": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-1.2.0.tgz", + "integrity": "sha512-QO4GXv0XZfWey4pYFndLUKEAktKkG5kZTdUNaTAkzbuJxn2tNBOr+QtxR2XpWaMhbImT2dPzyLrPXLlPhph34A==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^1.0.0", + "micromark-util-encode": "^1.0.0", + "micromark-util-symbol": "^1.0.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-util-subtokenize": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-subtokenize/-/micromark-util-subtokenize-1.1.0.tgz", + "integrity": "sha512-kUQHyzRoxvZO2PuLzMt2P/dwVsTiivCK8icYTeR+3WgbuPqfHgPPy7nFKbeqRivBvn/3N3GBiNC+JRTMSxEC7A==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-chunked": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0", + "uvu": "^0.5.0" + } + }, + "node_modules/react-markdown/node_modules/micromark-util-symbol": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-symbol/-/micromark-util-symbol-1.1.0.tgz", + "integrity": "sha512-uEjpEYY6KMs1g7QfJ2eX1SQEV+ZT4rUD3UcF6l57acZvLNK7PBZL+ty82Z1qhK1/yXIY4bdx04FKMgR0g4IAag==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/react-markdown/node_modules/micromark-util-types": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-1.1.0.tgz", + "integrity": "sha512-ukRBgie8TIAcacscVHSiddHjO4k/q3pnedmzMQ4iwDcK0FtFCohKOlFbaOL/mPgfnPsL3C1ZyxJa4sbWrBl3jg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/react-markdown/node_modules/property-information": { + "version": "6.3.0", + "resolved": "https://registry.npmjs.org/property-information/-/property-information-6.3.0.tgz", + "integrity": "sha512-gVNZ74nqhRMiIUYWGQdosYetaKc83x8oT41a0LlV3AAFCAZwCpg4vmGkq8t34+cUhp3cnM4XDiU/7xlgK7HGrg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/react-markdown/node_modules/react-is": { + "version": "18.2.0", + "resolved": "https://registry.npmjs.org/react-is/-/react-is-18.2.0.tgz", + "integrity": "sha512-xWGDIW6x921xtzPkhiULtthJHoJvBbF3q26fzloPCK0hsvxtPVelvftw3zjbHWSkR2km9Z+4uxbDDK/6Zw9B8w==", + "license": "MIT" + }, + "node_modules/react-markdown/node_modules/remark-parse": { + "version": "10.0.2", + "resolved": "https://registry.npmjs.org/remark-parse/-/remark-parse-10.0.2.tgz", + "integrity": "sha512-3ydxgHa/ZQzG8LvC7jTXccARYDcRld3VfcgIIFs7bI6vbRSxJJmzgLEIIoYKyrfhaY+ujuWaf/PJiMZXoiCXgw==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^3.0.0", + "mdast-util-from-markdown": "^1.0.0", + "unified": "^10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/react-markdown/node_modules/remark-rehype": { + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/remark-rehype/-/remark-rehype-10.1.0.tgz", + "integrity": "sha512-EFmR5zppdBp0WQeDVZ/b66CWJipB2q2VLNFMabzDSGR66Z2fQii83G5gTBbgGEnEEA0QRussvrFHxk1HWGJskw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^2.0.0", + "@types/mdast": "^3.0.0", + "mdast-util-to-hast": "^12.1.0", + "unified": "^10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/react-markdown/node_modules/style-to-object": { + "version": "0.4.2", + "resolved": "https://registry.npmjs.org/style-to-object/-/style-to-object-0.4.2.tgz", + "integrity": "sha512-1JGpfPB3lo42ZX8cuPrheZbfQ6kqPPnPHlKMyeRYtfKD+0jG+QsXgXN57O/dvJlzlB2elI6dGmrPnl5VPQFPaA==", + "license": "MIT", + "dependencies": { + "inline-style-parser": "0.1.1" + } + }, + "node_modules/react-markdown/node_modules/unified": { + "version": "10.1.2", + "resolved": "https://registry.npmjs.org/unified/-/unified-10.1.2.tgz", + "integrity": "sha512-pUSWAi/RAnVy1Pif2kAoeWNBa3JVrx0MId2LASj8G+7AiHWoKZNTomq6LG326T68U7/e263X6fTdcXIy7XnF7Q==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0", + "bail": "^2.0.0", + "extend": "^3.0.0", + "is-buffer": "^2.0.0", + "is-plain-obj": "^4.0.0", + "trough": "^2.0.0", + "vfile": "^5.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/react-markdown/node_modules/unist-util-is": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-5.2.1.tgz", + "integrity": "sha512-u9njyyfEh43npf1M+yGKDGVPbY/JWEemg5nH05ncKPfi+kBbKBJoTdsogMu33uhytuLlv9y0O7GH7fEdwLdLQw==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/react-markdown/node_modules/unist-util-position": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/unist-util-position/-/unist-util-position-4.0.4.tgz", + "integrity": "sha512-kUBE91efOWfIVBo8xzh/uZQ7p9ffYRtUbMRZBNFYwf0RK8koUMx6dGUfwylLOKmaT2cs4wSW96QoYUSXAyEtpg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/react-markdown/node_modules/unist-util-stringify-position": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-3.0.3.tgz", + "integrity": "sha512-k5GzIBZ/QatR8N5X2y+drfpWG8IDBzdnVj6OInRNWm1oXrzydiaAT2OQiA8DPRRZyAKb9b6I2a6PxYklZD0gKg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/react-markdown/node_modules/unist-util-visit": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-4.1.2.tgz", + "integrity": "sha512-MSd8OUGISqHdVvfY9TPhyK2VdUrPgxkUtWSuMHF6XAAFuL4LokseigBnZtPnJMu+FbynTkFNnFlyjxpVKujMRg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0", + "unist-util-is": "^5.0.0", + "unist-util-visit-parents": "^5.1.1" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/react-markdown/node_modules/unist-util-visit-parents": { + "version": "5.1.3", + "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-5.1.3.tgz", + "integrity": "sha512-x6+y8g7wWMyQhL1iZfhIPhDAs7Xwbn9nRosDXl7qoPTSCy0yNxnKc+hWokFifWQIDGi154rdUqKvbCa4+1kLhg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0", + "unist-util-is": "^5.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/react-markdown/node_modules/vfile": { + "version": "5.3.7", + "resolved": "https://registry.npmjs.org/vfile/-/vfile-5.3.7.tgz", + "integrity": "sha512-r7qlzkgErKjobAmyNIkkSpizsFPYiUPuJb5pNW1RB4JcYVZhs4lIbVqk8XPk033CV/1z8ss5pkax8SuhGpcG8g==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0", + "is-buffer": "^2.0.0", + "unist-util-stringify-position": "^3.0.0", + "vfile-message": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/react-markdown/node_modules/vfile-message": { + "version": "3.1.4", + "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-3.1.4.tgz", + "integrity": "sha512-fa0Z6P8HUrQN4BZaX05SIVXic+7kE3b05PWAtPuYP9QLHsLKYR7/AlLW3NtOrpXRLeawpDLMsVkmk5DG0NXgWw==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0", + "unist-util-stringify-position": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/react-native": { + "version": "0.72.4", + "resolved": "https://registry.npmjs.org/react-native/-/react-native-0.72.4.tgz", + "integrity": "sha512-+vrObi0wZR+NeqL09KihAAdVlQ9IdplwznJWtYrjnQ4UbCW6rkzZJebRsugwUneSOKNFaHFEo1uKU89HsgtYBg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@jest/create-cache-key-function": "^29.2.1", + "@react-native-community/cli": "11.3.6", + "@react-native-community/cli-platform-android": "11.3.6", + "@react-native-community/cli-platform-ios": "11.3.6", + "@react-native/assets-registry": "^0.72.0", + "@react-native/codegen": "^0.72.6", + "@react-native/gradle-plugin": "^0.72.11", + "@react-native/js-polyfills": "^0.72.1", + "@react-native/normalize-colors": "^0.72.0", + "@react-native/virtualized-lists": "^0.72.8", + "abort-controller": "^3.0.0", + "anser": "^1.4.9", + "base64-js": "^1.1.2", + "deprecated-react-native-prop-types": "4.1.0", + "event-target-shim": "^5.0.1", + "flow-enums-runtime": "^0.0.5", + "invariant": "^2.2.4", + "jest-environment-node": "^29.2.1", + "jsc-android": "^250231.0.0", + "memoize-one": "^5.0.0", + "metro-runtime": "0.76.8", + "metro-source-map": "0.76.8", + "mkdirp": "^0.5.1", + "nullthrows": "^1.1.1", + "pretty-format": "^26.5.2", + "promise": "^8.3.0", + "react-devtools-core": "^4.27.2", + "react-refresh": "^0.4.0", + "react-shallow-renderer": "^16.15.0", + "regenerator-runtime": "^0.13.2", + "scheduler": "0.24.0-canary-efb381bbf-20230505", + "stacktrace-parser": "^0.1.10", + "use-sync-external-store": "^1.0.0", + "whatwg-fetch": "^3.0.0", + "ws": "^6.2.2", + "yargs": "^17.6.2" + }, + "bin": { + "react-native": "cli.js" + }, + "engines": { + "node": ">=16" + }, + "peerDependencies": { + "react": "18.2.0" + } + }, + "node_modules/react-native/node_modules/@jest/types": { + "version": "26.6.2", + "resolved": "https://registry.npmjs.org/@jest/types/-/types-26.6.2.tgz", + "integrity": "sha512-fC6QCp7Sc5sX6g8Tvbmj4XUTbyrik0akgRy03yjXbQaBWWNWGE7SGtJk98m0N8nzegD/7SggrUlivxo5ax4KWQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@types/istanbul-lib-coverage": "^2.0.0", + "@types/istanbul-reports": "^3.0.0", + "@types/node": "*", + "@types/yargs": "^15.0.0", + "chalk": "^4.0.0" + }, + "engines": { + "node": ">= 10.14.2" + } + }, + "node_modules/react-native/node_modules/@types/yargs": { + "version": "15.0.15", + "resolved": "https://registry.npmjs.org/@types/yargs/-/yargs-15.0.15.tgz", + "integrity": "sha512-IziEYMU9XoVj8hWg7k+UJrXALkGFjWJhn5QFEv9q4p+v40oZhSuC135M38st8XPjICL7Ey4TV64ferBGUoJhBg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@types/yargs-parser": "*" + } + }, + "node_modules/react-native/node_modules/pretty-format": { + "version": "26.6.2", + "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-26.6.2.tgz", + "integrity": "sha512-7AeGuCYNGmycyQbCqd/3PWH4eOoX/OiCa0uphp57NVTeAGdJGaAliecxwBDHYQCIvrW7aDBZCYeNTP/WX69mkg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@jest/types": "^26.6.2", + "ansi-regex": "^5.0.0", + "ansi-styles": "^4.0.0", + "react-is": "^17.0.1" + }, + "engines": { + "node": ">= 10" + } + }, + "node_modules/react-native/node_modules/react-is": { + "version": "17.0.2", + "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz", + "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==", + "license": "MIT", + "peer": true + }, + "node_modules/react-native/node_modules/regenerator-runtime": { + "version": "0.13.11", + "resolved": "https://registry.npmjs.org/regenerator-runtime/-/regenerator-runtime-0.13.11.tgz", + "integrity": "sha512-kY1AZVr2Ra+t+piVaJ4gxaFaReZVH40AKNo7UCX6W+dEwBo/2oZJzqfuN1qLq1oL45o56cPaTXELwrTh8Fpggg==", + "license": "MIT", + "peer": true + }, + "node_modules/react-native/node_modules/scheduler": { + "version": "0.24.0-canary-efb381bbf-20230505", + "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.24.0-canary-efb381bbf-20230505.tgz", + "integrity": "sha512-ABvovCDe/k9IluqSh4/ISoq8tIJnW8euVAWYt5j/bg6dRnqwQwiGO1F/V4AyK96NGF/FB04FhOUDuWj8IKfABA==", + "license": "MIT", + "peer": true, + "dependencies": { + "loose-envify": "^1.1.0" + } + }, + "node_modules/react-reconciler": { + "version": "0.27.0", + "resolved": "https://registry.npmjs.org/react-reconciler/-/react-reconciler-0.27.0.tgz", + "integrity": "sha512-HmMDKciQjYmBRGuuhIaKA1ba/7a+UsM5FzOZsMO2JYHt9Jh8reCb7j1eDC95NOyUlKM9KRyvdx0flBuDvYSBoA==", + "license": "MIT", + "peer": true, + "dependencies": { + "loose-envify": "^1.1.0", + "scheduler": "^0.21.0" + }, + "engines": { + "node": ">=0.10.0" + }, + "peerDependencies": { + "react": "^18.0.0" + } + }, + "node_modules/react-reconciler/node_modules/scheduler": { + "version": "0.21.0", + "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.21.0.tgz", + "integrity": "sha512-1r87x5fz9MXqswA2ERLo0EbOAU74DpIUO090gIasYTqlVoJeMcl+Z1Rg7WHz+qtPujhS/hGIt9kxZOYBV3faRQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "loose-envify": "^1.1.0" + } + }, + "node_modules/react-refresh": { + "version": "0.4.3", + "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.4.3.tgz", + "integrity": "sha512-Hwln1VNuGl/6bVwnd0Xdn1e84gT/8T9aYNL+HAKDArLCS7LWjwr7StE30IEYbIkx0Vi3vs+coQxe+SQDbGbbpA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/react-remove-scroll": { + "version": "2.7.1", + "resolved": "https://registry.npmjs.org/react-remove-scroll/-/react-remove-scroll-2.7.1.tgz", + "integrity": "sha512-HpMh8+oahmIdOuS5aFKKY6Pyog+FNaZV/XyJOq7b4YFwsFHe5yYfdbIalI4k3vU2nSDql7YskmUseHsRrJqIPA==", + "license": "MIT", + "dependencies": { + "react-remove-scroll-bar": "^2.3.7", + "react-style-singleton": "^2.2.3", + "tslib": "^2.1.0", + "use-callback-ref": "^1.3.3", + "use-sidecar": "^1.1.3" + }, + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/react-remove-scroll-bar": { + "version": "2.3.8", + "resolved": "https://registry.npmjs.org/react-remove-scroll-bar/-/react-remove-scroll-bar-2.3.8.tgz", + "integrity": "sha512-9r+yi9+mgU33AKcj6IbT9oRCO78WriSj6t/cF8DWBZJ9aOGPOTEDvdUDz1FwKim7QXWwmHqtdHnRJfhAxEG46Q==", + "license": "MIT", + "dependencies": { + "react-style-singleton": "^2.2.2", + "tslib": "^2.0.0" + }, + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/react-router": { + "version": "6.15.0", + "resolved": "https://registry.npmjs.org/react-router/-/react-router-6.15.0.tgz", + "integrity": "sha512-NIytlzvzLwJkCQj2HLefmeakxxWHWAP+02EGqWEZy+DgfHHKQMUoBBjUQLOtFInBMhWtb3hiUy6MfFgwLjXhqg==", + "license": "MIT", + "dependencies": { + "@remix-run/router": "1.8.0" + }, + "engines": { + "node": ">=14.0.0" + }, + "peerDependencies": { + "react": ">=16.8" + } + }, + "node_modules/react-router-dom": { + "version": "6.15.0", + "resolved": "https://registry.npmjs.org/react-router-dom/-/react-router-dom-6.15.0.tgz", + "integrity": "sha512-aR42t0fs7brintwBGAv2+mGlCtgtFQeOzK0BM1/OiqEzRejOZtpMZepvgkscpMUnKb8YO84G7s3LsHnnDNonbQ==", + "license": "MIT", + "dependencies": { + "@remix-run/router": "1.8.0", + "react-router": "6.15.0" + }, + "engines": { + "node": ">=14.0.0" + }, + "peerDependencies": { + "react": ">=16.8", + "react-dom": ">=16.8" + } + }, + "node_modules/react-shallow-renderer": { + "version": "16.15.0", + "resolved": "https://registry.npmjs.org/react-shallow-renderer/-/react-shallow-renderer-16.15.0.tgz", + "integrity": "sha512-oScf2FqQ9LFVQgA73vr86xl2NaOIX73rh+YFqcOp68CWj56tSfgtGKrEbyhCj0rSijyG9M1CYprTh39fBi5hzA==", + "license": "MIT", + "peer": true, + "dependencies": { + "object-assign": "^4.1.1", + "react-is": "^16.12.0 || ^17.0.0 || ^18.0.0" + }, + "peerDependencies": { + "react": "^16.0.0 || ^17.0.0 || ^18.0.0" + } + }, + "node_modules/react-smooth": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/react-smooth/-/react-smooth-4.0.4.tgz", + "integrity": "sha512-gnGKTpYwqL0Iii09gHobNolvX4Kiq4PKx6eWBCYYix+8cdw+cGo3do906l1NBPKkSWx1DghC1dlWG9L2uGd61Q==", + "license": "MIT", + "dependencies": { + "fast-equals": "^5.0.1", + "prop-types": "^15.8.1", + "react-transition-group": "^4.4.5" + }, + "peerDependencies": { + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", + "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" + } + }, + "node_modules/react-spring": { + "version": "9.7.2", + "resolved": "https://registry.npmjs.org/react-spring/-/react-spring-9.7.2.tgz", + "integrity": "sha512-cckALtj79yiaJiAOUNAhtZbdqjvv1bdn/FpobgkckIChc8l6vu0E53WQ+zWru60gINI3JT+oRJSIn2hUVlOvlQ==", + "license": "MIT", + "dependencies": { + "@react-spring/core": "~9.7.3", + "@react-spring/konva": "~9.7.3", + "@react-spring/native": "~9.7.3", + "@react-spring/three": "~9.7.3", + "@react-spring/web": "~9.7.3", + "@react-spring/zdog": "~9.7.3" + }, + "peerDependencies": { + "react": "^16.8.0 || ^17.0.0 || ^18.0.0", + "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0" + } + }, + "node_modules/react-ssr-prepass": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/react-ssr-prepass/-/react-ssr-prepass-1.5.0.tgz", + "integrity": "sha512-yFNHrlVEReVYKsLI5lF05tZoHveA5pGzjFbFJY/3pOqqjGOmMmqx83N4hIjN2n6E1AOa+eQEUxs3CgRnPmT0RQ==", + "license": "MIT", + "peerDependencies": { + "react": "^16.8.0 || ^17.0.0 || ^18.0.0" + } + }, + "node_modules/react-style-singleton": { + "version": "2.2.3", + "resolved": "https://registry.npmjs.org/react-style-singleton/-/react-style-singleton-2.2.3.tgz", + "integrity": "sha512-b6jSvxvVnyptAiLjbkWLE/lOnR4lfTtDAl+eUC7RZy+QQWc6wRzIV2CE6xBuMmDxc2qIihtDCZD5NPOFl7fRBQ==", + "license": "MIT", + "dependencies": { + "get-nonce": "^1.0.0", + "tslib": "^2.0.0" + }, + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/react-transition-group": { + "version": "4.4.5", + "resolved": "https://registry.npmjs.org/react-transition-group/-/react-transition-group-4.4.5.tgz", + "integrity": "sha512-pZcd1MCJoiKiBR2NRxeCRg13uCXbydPnmB4EOeRrY7480qNWO8IIgQG6zlDkm6uRMsURXPuKq0GWtiM59a5Q6g==", + "license": "BSD-3-Clause", + "dependencies": { + "@babel/runtime": "^7.5.5", + "dom-helpers": "^5.0.1", + "loose-envify": "^1.4.0", + "prop-types": "^15.6.2" + }, + "peerDependencies": { + "react": ">=16.6.0", + "react-dom": ">=16.6.0" + } + }, + "node_modules/react-use-measure": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/react-use-measure/-/react-use-measure-2.1.1.tgz", + "integrity": "sha512-nocZhN26cproIiIduswYpV5y5lQpSQS1y/4KuvUCjSKmw7ZWIS/+g3aFnX3WdBkyuGUtTLif3UTqnLLhbDoQig==", + "license": "MIT", + "peer": true, + "dependencies": { + "debounce": "^1.2.1" + }, + "peerDependencies": { + "react": ">=16.13", + "react-dom": ">=16.13" + } + }, + "node_modules/react-zdog": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/react-zdog/-/react-zdog-1.2.2.tgz", + "integrity": "sha512-Ix7ALha91aOEwiHuxumCeYbARS5XNpc/w0v145oGkM6poF/CvhKJwzLhM5sEZbtrghMA+psAhOJkCTzJoseicA==", + "license": "MIT", + "peer": true, + "dependencies": { + "react": "^18.2.0", + "react-dom": "^18.2.0", + "resize-observer-polyfill": "^1.5.1" + } + }, + "node_modules/read-cache": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/read-cache/-/read-cache-1.0.0.tgz", + "integrity": "sha512-Owdv/Ft7IjOgm/i0xvNDZ1LrRANRfew4b2prF3OWMQLxLfu3bS8FVhCsrSCMK4lR56Y9ya+AThoTpDCTxCmpRA==", + "license": "MIT", + "dependencies": { + "pify": "^2.3.0" + } + }, + "node_modules/readable-stream": { + "version": "3.6.2", + "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz", + "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==", + "license": "MIT", + "dependencies": { + "inherits": "^2.0.3", + "string_decoder": "^1.1.1", + "util-deprecate": "^1.0.1" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/readdirp": { + "version": "3.6.0", + "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz", + "integrity": "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==", + "license": "MIT", + "dependencies": { + "picomatch": "^2.2.1" + }, + "engines": { + "node": ">=8.10.0" + } + }, + "node_modules/readline": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/readline/-/readline-1.3.0.tgz", + "integrity": "sha512-k2d6ACCkiNYz222Fs/iNze30rRJ1iIicW7JuX/7/cozvih6YCkFZH+J6mAFDVgv0dRBaAyr4jDqC95R2y4IADg==", + "license": "BSD", + "peer": true + }, + "node_modules/recast": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/recast/-/recast-0.21.5.tgz", + "integrity": "sha512-hjMmLaUXAm1hIuTqOdeYObMslq/q+Xff6QE3Y2P+uoHAg2nmVlLBps2hzh1UJDdMtDTMXOFewK6ky51JQIeECg==", + "license": "MIT", + "peer": true, + "dependencies": { + "ast-types": "0.15.2", + "esprima": "~4.0.0", + "source-map": "~0.6.1", + "tslib": "^2.0.1" + }, + "engines": { + "node": ">= 4" + } + }, + "node_modules/recast/node_modules/source-map": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", + "license": "BSD-3-Clause", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/recharts": { + "version": "2.15.3", + "resolved": "https://registry.npmjs.org/recharts/-/recharts-2.15.3.tgz", + "integrity": "sha512-EdOPzTwcFSuqtvkDoaM5ws/Km1+WTAO2eizL7rqiG0V2UVhTnz0m7J2i0CjVPUCdEkZImaWvXLbZDS2H5t6GFQ==", + "license": "MIT", + "dependencies": { + "clsx": "^2.0.0", + "eventemitter3": "^4.0.1", + "lodash": "^4.17.21", + "react-is": "^18.3.1", + "react-smooth": "^4.0.4", + "recharts-scale": "^0.4.4", + "tiny-invariant": "^1.3.1", + "victory-vendor": "^36.6.8" + }, + "engines": { + "node": ">=14" + }, + "peerDependencies": { + "react": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", + "react-dom": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" + } + }, + "node_modules/recharts-scale": { + "version": "0.4.5", + "resolved": "https://registry.npmjs.org/recharts-scale/-/recharts-scale-0.4.5.tgz", + "integrity": "sha512-kivNFO+0OcUNu7jQquLXAxz1FIwZj8nrj+YkOKc5694NbjCvcT6aSZiIzNzd2Kul4o4rTto8QVR9lMNtxD4G1w==", + "license": "MIT", + "dependencies": { + "decimal.js-light": "^2.4.1" + } + }, + "node_modules/recharts/node_modules/react-is": { + "version": "18.3.1", + "resolved": "https://registry.npmjs.org/react-is/-/react-is-18.3.1.tgz", + "integrity": "sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==", + "license": "MIT" + }, + "node_modules/recma-build-jsx": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/recma-build-jsx/-/recma-build-jsx-1.0.0.tgz", + "integrity": "sha512-8GtdyqaBcDfva+GUKDr3nev3VpKAhup1+RvkMvUxURHpW7QyIvk9F5wz7Vzo06CEMSilw6uArgRqhpiUcWp8ew==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "estree-util-build-jsx": "^3.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/recma-jsx": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/recma-jsx/-/recma-jsx-1.0.0.tgz", + "integrity": "sha512-5vwkv65qWwYxg+Atz95acp8DMu1JDSqdGkA2Of1j6rCreyFUE/gp15fC8MnGEuG1W68UKjM6x6+YTWIh7hZM/Q==", + "license": "MIT", + "dependencies": { + "acorn-jsx": "^5.0.0", + "estree-util-to-js": "^2.0.0", + "recma-parse": "^1.0.0", + "recma-stringify": "^1.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/recma-parse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/recma-parse/-/recma-parse-1.0.0.tgz", + "integrity": "sha512-OYLsIGBB5Y5wjnSnQW6t3Xg7q3fQ7FWbw/vcXtORTnyaSFscOtABg+7Pnz6YZ6c27fG1/aN8CjfwoUEUIdwqWQ==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "esast-util-from-js": "^2.0.0", + "unified": "^11.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/recma-stringify": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/recma-stringify/-/recma-stringify-1.0.0.tgz", + "integrity": "sha512-cjwII1MdIIVloKvC9ErQ+OgAtwHBmcZ0Bg4ciz78FtbT8In39aAYbaA7zvxQ61xVMSPE8WxhLwLbhif4Js2C+g==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "estree-util-to-js": "^2.0.0", + "unified": "^11.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/redis-errors": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/redis-errors/-/redis-errors-1.2.0.tgz", + "integrity": "sha512-1qny3OExCf0UvUV/5wpYKf2YwPcOqXzkwKKSmKHiE6ZMQs5heeE/c8eXK+PNllPvmjgAbfnsbpkGZWy8cBpn9w==", + "license": "MIT", + "engines": { + "node": ">=4" + } + }, + "node_modules/redis-parser": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/redis-parser/-/redis-parser-3.0.0.tgz", + "integrity": "sha512-DJnGAeenTdpMEH6uAJRK/uiyEIH9WVsUmoLwzudwGJUwZPp80PDBWPHXSAGNPwNvIXAbe7MSUB1zQFugFml66A==", + "license": "MIT", + "dependencies": { + "redis-errors": "^1.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/reflect.getprototypeof": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/reflect.getprototypeof/-/reflect.getprototypeof-1.0.3.tgz", + "integrity": "sha512-TTAOZpkJ2YLxl7mVHWrNo3iDMEkYlva/kgFcXndqMgbo/AZUmmavEkdXV+hXtE4P8xdyEKRzalaFqZVuwIk/Nw==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4", + "get-intrinsic": "^1.1.1", + "globalthis": "^1.0.3", + "which-builtin-type": "^1.1.3" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/regenerate": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/regenerate/-/regenerate-1.4.2.tgz", + "integrity": "sha512-zrceR/XhGYU/d/opr2EKO7aRHUeiBI8qjtfHqADTwZd6Szfy16la6kqD0MIUs5z5hx6AaKa+PixpPrR289+I0A==", + "license": "MIT", + "peer": true + }, + "node_modules/regenerate-unicode-properties": { + "version": "10.1.1", + "resolved": "https://registry.npmjs.org/regenerate-unicode-properties/-/regenerate-unicode-properties-10.1.1.tgz", + "integrity": "sha512-X007RyZLsCJVVrjgEFVpLUTZwyOZk3oiL75ZcuYjlIWd6rNJtOjkBwQc5AsRrpbKVkxN6sklw/k/9m2jJYOf8Q==", + "license": "MIT", + "peer": true, + "dependencies": { + "regenerate": "^1.4.2" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/regenerator-runtime": { + "version": "0.14.0", + "resolved": "https://registry.npmjs.org/regenerator-runtime/-/regenerator-runtime-0.14.0.tgz", + "integrity": "sha512-srw17NI0TUWHuGa5CFGGmhfNIeja30WMBfbslPNhf6JrqQlLN5gcrvig1oqPxiVaXb0oW0XRKtH6Nngs5lKCIA==", + "license": "MIT" + }, + "node_modules/regenerator-transform": { + "version": "0.15.2", + "resolved": "https://registry.npmjs.org/regenerator-transform/-/regenerator-transform-0.15.2.tgz", + "integrity": "sha512-hfMp2BoF0qOk3uc5V20ALGDS2ddjQaLrdl7xrGXvAIow7qeWRM2VA2HuCHkUKk9slq3VwEwLNK3DFBqDfPGYtg==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/runtime": "^7.8.4" + } + }, + "node_modules/regexp.prototype.flags": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/regexp.prototype.flags/-/regexp.prototype.flags-1.5.0.tgz", + "integrity": "sha512-0SutC3pNudRKgquxGoRGIz946MZVHqbNfPjBdxeOhBrdgDKlRoXmYLQN9xRbrR09ZXWeGAdPuif7egofn6v5LA==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.2.0", + "functions-have-names": "^1.2.3" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/regexpu-core": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/regexpu-core/-/regexpu-core-5.3.2.tgz", + "integrity": "sha512-RAM5FlZz+Lhmo7db9L298p2vHP5ZywrVXmVXpmAD9GuL5MPH6t9ROw1iA/wfHkQ76Qe7AaPF0nGuim96/IrQMQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "@babel/regjsgen": "^0.8.0", + "regenerate": "^1.4.2", + "regenerate-unicode-properties": "^10.1.0", + "regjsparser": "^0.9.1", + "unicode-match-property-ecmascript": "^2.0.0", + "unicode-match-property-value-ecmascript": "^2.1.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/regjsparser": { + "version": "0.9.1", + "resolved": "https://registry.npmjs.org/regjsparser/-/regjsparser-0.9.1.tgz", + "integrity": "sha512-dQUtn90WanSNl+7mQKcXAgZxvUe7Z0SqXlgzv0za4LwiUhyzBC58yQO3liFoUgu8GiJVInAhJjkj1N0EtQ5nkQ==", + "license": "BSD-2-Clause", + "peer": true, + "dependencies": { + "jsesc": "~0.5.0" + }, + "bin": { + "regjsparser": "bin/parser" + } + }, + "node_modules/regjsparser/node_modules/jsesc": { + "version": "0.5.0", + "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-0.5.0.tgz", + "integrity": "sha512-uZz5UnB7u4T9LvwmFqXii7pZSouaRPorGs5who1Ip7VO0wxanFvBL7GkM6dTHlgX+jhBApRetaWpnDabOeTcnA==", + "peer": true, + "bin": { + "jsesc": "bin/jsesc" + } + }, + "node_modules/rehype-recma": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/rehype-recma/-/rehype-recma-1.0.0.tgz", + "integrity": "sha512-lqA4rGUf1JmacCNWWZx0Wv1dHqMwxzsDWYMTowuplHF3xH0N/MmrZ/G3BDZnzAkRmxDadujCjaKM2hqYdCBOGw==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/hast": "^3.0.0", + "hast-util-to-estree": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-mdx": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/remark-mdx/-/remark-mdx-3.1.0.tgz", + "integrity": "sha512-Ngl/H3YXyBV9RcRNdlYsZujAmhsxwzxpDzpDEhFBVAGthS4GDgnctpDjgFl/ULx5UEDzqtW1cyBSNKqYYrqLBA==", + "license": "MIT", + "dependencies": { + "mdast-util-mdx": "^3.0.0", + "micromark-extension-mdxjs": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-parse": { + "version": "11.0.0", + "resolved": "https://registry.npmjs.org/remark-parse/-/remark-parse-11.0.0.tgz", + "integrity": "sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-from-markdown": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-rehype": { + "version": "11.1.1", + "resolved": "https://registry.npmjs.org/remark-rehype/-/remark-rehype-11.1.1.tgz", + "integrity": "sha512-g/osARvjkBXb6Wo0XvAeXQohVta8i84ACbenPpoSsxTOQH/Ae0/RGP4WZgnMH5pMLpsj4FG7OHmcIcXxpza8eQ==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "mdast-util-to-hast": "^13.0.0", + "unified": "^11.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/require-directory": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", + "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/require-main-filename": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/require-main-filename/-/require-main-filename-2.0.0.tgz", + "integrity": "sha512-NKN5kMDylKuldxYLSUfrbo5Tuzh4hd+2E8NPPX02mZtn1VuREQToYe/ZdlJy+J3uCpfaiGF05e7B8W0iXbQHmg==", + "license": "ISC", + "peer": true + }, + "node_modules/requires-port": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/requires-port/-/requires-port-1.0.0.tgz", + "integrity": "sha512-KigOCHcocU3XODJxsu8i/j8T9tzT4adHiecwORRQ0ZZFcp7ahwXuRU1m+yuO90C5ZUyGeGfocHDI14M3L3yDAQ==", + "license": "MIT" + }, + "node_modules/resize-observer-polyfill": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/resize-observer-polyfill/-/resize-observer-polyfill-1.5.1.tgz", + "integrity": "sha512-LwZrotdHOo12nQuZlHEmtuXdqGoOD0OhaxopaNFxWzInpEgaLWoVuAMbTzixuosCx2nEG58ngzW3vxdWoxIgdg==", + "license": "MIT", + "peer": true + }, + "node_modules/resolve": { + "version": "1.22.4", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.4.tgz", + "integrity": "sha512-PXNdCiPqDqeUou+w1C2eTQbNfxKSuMxqTCuvlmmMsk1NWHL5fRrhY6Pl0qEYYc6+QqGClco1Qj8XnjPego4wfg==", + "license": "MIT", + "dependencies": { + "is-core-module": "^2.13.0", + "path-parse": "^1.0.7", + "supports-preserve-symlinks-flag": "^1.0.0" + }, + "bin": { + "resolve": "bin/resolve" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/resolve-from": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-4.0.0.tgz", + "integrity": "sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=4" + } + }, + "node_modules/resolve-pkg-maps": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz", + "integrity": "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1" + } + }, + "node_modules/restore-cursor": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/restore-cursor/-/restore-cursor-3.1.0.tgz", + "integrity": "sha512-l+sSefzHpj5qimhFSE5a8nufZYAM3sBSVMAPtYkmC+4EH2anSGaEMXSD0izRQbu9nfyQ9y5JrVmp7E8oZrUjvA==", + "license": "MIT", + "peer": true, + "dependencies": { + "onetime": "^5.1.0", + "signal-exit": "^3.0.2" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/reusify": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.0.4.tgz", + "integrity": "sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw==", + "license": "MIT", + "engines": { + "iojs": ">=1.0.0", + "node": ">=0.10.0" + } + }, + "node_modules/rimraf": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-3.0.2.tgz", + "integrity": "sha512-JZkJMZkAGFFPP2YqXZXPbMlMBgsxzE8ILs4lMIX/2o0L9UBw9O/Y3o6wFw/i9YLapcUJWwqbi3kdxIPdC62TIA==", + "deprecated": "Rimraf versions prior to v4 are no longer supported", + "license": "ISC", + "dependencies": { + "glob": "^7.1.3" + }, + "bin": { + "rimraf": "bin.js" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/run-parallel": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz", + "integrity": "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT", + "dependencies": { + "queue-microtask": "^1.2.2" + } + }, + "node_modules/sade": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/sade/-/sade-1.8.1.tgz", + "integrity": "sha512-xal3CZX1Xlo/k4ApwCFrHVACi9fBqJ7V+mwhBsuf/1IOKbBy098Fex+Wa/5QMubw09pSZ/u8EY8PWgevJsXp1A==", + "license": "MIT", + "dependencies": { + "mri": "^1.1.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/safe-array-concat": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/safe-array-concat/-/safe-array-concat-1.0.0.tgz", + "integrity": "sha512-9dVEFruWIsnie89yym+xWTAYASdpw3CJV7Li/6zBewGf9z2i1j31rP6jnY0pHEO4QZh6N0K11bFjWmdR8UGdPQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "get-intrinsic": "^1.2.0", + "has-symbols": "^1.0.3", + "isarray": "^2.0.5" + }, + "engines": { + "node": ">=0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/safe-buffer": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz", + "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==", + "license": "MIT" + }, + "node_modules/safe-regex-test": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/safe-regex-test/-/safe-regex-test-1.0.0.tgz", + "integrity": "sha512-JBUUzyOgEwXQY1NuPtvcj/qcBDbDmEvWufhlnXZIm75DEHp+afM1r1ujJpJsV/gSM4t59tpDyPi1sd6ZaPFfsA==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "get-intrinsic": "^1.1.3", + "is-regex": "^1.1.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/scheduler": { + "version": "0.23.0", + "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.0.tgz", + "integrity": "sha512-CtuThmgHNg7zIZWAXi3AsyIzA3n4xx7aNyjwC2VJldO2LMVDhFK+63xGqq6CsJH4rTAt6/M+N4GhZiDYPx9eUw==", + "license": "MIT", + "dependencies": { + "loose-envify": "^1.1.0" + } + }, + "node_modules/semver": { + "version": "7.5.4", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.5.4.tgz", + "integrity": "sha512-1bCSESV6Pv+i21Hvpxp3Dx+pSD8lIPt8uVjRrxAUt/nbswYc+tK6Y2btiULjd4+fnq15PX+nqQDC7Oft7WkwcA==", + "license": "ISC", + "dependencies": { + "lru-cache": "^6.0.0" + }, + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/send": { + "version": "0.18.0", + "resolved": "https://registry.npmjs.org/send/-/send-0.18.0.tgz", + "integrity": "sha512-qqWzuOjSFOuqPjFe4NOsMLafToQQwBSOEpS+FwEt3A2V3vKubTquT3vmLTQpFgMXp8AlFWFuP1qKaJZOtPpVXg==", + "license": "MIT", + "peer": true, + "dependencies": { + "debug": "2.6.9", + "depd": "2.0.0", + "destroy": "1.2.0", + "encodeurl": "~1.0.2", + "escape-html": "~1.0.3", + "etag": "~1.8.1", + "fresh": "0.5.2", + "http-errors": "2.0.0", + "mime": "1.6.0", + "ms": "2.1.3", + "on-finished": "2.4.1", + "range-parser": "~1.2.1", + "statuses": "2.0.1" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/send/node_modules/debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "license": "MIT", + "peer": true, + "dependencies": { + "ms": "2.0.0" + } + }, + "node_modules/send/node_modules/debug/node_modules/ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "license": "MIT", + "peer": true + }, + "node_modules/send/node_modules/mime": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/mime/-/mime-1.6.0.tgz", + "integrity": "sha512-x0Vn8spI+wuJ1O6S7gnbaQg8Pxh4NNHb7KSINmEWKiPE4RKOplvijn+NkmYmmRgP68mc70j2EbeTFRsrswaQeg==", + "license": "MIT", + "peer": true, + "bin": { + "mime": "cli.js" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/send/node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "license": "MIT", + "peer": true + }, + "node_modules/send/node_modules/on-finished": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz", + "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==", + "license": "MIT", + "peer": true, + "dependencies": { + "ee-first": "1.1.1" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/send/node_modules/statuses": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.1.tgz", + "integrity": "sha512-RwNA9Z/7PrK06rYLIzFMlaF+l73iwpzsqRIFgbMLbTcLD6cOao82TaWefPXQvB2fOC4AjuYSEndS7N/mTCbkdQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/serialize-error": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/serialize-error/-/serialize-error-2.1.0.tgz", + "integrity": "sha512-ghgmKt5o4Tly5yEG/UJp8qTd0AN7Xalw4XBtDEKP655B699qMEtra1WlXeE6WIvdEG481JvRxULKsInq/iNysw==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/serve-static": { + "version": "1.15.0", + "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-1.15.0.tgz", + "integrity": "sha512-XGuRDNjXUijsUL0vl6nSD7cwURuzEgglbOaFuZM9g3kwDXOWVTck0jLzjPzGD+TazWbboZYu52/9/XPdUgne9g==", + "license": "MIT", + "peer": true, + "dependencies": { + "encodeurl": "~1.0.2", + "escape-html": "~1.0.3", + "parseurl": "~1.3.3", + "send": "0.18.0" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/set-blocking": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz", + "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==", + "license": "ISC" + }, + "node_modules/setprototypeof": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz", + "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==", + "license": "ISC", + "peer": true + }, + "node_modules/shallow-clone": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/shallow-clone/-/shallow-clone-3.0.1.tgz", + "integrity": "sha512-/6KqX+GVUdqPuPPd2LxDDxzX6CAbjJehAAOKlNpqqUpAqPM6HeL8f+o3a+JsyGjn2lv0WY8UsTgUJjU9Ok55NA==", + "license": "MIT", + "peer": true, + "dependencies": { + "kind-of": "^6.0.2" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "license": "MIT", + "dependencies": { + "shebang-regex": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/shell-quote": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.8.1.tgz", + "integrity": "sha512-6j1W9l1iAs/4xYBI1SYOVZyFcCis9b4KCLQ8fgAGG07QvzaRLVVRQvAy85yNmmZSjYjg4MWh4gNvlPujU/5LpA==", + "license": "MIT", + "peer": true, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.0.4.tgz", + "integrity": "sha512-q5XPytqFEIKHkGdiMIrY10mvLRvnQh42/+GoBlFW3b2LXLE2xxJpZFdm94we0BaoV3RwJyGqg5wS7epxTv0Zvw==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.0", + "get-intrinsic": "^1.0.2", + "object-inspect": "^1.9.0" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/signal-exit": { + "version": "3.0.7", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz", + "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==", + "license": "ISC" + }, + "node_modules/sisteransi": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/sisteransi/-/sisteransi-1.0.5.tgz", + "integrity": "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==", + "license": "MIT", + "peer": true + }, + "node_modules/slash": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz", + "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/slice-ansi": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-2.1.0.tgz", + "integrity": "sha512-Qu+VC3EwYLldKa1fCxuuvULvSJOKEgk9pi8dZeCVK7TqBfUNTH4sFkk4joj8afVSfAYgJoSOetjx9QWOJ5mYoQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "ansi-styles": "^3.2.0", + "astral-regex": "^1.0.0", + "is-fullwidth-code-point": "^2.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/slice-ansi/node_modules/ansi-styles": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", + "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", + "license": "MIT", + "peer": true, + "dependencies": { + "color-convert": "^1.9.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/slice-ansi/node_modules/color-convert": { + "version": "1.9.3", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", + "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", + "license": "MIT", + "peer": true, + "dependencies": { + "color-name": "1.1.3" + } + }, + "node_modules/slice-ansi/node_modules/color-name": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", + "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==", + "license": "MIT", + "peer": true + }, + "node_modules/sonner": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/sonner/-/sonner-2.0.5.tgz", + "integrity": "sha512-YwbHQO6cSso3HBXlbCkgrgzDNIhws14r4MO87Ofy+cV2X7ES4pOoAK3+veSmVTvqNx1BWUxlhPmZzP00Crk2aQ==", + "license": "MIT", + "peerDependencies": { + "react": "^18.0.0 || ^19.0.0 || ^19.0.0-rc", + "react-dom": "^18.0.0 || ^19.0.0 || ^19.0.0-rc" + } + }, + "node_modules/source-map": { + "version": "0.7.4", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.7.4.tgz", + "integrity": "sha512-l3BikUxvPOcn5E74dZiq5BGsTb5yEwhaTSzccU6t4sDOH8NWJCstKO5QT2CvtFoK6F0saL7p9xHAqHOlCPJygA==", + "license": "BSD-3-Clause", + "engines": { + "node": ">= 8" + } + }, + "node_modules/source-map-js": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.0.2.tgz", + "integrity": "sha512-R0XvVJ9WusLiqTCEiGCmICCMplcCkIwwR11mOSD9CR5u+IXYdiseeEuXCVAjS54zqwkLcPNnmU4OeJ6tUrWhDw==", + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/source-map-support": { + "version": "0.5.21", + "resolved": "https://registry.npmjs.org/source-map-support/-/source-map-support-0.5.21.tgz", + "integrity": "sha512-uBHU3L3czsIyYXKX88fdrGovxdSCoTGDRZ6SYXtSRxLZUzHg5P/66Ht6uoUlHu9EZod+inXhKo3qQgwXUT/y1w==", + "license": "MIT", + "peer": true, + "dependencies": { + "buffer-from": "^1.0.0", + "source-map": "^0.6.0" + } + }, + "node_modules/source-map-support/node_modules/source-map": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", + "license": "BSD-3-Clause", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/space-separated-tokens": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/space-separated-tokens/-/space-separated-tokens-2.0.2.tgz", + "integrity": "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/sprintf-js": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", + "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==", + "license": "BSD-3-Clause", + "peer": true + }, + "node_modules/stack-utils": { + "version": "2.0.6", + "resolved": "https://registry.npmjs.org/stack-utils/-/stack-utils-2.0.6.tgz", + "integrity": "sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "escape-string-regexp": "^2.0.0" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/stack-utils/node_modules/escape-string-regexp": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz", + "integrity": "sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/stackframe": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/stackframe/-/stackframe-1.3.4.tgz", + "integrity": "sha512-oeVtt7eWQS+Na6F//S4kJ2K2VbRlS9D43mAlMyVpVWovy9o+jfgH8O9agzANzaiLjclA0oYzUXEM4PurhSUChw==", + "license": "MIT", + "peer": true + }, + "node_modules/stacktrace-parser": { + "version": "0.1.10", + "resolved": "https://registry.npmjs.org/stacktrace-parser/-/stacktrace-parser-0.1.10.tgz", + "integrity": "sha512-KJP1OCML99+8fhOHxwwzyWrlUuVX5GQ0ZpJTd1DFXhdkrvg1szxfHhawXUZ3g9TkXORQd4/WG68jMlQZ2p8wlg==", + "license": "MIT", + "peer": true, + "dependencies": { + "type-fest": "^0.7.1" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/stacktrace-parser/node_modules/type-fest": { + "version": "0.7.1", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.7.1.tgz", + "integrity": "sha512-Ne2YiiGN8bmrmJJEuTWTLJR32nh/JdL1+PSicowtNb0WFpn59GK8/lfD61bVtzguz7b3PBt74nxpv/Pw5po5Rg==", + "license": "(MIT OR CC0-1.0)", + "peer": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/standard-as-callback": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/standard-as-callback/-/standard-as-callback-2.1.0.tgz", + "integrity": "sha512-qoRRSyROncaz1z0mvYqIE4lCd9p2R90i6GxW3uZv5ucSu8tU7B5HXUP1gG8pVZsYNVaXjk8ClXHPttLyxAL48A==", + "license": "MIT" + }, + "node_modules/state-local": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/state-local/-/state-local-1.0.7.tgz", + "integrity": "sha512-HTEHMNieakEnoe33shBYcZ7NX83ACUjCu8c40iOGEZsngj9zRnkqS9j1pqQPXwobB0ZcVTk27REb7COQ0UR59w==", + "license": "MIT" + }, + "node_modules/statuses": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/statuses/-/statuses-1.5.0.tgz", + "integrity": "sha512-OpZ3zP+jT1PI7I8nemJX4AKmAX070ZkYPVWV/AaKTJl+tXCTGyVdC1a4SL8RUQYEwk/f34ZX8UTykN68FwrqAA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/streamsearch": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/streamsearch/-/streamsearch-1.1.0.tgz", + "integrity": "sha512-Mcc5wHehp9aXz1ax6bZUyY5afg9u2rv5cqQI3mRrYkGC8rW2hM02jWuwjtL++LS5qinSyhj2QfLyNsuc+VsExg==", + "engines": { + "node": ">=10.0.0" + } + }, + "node_modules/string_decoder": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz", + "integrity": "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==", + "license": "MIT", + "dependencies": { + "safe-buffer": "~5.2.0" + } + }, + "node_modules/string_decoder/node_modules/safe-buffer": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz", + "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT" + }, + "node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "license": "MIT", + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/string-width/node_modules/emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", + "license": "MIT" + }, + "node_modules/string-width/node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/string.prototype.matchall": { + "version": "4.0.8", + "resolved": "https://registry.npmjs.org/string.prototype.matchall/-/string.prototype.matchall-4.0.8.tgz", + "integrity": "sha512-6zOCOcJ+RJAQshcTvXPHoxoQGONa3e/Lqx90wUA+wEzX78sg5Bo+1tQo4N0pohS0erG9qtCqJDjNCQBjeWVxyg==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4", + "get-intrinsic": "^1.1.3", + "has-symbols": "^1.0.3", + "internal-slot": "^1.0.3", + "regexp.prototype.flags": "^1.4.3", + "side-channel": "^1.0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/string.prototype.trim": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/string.prototype.trim/-/string.prototype.trim-1.2.7.tgz", + "integrity": "sha512-p6TmeT1T3411M8Cgg9wBTMRtY2q9+PNy9EV1i2lIXUN/btt763oIfxwN3RR8VU6wHX8j/1CFy0L+YuThm6bgOg==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/string.prototype.trimend": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/string.prototype.trimend/-/string.prototype.trimend-1.0.6.tgz", + "integrity": "sha512-JySq+4mrPf9EsDBEDYMOb/lM7XQLulwg5R/m1r0PXEFqrV0qHvl58sdTilSXtKOflCsK2E8jxf+GKC0T07RWwQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/string.prototype.trimstart": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/string.prototype.trimstart/-/string.prototype.trimstart-1.0.6.tgz", + "integrity": "sha512-omqjMDaY92pbn5HOX7f9IccLA+U1tA9GvtU4JrodiXFfYB7jPzzHpRzpglLAjtUV6bB557zwClJezTqnAiYnQA==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/stringify-entities": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/stringify-entities/-/stringify-entities-4.0.4.tgz", + "integrity": "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==", + "license": "MIT", + "dependencies": { + "character-entities-html4": "^2.0.0", + "character-entities-legacy": "^3.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/strip-bom": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/strip-bom/-/strip-bom-3.0.0.tgz", + "integrity": "sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=4" + } + }, + "node_modules/strip-final-newline": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/strip-final-newline/-/strip-final-newline-2.0.0.tgz", + "integrity": "sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/strip-json-comments": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz", + "integrity": "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/strnum": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/strnum/-/strnum-1.0.5.tgz", + "integrity": "sha512-J8bbNyKKXl5qYcR36TIO8W3mVGVHrmmxsd5PAItGkmyzwJvybiw2IVq5nqd0i4LSNSkB/sx9VHllbfFdr9k1JA==", + "license": "MIT", + "peer": true + }, + "node_modules/style-to-object": { + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/style-to-object/-/style-to-object-1.0.8.tgz", + "integrity": "sha512-xT47I/Eo0rwJmaXC4oilDGDWLohVhR6o/xAQcPQN8q6QBuZVL8qMYL85kLmST5cPjAorwvqIA4qXTRQoYHaL6g==", + "license": "MIT", + "dependencies": { + "inline-style-parser": "0.2.4" + } + }, + "node_modules/styled-jsx": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/styled-jsx/-/styled-jsx-5.1.1.tgz", + "integrity": "sha512-pW7uC1l4mBZ8ugbiZrcIsiIvVx1UmTfw7UkC3Um2tmfUq9Bhk8IiyEIPl6F8agHgjzku6j0xQEZbfA5uSgSaCw==", + "license": "MIT", + "dependencies": { + "client-only": "0.0.1" + }, + "engines": { + "node": ">= 12.0.0" + }, + "peerDependencies": { + "react": ">= 16.8.0 || 17.x.x || ^18.0.0-0" + }, + "peerDependenciesMeta": { + "@babel/core": { + "optional": true + }, + "babel-plugin-macros": { + "optional": true + } + } + }, + "node_modules/sucrase": { + "version": "3.34.0", + "resolved": "https://registry.npmjs.org/sucrase/-/sucrase-3.34.0.tgz", + "integrity": "sha512-70/LQEZ07TEcxiU2dz51FKaE6hCTWC6vr7FOk3Gr0U60C3shtAN+H+BFr9XlYe5xqf3RA8nrc+VIwzCfnxuXJw==", + "license": "MIT", + "dependencies": { + "@jridgewell/gen-mapping": "^0.3.2", + "commander": "^4.0.0", + "glob": "7.1.6", + "lines-and-columns": "^1.1.6", + "mz": "^2.7.0", + "pirates": "^4.0.1", + "ts-interface-checker": "^0.1.9" + }, + "bin": { + "sucrase": "bin/sucrase", + "sucrase-node": "bin/sucrase-node" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/sucrase/node_modules/commander": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/commander/-/commander-4.1.1.tgz", + "integrity": "sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==", + "license": "MIT", + "engines": { + "node": ">= 6" + } + }, + "node_modules/sucrase/node_modules/glob": { + "version": "7.1.6", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.1.6.tgz", + "integrity": "sha512-LwaxwyZ72Lk7vZINtNNrywX0ZuLyStrdDtabefZKAY5ZGJhVtgdznluResxNmPitE0SAO+O26sWTHeKSI2wMBA==", + "deprecated": "Glob versions prior to v9 are no longer supported", + "license": "ISC", + "dependencies": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.0.4", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + }, + "engines": { + "node": "*" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/sudo-prompt": { + "version": "9.2.1", + "resolved": "https://registry.npmjs.org/sudo-prompt/-/sudo-prompt-9.2.1.tgz", + "integrity": "sha512-Mu7R0g4ig9TUuGSxJavny5Rv0egCEtpZRNMrZaYS1vxkiIxGiGUwoezU3LazIQ+KE04hTrTfNPgxU5gzi7F5Pw==", + "deprecated": "Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.", + "license": "MIT", + "peer": true + }, + "node_modules/superjson": { + "version": "1.13.1", + "resolved": "https://registry.npmjs.org/superjson/-/superjson-1.13.1.tgz", + "integrity": "sha512-AVH2eknm9DEd3qvxM4Sq+LTCkSXE2ssfh1t11MHMXyYXFQyQ1HLgVvV+guLTsaQnJU3gnaVo34TohHPulY/wLg==", + "license": "MIT", + "dependencies": { + "copy-anything": "^3.0.2" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "license": "MIT", + "dependencies": { + "has-flag": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/supports-preserve-symlinks-flag": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz", + "integrity": "sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/suspend-react": { + "version": "0.1.3", + "resolved": "https://registry.npmjs.org/suspend-react/-/suspend-react-0.1.3.tgz", + "integrity": "sha512-aqldKgX9aZqpoDp3e8/BZ8Dm7x1pJl+qI3ZKxDN0i/IQTWUwBx/ManmlVJ3wowqbno6c2bmiIfs+Um6LbsjJyQ==", + "license": "MIT", + "peer": true, + "peerDependencies": { + "react": ">=17.0" + } + }, + "node_modules/tailwind-merge": { + "version": "1.14.0", + "resolved": "https://registry.npmjs.org/tailwind-merge/-/tailwind-merge-1.14.0.tgz", + "integrity": "sha512-3mFKyCo/MBcgyOTlrY8T7odzZFx+w+qKSMAmdFzRvqBfLlSigU6TZnlFHK0lkMwj9Bj8OYU+9yW9lmGuS0QEnQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/dcastil" + } + }, + "node_modules/tailwindcss": { + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-3.3.3.tgz", + "integrity": "sha512-A0KgSkef7eE4Mf+nKJ83i75TMyq8HqY3qmFIJSWy8bNt0v1lG7jUcpGpoTFxAwYcWOphcTBLPPJg+bDfhDf52w==", + "license": "MIT", + "dependencies": { + "@alloc/quick-lru": "^5.2.0", + "arg": "^5.0.2", + "chokidar": "^3.5.3", + "didyoumean": "^1.2.2", + "dlv": "^1.1.3", + "fast-glob": "^3.2.12", + "glob-parent": "^6.0.2", + "is-glob": "^4.0.3", + "jiti": "^1.18.2", + "lilconfig": "^2.1.0", + "micromatch": "^4.0.5", + "normalize-path": "^3.0.0", + "object-hash": "^3.0.0", + "picocolors": "^1.0.0", + "postcss": "^8.4.23", + "postcss-import": "^15.1.0", + "postcss-js": "^4.0.1", + "postcss-load-config": "^4.0.1", + "postcss-nested": "^6.0.1", + "postcss-selector-parser": "^6.0.11", + "resolve": "^1.22.2", + "sucrase": "^3.32.0" + }, + "bin": { + "tailwind": "lib/cli.js", + "tailwindcss": "lib/cli.js" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/tailwindcss-animate": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/tailwindcss-animate/-/tailwindcss-animate-1.0.6.tgz", + "integrity": "sha512-4WigSGMvbl3gCCact62ZvOngA+PRqhAn7si3TQ3/ZuPuQZcIEtVap+ENSXbzWhpojKB8CpvnIsrwBu8/RnHtuw==", + "license": "MIT", + "peerDependencies": { + "tailwindcss": ">=3.0.0 || insiders" + } + }, + "node_modules/tailwindcss/node_modules/object-hash": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/object-hash/-/object-hash-3.0.0.tgz", + "integrity": "sha512-RSn9F68PjH9HqtltsSnqYC1XXoWe9Bju5+213R98cNGttag9q9yAOTzdbsqvIa7aNm5WffBZFpWYr2aWrklWAw==", + "license": "MIT", + "engines": { + "node": ">= 6" + } + }, + "node_modules/tapable": { + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/tapable/-/tapable-2.2.1.tgz", + "integrity": "sha512-GNzQvQTOIP6RyTfE2Qxb8ZVlNmw0n88vp1szwWRimP02mnTsx3Wtn5qRdqY9w2XduFNUgvOwhNnQsjwCp+kqaQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/tar": { + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/tar/-/tar-6.2.0.tgz", + "integrity": "sha512-/Wo7DcT0u5HUV486xg675HtjNd3BXZ6xDbzsCUZPt5iw8bTQ63bP0Raut3mvro9u+CUyq7YQd8Cx55fsZXxqLQ==", + "license": "ISC", + "dependencies": { + "chownr": "^2.0.0", + "fs-minipass": "^2.0.0", + "minipass": "^5.0.0", + "minizlib": "^2.1.1", + "mkdirp": "^1.0.3", + "yallist": "^4.0.0" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/tar/node_modules/mkdirp": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz", + "integrity": "sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==", + "license": "MIT", + "bin": { + "mkdirp": "bin/cmd.js" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/temp": { + "version": "0.8.4", + "resolved": "https://registry.npmjs.org/temp/-/temp-0.8.4.tgz", + "integrity": "sha512-s0ZZzd0BzYv5tLSptZooSjK8oj6C+c19p7Vqta9+6NPOf7r+fxq0cJe6/oN4LTC79sy5NY8ucOJNgwsKCSbfqg==", + "license": "MIT", + "peer": true, + "dependencies": { + "rimraf": "~2.6.2" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/temp/node_modules/rimraf": { + "version": "2.6.3", + "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-2.6.3.tgz", + "integrity": "sha512-mwqeW5XsA2qAejG46gYdENaxXjx9onRNCfn7L0duuP4hCuTIi/QO7PDK07KJfp1d+izWPrzEJDcSqBa0OZQriA==", + "deprecated": "Rimraf versions prior to v4 are no longer supported", + "license": "ISC", + "peer": true, + "dependencies": { + "glob": "^7.1.3" + }, + "bin": { + "rimraf": "bin.js" + } + }, + "node_modules/terser": { + "version": "5.19.4", + "resolved": "https://registry.npmjs.org/terser/-/terser-5.19.4.tgz", + "integrity": "sha512-6p1DjHeuluwxDXcuT9VR8p64klWJKo1ILiy19s6C9+0Bh2+NWTX6nD9EPppiER4ICkHDVB1RkVpin/YW2nQn/g==", + "license": "BSD-2-Clause", + "peer": true, + "dependencies": { + "@jridgewell/source-map": "^0.3.3", + "acorn": "^8.8.2", + "commander": "^2.20.0", + "source-map-support": "~0.5.20" + }, + "bin": { + "terser": "bin/terser" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/terser/node_modules/commander": { + "version": "2.20.3", + "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz", + "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", + "license": "MIT", + "peer": true + }, + "node_modules/text-table": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/text-table/-/text-table-0.2.0.tgz", + "integrity": "sha512-N+8UisAXDGk8PFXP4HAzVR9nbfmVJ3zYLAWiTIoqC5v5isinhr+r5uaO8+7r3BMfuNIufIsA7RdpVgacC2cSpw==", + "dev": true, + "license": "MIT" + }, + "node_modules/thenify": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/thenify/-/thenify-3.3.1.tgz", + "integrity": "sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw==", + "license": "MIT", + "dependencies": { + "any-promise": "^1.0.0" + } + }, + "node_modules/thenify-all": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/thenify-all/-/thenify-all-1.6.0.tgz", + "integrity": "sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==", + "license": "MIT", + "dependencies": { + "thenify": ">= 3.1.0 < 4" + }, + "engines": { + "node": ">=0.8" + } + }, + "node_modules/three": { + "version": "0.156.1", + "resolved": "https://registry.npmjs.org/three/-/three-0.156.1.tgz", + "integrity": "sha512-kP7H0FK9d/k6t/XvQ9FO6i+QrePoDcNhwl0I02+wmUJRNSLCUIDMcfObnzQvxb37/0Uc9TDT0T1HgsRRrO6SYQ==", + "license": "MIT", + "peer": true + }, + "node_modules/throat": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/throat/-/throat-5.0.0.tgz", + "integrity": "sha512-fcwX4mndzpLQKBS1DVYhGAcYaYt7vsHNIvQV+WXMvnow5cgjPphq5CaayLaGsjRdSCKZFNGt7/GYAuXaNOiYCA==", + "license": "MIT", + "peer": true + }, + "node_modules/through2": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/through2/-/through2-2.0.5.tgz", + "integrity": "sha512-/mrRod8xqpA+IHSLyGCQ2s8SPHiCDEeQJSep1jqLYeEUClOFG2Qsh+4FU6G9VeqpZnGW/Su8LQGc4YKni5rYSQ==", + "license": "MIT", + "peer": true, + "dependencies": { + "readable-stream": "~2.3.6", + "xtend": "~4.0.1" + } + }, + "node_modules/through2/node_modules/isarray": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz", + "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==", + "license": "MIT", + "peer": true + }, + "node_modules/through2/node_modules/readable-stream": { + "version": "2.3.8", + "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz", + "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==", + "license": "MIT", + "peer": true, + "dependencies": { + "core-util-is": "~1.0.0", + "inherits": "~2.0.3", + "isarray": "~1.0.0", + "process-nextick-args": "~2.0.0", + "safe-buffer": "~5.1.1", + "string_decoder": "~1.1.1", + "util-deprecate": "~1.0.1" + } + }, + "node_modules/through2/node_modules/string_decoder": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz", + "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==", + "license": "MIT", + "peer": true, + "dependencies": { + "safe-buffer": "~5.1.0" + } + }, + "node_modules/tiny-invariant": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/tiny-invariant/-/tiny-invariant-1.3.3.tgz", + "integrity": "sha512-+FbBPE1o9QAYvviau/qC5SE3caw21q3xkvWKBtja5vgqOWIHHJ3ioaq1VPfn/Szqctz2bU/oYeKd9/z5BL+PVg==", + "license": "MIT" + }, + "node_modules/tmpl": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/tmpl/-/tmpl-1.0.5.tgz", + "integrity": "sha512-3f0uOEAQwIqGuWW2MVzYg8fV/QNnc/IpuJNG837rLuczAaLVHslWHZQj4IGiEl5Hs3kkbhwL9Ab7Hrsmuj+Smw==", + "license": "BSD-3-Clause", + "peer": true + }, + "node_modules/to-fast-properties": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/to-fast-properties/-/to-fast-properties-2.0.0.tgz", + "integrity": "sha512-/OaKK0xYrs3DmxRYqL/yDc+FxFUVYhDlXMhRmv3z915w2HF1tnN1omB354j8VUGO/hbRzyD6Y3sA7v7GS/ceog==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/to-regex-range": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz", + "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==", + "license": "MIT", + "dependencies": { + "is-number": "^7.0.0" + }, + "engines": { + "node": ">=8.0" + } + }, + "node_modules/toidentifier": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz", + "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.6" + } + }, + "node_modules/tr46": { + "version": "0.0.3", + "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz", + "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==", + "license": "MIT" + }, + "node_modules/trim-lines": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz", + "integrity": "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/trough": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/trough/-/trough-2.1.0.tgz", + "integrity": "sha512-AqTiAOLcj85xS7vQ8QkAV41hPDIJ71XJB4RCUrzo/1GM2CQwhkJGaf9Hgr7BOugMRpgGUrqRg/DrBDl4H40+8g==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/ts-api-utils": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-1.0.1.tgz", + "integrity": "sha512-lC/RGlPmwdrIBFTX59wwNzqh7aR2otPNPR/5brHZm/XKFYKsfqxihXUe9pU3JI+3vGkl+vyCoNNnPhJn3aLK1A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=16.13.0" + }, + "peerDependencies": { + "typescript": ">=4.2.0" + } + }, + "node_modules/ts-interface-checker": { + "version": "0.1.13", + "resolved": "https://registry.npmjs.org/ts-interface-checker/-/ts-interface-checker-0.1.13.tgz", + "integrity": "sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==", + "license": "Apache-2.0" + }, + "node_modules/ts-node": { + "version": "10.9.2", + "resolved": "https://registry.npmjs.org/ts-node/-/ts-node-10.9.2.tgz", + "integrity": "sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ==", + "license": "MIT", + "dependencies": { + "@cspotcode/source-map-support": "^0.8.0", + "@tsconfig/node10": "^1.0.7", + "@tsconfig/node12": "^1.0.7", + "@tsconfig/node14": "^1.0.0", + "@tsconfig/node16": "^1.0.2", + "acorn": "^8.4.1", + "acorn-walk": "^8.1.1", + "arg": "^4.1.0", + "create-require": "^1.1.0", + "diff": "^4.0.1", + "make-error": "^1.1.1", + "v8-compile-cache-lib": "^3.0.1", + "yn": "3.1.1" + }, + "bin": { + "ts-node": "dist/bin.js", + "ts-node-cwd": "dist/bin-cwd.js", + "ts-node-esm": "dist/bin-esm.js", + "ts-node-script": "dist/bin-script.js", + "ts-node-transpile-only": "dist/bin-transpile.js", + "ts-script": "dist/bin-script-deprecated.js" + }, + "peerDependencies": { + "@swc/core": ">=1.2.50", + "@swc/wasm": ">=1.2.50", + "@types/node": "*", + "typescript": ">=2.7" + }, + "peerDependenciesMeta": { + "@swc/core": { + "optional": true + }, + "@swc/wasm": { + "optional": true + } + } + }, + "node_modules/ts-node/node_modules/arg": { + "version": "4.1.3", + "resolved": "https://registry.npmjs.org/arg/-/arg-4.1.3.tgz", + "integrity": "sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA==", + "license": "MIT" + }, + "node_modules/tsconfig-paths": { + "version": "3.14.2", + "resolved": "https://registry.npmjs.org/tsconfig-paths/-/tsconfig-paths-3.14.2.tgz", + "integrity": "sha512-o/9iXgCYc5L/JxCHPe3Hvh8Q/2xm5Z+p18PESBU6Ff33695QnCHBEjcytY2q19ua7Mbl/DavtBOLq+oG0RCL+g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/json5": "^0.0.29", + "json5": "^1.0.2", + "minimist": "^1.2.6", + "strip-bom": "^3.0.0" + } + }, + "node_modules/tsconfig-paths/node_modules/json5": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/json5/-/json5-1.0.2.tgz", + "integrity": "sha512-g1MWMLBiz8FKi1e4w0UyVL3w+iJceWAFBAaBnnGKOpNa5f8TLktkbre1+s6oICydWAm+HRUGTmI+//xv2hvXYA==", + "dev": true, + "license": "MIT", + "dependencies": { + "minimist": "^1.2.0" + }, + "bin": { + "json5": "lib/cli.js" + } + }, + "node_modules/tslib": { + "version": "2.6.1", + "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.6.1.tgz", + "integrity": "sha512-t0hLfiEKfMUoqhG+U1oid7Pva4bbDPHYfJNiB7BiIjRkj1pyC++4N3huJfqY6aRH6VTB0rvtzQwjM4K6qpfOig==", + "license": "0BSD" + }, + "node_modules/tsx": { + "version": "4.19.4", + "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.19.4.tgz", + "integrity": "sha512-gK5GVzDkJK1SI1zwHf32Mqxf2tSJkNx+eYcNly5+nHvWqXUJYUkWBQtKauoESz3ymezAI++ZwT855x5p5eop+Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "esbuild": "~0.25.0", + "get-tsconfig": "^4.7.5" + }, + "bin": { + "tsx": "dist/cli.mjs" + }, + "engines": { + "node": ">=18.0.0" + }, + "optionalDependencies": { + "fsevents": "~2.3.3" + } + }, + "node_modules/type-check": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.4.0.tgz", + "integrity": "sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==", + "dev": true, + "license": "MIT", + "dependencies": { + "prelude-ls": "^1.2.1" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/type-detect": { + "version": "4.0.8", + "resolved": "https://registry.npmjs.org/type-detect/-/type-detect-4.0.8.tgz", + "integrity": "sha512-0fr/mIH1dlO+x7TlcMy+bIDqKPsw/70tVyeHW787goQjhmqaZe10uwLujubK9q9Lg6Fiho1KUKDYz0Z7k7g5/g==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/type-fest": { + "version": "0.20.2", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.20.2.tgz", + "integrity": "sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==", + "dev": true, + "license": "(MIT OR CC0-1.0)", + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/typed-array-buffer": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/typed-array-buffer/-/typed-array-buffer-1.0.0.tgz", + "integrity": "sha512-Y8KTSIglk9OZEr8zywiIHG/kmQ7KWyjseXs1CbSo8vC42w7hg2HgYTxSWwP0+is7bWDc1H+Fo026CpHFwm8tkw==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "get-intrinsic": "^1.2.1", + "is-typed-array": "^1.1.10" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/typed-array-byte-length": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/typed-array-byte-length/-/typed-array-byte-length-1.0.0.tgz", + "integrity": "sha512-Or/+kvLxNpeQ9DtSydonMxCx+9ZXOswtwJn17SNLvhptaXYDJvkFFP5zbfU/uLmvnBJlI4yrnXRxpdWH/M5tNA==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "for-each": "^0.3.3", + "has-proto": "^1.0.1", + "is-typed-array": "^1.1.10" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/typed-array-byte-offset": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/typed-array-byte-offset/-/typed-array-byte-offset-1.0.0.tgz", + "integrity": "sha512-RD97prjEt9EL8YgAgpOkf3O4IF9lhJFr9g0htQkm0rchFp/Vx7LW5Q8fSXXub7BXAODyUQohRMyOc3faCPd0hg==", + "dev": true, + "license": "MIT", + "dependencies": { + "available-typed-arrays": "^1.0.5", + "call-bind": "^1.0.2", + "for-each": "^0.3.3", + "has-proto": "^1.0.1", + "is-typed-array": "^1.1.10" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/typed-array-length": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/typed-array-length/-/typed-array-length-1.0.4.tgz", + "integrity": "sha512-KjZypGq+I/H7HI5HlOoGHkWUUGq+Q0TPhQurLbyrVrvnKTBgzLhIJ7j6J/XTQOi0d1RjyZ0wdas8bKs2p0x3Ng==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "for-each": "^0.3.3", + "is-typed-array": "^1.1.9" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/typescript": { + "version": "5.1.6", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.1.6.tgz", + "integrity": "sha512-zaWCozRZ6DLEWAWFrVDz1H6FVXzUSfTy5FUMWsQlU8Ym5JP9eO4xkTIROFCQvhQf61z6O/G6ugw3SgAnvvm+HA==", + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/uglify-es": { + "version": "3.3.9", + "resolved": "https://registry.npmjs.org/uglify-es/-/uglify-es-3.3.9.tgz", + "integrity": "sha512-r+MU0rfv4L/0eeW3xZrd16t4NZfK8Ld4SWVglYBb7ez5uXFWHuVRs6xCTrf1yirs9a4j4Y27nn7SRfO6v67XsQ==", + "deprecated": "support for ECMAScript is superseded by `uglify-js` as of v3.13.0", + "license": "BSD-2-Clause", + "peer": true, + "dependencies": { + "commander": "~2.13.0", + "source-map": "~0.6.1" + }, + "bin": { + "uglifyjs": "bin/uglifyjs" + }, + "engines": { + "node": ">=0.8.0" + } + }, + "node_modules/uglify-es/node_modules/commander": { + "version": "2.13.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-2.13.0.tgz", + "integrity": "sha512-MVuS359B+YzaWqjCL/c+22gfryv+mCBPHAv3zyVI2GN8EY6IRP8VwtasXn8jyyhvvq84R4ImN1OKRtcbIasjYA==", + "license": "MIT", + "peer": true + }, + "node_modules/uglify-es/node_modules/source-map": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", + "license": "BSD-3-Clause", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/unbox-primitive": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/unbox-primitive/-/unbox-primitive-1.0.2.tgz", + "integrity": "sha512-61pPlCD9h51VoreyJ0BReideM3MDKMKnh6+V9L08331ipq6Q8OFXZYiqP6n/tbHx4s5I9uRhcye6BrbkizkBDw==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind": "^1.0.2", + "has-bigints": "^1.0.2", + "has-symbols": "^1.0.3", + "which-boxed-primitive": "^1.0.2" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/unicode-canonical-property-names-ecmascript": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/unicode-canonical-property-names-ecmascript/-/unicode-canonical-property-names-ecmascript-2.0.0.tgz", + "integrity": "sha512-yY5PpDlfVIU5+y/BSCxAJRBIS1Zc2dDG3Ujq+sR0U+JjUevW2JhocOF+soROYDSaAezOzOKuyyixhD6mBknSmQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/unicode-match-property-ecmascript": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/unicode-match-property-ecmascript/-/unicode-match-property-ecmascript-2.0.0.tgz", + "integrity": "sha512-5kaZCrbp5mmbz5ulBkDkbY0SsPOjKqVS35VpL9ulMPfSl0J0Xsm+9Evphv9CoIZFwre7aJoa94AY6seMKGVN5Q==", + "license": "MIT", + "peer": true, + "dependencies": { + "unicode-canonical-property-names-ecmascript": "^2.0.0", + "unicode-property-aliases-ecmascript": "^2.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/unicode-match-property-value-ecmascript": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/unicode-match-property-value-ecmascript/-/unicode-match-property-value-ecmascript-2.1.0.tgz", + "integrity": "sha512-qxkjQt6qjg/mYscYMC0XKRn3Rh0wFPlfxB0xkt9CfyTvpX1Ra0+rAmdX2QyAobptSEvuy4RtpPRui6XkV+8wjA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/unicode-property-aliases-ecmascript": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/unicode-property-aliases-ecmascript/-/unicode-property-aliases-ecmascript-2.1.0.tgz", + "integrity": "sha512-6t3foTQI9qne+OZoVQB/8x8rk2k1eVy1gRXhV3oFQ5T6R1dqQ1xtin3XqSlx3+ATBkliTaR/hHyJBm+LVPNM8w==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/unified": { + "version": "11.0.5", + "resolved": "https://registry.npmjs.org/unified/-/unified-11.0.5.tgz", + "integrity": "sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "bail": "^2.0.0", + "devlop": "^1.0.0", + "extend": "^3.0.0", + "is-plain-obj": "^4.0.0", + "trough": "^2.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unified/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/unist-util-generated": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/unist-util-generated/-/unist-util-generated-2.0.1.tgz", + "integrity": "sha512-qF72kLmPxAw0oN2fwpWIqbXAVyEqUzDHMsbtPvOudIlUzXYFIeQIuxXQCRCFh22B7cixvU0MG7m3MW8FTq/S+A==", + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-is": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-6.0.0.tgz", + "integrity": "sha512-2qCTHimwdxLfz+YzdGfkqNlH0tLi9xjTnHddPmJwtIG9MGsdbutfTc4P+haPD7l7Cjxf/WZj+we5qfVPvvxfYw==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-is/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/unist-util-position": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/unist-util-position/-/unist-util-position-5.0.0.tgz", + "integrity": "sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-position-from-estree": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/unist-util-position-from-estree/-/unist-util-position-from-estree-2.0.0.tgz", + "integrity": "sha512-KaFVRjoqLyF6YXCbVLNad/eS4+OfPQQn2yOd7zF/h5T/CSL2v8NpN6a5TPvtbXthAGw5nG+PuTtq+DdIZr+cRQ==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-position-from-estree/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/unist-util-position/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/unist-util-stringify-position": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-4.0.0.tgz", + "integrity": "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-stringify-position/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/unist-util-visit": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-5.0.0.tgz", + "integrity": "sha512-MR04uvD+07cwl/yhVuVWAtw+3GOR/knlL55Nd/wAdblk27GCVt3lqpTivy/tkJcZoNPzTwS1Y+KMojlLDhoTzg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0", + "unist-util-visit-parents": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit-parents": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-6.0.1.tgz", + "integrity": "sha512-L/PqWzfTP9lzzEa6CKs0k2nARxTdZduw3zyh8d2NVBnsyvHjSX4TWse388YrrQKbvI8w20fGjGlhgT96WwKykw==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit-parents/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/unist-util-visit/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/universalify": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz", + "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 4.0.0" + } + }, + "node_modules/unpipe": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz", + "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/update-browserslist-db": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.0.11.tgz", + "integrity": "sha512-dCwEFf0/oT85M1fHBg4F0jtLwJrutGoHSQXCh7u4o2t1drG+c0a9Flnqww6XUKSfQMPpJBRjU8d4RXB09qtvaA==", + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/browserslist" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "escalade": "^3.1.1", + "picocolors": "^1.0.0" + }, + "bin": { + "update-browserslist-db": "cli.js" + }, + "peerDependencies": { + "browserslist": ">= 4.21.0" + } + }, + "node_modules/uri-js": { + "version": "4.4.1", + "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", + "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "punycode": "^2.1.0" + } + }, + "node_modules/url-parse": { + "version": "1.5.10", + "resolved": "https://registry.npmjs.org/url-parse/-/url-parse-1.5.10.tgz", + "integrity": "sha512-WypcfiRhfeUP9vvF0j6rw0J3hrWrw6iZv3+22h6iRMJ/8z1Tj6XfLP4DsUix5MhMPnXpiHDoKyoZ/bdCkwBCiQ==", + "license": "MIT", + "dependencies": { + "querystringify": "^2.1.1", + "requires-port": "^1.0.0" + } + }, + "node_modules/use-callback-ref": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/use-callback-ref/-/use-callback-ref-1.3.3.tgz", + "integrity": "sha512-jQL3lRnocaFtu3V00JToYz/4QkNWswxijDaCVNZRiRTO3HQDLsdu1ZtmIUvV4yPp+rvWm5j0y0TG/S61cuijTg==", + "license": "MIT", + "dependencies": { + "tslib": "^2.0.0" + }, + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/use-sidecar": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/use-sidecar/-/use-sidecar-1.1.3.tgz", + "integrity": "sha512-Fedw0aZvkhynoPYlA5WXrMCAMm+nSWdZt6lzJQ7Ok8S6Q+VsHmHpRWndVRJ8Be0ZbkfPc5LRYH+5XrzXcEeLRQ==", + "license": "MIT", + "dependencies": { + "detect-node-es": "^1.1.0", + "tslib": "^2.0.0" + }, + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/use-sync-external-store": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/use-sync-external-store/-/use-sync-external-store-1.2.0.tgz", + "integrity": "sha512-eEgnFxGQ1Ife9bzYs6VLi8/4X6CObHMw9Qr9tPY43iKwsPw8xE8+EFsf/2cFZ5S3esXgpWgtSCtLNS41F+sKPA==", + "license": "MIT", + "peerDependencies": { + "react": "^16.8.0 || ^17.0.0 || ^18.0.0" + } + }, + "node_modules/util-deprecate": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz", + "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==", + "license": "MIT" + }, + "node_modules/utils-merge": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/utils-merge/-/utils-merge-1.0.1.tgz", + "integrity": "sha512-pMZTvIkT1d+TFGvDOqodOclx0QWkkgi6Tdoa8gC8ffGAAqz9pzPTZWAybbsHHoED/ztMtkv/VoYTYyShUn81hA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.4.0" + } + }, + "node_modules/uuid": { + "version": "8.3.2", + "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz", + "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==", + "license": "MIT", + "bin": { + "uuid": "dist/bin/uuid" + } + }, + "node_modules/uvu": { + "version": "0.5.6", + "resolved": "https://registry.npmjs.org/uvu/-/uvu-0.5.6.tgz", + "integrity": "sha512-+g8ENReyr8YsOc6fv/NVJs2vFdHBnBNdfE49rshrTzDWOlUx4Gq7KOS2GD8eqhy2j+Ejq29+SbKH8yjkAqXqoA==", + "license": "MIT", + "dependencies": { + "dequal": "^2.0.0", + "diff": "^5.0.0", + "kleur": "^4.0.3", + "sade": "^1.7.3" + }, + "bin": { + "uvu": "bin.js" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/uvu/node_modules/diff": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/diff/-/diff-5.1.0.tgz", + "integrity": "sha512-D+mk+qE8VC/PAUrlAU34N+VfXev0ghe5ywmpqrawphmVZc1bEfn56uo9qpyGp1p4xpzOHkSW4ztBd6L7Xx4ACw==", + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.3.1" + } + }, + "node_modules/uvu/node_modules/kleur": { + "version": "4.1.5", + "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz", + "integrity": "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/v8-compile-cache-lib": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/v8-compile-cache-lib/-/v8-compile-cache-lib-3.0.1.tgz", + "integrity": "sha512-wa7YjyUGfNZngI/vtK0UHAN+lgDCxBPCylVXGp0zu59Fz5aiGtNXaq3DhIov063MorB+VfufLh3JlF2KdTK3xg==", + "license": "MIT" + }, + "node_modules/vary": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz", + "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/vfile": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/vfile/-/vfile-6.0.3.tgz", + "integrity": "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/vfile-message": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-4.0.2.tgz", + "integrity": "sha512-jRDZ1IMLttGj41KcZvlrYAaI3CfqpLpfpf+Mfig13viT6NKvRzWZ+lXz0Y5D60w6uJIBAOGq9mSHf0gktF0duw==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-stringify-position": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/vfile-message/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/vfile/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/victory-vendor": { + "version": "36.9.2", + "resolved": "https://registry.npmjs.org/victory-vendor/-/victory-vendor-36.9.2.tgz", + "integrity": "sha512-PnpQQMuxlwYdocC8fIJqVXvkeViHYzotI+NJrCuav0ZYFoq912ZHBk3mCeuj+5/VpodOjPe1z0Fk2ihgzlXqjQ==", + "license": "MIT AND ISC", + "dependencies": { + "@types/d3-array": "^3.0.3", + "@types/d3-ease": "^3.0.0", + "@types/d3-interpolate": "^3.0.1", + "@types/d3-scale": "^4.0.2", + "@types/d3-shape": "^3.1.0", + "@types/d3-time": "^3.0.0", + "@types/d3-timer": "^3.0.0", + "d3-array": "^3.1.6", + "d3-ease": "^3.0.1", + "d3-interpolate": "^3.0.1", + "d3-scale": "^4.0.2", + "d3-shape": "^3.1.0", + "d3-time": "^3.0.0", + "d3-timer": "^3.0.1" + } + }, + "node_modules/victory-vendor/node_modules/@types/d3-scale": { + "version": "4.0.9", + "resolved": "https://registry.npmjs.org/@types/d3-scale/-/d3-scale-4.0.9.tgz", + "integrity": "sha512-dLmtwB8zkAeO/juAMfnV+sItKjlsw2lKdZVVy6LRr0cBmegxSABiLEpGVmSJJ8O08i4+sGR6qQtb6WtuwJdvVw==", + "license": "MIT", + "dependencies": { + "@types/d3-time": "*" + } + }, + "node_modules/victory-vendor/node_modules/@types/d3-shape": { + "version": "3.1.7", + "resolved": "https://registry.npmjs.org/@types/d3-shape/-/d3-shape-3.1.7.tgz", + "integrity": "sha512-VLvUQ33C+3J+8p+Daf+nYSOsjB4GXp19/S/aGo60m9h1v6XaxjiT82lKVWJCfzhtuZ3yD7i/TPeC/fuKLLOSmg==", + "license": "MIT", + "dependencies": { + "@types/d3-path": "*" + } + }, + "node_modules/victory-vendor/node_modules/@types/d3-time": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/@types/d3-time/-/d3-time-3.0.4.tgz", + "integrity": "sha512-yuzZug1nkAAaBlBBikKZTgzCeA+k1uy4ZFwWANOfKw5z5LRhV0gNA7gNkKm7HoK+HRN0wX3EkxGk0fpbWhmB7g==", + "license": "MIT" + }, + "node_modules/victory-vendor/node_modules/d3-array": { + "version": "3.2.4", + "resolved": "https://registry.npmjs.org/d3-array/-/d3-array-3.2.4.tgz", + "integrity": "sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg==", + "license": "ISC", + "dependencies": { + "internmap": "1 - 2" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/victory-vendor/node_modules/d3-interpolate": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-interpolate/-/d3-interpolate-3.0.1.tgz", + "integrity": "sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==", + "license": "ISC", + "dependencies": { + "d3-color": "1 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/victory-vendor/node_modules/d3-path": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-path/-/d3-path-3.1.0.tgz", + "integrity": "sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ==", + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/victory-vendor/node_modules/d3-scale": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/d3-scale/-/d3-scale-4.0.2.tgz", + "integrity": "sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ==", + "license": "ISC", + "dependencies": { + "d3-array": "2.10.0 - 3", + "d3-format": "1 - 3", + "d3-interpolate": "1.2.0 - 3", + "d3-time": "2.1.1 - 3", + "d3-time-format": "2 - 4" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/victory-vendor/node_modules/d3-shape": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-3.2.0.tgz", + "integrity": "sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA==", + "license": "ISC", + "dependencies": { + "d3-path": "^3.1.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/victory-vendor/node_modules/d3-time": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-time/-/d3-time-3.1.0.tgz", + "integrity": "sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q==", + "license": "ISC", + "dependencies": { + "d3-array": "2 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/vlq": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/vlq/-/vlq-1.0.1.tgz", + "integrity": "sha512-gQpnTgkubC6hQgdIcRdYGDSDc+SaujOdyesZQMv6JlfQee/9Mp0Qhnys6WxDWvQnL5WZdT7o2Ul187aSt0Rq+w==", + "license": "MIT", + "peer": true + }, + "node_modules/walker": { + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/walker/-/walker-1.0.8.tgz", + "integrity": "sha512-ts/8E8l5b7kY0vlWLewOkDXMmPdLcVV4GmOQLyxuSswIJsweeFZtAsMF7k1Nszz+TYBQrlYRmzOnr398y1JemQ==", + "license": "Apache-2.0", + "peer": true, + "dependencies": { + "makeerror": "1.0.12" + } + }, + "node_modules/watchpack": { + "version": "2.4.0", + "resolved": "https://registry.npmjs.org/watchpack/-/watchpack-2.4.0.tgz", + "integrity": "sha512-Lcvm7MGST/4fup+ifyKi2hjyIAwcdI4HRgtvTpIUxBRhB+RFtUh8XtDOxUfctVCnhVi+QQj49i91OyvzkJl6cg==", + "license": "MIT", + "dependencies": { + "glob-to-regexp": "^0.4.1", + "graceful-fs": "^4.1.2" + }, + "engines": { + "node": ">=10.13.0" + } + }, + "node_modules/wcwidth": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/wcwidth/-/wcwidth-1.0.1.tgz", + "integrity": "sha512-XHPEwS0q6TaxcvG85+8EYkbiCux2XtWG2mkc47Ng2A77BQu9+DqIOJldST4HgPkuea7dvKSj5VgX3P1d4rW8Tg==", + "license": "MIT", + "peer": true, + "dependencies": { + "defaults": "^1.0.3" + } + }, + "node_modules/webidl-conversions": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", + "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==", + "license": "BSD-2-Clause" + }, + "node_modules/whatwg-fetch": { + "version": "3.6.19", + "resolved": "https://registry.npmjs.org/whatwg-fetch/-/whatwg-fetch-3.6.19.tgz", + "integrity": "sha512-d67JP4dHSbm2TrpFj8AbO8DnL1JXL5J9u0Kq2xW6d0TFDbCA3Muhdt8orXC22utleTVj7Prqt82baN6RBvnEgw==", + "license": "MIT", + "peer": true + }, + "node_modules/whatwg-url": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz", + "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==", + "license": "MIT", + "dependencies": { + "tr46": "~0.0.3", + "webidl-conversions": "^3.0.0" + } + }, + "node_modules/which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "license": "ISC", + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "node-which": "bin/node-which" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/which-boxed-primitive": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/which-boxed-primitive/-/which-boxed-primitive-1.0.2.tgz", + "integrity": "sha512-bwZdv0AKLpplFY2KZRX6TvyuN7ojjr7lwkg6ml0roIy9YeuSr7JS372qlNW18UQYzgYK9ziGcerWqZOmEn9VNg==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-bigint": "^1.0.1", + "is-boolean-object": "^1.1.0", + "is-number-object": "^1.0.4", + "is-string": "^1.0.5", + "is-symbol": "^1.0.3" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/which-builtin-type": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/which-builtin-type/-/which-builtin-type-1.1.3.tgz", + "integrity": "sha512-YmjsSMDBYsM1CaFiayOVT06+KJeXf0o5M/CAd4o1lTadFAtacTUM49zoYxr/oroopFDfhvN6iEcBxUyc3gvKmw==", + "dev": true, + "license": "MIT", + "dependencies": { + "function.prototype.name": "^1.1.5", + "has-tostringtag": "^1.0.0", + "is-async-function": "^2.0.0", + "is-date-object": "^1.0.5", + "is-finalizationregistry": "^1.0.2", + "is-generator-function": "^1.0.10", + "is-regex": "^1.1.4", + "is-weakref": "^1.0.2", + "isarray": "^2.0.5", + "which-boxed-primitive": "^1.0.2", + "which-collection": "^1.0.1", + "which-typed-array": "^1.1.9" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/which-collection": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/which-collection/-/which-collection-1.0.1.tgz", + "integrity": "sha512-W8xeTUwaln8i3K/cY1nGXzdnVZlidBcagyNFtBdD5kxnb4TvGKR7FfSIS3mYpwWS1QUCutfKz8IY8RjftB0+1A==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-map": "^2.0.1", + "is-set": "^2.0.1", + "is-weakmap": "^2.0.1", + "is-weakset": "^2.0.1" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/which-module": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/which-module/-/which-module-2.0.1.tgz", + "integrity": "sha512-iBdZ57RDvnOR9AGBhML2vFZf7h8vmBjhoaZqODJBFWHVtKkDmKuHai3cx5PgVMrX5YDNp27AofYbAwctSS+vhQ==", + "license": "ISC", + "peer": true + }, + "node_modules/which-typed-array": { + "version": "1.1.11", + "resolved": "https://registry.npmjs.org/which-typed-array/-/which-typed-array-1.1.11.tgz", + "integrity": "sha512-qe9UWWpkeG5yzZ0tNYxDmd7vo58HDBc39mZ0xWWpolAGADdFOzkfamWLDxkOWcvHQKVmdTyQdLD4NOfjLWTKew==", + "dev": true, + "license": "MIT", + "dependencies": { + "available-typed-arrays": "^1.0.5", + "call-bind": "^1.0.2", + "for-each": "^0.3.3", + "gopd": "^1.0.1", + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/wide-align": { + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/wide-align/-/wide-align-1.1.5.tgz", + "integrity": "sha512-eDMORYaPNZ4sQIuuYPDHdQvf4gyCF9rEEV/yPxGfwPkRodwEgiMUUXTx/dex+Me0wxx53S+NgUHaP7y3MGlDmg==", + "license": "ISC", + "dependencies": { + "string-width": "^1.0.2 || 2 || 3 || 4" + } + }, + "node_modules/wrap-ansi": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", + "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", + "license": "MIT", + "peer": true, + "dependencies": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/wrappy": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", + "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==", + "license": "ISC" + }, + "node_modules/write-file-atomic": { + "version": "2.4.3", + "resolved": "https://registry.npmjs.org/write-file-atomic/-/write-file-atomic-2.4.3.tgz", + "integrity": "sha512-GaETH5wwsX+GcnzhPgKcKjJ6M2Cq3/iZp1WyY/X1CSqrW+jVNM9Y7D8EC2sM4ZG/V8wZlSniJnCKWPmBYAucRQ==", + "license": "ISC", + "peer": true, + "dependencies": { + "graceful-fs": "^4.1.11", + "imurmurhash": "^0.1.4", + "signal-exit": "^3.0.2" + } + }, + "node_modules/ws": { + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/ws/-/ws-6.2.2.tgz", + "integrity": "sha512-zmhltoSR8u1cnDsD43TX59mzoMZsLKqUweyYBAIvTngR3shc0W6aOZylZmq/7hqyVxPdi+5Ud2QInblgyE72fw==", + "license": "MIT", + "peer": true, + "dependencies": { + "async-limiter": "~1.0.0" + } + }, + "node_modules/xtend": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz", + "integrity": "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.4" + } + }, + "node_modules/y18n": { + "version": "5.0.8", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", + "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==", + "license": "ISC", + "peer": true, + "engines": { + "node": ">=10" + } + }, + "node_modules/yallist": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz", + "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==", + "license": "ISC" + }, + "node_modules/yaml": { + "version": "2.8.0", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.0.tgz", + "integrity": "sha512-4lLa/EcQCB0cJkyts+FpIRx5G/llPxfP6VQU5KByHEhLxY3IJCH0f0Hy1MHI8sClTvsIb8qwRJ6R/ZdlDJ/leQ==", + "license": "ISC", + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14.6" + } + }, + "node_modules/yargs": { + "version": "17.7.2", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz", + "integrity": "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==", + "license": "MIT", + "peer": true, + "dependencies": { + "cliui": "^8.0.1", + "escalade": "^3.1.1", + "get-caller-file": "^2.0.5", + "require-directory": "^2.1.1", + "string-width": "^4.2.3", + "y18n": "^5.0.5", + "yargs-parser": "^21.1.1" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/yargs-parser": { + "version": "21.1.1", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz", + "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==", + "license": "ISC", + "peer": true, + "engines": { + "node": ">=12" + } + }, + "node_modules/yn": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/yn/-/yn-3.1.1.tgz", + "integrity": "sha512-Ux4ygGWsu2c7isFWe8Yu1YluJmqVhxqK2cLXNQA5AcC3QfbGNpM7fu0Y8b/z16pXLnFxZYvWhd3fhBY9DLmC6Q==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/yocto-queue": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz", + "integrity": "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==", + "license": "MIT", + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/zdog": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/zdog/-/zdog-1.1.3.tgz", + "integrity": "sha512-raRj6r0gPzopFm5XWBJZr/NuV4EEnT4iE+U3dp5FV5pCb588Gmm3zLIp/j9yqqcMiHH8VNQlerLTgOqL7krh6w==", + "license": "MIT", + "peer": true + }, + "node_modules/zod": { + "version": "3.22.2", + "resolved": "https://registry.npmjs.org/zod/-/zod-3.22.2.tgz", + "integrity": "sha512-wvWkphh5WQsJbVk1tbx1l1Ly4yg+XecD+Mq280uBGt9wa5BKSWf4Mhp6GmrkPixhMxmabYY7RbzlwVP32pbGCg==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, + "node_modules/zustand": { + "version": "3.7.2", + "resolved": "https://registry.npmjs.org/zustand/-/zustand-3.7.2.tgz", + "integrity": "sha512-PIJDIZKtokhof+9+60cpockVOq05sJzHCriyvaLBmEJixseQ1a5Kdov6fWZfWOu5SK9c+FhH1jU0tntLxRJYMA==", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=12.7.0" + }, + "peerDependencies": { + "react": ">=16.8" + }, + "peerDependenciesMeta": { + "react": { + "optional": true + } + } + }, + "node_modules/zwitch": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz", + "integrity": "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + } + } +} diff --git a/sirius-ui/package.json b/sirius-ui/package.json new file mode 100755 index 0000000..771bb37 --- /dev/null +++ b/sirius-ui/package.json @@ -0,0 +1,108 @@ +{ + "name": "sirius-ui", + "version": "1.0.0", + "private": true, + "scripts": { + "build": "npx next build", + "dev": "npx next dev", + "postinstall": "npx prisma generate", + "lint": "npx lint", + "start": "npx next start" + }, + "dependencies": { + "@hookform/resolvers": "^3.3.1", + "@mdx-js/loader": "^3.1.0", + "@mdx-js/react": "^3.1.0", + "@monaco-editor/react": "^4.7.0", + "@next-auth/prisma-adapter": "^1.0.7", + "@next/mdx": "13.4.2", + "@nivo/bar": "^0.83.0", + "@nivo/core": "^0.83.0", + "@nivo/line": "^0.83.0", + "@nivo/pie": "^0.83.0", + "@prisma/client": "^5.1.1", + "@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", + "@tanstack/react-virtual": "^3.13.18", + "@trpc/client": "^10.34.0", + "@trpc/next": "^10.34.0", + "@trpc/react-query": "^10.34.0", + "@trpc/server": "^10.34.0", + "@types/amqplib": "^0.10.6", + "@types/bcrypt": "^5.0.2", + "@types/mdx": "^2.0.13", + "@types/minimist": "^1.2.5", + "@xterm/addon-fit": "^0.10.0", + "@xterm/addon-search": "^0.16.0", + "@xterm/addon-web-links": "^0.11.0", + "@xterm/xterm": "^5.5.0", + "amqplib": "^0.10.5", + "axios": "^1.5.0", + "bcrypt": "^5.1.1", + "class-variance-authority": "^0.7.0", + "clsx": "^2.0.0", + "fuse.js": "^7.1.0", + "install": "^0.13.0", + "iovalkey": "^0.3.0", + "js-yaml": "^4.1.0", + "lucide-react": "^0.268.0", + "minimist": "^1.2.8", + "next": "^13.4.2", + "next-auth": "^4.22.4", + "next-themes": "^0.4.4", + "prisma": "^5.1.1", + "radix-ui": "^1.0.1", + "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", + "recharts": "^2.15.1", + "sonner": "^2.0.1", + "superjson": "^1.13.1", + "tailwind-merge": "^1.14.0", + "tailwindcss-animate": "^1.0.6", + "ts-node": "^10.9.2", + "yaml": "^2.8.0", + "zod": "^3.22.2" + }, + "devDependencies": { + "@types/eslint": "^8.37.0", + "@types/node": "^18.16.0", + "@types/prettier": "^2.7.2", + "@types/react": "^18.2.6", + "@types/react-dom": "^18.2.4", + "@typescript-eslint/eslint-plugin": "6.0.0", + "@typescript-eslint/parser": "6.0.0", + "autoprefixer": "^10.4.14", + "eslint": "^8.40.0", + "eslint-config-next": "^13.4.2", + "postcss": "^8.4.27", + "prettier": "^2.8.8", + "prettier-plugin-tailwindcss": "^0.2.8", + "tailwindcss": "^3.3.3", + "tsx": "^4.19.4", + "typescript": "^5.0.4" + }, + "ct3aMetadata": { + "initVersion": "7.18.0" + }, + "prisma": { + "seed": "npx tsx prisma/seed.ts" + } +} diff --git a/sirius-ui/postcss.config.cjs b/sirius-ui/postcss.config.cjs new file mode 100755 index 0000000..e305dd9 --- /dev/null +++ b/sirius-ui/postcss.config.cjs @@ -0,0 +1,8 @@ +const config = { + plugins: { + tailwindcss: {}, + autoprefixer: {}, + }, +}; + +module.exports = config; diff --git a/sirius-ui/prettier.config.cjs b/sirius-ui/prettier.config.cjs new file mode 100755 index 0000000..ca28ed9 --- /dev/null +++ b/sirius-ui/prettier.config.cjs @@ -0,0 +1,6 @@ +/** @type {import("prettier").Config} */ +const config = { + plugins: [require.resolve("prettier-plugin-tailwindcss")], +}; + +module.exports = config; diff --git a/sirius-ui/prisma/migrations/20250608024601_init/migration.sql b/sirius-ui/prisma/migrations/20250608024601_init/migration.sql new file mode 100644 index 0000000..f8d65d2 --- /dev/null +++ b/sirius-ui/prisma/migrations/20250608024601_init/migration.sql @@ -0,0 +1,62 @@ +-- CreateTable +CREATE TABLE "users" ( + "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, + "name" TEXT NOT NULL, + "email" TEXT NOT NULL, + "password" TEXT NOT NULL +); + +-- CreateTable +CREATE TABLE "hosts" ( + "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, + "ip" TEXT NOT NULL, + "hostname" TEXT, + "os" TEXT, + "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + "updatedAt" DATETIME NOT NULL +); + +-- CreateTable +CREATE TABLE "ports" ( + "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, + "number" INTEGER NOT NULL, + "protocol" TEXT NOT NULL, + "state" TEXT NOT NULL, + "service" TEXT, + "version" TEXT, + "hostId" INTEGER NOT NULL, + CONSTRAINT "ports_hostId_fkey" FOREIGN KEY ("hostId") REFERENCES "hosts" ("id") ON DELETE CASCADE ON UPDATE CASCADE +); + +-- CreateTable +CREATE TABLE "vulnerabilities" ( + "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, + "vid" TEXT NOT NULL, + "title" TEXT NOT NULL, + "description" TEXT NOT NULL, + "severity" TEXT NOT NULL, + "riskScore" REAL, + "hostId" INTEGER NOT NULL, + "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + "updatedAt" DATETIME NOT NULL, + CONSTRAINT "vulnerabilities_hostId_fkey" FOREIGN KEY ("hostId") REFERENCES "hosts" ("id") ON DELETE CASCADE ON UPDATE CASCADE +); + +-- CreateTable +CREATE TABLE "scans" ( + "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, + "target" TEXT NOT NULL, + "status" TEXT NOT NULL, + "results" TEXT, + "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + "updatedAt" DATETIME NOT NULL +); + +-- CreateIndex +CREATE UNIQUE INDEX "users_name_key" ON "users"("name"); + +-- CreateIndex +CREATE UNIQUE INDEX "users_email_key" ON "users"("email"); + +-- CreateIndex +CREATE UNIQUE INDEX "hosts_ip_key" ON "hosts"("ip"); diff --git a/sirius-ui/prisma/migrations/migration_lock.toml b/sirius-ui/prisma/migrations/migration_lock.toml new file mode 100644 index 0000000..e5e5c47 --- /dev/null +++ b/sirius-ui/prisma/migrations/migration_lock.toml @@ -0,0 +1,3 @@ +# Please do not edit this file manually +# It should be added in your version-control system (i.e. Git) +provider = "sqlite" \ No newline at end of file diff --git a/sirius-ui/prisma/schema.prisma b/sirius-ui/prisma/schema.prisma new file mode 100644 index 0000000..f11d0f8 --- /dev/null +++ b/sirius-ui/prisma/schema.prisma @@ -0,0 +1,74 @@ +// This is your Prisma schema file, +// learn more about it in the docs: https://pris.ly/d/prisma-schema + +generator client { + provider = "prisma-client-js" + //binaryTargets = ["native", "linux-musl-arm64-openssl-3.0.x"] // Local Dev + binaryTargets = ["native", "linux-arm64-openssl-1.1.x", "debian-openssl-1.1.x"] +} + +datasource db { + provider = "sqlite" + url = "file:./dev.db" +} + +model User { + id Int @id @default(autoincrement()) + name String @unique + email String @unique + password String + + @@map("users") +} + +model Host { + id Int @id @default(autoincrement()) + ip String @unique + hostname String? + os String? + ports Port[] + vulnerabilities Vulnerability[] + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@map("hosts") +} + +model Port { + id Int @id @default(autoincrement()) + number Int + protocol String + state String + service String? + version String? + hostId Int + host Host @relation(fields: [hostId], references: [id], onDelete: Cascade) + + @@map("ports") +} + +model Vulnerability { + id Int @id @default(autoincrement()) + vid String // Vulnerability ID (e.g., CVE-2021-1234) + title String + description String + severity String + riskScore Float? + hostId Int + host Host @relation(fields: [hostId], references: [id], onDelete: Cascade) + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@map("vulnerabilities") +} + +model Scan { + id Int @id @default(autoincrement()) + target String + status String // pending, running, completed, failed + results String? // JSON string of scan results + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@map("scans") +} \ No newline at end of file diff --git a/sirius-ui/prisma/seed.ts b/sirius-ui/prisma/seed.ts new file mode 100644 index 0000000..8527804 --- /dev/null +++ b/sirius-ui/prisma/seed.ts @@ -0,0 +1,51 @@ +import { PrismaClient } from '@prisma/client'; +import { hash } from 'bcrypt'; +const prisma = new PrismaClient(); + +async function main() { + const rawPassword = process.env.INITIAL_ADMIN_PASSWORD; + if (!rawPassword) { + throw new Error('INITIAL_ADMIN_PASSWORD is required for database seed'); + } + + // Hash the password with bcrypt + const hashedPassword = await hash(rawPassword, 10); + + try { + // First, try to get the existing user + const existingUser = await prisma.user.findUnique({ + where: { name: 'admin' } + }); + + if (existingUser) { + // If the user exists, update the password + const updatedUser = await prisma.user.update({ + where: { id: existingUser.id }, + data: { password: hashedPassword } + }); + console.log('Admin user updated with new password:', updatedUser.name); + } else { + // If no user exists, create a new one + const newUser = await prisma.user.create({ + data: { + name: 'admin', + email: 'admin@example.com', + password: hashedPassword, + } + }); + console.log('New admin user created:', newUser.name); + } + } catch (error) { + console.error('Error updating/creating admin user:', error); + throw error; + } +} + +main() + .catch((e) => { + console.error(e); + process.exit(1); + }) + .finally(async () => { + await prisma.$disconnect(); + }); \ No newline at end of file diff --git a/sirius-ui/public/favicon.ico b/sirius-ui/public/favicon.ico new file mode 100644 index 0000000..f8cffd5 Binary files /dev/null and b/sirius-ui/public/favicon.ico differ diff --git a/sirius-ui/public/loginbg.jpg b/sirius-ui/public/loginbg.jpg new file mode 100644 index 0000000..d73917b Binary files /dev/null and b/sirius-ui/public/loginbg.jpg differ diff --git a/sirius-ui/public/sirius-logo-square.png b/sirius-ui/public/sirius-logo-square.png new file mode 100644 index 0000000..549f3ff Binary files /dev/null and b/sirius-ui/public/sirius-logo-square.png differ diff --git a/sirius-ui/public/sirius-logo.png b/sirius-ui/public/sirius-logo.png new file mode 100755 index 0000000..644044c Binary files /dev/null and b/sirius-ui/public/sirius-logo.png differ diff --git a/sirius-ui/public/sirius-scan.png b/sirius-ui/public/sirius-scan.png new file mode 100755 index 0000000..8d60cc7 Binary files /dev/null and b/sirius-ui/public/sirius-scan.png differ diff --git a/sirius-ui/public/sirius.svg b/sirius-ui/public/sirius.svg new file mode 100644 index 0000000..f69a631 --- /dev/null +++ b/sirius-ui/public/sirius.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + \ No newline at end of file diff --git a/sirius-ui/scripts/reset-password.ts b/sirius-ui/scripts/reset-password.ts new file mode 100644 index 0000000..01aff41 --- /dev/null +++ b/sirius-ui/scripts/reset-password.ts @@ -0,0 +1,107 @@ +#!/usr/bin/env bun +/** + * Reset Password Utility for Sirius Scan + * + * This script allows administrators to reset a user's password from the command line. + * + * Usage with Bun: + * bun scripts/reset-password.ts --username --password + * + * Usage with Node + ts-node: + * npx ts-node scripts/reset-password.ts --username --password + */ + +import { PrismaClient } from "@prisma/client"; +import { hash } from "bcrypt"; +import minimist from "minimist"; + +const prisma = new PrismaClient(); + +async function resetPassword( + username: string, + newPassword: string +): Promise { + try { + // Validate inputs + if (!username) { + throw new Error("Username is required"); + } + + if (!newPassword || newPassword.length < 8) { + throw new Error("Password must be at least 8 characters long"); + } + + // Find the user + const user = await prisma.user.findFirst({ + where: { + OR: [{ email: username }, { name: username }], + }, + }); + + if (!user) { + throw new Error(`User "${username}" not found`); + } + + // Hash the new password + const hashedPassword = await hash(newPassword, 10); + + // Update the user's password + await prisma.user.update({ + where: { id: user.id }, + data: { password: hashedPassword }, + }); + + console.log(`Password for user "${username}" has been reset successfully`); + } catch (error) { + console.error( + "Error resetting password:", + error instanceof Error ? error.message : error + ); + process.exit(1); + } finally { + // Disconnect from the database + await prisma.$disconnect(); + } +} + +async function main(): Promise { + const argv = minimist(process.argv.slice(2)); + + // Display help if requested or if no arguments provided + if (argv.help || argv.h || Object.keys(argv).length === 1) { + console.log(` +Reset Password Utility for Sirius Scan + +Usage with Bun: + bun scripts/reset-password.ts --username --password + +Usage with Node + ts-node: + npx ts-node scripts/reset-password.ts --username --password + +Options: + --username, -u Username or email of the account to reset + --password, -p New password to set + --help, -h Display this help message + `); + process.exit(0); + } + + const username = argv.username || argv.u; + const password = argv.password || argv.p; + + if (!username || !password) { + console.error("Error: Both username and password are required"); + console.log("Use --help for usage information"); + process.exit(1); + } + + await resetPassword(username, password); +} + +// Run the script +main() + .then(() => process.exit(0)) + .catch((error) => { + console.error("Unhandled error:", error); + process.exit(1); + }); diff --git a/sirius-ui/src/components/DashNumberCard.tsx b/sirius-ui/src/components/DashNumberCard.tsx new file mode 100755 index 0000000..cb590e4 --- /dev/null +++ b/sirius-ui/src/components/DashNumberCard.tsx @@ -0,0 +1,36 @@ +"use client"; +import React from "react"; + +interface DashNumberCardProps { + title: string; + number: number; + color: string; + icon: React.ReactNode; +} + +const DashNumberCard: React.FC = ({ + title, + number, + color, + icon, +}) => { + return ( +
+
+ + {number} + +
+
+ + {icon} {title} + +
+
+ ); +}; + +export default DashNumberCard; diff --git a/sirius-ui/src/components/DataBoxTable.tsx b/sirius-ui/src/components/DataBoxTable.tsx new file mode 100755 index 0000000..3af2007 --- /dev/null +++ b/sirius-ui/src/components/DataBoxTable.tsx @@ -0,0 +1,60 @@ +interface TableProps { + title: string; + headers: string[]; + data: string[][]; + variant?: "ghost" | "default"; +} + +export const DataBoxTable: React.FC = ({ + title, + headers, + data, + variant = "default", +}) => { + + const cssDressing = { + default: "bg-paper mt-4 flex w-96 flex-col gap-4 rounded-md border-violet-700/10 p-4 shadow-md bg-violet-300/5", + ghost: "mt-4 flex w-96 flex-col gap-4 rounded-md", + } + + return ( + <> +
+

{title}

+ + + + {headers?.map((header) => ( + + ))} + + + + {data?.map((service) => ( + + + + + + ))} + +
+ {header} +
+ {service[0]} + + {service[1]} + + {service[2]} +
+
+ + + ); +}; diff --git a/sirius-ui/src/components/DockerLogsViewer.tsx b/sirius-ui/src/components/DockerLogsViewer.tsx new file mode 100644 index 0000000..31e7667 --- /dev/null +++ b/sirius-ui/src/components/DockerLogsViewer.tsx @@ -0,0 +1,473 @@ +import React, { useState, useEffect } from "react"; +import { + Card, + CardContent, + CardHeader, + CardTitle, +} from "~/components/lib/ui/card"; +import { Badge } from "~/components/lib/ui/badge"; +import { Button } from "~/components/lib/ui/button"; +import { + Select, + SelectContent, + SelectItem, + SelectTrigger, + SelectValue, +} from "~/components/lib/ui/select"; +import { Input } from "~/components/lib/ui/input"; +import { + RefreshCw, + Search, + Filter, + Download, + Eye, + EyeOff, + AlertTriangle, + FileText, + Clock, +} from "lucide-react"; + +interface DockerLogsViewerProps { + className?: string; +} + +interface LogEntry { + container: string; + timestamp: string; + level: string; + message: string; +} + +interface DockerLogsData { + logs: LogEntry[]; + summary: { + total_logs: number; + containers: string[]; + }; + timestamp: string; + container: string; + lines: string; +} + +export const DockerLogsViewer: React.FC = ({ + className, +}) => { + const [data, setData] = useState(null); + const [loading, setLoading] = useState(true); + const [error, setError] = useState(null); + const [selectedContainer, setSelectedContainer] = useState("all"); + const [lines, setLines] = useState("100"); + const [searchTerm, setSearchTerm] = useState(""); + const [showTimestamps, setShowTimestamps] = useState(true); + const [autoRefresh, setAutoRefresh] = useState(false); + const [refreshInterval, setRefreshInterval] = useState("30"); + + // Mock data for fallback + const generateMockData = (): DockerLogsData => { + const now = new Date(); + return { + logs: [ + { + container: "sirius-api", + timestamp: new Date(now.getTime() - 1 * 60 * 1000).toISOString(), + level: "INFO", + message: "🚀 Sirius API starting on port 9001...", + }, + { + container: "sirius-api", + timestamp: new Date(now.getTime() - 2 * 60 * 1000).toISOString(), + level: "INFO", + message: "✅ PostgreSQL database connection established", + }, + { + container: "sirius-ui", + timestamp: new Date(now.getTime() - 3 * 60 * 1000).toISOString(), + level: "INFO", + message: "Ready - started server on 0.0.0.0:3000", + }, + { + container: "sirius-engine", + timestamp: new Date(now.getTime() - 4 * 60 * 1000).toISOString(), + level: "INFO", + message: "Scanner service initialized successfully", + }, + { + container: "sirius-postgres", + timestamp: new Date(now.getTime() - 5 * 60 * 1000).toISOString(), + level: "INFO", + message: "database system is ready to accept connections", + }, + { + container: "sirius-valkey", + timestamp: new Date(now.getTime() - 6 * 60 * 1000).toISOString(), + level: "INFO", + message: "Valkey server started, ready to accept connections", + }, + { + container: "sirius-rabbitmq", + timestamp: new Date(now.getTime() - 7 * 60 * 1000).toISOString(), + level: "INFO", + message: "Server startup complete; 0 plugins started.", + }, + { + container: "sirius-api", + timestamp: new Date(now.getTime() - 8 * 60 * 1000).toISOString(), + level: "WARN", + message: "High memory usage detected in container", + }, + { + container: "sirius-engine", + timestamp: new Date(now.getTime() - 9 * 60 * 1000).toISOString(), + level: "ERROR", + message: "Failed to connect to external service: timeout", + }, + { + container: "sirius-ui", + timestamp: new Date(now.getTime() - 10 * 60 * 1000).toISOString(), + level: "INFO", + message: "Next.js application compiled successfully", + }, + ], + summary: { + total_logs: 10, + containers: [ + "sirius-api", + "sirius-ui", + "sirius-engine", + "sirius-postgres", + "sirius-valkey", + "sirius-rabbitmq", + ], + }, + timestamp: now.toISOString(), + container: "all", + lines: "100", + }; + }; + + const loadDockerLogs = async () => { + try { + setLoading(true); + setError(null); + + // Build query parameters + const params = new URLSearchParams(); + if (selectedContainer !== "all") { + params.append("container", selectedContainer); + } + params.append("lines", lines); + + // Fetch real Docker logs from API + const response = await fetch( + `${ + process.env.NEXT_PUBLIC_SIRIUS_API_URL || "http://localhost:9001" + }/api/v1/system/logs?${params.toString()}` + ); + if (!response.ok) { + throw new Error(`HTTP error! status: ${response.status}`); + } + const apiData = await response.json(); + + setData(apiData); + } catch (err) { + setError( + err instanceof Error ? err.message : "Failed to load Docker logs" + ); + console.error("Failed to load Docker logs:", err); + + // Fallback to mock data on error + const mockData = generateMockData(); + setData(mockData); + } finally { + setLoading(false); + } + }; + + useEffect(() => { + loadDockerLogs(); + }, [selectedContainer, lines]); + + // Auto-refresh functionality + useEffect(() => { + if (!autoRefresh) return; + + const interval = setInterval(() => { + loadDockerLogs(); + }, parseInt(refreshInterval) * 1000); + + return () => clearInterval(interval); + }, [autoRefresh, refreshInterval, selectedContainer, lines]); + + const handleRefresh = () => { + loadDockerLogs(); + }; + + const getLevelBadgeVariant = (level: string) => { + switch (level.toUpperCase()) { + case "ERROR": + return "destructive"; + case "WARN": + case "WARNING": + return "outline"; + case "INFO": + return "default"; + case "DEBUG": + return "secondary"; + default: + return "outline"; + } + }; + + const formatTimestamp = (timestamp: string) => { + try { + const date = new Date(timestamp); + return date.toLocaleString(); + } catch { + return "Unknown"; + } + }; + + const formatRelativeTime = (timestamp: string) => { + try { + const date = new Date(timestamp); + const now = new Date(); + const diffMs = now.getTime() - date.getTime(); + const diffMinutes = Math.floor(diffMs / (1000 * 60)); + + if (diffMinutes < 1) return "Just now"; + if (diffMinutes === 1) return "1 minute ago"; + return `${diffMinutes} minutes ago`; + } catch { + return "Unknown"; + } + }; + + // Filter logs based on search term + const filteredLogs = + data?.logs.filter( + (log) => + log.message.toLowerCase().includes(searchTerm.toLowerCase()) || + log.container.toLowerCase().includes(searchTerm.toLowerCase()) || + log.level.toLowerCase().includes(searchTerm.toLowerCase()) + ) || []; + + const downloadLogs = () => { + if (!data) return; + + const logText = filteredLogs + .map((log) => { + const timestamp = showTimestamps + ? `[${formatTimestamp(log.timestamp)}] ` + : ""; + return `${timestamp}[${log.container}] [${log.level}] ${log.message}`; + }) + .join("\n"); + + const blob = new Blob([logText], { type: "text/plain" }); + const url = URL.createObjectURL(blob); + const a = document.createElement("a"); + a.href = url; + a.download = `docker-logs-${selectedContainer}-${ + new Date().toISOString().split("T")[0] + }.txt`; + document.body.appendChild(a); + a.click(); + document.body.removeChild(a); + URL.revokeObjectURL(url); + }; + + if (loading && !data) { + return ( +
+
+
+ + Loading Docker logs... +
+
+
+ ); + } + + return ( +
+ {/* Header */} +
+
+

Docker Logs

+

+ Real-time container logs for cloud debugging +

+
+
+ + +
+
+ + {/* Error Alert */} + {error && ( +
+
+ + Error +
+

{error}

+
+ )} + + {/* Controls */} +
+
+ + +
+ +
+ + +
+ +
+ + setSearchTerm(e.target.value)} + className="w-48" + /> +
+ +
+ +
+ +
+ + {autoRefresh && ( + + )} +
+
+ + {/* Summary */} + {data && ( +
+
+ Showing {filteredLogs.length} of {data.summary.total_logs} logs + {selectedContainer !== "all" && ` from ${selectedContainer}`} + {searchTerm && ` matching "${searchTerm}"`} +
+
Last updated: {formatRelativeTime(data.timestamp)}
+
+ )} + + {/* Logs Display */} + {data && ( + + + Container Logs + + +
+ {filteredLogs.length === 0 ? ( +
+ No logs found matching your criteria +
+ ) : ( +
+ {filteredLogs.map((log, index) => ( +
+ {showTimestamps && ( +
+ {formatTimestamp(log.timestamp)} +
+ )} + + {log.container} + + + {log.level} + +
{log.message}
+
+ ))} +
+ )} +
+ + + )} +
+ ); +}; diff --git a/sirius-ui/src/components/DynamicTerminal.tsx b/sirius-ui/src/components/DynamicTerminal.tsx new file mode 100644 index 0000000..e4bfb68 --- /dev/null +++ b/sirius-ui/src/components/DynamicTerminal.tsx @@ -0,0 +1,1631 @@ +import { useEffect, useRef, useState, useCallback, useMemo } from "react"; +import { Terminal as XTerm } from "@xterm/xterm"; +import { FitAddon } from "@xterm/addon-fit"; +import { WebLinksAddon } from "@xterm/addon-web-links"; +import { api } from "~/utils/api"; +import { AgentList } from "~/components/agent/AgentList"; +import { AgentDetails } from "~/components/agent/AgentDetails"; +import { StatusDashboard } from "~/components/terminal/StatusDashboard"; + +import "@xterm/xterm/css/xterm.css"; + +// Module-level singleton to prevent multiple terminal instances +// This addresses React Strict Mode double mounting in development +let globalTerminalInstance: XTerm | null = null; +let globalInitializationInProgress = false; + +// Safety cleanup function for edge cases +const ensureGlobalCleanup = () => { + try { + if ( + globalTerminalInstance && + globalTerminalInstance.element?.isConnected === false + ) { + console.log("[Terminal] Cleaning up orphaned global instance"); + globalTerminalInstance.dispose(); + globalTerminalInstance = null; + globalInitializationInProgress = false; + } + } catch (error) { + console.warn("[Terminal] Error during cleanup:", error); + globalTerminalInstance = null; + globalInitializationInProgress = false; + } +}; + +// Catppuccin Mocha color scheme +const MOCHA_THEME = { + background: "#1e1e2e", // Base + foreground: "#cdd6f4", // Text + cursor: "#f5e0dc", // Rosewater + cursorAccent: "#1e1e2e", // Base + selection: "#585b7066", // Surface2 with alpha + black: "#45475a", // Surface1 + red: "#f38ba8", // Red + green: "#a6e3a1", // Green + yellow: "#f9e2af", // Yellow + blue: "#89b4fa", // Blue + magenta: "#cba6f7", // Mauve + cyan: "#89dceb", // Sky + white: "#bac2de", // Subtext1 + brightBlack: "#585b70", // Surface2 + brightRed: "#f38ba8", // Red + brightGreen: "#a6e3a1", // Green + brightYellow: "#f9e2af", // Yellow + brightBlue: "#89b4fa", // Blue + brightMagenta: "#cba6f7", // Mauve + brightCyan: "#89dceb", // Sky + brightWhite: "#a6adc8", // Subtext0 +} as const; + +interface Target { + type: "engine" | "agent"; + id?: string; + name?: string; +} + +// Define Agent type here (or move to shared types later) +type Agent = { + id: string; + name?: string | null; + status?: string | null; + lastSeen?: string | null; +}; + +// Define the curated details structure to be displayed +export type DisplayedAgentDetails = { + id: string; // Always need the ID + name?: string | null; + status?: string | null; + lastSeen?: string | null; + primaryIp?: string | null; + osArch?: string | null; + osVersion?: string | null; + agentVersion?: string | null; // Renamed from 'version' for clarity? + uptime?: string | null; +}; + +// Keep ParsedAgentStatus for parsing, but don't export if not needed elsewhere +type ParsedAgentStatus = { + agentId?: string; + hostId?: string; + uptime?: string; + serverTarget?: string; + apiTarget?: string; + scriptingEnabled?: string; + goVersion?: string; + osArch?: string; + osVersion?: string; + primaryIp?: string; + memoryAllocated?: string; + goroutines?: string; +}; + +// Note: agents and target commands need special handling with agentsQuery.data access, +// so they will be handled separately in the handleCommand function +const LOCAL_COMMANDS = { + help: (term: XTerm) => { + term.writeln(""); + term.writeln( + "\x1b[38;2;166;227;161m\x1b[1m Sirius Agent Terminal Help\x1b[0m" + ); + term.writeln( + "\x1b[38;2;166;227;161m─────────────────────────────────────────\x1b[0m" + ); + term.writeln(""); + term.writeln("\x1b[1mLocal Commands:\x1b[0m"); + term.writeln( + " \x1b[38;2;137;180;250mhelp\x1b[0m - Show this help message" + ); + term.writeln( + " \x1b[38;2;137;180;250mclear\x1b[0m - Clear the terminal" + ); + term.writeln( + " \x1b[38;2;137;180;250magents\x1b[0m - List available agents" + ); + term.writeln( + " \x1b[38;2;137;180;250mtarget\x1b[0m - Show current target" + ); + term.writeln(" \x1b[38;2;137;180;250muse\x1b[0m - Select target"); + term.writeln( + " \x1b[38;2;137;180;250mversion\x1b[0m - Show terminal version" + ); + term.writeln( + " \x1b[38;2;137;180;250mhistory\x1b[0m - Show command history" + ); + term.writeln( + " \x1b[38;2;137;180;250mexit\x1b[0m - Close the session" + ); + term.writeln( + " \x1b[38;2;137;180;250mstatus\x1b[0m - Show system status" + ); + term.writeln(""); + term.writeln("\x1b[1mUsage Examples:\x1b[0m"); + term.writeln(" \x1b[38;2;247;154;134muse engine\x1b[0m"); + term.writeln(" \x1b[38;2;247;154;134muse agent sephiroth\x1b[0m"); + term.writeln(" \x1b[38;2;247;154;134muse agent sirius-engine\x1b[0m"); + term.writeln(""); + term.writeln("\x1b[1mKeyboard Shortcuts:\x1b[0m"); + term.writeln(" Ctrl+C - Cancel command"); + term.writeln(" Ctrl+L - Clear screen"); + term.writeln(" Up/Down - Command history"); + term.writeln(" Tab - Auto-complete"); + term.writeln(""); + }, + clear: (term: XTerm) => term.clear(), + history: (term: XTerm, history: string[]) => { + history.forEach((cmd, i) => { + term.writeln(` ${history.length - i - 1} ${cmd}`); + }); + }, + exit: (term: XTerm) => { + term.writeln("\x1b[38;2;166;227;161mClosing session...\x1b[0m"); + return { exit: true }; + }, + version: (term: XTerm) => { + term.writeln("\x1b[38;2;166;227;161mSirius Agent Terminal v0.1.0\x1b[0m"); + }, + status: (term: XTerm) => { + term.writeln("\x1b[38;2;166;227;161m╭─── System Status ───╮\x1b[0m"); + term.writeln( + "\x1b[38;2;166;227;161m│\x1b[0m Terminal: \x1b[38;2;166;227;161mOnline\x1b[0m \x1b[38;2;166;227;161m│\x1b[0m" + ); + term.writeln( + "\x1b[38;2;166;227;161m│\x1b[0m API: \x1b[38;2;166;227;161mOnline\x1b[0m \x1b[38;2;166;227;161m│\x1b[0m" + ); + term.writeln( + "\x1b[38;2;166;227;161m│\x1b[0m Queue: \x1b[38;2;166;227;161mOnline\x1b[0m \x1b[38;2;166;227;161m│\x1b[0m" + ); + term.writeln("\x1b[38;2;166;227;161m╰─────────────────────╯\x1b[0m"); + }, +} as const; + +export default function DynamicTerminal() { + const terminalRef = useRef(null); + const terminal = useRef(null); + const fitAddonRef = useRef(null); + const commandHistoryRef = useRef([]); + const historyPositionRef = useRef(-1); + const currentLineRef = useRef(""); + const promptLengthRef = useRef(0); + const currentTargetRef = useRef({ + type: "engine", + }); + const [targetDisplay, setTargetDisplay] = useState({ + type: "engine", + }); + const [selectedAgentId, setSelectedAgentId] = useState(null); + const [agentStatusDetails, setAgentStatusDetails] = + useState(null); + const isInitializingRef = useRef(false); + + // Query for agents data using the new router with host information + const agentsQuery = api.agent.listAgentsWithHosts.useQuery(undefined, { + refetchInterval: 10000, + refetchOnWindowFocus: false, + }); + + // Query for agent details (now from the agent router) + const agentDetailsQuery = api.agent.getAgentDetails.useQuery( + { agentId: selectedAgentId || "" }, + { + enabled: !!selectedAgentId, + refetchInterval: 10000, + } + ); + + // Use the agent details query loading state instead of separate state + const isRefreshingDetails = agentDetailsQuery.isLoading; + + // Combine agent list data and parsed status details + const combinedAgentDetails = useMemo((): DisplayedAgentDetails | null => { + if (!selectedAgentId) return null; + + // Use the agent details from the new agent router + if (agentDetailsQuery.data) { + const agentData = agentDetailsQuery.data; + return { + id: agentData.id, + name: agentData.name, + status: agentData.status, + lastSeen: agentData.lastSeen, + primaryIp: agentData.host?.ip, + osArch: agentData.host?.os, + osVersion: agentData.host?.osVersion, + agentVersion: undefined, // Not available yet + uptime: undefined, // Not available yet + }; + } + + // Fallback: use basic agent info from list if available + const agentFromList = agentsQuery.data?.find( + (a) => a.id === selectedAgentId + ); + + if (agentFromList) { + return { + id: selectedAgentId, + name: agentFromList.name, + status: agentFromList.status, + lastSeen: agentFromList.lastSeen, + primaryIp: agentFromList.host?.ip, + osArch: agentFromList.host?.os, + osVersion: agentFromList.host?.osVersion, + agentVersion: undefined, + uptime: undefined, + }; + } + + return null; + }, [selectedAgentId, agentDetailsQuery.data, agentsQuery.data]); + + const stripAnsi = (str: string): string => { + return str.replace(/\x1b\[[0-9;]*[mK]/g, ""); + }; + + const writePrompt = useCallback((term: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${target.name ?? target.id ?? "??"}]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + term.write("\r\x1b[K"); + term.write(fullPrompt); + }, []); + + // Mutation to execute commands (handlers moved to separate useEffect) + const executeCommand = api.terminal.executeCommand.useMutation(); + + // Handle agent command with direct API call to ensure fresh data + const handleAgentsCommand = async (term: XTerm) => { + console.log("[Terminal] agentsQuery.data:", agentsQuery.data); + console.log("[Terminal] agentsQuery.isLoading:", agentsQuery.isLoading); + console.log("[Terminal] agentsQuery.error:", agentsQuery.error); + + try { + // Force refetch agents to get fresh data + const freshAgents = await agentsQuery.refetch(); + console.log("[Terminal] Fresh agents data:", freshAgents.data); + + if (freshAgents.data && freshAgents.data.length > 0) { + term.writeln(""); + term.writeln( + "\x1b[38;2;166;227;161m\x1b[1m Available Agents\x1b[0m" + ); + term.writeln( + "\x1b[38;2;166;227;161m─────────────────────────────────────────────────────────\x1b[0m" + ); + term.writeln(""); + term.writeln("Agent ID Name Status Last Seen"); + term.writeln( + "─────────────── ────────────── ────── ─────────────────" + ); + + freshAgents.data.forEach((agent) => { + console.log("[Terminal] Processing agent:", agent); + const agentId = (agent.id || "").substring(0, 15).padEnd(15); + const agentName = (agent.name || "Unknown") + .substring(0, 14) + .padEnd(14); + const status = + agent.status === "online" + ? "\x1b[32mOnline\x1b[0m " + : "\x1b[31mOffline\x1b[0m "; + const lastSeen = agent.lastSeen + ? new Date(agent.lastSeen).toLocaleTimeString() + : "Never"; + + term.writeln(`${agentId} ${agentName} ${status} ${lastSeen}`); + }); + + term.writeln(""); + term.writeln(`Total agents: ${freshAgents.data.length}`); + term.writeln(""); + } else { + term.writeln(""); + term.writeln( + "\x1b[38;2;166;227;161m\x1b[1m Available Agents\x1b[0m" + ); + term.writeln( + "\x1b[38;2;166;227;161m─────────────────────────────────────────────────────────\x1b[0m" + ); + term.writeln(""); + term.writeln("\x1b[33mNo agents available.\x1b[0m"); + term.writeln(""); + term.writeln( + `\x1b[38;2;137;180;250mDebug: freshAgents.data = ${JSON.stringify( + freshAgents.data + )}\x1b[0m` + ); + term.writeln( + `\x1b[38;2;137;180;250mDebug: Original agentsQuery.data = ${JSON.stringify( + agentsQuery.data + )}\x1b[0m` + ); + } + } catch (error) { + console.error("[Terminal] Error fetching agents:", error); + term.writeln(" \x1b[38;2;243;139;168mError fetching agents\x1b[0m"); + term.writeln( + ` \x1b[38;2;137;180;250mFallback agentsQuery.data = ${JSON.stringify( + agentsQuery.data + )}\x1b[0m` + ); + } + }; + + // Handle target command + const handleTargetCommand = (term: XTerm) => { + const target = currentTargetRef.current; + if (target.type === "agent") { + term.writeln( + `\x1b[38;2;166;227;161mCurrent target: agent ${target.id}\x1b[0m` + ); + } else { + term.writeln(`\x1b[38;2;166;227;161mCurrent target: engine\x1b[0m`); + } + }; + + // Handle agent details refresh + const handleRefreshAgentDetails = useCallback( + async (agentId: string) => { + console.log(`[Terminal] Refreshing details for agent ${agentId}`); + // Refetch agent details using the new query + if (agentId === selectedAgentId) { + await agentDetailsQuery.refetch(); + } + }, + [selectedAgentId, agentDetailsQuery] + ); + + // Rest of the terminal initialization logic... + useEffect(() => { + // Safety cleanup for orphaned instances + ensureGlobalCleanup(); + + // Enhanced guard logic using both local and global state + if ( + !terminalRef.current || + terminal.current || + isInitializingRef.current || + globalTerminalInstance || + globalInitializationInProgress + ) { + console.log("[Terminal useEffect] Skipping initialization:", { + noTerminalRef: !terminalRef.current, + terminalExists: !!terminal.current, + localInitializing: isInitializingRef.current, + globalInstance: !!globalTerminalInstance, + globalInitializing: globalInitializationInProgress, + }); + return; + } + + // Set both local and global initialization flags + isInitializingRef.current = true; + globalInitializationInProgress = true; + console.log( + "[Terminal useEffect] Initializing xterm with singleton protection..." + ); + + const term = new XTerm({ + cursorBlink: true, + fontSize: 14, + fontFamily: "JetBrains Mono, Menlo, Monaco, 'Courier New', monospace", + theme: MOCHA_THEME, + letterSpacing: 0, + lineHeight: 1.2, + scrollback: 5000, + cursorStyle: "block", + cursorWidth: 2, + rows: 30, + cols: 80, + scrollOnUserInput: true, + fastScrollModifier: "alt", + }); + + const webLinksAddon = new WebLinksAddon(); + const currentFitAddon = new FitAddon(); + fitAddonRef.current = currentFitAddon; + + term.loadAddon(currentFitAddon); + term.loadAddon(webLinksAddon); + + term.open(terminalRef.current); + + // Set both local and global references + terminal.current = term; + globalTerminalInstance = term; + console.log("[Terminal useEffect] Xterm opened and registered globally."); + + const initialFit = () => { + setTimeout(() => { + try { + if (terminal.current?.element && fitAddonRef.current) { + fitAddonRef.current.fit(); + console.log("[Terminal useEffect] Delayed initial fit executed."); + } + } catch (e) { + console.error( + "[Terminal useEffect] Error during delayed initial fit:", + e + ); + } + }, 50); + + const init = async () => { + console.log("[Terminal init] Writing welcome message..."); + term.writeln( + "\x1b[38;2;203;166;247m╭────────────────────────────────╮" + ); + term.writeln( + "\x1b[38;2;203;166;247m│\x1b[0m Welcome to the Sirius Terminal \x1b[38;2;203;166;247m│" + ); + term.writeln( + "\x1b[38;2;203;166;247m╰────────────────────────────────╯\x1b[0m" + ); + term.writeln("\x1b[38;2;166;227;161mHack the planet!\x1b[0m"); + term.writeln( + "\x1b[38;2;137;180;250mType 'help' for available commands or use the sidebar\x1b[0m" + ); + + // Use a stable reference for writePrompt to avoid dependency issues + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write("\r\x1b[K"); + termInstance.write(fullPrompt); + + // Ensure the prompt is visible after writing + ensureCursorVisible(); + }; + + stableWritePrompt(term); + console.log("[Terminal init] Prompt written."); + + // Clear global initialization flag after successful init + globalInitializationInProgress = false; + }; + void init(); + }; + + requestAnimationFrame(initialFit); + + const resizeObserver = new ResizeObserver(() => { + requestAnimationFrame(() => { + try { + if (terminal.current?.element && fitAddonRef.current) { + fitAddonRef.current.fit(); + } + } catch (e) { + console.error("[Terminal ResizeObserver] Error during fit:", e); + } + }); + }); + + const parentElement = terminalRef.current?.parentElement; + if (parentElement) { + resizeObserver.observe(parentElement); + } + + // Auto-scroll helper function to keep cursor visible + const ensureCursorVisible = () => { + const term = terminal.current; + if (!term) return; + + // Scroll to bottom to ensure the cursor/prompt is visible + term.scrollToBottom(); + }; + + // Input handling logic + let currentLine = ""; + let currentPosition = 0; + + const clearInputLine = () => { + const term = terminal.current; + if (!term) return; + // Move to start of prompt, then to end of prompt, then clear to end of line + term.write(`\r\x1b[${promptLengthRef.current}C`); + term.write("\x1b[K"); + }; + + const redrawInputLine = () => { + const term = terminal.current; + if (!term) return; + // Clear only the input part, preserving the prompt + clearInputLine(); + term.write(currentLine); + if (currentPosition < currentLine.length) { + term.write(`\x1b[${currentLine.length - currentPosition}D`); + } + }; + + const insertCharacterOptimized = (char: string) => { + const term = terminal.current; + if (!term) return; + + // Optimize for simple case: inserting at end of line + if (currentPosition === currentLine.length) { + currentLine += char; + currentPosition++; + term.write(char); // Just write the character, no redraw needed + } else { + // Complex case: inserting in middle of line, needs redraw + currentLine = + currentLine.slice(0, currentPosition) + + char + + currentLine.slice(currentPosition); + currentPosition++; + redrawInputLine(); + } + }; + + const insertCharacter = (char: string) => { + currentLine = + currentLine.slice(0, currentPosition) + + char + + currentLine.slice(currentPosition); + currentPosition++; + redrawInputLine(); + }; + + const deleteCharacterBeforeCursorOptimized = () => { + const term = terminal.current; + if (!term || currentPosition <= 0) return; + + // Optimize for simple case: deleting at end of line + if (currentPosition === currentLine.length) { + currentLine = currentLine.slice(0, -1); + currentPosition--; + // Move cursor back one position and clear to end of line + term.write("\x1b[D\x1b[K"); + } else { + // Complex case: deleting in middle of line, needs redraw + currentLine = + currentLine.slice(0, currentPosition - 1) + + currentLine.slice(currentPosition); + currentPosition--; + redrawInputLine(); + } + }; + + const deleteCharacterBeforeCursor = () => { + if (currentPosition > 0) { + currentLine = + currentLine.slice(0, currentPosition - 1) + + currentLine.slice(currentPosition); + currentPosition--; + redrawInputLine(); + } + }; + + const handleTabCompletion = async () => { + const beforeCursor = currentLine.slice(0, currentPosition); + const afterCursor = currentLine.slice(currentPosition); + + console.log("=== TAB COMPLETION DEBUG ==="); + console.log("currentLine:", JSON.stringify(currentLine)); + console.log("currentPosition:", currentPosition); + console.log("beforeCursor:", JSON.stringify(beforeCursor)); + console.log("afterCursor:", JSON.stringify(afterCursor)); + + // Available commands + const commands = [ + "help", + "clear", + "agents", + "target", + "use", + "version", + "history", + "exit", + "status", + ]; + + // Split current input to analyze context (don't trim to preserve trailing spaces) + const parts = beforeCursor.split(/\s+/); + console.log("parts:", parts); + console.log("beforeCursor ends with space:", beforeCursor.endsWith(" ")); + + if (parts.length === 1 && parts[0]) { + // Complete command names + const partial = parts[0].toLowerCase(); + const matches = commands.filter((cmd) => cmd.startsWith(partial)); + + if (matches.length === 1 && matches[0]) { + // Single match - complete it + const completion = matches[0]; + const newLine = completion + afterCursor; + const newPosition = completion.length; + + clearInputLine(); + currentLine = newLine; + currentPosition = newPosition; + term.write(currentLine); + + // Move cursor to correct position + if (currentPosition < currentLine.length) { + term.write(`\x1b[${currentLine.length - currentPosition}D`); + } + } else if (matches.length > 1) { + // Multiple matches - show options + term.writeln(""); + term.writeln(`Available commands: ${matches.join(", ")}`); + + // Find common prefix + let commonPrefix = matches[0] || ""; + for (const match of matches) { + while (commonPrefix && !match.startsWith(commonPrefix)) { + commonPrefix = commonPrefix.slice(0, -1); + } + } + + if (commonPrefix.length > partial.length) { + // Complete to common prefix + const newLine = commonPrefix + afterCursor; + const newPosition = commonPrefix.length; + + currentLine = newLine; + currentPosition = newPosition; + } + + // Redraw prompt and current input + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write(fullPrompt); + }; + stableWritePrompt(term); + term.write(currentLine); + + // Move cursor to correct position + if (currentPosition < currentLine.length) { + term.write(`\x1b[${currentLine.length - currentPosition}D`); + } + } + } else if ( + parts.length === 2 && + parts[0] && + parts[1] && + parts[0].toLowerCase() === "use" + ) { + // Complete "use" command arguments + const partial = parts[1].toLowerCase(); + const useOptions = ["engine", "agent"]; + + const matches = useOptions.filter((opt) => opt.startsWith(partial)); + + if (matches.length === 1 && matches[0]) { + // Complete the option + const completion = matches[0]; + const newLine = `use ${completion}${afterCursor}`; + const newPosition = `use ${completion}`.length; + + clearInputLine(); + currentLine = newLine; + currentPosition = newPosition; + term.write(currentLine); + + if (currentPosition < currentLine.length) { + term.write(`\x1b[${currentLine.length - currentPosition}D`); + } + } else if (matches.length > 1) { + // Multiple matches - show options + term.writeln(""); + term.writeln(`${matches.join(" ")}`); + + // Find common prefix + let commonPrefix = matches[0] || ""; + for (const match of matches) { + while (commonPrefix && !match.startsWith(commonPrefix)) { + commonPrefix = commonPrefix.slice(0, -1); + } + } + + if (commonPrefix.length > partial.length) { + const newLine = `use ${commonPrefix}${afterCursor}`; + const newPosition = `use ${commonPrefix}`.length; + + currentLine = newLine; + currentPosition = newPosition; + } + + // Redraw prompt and current input + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write(fullPrompt); + }; + stableWritePrompt(term); + term.write(currentLine); + + // Move cursor to correct position + if (currentPosition < currentLine.length) { + term.write(`\x1b[${currentLine.length - currentPosition}D`); + } + } + } else if ( + (parts.length === 2 && + parts[0] && + parts[1] && + parts[0].toLowerCase() === "use" && + parts[1].toLowerCase() === "agent") || + (parts.length === 3 && + parts[0] && + parts[1] && + parts[0].toLowerCase() === "use" && + parts[1].toLowerCase() === "agent" && + beforeCursor.endsWith(" ")) + ) { + // Handle "use agent" or "use agent " (with trailing space) + try { + console.log("[Autocomplete] Detected 'use agent' completion case"); + + const freshAgents = await agentsQuery.refetch(); + const agents = freshAgents.data || []; + + if (agents.length === 0) { + term.writeln(""); + term.writeln("no agents available"); + } else { + term.writeln(""); + const agentIds = agents.map((a) => a.id); + term.writeln(`${agentIds.join(" ")}`); + } + + // Redraw prompt and current input + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write(fullPrompt); + }; + stableWritePrompt(term); + term.write(currentLine); + + if (currentPosition < currentLine.length) { + term.write(`\x1b[${currentLine.length - currentPosition}D`); + } + } catch (error) { + console.error( + "[Terminal] Error fetching agents for autocomplete:", + error + ); + } + } else if ( + parts.length >= 3 && + parts[0] && + parts[1] && + parts[0].toLowerCase() === "use" && + parts[1].toLowerCase() === "agent" && + !beforeCursor.endsWith(" ") + ) { + // Handle "use agent " - there's partial text after agent + try { + const partial = parts[2] ? parts[2].toLowerCase() : ""; + + console.log( + "[Autocomplete] Detected 'use agent ' case, partial:", + partial + ); + + const freshAgents = await agentsQuery.refetch(); + const agents = freshAgents.data || []; + + if (agents.length === 0) { + term.writeln(""); + term.writeln("no agents available"); + + // Redraw prompt and current input + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write(fullPrompt); + }; + stableWritePrompt(term); + term.write(currentLine); + + if (currentPosition < currentLine.length) { + term.write(`\x1b[${currentLine.length - currentPosition}D`); + } + return; + } + + // Create autocomplete options: both agent.id and agent.name (if different) + const agentOptions: Array<{ id: string; displayName: string }> = []; + + agents.forEach((agent) => { + // Always add the agent ID + agentOptions.push({ id: agent.id, displayName: agent.id }); + + // Add agent name if it exists and is different from ID + if (agent.name && agent.name !== agent.id) { + agentOptions.push({ id: agent.id, displayName: agent.name }); + } + }); + + // Filter matches based on partial input (case insensitive) + // If no partial input, show all options + const matches = partial + ? agentOptions.filter((option) => + option.displayName.toLowerCase().startsWith(partial) + ) + : agentOptions; + + console.log( + "[Autocomplete] matches:", + matches.length, + matches.map((m) => m.displayName) + ); + + if (matches.length === 1 && partial && matches[0]) { + // Single match and we have partial input - complete using agent ID + const completion = matches[0].id; + const newLine = `use agent ${completion}${afterCursor}`; + const newPosition = `use agent ${completion}`.length; + + clearInputLine(); + currentLine = newLine; + currentPosition = newPosition; + term.write(currentLine); + + if (currentPosition < currentLine.length) { + term.write(`\x1b[${currentLine.length - currentPosition}D`); + } + } else if (matches.length >= 1) { + // Multiple matches OR no partial input - show options + term.writeln(""); + const displayNames = matches.map((m) => m.displayName); + + // Remove duplicates (when agent name = agent id) + const uniqueDisplayNames = [...new Set(displayNames)]; + term.writeln(`${uniqueDisplayNames.join(" ")}`); + + // Only try to complete common prefix if we have partial input + if (partial && matches.length > 1) { + // Find common prefix of display names + let commonPrefix = displayNames[0] || ""; + for (const name of displayNames) { + while ( + commonPrefix && + !name.toLowerCase().startsWith(commonPrefix.toLowerCase()) + ) { + commonPrefix = commonPrefix.slice(0, -1); + } + } + + if (commonPrefix.length > partial.length) { + // Find the agent whose display name starts with the common prefix + const matchingAgent = matches.find((m) => + m.displayName + .toLowerCase() + .startsWith(commonPrefix.toLowerCase()) + ); + + if (matchingAgent) { + const newLine = `use agent ${matchingAgent.id}${afterCursor}`; + const newPosition = `use agent ${matchingAgent.id}`.length; + + currentLine = newLine; + currentPosition = newPosition; + } + } + } + + // Redraw prompt and current input + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write(fullPrompt); + }; + stableWritePrompt(term); + term.write(currentLine); + + if (currentPosition < currentLine.length) { + term.write(`\x1b[${currentLine.length - currentPosition}D`); + } + } else { + // No matches with partial input - show all available agents + term.writeln(""); + const agentIds = agents.map((a) => a.id); + term.writeln(`Available agents: ${agentIds.join(", ")}`); + + // Redraw prompt and current input + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write(fullPrompt); + }; + stableWritePrompt(term); + term.write(currentLine); + + if (currentPosition < currentLine.length) { + term.write(`\x1b[${currentLine.length - currentPosition}D`); + } + } + } catch (error) { + console.error( + "[Terminal] Error fetching agents for autocomplete:", + error + ); + // Silent fail - just don't complete + } + } + }; + + const handleCommand = async (command: string) => { + const term = terminal.current; + if (!term) return; + + const cmd = command.trim().toLowerCase(); + const cmdParts = command.trim().split(/\s+/); + + // Handle 'use' command separately (it takes arguments) + if (cmdParts[0]?.toLowerCase() === "use") { + if (cmdParts.length < 2) { + term.writeln( + "\x1b[38;2;243;139;168musage: use {engine|agent} [id]\x1b[0m" + ); + } else if (cmdParts[1]?.toLowerCase() === "engine") { + currentTargetRef.current = { type: "engine" }; + setTargetDisplay({ type: "engine" }); + setSelectedAgentId(null); // Clear agent selection when switching to engine + term.writeln( + "\x1b[38;2;166;227;161mSwitched to engine target\x1b[0m" + ); + + } else if (cmdParts[1]?.toLowerCase() === "agent") { + if (cmdParts.length < 3) { + // Show usage with available agents + try { + const freshAgents = await agentsQuery.refetch(); + if (freshAgents.data && freshAgents.data.length > 0) { + term.writeln( + "\x1b[38;2;243;139;168musage: use agent \x1b[0m" + ); + term.writeln( + ` ${freshAgents.data.map((a) => a.id).join(", ")}` + ); + } else { + term.writeln( + "\x1b[38;2;243;139;168musage: use agent \x1b[0m" + ); + term.writeln(" (no agents available)"); + } + } catch (error) { + term.writeln( + "\x1b[38;2;243;139;168musage: use agent \x1b[0m" + ); + } + } else { + const agentId = cmdParts[2]; + if (!agentId) { + term.writeln( + "\x1b[38;2;243;139;168musage: use agent \x1b[0m" + ); + return; + } + + // Check if agent exists - fetch fresh data to ensure accuracy + console.log(`[Terminal] Looking for agent '${agentId}'`); + console.log( + `[Terminal] Available agentsQuery.data:`, + agentsQuery.data + ); + + try { + const freshAgents = await agentsQuery.refetch(); + console.log( + `[Terminal] Fresh agents for lookup:`, + freshAgents.data + ); + console.log( + `[Terminal] Agent IDs available:`, + freshAgents.data?.map((a) => a.id) + ); + + const agent = freshAgents.data?.find((a) => a.id === agentId); + if (!agent) { + term.writeln( + `\x1b[38;2;243;139;168magent '${agentId}' not found\x1b[0m` + ); + if (freshAgents.data && freshAgents.data.length > 0) { + term.writeln( + ` ${freshAgents.data.map((a) => a.id).join(", ")}` + ); + } + } else { + currentTargetRef.current = { + type: "agent", + id: agentId, + name: agent.name ?? agentId, + }; + setTargetDisplay({ + type: "agent", + id: agentId, + name: agent.name ?? agentId, + }); + setSelectedAgentId(agentId); + term.writeln( + `\x1b[38;2;166;227;161mSwitched to agent '${agentId}'\x1b[0m` + ); + + } + } catch (error) { + console.error( + "[Terminal] Error fetching fresh agents for use command:", + error + ); + term.writeln( + `\x1b[38;2;243;139;168mError checking agent availability\x1b[0m` + ); + } + } + } else { + term.writeln( + `\x1b[38;2;243;139;168minvalid target '${cmdParts[1]}'\x1b[0m` + ); + term.writeln( + "\x1b[38;2;243;139;168musage: use {engine|agent} [id]\x1b[0m" + ); + } + + setTimeout(() => { + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write("\r\x1b[K"); + termInstance.write(fullPrompt); + }; + stableWritePrompt(term); + }, 10); + return; + } + + // Handle special local commands that need access to React state + if (cmd === "agents") { + // Handle async agents command + (async () => { + await handleAgentsCommand(term); + setTimeout(() => { + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write("\r\x1b[K"); + termInstance.write(fullPrompt); + }; + stableWritePrompt(term); + }, 10); + })(); + return; + } else if (cmd === "target") { + handleTargetCommand(term); + setTimeout(() => { + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write("\r\x1b[K"); + termInstance.write(fullPrompt); + }; + stableWritePrompt(term); + }, 10); + return; + } + + // Handle standard local commands + if (cmd in LOCAL_COMMANDS) { + if (cmd === "help") { + LOCAL_COMMANDS.help(term); + } else if (cmd === "clear") { + LOCAL_COMMANDS.clear(term); + } else if (cmd === "version") { + LOCAL_COMMANDS.version(term); + } else if (cmd === "history") { + LOCAL_COMMANDS.history(term, commandHistoryRef.current); + } else if (cmd === "status") { + LOCAL_COMMANDS.status(term); + } else if (cmd === "exit") { + LOCAL_COMMANDS.exit(term); + } + + setTimeout(() => { + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write("\r\x1b[K"); + termInstance.write(fullPrompt); + }; + stableWritePrompt(term); + }, 10); + return; + } + + // Handle remote commands + try { + await executeCommand.mutateAsync({ + command, + target: currentTargetRef.current, + }); + } catch (error) { + console.error("Command execution failed:", error); + term.writeln(`\x1b[38;2;243;139;168mCommand failed: ${error}\x1b[0m`); + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write("\r\x1b[K"); + termInstance.write(fullPrompt); + }; + stableWritePrompt(term); + } + }; + + // Key event handler + const onKey = (e: { key: string; domEvent: KeyboardEvent }) => { + const ev = e.domEvent; + const printable = !ev.altKey && !ev.ctrlKey && !ev.metaKey; + + // Handle Ctrl+L to clear the terminal + if (ev.ctrlKey && ev.key === "l") { + term.clear(); + // Reset input state + currentLine = ""; + currentPosition = 0; + historyPositionRef.current = -1; + + // Redraw the prompt + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write("\r\x1b[K"); + termInstance.write(fullPrompt); + }; + stableWritePrompt(term); + return; + } + + // Handle Tab for autocomplete + if (ev.key === "Tab") { + ev.preventDefault(); + void handleTabCompletion(); + return; + } + + if (ev.key === "Enter") { + term.writeln(""); + const command = currentLine; + if (command.trim()) { + commandHistoryRef.current.unshift(command.trim()); + if (commandHistoryRef.current.length > 100) { + commandHistoryRef.current.pop(); + } + } + historyPositionRef.current = -1; + currentLine = ""; + currentPosition = 0; + + void handleCommand(command); + + // Ensure cursor stays visible after command submission + ensureCursorVisible(); + } else if (ev.key === "Backspace") { + deleteCharacterBeforeCursorOptimized(); + } else if (ev.key === "Delete") { + // Handle delete key + } else if (ev.key === "ArrowLeft") { + if (currentPosition > 0) { + currentPosition--; + term.write("\x1b[D"); + } + } else if (ev.key === "ArrowRight") { + if (currentPosition < currentLine.length) { + currentPosition++; + term.write("\x1b[C"); + } + } else if (ev.key === "ArrowUp") { + // Navigate backwards through command history + if (commandHistoryRef.current.length > 0) { + if ( + historyPositionRef.current < + commandHistoryRef.current.length - 1 + ) { + historyPositionRef.current++; + const historyCommand = + commandHistoryRef.current[historyPositionRef.current]; + + // Clear current input and replace with history command + if (historyCommand !== undefined) { + clearInputLine(); + currentLine = historyCommand; + currentPosition = currentLine.length; + term.write(currentLine); + } + } + } + } else if (ev.key === "ArrowDown") { + // Navigate forwards through command history + if (historyPositionRef.current > -1) { + historyPositionRef.current--; + + if (historyPositionRef.current === -1) { + // Back to empty prompt + clearInputLine(); + currentLine = ""; + currentPosition = 0; + } else { + // Show newer command from history + const historyCommand = + commandHistoryRef.current[historyPositionRef.current]; + if (historyCommand !== undefined) { + clearInputLine(); + currentLine = historyCommand; + currentPosition = currentLine.length; + term.write(currentLine); + } + } + } + } else if (printable) { + insertCharacterOptimized(e.key); + } + }; + + term.onKey(onKey); + + return () => { + console.log( + "[Terminal cleanup] Disposing terminal and clearing global state..." + ); + + // Dispose of the terminal instance + if (terminal.current) { + terminal.current.dispose(); + terminal.current = null; + } + + // Clear global state + if (globalTerminalInstance === term) { + globalTerminalInstance = null; + } + + // Reset initialization flags + isInitializingRef.current = false; + globalInitializationInProgress = false; + + // Disconnect resize observer + resizeObserver.disconnect(); + + console.log("[Terminal cleanup] Cleanup completed."); + }; + }, []); // EMPTY DEPENDENCY ARRAY - No dependencies to prevent re-execution + + // Effect to handle click-based agent selection from sidebar + useEffect(() => { + if (selectedAgentId && terminal.current && agentsQuery.data) { + // Always check if we need to switch contexts - allow switching back to same agent + // after being in engine mode, or force refresh of agent context + const agent = agentsQuery.data.find((a) => a.id === selectedAgentId); + if (agent) { + const isAlreadyOnCorrectAgent = + targetDisplay.type === "agent" && + targetDisplay.id === selectedAgentId; + + if (!isAlreadyOnCorrectAgent) { + currentTargetRef.current = { + type: "agent", + id: selectedAgentId, + name: agent.name ?? selectedAgentId, + }; + setTargetDisplay({ + type: "agent", + id: selectedAgentId, + name: agent.name ?? selectedAgentId, + }); + + // Update prompt immediately when target changes + const term = terminal.current; + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write("\r\x1b[K"); + termInstance.write(fullPrompt); + }; + stableWritePrompt(term); + + console.log( + `[Terminal] Switched to agent '${selectedAgentId}' via click selection (was: ${targetDisplay.type})` + ); + } + } + } + }, [selectedAgentId, targetDisplay.type, targetDisplay.id]); // Use targetDisplay state instead of ref + + // Separate effect for handling executeCommand mutation responses + useEffect(() => { + if (executeCommand.isSuccess && executeCommand.data && terminal.current) { + const term = terminal.current; + const result = executeCommand.data; + + // Display the command output + if (result.output) { + const lines = result.output.split("\n"); + lines.forEach((line: string) => { + if (line.trim()) { + term.writeln(line); + } + }); + } + + // Show prompt for next command + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write("\r\x1b[K"); + termInstance.write(fullPrompt); + }; + stableWritePrompt(term); + } + + if (executeCommand.isError && terminal.current) { + const term = terminal.current; + const error = executeCommand.error; + + term.writeln(`\x1b[38;2;243;139;168mError: ${error.message}\x1b[0m`); + const stableWritePrompt = (termInstance: XTerm) => { + const target = currentTargetRef.current; + const targetPrefix = + target.type === "agent" + ? `\x1b[38;2;243;139;168m[${ + target.name ?? target.id ?? "??" + }]\x1b[0m ` + : ""; + const promptSuffix = `\x1b[38;2;137;180;250msirius>\x1b[0m `; + const fullPrompt = targetPrefix + promptSuffix; + + const visiblePrompt = stripAnsi(fullPrompt); + promptLengthRef.current = visiblePrompt.length; + + termInstance.write("\r\x1b[K"); + termInstance.write(fullPrompt); + }; + stableWritePrompt(term); + } + }, [ + executeCommand.isSuccess, + executeCommand.isError, + executeCommand.data, + executeCommand.error, + ]); + + return ( +
+ {/* Enhanced Sidebar */} +
+
+ {/* Header */} +
+

+ Agent Control +

+
+ + {/* Scrollable Content */} +
+ {/* Status Dashboard */} + agent.status?.toLowerCase() === "online" + ).length || 0 + } + /> + + {/* Agent List */} +
+

+ Available Agents +

+ +
+ + {/* Agent Details (when selected) */} + {selectedAgentId && ( +
+

+ Agent Details +

+ handleRefreshAgentDetails(selectedAgentId)} + onRunScan={() => console.log("Run scan on", selectedAgentId)} + /> +
+ )} +
+
+
+ + {/* Terminal */} +
+
+
+
+ ); +} diff --git a/sirius-ui/src/components/EnvironmentDataTable.tsx b/sirius-ui/src/components/EnvironmentDataTable.tsx new file mode 100755 index 0000000..ebdf734 --- /dev/null +++ b/sirius-ui/src/components/EnvironmentDataTable.tsx @@ -0,0 +1,811 @@ +"use client"; + +import React, { useState, useMemo, useRef, useEffect } from "react"; +import { + flexRender, + getCoreRowModel, + getFilteredRowModel, + getPaginationRowModel, + getSortedRowModel, + useReactTable, + type ColumnDef, + type ColumnFiltersState, + type FilterFn, + type Row, +} from "@tanstack/react-table"; +import { type EnvironmentTableData } from "~/server/api/routers/host"; +import { useRouter } from "next/router"; +import { cn } from "~/components/lib/utils"; +import { Download, Filter, MoreHorizontal, RefreshCw } from "lucide-react"; +import { getRiskLevel as getRiskLevelUtil } from "~/utils/riskScoreCalculator"; +import { matchesSourceFilter } from "~/utils/tableFilters"; + +/** + * Custom global filter that searches across all relevant string fields + * in the row data (hostname, ip, os, tags) regardless of how column + * accessors are defined. Works for both environment-page and scanner-page + * data shapes because both share these fields. + */ +const rowGlobalFilter: FilterFn = ( + row: Row, + _columnId: string, + filterValue: string +): boolean => { + const search = filterValue.toLowerCase().trim(); + if (!search) return true; + + const d = row.original; + if (d.hostname?.toLowerCase().includes(search)) return true; + if (d.ip?.toLowerCase().includes(search)) return true; + if (d.os?.toLowerCase().includes(search)) return true; + if (d.tags?.some((tag) => tag.toLowerCase().includes(search))) return true; + + // Also search vulnerability count as a string (e.g. "14") + if (String(d.vulnerabilityCount ?? "").includes(search)) return true; + + return false; +}; + +interface EnvironmentDataTableProps { + columns: ColumnDef[]; + data: EnvironmentTableData[]; + onRefresh?: () => void; +} + +export function EnvironmentDataTable({ + columns, + data, + onRefresh, +}: EnvironmentDataTableProps) { + const [globalFilter, setGlobalFilter] = useState(""); + const [columnFilters, setColumnFilters] = useState([]); + const [rowSelection, setRowSelection] = useState({}); + const [activeFilters, setActiveFilters] = useState([]); + const [showExportDropdown, setShowExportDropdown] = useState(false); + const [showAdvancedFilters, setShowAdvancedFilters] = useState(false); + + // Dropdown filter state + const [osFilter, setOsFilter] = useState(""); + const [riskFilter, setRiskFilter] = useState(""); + const [sourceFilter, setSourceFilter] = useState(""); + + // Advanced filter state + const [advIpRange, setAdvIpRange] = useState(""); + const [advDateRange, setAdvDateRange] = useState(""); + const [advTags, setAdvTags] = useState(""); + + const exportRef = useRef(null); + const router = useRouter(); + + // getRiskLevel — uses centralized util (count-only fallback) + const getRiskLevel = (count: number): string => + getRiskLevelUtil(undefined, count); + + // ── Pre-filter data based on quick-filters, dropdowns, and advanced ── + const filteredData = useMemo(() => { + let rows = data; + + // Quick-filter presets + if (activeFilters.includes("highRisk")) { + rows = rows.filter( + (h) => + getRiskLevel(h.vulnerabilityCount ?? 0) === "critical" || + getRiskLevel(h.vulnerabilityCount ?? 0) === "high" + ); + } + if (activeFilters.includes("windows")) { + rows = rows.filter((h) => + h.os?.toLowerCase().includes("windows") + ); + } + if (activeFilters.includes("linux")) { + rows = rows.filter( + (h) => + h.os?.toLowerCase().includes("linux") || + h.os?.toLowerCase().includes("ubuntu") || + h.os?.toLowerCase().includes("debian") || + h.os?.toLowerCase().includes("centos") || + h.os?.toLowerCase().includes("fedora") || + h.os?.toLowerCase().includes("rhel") + ); + } + // "Recently Scanned" – no scan-date field available on the data type, + // so we treat it as a no-op for now (all visible hosts are recent). + + // Dropdown filters + if (osFilter) { + rows = rows.filter((h) => + h.os?.toLowerCase().includes(osFilter.toLowerCase()) + ); + } + if (riskFilter) { + rows = rows.filter( + (h) => getRiskLevel(h.vulnerabilityCount ?? 0) === riskFilter + ); + } + if (sourceFilter) { + rows = rows.filter((h) => matchesSourceFilter(h, sourceFilter)); + } + + // Advanced filters + if (advIpRange.trim()) { + const term = advIpRange.trim().toLowerCase(); + // Simple prefix / substring match (e.g. "192.168.1") + // For CIDR we'd need a library – substring covers 90 % of use-cases + rows = rows.filter((h) => h.ip?.toLowerCase().includes(term)); + } + if (advTags.trim()) { + const wanted = advTags + .split(",") + .map((t) => t.trim().toLowerCase()) + .filter(Boolean); + if (wanted.length > 0) { + rows = rows.filter((h) => + wanted.some((w) => + h.tags?.some((tag) => tag.toLowerCase().includes(w)) + ) + ); + } + } + // advDateRange is a no-op since the table data doesn't carry scan timestamps. + + return rows; + }, [data, activeFilters, osFilter, riskFilter, sourceFilter, advIpRange, advTags, advDateRange]); + + // Track clicks outside of export dropdown + useEffect(() => { + function handleClickOutside(event: MouseEvent) { + if ( + exportRef.current && + !exportRef.current.contains(event.target as Node) + ) { + setShowExportDropdown(false); + } + } + + document.addEventListener("mousedown", handleClickOutside); + return () => { + document.removeEventListener("mousedown", handleClickOutside); + }; + }, []); + + // Filter columns to exclude status column + const filteredColumns = useMemo(() => { + return columns.filter((column) => { + // Filter out the status column if it exists + if ("accessorKey" in column && column.accessorKey === "status") { + return false; + } + if ("id" in column && column.id === "status") { + return false; + } + return true; + }); + }, [columns]); + + // Enable row selection by adding a selection column + const selectionColumn: ColumnDef = { + id: "select", + header: ({ table }) => ( +
+ { + if (input) { + input.indeterminate = + table.getIsSomePageRowsSelected() && + !table.getIsAllPageRowsSelected(); + } + }} + onChange={table.getToggleAllPageRowsSelectedHandler()} + /> +
+ ), + cell: ({ row }) => ( +
e.stopPropagation()}> + +
+ ), + enableSorting: false, + enableGlobalFilter: false, + }; + + // Add selection column to columns array + const columnsWithSelection = useMemo(() => { + return [selectionColumn, ...filteredColumns]; + }, [filteredColumns]); + + const table = useReactTable({ + data: filteredData, + columns: columnsWithSelection, + getCoreRowModel: getCoreRowModel(), + getPaginationRowModel: getPaginationRowModel(), + getSortedRowModel: getSortedRowModel(), + getFilteredRowModel: getFilteredRowModel(), + globalFilterFn: rowGlobalFilter, + state: { + globalFilter, + columnFilters, + rowSelection, + }, + onColumnFiltersChange: setColumnFilters, + onGlobalFilterChange: setGlobalFilter, + onRowSelectionChange: setRowSelection, + initialState: { + pagination: { + pageSize: 10, + }, + }, + enableRowSelection: true, + }); + + // Handle search input + const handleSearch = (event: React.ChangeEvent) => { + const value = event.target.value; + setGlobalFilter(value); + }; + + // Handle row click - navigate to host details + const handleRowClick = (host: EnvironmentTableData) => { + // Use router.push with a properly formatted path + router.push({ + pathname: "/host/[ip]", + query: { ip: host.ip }, + }); + }; + + // Handle refresh click + const handleRefresh = () => { + if (onRefresh) { + onRefresh(); + } else { + // Default refresh behavior if no callback is provided + window.location.reload(); + } + }; + + // Define filter presets + const filterPresets = [ + { name: "High Risk Hosts", filter: "highRisk" }, + { name: "Windows Hosts", filter: "windows" }, + { name: "Linux Hosts", filter: "linux" }, + { name: "Recently Scanned", filter: "recentlyScan" }, + ]; + + // Toggle a quick-filter preset on/off + const applyFilterPreset = (filter: string) => { + setActiveFilters((prev) => + prev.includes(filter) + ? prev.filter((f) => f !== filter) + : [...prev, filter] + ); + }; + + // Handle export + const handleExport = (format: "csv" | "json") => { + const selectedRows = table.getSelectedRowModel().rows; + const dataToExport = + selectedRows.length > 0 + ? selectedRows.map((row) => row.original) + : filteredData; + + if (format === "csv") { + // CSV export logic + const headers = Object.keys(dataToExport[0] || {}).join(","); + const csvRows = dataToExport.map((row) => Object.values(row).join(",")); + const csvContent = [headers, ...csvRows].join("\n"); + + const blob = new Blob([csvContent], { type: "text/csv;charset=utf-8;" }); + const url = URL.createObjectURL(blob); + const link = document.createElement("a"); + link.setAttribute("href", url); + link.setAttribute("download", "environment-hosts.csv"); + link.click(); + setShowExportDropdown(false); + } else if (format === "json") { + // JSON export logic + const jsonContent = JSON.stringify(dataToExport, null, 2); + const blob = new Blob([jsonContent], { type: "application/json" }); + const url = URL.createObjectURL(blob); + const link = document.createElement("a"); + link.setAttribute("href", url); + link.setAttribute("download", "environment-hosts.json"); + link.click(); + setShowExportDropdown(false); + } + }; + + // Calculate summary of selected hosts + const selectedHostsSummary = useMemo(() => { + const selectedRows = table.getSelectedRowModel().rows; + if (selectedRows.length === 0) return null; + + return { + count: selectedRows.length, + vulnerabilities: selectedRows.reduce( + (sum, row) => sum + (row.original.vulnerabilityCount || 0), + 0 + ), + }; + }, [table.getSelectedRowModel().rows]); + + // Column filter components + const renderColumnFilters = () => { + return ( +
+ + + + + +
+ ); + }; + + // Advanced filter components + const renderAdvancedFilters = () => { + if (!showAdvancedFilters) return null; + + return ( +
+

+ Advanced Filters +

+
+
+ + setAdvIpRange(e.target.value)} + className="w-full rounded-md border border-violet-500/20 bg-gray-900/50 px-3 py-1.5 text-gray-200 focus:border-violet-500/40 focus:outline-none" + /> +
+
+ + +
+
+ + setAdvTags(e.target.value)} + className="w-full rounded-md border border-violet-500/20 bg-gray-900/50 px-3 py-1.5 text-gray-200 focus:border-violet-500/40 focus:outline-none" + /> +
+
+ + +
+
+ +
+ + +
+
+ ); + }; + + return ( +
+ {/* Search and Filter Controls */} +
+
+
+
+ + + + + + {globalFilter && ( + + )} +
+
+ {table.getFilteredRowModel().rows.length} hosts found +
+
+ +
+ +
+ + {showExportDropdown && ( +
+ + +
+ )} +
+ +
+
+ + {/* Advanced filters */} + {renderAdvancedFilters()} + + {/* Filter presets */} +
+ {filterPresets.map((preset) => ( + + ))} +
+ + {/* Column-specific filters */} + {renderColumnFilters()} + + {/* Selected hosts summary */} + {selectedHostsSummary && ( +
+
+
+ + {selectedHostsSummary.count} hosts selected + + + with {selectedHostsSummary.vulnerabilities} total + vulnerabilities + +
+
+ + +
+
+
+ )} +
+ + {/* Table */} +
+ + + {table.getHeaderGroups().map((headerGroup) => ( + + {headerGroup.headers.map((header) => ( + + ))} + + ))} + + + {table.getRowModel().rows.length ? ( + table.getRowModel().rows.map((row) => ( + handleRowClick(row.original)} + className="cursor-pointer odd:bg-gray-800/40 even:bg-gray-900/40 hover:bg-violet-500/[0.06] transition-colors" + > + {row.getVisibleCells().map((cell) => ( + + ))} + + )) + ) : ( + + + + )} + +
+
+ {header.isPlaceholder + ? null + : flexRender( + header.column.columnDef.header, + header.getContext() + )} + {header.column.getCanSort() && ( +
+ {{ + asc: ( + + + + ), + desc: ( + + + + ), + }[header.column.getIsSorted() as string] ?? null} +
+ )} +
+
e.stopPropagation() + : undefined + } + > + {cell.column.id === "actions" ? ( +
+ +
+ ) : ( + flexRender( + cell.column.columnDef.cell, + cell.getContext() + ) + )} +
+ No hosts found +
+
+ + {/* Pagination */} +
+
+ + + Showing{" "} + {table.getState().pagination.pageIndex * + table.getState().pagination.pageSize + + 1}{" "} + to{" "} + {Math.min( + (table.getState().pagination.pageIndex + 1) * + table.getState().pagination.pageSize, + table.getFilteredRowModel().rows.length + )}{" "} + of {table.getFilteredRowModel().rows.length} hosts + +
+
+ + {Array.from({ length: Math.min(5, table.getPageCount()) }, (_, i) => { + const pageIndex = i; + return ( + + ); + })} + +
+
+
+ ); +} diff --git a/sirius-ui/src/components/EnvironmentDataTableColumns.tsx b/sirius-ui/src/components/EnvironmentDataTableColumns.tsx new file mode 100755 index 0000000..f04fbac --- /dev/null +++ b/sirius-ui/src/components/EnvironmentDataTableColumns.tsx @@ -0,0 +1,448 @@ +"use client"; + +import React from "react"; +import { createColumnHelper } from "@tanstack/react-table"; +import { type EnvironmentTableData } from "~/server/api/routers/host"; +import { VulnerabilityBarGraphCompact } from "~/components/VulnerabilityBarGraph"; + +import { Circle, ShieldAlert, ShieldCheck } from "lucide-react"; + +import { cn } from "~/components/lib/utils"; +import { HostRowActions } from "~/components/HostRowActions"; + +// Helper for OS icons +const OSIconSelector = ({ os }: { os: string }) => { + // Normalize OS name for matching + const osLower = os?.toLowerCase() || ""; + + if (osLower.includes("windows")) { + return ( + + + + + + + + ); + } else if ( + osLower.includes("linux") || + osLower.includes("ubuntu") || + osLower.includes("debian") || + osLower.includes("centos") + ) { + return ( + + + + + + ); + } else if ( + osLower.includes("mac") || + osLower.includes("darwin") || + osLower.includes("ios") + ) { + return ( + + + + + + ); + } else { + // Default unknown OS icon + return ( + + + + + + ); + } +}; + +// Helper for OS name display +const OSSelector = ({ os }: { os: string }) => { + return ( +
+ + + + {os || "Unknown"} +
+ ); +}; + +// Risk score badge with color coding (v4 palette) +const RiskScoreBadge = ({ score }: { score: number }) => { + let colorClass = "bg-gray-900/50 text-gray-400 border border-violet-500/10"; + + if (score >= 80) { + colorClass = "bg-red-500/20 text-red-300 border border-red-500/20"; + } else if (score >= 60) { + colorClass = "bg-orange-500/20 text-orange-300 border border-orange-500/20"; + } else if (score >= 40) { + colorClass = "bg-yellow-500/20 text-yellow-300 border border-yellow-500/20"; + } else if (score >= 20) { + colorClass = "bg-green-500/20 text-green-300 border border-green-500/20"; + } else if (score > 0) { + colorClass = "bg-blue-500/20 text-blue-300 border border-blue-500/20"; + } + + return ( + + {score} + + ); +}; + +// Cell renderer for the vulnerabilities column +function VulnerabilitiesCell({ host }: { host: EnvironmentTableData }) { + // Directly fetch and display vulnerability data using the host ID + return ( +
+ +
+ ); +} + +// Create our column helper with the EnvironmentTableData type +const columnHelper = createColumnHelper(); + +// Utility function to render a status badge +const StatusBadge = ({ status }: { status: string }) => { + const colorMap: Record< + string, + { bg: string; text: string; icon: JSX.Element } + > = { + online: { + bg: "bg-green-900/20", + text: "text-green-300", + icon: , + }, + offline: { + bg: "bg-red-900/20", + text: "text-red-300", + icon: , + }, + warning: { + bg: "bg-yellow-900/20", + text: "text-yellow-300", + icon: , + }, + secure: { + bg: "bg-green-900/20", + text: "text-green-300", + icon: , + }, + }; + + const statusKey = status?.toLowerCase() || "warning"; + const config = colorMap[statusKey] || colorMap.warning; + + // Ensure config is never undefined + if (!config) { + throw new Error("Config should never be undefined"); + } + + return ( +
+ {config.icon} + + {status?.charAt(0).toUpperCase() + status?.slice(1)} + +
+ ); +}; + +// Risk badge — uses shared component +import { RiskBadge } from "~/components/shared/SeverityBadge"; + +// Function to render vulnerability count with color coding +const VulnerabilityCount = ({ count }: { count: number }) => { + let colorClass = "text-green-400"; + + if (count > 50) { + colorClass = "text-red-400"; + } else if (count > 20) { + colorClass = "text-orange-400"; + } else if (count > 5) { + colorClass = "text-yellow-400"; + } + + return {count}; +}; + +// getRiskLevel — uses centralized util, extracts maxCvss from host vulnerabilities +import { getRiskLevel as getRiskLevelUtil } from "~/utils/riskScoreCalculator"; +const getRiskLevel = (host: EnvironmentTableData): string => { + const maxScore = + host.vulnerabilities && host.vulnerabilities.length > 0 + ? host.vulnerabilities.reduce((max, v) => Math.max(max, v.riskScore || 0), 0) + : undefined; + return getRiskLevelUtil(maxScore, host.vulnerabilityCount || 0); +}; + +// Severity indicator dot — shows the host's highest severity +const SeverityDot = ({ host }: { host: EnvironmentTableData }) => { + const vulns = host.vulnerabilities ?? []; + if (vulns.length === 0) return null; + + // Determine the highest severity present + const hasCritical = vulns.some( + (v) => v.severity?.toLowerCase() === "critical", + ); + const hasHigh = vulns.some((v) => v.severity?.toLowerCase() === "high"); + const hasMedium = vulns.some((v) => v.severity?.toLowerCase() === "medium"); + const hasLow = vulns.some((v) => v.severity?.toLowerCase() === "low"); + + let dotColor = "bg-blue-500"; // informational + if (hasCritical) dotColor = "bg-red-500"; + else if (hasHigh) dotColor = "bg-orange-500"; + else if (hasMedium) dotColor = "bg-amber-500"; + else if (hasLow) dotColor = "bg-green-500"; + + return ( + + ); +}; + +// Open Ports cell — renders count + top port badges +const OpenPortsCell = ({ host }: { host: EnvironmentTableData }) => { + const ports = host.ports ?? []; + if (ports.length === 0) { + return —; + } + + const top3 = ports.slice(0, 3); + const remaining = ports.length - top3.length; + + return ( +
+ {ports.length} +
+ {top3.map((p, i) => ( + + {p.number} + + ))} + {remaining > 0 && ( + +{remaining} + )} +
+
+ ); +}; + +// Define the columns +export const columns = [ + // Host column with hostname, IP, and severity indicator dot + columnHelper.accessor((row) => ({ hostname: row.hostname, ip: row.ip }), { + id: "host", + header: "Host", + cell: ({ getValue, row }) => { + const { hostname, ip } = getValue(); + return ( +
+ +
+
{hostname || ip}
+ {hostname &&
{ip}
} +
+
+ ); + }, + }), + + // OS column + columnHelper.accessor("os", { + header: "Operating System", + cell: ({ getValue }) => , + }), + + // Vulnerabilities column + columnHelper.accessor("vulnerabilityCount", { + id: "vulnerabilities", + header: "Vulnerabilities", + cell: ({ row }) => { + const host = row.original; + return ; + }, + }), + + // Open Ports column + columnHelper.accessor((row) => row.ports?.length ?? 0, { + id: "openPorts", + header: "Open Ports", + cell: ({ row }) => , + }), + + // Risk score column + columnHelper.accessor((row) => row, { + id: "riskScore", + header: "Risk Level", + cell: ({ getValue }) => { + const host = getValue(); + const riskLevel = getRiskLevel(host); + return ; + }, + }), + + // Tags column + columnHelper.accessor("tags", { + header: "Tags", + cell: ({ getValue }) => { + const tags = getValue() || []; + if (tags.length === 0) return null; + + return ( +
+ {tags.slice(0, 3).map((tag, i) => ( + + {tag} + + ))} + {tags.length > 3 && ( + + +{tags.length - 3} more + + )} +
+ ); + }, + }), + + // Status column (computed from host data) + columnHelper.accessor((row) => row, { + id: "status", + header: "Status", + cell: ({ getValue }) => { + const host = getValue(); + const status = determineHostStatus(host); + return ; + }, + }), + + // Actions column + columnHelper.accessor((row) => row, { + id: "actions", + header: "", + cell: ({ row }) => { + return ( +
+ { + console.log("Scanning host:", host.ip); + // Implement scan logic + }} + onTag={(host) => { + console.log("Managing tags for host:", host.ip); + // Implement tag management logic + }} + onDelete={(host) => { + console.log("Deleting host:", host.ip); + // Implement delete logic with confirmation + if ( + confirm( + `Are you sure you want to remove ${ + host.hostname || host.ip + } from the environment?`, + ) + ) { + // Delete logic here + } + }} + /> +
+ ); + }, + }), +]; + +// Helper function to determine host status - in a real app, this would use actual data +function determineHostStatus(host: EnvironmentTableData): string { + // This is a placeholder - in a real application you'd determine this based on actual data + if (!host) return "unknown"; + + // Example logic based on available data + if (host.vulnerabilityCount > 20) return "warning"; + if (host.vulnerabilityCount > 0) return "warning"; + + // Default to online if no vulnerabilities + return "online"; +} diff --git a/sirius-ui/src/components/ErrorBoundary.tsx b/sirius-ui/src/components/ErrorBoundary.tsx new file mode 100644 index 0000000..5f3c767 --- /dev/null +++ b/sirius-ui/src/components/ErrorBoundary.tsx @@ -0,0 +1,73 @@ +import React, { Component, ErrorInfo, ReactNode } from "react"; + +interface Props { + children: ReactNode; + fallback?: ReactNode; +} + +interface State { + hasError: boolean; + error?: Error; +} + +class ErrorBoundary extends Component { + public state: State = { + hasError: false, + }; + + public static getDerivedStateFromError(error: Error): State { + // Update state so the next render will show the fallback UI + return { hasError: true, error }; + } + + public componentDidCatch(error: Error, errorInfo: ErrorInfo) { + console.error("Error caught by boundary:", error, errorInfo); + } + + public render() { + if (this.state.hasError) { + return ( + this.props.fallback || ( +
+
+
+ + + +
+

+ Something went wrong +

+

+ An error occurred while loading this page. +

+ +
+
+ ) + ); + } + + return this.props.children; + } +} + +export default ErrorBoundary; diff --git a/sirius-ui/src/components/Header.tsx b/sirius-ui/src/components/Header.tsx new file mode 100755 index 0000000..2727545 --- /dev/null +++ b/sirius-ui/src/components/Header.tsx @@ -0,0 +1,248 @@ +import { useSession } from "next-auth/react"; +import { useEffect, useState } from "react"; +import SiriusIcon from "./icons/SiriusIcon"; +import Link from "next/link"; +import { useRouter } from "next/router"; +import { initializeTheme } from "~/utils/theme"; +import { handleSignOut } from "~/utils/auth"; + +import { + DropdownMenu, + DropdownMenuContent, + DropdownMenuItem, + DropdownMenuLabel, + DropdownMenuSeparator, + DropdownMenuTrigger, + DropdownMenuGroup, +} from "~/components/lib/ui/dropdown-menu"; +import { Switch } from "~/components/lib/ui/switch"; +import { + Moon, + Sun, + Settings, + Activity, + LogOut, + User, + ChevronRight, +} from "lucide-react"; + +interface HeaderProps { + title: string; +} + +interface AvatarProps { + onClick?: () => void; + className?: string; +} + +const Avatar: React.FC = ({ onClick, className }) => { + return ( +
+ + {/* Constellation-style user icon - clearer human form */} + + {/* Head - larger and more prominent */} + + + {/* Neck connection point */} + + + {/* Shoulders */} + + + + {/* Torso/waist */} + + + + {/* Legs/feet */} + + + + {/* Connection lines - stronger and more visible */} + + + {/* Subtle glow effect for the head */} + + +
+ ); +}; + +const Header: React.FC = ({ title }) => { + const [darkMode, setDarkMode] = useState(false); + const { data: sessionData } = useSession(); + + const handleLogout = () => { + void handleSignOut(); + }; + + useEffect(() => { + // Initialize theme on mount + const isDark = initializeTheme(); + setDarkMode(isDark); + }, []); + + const toggleDarkMode = () => { + const newDarkMode = !darkMode; + setDarkMode(newDarkMode); + document.documentElement.classList.toggle("dark", newDarkMode); + window.localStorage.setItem("darkMode", newDarkMode.toString()); + }; + + const handleMenu = () => { + console.log("Menu clicked"); + }; + + const UserMenu: React.FC = () => { + const { data: sessionData } = useSession(); + const router = useRouter(); + const [darkMode, setDarkMode] = useState(false); + + useEffect(() => { + const isDark = document.documentElement.classList.contains("dark"); + setDarkMode(isDark); + }, []); + + const toggleDarkMode = () => { + const newDarkMode = !darkMode; + setDarkMode(newDarkMode); + document.documentElement.classList.toggle("dark", newDarkMode); + window.localStorage.setItem("darkMode", newDarkMode.toString()); + }; + + return ( +
+ + + + + + + {/* User Info Section */} + +
+
+ +
+
+ + Logged in as + + + {sessionData?.user?.name || sessionData?.user?.id || "User"} + +
+
+ + + + + {/* Theme Toggle */} + +
+
+ {darkMode ? ( + + ) : ( + + )} + + {darkMode ? "Dark Mode" : "Light Mode"} + +
+ +
+ + + + + {/* Navigation Items */} + + void router.push("/settings")} + > + + Settings + + + + void router.push("/system-monitor")} + > + + System Monitor + + + + + + + {/* Sign Out */} + void handleSignOut()} + > + + Sign out + + + +
+ ); + }; + + return ( + + ); +}; + +export default Header; diff --git a/sirius-ui/src/components/HostRowActions.tsx b/sirius-ui/src/components/HostRowActions.tsx new file mode 100644 index 0000000..24d2657 --- /dev/null +++ b/sirius-ui/src/components/HostRowActions.tsx @@ -0,0 +1,130 @@ +import React, { useState, useRef, useEffect } from "react"; +import { + ChevronDown, + ExternalLink, + MoreHorizontal, + RefreshCw, + Shield, + Tag, + Trash2, +} from "lucide-react"; +import { cn } from "~/components/lib/utils"; +import { type EnvironmentTableData } from "~/server/api/routers/host"; + +interface HostRowActionsProps { + host: EnvironmentTableData; + onScan?: (host: EnvironmentTableData) => void; + onTag?: (host: EnvironmentTableData) => void; + onDelete?: (host: EnvironmentTableData) => void; +} + +export const HostRowActions: React.FC = ({ + host, + onScan, + onTag, + onDelete, +}) => { + const [isOpen, setIsOpen] = useState(false); + const menuRef = useRef(null); + + // Close the menu when clicking outside + useEffect(() => { + const handleClickOutside = (event: MouseEvent) => { + if (menuRef.current && !menuRef.current.contains(event.target as Node)) { + setIsOpen(false); + } + }; + + document.addEventListener("mousedown", handleClickOutside); + return () => { + document.removeEventListener("mousedown", handleClickOutside); + }; + }, []); + + const handleToggle = (e: React.MouseEvent) => { + e.stopPropagation(); + setIsOpen(!isOpen); + }; + + const handleAction = ( + e: React.MouseEvent, + action: (host: EnvironmentTableData) => void + ) => { + e.stopPropagation(); + action(host); + setIsOpen(false); + }; + + return ( +
+ + + {isOpen && ( +
+
+
{host.hostname || "Unknown host"}
+
{host.ip}
+
+ + {onScan && ( + + )} + + + + + + {onTag && ( + + )} + + {onDelete && ( + + )} +
+ )} +
+ ); +}; diff --git a/sirius-ui/src/components/Layout.tsx b/sirius-ui/src/components/Layout.tsx new file mode 100755 index 0000000..953b9a4 --- /dev/null +++ b/sirius-ui/src/components/Layout.tsx @@ -0,0 +1,93 @@ +// components/Layout.tsx +import React from "react"; +import { useSession } from "next-auth/react"; +import { useRouter } from "next/router"; +import { useEffect } from "react"; +import Head from "next/head"; +import Header from "./Header"; +import Sidebar from "./Sidebar"; +import { Toaster } from "~/components/lib/ui/sonner"; +import { debugLog, debugRouting } from "~/utils/debug"; +import { ActiveConstellationV2Loader } from "~/components/loaders"; + +interface LayoutProps { + children: React.ReactNode; + title?: string; +} + +const Layout = ({ children, title = "Sirius Scan" }: LayoutProps) => { + const { data: session, status } = useSession(); + const router = useRouter(); + + // Use useEffect to handle redirects to avoid render loops + useEffect(() => { + if (status === "loading") { + debugLog("Layout", "Session loading", router.pathname); + return; // Wait for session to load + } + + // Only redirect if user is not authenticated and not on the home page + if (!session?.user && router.pathname !== "/") { + debugRouting(router.pathname, "/", "Unauthenticated user redirect"); + void router.replace("/"); + } + }, [session, status, router]); + + // Show loading state while session is loading or while redirecting + if (status === "loading") { + debugLog("Layout", "Rendering loading state - session loading"); + return ( +
+ +
+ ); + } + + // Show loading state while redirecting unauthenticated users + if (!session?.user && router.pathname !== "/") { + debugLog( + "Layout", + "Rendering loading state - redirecting unauthenticated user" + ); + return ( +
+ +
+ ); + } + + debugLog("Layout", "Rendering main layout", { + pathname: router.pathname, + user: !!session?.user, + }); + + return ( +
+ + +
+
+ + + {title} + + + + +
+ {/* Hexagonal gradient background */} +
+ + {/* Main content */} +
+
{children}
+
+
+
+ + +
+ ); +}; + +export default Layout; diff --git a/sirius-ui/src/components/LogDashboard.tsx b/sirius-ui/src/components/LogDashboard.tsx new file mode 100644 index 0000000..02c748c --- /dev/null +++ b/sirius-ui/src/components/LogDashboard.tsx @@ -0,0 +1,370 @@ +import React, { useState, useMemo } from 'react'; +import { + Table, + TableBody, + TableCell, + TableHead, + TableHeader, + TableRow, +} from '~/components/lib/ui/table'; +import { Badge } from '~/components/lib/ui/badge'; +import { Button } from '~/components/lib/ui/button'; +import { Input } from '~/components/lib/ui/input'; +import { + Select, + SelectContent, + SelectItem, + SelectTrigger, + SelectValue, +} from '~/components/lib/ui/select'; +import { RefreshCw, Search, Filter, AlertTriangle, Info, Bug, AlertCircle } from 'lucide-react'; +import { logService, LogEntry, LogRetrievalRequest, LogStatsResponse } from '~/services/logService'; +import { api } from '~/utils/api'; + +interface LogDashboardProps { + className?: string; +} + +export const LogDashboard: React.FC = ({ className }) => { + const [offset, setOffset] = useState(0); + const [limit] = useState(50); + + // Filters + const [serviceFilter, setServiceFilter] = useState(''); + const [levelFilter, setLevelFilter] = useState(''); + const [searchQuery, setSearchQuery] = useState(''); + + // Get unique services and levels from logs + const availableServices = useMemo(() => { + const services = new Set(); + logs.forEach(log => services.add(log.service)); + return Array.from(services).sort(); + }, [logs]); + + const availableLevels = useMemo(() => { + const levels = new Set(); + logs.forEach(log => levels.add(log.level)); + return Array.from(levels).sort(); + }, [logs]); + + // Build request object + const request: LogRetrievalRequest = useMemo(() => { + const req: LogRetrievalRequest = { + limit, + offset, + }; + + if (serviceFilter) req.service = serviceFilter; + if (levelFilter) req.level = levelFilter; + if (searchQuery.trim()) req.search = searchQuery.trim(); + + return req; + }, [serviceFilter, levelFilter, searchQuery, limit, offset]); + + const trpcListInput = useMemo( + () => ({ + limit: request.limit, + offset: request.offset, + service: request.service, + level: request.level, + subcomponent: request.subcomponent, + search: request.search, + }), + [request], + ); + + const { + data: logsData, + isLoading: logsLoading, + error: logsQueryError, + refetch: refetchLogs, + } = api.logs.list.useQuery(trpcListInput, { refetchInterval: 10000 }); + + const { + data: stats, + refetch: refetchStats, + } = api.logs.stats.useQuery(undefined, { refetchInterval: 30000 }); + + const logs = (logsData?.logs ?? []) as LogEntry[]; + const total = logsData?.total ?? 0; + const loading = logsLoading; + const error = logsQueryError?.message ?? null; + const statsTyped = stats as LogStatsResponse | null | undefined; + + // Handle pagination + const handlePreviousPage = () => { + if (offset > 0) { + setOffset(Math.max(0, offset - limit)); + } + }; + + const handleNextPage = () => { + if (offset + limit < total) { + setOffset(offset + limit); + } + }; + + // Handle refresh + const handleRefresh = () => { + void refetchLogs(); + void refetchStats(); + }; + + // Clear filters + const clearFilters = () => { + setServiceFilter(''); + setLevelFilter(''); + setSearchQuery(''); + setOffset(0); + }; + + // Get log level icon + const getLogLevelIcon = (level: string) => { + switch (level) { + case 'error': + return ; + case 'warn': + return ; + case 'info': + return ; + case 'debug': + return ; + default: + return ; + } + }; + + return ( +
+ {/* Header */} +
+
+

System Logs

+

+ Centralized logging system for all Sirius components +

+
+ +
+ + {/* Stats Cards */} + {statsTyped && ( +
+
+
+

Total Logs

+
+
+
{statsTyped.total_logs}
+
+
+ +
+
+

Services

+
+
+
{Object.keys(statsTyped.service_stats).length}
+
+
+ +
+
+

Errors

+
+
+
+ {statsTyped.level_stats?.error || 0} +
+
+
+ +
+
+

Warnings

+
+
+
+ {statsTyped.level_stats?.warn || 0} +
+
+
+
+ )} + + {/* Filters */} +
+
+

+ + Filters +

+
+
+
+
+ + +
+ +
+ + +
+ +
+ +
+ + setSearchQuery(e.target.value)} + className="pl-8" + /> +
+
+ +
+ + +
+
+
+
+ + {/* Error Alert */} + {error && ( +
+
+ + Error +
+

{error}

+
+ )} + + {/* Logs Table */} +
+
+

Log Entries

+

+ Showing {logs.length} of {total} logs + {loading && ' (Loading...)'} +

+
+
+
+ + + + Timestamp + Level + Service + Component + Message + + + + {logs.map((log) => ( + + +
{logService.formatTimestamp(log.timestamp)}
+
+ {logService.formatRelativeTime(log.timestamp)} +
+ + + + {getLogLevelIcon(log.level)} + {log.level.toUpperCase()} + + + + {log.service} + + + {log.subcomponent} + + +
+ {log.message} +
+ {log.metadata && Object.keys(log.metadata).length > 0 && ( +
+ {Object.entries(log.metadata).slice(0, 2).map(([key, value]) => ( + + {key}: {String(value)} + + ))} + {Object.keys(log.metadata).length > 2 && '...'} +
+ )} + + + ))} + +
+
+ + {/* Pagination */} +
+
+ Showing {offset + 1} to {Math.min(offset + limit, total)} of {total} entries +
+
+ + +
+
+
+
+
+ ); +}; diff --git a/sirius-ui/src/components/PageWrapper.tsx b/sirius-ui/src/components/PageWrapper.tsx new file mode 100644 index 0000000..e75be3a --- /dev/null +++ b/sirius-ui/src/components/PageWrapper.tsx @@ -0,0 +1,52 @@ +import React, { useState, useEffect, ReactNode } from "react"; +import { debugLog } from "~/utils/debug"; +import { ActiveConstellationV2Loader } from "~/components/loaders"; + +interface PageWrapperProps { + children: ReactNode; + pageName: string; + delay?: number; +} + +/** + * PageWrapper component that delays child rendering to prevent API calls + * from blocking navigation during route changes + */ +export const PageWrapper: React.FC = ({ + children, + pageName, + delay = 50, +}) => { + const [isReady, setIsReady] = useState(false); + + useEffect(() => { + debugLog("PageWrapper", `Starting initialization for ${pageName}`); + + if (delay === 0) { + setIsReady(true); + return; + } + + const timer = setTimeout(() => { + debugLog("PageWrapper", `Initialization complete for ${pageName}`); + setIsReady(true); + }, delay); + + return () => { + clearTimeout(timer); + debugLog("PageWrapper", `Cleanup for ${pageName}`); + }; + }, [pageName, delay]); + + if (!isReady) { + return ( +
+ +
+ ); + } + + return <>{children}; +}; + +export default PageWrapper; diff --git a/sirius-ui/src/components/PerformanceDashboard.tsx b/sirius-ui/src/components/PerformanceDashboard.tsx new file mode 100644 index 0000000..3d21465 --- /dev/null +++ b/sirius-ui/src/components/PerformanceDashboard.tsx @@ -0,0 +1,565 @@ +import React, { useState, useEffect } from "react"; +import { + Card, + CardContent, + CardDescription, + CardHeader, + CardTitle, +} from "~/components/lib/ui/card"; +import { + Table, + TableBody, + TableCell, + TableHead, + TableHeader, + TableRow, +} from "~/components/lib/ui/table"; +import { Badge } from "~/components/lib/ui/badge"; +import { Button } from "~/components/lib/ui/button"; +import { + Select, + SelectContent, + SelectItem, + SelectTrigger, + SelectValue, +} from "~/components/lib/ui/select"; +import { + RefreshCw, + TrendingUp, + Clock, + AlertTriangle, + Activity, +} from "lucide-react"; + +interface PerformanceMetric { + id: string; + timestamp: string; + service: string; + endpoint: string; + method: string; + duration_ms: number; + status_code: number; + response_size: number; + request_id?: string; +} + +interface PerformanceSummary { + total_requests: number; + average_response_ms: number; + min_response_ms: number; + max_response_ms: number; + error_rate: number; + requests_per_minute: number; + top_endpoints: EndpointStats[]; + service_stats: ServiceStats[]; +} + +interface EndpointStats { + endpoint: string; + method: string; + request_count: number; + average_response_ms: number; + error_count: number; + error_rate: number; +} + +interface ServiceStats { + service: string; + request_count: number; + average_response_ms: number; + error_count: number; + error_rate: number; +} + +interface PerformanceDashboardProps { + className?: string; +} + +export const PerformanceDashboard: React.FC = ({ + className, +}) => { + const [metrics, setMetrics] = useState([]); + const [summary, setSummary] = useState(null); + const [loading, setLoading] = useState(true); + const [error, setError] = useState(null); + const [timeRange, setTimeRange] = useState("1h"); + + // Mock data for now + const generateMockData = (): { + metrics: PerformanceMetric[]; + summary: PerformanceSummary; + } => { + const now = new Date(); + const mockMetrics: PerformanceMetric[] = [ + { + id: "perf_001", + timestamp: new Date(now.getTime() - 1 * 60 * 1000).toISOString(), + service: "sirius-api", + endpoint: "/api/v1/system/health", + method: "GET", + duration_ms: 15, + status_code: 200, + response_size: 1024, + request_id: "req_001", + }, + { + id: "perf_002", + timestamp: new Date(now.getTime() - 2 * 60 * 1000).toISOString(), + service: "sirius-api", + endpoint: "/api/v1/logs/stats", + method: "GET", + duration_ms: 8, + status_code: 200, + response_size: 512, + request_id: "req_002", + }, + { + id: "perf_003", + timestamp: new Date(now.getTime() - 3 * 60 * 1000).toISOString(), + service: "sirius-api", + endpoint: "/api/v1/logs", + method: "POST", + duration_ms: 25, + status_code: 201, + response_size: 256, + request_id: "req_003", + }, + { + id: "perf_004", + timestamp: new Date(now.getTime() - 4 * 60 * 1000).toISOString(), + service: "sirius-api", + endpoint: "/api/v1/hosts", + method: "GET", + duration_ms: 45, + status_code: 200, + response_size: 2048, + request_id: "req_004", + }, + { + id: "perf_005", + timestamp: new Date(now.getTime() - 5 * 60 * 1000).toISOString(), + service: "sirius-api", + endpoint: "/api/v1/vulnerabilities", + method: "GET", + duration_ms: 120, + status_code: 200, + response_size: 4096, + request_id: "req_005", + }, + { + id: "perf_006", + timestamp: new Date(now.getTime() - 6 * 60 * 1000).toISOString(), + service: "sirius-api", + endpoint: "/api/v1/hosts/invalid", + method: "GET", + duration_ms: 5, + status_code: 404, + response_size: 128, + request_id: "req_006", + }, + ]; + + const mockSummary: PerformanceSummary = { + total_requests: 6, + average_response_ms: 36.3, + min_response_ms: 5, + max_response_ms: 120, + error_rate: 16.7, + requests_per_minute: 1.0, + top_endpoints: [ + { + endpoint: "/api/v1/system/health", + method: "GET", + request_count: 1, + average_response_ms: 15, + error_count: 0, + error_rate: 0, + }, + { + endpoint: "/api/v1/logs/stats", + method: "GET", + request_count: 1, + average_response_ms: 8, + error_count: 0, + error_rate: 0, + }, + { + endpoint: "/api/v1/hosts/invalid", + method: "GET", + request_count: 1, + average_response_ms: 5, + error_count: 1, + error_rate: 100, + }, + ], + service_stats: [ + { + service: "sirius-api", + request_count: 6, + average_response_ms: 36.3, + error_count: 1, + error_rate: 16.7, + }, + ], + }; + + return { metrics: mockMetrics, summary: mockSummary }; + }; + + const loadPerformanceData = async () => { + try { + setLoading(true); + setError(null); + + // Fetch real performance data from API + const response = await fetch( + `${ + process.env.NEXT_PUBLIC_SIRIUS_API_URL || "http://localhost:9001" + }/api/v1/performance/metrics` + ); + if (!response.ok) { + throw new Error(`HTTP error! status: ${response.status}`); + } + const data = await response.json(); + + // Transform API response to match our interface + const transformedMetrics: PerformanceMetric[] = data.metrics.map( + (metric: any, index: number) => ({ + id: `perf_${index}`, + timestamp: metric.timestamp, + service: "sirius-api", + endpoint: metric.endpoint, + method: metric.method, + duration_ms: metric.duration_ms, + status_code: metric.status_code, + response_size: 1024, // Default size since API doesn't provide this yet + request_id: `req_${index}`, + }) + ); + + const transformedSummary: PerformanceSummary = { + total_requests: data.summary.total_requests, + average_response_ms: data.summary.average_response_ms, + min_response_ms: Math.min( + ...data.metrics.map((m: any) => m.duration_ms) + ), + max_response_ms: Math.max( + ...data.metrics.map((m: any) => m.duration_ms) + ), + error_rate: data.summary.error_rate, + requests_per_minute: data.summary.total_requests, + top_endpoints: data.metrics.map((metric: any) => ({ + endpoint: metric.endpoint, + method: metric.method, + request_count: 1, + average_response_ms: metric.duration_ms, + error_count: metric.status_code >= 400 ? 1 : 0, + error_rate: metric.status_code >= 400 ? 1 : 0, + })), + service_stats: [ + { + service: "sirius-api", + request_count: data.summary.total_requests, + average_response_ms: data.summary.average_response_ms, + error_count: 0, + error_rate: data.summary.error_rate, + }, + ], + }; + + setMetrics(transformedMetrics); + setSummary(transformedSummary); + } catch (err) { + setError( + err instanceof Error ? err.message : "Failed to load performance data" + ); + console.error("Failed to load performance data:", err); + + // Fallback to mock data on error + const { metrics: mockMetrics, summary: mockSummary } = generateMockData(); + setMetrics(mockMetrics); + setSummary(mockSummary); + } finally { + setLoading(false); + } + }; + + useEffect(() => { + loadPerformanceData(); + }, [timeRange]); + + const handleRefresh = () => { + loadPerformanceData(); + }; + + const getStatusBadgeVariant = (statusCode: number) => { + if (statusCode >= 200 && statusCode < 300) return "default"; + if (statusCode >= 300 && statusCode < 400) return "secondary"; + if (statusCode >= 400 && statusCode < 500) return "outline"; + return "destructive"; + }; + + const getDurationColor = (duration: number) => { + if (duration < 50) return "text-green-500"; + if (duration < 100) return "text-yellow-500"; + return "text-red-500"; + }; + + const formatTimestamp = (timestamp: string) => { + try { + const date = new Date(timestamp); + return date.toLocaleString(); + } catch { + return timestamp; + } + }; + + const formatRelativeTime = (timestamp: string) => { + try { + const date = new Date(timestamp); + const now = new Date(); + const diffMs = now.getTime() - date.getTime(); + const diffMinutes = Math.floor(diffMs / (1000 * 60)); + + if (diffMinutes < 1) return "Just now"; + if (diffMinutes === 1) return "1 minute ago"; + return `${diffMinutes} minutes ago`; + } catch { + return "Unknown"; + } + }; + + return ( +
+ {/* Header */} +
+
+

+ Performance Metrics +

+

+ Real-time performance monitoring and analytics +

+
+
+ + +
+
+ + {/* Error Alert */} + {error && ( +
+
+ + Error +
+

{error}

+
+ )} + + {/* Summary Cards */} + {summary && ( +
+ + + + Total Requests + + + + +
{summary.total_requests}
+

+ {summary.requests_per_minute.toFixed(1)} req/min +

+ + + + + + + Avg Response Time + + + + +
+ {summary.average_response_ms.toFixed(1)}ms +
+

+ {summary.min_response_ms}ms - {summary.max_response_ms}ms +

+ + + + + + Error Rate + + + +
5 ? "text-red-500" : "text-green-500" + }`} + > + {summary.error_rate.toFixed(1)}% +
+

+ {summary.error_rate > 5 + ? "High error rate" + : "Normal error rate"} +

+ + + + + + Performance + + + +
+ {summary.average_response_ms < 100 ? "Good" : "Slow"} +
+

+ {summary.average_response_ms < 100 + ? "Fast responses" + : "Needs optimization"} +

+ + +
+ )} + + {/* Top Endpoints */} + {summary && summary.top_endpoints.length > 0 && ( + + + Top Endpoints + + Most frequently accessed endpoints with performance metrics + + + +
+ {summary.top_endpoints.map((endpoint, index) => ( +
+
+ {endpoint.method} + + {endpoint.endpoint} + +
+
+ + {endpoint.request_count} requests + + + {endpoint.average_response_ms.toFixed(1)}ms avg + + {endpoint.error_count > 0 && ( + + {endpoint.error_rate.toFixed(1)}% errors + + )} +
+
+ ))} +
+ + + )} + + {/* Performance Metrics Table */} + + + Recent Performance Metrics + + Detailed performance data for recent requests + + + +
+ + + + Timestamp + Service + Endpoint + Method + Duration + Status + Size + + + + {metrics.map((metric) => ( + + +
{formatTimestamp(metric.timestamp)}
+
+ {formatRelativeTime(metric.timestamp)} +
+ + + {metric.service} + + + {metric.endpoint} + + + {metric.method} + + + + {metric.duration_ms}ms + + + + + {metric.status_code} + + + + {metric.response_size} bytes + + + ))} + +
+
+ + +
+ ); +}; diff --git a/sirius-ui/src/components/ScanBar.tsx b/sirius-ui/src/components/ScanBar.tsx new file mode 100755 index 0000000..28e018f --- /dev/null +++ b/sirius-ui/src/components/ScanBar.tsx @@ -0,0 +1,171 @@ +import { useState, useEffect, useRef } from "react"; +import { SEVERITY_COLORS } from "~/utils/severityTheme"; + +interface ScanBarProps { + isScanning: boolean; + hasRun?: boolean; // Optional prop to indicate if a scan has completed + isCancelling?: boolean; // Optional prop to indicate scan is being cancelled + wasCancelled?: boolean; // Optional prop to indicate scan was cancelled + scanStartTime?: string | null; // Persisted scan start from backend/store + scanEndTime?: string | null; // Optional persisted end timestamp +} + +export const ScanBar: React.FC = ({ + isScanning, + hasRun = false, + isCancelling = false, + wasCancelled = false, + scanStartTime, + scanEndTime, +}) => { + const [darkMode, setDarkMode] = useState(false); + const [elapsedTime, setElapsedTime] = useState(0); + const finalTimeRef = useRef(0); + + const parseIsoMs = (value?: string | null): number | null => { + if (!value) return null; + const ms = Date.parse(value); + return Number.isFinite(ms) ? ms : null; + }; + + useEffect(() => { + let interval: NodeJS.Timeout; + + if (isScanning || isCancelling) { + // Use persisted scan start when available so rerenders/remounts don't reset visible time. + const scanStartMs = parseIsoMs(scanStartTime); + const localStartMs = Date.now(); + const computeElapsedSeconds = () => { + const base = scanStartMs ?? localStartMs; + return Math.max(0, Math.floor((Date.now() - base) / 1000)); + }; + const initialElapsed = computeElapsedSeconds(); + setElapsedTime(initialElapsed); + interval = setInterval(() => { + const nextElapsed = computeElapsedSeconds(); + setElapsedTime(nextElapsed); + }, 1000); + } else { + const scanStartMs = parseIsoMs(scanStartTime); + const scanEndMs = parseIsoMs(scanEndTime); + + // Prefer persisted timestamps to derive final duration. + if ((hasRun || wasCancelled) && scanStartMs !== null) { + const resolvedEndMs = scanEndMs ?? Date.now(); + const finalElapsed = Math.max( + 0, + Math.floor((resolvedEndMs - scanStartMs) / 1000) + ); + finalTimeRef.current = finalElapsed; + setElapsedTime(finalElapsed); + } else if (elapsedTime > 0) { + finalTimeRef.current = elapsedTime; + } + // Only reset elapsed time if we're not preserving the final time + if (!hasRun && !wasCancelled) { + setElapsedTime(0); + } + } + + return () => { + if (interval) clearInterval(interval); + }; + }, [isScanning, isCancelling, hasRun, wasCancelled, scanStartTime, scanEndTime]); + + // Format elapsed time as mm:ss + const formatTime = (seconds: number): string => { + const mins = Math.floor(seconds / 60); + const secs = seconds % 60; + return `${mins.toString().padStart(2, "0")}:${secs + .toString() + .padStart(2, "0")}`; + }; + + // Define gradient colors based on state + const getGradientColors = () => { + if (isCancelling) { + return "linear-gradient(90deg, #f59e0b, #d97706)"; // Orange/amber for cancelling + } + if (wasCancelled) { + return `linear-gradient(90deg, ${SEVERITY_COLORS.critical.hex}, ${SEVERITY_COLORS.critical.hex})`; // Red for cancelled + } + return darkMode + ? "linear-gradient(90deg, #2c3e50, #4ca1af)" + : "linear-gradient(90deg, #38bdf8, #0369a1)"; + }; + + const gradientColors = getGradientColors(); + + const getStatusText = () => { + if (isCancelling) { + return `Stopping Scan... (${formatTime(elapsedTime)})`; + } + if (wasCancelled) { + return `Scan Cancelled - Time: ${formatTime(finalTimeRef.current)}`; + } + if (isScanning) { + return `Scan Time: ${formatTime(elapsedTime)}`; + } + if (hasRun) { + return `Scan Complete - Total Time: ${formatTime(finalTimeRef.current)}`; + } + return "Ready to Scan"; + }; + + const isActive = isScanning || isCancelling; + + return ( +
+
+ {getStatusText()} +
+
+
+
+
+
+ {isActive ? ( + + + In Progress + + ) : wasCancelled ? ( + + + Cancelled + + ) : hasRun ? ( + + + Complete + + ) : ( + + + Idle + + )} +
+
+ ); +}; diff --git a/sirius-ui/src/components/ScannerVulnerabilityColumns.tsx b/sirius-ui/src/components/ScannerVulnerabilityColumns.tsx new file mode 100644 index 0000000..d6fa053 --- /dev/null +++ b/sirius-ui/src/components/ScannerVulnerabilityColumns.tsx @@ -0,0 +1,102 @@ +import React from "react"; +import { type ColumnDef } from "@tanstack/react-table"; +import { type VulnerabilityTableData } from "~/types/scanTypes"; +import { cn } from "~/components/lib/utils"; +import { + getSeverityBadgeColors, + getSeverityLabel, + getSeverityPriority, + getCVSSBarColor, +} from "~/utils/riskScoreCalculator"; +import { SourceIcon } from "~/components/shared/SourceIcon"; + +// SeverityBadge — uses shared component +import { SeverityBadge } from "~/components/shared/SeverityBadge"; +export { SeverityBadge }; + +// Re-export getSeverityPriority for any external consumers +export { getSeverityPriority } from "~/utils/riskScoreCalculator"; + +// Column definitions for the scanner vulnerability table +export const scannerVulnerabilityColumns: ColumnDef< + VulnerabilityTableData, + any +>[] = [ + { + accessorKey: "cve", + header: "CVE ID", + cell: ({ row }) => ( +
+ {row.original.cve || "N/A"} +
+ ), + size: 140, + }, + { + accessorKey: "severity", + header: "Severity", + cell: ({ row }) => , + size: 100, + sortingFn: (rowA, rowB, columnId) => { + const severityA = getSeverityPriority(rowA.original.severity); + const severityB = getSeverityPriority(rowB.original.severity); + return severityA - severityB; // Default sort high-to-low + }, + }, + { + accessorKey: "description", + header: "Description", + cell: ({ row }) => ( +
+ {row.original.description || "No description available"} +
+ ), + size: 400, + }, + { + accessorKey: "cvss", + header: "CVSS", + cell: ({ row }) => { + // Ensure cvss is a number and handle potential NaN values + const rawScore = parseFloat(String(row.original.cvss || 0)); + const score = isNaN(rawScore) ? 0 : rawScore; + const color = getCVSSBarColor(score); + + return ( +
+
{score.toFixed(1)}
+
+
+
+
+ ); + }, + size: 100, + sortingFn: (rowA, rowB, columnId) => { + const scoreA = parseFloat(String(rowA.original.cvss || 0)) || 0; + const scoreB = parseFloat(String(rowB.original.cvss || 0)) || 0; + return scoreB - scoreA; // Default sort high-to-low + }, + }, + { + accessorKey: "count", + header: "Affected Hosts", + cell: ({ row }) => ( +
{row.original.count || 0}
+ ), + size: 120, + }, + { + accessorKey: "scan_source", + header: "Source", + cell: ({ row }) => { + const source = row.original.scan_source; + if (!source) return null; + return ; + }, + size: 90, + }, +]; diff --git a/sirius-ui/src/components/SeverityBadge.tsx b/sirius-ui/src/components/SeverityBadge.tsx new file mode 100755 index 0000000..11366bb --- /dev/null +++ b/sirius-ui/src/components/SeverityBadge.tsx @@ -0,0 +1,5 @@ +/** + * @deprecated — Import from "~/components/shared/SeverityBadge" instead. + * This file re-exports for backward compatibility during the v0.4 migration. + */ +export { SeverityBadge, getScannerRiskColors, RiskBadge, SeverityFilterPill } from "~/components/shared/SeverityBadge"; diff --git a/sirius-ui/src/components/Sidebar.tsx b/sirius-ui/src/components/Sidebar.tsx new file mode 100644 index 0000000..7448a86 --- /dev/null +++ b/sirius-ui/src/components/Sidebar.tsx @@ -0,0 +1,208 @@ +import React, { useState, useEffect } from "react"; +import Link from "next/link"; +import { useRouter } from "next/router"; +import * as Tooltip from "@radix-ui/react-tooltip"; +import VulnerabilityIcon from "./icons/VulnerabilityIcon"; +import EnvironmentIcon from "./icons/EnvironmentIcon"; +import ScanIcon from "./icons/ScanIcon"; +import AgentIcon from "./icons/AgentIcon"; +import SiriusIcon from "./icons/SiriusIcon"; + +const navigationItems = [ + { + name: "Scanner", + href: "/scanner", + matchPaths: ["/scanner"], + icon: ScanIcon, + }, + { + name: "Vulnerabilities", + href: "/vulnerabilities", + matchPaths: ["/vulnerabilities", "/vulnerability"], + icon: VulnerabilityIcon, + }, + { + name: "Environment", + href: "/environment", + matchPaths: ["/environment", "/host"], + icon: EnvironmentIcon, + }, + { + name: "Terminal", + href: "/terminal", + matchPaths: ["/terminal"], + icon: AgentIcon, + }, +]; + +const Sidebar = () => { + const router = useRouter(); + const [mounted, setMounted] = useState(false); + + useEffect(() => { + setMounted(true); + }, []); + + return ( + + + + ); +}; + +export default Sidebar; diff --git a/sirius-ui/src/components/SourceCoverageDashboard.tsx b/sirius-ui/src/components/SourceCoverageDashboard.tsx new file mode 100644 index 0000000..720827a --- /dev/null +++ b/sirius-ui/src/components/SourceCoverageDashboard.tsx @@ -0,0 +1,495 @@ +"use client"; + +import React, { useState, useEffect, useMemo } from "react"; +import { cn } from "~/components/lib/utils"; +import { getSourceColor } from "~/components/shared/SourceBadge"; +import { + Activity, + Shield, + Clock, + TrendingUp, + AlertTriangle, + CheckCircle, + BarChart3, + PieChart, + Radar, + RefreshCw, +} from "lucide-react"; +import { Button } from "~/components/lib/ui/button"; +import { type SourceCoverageStats } from "~/types/scanTypes"; +import { timeAgo, getConfidenceColor } from "~/utils/formatters"; + +interface SourceCoverageDashboardProps { + className?: string; + refreshInterval?: number; // in milliseconds +} + +interface CoverageMetrics { + totalHosts: number; + totalVulnerabilities: number; + totalPorts: number; + sourceCount: number; + averageConfidence: number; + lastScanTime: Date | null; + coverageGaps: string[]; + reliabilityScore: number; +} + +export const SourceCoverageDashboard: React.FC< + SourceCoverageDashboardProps +> = ({ + className, + refreshInterval = 30000, // 30 seconds default +}) => { + const [coverageStats, setCoverageStats] = useState([]); + const [loading, setLoading] = useState(true); + const [error, setError] = useState(null); + const [lastRefresh, setLastRefresh] = useState(new Date()); + + // Fetch coverage statistics + const fetchCoverageStats = async () => { + try { + setLoading(true); + setError(null); + + const response = await fetch("/api/host/source-coverage"); + if (!response.ok) { + throw new Error(`HTTP error! status: ${response.status}`); + } + + const data = await response.json(); + setCoverageStats(data.source_coverage_stats || []); + setLastRefresh(new Date()); + } catch (err) { + setError( + err instanceof Error + ? err.message + : "Failed to fetch coverage statistics" + ); + console.error("Error fetching coverage stats:", err); + } finally { + setLoading(false); + } + }; + + // Initial load and refresh interval + useEffect(() => { + fetchCoverageStats(); + + if (refreshInterval > 0) { + const interval = setInterval(fetchCoverageStats, refreshInterval); + return () => clearInterval(interval); + } + }, [refreshInterval]); + + // Calculate overall metrics + const metrics = useMemo((): CoverageMetrics => { + if (!coverageStats.length) { + return { + totalHosts: 0, + totalVulnerabilities: 0, + totalPorts: 0, + sourceCount: 0, + averageConfidence: 0, + lastScanTime: null, + coverageGaps: [], + reliabilityScore: 0, + }; + } + + const totalHosts = Math.max(...coverageStats.map((s) => s.hosts_scanned)); + const totalVulnerabilities = coverageStats.reduce( + (sum, s) => sum + s.vulnerabilities_found, + 0 + ); + const totalPorts = coverageStats.reduce( + (sum, s) => sum + s.ports_discovered, + 0 + ); + const sourceCount = coverageStats.length; + + const averageConfidence = + coverageStats.reduce((sum, s) => sum + s.average_confidence, 0) / + sourceCount; + + const lastScanTime = coverageStats.reduce((latest, s) => { + const scanTime = new Date(s.last_scan_time); + return !latest || scanTime > latest ? scanTime : latest; + }, null as Date | null); + + // Identify coverage gaps (sources with low host coverage) + const coverageGaps = coverageStats + .filter((s) => s.hosts_scanned < totalHosts * 0.8) // Less than 80% coverage + .map((s) => s.source); + + // Calculate reliability score based on confidence and coverage + const reliabilityScore = + coverageStats.reduce((sum, s) => { + const coverageRatio = s.hosts_scanned / totalHosts; + const reliabilityFactor = s.average_confidence * coverageRatio; + return sum + reliabilityFactor; + }, 0) / sourceCount; + + return { + totalHosts, + totalVulnerabilities, + totalPorts, + sourceCount, + averageConfidence, + lastScanTime, + coverageGaps, + reliabilityScore, + }; + }, [coverageStats]); + + // Use shared getSourceColor("solid") + " text-white" for dashboard elements + const getDashboardSourceColor = (source: string) => + getSourceColor(source, "solid") + " text-white"; + + if (loading && !coverageStats.length) { + return ( +
+
+ +

+ Loading coverage statistics... +

+
+
+ ); + } + + if (error) { + return ( +
+
+ +

{error}

+ +
+
+ ); + } + + return ( +
+ {/* Dashboard Header */} +
+
+ +

+ Source Coverage Dashboard +

+
+
+
+ Last updated: {timeAgo(lastRefresh)} +
+ +
+
+ + {/* Overview Metrics */} +
+
+
+
+

+ Total Sources +

+

+ {metrics.sourceCount} +

+
+ +
+
+ +
+
+
+

+ Hosts Covered +

+

+ {metrics.totalHosts} +

+
+ +
+
+ +
+
+
+

+ Avg Confidence +

+

+ {(metrics.averageConfidence * 100).toFixed(0)}% +

+
+ +
+
+ +
+
+
+

+ Reliability Score +

+

+ {(metrics.reliabilityScore * 100).toFixed(0)}% +

+
+ +
+
+
+ + {/* Coverage Gaps Alert */} + {metrics.coverageGaps.length > 0 && ( +
+
+ +
+

+ Coverage Gaps Detected +

+

+ The following sources have incomplete host coverage:{" "} + {metrics.coverageGaps.join(", ")} +

+
+
+
+ )} + + {/* Source Details */} +
+
+

+ Source Performance +

+
+
+
+ {coverageStats.map((source) => ( +
+
+
+ {source.source} +
+
+
+ + Hosts: + + + {source.hosts_scanned} + +
+
+ + Vulns: + + + {source.vulnerabilities_found} + +
+
+ + Ports: + + + {source.ports_discovered} + +
+
+
+
+
+
+ {(source.average_confidence * 100).toFixed(0)}% confidence +
+
+ Last scan:{" "} + {timeAgo(new Date(source.last_scan_time))} +
+
+
+
= 0.9 + ? "bg-green-500" + : source.average_confidence >= 0.7 + ? "bg-yellow-500" + : "bg-red-500" + )} + style={{ width: `${source.average_confidence * 100}%` }} + /> +
+
+
+ ))} +
+
+
+ + {/* Coverage Visualization */} +
+ {/* Host Coverage Chart */} +
+

+ Host Coverage +

+
+ {coverageStats.map((source) => { + const coveragePercentage = + (source.hosts_scanned / metrics.totalHosts) * 100; + return ( +
+
+ + {source.source} + + + {source.hosts_scanned}/{metrics.totalHosts} ( + {coveragePercentage.toFixed(0)}%) + +
+
+
+
+
+ ); + })} +
+
+ + {/* Vulnerability Discovery */} +
+

+ Vulnerability Discovery +

+
+ {coverageStats + .filter((s) => s.vulnerabilities_found > 0) + .sort((a, b) => b.vulnerabilities_found - a.vulnerabilities_found) + .map((source) => { + const discoveryPercentage = + (source.vulnerabilities_found / + metrics.totalVulnerabilities) * + 100; + return ( +
+
+ + {source.source} + + + {source.vulnerabilities_found} ( + {discoveryPercentage.toFixed(0)}%) + +
+
+
+
+
+ ); + })} +
+
+
+ + {/* Summary Stats */} +
+
+
+
+ {metrics.totalVulnerabilities} +
+
+ Total Vulnerabilities +
+
+
+
+ {metrics.totalPorts} +
+
+ Ports Discovered +
+
+
+
+ {metrics.lastScanTime + ? timeAgo(metrics.lastScanTime) + : "Never"} +
+
+ Last Scan Activity +
+
+
+
+
+ ); +}; + +export default SourceCoverageDashboard; diff --git a/sirius-ui/src/components/SourceCoverageDashboardCard.tsx b/sirius-ui/src/components/SourceCoverageDashboardCard.tsx new file mode 100644 index 0000000..fa6b336 --- /dev/null +++ b/sirius-ui/src/components/SourceCoverageDashboardCard.tsx @@ -0,0 +1,411 @@ +import React, { useState } from "react"; +import dynamic from "next/dynamic"; +import { api } from "~/utils/api"; +import { cn } from "~/components/lib/utils"; +import { Button } from "~/components/lib/ui/button"; +import { Shield, AlertTriangle, Activity, Database } from "lucide-react"; +import { SEVERITY_COLORS } from "~/utils/severityTheme"; + +const ResponsiveBar = dynamic( + () => import("@nivo/bar").then((m) => m.ResponsiveBar), + { ssr: false } +); + +const ResponsivePie = dynamic( + () => import("@nivo/pie").then((m) => m.ResponsivePie), + { ssr: false } +); + +interface ChartSettings { + chartType: "bar" | "pie"; + showValues: boolean; +} + +interface Props { + className?: string; +} + +// Helper function to determine severity from risk score (matching backend logic) +const determineSeverity = (riskScore: number): string => { + if (riskScore >= 9.0) return "critical"; + if (riskScore >= 7.0) return "high"; + if (riskScore >= 4.0) return "medium"; + if (riskScore > 0) return "low"; + return "informational"; +}; + +const VulnerabilityDashboard: React.FC = ({ className }) => { + const [settings, setSettings] = useState({ + chartType: "bar", + showValues: true, + }); + + // Get real vulnerability data + const { data: vulnerabilityData, isLoading } = + api.vulnerability.getAllVulnerabilities.useQuery(); + + // Process vulnerability data + const processedData = React.useMemo(() => { + if (!vulnerabilityData?.vulnerabilities) { + return { + severityData: [], + riskData: [], + summaryStats: { + totalVulnerabilities: 0, + totalHosts: 0, + avgRiskScore: 0, + highestRisk: 0, + }, + }; + } + + const vulns = vulnerabilityData.vulnerabilities; + + // Count vulnerabilities by severity + const severityCounts = { + critical: 0, + high: 0, + medium: 0, + low: 0, + informational: 0, + }; + + // Count by risk score ranges + const riskRanges = { + "9.0-10.0": 0, + "7.0-8.9": 0, + "4.0-6.9": 0, + "1.0-3.9": 0, + "0.0-0.9": 0, + }; + + vulns.forEach((vuln) => { + const severity = determineSeverity(vuln.riskScore); + severityCounts[severity as keyof typeof severityCounts]++; + + // Risk score distribution + if (vuln.riskScore >= 9.0) riskRanges["9.0-10.0"]++; + else if (vuln.riskScore >= 7.0) riskRanges["7.0-8.9"]++; + else if (vuln.riskScore >= 4.0) riskRanges["4.0-6.9"]++; + else if (vuln.riskScore >= 1.0) riskRanges["1.0-3.9"]++; + else riskRanges["0.0-0.9"]++; + }); + + // Prepare data for charts + const severityData = [ + { + severity: "Critical", + count: severityCounts.critical, + color: SEVERITY_COLORS.critical.hex, + }, + { severity: "High", count: severityCounts.high, color: SEVERITY_COLORS.high.hex }, + { severity: "Medium", count: severityCounts.medium, color: SEVERITY_COLORS.medium.hex }, + { severity: "Low", count: severityCounts.low, color: SEVERITY_COLORS.low.hex }, + { + severity: "Info", + count: severityCounts.informational, + color: SEVERITY_COLORS.info.hex, + }, + ].filter((item) => item.count > 0); // Only show severities that have vulnerabilities + + const riskData = Object.entries(riskRanges) + .map(([range, count]) => ({ range, count })) + .filter((item) => item.count > 0); + + // Summary statistics + const totalVulns = vulns.length; + const totalHosts = vulns.reduce((sum, vuln) => sum + vuln.hostCount, 0); + const avgRisk = + vulns.length > 0 + ? vulns.reduce((sum, vuln) => sum + vuln.riskScore, 0) / vulns.length + : 0; + const highestRisk = + vulns.length > 0 ? Math.max(...vulns.map((v) => v.riskScore)) : 0; + + return { + severityData, + riskData, + summaryStats: { + totalVulnerabilities: totalVulns, + totalHosts: totalHosts, + avgRiskScore: avgRisk, + highestRisk: highestRisk, + }, + }; + }, [vulnerabilityData]); + + if (isLoading) { + return ( +
+
+

+ Vulnerability Dashboard +

+

+ Loading vulnerability data... +

+
+
+
+ ); + } + + const { severityData, summaryStats } = processedData; + + return ( +
+ {/* Header */} +
+

+ Vulnerability Dashboard +

+

+ Current vulnerability analysis across your infrastructure +

+
+ + {/* Summary Stats Cards */} +
+
+
+ +
+

+ Total Vulnerabilities +

+

+ {summaryStats.totalVulnerabilities} +

+
+
+
+ +
+
+ +
+

+ Affected Hosts +

+

{summaryStats.totalHosts}

+
+
+
+ +
+
+ +
+

+ Avg Risk Score +

+

+ {summaryStats.avgRiskScore.toFixed(1)} +

+
+
+
+ +
+
+ +
+

+ Highest Risk +

+

+ {summaryStats.highestRisk.toFixed(1)} +

+
+
+
+
+ + {/* Control Buttons */} +
+ + + +
+ + {/* Chart */} +
+ {severityData.length > 0 ? ( + settings.chartType === "bar" ? ( + data.color} + borderColor={{ + from: "color", + modifiers: [["darker", 1.6]], + }} + axisTop={null} + axisRight={null} + axisBottom={{ + tickSize: 5, + tickPadding: 5, + tickRotation: 0, + legend: "Severity Level", + legendPosition: "middle", + legendOffset: 32, + }} + axisLeft={{ + tickSize: 5, + tickPadding: 5, + tickRotation: 0, + legend: "Vulnerability Count", + legendPosition: "middle", + legendOffset: -40, + }} + enableLabel={settings.showValues} + labelSkipWidth={12} + labelSkipHeight={12} + labelTextColor={{ + from: "color", + modifiers: [["darker", 1.6]], + }} + legends={[]} + role="application" + ariaLabel="Vulnerability severity distribution bar chart" + theme={{ + background: "transparent", + text: { + fontSize: 11, + fill: "#374151", + }, + axis: { + domain: { + line: { + stroke: "#e5e7eb", + strokeWidth: 1, + }, + }, + legend: { + text: { + fontSize: 12, + fill: "#374151", + }, + }, + ticks: { + line: { + stroke: "#e5e7eb", + strokeWidth: 1, + }, + text: { + fontSize: 11, + fill: "#6b7280", + }, + }, + }, + grid: { + line: { + stroke: "#f3f4f6", + strokeWidth: 1, + }, + }, + tooltip: { + container: { + background: "#1f2937", + color: "#f9fafb", + fontSize: 12, + borderRadius: 4, + boxShadow: "0 4px 6px -1px rgba(0, 0, 0, 0.1)", + }, + }, + }} + /> + ) : ( + ({ + id: item.severity, + label: item.severity, + value: item.count, + color: item.color, + }))} + margin={{ top: 40, right: 80, bottom: 80, left: 80 }} + innerRadius={0.5} + padAngle={0.7} + cornerRadius={3} + activeOuterRadiusOffset={8} + colors={({ data }) => data.color} + borderWidth={1} + borderColor={{ + from: "color", + modifiers: [["darker", 0.2]], + }} + arcLinkLabelsSkipAngle={10} + arcLinkLabelsTextColor="#333333" + arcLinkLabelsThickness={2} + arcLinkLabelsColor={{ from: "color" }} + arcLabelsSkipAngle={10} + arcLabelsTextColor={{ + from: "color", + modifiers: [["darker", 2]], + }} + enableArcLabels={settings.showValues} + enableArcLinkLabels={true} + theme={{ + background: "transparent", + text: { + fontSize: 11, + fill: "#374151", + }, + tooltip: { + container: { + background: "#1f2937", + color: "#f9fafb", + fontSize: 12, + borderRadius: 4, + boxShadow: "0 4px 6px -1px rgba(0, 0, 0, 0.1)", + }, + }, + }} + /> + ) + ) : ( +
+ No vulnerability data available +
+ )} +
+
+ ); +}; + +export default VulnerabilityDashboard; diff --git a/sirius-ui/src/components/SourceFilterInterface.tsx b/sirius-ui/src/components/SourceFilterInterface.tsx new file mode 100644 index 0000000..80202bd --- /dev/null +++ b/sirius-ui/src/components/SourceFilterInterface.tsx @@ -0,0 +1,288 @@ +"use client"; + +import React, { useState, useEffect } from "react"; +import { cn } from "~/components/lib/utils"; +import { Filter, X, Calendar, Shield, Search, RotateCcw } from "lucide-react"; +import { Button } from "~/components/lib/ui/button"; +import { getSourceColor } from "~/components/shared/SourceBadge"; +import { + sourceFilterOptions, + confidenceFilterOptions, +} from "./VulnerabilityTableSourceColumns"; + +export interface SourceFilterState { + sources: string[]; + confidence: string[]; + dateRange: { + start?: string; + end?: string; + }; + searchTerm: string; +} + +interface SourceFilterInterfaceProps { + onFilterChange: (filters: SourceFilterState) => void; + className?: string; + showAdvanced?: boolean; +} + +export const SourceFilterInterface: React.FC = ({ + onFilterChange, + className, + showAdvanced = true, +}) => { + const [isExpanded, setIsExpanded] = useState(false); + const [filters, setFilters] = useState({ + sources: [], + confidence: [], + dateRange: {}, + searchTerm: "", + }); + + // Notify parent of filter changes + useEffect(() => { + onFilterChange(filters); + }, [filters, onFilterChange]); + + const handleSourceToggle = (source: string) => { + setFilters((prev) => ({ + ...prev, + sources: prev.sources.includes(source) + ? prev.sources.filter((s) => s !== source) + : [...prev.sources, source], + })); + }; + + const handleConfidenceToggle = (confidence: string) => { + setFilters((prev) => ({ + ...prev, + confidence: prev.confidence.includes(confidence) + ? prev.confidence.filter((c) => c !== confidence) + : [...prev.confidence, confidence], + })); + }; + + const handleDateRangeChange = (field: "start" | "end", value: string) => { + setFilters((prev) => ({ + ...prev, + dateRange: { + ...prev.dateRange, + [field]: value || undefined, + }, + })); + }; + + const handleSearchChange = (value: string) => { + setFilters((prev) => ({ + ...prev, + searchTerm: value, + })); + }; + + const clearAllFilters = () => { + setFilters({ + sources: [], + confidence: [], + dateRange: {}, + searchTerm: "", + }); + }; + + const hasActiveFilters = + filters.sources.length > 0 || + filters.confidence.length > 0 || + filters.dateRange.start || + filters.dateRange.end || + filters.searchTerm.length > 0; + + const getSourceBadgeColor = (source: string) => + getSourceColor(source, "badge"); + + return ( +
+ {/* Filter Header */} +
+
+ + + Vulnerability Filters + + {hasActiveFilters && ( + + {filters.sources.length + + filters.confidence.length + + (filters.dateRange.start ? 1 : 0) + + (filters.searchTerm ? 1 : 0)}{" "} + active + + )} +
+
+ {hasActiveFilters && ( + + )} + {showAdvanced && ( + + )} +
+
+ + {/* Search Bar */} +
+
+ + handleSearchChange(e.target.value)} + className="w-full rounded-md border border-gray-600 bg-gray-800 py-2 pl-10 pr-4 text-sm text-gray-100 placeholder-gray-500 focus:border-transparent focus:ring-2 text-gray-100 placeholder-gray-400" + /> +
+
+ + {/* Source Filters */} +
+
+ + Sources: + +
+
+ {sourceFilterOptions.map((option) => ( + + ))} +
+
+ + {/* Confidence Filters */} +
+
+ + + Confidence Level: + +
+
+ {confidenceFilterOptions.map((option) => ( + + ))} +
+
+ + {/* Advanced Filters */} + {isExpanded && showAdvanced && ( +
+
+ + + Date Range: + +
+
+
+ + handleDateRangeChange("start", e.target.value)} + className="w-full rounded-md border border-gray-600 bg-gray-800 px-3 py-2 text-sm text-gray-100 focus:border-transparent focus:ring-2 text-gray-100" + /> +
+
+ + handleDateRangeChange("end", e.target.value)} + className="w-full rounded-md border border-gray-600 bg-gray-800 px-3 py-2 text-sm text-gray-100 focus:border-transparent focus:ring-2 text-gray-100" + /> +
+
+
+ )} + + {/* Active Filters Summary */} + {hasActiveFilters && ( +
+
+ Active filters: + {filters.sources.length > 0 && ( + + Sources: {filters.sources.join(", ")} + + )} + {filters.confidence.length > 0 && ( + + Confidence: {filters.confidence.join(", ")} + + )} + {filters.dateRange.start && ( + From: {filters.dateRange.start} + )} + {filters.dateRange.end && ( + To: {filters.dateRange.end} + )} + {filters.searchTerm && ( + Search: "{filters.searchTerm}" + )} +
+
+ )} +
+ ); +}; + +export default SourceFilterInterface; diff --git a/sirius-ui/src/components/SystemResourcesDashboard.tsx b/sirius-ui/src/components/SystemResourcesDashboard.tsx new file mode 100644 index 0000000..cca59fe --- /dev/null +++ b/sirius-ui/src/components/SystemResourcesDashboard.tsx @@ -0,0 +1,890 @@ +import React, { useState, useEffect, useCallback } from "react"; +import { + Card, + CardContent, + CardHeader, + CardTitle, +} from "~/components/lib/ui/card"; +import { + Table, + TableBody, + TableCell, + TableHead, + TableHeader, + TableRow, +} from "~/components/lib/ui/table"; +import { Badge } from "~/components/lib/ui/badge"; +import { Button } from "~/components/lib/ui/button"; +import { + Select, + SelectContent, + SelectItem, + SelectTrigger, + SelectValue, +} from "~/components/lib/ui/select"; +import { + RefreshCw, + Cpu, + HardDrive, + MemoryStick, + Network, + Activity, + AlertTriangle, + Users, + FileText, + Clock, + BarChart3, + ChevronDown, + ChevronRight, + RotateCcw, + Play, + Square, + CheckCircle, + XCircle, +} from "lucide-react"; +import { + Dialog, + DialogContent, + DialogDescription, + DialogFooter, + DialogHeader, + DialogTitle, +} from "~/components/lib/ui/dialog"; + +interface SystemResourceProps { + className?: string; +} + +interface ContainerResource { + name: string; + cpu_percent: number; + memory_usage: string; + memory_percent: number; + network_io: string; + disk_usage: string; + disk_percent: number; + process_count: number; + file_descriptors: number; + load_average_1m: number; + load_average_5m: number; + load_average_15m: number; + uptime: string; + status: string; +} + +interface SystemResourcesSummary { + total_containers: number; + running_containers: number; + total_cpu_percent: number; + total_memory_usage: string; + total_memory_percent: number; +} + +interface SystemResourcesData { + containers: ContainerResource[]; + summary: SystemResourcesSummary; + timestamp: string; +} + +export const SystemResourcesDashboard: React.FC = ({ + className, +}) => { + const [data, setData] = useState(null); + const [loading, setLoading] = useState(true); + const [error, setError] = useState(null); + const [refreshInterval, setRefreshInterval] = useState("5"); + const [expandedRows, setExpandedRows] = useState>(new Set()); + const [dialogOpen, setDialogOpen] = useState(false); + const [dialogContent, setDialogContent] = useState<{ + title: string; + message: string; + type: "success" | "error"; + } | null>(null); + const [restartingContainers, setRestartingContainers] = useState>( + new Set() + ); + const [containerUptimes, setContainerUptimes] = useState>( + new Map() + ); + const [containerLogs, setContainerLogs] = useState>( + new Map() + ); + + // Mock data for fallback + const generateMockData = (): SystemResourcesData => { + const now = new Date(); + return { + containers: [ + { + name: "sirius-api", + cpu_percent: 2.5, + memory_usage: "45.2MB", + memory_percent: 1.2, + network_io: "1.2kB / 856B", + disk_usage: "26.1GB / 503.6GB", + disk_percent: 5.2, + process_count: 3, + file_descriptors: 8, + load_average_1m: 1.96, + load_average_5m: 1.84, + load_average_15m: 1.47, + uptime: "1d 15h", + status: "running", + }, + { + name: "sirius-ui", + cpu_percent: 1.8, + memory_usage: "128.5MB", + memory_percent: 3.4, + network_io: "2.1kB / 1.2kB", + disk_usage: "15.2GB / 503.6GB", + disk_percent: 3.0, + process_count: 2, + file_descriptors: 6, + load_average_1m: 0.85, + load_average_5m: 0.92, + load_average_15m: 0.78, + uptime: "1d 15h", + status: "running", + }, + { + name: "sirius-engine", + cpu_percent: 0.5, + memory_usage: "89.3MB", + memory_percent: 2.1, + network_io: "856B / 432B", + disk_usage: "8.7GB / 503.6GB", + disk_percent: 1.7, + process_count: 5, + file_descriptors: 12, + load_average_1m: 0.45, + load_average_5m: 0.38, + load_average_15m: 0.42, + uptime: "1d 15h", + status: "running", + }, + { + name: "sirius-postgres", + cpu_percent: 0.2, + memory_usage: "156.7MB", + memory_percent: 4.1, + network_io: "3.2kB / 2.1kB", + disk_usage: "45.3GB / 503.6GB", + disk_percent: 9.0, + process_count: 8, + file_descriptors: 24, + load_average_1m: 0.12, + load_average_5m: 0.15, + load_average_15m: 0.18, + uptime: "1d 15h", + status: "running", + }, + { + name: "sirius-valkey", + cpu_percent: 0.1, + memory_usage: "12.3MB", + memory_percent: 0.3, + network_io: "432B / 256B", + disk_usage: "2.1GB / 503.6GB", + disk_percent: 0.4, + process_count: 1, + file_descriptors: 4, + load_average_1m: 0.05, + load_average_5m: 0.08, + load_average_15m: 0.06, + uptime: "1d 15h", + status: "running", + }, + { + name: "sirius-rabbitmq", + cpu_percent: 0.3, + memory_usage: "67.8MB", + memory_percent: 1.8, + network_io: "1.5kB / 1.1kB", + disk_usage: "3.4GB / 503.6GB", + disk_percent: 0.7, + process_count: 4, + file_descriptors: 16, + load_average_1m: 0.18, + load_average_5m: 0.22, + load_average_15m: 0.19, + uptime: "1d 15h", + status: "running", + }, + ], + summary: { + total_containers: 6, + running_containers: 6, + total_cpu_percent: 5.4, + total_memory_usage: "499.8MB", + total_memory_percent: 13.1, + }, + timestamp: now.toISOString(), + }; + }; + + const loadSystemResources = useCallback(async () => { + try { + setLoading(true); + setError(null); + + // Fetch real system resource data from API + const response = await fetch( + `${ + process.env.NEXT_PUBLIC_SIRIUS_API_URL || "http://localhost:9001" + }/api/v1/system/resources` + ); + if (!response.ok) { + throw new Error(`HTTP error! status: ${response.status}`); + } + const apiData = await response.json(); + + // Check for container restarts by comparing uptimes + if (apiData.containers) { + const newUptimes = new Map(); + const newRestartingContainers = new Set(restartingContainers); + + apiData.containers.forEach((container: ContainerResource) => { + const previousUptime = containerUptimes.get(container.name); + newUptimes.set(container.name, container.uptime); + + // If uptime changed and container was restarting, it's back online + if ( + previousUptime && + previousUptime !== container.uptime && + restartingContainers.has(container.name) + ) { + newRestartingContainers.delete(container.name); + console.log( + `Container ${container.name} has restarted successfully` + ); + } + }); + + setContainerUptimes(newUptimes); + setRestartingContainers(newRestartingContainers); + } + + setData(apiData); + } catch (err) { + setError( + err instanceof Error ? err.message : "Failed to load system resources" + ); + console.error("Failed to load system resources:", err); + + // Fallback to mock data on error + const mockData = generateMockData(); + setData(mockData); + } finally { + setLoading(false); + } + }, []); + + useEffect(() => { + loadSystemResources(); + }, []); + + // Auto-refresh based on interval + useEffect(() => { + if (refreshInterval === "0") return; // Disabled + + const interval = setInterval(() => { + loadSystemResources(); + }, parseInt(refreshInterval) * 1000); + + return () => clearInterval(interval); + }, [refreshInterval]); + + const handleRefresh = () => { + loadSystemResources(); + }; + + // Load recent logs for a specific container + const loadContainerLogs = async (containerName: string) => { + try { + const response = await fetch( + `${ + process.env.NEXT_PUBLIC_SIRIUS_API_URL || "http://localhost:9001" + }/api/v1/system/logs?container=${containerName}&lines=3` + ); + if (response.ok) { + const data = await response.json(); + setContainerLogs((prev) => { + const newMap = new Map(prev); + newMap.set(containerName, data.logs || []); + return newMap; + }); + } + } catch (error) { + console.error(`Error loading logs for ${containerName}:`, error); + } + }; + + const getStatusBadgeVariant = (status: string) => { + switch (status.toLowerCase()) { + case "running": + return "default"; + case "exited": + return "destructive"; + case "paused": + return "secondary"; + default: + return "outline"; + } + }; + + const getCpuColor = (cpuPercent: number) => { + if (cpuPercent < 25) return "text-green-500"; + if (cpuPercent < 50) return "text-yellow-500"; + if (cpuPercent < 75) return "text-orange-500"; + return "text-red-500"; + }; + + const getMemoryColor = (memoryPercent: number) => { + if (memoryPercent < 25) return "text-green-500"; + if (memoryPercent < 50) return "text-yellow-500"; + if (memoryPercent < 75) return "text-orange-500"; + return "text-red-500"; + }; + + const getDiskColor = (diskPercent: number) => { + if (diskPercent < 25) return "text-green-500"; + if (diskPercent < 50) return "text-yellow-500"; + if (diskPercent < 75) return "text-orange-500"; + return "text-red-500"; + }; + + const toggleRowExpansion = (index: number) => { + const newExpanded = new Set(expandedRows); + if (newExpanded.has(index)) { + newExpanded.delete(index); + } else { + newExpanded.add(index); + // Load logs when expanding + if (data && data.containers[index]) { + const containerName = data.containers[index].name; + loadContainerLogs(containerName); + } + } + setExpandedRows(newExpanded); + }; + + const formatTimestamp = (timestamp: string) => { + try { + const date = new Date(timestamp); + return date.toLocaleString(); + } catch { + return "Unknown"; + } + }; + + if (loading && !data) { + return ( +
+
+
+ + Loading system resources... +
+
+
+ ); + } + + return ( +
+ {/* Header */} +
+
+

+ System Resources +

+

+ Real-time container resource monitoring +

+
+
+ + +
+
+ + {/* Error Alert */} + {error && ( +
+
+ + Error +
+

{error}

+
+ )} + + {/* Summary Cards */} + {data && ( +
+ + + + Total Containers + + + + +
+ {data.summary.total_containers} +
+

+ {data.summary.running_containers} running +

+ + + + + + Total CPU + + + +
+ {data.summary.total_cpu_percent.toFixed(1)}% +
+

+ {data.summary.total_cpu_percent < 50 + ? "Low usage" + : "High usage"} +

+ + + + + + + Total Memory + + + + +
+ {data.summary.total_memory_usage} +
+

+ {data.summary.total_memory_percent.toFixed(1)}% of system +

+ + + + + + + Last Updated + + + + +
+ {formatTimestamp(data.timestamp)} +
+

+ {refreshInterval === "0" + ? "Manual refresh" + : refreshInterval === "2" + ? "Live updates" + : `Auto ${refreshInterval}s`} +

+ + +
+ )} + + {/* Container Resources Table */} + {data && ( + + + Container Resources + + + + + + Container + Status + CPU + Memory + Network I/O + Disk Usage + Uptime + Actions + + + + {data.containers.map((container, index) => ( + + toggleRowExpansion(index)} + > + +
+ {expandedRows.has(index) ? ( + + ) : ( + + )} + {container.name} +
+ + + + {container.status} + + + +
+ + + {container.cpu_percent.toFixed(1)}% + +
+ + +
+ +
+
+ {container.memory_usage} +
+
+ {container.memory_percent.toFixed(1)}% +
+
+
+ + +
+ + + {container.network_io} + +
+ + +
+ +
+
+ {container.disk_usage} +
+
+ {container.disk_percent.toFixed(1)}% +
+
+
+ + +
+ + + {container.uptime} + +
+ + +
+ +
+ + + + {/* Expanded Row Content */} + {expandedRows.has(index) && ( + + +
+ {/* Secondary Metrics */} +
+
+ +
+
+ Processes +
+
+ {container.process_count} +
+
+
+
+ +
+
+ File Descriptors +
+
+ {container.file_descriptors} +
+
+
+
+ +
+
+ Load Average +
+
+
+ 1m: {container.load_average_1m.toFixed(2)} +
+
+ 5m: {container.load_average_5m.toFixed(2)} +
+
+ 15m:{" "} + {container.load_average_15m.toFixed(2)} +
+
+
+
+ +
+
+ Container Health +
+
+ {container.status === "running" ? ( + + + Healthy + + ) : ( + + + {container.status} + + )} +
+
+
+
+
+ + {/* Recent Logs */} +
+

+ Recent Logs +

+ {containerLogs.has(container.name) ? ( +
+ {containerLogs + .get(container.name) + ?.slice(0, 3) + .map((log: any, idx: number) => ( +
+ + {log.level} + +
+
+ {new Date( + log.timestamp + ).toLocaleTimeString()} +
+
+ {log.message} +
+
+
+ ))} +
+ ) : ( +
+ Loading recent logs... +
+ )} +
+
+ + + )} + + ))} + +
+ + + )} + + {/* Confirmation Dialog */} + + + + {dialogContent?.title} + {dialogContent?.message} + + + {dialogContent?.title === "Confirm Restart" ? ( + <> + + + + ) : ( + + )} + + + +
+ ); +}; diff --git a/sirius-ui/src/components/Terminal.tsx b/sirius-ui/src/components/Terminal.tsx new file mode 100644 index 0000000..84941b9 --- /dev/null +++ b/sirius-ui/src/components/Terminal.tsx @@ -0,0 +1,26 @@ +import { useEffect, useRef, useState } from "react"; +import { Terminal } from "xterm"; +import { FitAddon } from "xterm-addon-fit"; +import "xterm/css/xterm.css"; +import { api } from "~/utils/api"; + +// Your existing theme and LOCAL_COMMANDS definitions here... + +const TerminalComponent = () => { + const terminalRef = useRef(null); + const [terminal, setTerminal] = useState(null); + const commandHistoryRef = useRef([]); + const historyPositionRef = useRef(-1); + const currentLineRef = useRef(""); + + // Your existing terminal logic here... + + return ( +
+ ); +}; + +export default TerminalComponent; \ No newline at end of file diff --git a/sirius-ui/src/components/TerminalWrapper.tsx b/sirius-ui/src/components/TerminalWrapper.tsx new file mode 100644 index 0000000..ed3bb95 --- /dev/null +++ b/sirius-ui/src/components/TerminalWrapper.tsx @@ -0,0 +1,41 @@ +import dynamic from "next/dynamic"; +import { Suspense } from "react"; + +// Dynamically import the new OperatorConsole with SSR disabled +const OperatorConsole = dynamic( + () => import("./console/OperatorConsole"), + { + ssr: false, + loading: () => ( +
+
+
+

Loading Console...

+
+
+ ), + } +); + +// Preload the component to improve perceived performance +if (typeof window !== "undefined") { + const preloadConsole = () => import("./console/OperatorConsole"); + setTimeout(preloadConsole, 100); +} + +export default function TerminalWrapper() { + return ( + +
+
+

Loading Console...

+
+
+ } + > + + + ); +} diff --git a/sirius-ui/src/components/Toast.tsx b/sirius-ui/src/components/Toast.tsx new file mode 100644 index 0000000..96fb39b --- /dev/null +++ b/sirius-ui/src/components/Toast.tsx @@ -0,0 +1,56 @@ +import { createContext, useContext, useState, useCallback } from 'react'; + +type ToastType = 'success' | 'error'; + +interface Toast { + id: number; + message: string; + type: ToastType; +} + +interface ToastContextType { + showToast: (message: string, type: ToastType) => void; +} + +const ToastContext = createContext(undefined); + +export const ToastProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => { + const [toasts, setToasts] = useState([]); + let toastId = 0; + + const showToast = useCallback((message: string, type: ToastType) => { + const id = toastId++; + setToasts(prev => [...prev, { id, message, type }]); + + // Remove toast after 3 seconds + setTimeout(() => { + setToasts(prev => prev.filter(toast => toast.id !== id)); + }, 3000); + }, []); + + return ( + + {children} +
+ {toasts.map(toast => ( +
+ {toast.message} +
+ ))} +
+ + ); +}; + +export const useToast = () => { + const context = useContext(ToastContext); + if (!context) { + throw new Error('useToast must be used within a ToastProvider'); + } + return context; +}; \ No newline at end of file diff --git a/sirius-ui/src/components/ViewModeSelector.tsx b/sirius-ui/src/components/ViewModeSelector.tsx new file mode 100644 index 0000000..89fe9d5 --- /dev/null +++ b/sirius-ui/src/components/ViewModeSelector.tsx @@ -0,0 +1,48 @@ +import React from "react"; +import { cn } from "~/components/lib/utils"; +import { LayoutList, Command, LayoutGrid } from "lucide-react"; +import { type ViewMode } from "~/components/vulnerability/types"; + +// Re-export ViewMode so existing imports keep working +export type { ViewMode }; + +interface ViewSelectorProps { + viewMode: ViewMode; + onViewChange: (mode: ViewMode) => void; + className?: string; +} + +const VIEW_OPTIONS: { mode: ViewMode; icon: typeof LayoutList; label: string }[] = [ + { mode: "table", icon: LayoutList, label: "Table" }, + { mode: "command", icon: Command, label: "Command Table" }, + { mode: "grouped", icon: LayoutGrid, label: "Grouped" }, +]; + +/** + * ViewModeSelector — v0.4 dark-only view mode toggle. + */ +export const ViewModeSelector: React.FC = ({ + viewMode, + onViewChange, + className, +}) => { + return ( +
+ {VIEW_OPTIONS.map(({ mode, icon: Icon, label }) => ( + + ))} +
+ ); +}; diff --git a/sirius-ui/src/components/VulnerabilitiesOverTimeChart.tsx b/sirius-ui/src/components/VulnerabilitiesOverTimeChart.tsx new file mode 100755 index 0000000..965a996 --- /dev/null +++ b/sirius-ui/src/components/VulnerabilitiesOverTimeChart.tsx @@ -0,0 +1,495 @@ +import React, { useEffect } from "react"; +import dynamic from "next/dynamic"; +import { useState } from "react"; + +import { Button } from "./lib/ui/button"; +import { SEVERITY_COLORS } from "~/utils/severityTheme"; + +const ResponsiveLine = dynamic( + () => import("@nivo/line").then((m) => m.ResponsiveLine), + { ssr: false } +); + +type Props = {}; + +interface ChartSettings { + stacked: boolean; + lineWidth: number; + enableArea: boolean; +} + +const VulnerabilitiesOverTimeChart = (props: Props) => { + const [settings, setSettings] = useState({ + stacked: true, + lineWidth: 0, + enableArea: true, + }); + + const data = [ + { + id: "informational", + color: "hsl(37, 70%, 50%)", + data: [ + { + x: "Scan 1", + y: 2, + }, + { + x: "Scan 2", + y: 42, + }, + { + x: "Scan 3", + y: 122, + }, + { + x: "Scan 4", + y: 101, + }, + { + x: "Scan 5", + y: 305, + }, + ], + }, + { + id: "low", + color: "hsl(37, 70%, 50%)", + data: [ + { + x: "Scan 1", + y: 242, + }, + { + x: "Scan 2", + y: 162, + }, + { + x: "Scan 3", + y: 122, + }, + { + x: "Scan 4", + y: 118, + }, + { + x: "Scan 5", + y: 38, + }, + ], + }, + { + id: "medium", + color: "hsl(37, 70%, 50%)", + data: [ + { + x: "Scan 1", + y: 192, + }, + { + x: "Scan 2", + y: 282, + }, + { + x: "Scan 3", + y: 172, + }, + { + x: "Scan 4", + y: 61, + }, + { + x: "Scan 5", + y: 125, + }, + ], + }, + { + id: "high", + color: "hsl(37, 70%, 50%)", + data: [ + { + x: "Scan 1", + y: 2, + }, + { + x: "Scan 2", + y: 142, + }, + { + x: "Scan 3", + y: 12, + }, + { + x: "Scan 4", + y: 111, + }, + { + x: "Scan 5", + y: 25, + }, + ], + }, + { + id: "critical", + color: "hsl(37, 70%, 50%)", + data: [ + { + x: "Scan 1", + y: 2, + }, + { + x: "Scan 2", + y: 12, + }, + { + x: "Scan 3", + y: 72, + }, + { + x: "Scan 4", + y: 11, + }, + { + x: "Scan 5", + y: 5, + }, + ], + }, + ]; + + const handleVulnerabilitiesOverTimeClick = () => { + setSettings({ + stacked: true, // Example of different settings + lineWidth: 0, + enableArea: true, + }); + }; + + const handleVulnerabilitiesBySeverityClick = () => { + setSettings({ + enableArea: false, + stacked: false, + lineWidth: 1, + }); + }; + + return ( +
+
+ + +
+ +
+ ); +}; + +interface VulnerabilityChartProps { + id: string; + color: string; + data: { + x: string; + y: number; + }[]; + settings: { + stacked: boolean; + lineWidth: number; + enableArea: boolean; + }; +} + +const theme = { + text: { + fontSize: 48, + color: "#fff", + }, + axis: { + domain: { + line: { + stroke: "#777777", + strokeWidth: 0, + }, + }, + legend: { + text: { + fontSize: 12, + fill: "#fff", + outlineWidth: 0, + outlineColor: "transparent", + }, + }, + ticks: { + line: {}, + text: { + fontSize: 8, + fill: "#fff", + outlineWidth: 0, + outlineColor: "transparent", + }, + }, + }, + grid: { + line: { + stroke: "#777777", + strokeWidth: 0.2, + }, + }, + legends: { + title: { + text: { + fontSize: 48, + fill: "#fff", + outlineWidth: 0, + outlineColor: "transparent", + }, + }, + text: { + fontSize: 12, + fill: "#fff", + outlineWidth: 0, + outlineColor: "transparent", + }, + }, + tooltip: { + container: { + background: "#000", + fontSize: 12, + }, + basic: {}, + chip: {}, + table: {}, + tableCell: {}, + tableCellValue: {}, + }, +}; + +const VulnerabilityChart: React.FC = ({ + id, + color, + data, + settings, +}) => { + const tmp = [ + { + id: "informational", + color: "hsl(0, 0%, 0%, .1)", + data: [ + { + x: "Scan 1", + y: 42, + }, + { + x: "Scan 2", + y: 142, + }, + { + x: "Scan 3", + y: 172, + }, + { + x: "Scan 4", + y: 211, + }, + { + x: "Scan 5", + y: 325, + }, + ], + }, + { + id: "low", + color: "hsl(37, 70%, 50%)", + data: [ + { + x: "Scan 1", + y: 242, + }, + { + x: "Scan 2", + y: 242, + }, + { + x: "Scan 3", + y: 172, + }, + { + x: "Scan 4", + y: 111, + }, + { + x: "Scan 5", + y: 5, + }, + ], + }, + { + id: "medium", + color: "hsl(37, 70%, 50%)", + data: [ + { + x: "Scan 1", + y: 242, + }, + { + x: "Scan 2", + y: 242, + }, + { + x: "Scan 3", + y: 72, + }, + { + x: "Scan 4", + y: 111, + }, + { + x: "Scan 5", + y: 225, + }, + ], + }, + { + id: "high", + color: "hsl(37, 70%, 50%)", + data: [ + { + x: "Scan 1", + y: 2, + }, + { + x: "Scan 2", + y: 142, + }, + { + x: "Scan 3", + y: 172, + }, + { + x: "Scan 4", + y: 111, + }, + { + x: "Scan 5", + y: 25, + }, + ], + }, + { + id: "critical", + label: "Critical", + color: "#000", + data: [ + { + x: "Scan 1", + y: 2, + }, + { + x: "Scan 2", + y: 12, + }, + { + x: "Scan 3", + y: 72, + }, + { + x: "Scan 4", + y: 11, + }, + { + x: "Scan 5", + y: 25, + }, + ], + }, + ]; + + return ( + + ); +}; +export default VulnerabilitiesOverTimeChart; diff --git a/sirius-ui/src/components/VulnerabilityBarGraph.tsx b/sirius-ui/src/components/VulnerabilityBarGraph.tsx new file mode 100644 index 0000000..f804ab1 --- /dev/null +++ b/sirius-ui/src/components/VulnerabilityBarGraph.tsx @@ -0,0 +1,288 @@ +import React from "react"; +import { cn } from "~/components/lib/utils"; +import { api } from "~/utils/api"; +import { SEVERITY_COLORS } from "~/utils/severityTheme"; +import { type HostStatistics } from "~/server/api/routers/host"; + +// Define the severity counts interface for internal use +export interface VulnerabilitySeverityCounts { + critical: number; + high: number; + medium: number; + low: number; + informational: number; +} + +interface VulnerabilityBarGraphProps { + hostId: string; // Required prop to fetch data by host ID + height?: number; + className?: string; +} + +export function VulnerabilityBarGraph({ + hostId, + height = 8, + className, +}: VulnerabilityBarGraphProps) { + // Fetch the statistics directly using the hostId + const hostStatsQuery = api.host.getHostStatistics.useQuery( + { hid: hostId }, + { enabled: !!hostId && hostId.trim() !== "" } + ); + + // Show loading indicator while fetching data + if (hostStatsQuery.isLoading) { + return ( +
+
+
+ ); + } + + // Get severity counts from API data + const severityCounts: VulnerabilitySeverityCounts = hostStatsQuery.data + ?.hostSeverityCounts || { + critical: 0, + high: 0, + medium: 0, + low: 0, + informational: 0, + }; + + // Calculate the total count of vulnerabilities + const total = + severityCounts.critical + + severityCounts.high + + severityCounts.medium + + severityCounts.low + + severityCounts.informational; + + // If there are no vulnerabilities, display a placeholder + if (total === 0) { + return ( +
+ No vulnerabilities +
+ ); + } + + // Calculate percentages for each severity + const criticalPercentage = (severityCounts.critical / total) * 100; + const highPercentage = (severityCounts.high / total) * 100; + const mediumPercentage = (severityCounts.medium / total) * 100; + const lowPercentage = (severityCounts.low / total) * 100; + const infoPercentage = (severityCounts.informational / total) * 100; + + return ( +
+ {/* Summary of vulnerabilities as text */} +
+ Vulnerabilities + {total} +
+ + {/* The actual bar graph */} +
+ {/* Critical vulnerabilities - red */} + {severityCounts.critical > 0 && ( +
+ )} + + {/* High vulnerabilities - orange */} + {severityCounts.high > 0 && ( +
+ )} + + {/* Medium vulnerabilities - amber */} + {severityCounts.medium > 0 && ( +
+ )} + + {/* Low vulnerabilities - green */} + {severityCounts.low > 0 && ( +
+ )} + + {/* Informational vulnerabilities - blue */} + {severityCounts.informational > 0 && ( +
+ )} +
+ + {/* Legend showing total counts by severity */} +
+ {severityCounts.critical > 0 && ( + + + {severityCounts.critical} Critical + + )} + {severityCounts.high > 0 && ( + + + {severityCounts.high} High + + )} + {severityCounts.medium > 0 && ( + + + {severityCounts.medium} Medium + + )} + {severityCounts.low > 0 && ( + + + {severityCounts.low} Low + + )} + {severityCounts.informational > 0 && ( + + + {severityCounts.informational} Info + + )} +
+
+ ); +} + +// A more compact version for use in table cells +export function VulnerabilityBarGraphCompact({ + hostId, + height = 6, + className, +}: VulnerabilityBarGraphProps) { + // Fetch the statistics directly using the hostId + const hostStatsQuery = api.host.getHostStatistics.useQuery( + { hid: hostId }, + { enabled: !!hostId && hostId.trim() !== "" } + ); + + // Show loading indicator while fetching data + if (hostStatsQuery.isLoading) { + return ( +
+
+ Loading... +
+ ); + } + + // Get severity counts from API data + const severityCounts: VulnerabilitySeverityCounts = hostStatsQuery.data + ?.hostSeverityCounts || { + critical: 0, + high: 0, + medium: 0, + low: 0, + informational: 0, + }; + + const total = + severityCounts.critical + + severityCounts.high + + severityCounts.medium + + severityCounts.low + + severityCounts.informational; + + if (total === 0) { + return ( +
+ No vulnerabilities +
+ ); + } + + const criticalPercentage = (severityCounts.critical / total) * 100; + const highPercentage = (severityCounts.high / total) * 100; + const mediumPercentage = (severityCounts.medium / total) * 100; + const lowPercentage = (severityCounts.low / total) * 100; + const infoPercentage = (severityCounts.informational / total) * 100; + + return ( +
+
+ {total} vulnerabilities + {severityCounts.critical > 0 && ( + + {severityCounts.critical} critical + + )} +
+ +
+ {severityCounts.critical > 0 && ( +
+ )} + {severityCounts.high > 0 && ( +
+ )} + {severityCounts.medium > 0 && ( +
+ )} + {severityCounts.low > 0 && ( +
+ )} + {severityCounts.informational > 0 && ( +
+ )} +
+
+ ); +} diff --git a/sirius-ui/src/components/VulnerabilityCommandTable.tsx b/sirius-ui/src/components/VulnerabilityCommandTable.tsx new file mode 100644 index 0000000..0ad1d48 --- /dev/null +++ b/sirius-ui/src/components/VulnerabilityCommandTable.tsx @@ -0,0 +1,477 @@ +/** + * VulnerabilityCommandTable — v0.4 dark-only rewrite. + * + * Uses shared SeverityBadge and CvssScore components. + * Full keyboard navigation with arrow keys, space to select, enter to view details. + */ + +import React, { useState, useRef, useEffect, useCallback } from "react"; +import { + useReactTable, + getCoreRowModel, + getSortedRowModel, + getFilteredRowModel, + flexRender, + type ColumnDef, + type SortingState, + type RowSelectionState, + createColumnHelper, + type Updater, +} from "@tanstack/react-table"; +import { ChevronDown, ChevronUp, ExternalLink, Eye, Shield } from "lucide-react"; +import { cn } from "~/components/lib/utils"; +import { SeverityBadge } from "~/components/shared/SeverityBadge"; +import { CvssScore } from "~/components/shared/CvssScore"; + +/* ------------------------------------------------------------------ */ +/* Types */ +/* ------------------------------------------------------------------ */ + +export interface VulnTableItem { + cve: string; + severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFORMATIONAL"; + description: string; + riskScore: number; + affectedHosts: string[]; + published?: string; + lastModified?: string; + references?: string[]; + cpe?: string[]; + fixed?: boolean; + exploit?: boolean; + selected?: boolean; +} + +interface VulnerabilityCommandTableProps { + data: VulnTableItem[]; + onSelectRow?: (selectedRows: string[]) => void; + onViewDetails?: (cve: string) => void; + onRefresh?: () => void; + selectedRows?: string[]; + isLoading?: boolean; +} + +/* ------------------------------------------------------------------ */ +/* Component */ +/* ------------------------------------------------------------------ */ + +export const VulnerabilityCommandTable = ({ + data, + onSelectRow, + onViewDetails, + selectedRows = [], + isLoading = false, +}: VulnerabilityCommandTableProps) => { + const [sorting, setSorting] = useState([ + { id: "severity", desc: false }, + ]); + const [rowSelection, setRowSelection] = useState({}); + const [expandedRows, setExpandedRows] = useState>({}); + const [hoveredRowIndex, setHoveredRowIndex] = useState(null); + const [focusedRowIndex, setFocusedRowIndex] = useState(null); + const tableContainerRef = useRef(null); + + /* ---- Column definitions ---- */ + const columnHelper = createColumnHelper(); + + const columns = [ + // Checkbox + columnHelper.display({ + id: "select", + header: ({ table }) => ( +
+ { + table.getToggleAllRowsSelectedHandler()(e); + e.stopPropagation(); + }} + onClick={(e) => { + e.stopPropagation(); + e.nativeEvent.stopImmediatePropagation(); + }} + className="h-4 w-4 rounded border-gray-600 bg-gray-800 text-violet-500 focus:ring-violet-500/30" + /> +
+ ), + cell: ({ row }) => ( +
e.stopPropagation()}> + { + e.stopPropagation(); + e.nativeEvent.stopImmediatePropagation(); + setTimeout(() => row.toggleSelected(), 0); + }} + onClick={(e) => { + e.stopPropagation(); + e.nativeEvent.stopImmediatePropagation(); + }} + className="h-4 w-4 rounded border-gray-600 bg-gray-800 text-violet-500 focus:ring-violet-500/30" + /> +
+ ), + size: 40, + }), + + // Severity + columnHelper.accessor("severity", { + header: "Severity", + cell: ({ getValue }) => ( + + ), + size: 100, + enableSorting: true, + }), + + // CVE ID + columnHelper.accessor("cve", { + header: "CVE ID", + cell: ({ getValue }) => ( + + {getValue()} + + ), + size: 140, + }), + + // CVSS Score + columnHelper.accessor("riskScore", { + header: "CVSS", + cell: ({ getValue }) => , + size: 100, + enableSorting: true, + }), + + // Description + columnHelper.accessor("description", { + header: "Description", + cell: ({ getValue, row }) => { + const isExpanded = expandedRows[row.id]; + const text = getValue(); + return ( +
+
+ {text} +
+ {text.length > 120 && ( + + )} +
+ ); + }, + size: 450, + }), + + // Actions + columnHelper.display({ + id: "actions", + header: "", + cell: ({ row }) => { + const rowIndex = parseInt(row.id); + const isHovered = + hoveredRowIndex === row.id || focusedRowIndex === rowIndex; + const cve = row.original.cve; + + return ( +
+ + e.stopPropagation()} + > + + +
+ ); + }, + size: 80, + }), + + // Affected Hosts + columnHelper.accessor("affectedHosts", { + header: "Hosts", + cell: ({ getValue }) => ( +
+ + {getValue().length} + +
+ ), + size: 60, + enableSorting: true, + }), + ] as ColumnDef[]; + + /* ---- Sync external selection ---- */ + const prevSelectedRowsRef = useRef(selectedRows); + + useEffect(() => { + prevSelectedRowsRef.current = selectedRows; + const currentCVEs = Object.keys(rowSelection) + .map((idx) => data[parseInt(idx)]?.cve) + .filter(Boolean); + const changed = + selectedRows.length !== currentCVEs.length || + selectedRows.some((cve) => !currentCVEs.includes(cve)); + + if (changed) { + if (selectedRows.length === 0 && Object.keys(rowSelection).length > 0) { + setRowSelection({}); + } else if (selectedRows.length > 0) { + const sel: RowSelectionState = {}; + selectedRows.forEach((cve) => { + const idx = data.findIndex((item) => item.cve === cve); + if (idx !== -1) sel[idx] = true; + }); + setRowSelection(sel); + } + } + }, [selectedRows, data, rowSelection]); + + /* ---- Selection change callback ---- */ + const handleSelectionChange = useCallback( + (updaterOrValue: Updater) => { + const newSel = + typeof updaterOrValue === "function" + ? updaterOrValue(rowSelection) + : updaterOrValue; + setRowSelection(newSel); + + if (onSelectRow) { + const cves = Object.keys(newSel) + .map((idx) => data[parseInt(idx)]?.cve) + .filter((c): c is string => c !== undefined); + onSelectRow(cves); + } + }, + [data, onSelectRow, rowSelection], + ); + + /* ---- Table instance ---- */ + const table = useReactTable({ + data, + columns, + state: { sorting, rowSelection }, + enableRowSelection: true, + onRowSelectionChange: handleSelectionChange, + onSortingChange: setSorting, + getCoreRowModel: getCoreRowModel(), + getSortedRowModel: getSortedRowModel(), + getFilteredRowModel: getFilteredRowModel(), + }); + + /* ---- Focus container on mount ---- */ + useEffect(() => { + if (tableContainerRef.current && data.length > 0) { + tableContainerRef.current.focus(); + if (focusedRowIndex === null) setFocusedRowIndex(0); + } + }, [data, focusedRowIndex]); + + /* ---- Keyboard navigation ---- */ + const handleKeyDown = (e: React.KeyboardEvent) => { + if (focusedRowIndex === null && data.length > 0) { + setFocusedRowIndex(0); + return; + } + if (focusedRowIndex === null) return; + + switch (e.key) { + case "ArrowDown": + e.preventDefault(); + if (focusedRowIndex < data.length - 1) + setFocusedRowIndex(focusedRowIndex + 1); + break; + case "ArrowUp": + e.preventDefault(); + if (focusedRowIndex > 0) setFocusedRowIndex(focusedRowIndex - 1); + break; + case "Enter": + e.preventDefault(); + if (data[focusedRowIndex]) onViewDetails?.(data[focusedRowIndex].cve); + break; + case " ": + e.preventDefault(); + e.stopPropagation(); + if (focusedRowIndex !== null) { + setTimeout(() => { + table.setRowSelection((prev) => ({ + ...prev, + [focusedRowIndex]: !prev[focusedRowIndex], + })); + }, 0); + } + break; + } + }; + + /* ---- Render ---- */ + return ( +
+ + + {table.getHeaderGroups().map((hg) => ( + + {hg.headers.map((header) => ( + + ))} + + ))} + + + {isLoading ? ( + + + + ) : table.getRowModel().rows.length === 0 ? ( + + + + ) : ( + table.getRowModel().rows.map((row) => { + const rowIndex = parseInt(row.id); + return ( + setHoveredRowIndex(row.id)} + onMouseLeave={() => setHoveredRowIndex(null)} + onClick={(e) => { + const target = e.target as Element; + const isControl = + target instanceof HTMLInputElement || + target instanceof HTMLButtonElement || + target instanceof HTMLAnchorElement || + target.closest?.("input, button, a"); + if (!isControl) { + setFocusedRowIndex(rowIndex); + if (!e.defaultPrevented) row.toggleSelected(); + } + }} + > + {row.getVisibleCells().map((cell) => ( + + ))} + + ); + }) + )} + +
+
+ {flexRender( + header.column.columnDef.header, + header.getContext(), + )} + {header.column.getCanSort() && ( +
+ {header.column.getIsSorted() === "asc" ? ( + + ) : header.column.getIsSorted() === "desc" ? ( + + ) : ( +
+ )} +
+ )} +
+
+
+
+ + Loading vulnerabilities... + +
+
+
+ + + No vulnerabilities found + +
+
+ {flexRender( + cell.column.columnDef.cell, + cell.getContext(), + )} +
+ + {/* Keyboard shortcuts help */} +
+ + ↑↓ + {" "} + Navigate{" "} + + Space + {" "} + Select{" "} + + Enter + {" "} + View Details +
+
+ ); +}; + +export default VulnerabilityCommandTable; diff --git a/sirius-ui/src/components/VulnerabilityDataTable.tsx b/sirius-ui/src/components/VulnerabilityDataTable.tsx new file mode 100755 index 0000000..c669b67 --- /dev/null +++ b/sirius-ui/src/components/VulnerabilityDataTable.tsx @@ -0,0 +1,288 @@ +"use client"; + +import React, { useState, useEffect } from "react"; +import { Button } from "~/components/lib/ui/button"; +import { Input } from "~/components/lib/SearchInput"; +import { + Select, + SelectContent, + SelectItem, + SelectTrigger, + SelectValue, +} from "~/components/lib/ui/select"; + +import { + type ColumnDef, + type ColumnFiltersState, + type SortingState, + flexRender, + getCoreRowModel, + getFilteredRowModel, + getPaginationRowModel, + getSortedRowModel, + useReactTable, +} from "@tanstack/react-table"; + +import { + ChevronLeftIcon, + ChevronRightIcon, + DoubleArrowLeftIcon, + DoubleArrowRightIcon, +} from "@radix-ui/react-icons"; + +import { + Table, + TableBody, + TableCell, + TableHead, + TableHeader, + TableRow, +} from "~/components/lib/ui/table"; +import { useRouter } from "next/router"; + +interface VulnerabilityTableData { + severity: string; + description: string; + cve: string; + cvss: number; + count: number; + published: string; +} + +interface VulnerabilityDataTableProps { + columns: ColumnDef[]; + data: TData[]; +} + +export function VulnerabilityDataTable({ + columns, + data, +}: VulnerabilityDataTableProps) { + const router = useRouter(); + + const [sorting, setSorting] = useState([{ id: "severity", desc: true }]); + const [columnFilters, setColumnFilters] = useState([]); + const [rowSelection, setRowSelection] = useState({}); + const [tableData, setTableData] = useState(data); + + useEffect(() => { + setTableData(data); + }, [data]); + + const handleSearch = (event: React.ChangeEvent) => { + const searchValue = event.target.value.toLowerCase(); + + const filteredRows = data.filter((row) => { + return ( + row.severity.toLowerCase().includes(searchValue) || + row.description.toLowerCase().includes(searchValue) || + row.cve.toLowerCase().includes(searchValue) + ); + }); + + setTableData(filteredRows); + }; + + const handleRowClick = (cve: string) => { + void router.push(`/vulnerability?id=${cve}`); + }; + + const table = useReactTable({ + data: tableData, + columns, + getCoreRowModel: getCoreRowModel(), + getPaginationRowModel: getPaginationRowModel(), + onSortingChange: setSorting, + onColumnFiltersChange: setColumnFilters, + getSortedRowModel: getSortedRowModel(), + getFilteredRowModel: getFilteredRowModel(), + onRowSelectionChange: setRowSelection, + state: { + sorting, + columnFilters, + rowSelection, + }, + }); + + // const rowCount = table.getRowModel().rows; + // console.log('Row count:', rowCount); + + const columnWidths = { + select: "4%", + severity: "3%", + cve: "15%", + description: "80%", + count: "2%", + cvss: "5%", + actions: "1%", + }; + + return ( +
+
+ + +
+
+ + + {table.getHeaderGroups().map((headerGroup) => ( + + {headerGroup.headers.map((header) => { + return ( + + {header.isPlaceholder + ? null + : flexRender( + header.column.columnDef.header, + header.getContext() + )} + + ); + })} + + ))} + + + + {table.getRowModel().rows.length ? ( + table.getRowModel().rows.map((row) => ( + handleRowClick(row.getValue("cve"))} + > + {row.getVisibleCells().map((cell) => ( + + {flexRender( + cell.column.columnDef.cell, + cell.getContext() + )} + + ))} + + )) + ) : ( + + + No results. + + + )} + +
+
+
+
+
+
+

Rows per page

+ +
+
+
+ + + + +
+
+
+
+ ); +} diff --git a/sirius-ui/src/components/VulnerabilityDataTableColumns.tsx b/sirius-ui/src/components/VulnerabilityDataTableColumns.tsx new file mode 100755 index 0000000..01e2ee5 --- /dev/null +++ b/sirius-ui/src/components/VulnerabilityDataTableColumns.tsx @@ -0,0 +1,251 @@ +"use client"; + +import type { ColumnDef } from "@tanstack/react-table"; +import { ArrowUp, ArrowDown } from "lucide-react"; + +import { Button } from "~/components/lib/ui/button"; +import { Checkbox } from "~/components/lib/ui/checkbox"; + +import { + DropdownMenu, + DropdownMenuContent, + DropdownMenuItem, + DropdownMenuLabel, + DropdownMenuSeparator, + DropdownMenuTrigger, +} from "~/components/lib/ui/dropdown-menu"; +import { SeverityBadge } from "./SeverityBadge"; + +// This type is used to define the shape of our data. +// You can use a Zod schema here if you want. +export type VulnerabilityTableData = { + cve: string; + cvss: number; + description: string; + published: string; + severity: string; + count: number; +}; + +const severitySortingFn: SortingFn = (rowA, rowB) => { + const order = ["informational", "low", "medium", "high", "critical"]; + const a = rowA.getValue("severity"); + const b = rowB.getValue("severity"); + + return order.indexOf(a) - order.indexOf(b); +}; + +export const columns: ColumnDef[] = [ + { + id: "select", + header: ({ table }) => ( + table.toggleAllPageRowsSelected(!!value)} + aria-label="Select all" + /> + ), + cell: ({ row }) => ( + row.toggleSelected(!!value)} + aria-label="Select row" + /> + ), + enableSorting: false, + enableHiding: false, + }, + { + accessorKey: "severity", + header: ({ column }) => { + return ( + + ); + }, + sortingFn: severitySortingFn, + cell: ({ row }) => { + const severity = row.getValue("severity"); + const capitalizedSeverity = + severity?.charAt(0).toUpperCase() + severity?.slice(1); + return ; + }, + }, + + { + accessorKey: "cve", + header: ({ column }) => { + return ( + + ); + }, + }, + { + accessorKey: "description", + header: "Description", + // Add width class to control the size + cell: ({ row }) => { + const description = row.getValue("description"); + const truncatedDescription = + description?.length > 50 + ? description?.substring(0, 130) + "..." + : description; + + return
{truncatedDescription}
; + }, + }, + { + accessorKey: "count", + header: ({ column }) => ( + + ), + }, + { + accessorKey: "cvss", + header: ({ column }) => ( + + ), + cell: ({ row }) => ( +
{row.getValue("cvss")}
+ ), + }, + { + id: "actions", + header: "Actions", + cell: ({ row }) => { + const vulnerability = row.original; + + return ( + + +
+ +
+ + + Actions + + void navigator.clipboard.writeText(vulnerability.cve) + } + > + Copy CVE + + + View Vulnerability Details + Mark as Resolved + + + ); + }, + }, +]; diff --git a/sirius-ui/src/components/VulnerabilitySeverityCards.tsx b/sirius-ui/src/components/VulnerabilitySeverityCards.tsx new file mode 100755 index 0000000..7672dde --- /dev/null +++ b/sirius-ui/src/components/VulnerabilitySeverityCards.tsx @@ -0,0 +1,153 @@ +import React from "react"; +import { SEVERITY_COLORS, type SeverityLevel } from "~/utils/severityTheme"; + +/* ------------------------------------------------------------------ */ +/* Severity card order */ +/* ------------------------------------------------------------------ */ + +const SEVERITY_CARD_ORDER: Array<{ + key: SeverityLevel; + label: string; + countKey: string; +}> = [ + { key: "critical", label: "Critical", countKey: "critical" }, + { key: "high", label: "High", countKey: "high" }, + { key: "medium", label: "Medium", countKey: "medium" }, + { key: "low", label: "Low", countKey: "low" }, + { key: "info", label: "Info", countKey: "informational" }, +]; + +/* ------------------------------------------------------------------ */ +/* Shared types */ +/* ------------------------------------------------------------------ */ + +interface VulnerabilitySeverityCardsProps { + counts: { + critical: number; + high: number; + medium: number; + low: number; + informational: number; + }; +} + +/* ------------------------------------------------------------------ */ +/* Single card */ +/* ------------------------------------------------------------------ */ + +const SeverityCard: React.FC<{ + count: number; + label: string; + severityKey: SeverityLevel; +}> = ({ count, label, severityKey }) => { + const colors = SEVERITY_COLORS[severityKey]; + const isEmpty = count === 0; + + return ( +
+ + {count} + + + {label} + +
+ ); +}; + +/* ------------------------------------------------------------------ */ +/* Distribution bar */ +/* ------------------------------------------------------------------ */ + +const DistributionBar: React.FC<{ counts: VulnerabilitySeverityCardsProps["counts"] }> = ({ + counts, +}) => { + const total = + counts.critical + counts.high + counts.medium + counts.low + counts.informational; + if (total === 0) return null; + + return ( +
+ {SEVERITY_CARD_ORDER.map(({ key, countKey }) => { + const value = counts[countKey as keyof typeof counts]; + const pct = total > 0 ? (value / total) * 100 : 0; + return ( +
+ {pct > 0 && ( +
+ )} +
+ ); + })} +
+ ); +}; + +/* ------------------------------------------------------------------ */ +/* Vertical layout */ +/* ------------------------------------------------------------------ */ + +export const VulnerabilitySeverityCardsVertical: React.FC< + VulnerabilitySeverityCardsProps +> = ({ counts }) => { + return ( +
+ {SEVERITY_CARD_ORDER.map(({ key, label, countKey }) => ( + + ))} + +
+ ); +}; + +/* ------------------------------------------------------------------ */ +/* Horizontal (responsive) layout */ +/* ------------------------------------------------------------------ */ + +export const VulnerabilitySeverityCardsHorizontal: React.FC< + VulnerabilitySeverityCardsProps +> = ({ counts }) => { + return ( +
+
+ {SEVERITY_CARD_ORDER.map(({ key, label, countKey }) => ( + + ))} +
+ +
+ ); +}; + +/* ------------------------------------------------------------------ */ +/* Legacy export alias */ +/* ------------------------------------------------------------------ */ + +export const VulnerabilityCount = SeverityCard; diff --git a/sirius-ui/src/components/VulnerabilityTable.tsx b/sirius-ui/src/components/VulnerabilityTable.tsx new file mode 100644 index 0000000..92863dc --- /dev/null +++ b/sirius-ui/src/components/VulnerabilityTable.tsx @@ -0,0 +1,657 @@ +/** + * VulnerabilityTable — v0.4 dark-only generic table with pagination. + * + * Preserves all original functionality: + * - Generic type parameter + * - Pagination, sorting, filtering + * - Row selection with select-all / individual checkboxes + * - Source filter (network/agent) + * - Export (CSV/JSON) + * - Report generation + * - Selection summary + */ + +"use client"; + +import React, { useState, useMemo, useRef, useEffect } from "react"; +import { + flexRender, + getCoreRowModel, + getFilteredRowModel, + getPaginationRowModel, + getSortedRowModel, + useReactTable, + type ColumnDef, + type ColumnFiltersState, +} from "@tanstack/react-table"; +import { cn } from "~/components/lib/utils"; +import { Download, ExternalLink, Bot, Wifi, ChevronUp, ChevronDown } from "lucide-react"; +import { normalizeSeverity } from "~/utils/riskScoreCalculator"; +import { matchesSourceFilter } from "~/utils/tableFilters"; + +/* ------------------------------------------------------------------ */ +/* Props */ +/* ------------------------------------------------------------------ */ + +interface VulnerabilityTableProps { + columns: ColumnDef[]; + data: T[]; + onRowClick?: (row: T) => void; + onRefresh?: () => void; + onSelectionChange?: (selectedRows: T[]) => void; + onGenerateReport?: (selectedRows: T[]) => void; +} + +/* ------------------------------------------------------------------ */ +/* Component */ +/* ------------------------------------------------------------------ */ + +export function VulnerabilityTable({ + columns, + data, + onRowClick, + onSelectionChange, + onGenerateReport, +}: VulnerabilityTableProps) { + const [globalFilter, setGlobalFilter] = useState(""); + const [columnFilters, setColumnFilters] = useState([]); + const [rowSelection, setRowSelection] = useState({}); + const [activeFilters, setActiveFilters] = useState([]); + const [sourceFilter, setSourceFilter] = useState(""); + const [showExportDropdown, setShowExportDropdown] = useState(false); + const exportRef = useRef(null); + + /* ---- Click-outside for export dropdown ---- */ + useEffect(() => { + function handleClickOutside(event: MouseEvent) { + if (exportRef.current && !exportRef.current.contains(event.target as Node)) { + setShowExportDropdown(false); + } + } + document.addEventListener("mousedown", handleClickOutside); + return () => document.removeEventListener("mousedown", handleClickOutside); + }, []); + + /* ---- Selection column ---- */ + const selectionColumn: ColumnDef = { + id: "select", + header: ({ table }) => ( +
+ { + if (input) { + input.indeterminate = + table.getIsSomePageRowsSelected() && + !table.getIsAllPageRowsSelected(); + } + }} + onChange={table.getToggleAllPageRowsSelectedHandler()} + /> +
+ ), + cell: ({ row }) => ( +
e.stopPropagation()}> + +
+ ), + enableSorting: false, + enableGlobalFilter: false, + }; + + /* ---- Pre-filter by source ---- */ + const filteredBySource = useMemo(() => { + if (!sourceFilter) return data; + return data.filter((row) => matchesSourceFilter(row, sourceFilter)); + }, [data, sourceFilter]); + + /* ---- Columns with selection ---- */ + const columnsWithSelection = useMemo( + () => [selectionColumn, ...columns], + [columns], + ); + + /* ---- Table instance ---- */ + const table = useReactTable({ + data: filteredBySource, + columns: columnsWithSelection, + getCoreRowModel: getCoreRowModel(), + getPaginationRowModel: getPaginationRowModel(), + getSortedRowModel: getSortedRowModel(), + getFilteredRowModel: getFilteredRowModel(), + state: { globalFilter, columnFilters, rowSelection }, + onColumnFiltersChange: setColumnFilters, + onGlobalFilterChange: setGlobalFilter, + onRowSelectionChange: (updater) => { + setRowSelection(updater); + if (onSelectionChange) { + const newSel = + typeof updater === "function" ? updater(rowSelection) : updater; + const selected = Object.keys(newSel) + .map((idx) => filteredBySource[parseInt(idx)]) + .filter((item): item is T => item !== undefined); + onSelectionChange(selected); + } + }, + initialState: { + pagination: { pageSize: 10 }, + sorting: [{ id: "severity", desc: true }], + }, + enableRowSelection: true, + }); + + /* ---- Handlers ---- */ + const handleRowClick = (row: T) => { + if (onRowClick) { + onRowClick(row); + } else { + const cveId = row.cve || row.id; + if (cveId) + window.location.href = `/vulnerability?id=${encodeURIComponent(cveId)}`; + } + }; + + const applyFilterPreset = (filter: string) => { + if (activeFilters.includes(filter)) { + setActiveFilters(activeFilters.filter((f) => f !== filter)); + table.getColumn("severity")?.setFilterValue(undefined); + } else { + setActiveFilters([...activeFilters, filter]); + table.getColumn("severity")?.setFilterValue(filter.toUpperCase()); + } + }; + + const handleExport = (format: "csv" | "json") => { + const selectedRows = table.getSelectedRowModel().rows; + const dataToExport = + selectedRows.length > 0 ? selectedRows.map((r) => r.original) : data; + + if (format === "csv") { + const headers = Object.keys(data[0] || {}).join(","); + const csvRows = dataToExport.map((row) => Object.values(row).join(",")); + const csvContent = [headers, ...csvRows].join("\n"); + downloadBlob(csvContent, "text/csv;charset=utf-8;", "vulnerabilities.csv"); + } else { + downloadBlob( + JSON.stringify(dataToExport, null, 2), + "application/json", + "vulnerabilities.json", + ); + } + setShowExportDropdown(false); + }; + + const handleGenerateReport = () => { + const selectedRows = table + .getSelectedRowModel() + .rows.map((r) => r.original); + if (selectedRows.length === 0) { + selectedRows.push( + ...table.getFilteredRowModel().rows.map((r) => r.original), + ); + } + if (onGenerateReport) { + onGenerateReport(selectedRows); + } else { + generateDefaultReport(selectedRows); + } + }; + + /* ---- Selection summary ---- */ + const selectedVulnSummary = useMemo(() => { + const selected = table.getSelectedRowModel().rows; + if (selected.length === 0) return null; + + const counts: Record = { + CRITICAL: 0, + HIGH: 0, + MEDIUM: 0, + LOW: 0, + }; + selected.forEach((row) => { + const sev = normalizeSeverity(row.original.severity || "info").toUpperCase(); + if (sev in counts) counts[sev]!++; + }); + return { count: selected.length, severityCounts: counts }; + }, [table.getSelectedRowModel().rows]); + + /* ---- Filter presets config ---- */ + const filterPresets = [ + { name: "Critical", filter: "critical" }, + { name: "High", filter: "high" }, + { name: "Medium", filter: "medium" }, + { name: "Low", filter: "low" }, + ]; + + /* ---- Render ---- */ + return ( +
+ {/* Controls */} +
+
+
+ {/* Search */} +
+ + + + + setGlobalFilter(e.target.value)} + className="h-9 w-64 rounded-lg border border-violet-500/20 bg-gray-900/50 pl-9 pr-8 text-sm text-white placeholder-gray-500 outline-none focus:border-violet-500/40 focus:ring-1 focus:ring-violet-500/20" + /> + {globalFilter && ( + + )} +
+ + {table.getFilteredRowModel().rows.length} vulnerabilities + +
+ + {/* Export */} +
+ + {showExportDropdown && ( +
+ + +
+ )} +
+
+ + {/* Filter presets */} +
+ {filterPresets.map((preset) => ( + + ))} + + + + + +
+ + {/* Selection summary */} + {selectedVulnSummary && ( +
+
+
+ + {selectedVulnSummary.count} vulnerabilities selected + +
+ {selectedVulnSummary.severityCounts.CRITICAL! > 0 && ( + + {selectedVulnSummary.severityCounts.CRITICAL} Critical + + )} + {selectedVulnSummary.severityCounts.HIGH! > 0 && ( + + {selectedVulnSummary.severityCounts.HIGH} High + + )} + {selectedVulnSummary.severityCounts.MEDIUM! > 0 && ( + + {selectedVulnSummary.severityCounts.MEDIUM} Medium + + )} + {selectedVulnSummary.severityCounts.LOW! > 0 && ( + + {selectedVulnSummary.severityCounts.LOW} Low + + )} +
+
+ +
+
+ )} +
+ + {/* Table */} +
+ + + {table.getHeaderGroups().map((hg) => ( + + {hg.headers.map((header) => ( + + ))} + + ))} + + + {table.getRowModel().rows.length ? ( + table.getRowModel().rows.map((row) => ( + handleRowClick(row.original)} + className="cursor-pointer odd:bg-gray-800/30 even:bg-gray-900/30 transition-colors hover:bg-violet-500/[0.06]" + > + {row.getVisibleCells().map((cell) => ( + + ))} + + )) + ) : ( + + + + )} + +
+
+ {header.isPlaceholder + ? null + : flexRender( + header.column.columnDef.header, + header.getContext(), + )} + {header.column.getCanSort() && ( + + {header.column.getIsSorted() === "asc" ? ( + + ) : header.column.getIsSorted() === "desc" ? ( + + ) : null} + + )} +
+
e.stopPropagation() + : undefined + } + > + {cell.column.id === "actions" ? ( +
+ +
+ ) : ( + flexRender( + cell.column.columnDef.cell, + cell.getContext(), + ) + )} +
+ No vulnerabilities found +
+
+ + {/* Pagination */} +
+
+ + + {table.getState().pagination.pageIndex * + table.getState().pagination.pageSize + + 1} + – + {Math.min( + (table.getState().pagination.pageIndex + 1) * + table.getState().pagination.pageSize, + table.getFilteredRowModel().rows.length, + )}{" "} + of {table.getFilteredRowModel().rows.length} + +
+
+ table.previousPage()} + disabled={!table.getCanPreviousPage()} + > + Previous + + {Array.from( + { length: Math.min(5, table.getPageCount()) }, + (_, i) => ( + table.setPageIndex(i)} + > + {i + 1} + + ), + )} + table.nextPage()} + disabled={!table.getCanNextPage()} + > + Next + +
+
+
+ ); +} + +/* ------------------------------------------------------------------ */ +/* Helpers */ +/* ------------------------------------------------------------------ */ + +function PaginationBtn({ + children, + active, + disabled, + onClick, +}: { + children: React.ReactNode; + active?: boolean; + disabled?: boolean; + onClick: () => void; +}) { + return ( + + ); +} + +function downloadBlob(content: string, type: string, filename: string) { + const blob = new Blob([content], { type }); + const url = URL.createObjectURL(blob); + const link = document.createElement("a"); + link.href = url; + link.download = filename; + link.click(); + URL.revokeObjectURL(url); +} + +function generateDefaultReport>( + selectedData: T[], +) { + const dateStr = new Date().toISOString().split("T")[0]; + const severityGroups: Record = {}; + selectedData.forEach((item) => { + const sev = (item.severity || "UNKNOWN").toUpperCase(); + severityGroups[sev] = (severityGroups[sev] || 0) + 1; + }); + + let html = `Vulnerability Report - ${dateStr} + +

Vulnerability Report — ${dateStr}

+

Summary

${selectedData.length} vulnerabilities

    `; + + for (const [sev, count] of Object.entries(severityGroups)) { + const norm = normalizeSeverity(sev); + html += `
  • ${count} ${norm.charAt(0).toUpperCase() + norm.slice(1)}
    • `; + } + + html += `

Findings

`; + + selectedData.forEach((item) => { + const norm = normalizeSeverity(item.severity || "info"); + const cvss = + typeof item.cvss === "number" + ? item.cvss.toFixed(1) + : typeof item.riskScore === "number" + ? item.riskScore.toFixed(1) + : "?"; + const hosts = Array.isArray(item.affectedHosts) + ? item.affectedHosts.length + : typeof item.count === "number" + ? item.count + : "?"; + html += ``; + }); + + html += `
IDSeverityCVSSHostsDescription
${item.cve || item.id || "Unknown"}${norm.charAt(0).toUpperCase() + norm.slice(1)}${cvss}${hosts}${item.description || ""}

Generated ${new Date().toLocaleString()}

`; + + const blob = new Blob([html], { type: "text/html" }); + const url = URL.createObjectURL(blob); + const a = document.createElement("a"); + a.href = url; + a.download = `vulnerability-report-${dateStr}.html`; + document.body.appendChild(a); + a.click(); + document.body.removeChild(a); + URL.revokeObjectURL(url); +} diff --git a/sirius-ui/src/components/VulnerabilityTableBasic.tsx b/sirius-ui/src/components/VulnerabilityTableBasic.tsx new file mode 100755 index 0000000..a74fff9 --- /dev/null +++ b/sirius-ui/src/components/VulnerabilityTableBasic.tsx @@ -0,0 +1,67 @@ +import React from "react"; + +export interface ColumnDefinition { + /** The column header title. */ + header: string; + /** + * The property key on the data item to display. + * Optional if a custom render function is provided. + */ + accessor?: keyof T; + /** + * Optional custom render function for the cell. + * If provided, this function will be used to render the cell. + */ + render?: (item: T) => React.ReactNode; +} + +export interface DataTableProps { + /** Title for the table (e.g., "Vulnerabilities") */ + title: string; + /** Array of data items to render in the table */ + data: T[]; + /** Definitions for the columns to display */ + columns: ColumnDefinition[]; +} + +const DataTable = ({ title, data, columns }: DataTableProps) => { + return ( +
+

{title}

+ + + + {columns.map((col, index) => ( + + ))} + + + + {data.map((item, rowIndex) => ( + + {columns.map((col, colIndex) => ( + + ))} + + ))} + +
+ {col.header} +
+ {col.render + ? col.render(item) + : col.accessor + ? (item[col.accessor] as unknown as React.ReactNode) + : null} +
+
+ ); +}; + +export default DataTable; \ No newline at end of file diff --git a/sirius-ui/src/components/VulnerabilityTableColumns.tsx b/sirius-ui/src/components/VulnerabilityTableColumns.tsx new file mode 100644 index 0000000..08de3b7 --- /dev/null +++ b/sirius-ui/src/components/VulnerabilityTableColumns.tsx @@ -0,0 +1,9 @@ +/** + * @deprecated — Import from "~/components/vulnerability/VulnColumns" instead. + * This file re-exports for backward compatibility during the v0.4 migration. + */ +export { + vulnColumns as columns, + type VulnTableData, + type VulnTableDataWithSources, +} from "~/components/vulnerability/VulnColumns"; diff --git a/sirius-ui/src/components/VulnerabilityTableSourceColumns.tsx b/sirius-ui/src/components/VulnerabilityTableSourceColumns.tsx new file mode 100644 index 0000000..45c938b --- /dev/null +++ b/sirius-ui/src/components/VulnerabilityTableSourceColumns.tsx @@ -0,0 +1,10 @@ +/** + * @deprecated — Import from "~/components/vulnerability/VulnColumns" instead. + * This file re-exports for backward compatibility during the v0.4 migration. + */ +export { + vulnColumnsWithSources as columnsWithSources, + type VulnTableDataWithSources, + sourceFilterOptions, + confidenceFilterOptions, +} from "~/components/vulnerability/VulnColumns"; diff --git a/sirius-ui/src/components/VulnerabilityTableViews.tsx b/sirius-ui/src/components/VulnerabilityTableViews.tsx new file mode 100644 index 0000000..5462622 --- /dev/null +++ b/sirius-ui/src/components/VulnerabilityTableViews.tsx @@ -0,0 +1,156 @@ +import React, { useState } from "react"; +import { cn } from "~/components/lib/utils"; +import VulnerabilityCommandTable, { + type VulnTableItem, +} from "~/components/VulnerabilityCommandTable"; +import { Button } from "~/components/lib/ui/button"; +import { ViewModeSelector } from "~/components/ViewModeSelector"; + +// Type definition for view mode +export type ViewMode = "table" | "command" | "grouped"; + +// Interface for any vulnerability item that can be displayed in tables +export interface VulnerabilityViewItem { + id: string; // Unique identifier (could be cve, vid, etc.) + title?: string; // Title or name of the vulnerability + description: string; // Description text + severity: string; // Severity level + riskScore: number; // Risk score (CVSS or equivalent) + affectedHosts?: string[] | number; // Hosts affected (either list or count) + published?: string; // Publication date + lastModified?: string; // Last modified date + references?: string[]; // Reference links + [key: string]: any; // Allow for additional properties +} + +// Common props for all vulnerability view components +interface VulnerabilityViewProps { + data: VulnerabilityViewItem[]; + selectedItems?: string[]; + onSelectItems?: (ids: string[]) => void; + onViewDetails?: (id: string) => void; + isLoading?: boolean; + viewMode: ViewMode; +} + +// Convert generic vulnerability items to the specific format needed by VulnerabilityCommandTable +const convertToCommandTableFormat = ( + items: VulnerabilityViewItem[] +): VulnTableItem[] => { + return items.map((item) => ({ + cve: item.id, + severity: item.severity as any, + description: item.description, + riskScore: item.riskScore, + affectedHosts: Array.isArray(item.affectedHosts) + ? item.affectedHosts + : typeof item.affectedHosts === "number" + ? Array(item.affectedHosts).fill("") + : [], + published: item.published || "", + lastModified: item.lastModified, + references: item.references, + selected: false, + })); +}; + +// Main vulnerability view component that handles different view modes +export const VulnerabilityView: React.FC = ({ + data, + selectedItems = [], + onSelectItems, + onViewDetails, + isLoading = false, + viewMode, +}) => { + // Convert data to the format needed by the specific view components + const commandTableData = convertToCommandTableFormat(data); + + // Handle row selection + const handleSelectRows = (ids: string[]) => { + if (onSelectItems) { + onSelectItems(ids); + } + }; + + // Handle view details request + const handleViewDetails = (id: string) => { + if (onViewDetails) { + onViewDetails(id); + } + }; + + // Render the appropriate view based on viewMode + switch (viewMode) { + case "command": + return ( + + ); + case "table": + // Placeholder for standard table view - to be implemented + return ( +
+

Standard table view is not implemented yet.

+

+ Please use Command Table view for now. +

+
+ ); + case "grouped": + // Placeholder for grouped view - to be implemented + return ( +
+

Grouped view is not implemented yet.

+

+ Please use Command Table view for now. +

+
+ ); + default: + return null; + } +}; + +// Complete vulnerability table component with view selector and main view +export const VulnerabilityTableWithViewSelector: React.FC< + Omit & { + initialViewMode?: ViewMode; + className?: string; + } +> = ({ + data, + selectedItems, + onSelectItems, + onViewDetails, + isLoading, + initialViewMode = "command", + className, +}) => { + const [viewMode, setViewMode] = useState(initialViewMode); + + return ( +
+
+ +
+
+ +
+
+ ); +}; + +export default VulnerabilityView; diff --git a/sirius-ui/src/components/VulnerabilityTimeline.tsx b/sirius-ui/src/components/VulnerabilityTimeline.tsx new file mode 100644 index 0000000..690d0a4 --- /dev/null +++ b/sirius-ui/src/components/VulnerabilityTimeline.tsx @@ -0,0 +1,351 @@ +"use client"; + +import React, { useMemo } from "react"; +import { cn } from "~/components/lib/utils"; +import { getSourceColor, SourceBadge } from "~/components/shared/SourceBadge"; +import { getSeverityColors } from "~/utils/severityTheme"; +import { + Clock, + Shield, + AlertTriangle, + CheckCircle, + XCircle, +} from "lucide-react"; +import { + type VulnTableDataWithSources, + type SourceAttribution, +} from "./VulnerabilityTableSourceColumns"; + +interface TimelineEvent { + id: string; + type: "discovery" | "confirmation" | "status_change"; + date: Date; + source: string; + source_version: string; + vulnerability: VulnTableDataWithSources; + confidence: number; + status: string; + notes?: string; +} + +interface VulnerabilityTimelineProps { + vulnerabilities: VulnTableDataWithSources[]; + className?: string; + showConfidence?: boolean; + groupBySource?: boolean; + dateRange?: { + start?: Date; + end?: Date; + }; +} + +export const VulnerabilityTimeline: React.FC = ({ + vulnerabilities, + className, + showConfidence = true, + groupBySource = false, + dateRange, +}) => { + // Generate timeline events from vulnerability data + const timelineEvents = useMemo(() => { + const events: TimelineEvent[] = []; + + vulnerabilities.forEach((vuln) => { + if (!vuln.sources || vuln.sources.length === 0) return; + + vuln.sources.forEach((source) => { + // Discovery event (first_seen) + const discoveryDate = new Date(source.first_seen); + if ( + !dateRange || + ((!dateRange.start || discoveryDate >= dateRange.start) && + (!dateRange.end || discoveryDate <= dateRange.end)) + ) { + events.push({ + id: `${vuln.cve}-${source.source}-discovery`, + type: "discovery", + date: discoveryDate, + source: source.source, + source_version: source.source_version, + vulnerability: vuln, + confidence: source.confidence, + status: source.status, + notes: source.notes, + }); + } + + // Confirmation event (last_seen, if different from first_seen) + const confirmationDate = new Date(source.last_seen); + if (confirmationDate.getTime() !== discoveryDate.getTime()) { + if ( + !dateRange || + ((!dateRange.start || confirmationDate >= dateRange.start) && + (!dateRange.end || confirmationDate <= dateRange.end)) + ) { + events.push({ + id: `${vuln.cve}-${source.source}-confirmation`, + type: "confirmation", + date: confirmationDate, + source: source.source, + source_version: source.source_version, + vulnerability: vuln, + confidence: source.confidence, + status: source.status, + notes: source.notes, + }); + } + } + }); + }); + + // Sort events by date + return events.sort((a, b) => a.date.getTime() - b.date.getTime()); + }, [vulnerabilities, dateRange]); + + // Group events by date for better visualization + const groupedEvents = useMemo(() => { + const groups: Record = {}; + + timelineEvents.forEach((event) => { + const dateKey = event.date.toDateString(); + if (!groups[dateKey]) { + groups[dateKey] = []; + } + groups[dateKey]!.push(event); + }); + + return Object.entries(groups).map(([date, events]) => ({ + date: new Date(date), + events: events.sort((a, b) => a.date.getTime() - b.date.getTime()), + })); + }, [timelineEvents]); + + const getSeverityColor = (severity: string) => + getSeverityColors(severity).text; + + const getEventIcon = (event: TimelineEvent) => { + switch (event.type) { + case "discovery": + return ; + case "confirmation": + return ; + case "status_change": + return ; + default: + return ; + } + }; + + const formatTime = (date: Date) => { + return date.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }); + }; + + const formatDate = (date: Date) => { + return date.toLocaleDateString([], { + weekday: "short", + month: "short", + day: "numeric", + year: "numeric", + }); + }; + + if (timelineEvents.length === 0) { + return ( +
+
+ +

+ No timeline events found for the selected criteria +

+
+
+ ); + } + + return ( +
+ {/* Timeline Header */} +
+
+ +

+ Vulnerability Timeline +

+
+
+ {timelineEvents.length} events across {groupedEvents.length} days +
+
+ + {/* Timeline */} +
+ {/* Timeline line */} +
+ + {/* Timeline events */} +
+ {groupedEvents.map((group, groupIndex) => ( +
+ {/* Date marker */} +
+
+ + {formatDate(group.date)} + +
+
+
+ + {/* Events for this date */} +
+ {group.events.map((event, eventIndex) => ( +
+ {/* Event marker */} +
+
{getEventIcon(event)}
+
+ + {/* Event content */} +
+
+
+
+ + {event.vulnerability.cve} + + + {event.vulnerability.severity} + + + {formatTime(event.date)} + +
+ +

+ {event.vulnerability.description} +

+ +
+
+ Source: + +
+ + {showConfidence && ( +
+ + = 0.9 + ? "text-emerald-400" + : event.confidence >= 0.7 + ? "text-yellow-400" + : "text-red-400", + )} + > + {(event.confidence * 100).toFixed(0)}% + +
+ )} + +
+ Type: + + {event.type.replace("_", " ")} + +
+
+ + {event.notes && ( +
+ Notes:{" "} + {event.notes} +
+ )} +
+ + {/* Risk score */} +
+
+
+ {event.vulnerability.riskScore.toFixed(1)} +
+
CVSS
+
+
+
= 9.0 + ? "bg-red-500" + : event.vulnerability.riskScore >= 7.0 + ? "bg-orange-500" + : event.vulnerability.riskScore >= 4.0 + ? "bg-amber-500" + : "bg-green-500", + )} + style={{ + height: `${Math.min( + event.vulnerability.riskScore * 10, + 100, + )}%`, + marginTop: `${ + 100 - + Math.min( + event.vulnerability.riskScore * 10, + 100, + ) + }%`, + }} + >
+
+
+
+
+
+ ))} +
+
+ ))} +
+
+ + {/* Timeline Legend */} +
+
+ + Discovery +
+
+ + Confirmation +
+
+ + Status Change +
+
+
+ ); +}; + +export default VulnerabilityTimeline; diff --git a/sirius-ui/src/components/agent/AgentCard.tsx b/sirius-ui/src/components/agent/AgentCard.tsx new file mode 100644 index 0000000..6533927 --- /dev/null +++ b/sirius-ui/src/components/agent/AgentCard.tsx @@ -0,0 +1,96 @@ +import React, { useCallback } from "react"; +import { useRouter } from "next/router"; +import { cn } from "~/components/lib/utils"; +import type { AgentWithHost } from "~/server/api/routers/agent"; +import { ExternalLinkIcon } from "lucide-react"; + +// Use the proper agent type +type Agent = AgentWithHost; + +interface AgentCardProps { + agent: Agent; + isSelected: boolean; + onClick: () => void; +} + +export const AgentCard: React.FC = ({ + agent, + isSelected, + onClick, +}) => { + const router = useRouter(); + const isOnline = agent.status?.toLowerCase() === "online"; + + // Use real host data if available, fallback to basic info + const displayInfo = { + ip: agent.host?.ip || "No IP available", + os: + agent.host?.os && agent.host?.osVersion + ? `${agent.host.os} ${agent.host.osVersion}` + : agent.host?.os || "Unknown OS", + }; + + const handleHostNavigation = useCallback( + (e: React.MouseEvent) => { + e.stopPropagation(); // Prevent triggering the agent selection + + // Ensure we're on the client side and have a valid IP + if (typeof window !== "undefined" && agent.host?.ip) { + router.push(`/host/${agent.host.ip}`); + } + }, + [router, agent.host?.ip] + ); + + return ( + +
+ + ); +}; diff --git a/sirius-ui/src/components/agent/AgentDetails.tsx b/sirius-ui/src/components/agent/AgentDetails.tsx new file mode 100644 index 0000000..721801f --- /dev/null +++ b/sirius-ui/src/components/agent/AgentDetails.tsx @@ -0,0 +1,261 @@ +import React from "react"; +import { api } from "~/utils/api"; +import { cn } from "~/components/lib/utils"; +import { + Card, + CardContent, + CardHeader, + CardTitle, + CardFooter, +} from "~/components/lib/ui/card"; // Reverting path +import { Skeleton } from "~/components/lib/ui/skeleton"; // Reverting path +import { Button } from "~/components/lib/ui/button"; // Reverting path for Button +import { RefreshCwIcon } from "lucide-react"; // Added icon +import type { DisplayedAgentDetails } from "~/components/console/types"; +import { toast } from "sonner"; // Re-import toast +import { CopyIcon, ScanLineIcon } from "lucide-react"; // Icon for copy button & scan button + +// Define the expected shape of the parsed agent status details +// Based on the `internal:status` output format +// export type ParsedAgentStatus = { // No longer needed here +// ... +// }; + +interface AgentDetailsProps { + agentId: string | null; // Still needed to know *which* agent we're showing details for + details: DisplayedAgentDetails | null; // Use the combined details type + isLoading: boolean; // Loading state passed from parent (during command execution) + onRefresh: () => void; // Callback to trigger refresh + onRunScan: () => void; // Add callback for running scan +} + +const DetailRow: React.FC<{ label: string; value: React.ReactNode }> = ({ + label, + value, +}) => { + if (value === null || value === undefined || value === "") { + return null; // Don't render row if value is empty + } + return ( +
+ + {label} + + + {value} + +
+ ); +}; + +const AgentDetailsSkeleton: React.FC = () => ( + + +
+ + {/* Placeholder for refresh button */} +
+ + + + + + + + + + +); + +// Original component function +const AgentDetailsComponent: React.FC = ({ + agentId, + details, + isLoading, + onRefresh, + onRunScan, +}) => { + const formatLastSeen = (isoString: string | null | undefined): string => { + if (!isoString) return "Never"; + try { + const date = new Date(isoString); + // Simple relative time (replace with a library like date-fns for more accuracy) + const seconds = Math.round((Date.now() - date.getTime()) / 1000); + if (seconds < 60) return `${seconds}s ago`; + const minutes = Math.round(seconds / 60); + if (minutes < 60) return `${minutes}m ago`; + const hours = Math.round(minutes / 60); + if (hours < 24) return `${hours}h ago`; + // Fallback to locale string for older dates + return date.toLocaleString(); + } catch (e) { + return "Invalid Date"; + } + }; + + // Helper to copy text (moved here from AgentList) + const copyToClipboard = (text: string | undefined | null, label: string) => { + if (!text) { + toast.error(`Cannot copy empty ${label}`); + return; + } + navigator.clipboard + .writeText(text) + .then(() => { + console.log(`${label} copied to clipboard:`, text); + toast.success(`${label} copied!`); + }) + .catch((err) => { + console.error(`Failed to copy ${label}:`, err); + toast.error(`Failed to copy ${label}`); + }); + }; + + if (!agentId) { + // Handle case where no agent is selected *at all* + return ( +
+ Select an agent to view details. +
+ ); + } + + // Show skeleton only if loading AND we don't have any details yet + if (isLoading && !details) { + return ; + } + + // Show refresh prompt if an agent *is* selected, but we have no details (and not loading) + if (!details) { + return ( + + +
+ {/* Use agentId prop here as details is null */} + + {`Agent (${agentId.substring(0, 8)}...)`} + + +
+ + + No details available. Click refresh. + + + ); + } + + // We have details now + const isOnline = details.status?.toLowerCase() === "online"; + + return ( + + +
+ {/* Display Agent Name if available, fallback to ID from details */} + + {details.name || `Agent (${details.id.substring(0, 8)}...)`} + + +
+ {/* Status Badge + Last Seen */} +
+ {" "} + {/* Reduced gap */} + + + {isOnline + ? "Online" + : `Offline (${formatLastSeen(details.lastSeen)})`} + +
+ + + {/* Essential Information Only - IP and OS */} +
+ + + {details.osVersion || details.osArch || "Not available"} + + } + /> +
+ + + + + + + ); +}; + +// Wrap the component with React.memo +export const AgentDetails = React.memo(AgentDetailsComponent); diff --git a/sirius-ui/src/components/agent/AgentList.tsx b/sirius-ui/src/components/agent/AgentList.tsx new file mode 100644 index 0000000..41fe313 --- /dev/null +++ b/sirius-ui/src/components/agent/AgentList.tsx @@ -0,0 +1,143 @@ +import React, { useState, useMemo } from "react"; +import { api } from "~/utils/api"; +import { cn } from "~/components/lib/utils"; +import { Input } from "~/components/lib/ui/input"; +import { AgentCard } from "./AgentCard"; +import type { AgentWithHost } from "~/server/api/routers/agent"; +// import { +// ContextMenu, +// ContextMenuContent, +// ContextMenuItem, +// ContextMenuTrigger, +// ContextMenuSeparator, +// } from "~/components/lib/ui/context-menu"; // Reverted path +// import { toast } from "sonner"; + +// Use the proper type from the agent router +type Agent = AgentWithHost; + +interface AgentListProps { + onAgentSelect: (agentId: string) => void; // Callback when an agent is selected + selectedAgentId?: string | null; // Optional prop to highlight the selected agent +} + +export const AgentList: React.FC = ({ + onAgentSelect, + selectedAgentId, +}) => { + const { + data: agents, + isLoading, + error, + } = api.agent.listAgentsWithHosts.useQuery(undefined, { + refetchInterval: 10000, // Poll every 10 seconds + }); + + const [searchTerm, setSearchTerm] = useState(""); + + const handleSelectAgent = (agentId: string) => { + onAgentSelect(agentId); + }; + + // Helper to copy text + // const copyToClipboard = (text: string, label: string) => { + // navigator.clipboard + // .writeText(text) + // .then(() => { + // console.log(`${label} copied to clipboard:`, text); + // toast.success(`${label} copied!`); // Use toast for feedback + // }) + // .catch((err) => { + // console.error(`Failed to copy ${label}:`, err); + // toast.error(`Failed to copy ${label}`); + // }); + // }; + + const filteredAgents = useMemo(() => { + if (!agents) return []; + if (!searchTerm) return agents; + + const lowerCaseSearchTerm = searchTerm.toLowerCase(); + return agents.filter( + (agent) => + agent.id.toLowerCase().includes(lowerCaseSearchTerm) || + agent.name?.toLowerCase().includes(lowerCaseSearchTerm) || + agent.host?.hostname?.toLowerCase().includes(lowerCaseSearchTerm) || + agent.host?.ip?.toLowerCase().includes(lowerCaseSearchTerm) + ); + }, [agents, searchTerm]); + + if (isLoading && !agents) { + return ( +
+ Loading agents... +
+ ); + } + + if (error) { + return ( +
+ Error loading agents: {error.message} +
+ ); + } + + if (!agents || agents.length === 0) { + return ( +
+ No agents found. +
+ ); + } + + return ( +
+ {/* Search Input - Only show for 5+ agents */} + {agents && agents.length >= 5 && ( +
+ setSearchTerm(e.target.value)} + className="h-8 text-sm" // Make input slightly smaller + /> +
+ )} + + {/* Agent List (Scrollable) */} +
+ {/* Display message if loading takes time but we have stale data */} + {isLoading && agents && ( +
Updating...
+ )} + {/* Display message if no agents match filter */} + {!isLoading && filteredAgents.length === 0 && ( +
+ {searchTerm ? "No matching agents" : "No agents available"} +
+ )} + {/* Map over filtered agents using AgentCard */} + {filteredAgents.map((agent) => { + const isSelected = agent.id === selectedAgentId; + + return ( + handleSelectAgent(agent.id)} + /> + ); + })} +
+ {/* Optional Footer/Actions */} + {/*
+ +
*/} +
+ ); +}; diff --git a/sirius-ui/src/components/agent/AgentSummary.tsx b/sirius-ui/src/components/agent/AgentSummary.tsx new file mode 100644 index 0000000..9cbe1d0 --- /dev/null +++ b/sirius-ui/src/components/agent/AgentSummary.tsx @@ -0,0 +1,54 @@ +import React, { useMemo } from "react"; + +// Re-using the Agent type definition, potentially move to a shared types file later +type Agent = { + id: string; + name?: string | null; + status?: string | null; + lastSeen?: string | null; +}; + +interface AgentSummaryProps { + agents: Agent[] | null | undefined; // Accept null/undefined during loading/error + isLoading: boolean; +} + +export const AgentSummary: React.FC = ({ + agents, + isLoading, +}) => { + const summary = useMemo(() => { + if (!agents) { + return { totalAgents: 0, onlineAgents: 0 }; + } + const totalAgents = agents.length; + const onlineAgents = agents.filter( + (agent) => agent.status?.toLowerCase() === "online" + ).length; + return { totalAgents, onlineAgents }; + }, [agents]); + + // Simplified display, similar to environment.tsx cards but more compact for a sidebar + return ( +
+
+
+
+ Total +
+
+ {isLoading ? "-" : summary.totalAgents} +
+
+
+
+ Online +
+
+ {isLoading ? "-" : summary.onlineAgents} +
+
+
+
+ ); +}; diff --git a/sirius-ui/src/components/auth/AuthGuard.tsx b/sirius-ui/src/components/auth/AuthGuard.tsx new file mode 100644 index 0000000..749e3e7 --- /dev/null +++ b/sirius-ui/src/components/auth/AuthGuard.tsx @@ -0,0 +1,87 @@ +import React from "react"; +import { useSession } from "next-auth/react"; +import { useRouter } from "next/router"; +import { useEffect } from "react"; +import { isAuthenticated } from "~/utils/auth"; + +interface AuthGuardProps { + children: React.ReactNode; + fallback?: React.ReactNode; + redirectTo?: string; +} + +/** + * AuthGuard component to protect authenticated routes + * Automatically redirects unauthenticated users to login page + */ +export const AuthGuard: React.FC = ({ + children, + fallback, + redirectTo = "/", +}) => { + const { data: session, status } = useSession(); + const router = useRouter(); + + useEffect(() => { + if (status === "loading") return; // Still loading + + if (!isAuthenticated(session)) { + void router.push(redirectTo); + } + }, [session, status, router, redirectTo]); + + // Show loading state + if (status === "loading") { + return ( + fallback || ( +
+
+
+

Loading...

+
+
+ ) + ); + } + + // Don't render children if not authenticated + if (!isAuthenticated(session)) { + return null; + } + + return <>{children}; +}; + +/** + * Hook to check authentication status + */ +export const useAuthGuard = () => { + const { data: session, status } = useSession(); + const router = useRouter(); + + const redirectToLogin = (returnUrl?: string) => { + const loginUrl = returnUrl + ? `/?return=${encodeURIComponent(returnUrl)}` + : "/"; + void router.push(loginUrl); + }; + + const requireAuth = (redirectUrl?: string) => { + if (status === "loading") return false; + + if (!isAuthenticated(session)) { + redirectToLogin(redirectUrl || router.asPath); + return false; + } + + return true; + }; + + return { + isAuthenticated: isAuthenticated(session), + isLoading: status === "loading", + session, + redirectToLogin, + requireAuth, + }; +}; diff --git a/sirius-ui/src/components/auth/LoginInput.tsx b/sirius-ui/src/components/auth/LoginInput.tsx new file mode 100644 index 0000000..224aa5d --- /dev/null +++ b/sirius-ui/src/components/auth/LoginInput.tsx @@ -0,0 +1,98 @@ +import React from "react"; +import { cn } from "~/components/lib/utils"; + +interface LoginInputProps extends React.InputHTMLAttributes { + label: string; + error?: string; + isLoading?: boolean; +} + +/** + * Reusable input component for authentication forms + * Follows the established design patterns of the Sirius UI + */ +export const LoginInput: React.FC = ({ + label, + error, + isLoading = false, + className, + id, + ...props +}) => { + const inputId = id || `input-${label.toLowerCase().replace(/\s+/g, "-")}`; + + return ( +
+ + + {error && ( + + )} +
+ ); +}; + +interface LoginCheckboxProps + extends React.InputHTMLAttributes { + label: string; + isLoading?: boolean; +} + +/** + * Reusable checkbox component for authentication forms + */ +export const LoginCheckbox: React.FC = ({ + label, + isLoading = false, + className, + id, + ...props +}) => { + const inputId = id || `checkbox-${label.toLowerCase().replace(/\s+/g, "-")}`; + + return ( + + ); +}; diff --git a/sirius-ui/src/components/console/AgentCardV2.tsx b/sirius-ui/src/components/console/AgentCardV2.tsx new file mode 100644 index 0000000..97e8ec3 --- /dev/null +++ b/sirius-ui/src/components/console/AgentCardV2.tsx @@ -0,0 +1,184 @@ +import React, { useCallback, useMemo } from "react"; +import { useRouter } from "next/router"; +import { cn } from "~/components/lib/utils"; +import { + ExternalLink, + CheckSquare, + Square, + Clock, + StickyNote, + Tag, + X, +} from "lucide-react"; +import type { Agent } from "./types"; + +// ─── Stale detection (Phase 1.4) ──────────────────────────────────────────── + +export type AgentFreshness = "online" | "stale" | "offline"; + +export function getAgentFreshness(agent: Agent): AgentFreshness { + if (agent.status?.toLowerCase() !== "online") return "offline"; + if (!agent.lastSeen) return "online"; + const elapsed = Date.now() - new Date(agent.lastSeen).getTime(); + if (elapsed > 30 * 60 * 1000) return "offline"; // > 30 min + if (elapsed > 5 * 60 * 1000) return "stale"; // > 5 min + return "online"; +} + +// ─── Component ────────────────────────────────────────────────────────────── + +interface AgentCardV2Props { + agent: Agent; + isSelected: boolean; + isMultiSelected?: boolean; + multiSelectMode?: boolean; + tags?: string[]; + hasNote?: boolean; + onClick: () => void; + onMultiSelectToggle?: () => void; + onContextMenu?: (e: React.MouseEvent) => void; + onRemoveTag?: (tag: string) => void; +} + +export const AgentCardV2: React.FC = ({ + agent, + isSelected, + isMultiSelected = false, + multiSelectMode = false, + tags, + hasNote, + onClick, + onMultiSelectToggle, + onContextMenu, + onRemoveTag, +}) => { + const router = useRouter(); + const freshness = useMemo(() => getAgentFreshness(agent), [agent]); + + const displayName = agent.host?.hostname || agent.name || agent.id; + const displayIp = agent.host?.ip || "No IP"; + const displayOs = agent.host?.os || "Unknown"; + + const handleHostNavigation = useCallback( + (e: React.MouseEvent) => { + e.stopPropagation(); + if (typeof window !== "undefined" && agent.host?.ip) { + void router.push(`/host/${agent.host.ip}`); + } + }, + [router, agent.host?.ip] + ); + + const handleCheckboxClick = useCallback( + (e: React.MouseEvent) => { + e.stopPropagation(); + onMultiSelectToggle?.(); + }, + [onMultiSelectToggle] + ); + + const statusDotClasses = useMemo(() => { + switch (freshness) { + case "online": + return "bg-emerald-400 shadow-[0_0_6px_rgba(52,211,153,0.4)]"; + case "stale": + return "bg-amber-400 shadow-[0_0_6px_rgba(251,191,36,0.3)]"; + case "offline": + return "bg-red-400 shadow-[0_0_6px_rgba(248,113,113,0.3)]"; + } + }, [freshness]); + + return ( + + )} + + {/* Status indicator */} +
+
+ {freshness === "stale" && ( + + )} +
+ + {/* Agent info */} +
+
+ + {displayName} + + {hasNote && ( + + )} +
+
+ {displayIp} · {displayOs} +
+
+ + {/* Host link */} + +
+ + {/* Tags row */} + {tags && tags.length > 0 && ( +
+ {tags.map((tag) => ( + + + {tag} + {onRemoveTag && ( + + )} + + ))} +
+ )} + + ); +}; diff --git a/sirius-ui/src/components/console/AgentContextMenu.tsx b/sirius-ui/src/components/console/AgentContextMenu.tsx new file mode 100644 index 0000000..99a41c2 --- /dev/null +++ b/sirius-ui/src/components/console/AgentContextMenu.tsx @@ -0,0 +1,128 @@ +import React, { useEffect, useRef, useCallback } from "react"; +import { + Crosshair, + ScanLine, + Activity, + ExternalLink, + Copy, + Tag, + StickyNote, +} from "lucide-react"; + +interface ContextMenuPosition { + x: number; + y: number; +} + +interface AgentContextMenuProps { + agentId: string; + agentName: string; + agentIp?: string; + position: ContextMenuPosition; + onClose: () => void; + onSelect: () => void; + onRunScan: () => void; + onCheckStatus: () => void; + onViewHost: () => void; + onCopyIp: () => void; + onCopyId: () => void; + onAddTag: () => void; + onAddNote: () => void; +} + +export const AgentContextMenu: React.FC = ({ + position, + onClose, + onSelect, + onRunScan, + onCheckStatus, + onViewHost, + onCopyIp, + onCopyId, + onAddTag, + onAddNote, +}) => { + const menuRef = useRef(null); + + useEffect(() => { + const handleClickOutside = (e: MouseEvent) => { + if (menuRef.current && !menuRef.current.contains(e.target as Node)) { + onClose(); + } + }; + const handleEsc = (e: KeyboardEvent) => { + if (e.key === "Escape") onClose(); + }; + document.addEventListener("mousedown", handleClickOutside); + document.addEventListener("keydown", handleEsc); + return () => { + document.removeEventListener("mousedown", handleClickOutside); + document.removeEventListener("keydown", handleEsc); + }; + }, [onClose]); + + // Adjust position to stay within viewport + const adjustedPosition = useCallback(() => { + const menuWidth = 200; + const menuHeight = 320; + let x = position.x; + let y = position.y; + if (x + menuWidth > window.innerWidth) x = window.innerWidth - menuWidth - 8; + if (y + menuHeight > window.innerHeight) y = window.innerHeight - menuHeight - 8; + return { x, y }; + }, [position]); + + const pos = adjustedPosition(); + + const items = [ + { icon: Crosshair, label: "Select", action: onSelect }, + { icon: ScanLine, label: "Run Scan", action: onRunScan }, + { icon: Activity, label: "Check Status", action: onCheckStatus }, + { type: "separator" as const }, + { icon: ExternalLink, label: "View Host Page", action: onViewHost }, + { icon: Copy, label: "Copy IP", action: onCopyIp }, + { icon: Copy, label: "Copy Agent ID", action: onCopyId }, + { type: "separator" as const }, + { icon: Tag, label: "Add Tag", action: onAddTag }, + { icon: StickyNote, label: "Add Note", action: onAddNote }, + ]; + + return ( +
+
+ {items.map((item, i) => { + if ("type" in item && item.type === "separator") { + return ( +
+ ); + } + const { icon: Icon, label, action } = item as { + icon: React.ElementType; + label: string; + action: () => void; + }; + return ( + + ); + })} +
+
+ ); +}; diff --git a/sirius-ui/src/components/console/AgentDetailView.tsx b/sirius-ui/src/components/console/AgentDetailView.tsx new file mode 100644 index 0000000..8355acb --- /dev/null +++ b/sirius-ui/src/components/console/AgentDetailView.tsx @@ -0,0 +1,351 @@ +import React, { useState, useCallback } from "react"; +import { cn } from "~/components/lib/utils"; +import { + ScanLine, + Copy, + ExternalLink, + StickyNote, + Tag, + Plus, + X, + Server, + Globe, + Shield, + Cpu, + HardDrive, + Clock, + UserCog, + Pencil, + Check, +} from "lucide-react"; +import { toast } from "sonner"; +import type { DisplayedAgentDetails } from "./types"; + +interface AgentDetailViewProps { + agentId: string | null; + details: DisplayedAgentDetails | null; + tags: string[]; + note: string; + onRunScan: () => void; + onViewHost: () => void; + onAddTag: (tag: string) => void; + onRemoveTag: (tag: string) => void; + onSetNote: (note: string) => void; + onCopyId: () => void; +} + +export const AgentDetailView: React.FC = ({ + agentId, + details, + tags, + note, + onRunScan, + onViewHost, + onAddTag, + onRemoveTag, + onSetNote, + onCopyId, +}) => { + const [addingTag, setAddingTag] = useState(false); + const [tagInput, setTagInput] = useState(""); + const [editingNote, setEditingNote] = useState(false); + const [noteInput, setNoteInput] = useState(note); + + // Sync note input when note prop changes (different agent selected) + React.useEffect(() => { + setNoteInput(note); + setEditingNote(false); + }, [note, agentId]); + + const handleAddTag = useCallback(() => { + if (tagInput.trim()) { + onAddTag(tagInput.trim().toLowerCase()); + setTagInput(""); + setAddingTag(false); + } + }, [tagInput, onAddTag]); + + const handleSaveNote = useCallback(() => { + onSetNote(noteInput); + setEditingNote(false); + }, [noteInput, onSetNote]); + + const formatLastSeen = (isoString: string | null | undefined): string => { + if (!isoString) return "Never"; + try { + const date = new Date(isoString); + const seconds = Math.round((Date.now() - date.getTime()) / 1000); + if (seconds < 60) return `${seconds}s ago`; + const minutes = Math.round(seconds / 60); + if (minutes < 60) return `${minutes}m ago`; + const hours = Math.round(minutes / 60); + if (hours < 24) return `${hours}h ago`; + return date.toLocaleString(); + } catch { + return "Invalid Date"; + } + }; + + // ── Empty state ────────────────────────────────────────────────────────── + if (!agentId || !details) { + return ( +
+ +

No Agent Selected

+

+ Select an agent from the sidebar to view its details, manage tags, and + add notes. +

+
+ ); + } + + const isOnline = details.status?.toLowerCase() === "online"; + + // ── Full agent detail panel ────────────────────────────────────────────── + return ( +
+ {/* ── Header ─────────────────────────────────────────────────────────── */} +
+
+
+
+
+ +
+
+

+ {details.name || details.id} +

+
+
+ + {isOnline + ? "Online" + : `Offline — last seen ${formatLastSeen(details.lastSeen)}`} + +
+
+
+
+ + {/* Action buttons */} +
+ + + +
+
+
+ + {/* ── Content ────────────────────────────────────────────────────────── */} +
+ {/* System Info */} +
+ +
+ + + + + + +
+
+ + {/* Tags */} +
+ 0 ? String(tags.length) : undefined} + /> +
+ {tags.map((tag) => ( + + {tag} + + + ))} + {addingTag ? ( +
+ setTagInput(e.target.value)} + onKeyDown={(e) => { + if (e.key === "Enter") handleAddTag(); + if (e.key === "Escape") { + setAddingTag(false); + setTagInput(""); + } + }} + onBlur={() => { + if (tagInput.trim()) handleAddTag(); + else setAddingTag(false); + }} + placeholder="tag name..." + className="w-28 rounded-md bg-gray-800 px-2.5 py-1 text-xs text-white outline-none ring-1 ring-violet-500/30 placeholder:text-gray-400" + /> +
+ ) : ( + + )} +
+ {tags.length === 0 && !addingTag && ( +

+ No tags yet. Tags help organize and filter your agents. +

+ )} +
+ + {/* Notes */} +
+ +
+ {editingNote ? ( +
+