chore: import upstream snapshot with attribution

2026-07-13 12:32:25 +08:00
commit 161ef94b4f
708 changed files with 189571 additions and 0 deletions
@@ -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)
+
@@ -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)
+