siriusscan--sirius/documentation/dev/apps/agent/README.agent-template-api.md

title, description, template, llm_context, categories, tags, related_docs, search_keywords

title	description	template	llm_context	categories	tags	related_docs	search_keywords
Agent Template API Documentation	API endpoints for managing agent vulnerability detection templates	TEMPLATE.documentation-standard	high	api agent templates	api agent templates vulnerability detection	README.agent-template-ui.md ABOUT.documentation.md	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:

[
  {
    "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:

{
  "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:

{
  "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

  {
    "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:

{
  "content": "id: test-template\ninfo:\n  name: Test Template\n..."
}

Response:

{
  "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:

{
  "content": "id: test-template\ninfo:\n  name: Updated Test Template\n..."
}

Response:

{
  "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:

{
  "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:

{
  "agent_id": "agent-123"
}

Response:

{
  "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:

{
  "agent_ids": ["agent-123", "agent-456"]
}

Note: Empty agent_ids array deploys to all agents.

Response:

{
  "message": "Template deployed to agents",
  "agent_count": 2
}

---

Get Template Analytics

Get template effectiveness statistics.

Endpoint: GET /agent-templates/analytics

Response:

{
  "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:

{
  "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

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

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

- type: file_hash
  config:
    path: /usr/bin/vulnerable-binary
    hash: abc123def456...
    algorithm: sha256 # sha256, sha1, md5, sha512

File Content

- type: file_content
  config:
    path: /etc/apache2/apache2.conf
    regex: "ServerTokens\\s+Full"

Command Version

- type: command_version
  config:
    command: ["dpkg-query", "-W", "-f='${Version}'", "openssh-server"]
    regex: "^6\\.5\\.1"
    exit_code: 0 # optional

Script

- 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

curl -X POST http://localhost:9001/api/agent-templates \
  -F "file=@my-template.yaml" \
  -F "author=Security Team"

Get All Templates

curl http://localhost:9001/api/agent-templates

Delete a Custom Template

curl -X DELETE http://localhost:9001/api/agent-templates/my-custom-template

Test Template on Agent

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
• Agent Template Types Definition
• Template System Notes