--- url: 'https://asp.viperrtp.com/asp/workspace/alert.md' --- # Alert Alert is an alert record from SIEM, EDR, cloud platforms, or Webhook. It is the evidence layer and detection context layer of Case, used to preserve alert source, rules, products, MITRE, raw logs, and extracted Artifacts. Alerts typically do not serve as the final disposition object for independent closure. Analysts investigate and respond based on Alerts, but final judgment, collaborative discussion, closure summary, and disposition decisions should be completed in Case. ## View The Alert list centrally displays all alert records, supports quick filtering by severity, confidence, impact, etc., and also supports advanced search by rules, products, tags, source ID, time, etc. ![Alert List](img.png) ## Key Fields * Alert ID: System-generated readable ID. * Case: Associated case. * Title: Alert title. * Severity, Confidence, Impact, Risk Level: Risk information. * Disposition, Action, Status: Alert source and disposition status. * Rule ID, Rule Name, Correlation UID, Source UID: Source and correlation information. * Product Vendor, Product Name, Product Feature: Source product. * Tactic, Technique, Sub-technique: MITRE mapping. * Raw Data, Unmapped: Raw data and unmapped fields. ## Basic Basic displays the core information of the Alert: title, risk assessment, detection description, source rules, product information, MITRE mapping, and disposition status. By default, Alert fields are used to present factual information from the source system and detection rules. Analysts typically do not directly modify alert data, but proceed to Case based on alert content to complete judgment and response. ![Alert Basic](img_1.png) ## Artifacts Artifacts display entities and IOC extracted from or associated with the Alert, such as IP, domain, account, host, file hash, etc. They are the foundation for subsequent threat intelligence queries, asset verification, blocking, and scope determination. ![Alert Artifacts](img_2.png) ## Enrichments Enrichments display enrichment results associated with the Alert, such as external context including threat intelligence, reputation, assets, identity, history, etc. ![Alert Enrichments](img_3.png) ## Raw Log & Unmapped Data Raw Log is the raw log content of the alert, typically stored in JSON. It is used for tracing alert sources, verifying field mapping, locating original events, and investigating false positives. Unmapped Data preserves data from the raw alert that is not mapped to standard fields. It retains additional information from the source system, but is not the focus of default AI analysis. ![Alert Raw Log](img_4.png) ## Usage Recommendations * Enter associated Alert from Case to view detection context and original evidence. * Use Rule ID, Rule Name, Source UID, and Correlation UID to trace back to the source system and locate alerts. * View Artifacts to determine which entities and IOC are involved. * View Raw Log / Unmapped Data to verify field mapping completeness. ## Next Steps * [Case](../case/) — Return to the case for final judgment, collaboration, and response decisions. * [Artifact](../artifact/) — View entities and IOCs extracted from alerts. * [Enrichment](../enrichment/) — View enrichment results such as threat intelligence, asset, identity, and historical context. --- --- url: 'https://asp.viperrtp.com/asp/development/alert-ingestion.md' --- # Alert Ingestion Alert Ingestion writes alerts from SIEM or detection platforms into ASP Redis Streams. It is the upstream layer of Modules and does not directly create Cases / Alerts / Artifacts. ```text SIEM Rule / Alert -> Webhook or ELK Index Action -> Redis Stream -> Module -> Case / Alert / Artifact ``` > Stream naming is the key contract between Alert Ingestion and Modules. Splunk `search_name`, Kibana `rule.name`, or ELK Index Action `rule.name` should match the target Module `STREAM_NAME`. ## Ingestion methods | Method | Scenario | Next step | | --- | --- | --- | | [Splunk Webhook](splunk-webhook/) | Splunk Alert can directly access ASP API. | Webhook writes `result` to the Redis Stream named by `search_name`. | | [Kibana Webhook](kibana-webhook/) | Kibana Rule can directly access ASP API. | Webhook writes `context.hits` to the Redis Stream named by `rule.name`. | | [ELK Index Action](elk-index-action/) | Kibana cannot directly POST to ASP, or you prefer writing actions to Elasticsearch first. | Worker polls the Action Index and writes to the Redis Stream named by `rule.name`. | ## Relationship to other custom development pages * [Mock Data](../mock-data/): generates SIEM test logs for alert rules. * [SIEM YAML](../siem-yaml/): describes log indexes and fields for queries and Harness Agent understanding. * [Module Development](../module-examples/): consumes Redis Stream raw alerts and creates ASP resources. * [Custom Console](../custom-console/): checks whether Modules are loaded, Streams exist, and messages have entered Streams. * [Custom Examples](../custom-examples/): shows how Mock SIEM, alert queries, Modules, and Playbooks work together. ## Recommendations * If the SIEM can directly reach ASP, prefer Webhook. * If Kibana uses Community Edition or cannot directly reach ASP, use ELK Index Action. * To validate a full local flow, first generate SIEM logs with [Mock Data](../mock-data/), then configure alert ingestion and Module consumption. ## Next Steps * [Splunk Webhook](splunk-webhook/) — Configure Splunk Alert to write directly into ASP. * [Kibana Webhook](kibana-webhook/) — Configure Kibana Rule to write directly into ASP. * [ELK Index Action](elk-index-action/) — Indirectly ingest Kibana alerts through Elasticsearch Action Index. * [Module Development](../module-examples/) — Write alert processing logic that consumes Redis Streams. --- --- url: 'https://asp.viperrtp.com/asp/integrations/api.md' --- # API Integration The ASP backend serves live OpenAPI documentation for external system integration, scripting, and API debugging. The complete HTTP API reference is generated by the running backend through Swagger UI / Redoc. This documentation site only maintains entry points, authentication guidance, and realtime protocol notes to avoid duplicating the API reference. ## Documentation endpoints After deployment, use these endpoints: | Entry point | Path | Purpose | |-------------|------|---------| | Swagger UI | `/api/docs/` | Interactive API documentation with request execution support. | | Redoc | `/api/redoc/` | Read-only API documentation for browsing and searching. | | OpenAPI Schema | `/api/schema/` | OpenAPI 3 schema for SDK generation or third-party tooling. | ## Authentication API keys are recommended for automation integrations. Use this request header: ```http Authorization: Api-Key ``` Interactive users and frontend login flows can use JWT: ```http Authorization: Bearer ``` The Swagger UI `Authorize` dialog supports both authentication methods. For `bearerAuth`, enter only the access token; Swagger UI adds the `Bearer` prefix automatically. Prefer API keys for long-running external integrations because they do not depend on user login sessions and are easier to manage for scripts and service accounts. ## API versioning The main HTTP API currently uses `/api/...` paths and does not yet have a global `/api/v1/...` prefix. Agent / CLI integration endpoints use `/api/agent/v1/...` for automation scenarios that need a more stable contract. ## Realtime API OpenAPI describes HTTP APIs only. Realtime events use WebSocket: ```text /ws/events/ ``` After a successful connection, the server sends: ```json {"type": "realtime.connected"} ``` Clients can send these messages to subscribe to or unsubscribe from comment events: ```json {"type": "comments.subscribe", "content_type": "case", "object_id": "CASE-000001"} ``` ```json {"type": "comments.unsubscribe", "content_type": "case", "object_id": "CASE-000001"} ``` The server may return: | Event type | Description | |------------|-------------| | `comments.subscribed` | The connection subscribed to comment events for the target record. | | `comments.unsubscribed` | The connection unsubscribed from comment events for the target record. | | `realtime.error` | The message could not be processed or the message type is unknown. | Inbox and comment changes are also pushed through this connection to authenticated users. --- --- url: 'https://asp.viperrtp.com/asp/workspace/artifact.md' --- # Artifact Artifact represents an entity, evidence item, or IOC in a security incident, such as IP, domain, URL, file hash, account, host, process, registry key, cloud resource, etc. During investigation, many queries, responses, and enrichment actions revolve around Artifact: for example, querying the owner of a host, querying threat intelligence for a file hash, or confirming whether an IP needs to be blocked. Artifact is the key layer that transforms "fields in alerts" into "investigatable objects." ## View The Artifact list is used to centrally view extracted entities and IOC. The list displays Artifact ID, Name, Type, Value, Role, Alerts, Enrichments, Created Time, and Updated Time. Analysts can quickly see the entity itself, its role in the incident, and the number of associated contexts. The list supports quick filtering by Type and Role, and also supports advanced filtering by Artifact ID, Type, Role, Name, Value, Created Time, and Updated Time to locate records. ![Artifact List](img.png) ## Key Fields * Artifact ID: System-generated readable ID. * Name: Entity name. * Type: Entity type. * Role: Role in the incident, such as Target, Actor, Affected, Related. * Value: Entity value. ## Basic Name is used for list and detail dialog titles to help quickly identify the current entity. Basic displays Artifact ID, Type, Role, and Value: Type represents the entity type, Role represents its role in the incident, and Value is the actual entity value used for queries, responses, and enrichment. ![Artifact Basic](img_1.png) ## Relationships Artifact can be associated with multiple Alerts and can also have multiple Enrichments. ## Alerts Alerts display alerts associated with the current Artifact. Analysts can use this to trace back which alerts the same entity appears in, then enter Alert details to view detection rules, raw logs, and the associated Case. ![Artifact Alerts](img_3.png) ## Enrichments Enrichments display external context generated around the Artifact, such as threat intelligence, reputation, assets, identity, history, vulnerability information, etc. These enrichment results can help analysts determine whether an entity is malicious, whether it belongs to internal assets, whether it has appeared in other incidents, and how to respond next. Analysts can also add new enrichment records in Enrichments to attach threat intelligence, assets, identity, or investigation conclusions to the current Artifact. ![Artifact Enrichments](img_2.png) ## Usage Recommendations * Enter related Artifact from Alert details. * View threat intelligence enrichment results for key IOC. * Use Artifact to trace back alerts involving the same entity. * Trace back entity source alerts and external context from Alerts and Enrichments. * Prioritize supplementing asset or threat intelligence context for key entities such as hosts, accounts, IPs, and file hashes. * Try to target specific Artifact for response actions, rather than just staying at the alert description level. ## Next Steps * [Enrichment](../enrichment/) — View threat intelligence, asset, identity, and historical context for Artifacts. * [Alert](../alert/) — Return to the source alert to verify detection rules, raw logs, and field mapping. * [Case](../case/) — Bring entity judgments back to the case for final analysis and response decisions. --- --- url: 'https://asp.viperrtp.com/asp/integrations/cli.md' --- # ASP CLI ASP CLI provides the `asp` command for analysts, automation scripts, and Harness Agents to access ASP from the command line. It supports authentication, resource queries, comments and files, Playbook execution, SIEM queries, threat intelligence, CMDB lookups, and other common tasks. It is also the stable command boundary used by Skills to call the ASP Agent Operations API. ## Install Install `pipx` first. ### macOS ```bash brew install pipx pipx ensurepath ``` ### Linux ```bash python3 -m pip install --user pipx python3 -m pipx ensurepath ``` ### Windows ```powershell scoop install pipx pipx ensurepath ``` For more detailed installation instructions, see the [full pipx documentation](https://pipx.pypa.io/stable/how-to/install-pipx/). Install ASP CLI with `pipx`: ```powershell pipx install asp-cli ``` ### Upgrade Upgrade to the latest version: ```powershell pipx upgrade asp-cli ``` Install or downgrade to a specific version: ```powershell pipx install asp-cli==0.5.0 --force ``` After installation, check the command help: ```powershell asp --help ``` ## Login and verify Log in with your ASP URL and personal API key: ```powershell asp auth login --api-url https://asp.example.com --api-key asp_xxx ``` Verify local configuration and server connectivity: ```powershell asp doctor --output json ``` ## Output format The default output is optimized for human reading. For scripts, automation, and Skills, prefer explicit JSON output: ```powershell asp case list --output json ``` ## Common features | Scenario | Common commands | Purpose | |----------|-----------------|---------| | Auth and configuration | `asp auth status`, `asp doctor` | Check the current login state and server connectivity. | | Case / Alert / Artifact | `asp case list`, `asp case show case_000001 --include-related`, `asp alert list`, `asp artifact show artifact_000001` | Query core investigation records, related Alerts, and direct Case relationship summaries. | | Comment / File | `asp comment list case_000001`, `asp comment add case_000001 --body "..."`, `asp file upload ./evidence.txt`, `asp file read-text ` | Read discussions, add comments, upload files, or read attachments. | | Playbook | `asp playbook template list`, `asp playbook run investigation case_000001 --user-input "..."` | List runnable templates and trigger Case automation tasks. | | SIEM | `asp siem schema list`, `asp siem search keyword "powershell" --from 2026-07-01T00:00:00Z --to 2026-07-02T00:00:00Z`, `asp siem query spl "index=main | head 10" --from ... --to ...` | Inspect log schema, run keyword searches, or execute raw SPL / ES|QL queries. | | Threat Intelligence / CMDB | `asp ti query 8.8.8.8 --artifact-type "IP Address" --provider OpenCTI`, `asp cmdb lookup IP 10.0.0.5` | Query IOC reputation and asset context. | | Knowledge / Enrichment | `asp knowledge search phishing`, `asp enrichment create artifact_000001 --name "TI result" --value malicious` | Search reusable knowledge or write structured enrichment results. | ## View directly related Cases ```powershell asp case show case_000001 --include-related --output json ``` The JSON `relationships` field contains up to 50 direct relationship summaries and does not recursively expand the other Cases. The CLI currently has no relationship create, update, delete, or Artifact-suggestion command. See [Related Cases in the Case workspace](../../workspace/case/#related-cases) for the full semantics. ## Next Steps * [Skills](../skills/) — Let Harness Agents use capabilities provided by ASP CLI. * [Setup](../skills/asp-setup/) — Check CLI login and basic configuration in the agent environment. * [Personal Center](../../workspace/personal-center/) — Create a personal API Key for CLI login. --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-alert.md' --- # asp-alert `asp-alert` manages ASP alerts. Use it to list, inspect, review, or triage alert context. ## Invocation ```text /asp-alert ``` The agent reads alerts through `asp alert ... --output json`. ## Common Examples ```text /asp-alert list alerts under case_000001 ``` ```text /asp-alert show details for alert_000001 ``` ```text /asp-alert help decide whether alert_000001 should be escalated ``` Related CLI commands: ```powershell asp alert list --case-id case_000001 --output json asp alert show alert_000001 --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-artifact.md' --- # asp-artifact `asp-artifact` queries and analyzes ASP artifacts. Use it for investigation pivots around IPs, users, hosts, domains, URLs, hashes, and similar entities. ## Invocation ```text /asp-artifact ``` The agent finds entity records through `asp artifact ... --output json`. ## Common Examples ```text /asp-artifact find all IP Address artifacts ``` ```text /asp-artifact show artifact_000001 ``` ```text /asp-artifact decide which cases or alerts we can pivot to from this IOC ``` Related CLI commands: ```powershell asp artifact list --type "IP Address" --output json asp artifact show artifact_000001 --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-artifact-investigation.md' --- # asp-artifact-investigation `asp-artifact-investigation` is an Artifact- or IOC-centered investigation workflow skill. Use it to enrich context, assess risk, and choose pivot directions. ## Invocation ```text /asp-artifact-investigation ``` It combines capabilities such as `asp-artifact`, `asp-threat-intelligence`, `asp-cmdb`, `asp-siem-search`, `asp-case`, and `asp-alert`. ## Common Examples ```text /asp-artifact-investigation investigate the risk and related cases for 1.2.3.4 ``` ```text /asp-artifact-investigation check whether artifact_000001 belongs to an internal asset ``` ```text /asp-artifact-investigation suggest next pivots around this hash ``` Common CLI commands: ```powershell asp artifact list --type "IP Address" --output json asp ti query 1.2.3.4 --artifact-type "IP Address" --output json asp cmdb lookup "IP Address" 1.2.3.4 --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-case.md' --- # asp-case `asp-case` manages ASP security cases. Use it to list, inspect, review, or explicitly update case AI analysis fields. ## Invocation ```text /asp-case ``` The agent uses `asp case ... --output json` to retrieve structured case results. ## Common Examples ```text /asp-case list cases in New status ``` ```text /asp-case inspect case_000001 and summarize the evidence to review ``` ```text /asp-case update AI analysis for case_000001 from summary.md ``` Related CLI commands: ```powershell asp case list --status New --output json asp case show case_000001 --include-related --output json asp case update-ai case_000001 --summary-file summary.md --output json ``` With `--include-related`, the Skill can read related Alerts and up to 50 direct Case relationship summaries. The other Case is represented only by its ID, title, Status, Severity, Verdict, Assignee, relationship direction, Note, and creation information; it is not recursively expanded. Case Relationships are investigation leads and do not synchronize business fields between Cases. The CLI currently does not support relationship CRUD or Artifact suggestion queries. See [Related Cases in the Case workspace](../../../workspace/case/#related-cases) for details. --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-case-investigation.md' --- # asp-case-investigation `asp-case-investigation` is a case-centered investigation workflow skill. Use it for triage, evidence review, context enrichment, and next-step recommendations. ## Invocation ```text /asp-case-investigation ``` It combines capabilities such as `asp-case`, `asp-alert`, `asp-artifact`, `asp-siem-search`, `asp-knowledge`, `asp-enrichment`, and `asp-comment`. ## Common Examples ```text /asp-case-investigation investigate case_000001 and provide severity, confidence, and next steps ``` ```text /asp-case-investigation review alerts and artifacts in case_000001 and decide whether it is a false positive ``` ```text /asp-case-investigation identify which evidence is still missing for case_000001 ``` Common CLI commands: ```powershell asp case show case_000001 --include-related --output json asp alert list --case-id case_000001 --output json asp playbook list --case-id case_000001 --output json ``` The initial Case view includes direct Case relationship summaries. The Skill treats them as investigation leads rather than malicious evidence. It queries another Case only when that Case can affect the current judgment and does not recursively traverse the full relationship graph. See [Related Cases in the Case workspace](../../../workspace/case/#related-cases) for details. --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-cmdb.md' --- # asp-cmdb `asp-cmdb` queries ASP CMDB context. Use it to retrieve asset, identity, owner, business-system, and internal environment information. ## Invocation ```text /asp-cmdb ``` The agent queries internal asset context through `asp cmdb lookup ... --output json`. ## Common Examples ```text /asp-cmdb look up asset information for IP Address 1.2.3.4 ``` ```text /asp-cmdb find the owner and business system for this host ``` ```text /asp-cmdb decide whether the current artifact belongs to a core production asset ``` Related CLI command: ```powershell asp cmdb lookup "IP Address" 1.2.3.4 --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-comment.md' --- # asp-comment `asp-comment` manages ASP comments. Use it to view or add natural-language comments on Case, Alert, Artifact, Enrichment, Knowledge, and Playbook resources. ## Invocation ```text /asp-comment ``` Adding a comment is a write operation and requires an explicit user request. ## Common Examples ```text /asp-comment view comments on case_000001 ``` ```text /asp-comment add the contents of note.md to case_000001 ``` ```text /asp-comment summarize unresolved questions from the comments on case_000001 ``` Related CLI commands: ```powershell asp comment list case_000001 --output json asp comment add case_000001 --body-file note.md --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-enrichment.md' --- # asp-enrichment `asp-enrichment` creates ASP Enrichment records. Use it to save structured analysis, intelligence, asset context, or investigation conclusions to a Case, Alert, or Artifact. ## Invocation ```text /asp-enrichment ``` Creating an Enrichment is a write operation and requires an explicit user request. ## Common Examples ```text /asp-enrichment save enrichment.json to case_000001 ``` ```text /asp-enrichment save the threat intelligence result as a ti enrichment ``` ```text /asp-enrichment attach owner and business-system context to the current artifact ``` Related CLI command: ```powershell asp enrichment create case_000001 --name ti --data-file enrichment.json --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-file.md' --- # asp-file `asp-file` manages ASP files and comment attachments. Use it to upload files, inspect metadata, download files, or read text content. ## Invocation ```text /asp-file ``` Uploading a file is a write operation and requires an explicit user request. ## Common Examples ```text /asp-file upload evidence.txt and return the file_key ``` ```text /asp-file show file info for 6f2c5d7e-31c6-4f48-9e3c-6d9b5f92c457 ``` ```text /asp-file read the first 4096 bytes of this text attachment ``` Related CLI commands: ```powershell asp file upload evidence.txt --output json asp file info 6f2c5d7e-31c6-4f48-9e3c-6d9b5f92c457 --output json asp file read-text 6f2c5d7e-31c6-4f48-9e3c-6d9b5f92c457 --max-bytes 4096 --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-knowledge.md' --- # asp-knowledge `asp-knowledge` searches, views, or updates ASP Knowledge records. Use it to reuse internal experience, SOPs, historical patterns, and analyst knowledge. ## Invocation ```text /asp-knowledge ``` Updating knowledge is a write operation and requires an explicit user request. ## Common Examples ```text /asp-knowledge search for phishing knowledge ``` ```text /asp-knowledge show knowledge_000001 ``` ```text /asp-knowledge update knowledge_000001 from note.md ``` Related CLI commands: ```powershell asp knowledge search phishing --output json asp knowledge show knowledge_000001 --output json asp knowledge update knowledge_000001 --body-file note.md --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-module-creator.md' --- # asp-module-creator `asp-module-creator` creates ASP custom alert processing modules. Use it to generate `custom/modules` modules from SIEM rule samples and project conventions. ## Invocation ```text /asp-module-creator ``` The skill reads local project conventions and can use `asp dev stream ... --output json` to fetch development stream samples. ## Common Examples ```text /asp-module-creator generate a module from this SIEM rule and raw_alert sample ``` ```text /asp-module-creator read the latest 3 custom-module-events messages and infer field mapping ``` ```text /asp-module-creator check whether the new module correctly creates Case, Alert, and Artifact fields ``` Related CLI commands: ```powershell asp dev stream head custom-module-events -n 3 --output json asp dev stream read custom-module-events 0-1 --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-playbook.md' --- # asp-playbook `asp-playbook` manages ASP Playbook automation. Use it to list templates, view run history, or execute Playbooks after explicit authorization. ## Invocation ```text /asp-playbook ``` Executing a Playbook is an automation write operation and requires explicit user authorization. ## Common Examples ```text /asp-playbook list runnable playbook templates ``` ```text /asp-playbook show playbook runs for case_000001 ``` ```text /asp-playbook run collect_case_context on case_000001 using prompt.md ``` Related CLI commands: ```powershell asp playbook template list --output json asp playbook list --case-id case_000001 --output json asp playbook run collect_case_context case_000001 --user-input-file prompt.md --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-playbook-creator.md' --- # asp-playbook-creator `asp-playbook-creator` creates or improves ASP Playbooks. Use it to write LLM analysis Playbooks or SOAR-style automation Playbooks. ## Invocation ```text /asp-playbook-creator ``` The skill follows the current backend convention and generates Playbooks under `backend/custom/playbooks/`. Prompt files may live under `backend/custom/data/playbooks//System_zh.md` when needed. ## Common Examples ```text /asp-playbook-creator create a case_summary LLM analysis playbook ``` ```text /asp-playbook-creator create a CMDB enrichment automation playbook ``` ```text /asp-playbook-creator check whether an existing playbook follows the current BasePlaybook convention ``` Related CLI commands: ```powershell asp playbook template list --output json asp playbook run collect_case_context case_000001 --user-input-file prompt.md --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-setup.md' --- # asp-setup `asp-setup` configures ASP CLI authentication and verifies that the current agent can access ASP. Run it first after installing the skills. ## Invocation ```text /asp-setup ``` The skill guides [ASP CLI](../../cli/) installation, runs `asp auth login`, and verifies the connection with `asp doctor --output json`. ## Common Examples ```text /asp-setup check whether asp-cli is installed on this machine ``` ```text /asp-setup log in with https://asp.example.com and my API key ``` ```text /asp-setup verify whether the current account can access ASP ``` See [ASP CLI](../../cli/) for the related commands and installation steps. --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-siem-index-yaml.md' --- # asp-siem-index-yaml `asp-siem-index-yaml` creates or updates ASP SIEM index YAML. Use it to generate maintainable index configuration from backend field discovery results. ## Invocation ```text /asp-siem-index-yaml ``` The skill combines local project files with `asp siem fields discover ... --output json` results to help generate YAML configuration. ## Common Examples ```text /asp-siem-index-yaml generate ELK index YAML for logs-security ``` ```text /asp-siem-index-yaml discover fields from logs-security for the last hour and suggest configuration ``` ```text /asp-siem-index-yaml check whether the existing YAML is missing common time, host, and user fields ``` Related CLI commands: ```powershell asp siem fields discover logs-security ELK --from 2026-07-02T00:00:00Z --to 2026-07-02T01:00:00Z --output json asp siem schema show logs-security --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-siem-rule.md' --- # asp-siem-rule `asp-siem-rule` writes and validates ASP SIEM detection rules. Use it to turn threat scenarios into Splunk SPL or ELK ES|QL queries. ## Invocation ```text /asp-siem-rule ``` The skill understands the target and data source first, then validates queries with `asp siem query spl` or `asp siem query esql`. ## Common Examples ```text /asp-siem-rule generate SPL for multiple failed logins followed by a successful login ``` ```text /asp-siem-rule write an ES|QL query for suspicious PowerShell processes in the last hour ``` ```text /asp-siem-rule validate whether this SPL returns sample events ``` Related CLI commands: ```powershell asp siem query spl "index=main error" --from 2026-07-02T00:00:00Z --to 2026-07-02T01:00:00Z --output json asp siem query esql "FROM logs-* | LIMIT 10" --from 2026-07-02T00:00:00Z --to 2026-07-02T01:00:00Z --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-siem-search.md' --- # asp-siem-search `asp-siem-search` explores ASP SIEM schemas, searches logs, runs adaptive queries, SPL, ES|QL, and field discovery. ## Invocation ```text /asp-siem-search ``` The agent chooses `asp siem ... --output json` commands based on the data source type and should prefer bounded time ranges. ## Common Examples ```text /asp-siem-search search for 1.2.3.4 from yesterday 00:00 to 01:00 ``` ```text /asp-siem-search show the schema for logs-security ``` ```text /asp-siem-search run an adaptive query on logs-security using filters.json ``` Related CLI commands: ```powershell asp siem search keyword 1.2.3.4 --from 2026-07-02T00:00:00Z --to 2026-07-02T01:00:00Z --output json asp siem schema show logs-security --output json asp siem query adaptive logs-security --from 2026-07-02T00:00:00Z --to 2026-07-02T01:00:00Z --filters-file filters.json --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-threat-hunting.md' --- # asp-threat-hunting `asp-threat-hunting` orchestrates ASP threat hunting. Use it for bounded SIEM hunts around hypotheses, IOCs, TTPs, or suspicious activity. ## Invocation ```text /asp-threat-hunting ``` It combines `asp-siem-search`, `asp-siem-rule`, `asp-alert`, `asp-artifact`, `asp-case`, `asp-threat-intelligence`, and `asp-knowledge`. ## Common Examples ```text /asp-threat-hunting run a 24-hour hunt for suspicious PowerShell download activity ``` ```text /asp-threat-hunting use these IOCs to search related SIEM activity ``` ```text /asp-threat-hunting generate a verifiable hunt query for ATT&CK T1059 ``` Common CLI commands: ```powershell asp siem schema list --output json asp siem search keyword 1.2.3.4 --from 2026-07-02T00:00:00Z --to 2026-07-02T01:00:00Z --output json asp siem query spl "index=main error" --from 2026-07-02T00:00:00Z --to 2026-07-02T01:00:00Z --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills/asp-threat-intelligence.md' --- # asp-threat-intelligence `asp-threat-intelligence` queries ASP threat intelligence. Use it to retrieve IOC reputation, risk levels, tags, attack techniques, and malicious context. ## Invocation ```text /asp-threat-intelligence ``` The agent queries threat intelligence through `asp ti query ... --output json`. If you need to select a source explicitly, use the Provider name, such as `OpenCTI` or `AlienVaultOTX`. ## Common Examples ```text /asp-threat-intelligence query threat intelligence for 1.2.3.4 ``` ```text /asp-threat-intelligence check whether this domain has malicious history ``` ```text /asp-threat-intelligence query this IOC and format the result so it can be saved as an enrichment ``` Related CLI command: ```powershell asp ti query 1.2.3.4 --artifact-type "IP Address" --output json ``` ```powershell asp ti query 1.2.3.4 --artifact-type "IP Address" --provider OpenCTI --output json ``` --- --- url: 'https://asp.viperrtp.com/asp/workspace/audit-log.md' --- # Audit Log Audit Log is used to track changes to important resources within the platform. It records who created, updated, or deleted what and when, as well as what specific fields or relationships changed. Its focus is not on displaying resource details, but on providing a traceable change timeline to help users understand how data evolved step by step into its current state. ## Entry Point Audit Log is opened via the `Log` button in the upper right corner of the resource detail page. Resources such as Case, Alert, Artifact, Enrichment, Playbook, and Knowledge can all view their own change timeline from the detail page. ## Recorded Content | Content | Description | |---------|-------------| | Resource | The resource being operated on. | | Action | Operation type, such as create, update, delete, linked, unlinked, deleted. | | Operator | The operator. System automated actions display as system. | | Time | When the operation occurred. | | Changes | Field changes, including before and after modification values. | | Relation | Resource relationship changes, such as linked or unlinked records. | | Metadata | Additional information for saving relationships, tags, or supplementary context for deleted records. | Currently, the timeline displays the most recent 100 records in reverse chronological order. ## Timeline View Audit Log is displayed as a timeline. Each record contains operation type, operator, time, and change content, making it easy to quickly track the resource change process. Field updates are displayed in `from → to` format; relationship changes show related resource types and readable labels. For associated resources that still exist, you can click to navigate directly to the corresponding detail page. ![Audit Log Timeline](img.png) ## Filters When there are many records, you can quickly locate key information through filtering: * Action: Filter by operation type. * Operator: Filter by operator. * Field: Filter by changed field. * Time Range: Filter by time range. ![Audit Log Filters](img_1.png) ## Deleted Records When a resource is deleted, the audit log preserves readable labels in metadata to avoid only seeing UUIDs after deletion. If the deleted object is a relationship object, a `deleted` relationship event will appear in the parent resource's timeline. Since the target object no longer exists, this type of event only shows a readable label and does not provide navigation. ## Usage Recommendations * View change history in resource details such as Case, Alert, and Artifact. * When investigating misoperations, first check the operator and changes. * When tracking relationship changes, pay attention to linked, unlinked, and deleted events. * For deleted records, prioritize checking deletion labels in metadata. ## Next Steps * [Case](../case/) — View Comments, Timeline, and the investigation loop in cases. * [Inbox](../inbox/) — Learn how collaboration notifications and @ mentions enter in-app messages. * [User Management](../../settings/users/) — Manage users, roles, and API Keys. --- --- url: 'https://asp.viperrtp.com/asp/quick-start/backup-restore.md' --- # Backup & Restore ASP provides scripts for stopped full backups and restores. A backup contains deployment files, settings, certificates, logs, and all Docker named volumes. ::: warning Keep the deployment directory name Run backup and restore from a deployment directory named `asp-compose`. Changing the directory name changes the Docker Compose project name and named volume names, so the scripts refuse to run. ::: ::: warning Protect backup files Backups contain `.env`, certificates, databases, object storage, and logs, and may include secrets, API keys, alerts, and investigation records. Secret and plain Custom Variable values are stored as plaintext in PostgreSQL and are included in backups. Encrypt them and restrict access. ::: ## 1. Create a full backup Run from `asp-compose/`: ```bash ./scripts/backup.sh ``` The script stops services, creates the backup, starts services, and runs `doctor.sh`. The default output directory is: ```text backups/asp-full-/ ``` Use another backup root when needed: ```bash ./scripts/backup.sh /mnt/asp-backups ``` Each backup contains: | File | Content | | --- | --- | | `files.tar.gz` | `.env`, Compose files, scripts, custom content, certificates, and logs. | | `volumes.tar.gz` | PostgreSQL, Redis, RustFS, custom Python dependencies, and static file volumes. | | `manifest.txt` | Backup format, timestamp, and Compose project information. | | `SHA256SUMS` | SHA-256 checksums for both archives. | ASP is temporarily unavailable during backup. The script does not remove old backups automatically. ## 2. Prepare to restore Confirm: * The current directory is named `asp-compose`. * The backup contains `manifest.txt`, `SHA256SUMS`, `files.tar.gz`, and `volumes.tar.gz`. * For a new machine, Docker and Docker Compose are installed and the ASP Compose package has been extracted as `asp-compose/`; do not initialize it. ::: danger Restore overwrites current data Restore replaces deployment files and clears the PostgreSQL, Redis, RustFS, custom Python dependency, and static file volumes before loading backup data. It does not back up the current environment automatically. ::: ## 3. Restore Run from the `asp-compose/` directory to restore: ```bash ./scripts/restore.sh /path/to/asp-full-backup ``` The script validates the manifest, SHA-256 checksums, archives, and Compose configuration before stopping services. After a complete restore it starts services and runs `doctor.sh`. If file or volume restoration fails, services remain stopped. Fix the reported problem and run restore again. ## Next Steps * [Upgrade](../upgrade/) — Create a stopped full backup before upgrading. * [Restart & Operations](../operations/) — Check service status and logs. --- --- url: 'https://asp.viperrtp.com/asp/workspace/case.md' --- # Case Case is the core disposition object in ASP and the war room for analyst collaborative investigation. A Case aggregates alerts, entities, enrichment, knowledge, playbooks, AI investigation reports, discussions, and timelines, allowing teams to complete judgment and response around the same security incident. In ASP, Case is not just a ticket. Discussions, supplementary judgments, and attachments in Comments, as well as operation traces in Log / Timeline, all become important context for subsequent LLM analysis, report generation, and knowledge extraction. ## View The Case list is used to centrally manage and track the security incident handling process. Analysts can filter and sort by status, severity, assignee, and other conditions to quickly find cases that need disposition. ![Case List](img.png) ## Key Fields * Case ID: System-generated readable ID. * Title: Case title. * Status: New, In Progress, On Hold, Resolved, Closed. * Severity / Confidence / Impact / Priority: Manual assessment. * Severity (AI) / Confidence (AI) / Impact (AI) / Priority (AI): AI assessment. * Verdict / Verdict (AI): Final disposition and AI disposition. * Assignee: Person responsible. * Summary: Closure summary. * Correlation UID: Correlation ID. ## Basic The Case detail page is the main interface of the case war room. The left side displays case basic information, associated evidence, automation results, and AI reports; the right side can open Comments or Log drawers to view collaborative discussions and timelines. ![Case Detail](img_1.png) ## Associated Evidence and Context The Case detail page includes: * Summary, Risk Assessment, Classification, Time, Ownership, Description. * Alerts: Associated alerts. * Enrichments: Associated enrichment results. * Related Cases: Explicit direct investigative relationships between Cases. * Knowledge: Knowledge extracted from or associated with the case. * Playbooks: Playbook tasks triggered from the case. * Investigation: AI investigation report. ### Alerts Alerts preserve all alerts associated with the Case. Analysts can enter Alert details from here to view detection rules, raw logs, Artifact, and Enrichment. ![Case Associated Alerts](img_2.png) ### Enrichments Enrichments display external context associated with the Case, such as threat intelligence, assets, identity, history, etc., helping analysts quickly assess risk. ![Case Associated Enrichments](img_3.png) ### Related Cases Related Cases records direct investigative links between Cases using `Related`, `Duplicate of`, or `Parent of`. Relationships do not merge Cases or synchronize business fields such as Status, Verdict, or Assignee. ![](img_11.png) The table shows the relationship, basic information about the other Case, the Note, and creation information. Select a Case ID to open the other Case. Admin and User roles can add, update, or delete relationships; Viewers have read-only access. #### Suggested Cases The toolbar search action opens the **Suggested Cases** modal and proposes potentially related Cases based on shared Artifacts. ![](img_12.png) Suggestions run only when requested, use at most 20 Artifacts, and return up to 10 results. They are only leads; confirming one creates a `Related` relationship. ### Playbooks Playbooks display automation tasks triggered from the current Case, including investigation, knowledge extraction, threat intelligence enrichment, and CMDB enrichment. ![Case Associated Playbooks](img_4.png) ## Investigation Investigation displays AI-generated investigation reports. The report references Case fields, associated Alerts, Artifact, Enrichment, Comments, and Log / Timeline to generate disposition, attack chain, key evidence, timeline, and response recommendations. ![AI Investigation Report](img_5.png) ![AI Investigation Report Detail](img_6.png) ![AI Investigation Report Timeline](img_7.png) ## Comments Comments is the collaborative discussion area in the Case war room. Analysts can record judgments, supplement leads, reply to teammates, @mention members, and attach files. These discussions are not ordinary notes. Case's LLM analysis reads Comments, so what analysts write here—confirmations, denials, exceptions, and disposition records—will influence subsequent AI reports and knowledge extraction. ![Case Comments](img_8.png) ## Log / Timeline Log / Timeline displays the operation trace of the Case, including field changes, associated resource changes, operators, and occurrence times. It is not only for auditing but also for reconstructing the incident handling process. Case's AI analysis references this timeline information to help generate more accurate reports and process reviews. ![Case Log](img_9.png) ## Executing Playbook Case is the primary trigger point for Playbooks. Analysts can select investigation, knowledge extraction, threat intelligence enrichment, or CMDB enrichment playbooks from the Case, and supplement natural language requirements through User Input. After Playbook execution, a task record is generated, with status progressing from Pending, Running to Success or Failed. Execution results return to Case, Knowledge, or Enrichment to continue serving subsequent analysis and report generation. ![Execute Playbook](img_10.png) ## Common Operations * Modify status, assignee, closure time, and closure summary. * View associated Alert, Artifact, and Enrichment. * View and maintain directly related Cases. * Record analysis judgments, supplement leads, and team discussions in Comments. * View Log / Timeline to reconstruct case handling process. * Trigger Playbook from Case, and return to Case to review execution results. ## Next Steps * [Alert](../alert/) — View how alerts provide detection context. * [Artifact](../artifact/) — View how entities and IOC support investigation. * [Playbook](../playbook/) — View how automation tasks are triggered from Case. * [Audit Log](../audit-log/) — View more details about timelines and change records. --- --- url: 'https://asp.viperrtp.com/asp/development/custom-console.md' --- # Custom Console Custom Console is ASP's runtime inspection and validation page for custom development. It helps confirm whether Modules, Playbooks, and SIEM YAML files are loaded correctly in the current environment. It does not replace an editor and does not create complex definitions online; creation and updates should still be done through the code repository, Harness Agents, or related Skills. > To understand how source-tree Mock Data, SIEM YAML, Modules, and Playbook examples work together, start with [Custom Examples](../custom-examples/). ## Entry Custom Console is located in the left navigation as `Custom` and is available only to administrators. ![Custom Console overview](img.png) ## What It Solves Custom development spans files, dependencies, Redis Streams, backend registries, and frontend runtime entry points. Custom Console centralizes runtime status so developers can answer: * Whether a new or modified Module has been discovered. * Whether the Redis Stream listened to by a Module exists, has messages, and has healthy consumer groups. * Whether a new or modified Playbook Definition has been discovered, and whether its source, tags, and description are correct. * Whether SIEM YAML can be parsed, and whether fields, key fields, and backend type match expectations. * Whether manual refresh/validation has errors, and which file caused the error. ## Page Structure | Tab | Purpose | Recommended Reading | | --- | --- | --- | | Modules | Displays Module name, description, script path, Stream name, thread count, and Stream status. | [Module Development](../module-examples/) | | Playbooks | Displays runnable Playbook Definitions, source, tags, description, and script path. | [Playbook Development](../playbook/) | | SIEM YAML | Displays SIEM index YAML, backend type, field count, key field count, and field details. | [SIEM YAML](../siem-yaml/) | Playbooks distinguish between `official` and `custom` sources. Modules and SIEM YAML do not have an official/custom concept, so no source field is displayed for them. ## Refresh / Validate Each tab has an independent `Refresh / Validate` action: * Modules: rescans Module scripts and refreshes the Module list and loading errors. * Playbooks: rescans built-in and custom Playbook scripts and refreshes Definition list and loading errors. * SIEM YAML: rescans YAML files and refreshes the SIEM registry cache. Opening the page automatically reads current loaded status and does not write Audit Log. Manually executing `Refresh / Validate` writes Audit Log, making it clear who triggered a rescan and when. If only script definitions or YAML content changed, `Refresh / Validate` is usually enough. If `custom\requirements.txt`, third-party Python packages, or shared helper modules changed, reinstall dependencies and restart related containers before validating again in Custom Console. ## Modules The Modules tab is used to inspect whether Modules have been recognized by runtime and how they relate to Redis Streams. ![Modules tab](img_1.png) Main list fields: | Field | Description | | --- | --- | | Module | The Module `NAME`. | | Description | The Module `DESC`. | | Stream | The Module `STREAM_NAME`; it must match the Stream name written by Webhook / ELK Index Action. | | Threads | The Module `THREAD_NUM`. | | Stream Health | Whether Redis Stream exists, length, first/last message IDs, and consumer group summary. | | Path | Module script path. | ### Stream Inspection Module details can inspect Redis Stream in read-only mode: * Stream basic information. * Consumer group summary. * Recent message JSON. * Read a specific message by message ID. ![Module Stream Inspection](img_2.png) This feature is read-only. It does not write to the Stream, consume messages, delete the Stream, or trigger Module execution. It is useful for confirming whether SIEM alerts have entered the Stream and whether Stream status looks reasonable before and after Module consumption. ## Playbooks The Playbooks tab displays Playbook Definitions that can be run from a Case page. It only displays and validates definitions; it does not run Playbooks from Custom Console. To test a Playbook, use `Run Playbook` on a Case detail page. ![Playbooks tab](img_3.png) Main list fields: | Field | Description | | --- | --- | | Playbook | The Playbook `NAME`. | | Source | `official` or `custom`. | | Tags | The Playbook `TAGS`, used for filtering and identifying purpose. | | Description | The Playbook `DESC`. | | Path | Playbook script path. | Prompt files are not managed by Custom Console. A Playbook may keep prompts in code or call `self.read_prompt("System")` to read prompt files; Custom Console does not validate whether prompt files exist. ## SIEM YAML The SIEM YAML tab displays each YAML-defined index, backend, field count, key field count, and field table. It helps confirm whether the SIEM schema visible to Harness Agents matches expectations. ![SIEM YAML tab](img_4.png) The field table includes: | Field | Description | | --- | --- | | Name | Field name. | | Type | Field type. | | Key field | Whether it is marked as a key field. | | Description | Field meaning. | | Sample values | Example values. | Creating or substantially updating YAML usually requires understanding log structure and query scenarios. Use the [SIEM YAML](../siem-yaml/) documentation or the [SIEM Index YAML Skill](../../integrations/skills/asp-siem-index-yaml/) to help create it. Custom Console only displays and validates the final loaded result. ## Next Steps * [Custom Development Overview](../) — Learn how Module, Playbook, and SIEM YAML relate to each other in ASP. * [Module Development](../module-examples/) — Write Redis Stream consumption logic. * [Playbook Development](../playbook/) — Write Case-triggered automation tasks. * [SIEM YAML](../siem-yaml/) — Maintain index field definitions queryable by Harness Agents. * [Custom Examples](../custom-examples/) — Learn how source examples connect into end-to-end flows. * [Custom Content Deployment](../custom-deployment/) — Learn the Compose `custom/` directory, dependency installation, and restart workflow. --- --- url: 'https://asp.viperrtp.com/asp/development/custom-deployment.md' --- # Custom Content Deployment This page describes how to deploy custom Modules, Playbooks, SIEM YAML, and Python dependencies to a Docker Compose installation. Complete [Deployment](../../quick-start/deployment/) first. ## 1. Custom directory The Compose deployment mounts the host `custom/` directory into backend containers: | Path | Purpose | | --- | --- | | `custom/modules/*.py` | Custom Modules. | | `custom/playbooks/*.py` | Custom Playbooks. | | `custom/data/modules//raw_alert_*.json` | Module development samples. | | `custom/data/siem/*.yaml` | Custom SIEM YAML. | | `custom/data/playbooks//*.md` | Custom Playbook prompts. | | `custom/requirements.txt` | Extra Python packages required by Modules, Playbooks, or shared helpers. | `init.sh` creates the empty directory structure and `custom/requirements.txt` template. Source examples under `backend/custom/` are development references and are not included in release packages. ## 2. Install Python dependencies Add dependencies to: ```text custom/requirements.txt ``` Install them: ```bash docker compose run --rm asp-custom-deps ``` Dependencies are installed at `/opt/asp/custom-packages`, persisted in the `custom-python-packages` Docker named volume, and mounted into all backend services. To choose a Python package index: ```bash docker compose run --rm asp-custom-deps --index-url https://pypi.org/simple ``` Arguments after the service name are passed to `uv pip install`, for example: * `--extra-index-url https://packages.example.com/simple` * `--upgrade` To pass proxy settings into the container: ```bash docker compose run --rm \ -e HTTP_PROXY=http://proxy.example:8080 \ -e HTTPS_PROXY=http://proxy.example:8080 \ asp-custom-deps ``` ## 3. Manage custom variables Admins can manage variables used by custom Modules and Playbooks under `Custom > Variables`. Keys may contain only uppercase letters, numbers, and underscores, and cannot be renamed after creation. Every variable requires a Type: | Type | Python return type | Value editor | | --- | --- | --- | | String | `str` | Text input | | Integer | `int` | Integer input | | Float | `float` | Number input | | Boolean | `bool` | Switch | | List | `list` | JSON code editor | | Dictionary | `dict` | JSON code editor | List and Dictionary support nested JSON values. The editor provides line numbers, syntax highlighting, bracket matching, code folding, and Format; JSON syntax and the top-level type are validated when you save. Dictionary key order is not guaranteed. Use a List when order matters. String cannot be empty. Integer must be a JavaScript safe integer, and Float must be finite. Boolean `false`, numeric `0`, an empty List, and an empty Dictionary are all valid values. A Value may contain up to 65,536 UTF-8 bytes, and List and Dictionary may be nested up to 20 levels. Only String can be marked as Secret. Secret values are hidden from normal Admin API responses and edit forms; an Admin must use Reveal to view one. To change a Secret to another Type, disable Secret and enter a new Value. Changing the Type of any variable clears the previous Value and requires confirmation. Read variables through the base class in custom code: ```python class Playbook(BasePlaybook): def run(self): base_url = self.get_variable("EDR_BASE_URL") token = self.get_variable("EDR_API_TOKEN") verify_tls = self.get_variable("EDR_VERIFY_TLS") headers = self.get_variable("EDR_HEADERS") if base_url is None or token is None: raise ValueError("EDR custom variables are not configured.") if verify_tls is None: verify_tls = True if headers is None: headers = {} ``` `BaseModule` uses the same lookup method: ```python class Module(BaseModule): NAME = "EDR alert processor" STREAM_NAME = "EDR-Alerts" def run(self, message): base_url = self.get_variable("EDR_BASE_URL") token = self.get_variable("EDR_API_TOKEN") if base_url is None or token is None: raise ValueError("EDR custom variables are not configured.") # Process the alert using message, base_url, and token. ``` `BasePlaybook.get_variable()` and `BaseModule.get_variable()` query the current database value on every call and return the native Python type selected by Type. Custom code does not need to parse JSON. They return `None` when a variable is missing, disabled, or deleted. ::: tip Use `is None` to detect a missing variable `false`, `0`, `[]`, and `{}` are valid values. Use `value is None` to detect a missing variable instead of `if not value`. ::: ::: warning Secrets are not encrypted at rest The Secret flag only hides a value from normal Admin API responses and lists. The value remains plaintext in the database and can be read by database administrators or anyone with a database backup. Install only trusted custom code, and never write secrets to logs, task summaries, Enrichments, or exceptions. ::: ## 4. Apply changes For Module, Playbook, or SIEM YAML changes, use `Refresh / Validate` in the corresponding [Custom Console](../custom-console/) tab. After dependency or shared helper changes: ```bash docker compose run --rm asp-custom-deps docker compose restart asp-web asp-worker-module asp-worker-playbook ./scripts/doctor.sh ``` ## 5. Compose overrides `init.sh` creates `compose.override.yaml` when it does not exist. Docker Compose merges it with the official `compose.yaml`. * Keep supported settings in `.env`. * Edit `compose.override.yaml` for service-level volumes, environment variables, commands, or other overrides. * Do not edit the official `compose.yaml`. For example: ```yaml services: asp-web: environment: EXAMPLE_SETTING: value ``` Apply the change: ```bash docker compose up -d ./scripts/doctor.sh ``` Release packages do not contain `.env`, `compose.override.yaml`, or `custom/`, so overlay upgrades preserve them. See [Upgrade](../../quick-start/upgrade/). ## Next Steps * [Custom Console](../custom-console/) — Inspect and validate loaded definitions. * [Module Development](../module-examples/) — Write Redis Stream consumption logic. * [Playbook Development](../playbook/) — Write Case-triggered automation. * [SIEM YAML](../siem-yaml/) — Maintain index field definitions. * [Restart & Operations](../../quick-start/operations/) — Check service status and logs. --- --- url: 'https://asp.viperrtp.com/asp/development.md' --- # Custom Development Custom development explains how to extend ASP based on your own security operations scenarios. The main extension points currently open for user custom development are Alert Ingestion, SIEM YAML, Module, and Playbook. The source repository also includes [Custom Examples](custom-examples/) that show how Mock SIEM logs, Alert Ingestion, SIEM YAML, Modules, and Playbooks work together. ## Target Audience * Developers who need to ingest new SIEM Rule alerts into ASP. * Developers who need to orchestrate automated investigation, enrichment, or response actions for Case. * Developers who need to supplement SIEM index field descriptions for Harness Agent queries. ## Extension Points | Extension Point | Location | Purpose | | --- | --- | --- | | Alert Ingestion | Webhook / ELK Index Action | Writes SIEM alerts into Redis Stream as Module input. | | SIEM YAML | `custom\data\siem\*.yaml` | Describes Splunk / ELK indexes, fields, and default aggregation fields for Harness Agent queries. | | Module | `custom\modules\*.py` | Consumes raw alerts from Redis Stream, generates Case / Alert / Artifact. | | Playbook | `custom\playbooks\*.py` / `backend\playbooks\*.py` | Triggers user-initiated automation tasks from Case. | In production, only `custom/` is loaded by default for Module and SIEM YAML. The `backend\custom\` in the source repository can serve as local development examples; `init.sh` creates an empty `custom/` directory structure in the deployment directory. Playbook preserves built-in product capabilities and also allows appending or overriding through `custom\playbooks\*.py`. ## Data Flow ```text Mock Data / SIEM Rule → Alert Ingestion (Webhook / ELK Index Action) → Redis Stream → Module → Case / Alert / Artifact → Playbook / Enrichment / Knowledge ``` Alert Ingestion writes SIEM detections into Streams; Module reduces noise and standardizes raw alerts so analysts can work around Cases; Playbook advances investigation, enrichment, knowledge extraction, or other automation on Cases; SIEM YAML enables Harness Agents to understand and query external logs. ## Refresh and Dependencies After modifying Module, Playbook, or SIEM YAML, click `Refresh / Validate` in the corresponding [Custom Console](custom-console/) tab to rescan and view loading results. Loading failures display file path and exception information, and write to Audit Log. After dependency packages or shared helper changes, reinstall dependencies and restart related containers. See [Custom Content Deployment](custom-deployment/) for the Compose directory and deployment workflow. ## Current Examples The backend currently includes the following Module examples in `backend\custom\modules\`: * `aws_iam_privilege_escalation_attach_user_policy.py` * `edr_vssadmin_delete_shadows.py` * `mail_user_report_phishing.py` The backend currently includes the following Playbook examples: * `investigation.py` * `knowledge_extraction.py` * `threat_intelligence_enrichment.py` * `cmdb_enrichment.py` ## Next Steps Read in this order: * [Environment Setup](environment-setup/) — Prepare the source development environment and custom directory. * [Custom Content Deployment](custom-deployment/) — Deploy custom code, configuration, and dependencies to Compose. * [Service Management UIs](management-uis/) — Access Redis Stack UI and RustFS Console. * [Mock Data](mock-data/) — Generate workspace data or SIEM test logs. * [Alert Ingestion](alert-ingestion/) — Learn how Webhook / ELK Index Action writes SIEM alerts into Redis Stream. * [SIEM YAML](siem-yaml/) — Learn how to maintain index configuration for Harness Agent queries. * [Module Development](module-examples/) — Learn how to convert Stream alerts into ASP resources. * [Playbook Development](playbook/) — Learn how to write Case-triggered automation tasks. * [Custom Console](custom-console/) — Learn how to inspect and validate definitions loaded in the current environment. * [Custom Examples](custom-examples/) — Understand how Mock Data, Alert Ingestion, SIEM YAML, Modules, and Playbooks connect through runnable examples. * [Module Creator](../integrations/skills/asp-module-creator/) / [Playbook Creator](../integrations/skills/asp-playbook-creator/) — Let Harness Agents help generate code drafts. --- --- url: 'https://asp.viperrtp.com/asp/development/custom-examples.md' --- # Custom Examples Custom Examples explains how to use the source-tree custom examples. It is not a new extension mechanism; it groups examples into two parts: Custom Module and Custom Playbook. > The `custom/` directory created by `init.sh` does not include these test examples. Use `backend/custom/` in the source repository as a local development reference. If you want to test examples in a Compose deployment, copy only the examples you need into the deployment `custom/` directory. ## Two example types | Type | Source path | Focus | | --- | --- | --- | | [Custom Module Examples](modules/) | `backend/custom/modules/` | How three Module examples convert logs or raw alerts into Cases / Alerts / Artifacts. | | [Custom Playbook Examples](playbooks/) | `backend/custom/playbooks/` | How two Playbooks write back Summary or add Enrichment on Cases. | Common Custom Module flow: ```text log / raw alert -> alert rule -> alert ingestion -> Redis Stream -> Custom Module -> Case / Alert / Artifact ``` Common Custom Playbook flow: ```text Case -> Run Playbook -> Custom Playbook -> Summary / Enrichment / Remark ``` ## Copying to a Compose deployment To test these examples in a Compose release package, copy selected files as needed: ```text backend/custom/modules/*.py -> custom/modules/ backend/custom/playbooks/*.py -> custom/playbooks/ backend/custom/data/siem/*.yaml -> custom/data/siem/ backend/custom/data/modules//*.json -> custom/data/modules// backend/custom/data/playbooks//*.md -> custom/data/playbooks// ``` After copying: * Run `Refresh / Validate` for Modules / Playbooks / SIEM YAML in [Custom Console](../custom-console/). * If new Python dependencies are added, update `custom/requirements.txt` and reinstall dependencies. * To consume raw alerts automatically, run the Module Worker and make sure the Redis Stream name matches the Module `STREAM_NAME`. ## Next Steps * [Custom Module Examples](modules/) — See how three Module examples generate Cases from logs or raw alerts. * [Custom Playbook Examples](playbooks/) — See how Playbooks write back Summary or add Enrichment after a Case exists. * [Custom Console](../custom-console/) — Confirm at runtime whether Modules and Playbooks are loaded successfully. --- --- url: 'https://asp.viperrtp.com/asp/development/custom-examples/modules.md' --- # Custom Module Examples This page introduces three built-in custom Module examples and one detection example that can be generated with Module Creator. They show how external logs or raw alerts become ASP [Cases](../../../workspace/case/), Alerts, and Artifacts. > For testing, use [Mock Data](../../mock-data/) or raw alert samples under `backend/custom/data/modules/`. In production, the source is usually real SIEM / EDR / mail-system logs. This page does not focus on how logs are generated; it focuses on how alert rules, alert ingestion, and Module scripts connect. ## Common flow All examples follow the same idea: ```text log / raw alert -> SPL / ES|QL / alert rule -> alert ingestion writes Redis Stream -> custom Module consumes Stream -> creates Case / Alert / Artifact ``` * Log source: use [Mock Data](../../mock-data/) in testing; use real SIEM / EDR / mail-system logs in production. * Alert ingestion: [Splunk Webhook](../../alert-ingestion/splunk-webhook/), [Kibana Webhook](../../alert-ingestion/kibana-webhook/), or [ELK Index Action](../../alert-ingestion/elk-index-action/). * Module validation: use `Refresh / Validate` in [Custom Console](../../custom-console/) to confirm the Module is loaded and inspect Stream status. * Output: check generated Cases in [Case](../../../workspace/case/), then open Case detail to review Alert and Artifact. ## 1. EDR Vssadmin Delete Shadows | Item | Value | | --- | --- | | Module | `backend/custom/modules/edr_vssadmin_delete_shadows.py` | | Stream | `EDR-01-HOST-Vssadmin-Delete-Shadows` | | Scenario | Detects `vssadmin.exe delete shadows`, a common recovery-inhibition behavior used by ransomware. | ### Alert query example ```esql FROM siem-host-events | WHERE process.name == "vssadmin.exe" | WHERE risk_score >= 80 | WHERE process.command_line LIKE "*delete*shadows*" | SORT @timestamp DESC ``` ### Alert ingestion Write matched events to Redis Stream through [Kibana Webhook](../../alert-ingestion/kibana-webhook/) or [ELK Index Action](../../alert-ingestion/elk-index-action/). The Stream name must match the Module `STREAM_NAME`: ```text EDR-01-HOST-Vssadmin-Delete-Shadows ``` ### What the Module does This Module extracts: * Host name and host IP. * User name. * Process name, parent process, and command line. * File path and file hash. It then generates a correlation UID and calls `create_alert_with_context()` to create or associate Case, Alert, and Artifact. The generated Case represents an investigatable ransomware precursor behavior, not a single log line. ## 2. AWS IAM Privilege Escalation via AttachUserPolicy | Item | Value | | --- | --- | | Module | `backend/custom/modules/aws_iam_privilege_escalation_attach_user_policy.py` | | Stream | `Cloud-01-AWS-IAM-Privilege-Escalation-via-AttachUserPolicy` | | Scenario | Detects high-risk IAM `AttachUserPolicy` operations that may lead to privilege escalation. | ### Alert query example ```esql FROM siem-aws-cloudtrail | WHERE event.action == "AttachUserPolicy" | WHERE event.risk_score > 80 | WHERE event.outcome == "success" | WHERE requestParameters.policyArn IN ( "arn:aws:iam::aws:policy/AdministratorAccess", "arn:aws:iam::aws:policy/IAMFullAccess" ) | SORT @timestamp DESC ``` ### Alert ingestion Write matched CloudTrail events to Redis Stream through [Kibana Webhook](../../alert-ingestion/kibana-webhook/) or [ELK Index Action](../../alert-ingestion/elk-index-action/). The Stream name must match the Module `STREAM_NAME`: ```text Cloud-01-AWS-IAM-Privilege-Escalation-via-AttachUserPolicy ``` ### What the Module does This Module extracts: * AWS account and region. * Actor user, ARN, principal ID, and access key ID. * Target user. * Attached IAM policy ARN. * Source IP and user agent. It then creates a Case / Alert based on outcome, risk score, and policy type, and splits users, account, policy, source IP, and related values into Artifacts for investigation and enrichment. ## 3. User Reported Phishing Mail | Item | Value | | --- | --- | | Module | `backend/custom/modules/mail_user_report_phishing.py` | | Stream | `Mail-01-User-Report-Phishing-Mail` | | Scenario | Processes user-reported suspicious mail and creates a mail-security investigation Case. | ### Input source This example is not generated by the SIEM Mock log generator. For testing, use: ```text backend/custom/data/modules/mail_user_report_phishing/raw_alert_*.json ``` In production, the source can be a mail gateway, user-reporting system, SOAR, or mail alert from SIEM. ### Alert ingestion Send mail raw alerts to Redis Stream through [Splunk Webhook](../../alert-ingestion/splunk-webhook/), [Kibana Webhook](../../alert-ingestion/kibana-webhook/), or any other Stream-writing integration. The Stream name must match the Module `STREAM_NAME`: ```text Mail-01-User-Report-Phishing-Mail ``` ### What the Module does This Module extracts: * Sender, recipient, and reporter. * Subject and Message ID. * URLs and domains. * Attachment filenames and hashes. It then creates a phishing-related Case / Alert and splits email addresses, URLs, domains, attachments, and hashes into Artifacts. This example shows that non-SIEM logs can also enter Modules through a unified raw alert shape. ## 4. NDR Brute Force: Failed Logins Followed By Success | Item | Value | | --- | --- | | Alert name / Stream | `NDR-01-Brute-Force-Multiple-Failed-Logins-Followed-By-Success` | | Log source | Authentication logs from `siem-network-traffic`. Use [Mock Data](../../mock-data/) for testing, and real network or authentication logs in production. | | Scenario | The same `source.ip` / `user.name` has multiple failed logins followed by a successful login, indicating possible successful brute force. | ### Alert query example ```spl index=siem-network-traffic event.category=authentication (event.action=login_failed OR event.action=login_success) | search [search index=siem-network-traffic event.category=authentication event.action=login_failed | stats count AS failed_count BY source.ip, user.name | where failed_count >= 5 | join source.ip, user.name [search index=siem-network-traffic event.category=authentication event.action=login_success | stats count AS success_count BY source.ip, user.name] | fields source.ip, user.name] ``` ### Splunk Action / Alert ingestion Save the SPL as a Splunk Alert and configure a [Splunk Webhook](../../alert-ingestion/splunk-webhook/) Action: * Select `For each result` as the trigger so each result is sent separately. * Set Webhook URL to ASP: `https:///api/webhook/splunk/`. * Set Alert name to: ```text NDR-01-Brute-Force-Multiple-Failed-Logins-Followed-By-Success ``` Splunk Webhook uses `search_name` as the Redis Stream name and writes `result` as the raw alert. Therefore, the generated Module should use the same value as `STREAM_NAME`. ### Generate the Module with Module Creator This example does not currently have a built-in Module script. Use the [Module Creator](../../../integrations/skills/asp-module-creator/) Skill to generate one from the SPL output fields. Recommended input for Module generation: * Module name: `NDR Brute Force Multiple Failed Logins Followed By Success` * `STREAM_NAME`: `NDR-01-Brute-Force-Multiple-Failed-Logins-Followed-By-Success` * Key fields: `source.ip`, `user.name`, `event.action`, `event.outcome`, `failed_count`, `success_count` * Expected Case: a suspected successful brute-force login. * Expected Artifacts: source IP, user name, authentication action, related host or session fields. After generation, place the script in: ```text custom/modules/ ``` Then run `Refresh / Validate` in [Custom Console](../../custom-console/) → `Modules`, confirm the Module loads successfully, and check whether the Redis Stream with the same name has messages written by Splunk Webhook. ## Run and validate 1. Place Module files in `custom/modules/`. 2. Run `Refresh / Validate` in [Custom Console](../../custom-console/). 3. Confirm the Module list contains the expected `STREAM_NAME`. 4. Confirm that the Module Worker is running; in source development, you can start it manually: ```bash python manage.py run_agentic_module_worker ``` 5. Write raw alerts through alert ingestion or a test script. 6. Check generated results in [Case](../../../workspace/case/). ## Next Steps * [Mock Data](../../mock-data/) — Generate SIEM test logs or workspace sample data. * [Alert Ingestion](../../alert-ingestion/) — Write Splunk, Kibana, or ELK Index Action alerts into Redis Stream. * [Module Development](../../module-examples/) — Learn Module script structure and design recommendations. * [Custom Console](../../custom-console/) — Validate Module loading status and Stream messages. * [Custom Playbook Examples](../playbooks/) — See automation examples after Cases are generated. --- --- url: 'https://asp.viperrtp.com/asp/development/custom-examples/playbooks.md' --- # Custom Playbook Examples This page introduces two custom Playbook examples from the source repository: Case Summary and CMDB Enrichment. They show how Playbooks continue investigation, enrichment, or field write-back after a Case exists. > A Playbook is a Case-triggered automation task. To test a Playbook, click `Run Playbook` on a Case detail page and make sure the Playbook Worker is running. ## Example files | Example | Source path | Purpose | | --- | --- | --- | | Case Summary | `backend/custom/playbooks/case_summary.py` | Calls an LLM to generate an analyst-facing summary and writes it back to the Case Summary field. | | Case Summary Prompt | `backend/custom/data/playbooks/case_summary/System_zh.md` / `System_en.md` | Provides system prompts used by the Case Summary Playbook. | | CMDB Enrichment | `backend/custom/playbooks/cmdb_enrichment.py` | Queries CMDB context for Artifacts linked to the Case and writes results to Enrichment. | ## Case Summary `case_summary.py` summarizes current Case context into a concise analyst-facing summary. Execution flow: 1. Read the current Case. 2. Serialize Case investigation context with `serialize_case_for_investigation()`. 3. Read `System_zh.md` or `System_en.md` according to Runtime Prompt Language. 4. Call the LLM to generate a 2-4 sentence summary. 5. Write the result back to the Case `summary` field. Prompt paths: ```text custom/data/playbooks/case_summary/System_zh.md custom/data/playbooks/case_summary/System_en.md ``` Use cases: * The Case already has Alert / Artifact / Enrichment / Audit Log context. * Analysts want a quick editable summary. * You want to demonstrate how a custom Playbook reads external prompt files. ## CMDB Enrichment `cmdb_enrichment.py` enriches Case-linked Artifacts with asset or identity context. Execution flow: 1. Iterate Artifacts under Alerts linked to the Case. 2. Deduplicate Artifacts and call the CMDB lookup interface. 3. Write supported results to Artifact Enrichment. 4. Return execution statistics such as alert count, artifact count, enriched count, and error count. Use cases: * The Case already contains host, IP, account, or domain Artifacts. * Analysts need to understand the related asset, business system, owner, or criticality. * You want to demonstrate how a custom Playbook writes external query results to Enrichment. ## Run and validate 1. Place Playbook files in `custom/playbooks/`. 2. If prompt files are used, place them in `custom/data/playbooks//`. 3. Run `Refresh / Validate` in [Custom Console](../../custom-console/) → `Playbooks`. 4. Confirm that the Playbook Worker is running; in source development, you can start it manually: ```bash python manage.py run_agentic_playbook_worker ``` 5. Click `Run Playbook` on a Case detail page. 6. Check results: * Case Summary: check the Summary field in Case basic information. * CMDB Enrichment: check Enrichment for Artifacts linked to the Case. * Playbook record: check status and Remark. ## Copying to a Compose deployment Source-to-deployment paths: ```text backend/custom/playbooks/*.py -> custom/playbooks/ backend/custom/data/playbooks//*.md -> custom/data/playbooks// ``` If a Playbook introduces new third-party dependencies, update `custom/requirements.txt` and reinstall dependencies. ## Next Steps * [Custom Examples overview](../) — Understand the overall relationship between Module and Playbook examples. * [Playbook Development](../../playbook/) — Learn custom Playbook script structure and design recommendations. * [Custom Console](../../custom-console/) — Validate whether Playbook Definitions load successfully. * [Custom Module Examples](../modules/) — See how upstream Case / Alert / Artifact records are generated by Modules. --- --- url: 'https://asp.viperrtp.com/asp/workspace/dashboard.md' --- # Dashboard Dashboard is used to quickly view the current security operations status. The current page aggregates and displays information such as Case, Alert, key trends, risk distribution, and keyword clouds, helping analysts determine which areas need priority attention today. ![img.png](../../../../public/hero/zh/img.png) ## Data Refresh Dashboard does not rerun every aggregation each time the page opens. `asp-worker-dashboard-cache` generates 24h, 7d, and 30d snapshots in the background and stores them in Redis. The page reads the latest successfully generated snapshot. The page shows when the data was generated and requests newer snapshots using Dashboard Refresh Interval from [Runtime](../../settings/runtime/). The default interval is 5 minutes. If a snapshot is older than three refresh intervals, the page warns that the data is stale. On first startup, Dashboard temporarily returns 503 and reports that its cache is preparing until the worker generates the first snapshots. ## Cache Troubleshooting If Dashboard has no data for an extended period or keeps warning that data is stale, check the cache worker: ```bash docker compose ps asp-worker-dashboard-cache docker compose logs --tail=100 asp-worker-dashboard-cache ``` Confirm that the worker is running and completing refreshes for the 24h, 7d, and 30d windows. See [Restart & Operations](../../quick-start/operations/) for complete operational commands. ## Usage Recommendations * Check Dashboard at the start of each shift. * Focus on new Cases, severity levels, alert trends, and high-frequency keywords. * When a stale-data warning appears, check the cache worker instead of treating the old snapshot as realtime data. * Use Dashboard to determine whether to enter Case or Alert lists for further filtering. ## Next Steps * [Case](../case/) — Review and handle security cases that need analyst follow-up. * [Alert](../alert/) — View raw alerts and detection context ingested into ASP. * [Artifact](../artifact/) — Continue investigation around entities such as IPs, domains, accounts, and hosts. --- --- url: 'https://asp.viperrtp.com/asp/quick-start/deployment.md' --- # Deployment ASP supports single-host private deployment on Linux using the Docker Compose release package. ## 1. Prerequisites ### Operating system Recommended 64-bit Linux distributions: | Distribution family | Recommended versions | | --- | --- | | Debian | 12, 13 | | Ubuntu Server | 22.04 LTS, 24.04 LTS, 26.04 LTS | | Red Hat Enterprise Linux | 8, 9, 10 | | Rocky Linux / AlmaLinux | 8, 9, 10 | | CentOS Stream | 9, 10 | ### Docker and network Before starting, confirm: * Docker Engine and the Docker Compose plugin are installed. * The host can access GitHub Releases and GHCR. * The default HTTPS port `443` is available. * Redis Stack UI port `8001` and RustFS Console port `9001` are not exposed to untrusted networks. ```bash docker --version docker compose version ``` ## 2. Download the release package * GitHub Releases: * Latest release package: `asp-compose.tar.gz` ```bash curl -fL -o asp-compose.tar.gz https://github.com/FunnyWolf/agentic-soc-platform/releases/latest/download/asp-compose.tar.gz && tar -xzf asp-compose.tar.gz && rm asp-compose.tar.gz && cd asp-compose ``` ::: warning Keep the deployment directory name Run subsequent commands from the extracted `asp-compose/` directory. Do not rename it. Changing the directory name changes the Docker Compose project name and named volume names, which can prevent services from reading existing data. ::: ## 3. Prepare a production certificate (optional) Compose listens on HTTPS only by default. For production, place a certificate issued by an enterprise or public CA at: ```text certs/asp.crt certs/asp.key ``` If these files do not exist, the frontend generates a self-signed certificate on first start. Browser trust warnings are expected. ## 4. Initialize and start ```bash ./scripts/init.sh ``` `init.sh`: 1. Creates runtime directories and `compose.override.yaml`. 2. Creates `.env` from `.env.example`. 3. Generates random Django, PostgreSQL, Redis, and RustFS credentials. 4. Pulls images. 5. Runs database migrations. 6. Starts all services. The random credentials are stored in `.env` and do not need to be changed manually. Protect this file and do not commit it. ## 5. Verify the deployment ```bash ./scripts/doctor.sh ``` A successful check confirms the long-running services, PostgreSQL, Redis, Django, custom definitions, and the RustFS/S3 bucket are available. For failures, see [Restart & Operations](../operations/). ## 6. Create an administrator ```bash docker compose exec asp-web python manage.py createsuperuser ``` Use this account with the `Platform` login method. ## 7. Access ASP ```text https:/// ``` When using the generated self-signed certificate, accept the browser certificate warning on first access. ## Next Steps * [First Login](../first-login/) — Sign in and understand Platform and LDAP accounts. * [Environment Variables](../environment-variables/) — Review all `.env` deployment settings. * [System Settings](../../settings/) — Configure LLM, SIEM, Threat Intelligence, and LDAP. * [Restart & Operations](../operations/) — Check service status and logs. * [Custom Content Deployment](../../development/custom-deployment/) — Deploy custom Modules, Playbooks, SIEM YAML, and dependencies. --- --- url: 'https://asp.viperrtp.com/asp/development/alert-ingestion/elk-index-action.md' --- # ELK Index Action ELK Index Action polls alerts from an Elasticsearch index written by Kibana actions. It is useful when Kibana cannot directly POST to ASP Webhook, or when you prefer writing alert actions to Elasticsearch first and letting ASP pull them. ## How it works ```text Kibana Rule -> Index Action writes to Elasticsearch index -> ASP ELK action worker polls Action Index -> Converts to Kibana webhook payload -> Writes to Redis Stream -> Module processes alert and generates Case / Alert / Artifact ``` ## Configuration location ELK connection, Action Index, polling interval, and read size are configured in [SIEM Settings](../../../settings/siem/#elk-index-action). This page only explains the ingestion flow, Kibana action content, and worker execution. ## Create Index Connector Create an Index Connector in Kibana to write actions to a specific Elasticsearch index. ![Create Index Connector](img_4.png) ![Configure Index Connector](img_5.png) The index name is configurable, but it must match the Action Index in SIEM settings. ![Set Action Index](img_6.png) ## Kibana Action content Create a Kibana Alert Rule and configure query conditions, execution schedule, and trigger conditions. ![Kibana Rule](img.png) ![Kibana Rule conditions](img_1.png) Add an Index Action to the Rule and use the connector created earlier. ![Kibana Index Action](img_2.png) ![Kibana Action parameters](img_3.png) The action document must contain the rule name and the matched original event. ASP reads: | Field | Description | | --- | --- | | `rule.name` | Used as Stream name and alert rule name. | | `context.hits` | Matched events. It can be an array or a JSON string. | Example structure: ```json { "@timestamp": "{{context.date}}", "rule": { "name": "{{rule.name}}" }, "context": { "hits": "[{{context.hits}}]" } } ``` After the Rule triggers, new alert documents appear in the Action Index. ![Action Index document](img_7.png) ## Worker Runtime and Verification In Docker Compose production deployments, `asp-worker-elk-action` starts by default with the release package. Enablement, Action Index, polling interval, and read count are configured in [SIEM settings](../../../settings/siem/#elk-index-action); production deployments do not need manual startup arguments. In source development environments, if you need to debug ELK Index Action directly, start the worker manually from the `backend` directory: ```bash python manage.py run_elk_action_worker ``` View messages written by the worker in Redis or [Custom Console](../../custom-console/) to confirm that a Module can consume them. ![ELK Action Stream message](img_14.png) ## Difference from Webhook | Method | Description | | --- | --- | | Webhook | SIEM directly POSTs to ASP `/api/webhook/kibana/` or `/api/webhook/splunk/`. | | ELK Index Action | Kibana first writes actions to Elasticsearch index, then ASP worker polls and reads them. | Both methods write to Redis Stream and then hand off processing to Modules. ## Recommendations * If the network allows SIEM to directly access ASP, prefer Webhook. * If it is more convenient for Kibana to write to Elasticsearch index, use ELK Index Action. * Ensure `rule.name` and `context.hits` are complete in the action document. * Confirm that `asp-worker-elk-action` is running; otherwise actions in the index will not be pulled and processed. * For complete examples, see [Custom Module Examples](../../custom-examples/modules/). ## Next Steps * [SIEM](../../../settings/siem/) — Configure ELK connection, Action Index, and polling parameters. * [Module Development](../../module-examples/) — Write a Module that consumes the ELK Action Stream. * [Custom Console](../../custom-console/) — Check Stream messages and Module loading status. --- --- url: 'https://asp.viperrtp.com/asp/workspace/enrichment.md' --- # Enrichment Enrichment is external context attached to Case, Alert, or Artifact, used to store threat intelligence, assets, identity, history, SIEM query results, or analyst structured investigation findings. ## View The Enrichment list is used to centrally view all enrichment records. The list displays Enrichment ID, Name, Type, Provider, Value, Linked Object, Created Time, Updated Time, Description, and UID. The list supports quick filtering by Type and Provider, and also supports advanced filtering by Enrichment ID, Type, Provider, Name, UID, Value, Description, Created Time, and Updated Time to locate records. ![Enrichment List](img.png) ## Key Fields * Enrichment ID: System-generated readable ID. * Name: Enrichment name. * Type: Enrichment type, such as Threat Intelligence, Reputation, CMDB, Identity, History. * Provider: Data source, such as AlienVaultOTX, OpenCTI, Internal CMDB, Splunk, Elastic, Manual. * UID: External stable identifier, used for deduplication. * Value: Enrichment value. * Desc: Summary. * Data: Complete JSON data. ## Basic Basic displays the core information of the enrichment record: Enrichment ID, Type, Provider, Linked Object, UID, Value, Description, and Data. Linked Object indicates which Case, Alert, or Artifact the current Enrichment is attached to; clicking it returns to the corresponding resource to continue investigation. Data is used to store complete JSON, suitable for storing threat intelligence return values, asset details, identity context, or SIEM query results. ![Enrichment Detail](img_1.png) ## Associated Targets Enrichment can be associated with: * Case * Alert * Artifact One Enrichment is only associated with one target object. The detail pages of Case, Alert, and Artifact can all view their associated enrichment context through Enrichments. ## Add and Edit Analysts can add new enrichment records in the Enrichments section of Case, Alert, or Artifact detail pages. Manually added records have Provider set to `MANUAL`, and you can fill in Type, Name, UID, Value, and Description. The Enrichment detail page supports editing UID, Value, and Description, suitable for supplementing stable identifiers, key values, and summary descriptions during investigation. ![img\_2.png](img_2.png) ## Usage Recommendations * Attach IOC threat intelligence results to the corresponding Artifact. * Attach asset, identity, CMDB, or history context to related Case, Alert, or Artifact. * Save SIEM query results, manual judgments, and structured investigation findings as Enrichment, rather than leaving them only in temporary conversations or notes. * Use UID to save external system stable identifiers for deduplication and source tracing. ## Next Steps * [Artifact](../artifact/) — See how enrichment results are used around entities and IOCs. * [Case](../case/) — Return to the case and use enrichment context for analysis. * [Threat Intelligence](../../settings/threat-intelligence/) — Configure threat intelligence sources such as AlienVault OTX and OpenCTI. --- --- url: 'https://asp.viperrtp.com/asp/development/environment-setup.md' --- # Environment Setup This page is for source development and local debugging. For production or single-host private deployment, use the Docker Compose release package in [Deployment](../../quick-start/deployment/). > This guide assumes a Linux/macOS shell by default. The recommended development setup is split: run dependency services with Docker Compose, then run backend and frontend processes directly on the host. This makes code debugging, log inspection, frontend changes, and individual Worker processes easier. ## 1. Processes and ports Local ASP development involves three backend process types: | Process | Default Port | Responsibility | | --- | --- | --- | | WSGI / Django | `8000` | Optional Django REST API entrypoint that handles `/api/` directly. | | ASGI / Django + WebSocket | `8001` (adjustable) | Default Vite proxy target that handles both `/api/` and `/ws/`. | | Workers | — | Background tasks: Module consumption, Case analysis, Playbook execution, ELK polling, and Dashboard caching. | Routing: ```text /api/* -> ASGI / Django (Vite default) /ws/* -> ASGI / WebSocket ``` > In production, the ASGI container uses internal port `8001`. If Redis Stack UI also uses `8001` locally, choose another free ASGI port and update both the `/api` and `/ws` proxies in `frontend/vite.config.ts`. ## 2. Start dependency services Use `development/docker` to start PostgreSQL, Redis Stack, and RustFS: ```bash cd /path/to/agentic-soc-platform/development/docker cp .env.example .env docker compose up -d ``` Available services: | Service | Address | Purpose | | --- | --- | --- | | PostgreSQL | `localhost:5432` | Backend database. | | Redis | `localhost:6379` | Cache and Redis Stream. | | Redis Stack UI | `http://localhost:8001` | Redis web management UI. | | RustFS S3 API | `http://localhost:9000` | S3-compatible API for attachments and avatars. | | RustFS Console | `http://localhost:9001` | RustFS web console. | > If a port is already in use, adjust `development/docker/.env` or the Compose port mapping before starting dependency services. ## 3. Configure backend `.env` Enter `backend` and create a local `.env` from the example: ```bash cd /path/to/agentic-soc-platform/backend cp .env.example .env ``` At minimum, make sure these values match `development/docker/.env`: ```text DJANGO_SECRET_KEY=dev-secret-key DJANGO_DEBUG=true DJANGO_ALLOWED_HOSTS=* POSTGRES_DB=asp POSTGRES_USER=postgres POSTGRES_PASSWORD=asp-dev-postgres-password POSTGRES_HOST=localhost POSTGRES_PORT=5432 REDIS_HOST=localhost REDIS_PORT=6379 REDIS_DB=1 REDIS_PASSWORD=asp-dev-redis-password RUSTFS_ENDPOINT_URL=http://localhost:9000 RUSTFS_ACCESS_KEY=asp RUSTFS_SECRET_KEY=asp-dev-rustfs-password RUSTFS_BUCKET=asp RUSTFS_REGION=us-east-1 ``` > These values are for local development only. Production must use random secrets and controlled passwords. ## 4. Initialize backend Install dependencies, apply migrations, and create an administrator: ```bash uv sync .venv/bin/python manage.py migrate .venv/bin/python manage.py createsuperuser ``` Common checks: ```bash .venv/bin/python manage.py check .venv/bin/python manage.py test ``` > Backend dependencies are managed by `uv`. Prefer `backend/.venv/bin/python` for management commands. ## 5. Start backend API The common option is Django development server: ```bash .venv/bin/python manage.py runserver 0.0.0.0:8000 ``` After startup: * API: `http://localhost:8000/api/` For a setup closer to production, use Gunicorn: ```bash .venv/bin/gunicorn asp.wsgi:application --bind 0.0.0.0:8000 --reload ``` ## 6. Start ASGI / WebSocket The ASGI process provides both the Django HTTP API and realtime event WebSocket, and is Vite's default backend: ```bash .venv/bin/uvicorn asp.asgi:application --host 0.0.0.0 --port 8001 --reload ``` ASGI routes: ```text /ws/* -> Realtime event WebSocket /api/* -> Django HTTP API / -> Django fallback ``` > If `8001` is already used by Redis Stack UI, choose another free port and update both the frontend `/api` and `/ws` proxies. ## 7. Start Workers Start background processes as needed: ```bash .venv/bin/python manage.py run_agentic_module_worker .venv/bin/python manage.py run_agentic_case_analysis_worker .venv/bin/python manage.py run_agentic_playbook_worker .venv/bin/python manage.py run_elk_action_worker .venv/bin/python manage.py run_dashboard_cache_worker ``` | Worker | Purpose | | --- | --- | | `run_agentic_module_worker` | Consumes Redis Stream and runs Modules to generate Cases / Alerts / Artifacts. | | `run_agentic_case_analysis_worker` | Runs Case AI analysis tasks. | | `run_agentic_playbook_worker` | Runs user-triggered Playbooks. | | `run_elk_action_worker` | Polls alerts from the ELK Action Index. | | `run_dashboard_cache_worker` | Periodically generates the Dashboard 24h, 7d, and 30d caches. | > Dashboard requires `run_dashboard_cache_worker` to generate its first cache; without it, the Dashboard returns 503. You can omit this worker when developing other frontend list pages. ## 8. Start frontend Enter `frontend`, install dependencies, and start Vite: ```bash cd /path/to/agentic-soc-platform/frontend pnpm install pnpm dev ``` Default URL: ```text http://localhost:5173 ``` Default Vite proxy: ```text http://localhost:5173/api/* -> http://localhost:8001/api/* ws://localhost:5173/ws/* -> ws://localhost:8001/ws/* ``` If ASGI uses a different port, update `vite.config.ts` accordingly: ```typescript server: { proxy: { '/api': { target: 'http://localhost:8002', changeOrigin: true }, '/ws': { target: 'ws://localhost:8002', ws: true }, }, } ``` > Frontend changes do not need `npm build` unless build validation is explicitly requested. ## 9. Frontend-backend request flow Development: ```text Browser (localhost:5173) -> Vite proxy -> /ws/* -> ASGI (localhost:8001 or custom port) -> /api/* -> ASGI / Django (localhost:8001 or custom port) ``` Production: ```text Browser (443) -> Nginx -> /ws/* -> ASGI (asp-asgi:8001) -> /api/* -> WSGI / Django (asp-web:8000) -> /* -> Frontend static files ``` ## 10. Custom directory During source development, `backend/custom/` mirrors the `custom/` directory in the Compose release package: ```text backend/custom/ modules/ playbooks/ data/ modules/ siem/ playbooks/ requirements.txt ``` * `backend/custom/modules/`: Custom Modules. * `backend/custom/playbooks/`: Custom Playbooks. * `backend/custom/data/siem/`: Custom SIEM YAML. * `backend/custom/data/playbooks/`: Custom Playbook prompts. * `backend/custom/requirements.txt`: Extra Python packages required by custom code. To test custom dependencies, install them into a local custom package directory and add it to `PYTHONPATH`: ```bash mkdir -p .custom-packages uv pip install --python .venv/bin/python --target .custom-packages -r custom/requirements.txt export PYTHONPATH="$(pwd)/.custom-packages:$(pwd)/custom" ``` > After changing scripts or YAML files, use `Refresh / Validate` in the ASP frontend [Custom Console](../custom-console/). ## Next Steps * [Mock Data](../mock-data/) — Generate workspace data or SIEM test logs. * [Custom Console](../custom-console/) — Refresh and validate locally loaded custom definitions. * [Module Development](../module-examples/) — Write custom alert processing Modules. * [Playbook Development](../playbook/) — Write automation tasks triggered from Cases. --- --- url: 'https://asp.viperrtp.com/asp/quick-start/environment-variables.md' --- # Environment Variables Docker Compose uses `.env` in the `asp-compose/` directory. On first initialization, `init.sh` creates it from `.env.example` and generates random Django, PostgreSQL, Redis, and RustFS credentials. Apply changes with: ```bash docker compose up -d ./scripts/doctor.sh ``` ::: warning Protect .env `.env` contains service passwords and secrets. Restrict access and never commit it. ::: ## Images | Variable | Default | Description | | --- | --- | --- | | `ASP_BACKEND_IMAGE` | Current backend image | Used by backend, Worker, and migration services. | | `ASP_FRONTEND_IMAGE` | Current frontend image | Used by the HTTPS entrypoint and frontend. | The upgrade script updates both variables from the latest release package. ## HTTPS entrypoint | Variable | Default | Description | | --- | --- | --- | | `ASP_BIND` | `0.0.0.0` | Host bind address. | | `ASP_HTTPS_PORT` | `443` | Host HTTPS port. | | `ASP_PUBLIC_HOSTNAME` | `localhost` | CN and SAN used only for the fallback self-signed certificate. | | `ASP_CERT_EXTRA_SAN` | Empty | Extra SAN entries, such as `DNS:asp.example.com,IP:10.0.0.10`. | | `ASP_MAX_UPLOAD_SIZE` | `20m` | Maximum request body accepted by Nginx. | Certificate hostname settings apply only when `certs/asp.crt` and `certs/asp.key` do not exist. ## Web API | Variable | Default | Description | | --- | --- | --- | | `ASP_WEB_WORKERS` | `3` | Gunicorn worker processes. | | `ASP_WEB_THREADS` | `4` | Threads per worker. | | `ASP_WEB_TIMEOUT` | `210` | Request timeout in seconds; Nginx derives its proxy timeout from it. | | `ASP_WEB_KEEPALIVE` | `5` | HTTP keep-alive duration in seconds. | | `ASP_WEB_MAX_REQUESTS` | `1000` | Requests handled before recycling a worker. | | `ASP_WEB_MAX_REQUESTS_JITTER` | `100` | Random offset for worker recycling. | | `ASP_DOCTOR_WAIT_SECONDS` | `180` | Maximum seconds `doctor.sh` waits for services. | More workers and threads increase CPU, memory, and PostgreSQL connection usage. ## Management UIs | Variable | Default | Description | | --- | --- | --- | | `ASP_MANAGEMENT_BIND` | `0.0.0.0` | Host bind address for both management UIs. | | `ASP_REDIS_UI_PORT` | `8001` | Redis Stack UI host port. | | `ASP_RUSTFS_CONSOLE_PORT` | `9001` | RustFS Console host port. | Restrict production access with a firewall or VPN. See [Service Management UIs](../../development/management-uis/). ## Django | Variable | Default | Description | | --- | --- | --- | | `DJANGO_SECRET_KEY` | Generated | Django signing secret. | | `DJANGO_DEBUG` | `false` | Enables Django Debug; keep disabled in production. | | `DJANGO_ALLOWED_HOSTS` | `*` | Comma-separated accepted Host values. | | `DJANGO_LOG_LEVEL` | `INFO` | Application root log level. | | `DJANGO_LOG_LEVEL_DJANGO` | `INFO` | Django framework log level. | | `DJANGO_LOG_FORMAT` | `text` | `text` or `json`. | ## PostgreSQL ### Connection | Variable | Default | Description | | --- | --- | --- | | `POSTGRES_DB` | `asp` | Database name. | | `POSTGRES_USER` | `postgres` | Database user. | | `POSTGRES_PASSWORD` | Generated | Database password. | | `POSTGRES_HOST` | `postgres` | Database host used by ASP. | | `POSTGRES_PORT` | `5432` | Database port used by ASP. | | `POSTGRES_CONN_MAX_AGE` | `60` | Django persistent connection lifetime in seconds. | | `POSTGRES_CONN_HEALTH_CHECKS` | `true` | Checks persistent connections before reuse. | ### Server tuning | Variable | Default | Description | | --- | --- | --- | | `POSTGRES_MAX_CONNECTIONS` | `150` | Maximum database connections. | | `POSTGRES_SHARED_BUFFERS` | `512MB` | PostgreSQL shared buffers. | | `POSTGRES_EFFECTIVE_CACHE_SIZE` | `2GB` | Planner estimate of available cache; not a direct allocation. | | `POSTGRES_WORK_MEM` | `8MB` | Memory available per sort or hash operation. | | `POSTGRES_MAINTENANCE_WORK_MEM` | `256MB` | Memory for maintenance operations. | | `POSTGRES_CHECKPOINT_COMPLETION_TARGET` | `0.9` | Fraction of the checkpoint interval used for writes. | | `POSTGRES_RANDOM_PAGE_COST` | `1.1` | Planner random page read cost. | | `POSTGRES_LOG_MIN_DURATION_STATEMENT` | `1000` | Slow-query logging threshold in milliseconds. | PostgreSQL memory settings are cumulative. Evaluate host memory, connection count, and workload before changing them. ## Redis | Variable | Default | Description | | --- | --- | --- | | `REDIS_HOST` | `redis-stack` | Redis host used by ASP. | | `REDIS_PORT` | `6379` | Redis port used by ASP. | | `REDIS_DB` | `1` | Redis logical database used by ASP. | | `REDIS_PASSWORD` | Generated | Redis password. | ## RustFS | Variable | Default | Description | | --- | --- | --- | | `RUSTFS_ENDPOINT_URL` | `http://rustfs:9000` | S3-compatible API endpoint used by ASP. | | `RUSTFS_ACCESS_KEY` | `asp` | S3-compatible Access Key. | | `RUSTFS_SECRET_KEY` | Generated | S3-compatible Secret Key. | | `RUSTFS_BUCKET` | `asp` | Bucket used for attachments and objects. | | `RUSTFS_REGION` | `us-east-1` | Region used for S3 request signing. | ## Changing credentials After initialization, do not change only the PostgreSQL, Redis, or RustFS password in `.env`. Existing server credentials do not update automatically. For credential rotation, change the credential in the service first, then update `.env` and run `docker compose up -d`. ## Next Steps * [Restart & Operations](../operations/) — Apply settings and check services. * [Service Management UIs](../../development/management-uis/) — Access Redis Stack UI and RustFS Console. * [Backup & Restore](../backup-restore/) — Back up before important configuration changes. --- --- url: 'https://asp.viperrtp.com/asp/quick-start/first-login.md' --- # First Login ASP supports Platform account and LDAP account login. The login page provides Platform / LDAP switching. ## Login Page After opening the ASP access URL, you will enter the login page. Select `Platform` to log in with a Platform account, select `LDAP` to log in with enterprise LDAP credentials. ![Login Page](img.png) ## Platform Account Platform accounts are managed by the Django user system. If an administrator was not created during deployment, run: ```bash docker compose exec asp-web python manage.py createsuperuser ``` The created admin is a Django superuser, use `Platform` on the login page to log in. For more details on admin account maintenance, see [User Management](../../settings/users/#admin-account). ## User Management After logging in with the admin account, go to the [User Management](../../settings/users/) page in system settings to create regular users or read-only users. | Role | Description | |------|-------------| | admin | Django superuser, can access system settings. | | user | Can create, update, and delete business resources. | | viewer | Read-only user. | Web UI can only create and assign `user` / `viewer`, cannot create admin. ## LDAP Account LDAP login requires first enabling and configuring [LDAP](../../settings/ldap/) in system settings, and using the test function to confirm connection and account query are available. LDAP does not automatically create ASP users. The admin needs to first create an ASP user with Authentication Type set to LDAP, then the user can select `LDAP` on the login page and log in with LDAP password. Platform users cannot log in via LDAP, and LDAP users cannot log in via Platform password. ## Login Failure Troubleshooting | Symptom | Check | |---------|-------| | Invalid credentials | Confirm username, password, and Platform / LDAP selection match. | | LDAP user cannot log in | Confirm the same-name LDAP user exists in ASP, LDAP settings are enabled and tested. | | Platform user cannot log in | Confirm Platform is selected and the account is not disabled. | | Admin cannot access system settings | Confirm the account is a Django superuser. | ## Next Steps * [System Settings](../../settings/) — Configure LLM, SIEM, Threat Intelligence, and Runtime. * [User Management](../../settings/users/) — Create team member accounts. * [Personal Center](../../workspace/personal-center/) — Maintain your profile and create API Keys when needed. --- --- url: 'https://asp.viperrtp.com/asp/overview/glossary.md' --- # Glossary | Term | Meaning | |------|---------| | Case | A security case, the primary object for managing and tracking the security incident handling process. Contains status, severity, priority, disposition, assignee, summary, AI investigation report, discussion, and associated Playbook. | | Alert | An alert, typically from SIEM, EDR, cloud platforms, or Webhook. Alert is associated with Case and preserves context such as rules, products, MITRE, and raw logs; analysts typically investigate based on alerts and do not directly modify alert data. | | Artifact | An entity, evidence item, or IOC related to a security incident, such as IP, domain, URL, file hash, account, host, process, etc. Queries, responses, and enrichment typically revolve around Artifact. | | Enrichment | Enrichment results, recording external context such as threat intelligence, reputation, assets, identity, history, and response recommendations. | | Knowledge | Knowledge, supports manual maintenance and can also be extracted from investigation records and discussions of closed Cases. Used to accumulate reusable security experience for SOC teams and support future investigations, AI analysis, and Harness Agent retrieval. | | Playbook | An automation task record. Currently triggered from Case, records playbook name, user input, execution status, and background task ID. Common statuses include Pending, Running, Success, Failed. | | Investigation Report | A structured investigation report generated by AI analysis, typically containing disposition, attack chain, IOC, impact, and remediation recommendations. | | Raw Log | The raw log content of an Alert, typically stored in JSON, used for tracing alert sources and complete context. | | Unmapped Data | Data in the raw alert that is not mapped to standard fields. It preserves original information but is typically not the focus of default AI analysis. | | Module | A Python alert processing script for streaming alert processing. Module extracts fields and IOC from alert messages, performs correlation and aggregation, and generates or updates Case, Alert, and Artifact. | | User Input | Natural language supplementary requirements provided by users when executing Playbook, which LLM or automation tasks reference during execution. | | Comment | Discussion and supplementary context in resource details. Case Comments are referenced by LLM as part of the investigation context. | | Case Log / Timeline | Timeline that records Case status changes, field updates, related resource changes, and key operation sequences, used to reconstruct the incident handling process. | | Inbox | In-app messages, used to send system or user messages to users, can associate resources and attachments. | | Audit Log | Audit log, records resource creation, update, deletion, as well as changed fields and operators. | | LLM Provider | Large model configuration item, containing name, Base URL, model, API Key, proxy, tags, and priority. | | Runtime | Agentic runtime configuration, currently includes parameters such as prompt language and Stream length; default Prompt Language is `en`, Stream Maxlen is `10000`. | | Harness Agent | An external agent / CLI environment that hosts and runs ASP Skills, such as Claude Code, Codex, GitHub Copilot CLI, and Gemini CLI. They typically have code editing and tool-calling capabilities, and can work around Case, Artifact, SIEM logs, threat intelligence, Module, and Playbook. | | Skills | Capability descriptions and operating conventions for Harness Agents, allowing Harness Agents to call ASP resources, query logs, use threat intelligence, and help write Module / Playbook code. | | asp-cli | The ASP command-line tool, providing a unified entry point for users and Skills to access ASP APIs. | | Webhook | An entry point for external SIEM or alert systems to connect to ASP, for example Splunk / Kibana alerts can enter the platform through Webhook. | | ELK Index Action | An ingestion method where Kibana first writes actions to an Elasticsearch index, then ASP worker polls and converts them into alerts. | | SIEM YAML | A YAML configuration describing Splunk / ELK indexes, fields, and default aggregation fields, used for Harness Agents to understand and query logs. | | Personal Center | Personal center, where current users maintain their profile, personal settings, password, and API Key. | --- --- url: 'https://asp.viperrtp.com/asp/workspace/inbox.md' --- # Inbox Inbox is ASP's in-app messaging capability, used to receive system notifications, user messages, and resource-related collaboration reminders. ## Entry and List The message button at the top of the frontend displays the unread count; clicking it opens the Inbox Drawer. ![Inbox Entry](img.png) Inbox supports viewing all messages or only unread messages, and also supports refreshing the list and Mark all read. Clicking a message loads the details and marks the current user's receipt status as read. ![Inbox List](img_1.png) ## Message Types * System: System messages. * User: User messages. Each recipient has an independent read status, so the same message can have different read / unread status for different users. ## Message Content Messages display sender, send time, message type, body, attachments, and associated resources. Image attachments can be previewed, and other files can be opened or downloaded. If a message is associated with a resource, Inbox displays the resource type and resource label; clicking it opens the corresponding detail page to continue processing. ![Message Detail](img_2.png) ## Send and Reply When sending a User message, you need to `@` at least one user in the body as a recipient, and you can also attach files or paste images. User messages support replies; System messages cannot be replied to. Users can only delete their own User messages, and cannot delete System messages or messages from others. ![Send or Reply Message](img_3.png) ## Associated Resources Inbox messages can be associated with the following resources: * Case * Alert * Artifact * Enrichment * Playbook * Knowledge * User `@` mentioning users in Comments generates Inbox messages and associates the current resource. When users reply from such messages, the reply content is also synchronized back to the corresponding resource's Comments. ## Common Uses * Notify users to follow a Case, Alert, or Artifact. * Send system processing results. * Conduct lightweight collaboration around security resources. * Enter the corresponding resource from @ mentions in Comments to continue processing. ## Next Steps * [Case](../case/) — See how Comments, @ mentions, and resource collaboration happen in cases. * [Personal Center](../personal-center/) — Configure personal notification preferences and API Keys. * [Audit Log](../audit-log/) — Distinguish collaboration notifications from resource change audit records. --- --- url: 'https://asp.viperrtp.com/asp/integrations.md' --- # Integrations ASP currently recommends CLI and Skills for integrating Harness Agents and command-line automation: | Integration | Description | |-------------|-------------| | [CLI](cli/) | Provides the `asp` command for authentication, ASP resource queries, Playbook execution, SIEM / threat intelligence / CMDB lookups, and stable JSON output for automation and Skills. | | [Skills](skills/) | Uses `asp-cli` and the skills.sh registry to let Harness Agents use ASP Case, Alert, Artifact, SIEM, Playbook, and other capabilities. | ## Next Steps * [CLI](cli/) — Install and configure the `asp` command. * [Skills](skills/) — Let Harness Agents use ASP capabilities. * [SIEM Search](skills/asp-siem-search/) — Learn how Harness Agents query SIEM logs. --- --- url: 'https://asp.viperrtp.com/asp/development/alert-ingestion/kibana-webhook.md' --- # Kibana Webhook Kibana Webhook sends Kibana Rule matches directly to ASP and writes them into Redis Stream for Module consumption. ## Endpoint ```text POST /api/webhook/kibana/ ``` Replace the domain with your ASP backend address, for example: ```text https://asp.example.com/api/webhook/kibana/ ``` ## Create Webhook Connector Create a Webhook connector in Kibana and set the URL to the ASP endpoint: ```text https:///api/webhook/kibana/ ``` ![Kibana Webhook Connector](img_9.png) ![Kibana Webhook URL](img_10.png) ## Create Rule Create a Kibana Alert Rule and configure query conditions, execution schedule, and trigger conditions. ![Kibana Rule](img.png) ![Kibana Rule conditions](img_1.png) ## Configure Action Add a Webhook Action to the Rule and use the connector created earlier. ![Kibana Webhook Action](img_11.png) ![Kibana Action parameters](img_12.png) ASP's Kibana Webhook expects this JSON structure: ```json { "rule": { "name": "{{rule.name}}" }, "context": { "hits": [{{{context.hits}}}] } } ``` Field description: | Field | Description | | --- | --- | | `rule.name` | Kibana Rule name. It is used as the Redis Stream name. | | `context.hits` | Matched events. ASP writes each item to Stream. | ## Verification After the Rule triggers, Kibana sends a request to ASP Webhook. ASP extracts `_source` from each hit and writes it to the Redis Stream named by `rule.name`. View written messages in Redis or [Custom Console](../../custom-console/) to confirm that a Module can consume them. ![Kibana Stream message](img_14.png) ## Recommendations * Webhook requires Kibana to directly access the ASP backend. * If the network does not allow direct POST to ASP, or ELK uses Community Edition, use [ELK Index Action](../elk-index-action/). * Keep Rule name consistent with the Stream name expected by the backend Module. * Preserve key fields in `_source` for Case, Alert, and Artifact mapping. * For complete examples, see [Custom Module Examples](../../custom-examples/modules/). ## Next Steps * [ELK Index Action](../elk-index-action/) — Use indirect ingestion when Kibana cannot directly POST to ASP. * [Module Development](../../module-examples/) — Write a Module that consumes the Kibana Stream. * [Custom Console](../../custom-console/) — Check Stream messages and Module loading status. --- --- url: 'https://asp.viperrtp.com/asp/workspace/knowledge.md' --- # Knowledge Knowledge is used to accumulate reusable security experience, allowing teams to save disposition conclusions, false positive judgments, investigation steps, and IOC assessment experience as searchable, reusable knowledge. ## View The Knowledge list is used to centrally manage knowledge entries. The list displays Knowledge ID, Title, Source, Case, Tags, Expires At, Created Time, Updated Time, and Body. The list supports quick filtering by Source and Tags, and also supports advanced filtering by Knowledge ID, Source, Tags, Title, Body, Expires At, Created Time, and Updated Time to locate records. ![Knowledge List](img.png) ## Sources Currently supports two types of sources: | Source | Description | |--------|-------------| | Manual | Manually created knowledge. | | Case | Knowledge extracted from Case. | Case-sourced Knowledge must be associated with a Case; Manual-sourced Knowledge is not associated with a Case. One Case corresponds to at most one extracted Knowledge. ## Key Fields * Knowledge ID: System-generated readable ID. * Title: Title. * Body: Body, supports Markdown. * Source: Source. * Tags: Tags. * Expires At: Expiration time, empty means long-term valid; after expiration, it no longer participates in knowledge search and Harness Agent retrieval. ## Basic Basic displays the core information of the knowledge entry: Knowledge ID, Source, Case, Expires At, Title, Tags, and Body. Case-sourced Knowledge displays the source Case; clicking it returns to the corresponding Case to view investigation context. Body uses Markdown display, suitable for saving structured analysis steps, judgment basis, and response recommendations. ![Knowledge Detail](img_1.png) ## Add and Edit Analysts can manually add new knowledge in the Knowledge list, filling in Title, Expires At, Tags, and Body. Manually created knowledge has Source set to `Manual`. ![img\_2.png](img_2.png) The detail page supports editing Title, Expires At, Tags, and Body. Case-sourced Knowledge is typically generated by the `Knowledge Extraction` Playbook, and content can also be further organized on the detail page. ## Knowledge Extraction The `Knowledge Extraction` Playbook extracts reusable knowledge from Cases that already have an analyst verdict. During execution, it reads the Case investigation context, generates title, body, and tags, and saves it as Knowledge with Source set to `Case`. If the Case has no verdict, the Playbook skips extraction to avoid accumulating unconfirmed investigation processes as organizational knowledge. ## Usage Recommendations * Write recurring disposition experience into Knowledge. * After closing key Cases, extract knowledge through Playbook. * Accumulate false positive judgments, investigation steps, IOC assessment experience, and response recommendations as searchable content. * Use Tags to categorize by attack type, business system, data source, or response action. * Set Expires At for short-term valid intelligence or temporary disposition experience. * Reference similar experience in subsequent investigations. ## Next Steps * [Case](../case/) — See how Knowledge is extracted from confirmed case context. * [Playbook](../playbook/) — Learn about automation task records such as `Knowledge Extraction`. * [Tags](../../settings/tags/) — Maintain tags used for knowledge categorization and retrieval. --- --- url: 'https://asp.viperrtp.com/asp/settings/ldap.md' --- # LDAP LDAP is used to connect to enterprise identity sources. ## Entry LDAP settings are located in the `LDAP` Tab of System Settings. ![LDAP Settings](img.png) ## Configuration Items | Field | Description | |-------|-------------| | Enabled | Whether to enable LDAP login. | | Server URI | LDAP server address, must start with `ldap://` or `ldaps://`. | | Domain | Used in direct bind mode to build `username@domain`. | | Bind DN | Optional service account DN for searching users first. | | Bind Password | Password for Bind DN. | | User Search Base DN | Starting DN for user search. | | User Login Attr | Login name matching field, default `uid`. | ## Common Windows AD Configuration Windows Active Directory typically uses search bind mode: | Field | Example | |-------|---------| | Server URI | `ldaps://ad.example.com:636` or `ldap://ad.example.com:389` | | Domain | `example.com` | | Bind DN | `svc_asp@example.com` or `CN=svc-asp,OU=Service Accounts,DC=example,DC=com` | | Bind Password | Service account password | | User Search Base DN | `DC=example,DC=com` or `OU=Users,DC=example,DC=com` | | User Login Attr | `sAMAccountName` | If you want users to log in with UPN, set `User Login Attr` to `userPrincipalName` and require users to enter the full UPN on the login page, such as `alice@example.com`. ## Confirm Configuration on a Domain-Joined Windows Host If the current Windows host has already joined the domain, first use local PowerShell to confirm the domain name, domain controller, and port connectivity: ```powershell $domain = $env:USERDNSDOMAIN $domain nltest /dsgetdc:$domain ``` The `DC` or `Address` value in `nltest` output can be used to identify the domain controller. Then check LDAP / LDAPS ports: ```powershell Test-NetConnection -Port 636 Test-NetConnection -Port 389 ``` If port 636 is available, prefer `ldaps://:636`; otherwise use `ldap://:389`. | ASP field | How to confirm | |-----------|----------------| | Server URI | Use `nltest /dsgetdc:$domain` to find the domain controller, then choose `ldaps://:636` or `ldap://:389` based on the port. | | Domain | Usually use `$env:USERDNSDOMAIN`, for example `example.com`. | | Bind DN | Prefer a dedicated service account UPN such as `svc_asp@example.com`; a full DN also works. | | Bind Password | Service account password. It cannot be read from local commands and must be provided or reset by an AD administrator. | | User Search Base DN | Usually derived from the domain name, for example `example.com` becomes `DC=example,DC=com`; you can narrow it to the OU where users actually live. | | User Login Attr | Windows AD usually uses `sAMAccountName`; use `userPrincipalName` if users should enter full UPNs. | If the RSAT Active Directory module is installed, you can further confirm DNs: ```powershell Import-Module ActiveDirectory Get-ADDomain | Select-Object DNSRoot, DistinguishedName, PDCEmulator Get-ADUser svc_asp -Properties UserPrincipalName, DistinguishedName | Select-Object SamAccountName, UserPrincipalName, DistinguishedName ``` ## Authentication Mode When `User Search Base DN` is configured, the backend will first use Bind DN / Bind Password for service bind, then search for user DN by `User Login Attr=`, and finally use the user's input password to bind that user DN. When `User Search Base DN` is not configured, the backend will directly bind the user: if Domain is configured, use `username@domain`; otherwise use `username` directly. ## Test Connection When Test Username / Test Password are not filled in, Test only verifies whether LDAP bind succeeds. When test account is filled in, username and password must be provided together, and the backend will execute a complete user authentication according to current configuration. ![LDAP Test](img_1.png) ## Login Flow 1. Admin enables and saves LDAP configuration. 2. Use test function to confirm connection and account query are available. 3. Admin creates ASP user with Authentication Type set to LDAP in user management. 4. User switches to LDAP on login page. 5. Backend confirms ASP user exists, account is enabled, authentication type is LDAP. 6. Backend uses LDAP to verify user credentials and logs in as that ASP user. ![LDAP Login](img_2.png) LDAP login does not automatically create ASP users, nor does it automatically assign roles. `Local Password` users cannot log in with LDAP, and LDAP users cannot log in with `Platform`. ## Security and Audit Bind Password is hidden by default. Saving configuration, testing connection, and revealing Bind Password are all written to Audit Log; password fields in audit records only record whether a value changed or was revealed, not plaintext secrets. After saving configuration, the backend refreshes the LDAP runtime cache so later logins use the latest settings. ## Usage Recommendations * Prefer `ldaps://` in production environments. * Windows AD typically uses `sAMAccountName` as User Login Attr. * Control User Search Base DN to the actual user's OU or domain scope. * First use Test Username / Test Password to verify real user login before opening to users. ## Next Steps * [User Management](../users/) — Create ASP users with Authentication Type set to LDAP. * [First Login](../../quick-start/first-login/) — Review Platform / LDAP login methods. * [Personal Center](../../workspace/personal-center/) — Understand password-change differences between LDAP and Platform users. --- --- url: 'https://asp.viperrtp.com/asp/settings/llm-provider.md' --- # LLM Provider LLM Provider defines the large model connection method used by ASP. AI investigation, knowledge extraction, and Runtime select models from enabled Providers by tags and priority. ## View LLM Providers list displays Name, Base URL, Model, Tags, Enabled, and Priority. The list supports quick filtering by Enabled and Tags, and also supports advanced filtering by Name, Base URL, Model, Enabled, and Priority to locate configurations. ![LLM Provider List](img.png) ## Fields | Field | Description | |-------|-------------| | Name | Configuration name, unique. | | Base URL | OpenAI Chat Completions compatible model service address. | | Model | Model name. | | API Key | Access key, can be filled according to model service requirements. | | Proxy | Optional proxy. | | Tags | Model capability tags. | | Enabled | Whether enabled. | | Priority | Priority, smaller number means higher priority. | ## Add and Edit Admins can add, edit, enable, disable, or delete LLM Providers. When editing, saved configuration is read; API Key is hidden by default, only loaded through reveal when editing. ![Add or Edit LLM Provider](img_1.png) Proxy supports addresses starting with `http://`、`https://`、`socks4://`、`socks5://`。 ## Tag Selection Common tags: * `fast` * `powerful` * `tool_calling` * `structured_output` At least one tag must be filled. The frontend provides common tags, but you can also add custom tags based on actual scenarios. Different tasks select appropriate models based on tags. For example, structured output tasks prefer Providers tagged with `structured_output`. ## Test Connection When adding or editing configuration, you can directly Test; saved Providers can also be Test from the list. The test will call the Provider's Chat Completions compatible interface and send a simple request to confirm model service is available. ![LLM Provider Test](img_2.png) ## Runtime Selection Only Enabled Providers enter runtime configuration. Runtime sorts by Priority, Name, Created Time: * When no tag is specified, use the first Provider after sorting. * When one tag is specified, select the first Provider containing that tag. * When multiple tags are specified, select the first Provider containing all tags. If there are no enabled Providers, or no Providers matching specified tags, related AI tasks will fail. ## Security and Audit Creating, updating, deleting, testing, and revealing API Key are all written to Audit Log. API Key fields in audit records only record whether a value changed or was revealed, not plaintext secrets. ## Usage Recommendations * At least configure one enabled `structured_output` Provider for investigation reports and knowledge extraction. * Use Priority to control default model selection order, smaller number means higher priority. * Use Tags to distinguish fast models, strong reasoning models, tool calling models, and structured output models. * After saving, first execute Test to confirm Base URL, Model, API Key, and Proxy configuration are correct. ## Next Steps * [Runtime](../runtime/) — Configure Prompt Language and runtime parameters. * [Case](../../workspace/case/) — See how LLM Provider supports case investigation reports. * [Knowledge](../../workspace/knowledge/) — See how structured output is used for knowledge extraction. --- --- url: 'https://asp.viperrtp.com/asp/development/mock-data.md' --- # Mock Data Mock data is used to experience the ASP workspace, verify Module / Playbook flows, or write simulated logs to SIEM when there are no real alert sources. > SIEM Mock logs can be used with [Alert Ingestion](../alert-ingestion/), example SIEM YAML, Splunk SPL / ELK ES|QL queries, and Modules in [Custom Examples](../custom-examples/) to demonstrate the full log-to-Case flow. The backend currently provides two types of Mock: | Type | Location | Purpose | | --- | --- | --- | | ASP Workspace Mock Data | `backend\mock\import_mock_data.py` | Directly writes Case, Alert, Artifact, Enrichment, Knowledge, and Playbook examples to the ASP database. | | SIEM Mock Logs | `backend\mock\siem\` | Generates network, host, and cloud logs, and sends them to ELK or Splunk. | ## Import ASP Workspace Mock Data Execute in the `backend` directory: ```powershell .\.venv\Scripts\python.exe manage.py shell -c "from mock.import_mock_data import run; run()" ``` This script can be run repeatedly. Each run creates a new mock batch and does not overwrite or clean up historical mock data. After import, you can see in the workspace: * Multiple Cases of different categories, such as EDR, IAM, NDR, Email, DLP, WAF, Proxy, Threat Intelligence. * Associated Alerts. * Artifacts. * Enrichments. * Knowledge. * Playbook execution records. Cases will contain realistic TTD, TTA, TTR timeline information and cover statuses such as New, In Progress, On Hold, Resolved, and Closed. The script creates the following example users, all with password `mockpass`: | User | Description | | --- | --- | | `alice.chen` | Analyst example user. | | `bob.li` | Analyst example user. | | `maya.singh` | Analyst example user. | | `automation` | Automation operation example user. | ## Generate SIEM Mock Logs SIEM Mock is used to write simulated logs to ELK or Splunk. It continuously generates three types of index data: | Index | Scenario | | --- | --- | | `siem-network-traffic` | Network traffic and brute force scenarios. | | `siem-host-events` | Host events and ransomware behavior scenarios. | | `siem-aws-cloudtrail` | Cloud logs and privilege escalation scenarios. | First copy and edit the configuration: ```powershell Copy-Item .\mock\siem\.env.example .\mock\siem\.env ``` `.env` example: ```text MOCK_SIEM_ELK_ENABLED=true MOCK_SIEM_ELK_HOST=http://localhost:9200 MOCK_SIEM_ELK_KEY=replace-me MOCK_SIEM_SPLUNK_ENABLED=true MOCK_SIEM_SPLUNK_HEC_URL=http://localhost:8088/services/collector MOCK_SIEM_SPLUNK_TOKEN=replace-me ``` Start the generator: ```powershell .\.venv\Scripts\python.exe -m mock.siem.main ``` The generator will batch send logs to ELK `_bulk` or Splunk HEC according to configuration. ## Runtime Parameters The basic runtime parameters for SIEM Mock are in `backend\mock\siem\settings.py`: | Parameter | Default | Description | | --- | --- | --- | | `EPS` | `10` | Events per second. | | `BATCH_SIZE` | `100` | Number generated per batch. | | `MALICIOUS_PERCENTAGE` | `0.05` | Probability of injecting anomaly scenarios. | ## Usage Recommendations * To quickly experience the workspace: first import ASP Workspace Mock Data. * To verify SIEM queries, SIEM YAML, Module, or alert ingestion: use SIEM Mock Logs. * SIEM Mock continuously sends data, remember to stop the process after testing. * Do not import Mock data or run Mock log generators in production environments. ## Next Steps * [Dashboard](../../workspace/dashboard/) — View the workspace overview after importing data. * [Case](../../workspace/case/) — Inspect Mock Cases, Alerts, Artifacts, and investigation context. * [SIEM YAML](../siem-yaml/) — Maintain index field descriptions for SIEM Mock logs. * [Custom Examples](../custom-examples/) — Validate the complete chain with sample Modules, Playbooks, and SIEM YAML. --- --- url: 'https://asp.viperrtp.com/asp/development/module-examples.md' --- # Module Development Module is used to automatically consume raw alerts from Redis Stream and convert them into Case / Alert / Artifact in the ASP workspace. > A Module usually consumes Redis Streams written by [Alert Ingestion](../alert-ingestion/). To see complete raw alert → Module → Case / Alert / Artifact examples, read [Custom Module Examples](../custom-examples/modules/). ## Script Location User-defined Modules are placed in: ```text custom/modules/ ``` Local development examples and raw alerts are located at: ```text backend/custom/modules/ backend/custom/data/modules/ ``` Module files are automatically discovered by the backend. Each file needs to define a `Module` class that inherits from `BaseModule` and sets `STREAM_NAME`. ## Basic Structure ```python from apps.agentic.runtime.base import BaseModule class Module(BaseModule): NAME = "Human readable name" DESC = "Short description" STREAM_NAME = "SIEM-Rule-Or-Stream-Name" THREAD_NUM = 1 def run(self, message): # message is the raw alert dict read from Redis Stream ... ``` ## Execution The Module worker scans `custom\modules\*.py`, discovers `Module` classes inheriting from `BaseModule`, then consumes Redis Stream by `STREAM_NAME`. ```bash python manage.py run_agentic_module_worker ``` The default consumer group is `agentic-modules`. The Stream names written by Webhook and ELK Index Action need to correspond to the Module's `STREAM_NAME`. After modifying a Module, click `Refresh / Validate` in [Custom Console](../custom-console/) → `Modules` to view loading results and inspect the related Redis Stream status. If the Module introduces new third-party packages, update `custom\requirements.txt` and reinstall dependencies first. ## Processing Flow 1. Read raw alert. 2. Parse event time; prefer `parse_event_time()`. 3. Extract key fields and Artifact, such as IP, domain, account, host, file, process. 4. Design `correlation_uid`; prefer `generate_correlation_uid()`. 5. Use `create_alert_with_context()` to create or associate Case, Alert, Artifact, and Enrichment. 6. Trigger Case AI analysis when necessary. ## Current Examples Example scripts in the source repository are located at `backend\custom\modules\`, raw alert samples are at `backend\custom\data\modules\`. The `custom/` directory created by `init.sh` does not include these test examples. * `aws_iam_privilege_escalation_attach_user_policy.py` * Processes AWS CloudTrail `AttachUserPolicy` high-risk IAM behavior. * Example focus: Cloud account, subject identity, target user, permission policy, and source IP. * `edr_vssadmin_delete_shadows.py` * Processes EDR `vssadmin delete shadows` type ransomware precursor behavior. * Example focus: Host, user, process, command line, and file hash. * `mail_user_report_phishing.py` * Processes user-reported phishing emails. * Example focus: Sender, recipient, reporter, subject, URL, domain, and attachments. ## Recommended Data Destinations Module should output or associate as much useful context as possible: * Case: Disposition entry for the same incident. * Alert: Detection context and raw logs. * Artifact: IOC, account, host, file, process, and other entities. * Enrichment: Reusable external context. ## Design Recommendations * Keep `STREAM_NAME` consistent with SIEM Rule / Redis Stream name. * Do not use random fields as aggregation keys, such as request id, session id, exact timestamps. * One Case should represent one investigatable, actionable security incident, not a single log. * Split Artifacts into investigable atomic entities where possible. * Store the original raw alert in Alert `raw_data`, and put valuable unmapped fields into `unmapped`. * Use the [Module Creator](../../integrations/skills/asp-module-creator/) Skill to help draft Modules. ## Next Steps * [Custom Console](../custom-console/) — Refresh, validate, and inspect Module loading results. * [Alert Ingestion](../alert-ingestion/) — Write SIEM alerts into Redis Stream. * [Custom Modules](../custom-examples/modules/) — View complete Module examples. * [Playbook Development](../playbook/) — Write downstream automation tasks triggered from Cases. --- --- url: 'https://asp.viperrtp.com/asp/workspace/personal-center.md' --- # Personal Center Personal Center is used for the currently logged-in user to maintain their profile, personal settings, password, and API Key. ## Entry Click the user menu in the upper right corner of the frontend to open Personal Center. All logged-in users can enter Personal Center. ![Personal Center](img.png) ## Profile Profile is used to maintain the current user's personal information: * Avatar * Email * First Name * Last Name * Mobile Phone These fields only affect the current user's profile and do not change user roles or authentication types. ## Settings Settings is used to maintain personal preferences for the current user. It currently includes Notification Preferences: * Notify me when my Playbook runs finish: when enabled, the user who triggered a Playbook receives an Inbox system notification after the run finishes. Both success and failure are notified. * Notify me when a Case is assigned to me: when enabled, the user receives an Inbox system notification when a Case is assigned to them. Notification preferences are enabled by default. Turning them off only affects the current user and does not affect notifications received by other users. Case assignment notifications are sent only to the new assignee. Unassignment, saving the same assignee again, and assigning a Case to yourself do not send notifications. ![img\_3.png](img_3.png) ## Password Platform users can change their password in Personal Center. LDAP users log in with LDAP password, so the local password change page is not displayed. ![img\_2.png](img_2.png) ## API Keys API Key is used for external scripts, tools, or Harness Agents to call ASP API. Each user can only manage their own API Key. API Key supports: * Name: Key name. * Key: Key value starting with `asp_`. * Expires At: Expiration time, empty means no expiration. * Last Used: Last used time. * Refresh: Refresh key value. * Delete: Delete key. ![API Keys](img_1.png) When using API Key to call interfaces, add to the request header: ```http Authorization: Api-Key ``` Expired API Keys cannot continue to be used; if a user is disabled, that user's API Keys also cannot pass authentication. The API Key endpoint is `/api/auth/api-keys/`. ## Next Steps * [Inbox](../inbox/) — View in-app messages controlled by notification preferences. * [User Management](../../settings/users/) — Let administrators maintain users, roles, and authentication types. * [CLI](../../integrations/cli/) — Use API Keys to let external tools access ASP. --- --- url: 'https://asp.viperrtp.com/asp/workspace/playbook.md' --- # Playbook Playbook is an automation task execution record triggered from Case, used to execute user-triggered processes such as AI investigation, knowledge extraction, threat intelligence enrichment, and CMDB enrichment. ## View The Playbook list is used to view all task execution records. The list displays Playbook ID, Name, Status, Case, User, Job ID, Created Time, Updated Time, User Input, and Remark. The list supports quick filtering by Status, and also supports advanced filtering by Playbook ID, Status, Name, Job ID, User Input, Remark, Created Time, and Updated Time to locate records. ![Playbook List](img.png) ## Key Fields * Playbook ID: System-generated readable ID. * Case: Trigger source. * Name: Name of the executed playbook. * User Input: Initial or appended input. * User: Requesting user. * Job Status: Success, Failed, Pending, Running. * Job ID: Background task ID. * Remark: Execution remark. ## Run Playbook Playbook is triggered from the Case detail page. After opening the Case, click the Run Playbook button in the upper right corner. ![Run Playbook Entry](img_0.png) In the dialog, select the Playbook to execute. The list displays Playbook name, tags, and description, and supports search by name, description, or tags. If there are additional requirements, you can supplement them in natural language in User Input. When executing LLM-related Playbooks such as Investigation or Knowledge Extraction, User Input participates as additional context in the analysis. ![Fill in User Input](img_2.png) After submission, a Playbook execution record is created with initial status `Pending`. ## Basic The Playbook detail page displays Playbook ID, Status, Case, User, Name, Job ID, as well as User Input and Remark in Input & Result. The Case field can navigate back to the trigger source. Remark is used to record execution summary or failure reasons. ![img\_2.png](img_2.png) ## Status Flow Playbook status changes follow this flow: ```text Pending → Running → Success / Failed ``` `Pending` means the task has been submitted and is waiting for background scheduling; `Running` means it is being executed; `Success` and `Failed` are terminal states. After execution completes, clicking the task record can view execution details. ## Current Built-in Directions The backend currently includes the following Playbook examples: * Investigation: Case investigation. * Knowledge Extraction: Extract reusable knowledge from Cases that already have an analyst verdict. * Threat Intelligence Enrichment: Query threat intelligence for Case-associated Artifact and write to Enrichment. * CMDB Enrichment: Query asset context for Case-associated Artifact and write to Enrichment. Playbook output should be written back to Case, Knowledge, or Enrichment, rather than staying in temporary logs. ## Usage Recommendations * Trigger Playbook from Case, not directly from Alert or Artifact. * Execute Investigation for cases that need AI investigation reports. * Execute Knowledge Extraction after the Case has a clear verdict to accumulate reusable knowledge. * Execute threat intelligence or CMDB enrichment for cases involving entities such as IOC, hosts, and accounts. * After execution, return to Case, Knowledge, or Enrichment to review results, not just view the Playbook record itself. ## Next Steps * [Case](../case/) — See how Playbooks are triggered from the case war room. * [Knowledge](../knowledge/) — View knowledge capture results from `Knowledge Extraction`. * [Enrichment](../enrichment/) — View threat intelligence and CMDB enrichment results. * [Playbook Development](../../development/playbook/) — Write custom Playbooks. --- --- url: 'https://asp.viperrtp.com/asp/development/playbook.md' --- # Playbook Development Playbook is a Case-oriented automation task in ASP. > To see the source-tree Case Summary and CMDB Enrichment custom Playbook examples, read [Custom Playbook Examples](../custom-examples/playbooks/). ## Script Location When deploying with Compose, user-defined Playbooks are placed in: ```text custom/playbooks/ ``` During source code development, built-in examples are located at: ```text backend/playbooks/ ``` Each file needs to define a `Playbook` class that inherits from `BasePlaybook` and sets `NAME`, `DESC`, and `TAGS`. ## Basic Structure ```python from apps.agentic.runtime.base import BasePlaybook class Playbook(BasePlaybook): NAME = "Playbook Name" DESC = "What this playbook does." TAGS = ["System"] def run(self): if self.case is None: raise ValueError("Playbook requires a linked case.") # self.case is the trigger source Case # self.user_input is the supplementary description filled by the user at runtime return "Execution summary" ``` ## Execution After the user selects a Playbook from the Case detail page and submits, the backend creates a `Pending` Playbook record. The background worker picks up the task and executes the script: ```bash python manage.py run_agentic_playbook_worker ``` After successful execution, the return value is written to the Playbook's `Remark`; on failure, exception information is written to the failure record. After modifying a Playbook, click `Refresh / Validate` in [Custom Console](../custom-console/) → `Playbooks` to view loading results. If the Playbook introduces new third-party packages, update `custom\requirements.txt` and reinstall dependencies first. ## Current Examples * `investigation.py` * Triggers Case AI investigation and writes the report back to Case. * `knowledge_extraction.py` * Extracts reusable knowledge from Cases that already have an analyst verdict. * `threat_intelligence_enrichment.py` * Queries threat intelligence for Case-associated Artifact and writes to Artifact Enrichment. * `custom\playbooks\cmdb_enrichment.py` * Queries CMDB for Case-associated Artifact and writes to Artifact Enrichment. * `custom\playbooks\case_summary.py` * Reads `custom\data\playbooks\case_summary\System_.md`, calls LLM to generate Case Summary. ## Data Destinations Playbook should not only output temporary text. It is recommended to write results back to: * Case: Investigation reports, AI assessments, summaries. * Knowledge: Reusable knowledge extracted from cases. * Enrichment: Threat intelligence, assets, identity, or historical context. * Comment: Natural-language execution summaries, handoff notes, or information that should remain in the resource discussion. * Playbook: Task status, remarks, and background task ID. ## Reading Comment Attachments Custom Playbooks run inside the backend process, so they do not need an external file lookup tool to read comment attachments. Use Django ORM to fetch Comments on the target resource, then read any file type with `attachment.file.open("rb")`: ```python from django.contrib.contenttypes.models import ContentType from apps.comments.models import Comment content_type = ContentType.objects.get_for_model(self.case, for_concrete_model=False) comments = ( Comment.objects .filter(content_type=content_type, object_id=str(self.case.pk)) .prefetch_related("attachments") ) for comment in comments: for attachment in comment.attachments.all(): with attachment.file.open("rb") as file_obj: content = file_obj.read() filename = attachment.filename size = attachment.size ``` Attachments are not restricted by file type. The Playbook should choose parsing logic based on filename, size, and actual content instead of assuming text, image, or JSON. ## Custom Prompts Custom Playbooks can place prompts in: ```text custom/data/playbooks//System_en.md custom/data/playbooks//System_zh.md ``` Playbook reads the corresponding file via `self.read_prompt("System")` based on Runtime's Prompt Language. When the Prompt file is missing, the Playbook fails and writes the error to the task record. ## Design Recommendations * Keep input centered on the Case. * Produce structured output. * Write failure reasons to the task record. * Write external query results to Enrichment for later audit and reuse. * When generating reports or structured judgments, prefer writing them back to Case or Knowledge. * Use the [Playbook Creator](../../integrations/skills/asp-playbook-creator/) Skill to help draft Playbooks. ## Next Steps * [Custom Console](../custom-console/) — Refresh, validate, and inspect Playbook loading results. * [Custom Playbooks](../custom-examples/playbooks/) — View complete Playbook examples. * [Playbook](../../workspace/playbook/) — View Playbook run records and execution results. * [Module Development](../module-examples/) — Write upstream alert processing logic. --- --- url: 'https://asp.viperrtp.com/asp/overview/architecture.md' --- # Product Architecture ASP's product architecture can be understood through two main threads: 1. Data thread: external alerts enter the platform, are converted into unified resources such as Case / Alert / Artifact, and then move into investigation, enrichment, response, and knowledge capture. 2. Collaboration thread: analysts, background automation tasks, LLMs, and Harness Agents work around the same resources instead of maintaining isolated contexts. ASP is therefore not a single AI feature, but a SOC workspace that connects alert ingestion, resource modeling, automation execution, human-agent collaboration, and governance audit. ## Architecture Diagram ![ASP Product Architecture](arch.jpg) ## Layered View | Layer | Description | |-------|-------------| | Ingestion Layer | Receives alerts and log context from sources such as SIEM, Webhook, Splunk, and Kibana. | | Resource Layer | Uses Case, Alert, Artifact, Enrichment, Knowledge, and Playbook as core resources to form a unified security workflow. | | Automation Layer | Module handles streaming alert processing, Playbook handles user-triggered automation tasks, and LLM generates investigation analysis. | | Workspace Layer | The frontend provides Dashboard, lists, details, settings, notifications, Comments, and Timeline so analysts can investigate and respond in one interface. | | Agent Integration Layer | Harness Agents use ASP capabilities through CLI and Skills to read and update Cases, query SIEM, call threat intelligence, and help write Module / Playbook code. | | Configuration and Governance Layer | Manages runtime and governance settings such as LLM Provider, SIEM, AlienVault OTX, OpenCTI, LDAP, Runtime, users/API Keys, and audit logs. | ## Data Flow: From Alert to Case ```text NDR / EDR / XDR / Cloud → SIEM Rule → Webhook / ELK Index Action → Redis Stream → Module Streaming Processing → Case / Alert / Artifact → AI Analysis / Enrichment / Playbook → Knowledge / Response Decision ``` The responsibility of Module is not simply forwarding logs, but extracting IOC, mapping fields, correlating and aggregating, and compressing raw alerts into Cases that analysts can handle. During processing, ASP still preserves Alert and Artifact as evidence context to avoid losing critical information after noise reduction. ## Automation and Background Tasks ASP's background capabilities consist of multiple asynchronous task types: | Task | Function | |------|----------| | ELK Action Worker | Polls Kibana actions from Elasticsearch Action Index and converts them into Webhook alerts. | | Module Worker | Continuously consumes alert messages, generates or updates Case, Alert, and Artifact. | | AI Analysis | Schedules LLM analysis after Case creation or update, generating investigation reports and risk recommendations. | | Playbook Worker | Discovers pending Playbook records and runs tasks such as investigation, knowledge extraction, threat intelligence enrichment, and CMDB enrichment. | These tasks together transform "alerts entering the platform" into "cases being analyzed, enriched, captured as knowledge, and entering response decisions." Analysts do not need to wait synchronously for every step; they can keep seeing new evidence, analysis results, and execution records in the Case. ## Case War Room and Human-Agent Collaboration Case is the primary user interaction object in ASP, not just a ticket container. It is closer to a war room in SOAR: analysts view evidence, assign responsibility, update status, trigger Playbooks, and conduct discussions and supplement context through Comments within the Case. This collaborative content is not ancillary information. Comments are referenced by LLM as part of the Case investigation context to understand leads that analysts have confirmed, denied, or supplemented. Case Log / Timeline records status changes, field updates, associated resource changes, and key operation sequences, helping reconstruct the incident handling process and providing a basis for subsequent report generation and timeline analysis. Harness Agents also enter the same closed loop. Here, Harness Agents include external agent / CLI environments that can host Skills, such as Claude Code, Codex, GitHub Copilot CLI, and Gemini CLI. Users can ask these agents to query SIEM, inspect Artifacts, call threat intelligence, summarize investigation progress, or help write Module / Playbook code based on Case context. Harness Agent output still returns to Case, Knowledge, Enrichment, or Playbook records for analyst review and traceability. Therefore, a Case's analysis context includes not only Alert, Artifact, and Enrichment, but also human judgment, discussions, Harness Agent assistance, and operation traces. ASP's goal is to place machine-generated evidence, Harness Agent assistance, and human response decisions in the same investigation closed loop. ## Typical Workflow 1. Splunk / Kibana ingests alerts via Webhook or ELK Index Action. 2. Module extracts key fields and IOC, generates or updates Case based on correlation rules. 3. Alert preserves detection context, Artifact aggregates entities such as IP, domain, account, host, and file. 4. LLM generates investigation report, Enrichment supplements threat intelligence, asset, identity, and historical context. 5. Analysts discuss leads, supplement judgments, adjust status in the Case war room, and preserve operation traces through Timeline. 6. Users can use Harness Agents to continue querying SIEM, analyzing Artifacts, calling threat intelligence, or generating follow-up investigation and automation suggestions. 7. Analysts trigger Playbook to advance investigation, enrichment, knowledge extraction, or response when necessary. 8. Playbook results are written back to Case, Knowledge, or Enrichment. 9. Comments, Timeline, Harness Agent assistance, and resource context together support subsequent LLM analysis, report generation, and knowledge extraction. --- --- url: 'https://asp.viperrtp.com/asp/quick-start/operations.md' --- # Restart & Operations Run all commands on this page from the `asp-compose/` deployment directory. After starting, recreating, or restarting services, or after applying configuration changes, run a complete deployment check: ```bash ./scripts/doctor.sh ``` ## 1. Check service status View all containers: ```bash docker compose ps ``` `STATUS` should be running, and services with health checks should be healthy. `doctor.sh` waits for every official long-running service to become running/healthy, then checks PostgreSQL, Redis, Django, custom definitions, and the RustFS/S3 bucket. Admins can also open [System Settings > Workers](../../settings/workers/) to view heartbeat, runtime state, and the latest polling result for all five background Workers. This page does not replace container status, business records, or log investigation. ## 2. View logs List available service names: ```bash docker compose config --services ``` Follow a service: ```bash docker compose logs -f ``` View the most recent 100 lines: ```bash docker compose logs --tail=100 ``` For example: ```bash docker compose logs -f asp-frontend docker compose logs --tail=100 asp-web ``` Nginx and backend process logs are also written under `logs/`. ## 3. Choose the correct operation | Scenario | Command | | --- | --- | | Restart processes in existing containers | `docker compose restart` | | Apply `.env` or `compose.override.yaml` changes | `docker compose up -d` | | Reload replaced `certs/asp.crt` and `certs/asp.key` | `docker compose restart asp-frontend` | | Stop all services while preserving containers and data | `docker compose stop` | | Start stopped services | `docker compose up -d` | ### Restart services Restart all services: ```bash docker compose restart ``` Restart Web/API services: ```bash docker compose restart asp-frontend asp-web asp-asgi ``` Restart background workers: ```bash docker compose restart asp-worker-module asp-worker-case-analysis asp-worker-playbook asp-worker-elk-action asp-worker-dashboard-cache ``` ### Apply configuration changes After changing `.env` or `compose.override.yaml`: ```bash docker compose up -d ``` ### Stop and start ```bash docker compose stop docker compose up -d ``` `stop` stops containers. `down` removes containers and the Compose network while preserving named volumes by default. `down -v` also deletes named volumes. ::: warning Do not delete volumes Do not run `docker compose down -v` unless you explicitly intend to delete all persistent PostgreSQL, Redis, RustFS, and custom Python dependency data. ::: ## 4. General troubleshooting 1. Check service status: ```bash docker compose ps ``` 2. Find services that are not running/healthy. 3. Inspect the recent service logs: ```bash docker compose logs --tail=100 ``` 4. Fix the configuration or runtime problem, choose `restart` or `up -d`, then run: ```bash ./scripts/doctor.sh ``` ## Next Steps * [Environment Variables](../environment-variables/) — Review `.env` settings and how to apply them. * [Backup & Restore](../backup-restore/) — Create or restore a stopped full backup. * [Upgrade](../upgrade/) — Download the latest release and update ASP. * [Custom Content Deployment](../../development/custom-deployment/) — Deploy custom content and dependencies. * [Service Management UIs](../../development/management-uis/) — Access Redis Stack UI and RustFS Console. --- --- url: 'https://asp.viperrtp.com/asp/settings/runtime.md' --- # Runtime Runtime stores ASP's Agentic runtime configuration, including prompt language, Webhook Stream retention length, and the Dashboard refresh interval. ## Entry Runtime settings are located in the `Runtime` Tab of System Settings. ![Runtime Settings](img.png) ## Fields | Field | Default | Description | |-------|---------|-------------| | Prompt Language | `en` | Prompt language used for Agentic analysis and knowledge extraction. | | Stream Maxlen | `10000` | Approximate maximum length retained when writing Webhook alerts to Redis Stream. | | Dashboard Refresh Interval | `300` seconds | Interval at which the background worker regenerates Dashboard caches. | ## Prompt Language Prompt Language supports `en` and `zh`. The backend reads corresponding language prompt files based on this value, for example: * `backend\data\prompt\analysis\System_en.md` * `backend\data\prompt\analysis\System_zh.md` * `backend\data\prompt\analysis\KnowledgeKeywords_en.md` * `backend\data\prompt\knowledge_extraction\System_en.md` This configuration affects Case AI investigation, knowledge keyword extraction, and Knowledge Extraction. ## Stream Maxlen Stream Maxlen is used to control the retention length when Splunk / Kibana Webhook alerts are written to Redis Stream. It is an approximate maximum length used to prevent alert Streams from growing without bound. The default value is `10000`. ## Dashboard Refresh Interval Dashboard Refresh Interval controls how often the background worker recalculates the 24h, 7d, and 30d Dashboard caches. Available values are: * 5 minutes (`300` seconds, default) * 15 minutes (`900` seconds) * 30 minutes (`1800` seconds) * 60 minutes (`3600` seconds) A shorter interval keeps Dashboard data more current but runs database aggregations more often. Large deployments can use a longer interval to reduce database load. ## Save and Audit After saving Runtime configuration, the backend refreshes the Runtime cache. The Dashboard Cache Worker reads the new interval on its next loop, and the frontend automatically requests newer snapshots using the interval returned with the cached response. Runtime configuration updates are written to Audit Log. ## Usage Recommendations * Chinese teams can set Prompt Language to `zh` so investigation and knowledge extraction use Chinese prompts. * Stream Maxlen should be adjusted based on alert volume; larger alert volume may require a larger retention length. * Increase Dashboard Refresh Interval if Dashboard aggregation takes a long time or adds too much database load. * After modifying Runtime, observe the effect from new Cases or new Webhook alerts. ## Next Steps * [LLM Provider](../llm-provider/) — Configure model connections required by Runtime. * [Dashboard](../../workspace/dashboard/) — Review cache refresh status and the security operations overview. * [Case](../../workspace/case/) — See how Prompt Language affects AI investigation reports. * [Knowledge](../../workspace/knowledge/) — Review Knowledge Extraction output. --- --- url: 'https://asp.viperrtp.com/asp/development/management-uis.md' --- # Service Management UIs Docker Compose provides Redis Stack UI and RustFS Console. Their ports are configured in `.env`. ::: warning Restrict access These interfaces expose cache, task message, and object storage data. Restrict production access with a firewall or VPN. ::: ## View credentials Run from the `asp-compose/` directory: ```bash grep -E '^(REDIS_PASSWORD|RUSTFS_ACCESS_KEY|RUSTFS_SECRET_KEY)=' .env ``` `.env` contains sensitive credentials. Do not commit or disclose it. ## Redis Stack UI Default URL: ```text http://:8001 ``` If `ASP_REDIS_UI_PORT` was changed in `.env`, use the configured port. Redis Stack UI is the RedisInsight management interface. On first access, add a Redis database with: | Field | Value | | --- | --- | | Host | `127.0.0.1` | | Port | `6379` | | Username | `default` | | Password | Value of `REDIS_PASSWORD` in `.env` | RedisInsight and Redis Server run in the same `redis-stack` container, so use `127.0.0.1:6379`. ## RustFS Console Default URL: ```text http://:9001 ``` If `ASP_RUSTFS_CONSOLE_PORT` was changed in `.env`, use the configured port. | Field | Value | | --- | --- | | Access Key | Value of `RUSTFS_ACCESS_KEY` in `.env` | | Secret Key | Value of `RUSTFS_SECRET_KEY` in `.env` | After login, you can inspect the ASP bucket, objects, and storage status. The bucket name is configured by `RUSTFS_BUCKET`. ## Troubleshooting Check services and ports: ```bash docker compose ps redis-stack rustfs grep -E '^ASP_(MANAGEMENT_BIND|REDIS_UI_PORT|RUSTFS_CONSOLE_PORT)=' .env ``` View logs: ```bash docker compose logs --tail=100 redis-stack docker compose logs --tail=100 rustfs ``` ## Next Steps * [Restart & Operations](../../quick-start/operations/) — Check service status, ports, and logs. * [Custom Content Deployment](../custom-deployment/) — Deploy custom content and dependencies. --- --- url: 'https://asp.viperrtp.com/asp/settings/siem.md' --- # SIEM ASP currently provides Splunk and ELK connection configurations for log queries, Harness Agent investigation, and alert ingestion. ## Entry SIEM settings are located in the `SIEM` tab of System Settings and include Splunk and ELK subtabs. ![SIEM Settings](img.png) ## Splunk Splunk configuration is used to connect to Splunk management interface for SIEM query capabilities. | Field | Description | |-------|-------------| | Host | Splunk server address. | | Port | Splunk management port, default `8089`. | | Username | Login username. | | Password | Login password. | | Scheme | `http` or `https`. | | Verify | Whether to verify certificate. | After configuration, you can use the test function to verify connection. ![Splunk Configuration](img_1.png) ## ELK ELK configuration is used to connect to Elasticsearch for SIEM query capabilities and ELK Index Action. | Field | Description | |-------|-------------| | Host | Elasticsearch server address. | | API Key | Elasticsearch API Key. | | Verify Certs | Whether to verify certificate. | | Request Timeout Seconds | Request timeout time. | | Process Alert From Index Enabled | Whether to enable ELK Index Action polling. | | Action Index | Index name where Kibana actions are written. | | Action Poll Interval Seconds | Polling interval. | | Action Size | Maximum number of actions read per batch. | ![ELK Configuration](img_2.png) ## Connection Test and Audit Both Splunk and ELK support Test. Splunk test connects to Splunk and reads service info; ELK test connects to Elasticsearch and reads cluster info. Saving configuration, testing connection, and revealing keys are all written to Audit Log. Splunk Password and ELK API Key are hidden by default; audit records only record whether a value changed or was revealed, and never store plaintext secrets. After saving SIEM configuration, the backend refreshes the SIEM client cache so later queries use the latest connection information. ## SIEM Query and Index Configuration SIEM connection configuration is only responsible for providing Splunk / ELK backend credentials. Harness Agent SIEM queries also depend on index configuration in `custom\data\siem\*.yaml`. YAML index configuration is used to describe searchable indexes, backend types, field meanings, and default aggregation fields. Unconfigured indexes will not appear in schema list and will not participate in schema-based queries. ## ELK Index Action After enabling `Process Alert From Index Enabled`, the background worker will read Kibana action documents from Elasticsearch according to configured Action Index, Poll Interval, and Action Size. Read actions are converted to the Kibana webhook alert processing flow, then continue through ASP alert ingestion and Case / Alert / Artifact generation. For complete ingestion flow, Kibana action content, and worker execution, see [ELK Index Action](../../development/alert-ingestion/elk-index-action/). ## Usage Recommendations * After saving, first execute Test to confirm network, account, certificate, and key configuration are correct. * Only enable ELK Index Action when ASP needs to pull alerts from a Kibana action index. * Maintain `custom\data\siem\*.yaml` index configuration for Harness Agent queries, so LLMs do not blindly search unknown indexes. * For Webhook ingestion, see [Alert Ingestion](../../development/alert-ingestion/). It is not configured on the SIEM settings page. ## Next Steps * [SIEM YAML](../../development/siem-yaml/) — Describe Splunk / ELK indexes, fields, and default aggregation fields. * [Alert Ingestion](../../development/alert-ingestion/) — Configure Splunk Webhook, Kibana Webhook, or ELK Index Action. * [SIEM Search](../../integrations/skills/asp-siem-search/) — Let Harness Agents query logs based on SIEM YAML. --- --- url: 'https://asp.viperrtp.com/asp/development/siem-yaml.md' --- # SIEM YAML SIEM YAML is used to describe the index structure in Splunk / ELK that can be queried by Harness Agents. > To see how SIEM YAML works with query rules and Module examples, read [SIEM Search](../../integrations/skills/asp-siem-search/), [SIEM Rule](../../integrations/skills/asp-siem-rule/), and [Custom Module Examples](../custom-examples/modules/). ## Configuration Location User-defined SIEM YAML is placed in: ```text custom/data/siem/*.yaml ``` Test YAML in the source repository is located at: ```text backend\custom\data\siem\*.yaml ``` Each YAML file describes a queryable index. The backend currently only loads configuration from `custom\data\siem\*.yaml`. Only indexes written to YAML will appear in `siem_explore_schema`. After modifying YAML, click `Refresh / Validate` in [Custom Console](../custom-console/) → `SIEM YAML` to rescan and review the field table and key fields. The `custom\data\siem\` directory created by `init.sh` does not include test YAML. ## Basic Structure ```yaml name: siem-network-traffic backend: ELK description: Network traffic logs fields: - name: source.ip type: ip description: Source IP is_key_field: true sample_values: ["10.0.0.19"] ``` ## Field Description | Field | Description | | --- | --- | | `name` | Index name. | | `backend` | `ELK` or `Splunk`. | | `description` | Index purpose description. | | `fields[].name` | Field name. | | `fields[].type` | Field type. | | `fields[].description` | Field meaning. | | `fields[].is_key_field` | Whether to use as default aggregation field. | | `fields[].sample_values` | Sample values. | ## Usage Scenarios * `siem_explore_schema` uses it to display available indexes and fields. * `siem_adaptive_query` uses it to determine backend and default aggregation fields. * Skills such as SIEM Search / SIEM Rule / Threat Hunting use it to understand log structure. ## Query Flow ```text SIEM YAML → siem_explore_schema displays indexes and fields → siem_keyword_search / siem_adaptive_query selects backend → Splunk / ELK executes query → Harness Agent summarizes evidence ``` YAML does not store log data, only index and field descriptions. ## Usage Recommendations * Only create YAML for indexes that need to be queried by Harness Agents. * Write clear business meanings for key fields, not just field names. * Mark high-value fields as `is_key_field: true`, such as user, host, IP, domain, process, cloud account, etc. * Use the [SIEM Index YAML](../../integrations/skills/asp-siem-index-yaml/) Skill to help generate YAML. ## Next Steps * [SIEM](../../settings/siem/) — Configure Splunk / ELK connections. * [SIEM Search](../../integrations/skills/asp-siem-search/) — Let Harness Agents query logs based on SIEM YAML. * [SIEM Rule](../../integrations/skills/asp-siem-rule/) — Write detection rules based on index structure. * [Module Development](../module-examples/) — Use query results and alert fields to write alert processing logic. --- --- url: 'https://asp.viperrtp.com/asp/integrations/skills.md' --- # Skills ASP Skills is a capability package for Harness Agents. It exposes ASP Case, Alert, Artifact, SIEM, CMDB, threat intelligence, Playbook, and development helper workflows as reusable skills. The skills runtime uses the `asp` command as the boundary. Agents access the ASP Agent Operations API through `asp-cli` and prefer `--output json` for stable structured results. It does not require the old plugin installation flow or server-protocol environment variables. ## Install Complete [ASP CLI](../cli/) installation, login, and connectivity verification first. Install the skill registry: ```bash npx skills@latest add FunnyWolf/asp-marketplace ``` Install and run [`asp-setup`](asp-setup/) first: ```text /asp-setup ``` ## Skill Catalog | Category | Skills | |----------|--------| | Setup | [`asp-setup`](asp-setup/) | | Records | [`asp-case`](asp-case/), [`asp-alert`](asp-alert/), [`asp-artifact`](asp-artifact/), [`asp-comment`](asp-comment/), [`asp-file`](asp-file/), [`asp-knowledge`](asp-knowledge/), [`asp-enrichment`](asp-enrichment/), [`asp-playbook`](asp-playbook/) | | Integrations | [`asp-siem-search`](asp-siem-search/), [`asp-siem-index-yaml`](asp-siem-index-yaml/), [`asp-siem-rule`](asp-siem-rule/), [`asp-cmdb`](asp-cmdb/), [`asp-threat-intelligence`](asp-threat-intelligence/) | | Authoring | [`asp-module-creator`](asp-module-creator/), [`asp-playbook-creator`](asp-playbook-creator/) | | Investigation Workflows | [`asp-case-investigation`](asp-case-investigation/), [`asp-artifact-investigation`](asp-artifact-investigation/), [`asp-threat-hunting`](asp-threat-hunting/) | ## Usage Rules * Read operations may be invoked by the agent when they match the user's request. * Create, update, upload, comment, enrich, and Playbook execution operations require explicit user authorization. * Automation and investigation workflows should prefer JSON output, such as `asp case list --output json`. * Do not write API keys into skill files, repository files, or prompts. ## Next Steps * [Setup](asp-setup/) — Check CLI login and basic configuration in the agent environment. * [Case](asp-case/) — Let Harness Agents query and update Cases. * [SIEM Search](asp-siem-search/) — Let Harness Agents query Splunk / ELK logs. * [Module Creator](asp-module-creator/) — Help write custom Modules. --- --- url: 'https://asp.viperrtp.com/asp/development/alert-ingestion/splunk-webhook.md' --- # Splunk Webhook Splunk Webhook sends Splunk Alert results directly to ASP and writes them into Redis Stream for Module consumption. ## Endpoint ```text POST /api/webhook/splunk/ ``` Replace the domain with your ASP backend address, for example: ```text https://asp.example.com/api/webhook/splunk/ ``` ## Create an Alert in Splunk Write SPL and save it as an Alert. ![Splunk Alert configuration](img.png) Recommended configuration: * Set Cron Expression / Time Range according to detection frequency, for example run every 5 minutes and search the previous 5 minutes. * Select `For each result` as the trigger so each result is sent as an independent Webhook request. * Set Webhook URL to `https:///api/webhook/splunk/`. * Keep the Alert name consistent with the target Module `STREAM_NAME`. ## Payload requirements ASP's Splunk Webhook reads these fields: | Field | Description | | --- | --- | | `search_name` | Splunk Alert name. It is used as the Redis Stream name. | | `result` | Single alert result written to Stream for Module processing. | | `sid` | Optional Splunk search job ID. | | `app` | Optional Splunk app. | | `owner` | Optional Splunk owner. | | `results_link` | Optional link back to Splunk results. | ## Verification After the Alert triggers, Splunk sends a request to ASP Webhook. After ASP returns success, the result is written to the Redis Stream named by `search_name`. View written messages in Redis or [Custom Console](../../custom-console/) to confirm that a Module can consume them. ![Splunk Stream message](img_1.png) ## Recommendations * Keep SPL output fields stable to avoid frequent Module mapping changes. * Keep Alert name consistent with the Stream name expected by the backend Module. * Output stable correlation fields for the same event type so Correlation UID can be generated later. * For complete examples, see [Custom Module Examples](../../custom-examples/modules/). ## Next Steps * [Module Development](../../module-examples/) — Write a Module that consumes the Splunk Stream. * [Custom Console](../../custom-console/) — Check Stream messages and Module loading status. * [SIEM YAML](../../siem-yaml/) — Maintain index field descriptions for Splunk log queries. --- --- url: 'https://asp.viperrtp.com/asp/settings.md' --- # System Settings System settings are used to manage ASP's user, authentication, LLM, SIEM, Threat Intelligence, Runtime, and frontend Tag preview pages. ## Entry and Permissions System settings entry is located at the frontend `/system`. Only admins can enter this page and use the related settings features. ![System Settings](img.png) ## Settings Items | Setting | Description | |---------|-------------| | User Management | Manage users, roles, authentication types, and account status. | | LLM Providers | Configure model providers for AI investigation, knowledge extraction, and Runtime. | | Threat Intelligence | Configure threat intelligence providers such as AlienVault OTX and OpenCTI. | | SIEM | Configure Splunk and ELK connections. | | LDAP | Configure LDAP login. | | Runtime | Configure Agentic runtime parameters. | | Workers | View background Worker heartbeat, runtime state, and latest polling result. | | Tags | Read-only preview of frontend Tag fields, enums, and colors. | ## Audit LLM, Threat Intelligence, SIEM, and LDAP configurations all support connection tests. Settings updates, connection tests, and key reveals are written to Audit Log; key fields record only whether a value changed or was revealed, not plaintext secrets. ## Next Steps * [User Management](users/) — Manage users, roles, authentication types, and account status. * [LLM Provider](llm-provider/) — Configure models used by AI investigation and knowledge extraction. * [SIEM](siem/) — Configure Splunk or ELK connections. * [Runtime](runtime/) — Configure Agentic runtime parameters. * [Workers](workers/) — View background Worker runtime state. --- --- url: 'https://asp.viperrtp.com/asp/settings/tags.md' --- # Tags Tags is a read-only preview page in System Settings. It centralizes the frontend Tag fields, enum values, and color effects currently used by ASP. ## Entry Tags is located in the `Tags` tab of System Settings and is available only to administrators. ![Tags page](img.png) ## Page Content The Tags page groups common frontend Tags by business area: * Cases: Category, Severity, Confidence, Impact, Priority, Verdict, etc. * Alerts: Severity, Risk Level, Disposition, Action, Product Category, Analytic Type, etc. * Artifacts / Enrichments: Artifact Type, Artifact Role, Enrichment Type, Provider, etc. * Knowledge / Playbooks / Users / Settings: Knowledge Source, Playbook Tags, User Role, LLM Provider Tags, etc. * Custom Console / System UI: SIEM Backend, Audit Action, Inbox Kind, etc. This page does not modify data or save configuration. Its purpose is to let administrators and developers inspect field enums and colors without creating test records. ## Risk Level Color Scale Severity, Confidence, Impact, Priority, and Risk Level currently share the same risk color scale: | Level | Color | | --- | --- | | Critical | red | | High | volcano | | Medium | gold | | Low | cyan | | Info / Informational | blue | | Unknown / Other | default | ## Next Steps * [Case](../../workspace/case/) — See how tags such as Severity, Confidence, Impact, and Priority are used in cases. * [Alert](../../workspace/alert/) — See alert risk levels and source field tags. * [LLM Provider](../llm-provider/) — See how model capability Tags participate in runtime selection. --- --- url: 'https://asp.viperrtp.com/asp/settings/threat-intelligence.md' --- # Threat Intelligence Threat Intelligence settings configure ASP's IOC lookup and threat-context enrichment capabilities. ASP now includes two first-class providers: `AlienVaultOTX` and `OpenCTI`. ## Entry Threat Intelligence settings are located in the `Threat Intelligence` Tab of System Settings. ![Threat Intelligence Settings](img.png) The page is organized by provider: * `AlienVault OTX`: Query public IOC reputation, pulses, and malicious context from AlienVault OTX. * `OpenCTI`: Read STIX / OpenCTI objects, relationships, and report context from a self-hosted OpenCTI platform. ## AlienVault OTX After registering AlienVault OTX, you can get the API Key from the account settings page. ![Get OTX API Key](img_1.png) ### Configuration Items | Field | Description | |-------|-------------| | Enabled | Whether to enable AlienVault OTX. | | API Key | AlienVault OTX API Key. | | Base URL | OTX API address, default `https://otx.alienvault.com/api/v1`. | | Proxy | Optional proxy. | | Timeout Seconds | Query timeout. | Proxy supports addresses starting with `http://`, `https://`, `socks4://`, or `socks5://`. ### Test Behavior Before saving, you can use Test to verify configuration. OTX calls the authenticated `/user/me` endpoint to verify API Key, Base URL, Proxy, and Timeout. ## OpenCTI The OpenCTI Provider connects to a self-hosted OpenCTI platform and converts OpenCTI Indicator, Observable, Vulnerability, Malware, Threat Actor, Campaign, Report, Sighting, and relationship data into ASP threat intelligence enrichment results. After logging in to OpenCTI, you can get the API Key from the account settings page. ![img\_3.png](img_3.png) ### Configuration Items | Field | Description | |-------|-------------| | Enabled | Whether to enable OpenCTI. | | Base URL | OpenCTI platform URL, for example `http://localhost:8080`. | | API Token | OpenCTI API Token. | | SSL Verify | Whether to verify OpenCTI HTTPS certificates. | | Proxy | Optional proxy. | | Timeout Seconds | Query timeout. | ### Test Behavior OpenCTI Test performs a platform health check and tries to read one Indicator or Observable to confirm that the token has read permission. ## Provider Behavior At runtime, ASP queries all enabled real providers: * If OTX is enabled and an API Key exists, ASP queries `AlienVaultOTX`. * If OpenCTI is enabled and URL / API Token exist, ASP queries `OpenCTI`. * Callers can explicitly select a provider, for example `--provider OpenCTI` in the CLI. * If no real provider is enabled, the query returns a configuration error. When multiple providers are enabled, one Artifact can produce multiple threat intelligence results. Each result keeps its own Provider, risk level, reputation score, tags, attack techniques, malware families, report summaries, and raw data. ## OpenCTI Type Mapping ASP's external API continues to use existing Artifact Type names. The OpenCTI Provider maps them internally to STIX / OpenCTI types and preserves `stix_type`, `opencti_entity_types`, `matched_by`, matched objects, and one-hop relationship context in `raw.opencti`. Common mappings include: | ASP Artifact Type | OpenCTI / STIX query type | |-------------------|---------------------------| | `IP Address` | `IPv4-Addr` / `IPv6-Addr` | | `Hostname`, `Endpoint` | `Hostname`; domain-like values also query `Domain-Name` | | `URL String`, `Uniform Resource Locator` | `Url` | | `Hash`, `File`, `File Name`, `File Path`, `Fingerprint` | `StixFile` | | `Email Address`, `Email` | `Email-Addr` / `Email-Message` | | `MAC Address` | `Mac-Addr` | | `Process Name`, `Process`, `Process ID`, `Command Line` | `Process` | | `Registry`, `Registry Path` | `Windows-Registry-Key` | | `HTTP User-Agent` | `User-Agent` | | `User Name`, `User`, `Account` | `User-Account` | | `User Credential ID` | `Credential` | | `Resource UID`, `Resource`, `Device`, `Serial Number` | `Simple-Observable` | | `CVE`, `CWE` | `Vulnerability` | | `Country`, `Geo Location` | `Location` | | `Advisory` | `Report` | Types that cannot be mapped rigorously return unsupported. The provider does not perform broad full-text fallback search, which avoids writing weakly related matches as valid threat intelligence. ## Enrichment Flow `Threat Intelligence Enrichment` Playbook collects Artifacts from Case-associated Alerts, queries threat intelligence for each unique Artifact, and writes results to the Artifact's Enrichment. ![Artifact Threat Intelligence Enrichment](img_2.png) The written Enrichment type is `Threat Intelligence`. OpenCTI results keep both common fields and OpenCTI-specific context: * Common fields: Provider, risk level, reputation score, malicious judgment, tags, attack techniques, malware families, adversaries, industries, and report summaries. * OpenCTI-specific fields: matched objects, STIX / OpenCTI types, one-hop relationships, related Malware, Threat Actor, Campaign, Infrastructure, Vulnerability, Report, Sighting, and more under `raw.opencti`. OpenCTI risk level primarily uses the highest matched `x_opencti_score`: `>=70` is high, `>=40` is medium, and `>0` is low. If no score exists but malicious context is present, the result falls back to medium. ## Usage Recommendations * Use Test first to confirm the Provider key / token and network are available. * Configure Proxy when operating behind a proxy. * Control Timeout to avoid external services blocking investigation flow. * If OTX and OpenCTI are both enabled, compare Enrichment results by Provider. * After executing Threat Intelligence Enrichment from a Case, return to Artifact Enrichments to review results. ## Next Steps * [Enrichment](../../workspace/enrichment/) — See how threat intelligence results are attached to Artifacts. * [Playbook](../../workspace/playbook/) — Run `Threat Intelligence Enrichment` automation tasks. * [Threat Intelligence Skill](../../integrations/skills/asp-threat-intelligence/) — Let Harness Agents query threat intelligence. --- --- url: 'https://asp.viperrtp.com/asp/quick-start/upgrade.md' --- # Upgrade ## 1. Back up before upgrading Create a stopped full backup from the existing `asp-compose/` deployment directory: ```bash ./scripts/backup.sh ``` ## 2. Download and overlay the latest release First installation and upgrades use the same release package. The following commands return to the parent directory, download the latest release, and overlay the official files in the existing `asp-compose/` directory: ```bash cd .. curl -fL -o asp-compose.tar.gz https://github.com/FunnyWolf/agentic-soc-platform/releases/latest/download/asp-compose.tar.gz && tar -xzf asp-compose.tar.gz && rm asp-compose.tar.gz && cd asp-compose && ./scripts/upgrade.sh ``` After extraction, the `upgrade.sh` from the latest release package is executed. ## 3. Upgrade script The upgrade script: 1. Updates the existing `.env` with images from the new package's `.env.example`. 2. Validates the Compose configuration, pulls images, and stops the current application services. 3. Runs target-release upgrade operations and Django database migrations. 4. Starts services and runs `doctor.sh`. Except for updating `ASP_BACKEND_IMAGE` and `ASP_FRONTEND_IMAGE`, the upgrade preserves the other settings in `.env`, along with `compose.override.yaml`, `custom/`, `certs/`, `logs/`, and Docker named volumes. ## 4. Upgrade failures The upgrade script does not roll back automatically. Use the command output to identify the failed stage, then see [Restart & Operations](../operations/) for service status and logs. Use the [backup](../backup-restore/) created before upgrading when a full restore is required. ## Next Steps * [Restart & Operations](../operations/) — Check service status and logs. --- --- url: 'https://asp.viperrtp.com/asp/settings/users.md' --- # User Management User Management is used for admins to maintain ASP users, roles, authentication types, and account status. ## Entry User Management is located in the `User Management` Tab of System Settings. Only admin can enter system settings and manage users. ![User Management List](img.png) ## User List The list displays Username, Avatar, Role, Auth Type, Status, Email, Full Name, Mobile Phone, Last Login, and Date Joined. The list supports quick filtering by Role, Auth Type, and Status, and also supports advanced filtering by Username, Email, First Name, Last Name, Mobile Phone, Date Joined, Last Login, and other fields. ## User Roles | Role | Source | Description | |------|--------|-------------| | admin | Django superuser | Can enter system settings and manage configurations. | | user | user group or default role | Can create, update, and delete business resources. | | viewer | viewer group | Read-only user, can only view resources. | The current interface can only assign `user` or `viewer` when creating and editing users; `admin` comes from Django superuser and is not created through the user management interface. ## Admin Account ASP's admin is a Django superuser and must be created and maintained from the backend command line. Create admin: ```bash docker compose exec asp-web python manage.py createsuperuser ``` Created admin uses `Platform` method on login page to log in. If you forget the admin username, you can list existing superusers: ```bash docker compose exec asp-web python manage.py shell -c "from apps.accounts.models import User; print('\n'.join(User.objects.filter(is_superuser=True).values_list('username', flat=True)))" ``` If you need to reset admin password: ```bash docker compose exec asp-web python manage.py changepassword ``` ## Authentication Types | Type | Description | |------|-------------| | Local Password | Log in using platform local password. | | LDAP | Log in using LDAP password, after LDAP is configured and enabled. | When creating `Local Password` users, the system generates an initial password and displays copyable account information. LDAP users do not generate local passwords and use LDAP passwords when logging in. ![Create User](img_1.png) ## Common Operations * Create `user` or `viewer` users. * Edit email, name, mobile phone, and role. * Enable or disable non-admin users. * Reset passwords for `Local Password` users. * Modify user avatar. ## Next Steps * [First Login](../../quick-start/first-login/) — Learn about Platform / LDAP login methods. * [LDAP](../ldap/) — Configure enterprise identity sources and LDAP user login. * [Personal Center](../../workspace/personal-center/) — Let users maintain profiles, notification preferences, and API Keys. --- --- url: 'https://asp.viperrtp.com/asp/overview.md' --- # What is Agentic SOC Platform Agentic SOC Platform (ASP) is an open-source security operations platform that provides security teams with a complete workflow from alert ingestion, automatic aggregation, AI analysis to response disposition. ASP places alerts, cases, entities, enrichment results, knowledge, and automation playbooks in the same workspace. Analysts no longer need to repeatedly switch tools around individual alerts, but instead review evidence, confirm AI reports, and make disposition decisions around Case. ## Why Not Another SIEM/SOAR ASP is not an AI chat entry point added on top of a traditional alert list, nor does it force users to express automation only through drag-and-drop flows or static configuration files. It keeps the workspace experience and security data model expected from mature SOAR platforms, while moving highly customized alert handling, investigation flows, and response actions into Python code. ASP does not rebuild a separate, isolated agent system. Instead, it brings LLM analysis, Playbook automation, and Harness Agent capabilities into the same SOC workflow. This means the analyst's work will change from "processing alerts one by one" to "reviewing AI analysis results and making final judgments." The platform is responsible for aggregating information, completing context, and advancing repetitive processes; humans are responsible for judging risk, confirming impact, and deciding response actions. ## Unique Advantages | Advantage | Description | |-----------|-------------| | Workspace and data model | ASP provides UI/UX for daily SOC work and organizes workflows around Case, Alert, Artifact, Enrichment, Playbook, and Knowledge resources, staying close to mature SOAR best practices. | | Code-first flexibility | Module and Playbook are written in Python and are not limited by drag-and-drop orchestrators or static configuration files. Users can fully express field normalization, correlation, context enrichment, external system integration, and response logic. | | Better suited for agent-assisted development | Code-first customization raises the ceiling and would traditionally raise the development barrier. ASP uses Skills to help Harness Agents generate, modify, and validate Module / Playbook code, turning flexibility into lower implementation cost. | | Harness Agent first | ASP exposes platform capabilities through CLI and Skills, prioritizing reuse of the user's existing Harness Agents instead of building an isolated agent system. Harness Agents can participate in SOC operations around Case, Artifact, SIEM logs, threat intelligence, Module, and Playbook. | | Open source and private deployment | ASP uses the MIT license and supports single-node private deployment with Docker Compose, so security data can stay inside the internal network. Backend, frontend, extension scripts, and deployment flows remain clear for audit and customization. | ## From Alerts to Knowledge | Stage | What ASP does | |-------|---------------| | Alert ingestion | Receives alerts from SIEM / Webhook / ELK Index Action and writes them to Redis Stream. | | Module processing | Uses Python Module to extract IOCs, map fields, correlate signals, and generate Case / Alert / Artifact. | | Case investigation | Lets analysts review evidence, discuss leads, inspect Timeline, and confirm risk judgments around Case. | | AI analysis and enrichment | LLM generates investigation reports, while Playbook adds threat intelligence, CMDB context, knowledge extraction, and other automation results. | | Harness Agent collaboration | Uses CLI and Skills to let Harness Agents query SIEM, operate resources, and write Module / Playbook code. | | Knowledge capture | Extracts reusable experience from confirmed Cases and turns it into organization-level Knowledge. | | Governance and collaboration | Uses users/API Keys, LDAP, Audit Log, and Inbox to support collaboration, audit, and access control. | ASP's core data model (Case, Alert, Artifact, Enrichment, Playbook, Knowledge) references mainstream SOAR / Agentic SOC platform workflows, ensuring the process is intuitive and universal for security teams. ## Who Should Use * Security operations teams that want to converge SIEM alerts into actionable Cases. * Teams that want to use LLM in investigation, but also need audit, traceability, and manual decision-making. * Teams that want to unify threat intelligence, assets, identity, history, and other context onto security resources. * Teams that want to use Python for low-cost customization of alert processing logic and automation playbooks. * Teams that want to let Harness Agents enter the security operations process. ## Get Started * [Quick Deployment](../quick-start/deployment/) — Deploy ASP and start the basic workflow in the documentation. * [Skills](../integrations/skills/) — Let Harness Agents use ASP capabilities through asp-cli. * [Case Workspace](../workspace/case/) — Learn how analysts handle security events around Case. * [Module Development](../development/module-examples/) — Learn how to use Module to stream process alerts. * [Playbook Development](../development/playbook/) — Learn how to orchestrate LLM analysis and SOAR automation together. --- --- url: 'https://asp.viperrtp.com/asp/settings/workers.md' --- # Workers The Workers page shows the current runtime state of ASP's five background Workers. It helps identify cases where a container is still running but its Worker polling loop has failed. ## Entry and Permissions Workers is located in the `Workers` Tab of System Settings and is available only to admins. The page loads immediately when opened and refreshes automatically every 10 seconds. It has no manual refresh button; failed requests are retried during the next refresh cycle. ## Worker Types | Worker | Django Command | Purpose | | --- | --- | --- | | Agentic Module Worker | `run_agentic_module_worker` | Consume Module Redis Streams and execute custom Modules. | | Case Analysis Worker | `run_agentic_case_analysis_worker` | Execute pending Case Analysis Jobs. | | Playbook Worker | `run_agentic_playbook_worker` | Execute pending Playbook Runs. | | ELK Action Worker | `run_elk_action_worker` | Poll the ELK Action Index and write to Redis Streams. | | Dashboard Cache Worker | `run_dashboard_cache_worker` | Generate Dashboard caches periodically. | ## State | State | Description | | --- | --- | | `Starting` | The Worker started but has not completed its first polling iteration. | | `Idle` | The latest polling iteration succeeded and no iteration is currently running. | | `Running` | The Worker is currently executing an iteration. | | `Degraded` | The latest Worker polling iteration encountered an infrastructure error. | | `Down` | The Worker never reported, exited normally, or its heartbeat expired. | The reason field distinguishes the causes of `Down`: | Reason | Description | | --- | --- | | `never_reported` | The Worker has never written health state. | | `heartbeat_expired` | The latest heartbeat is more than 30 seconds old. | | `graceful` | The Worker exited normally. | An individual Playbook, Case Analysis, or Module business failure does not mark its Worker as `Degraded`. Inspect the corresponding business record and logs for those failures. ## Page Fields * Current State and reason. * Current or latest task summary. * Current or latest iteration duration. * Latest heartbeat time. * Latest successful polling time. * Latest time that work was processed. * Latest polling failure time. * A safe error summary without raw exceptions or secrets. The page does not show backlogs, historical trends, log content, or cumulative counters, and provides no Restart, Stop, or Run Now actions. ## Manual Execution Compose already runs one long-lived process for each Worker type. To execute one iteration while troubleshooting, use `--once`: ```bash docker compose exec asp-web python manage.py run_dashboard_cache_worker --once ``` Replace the command with another command from the table as needed. `--once` does not report Worker Health. Do not manually start a second long-lived Worker without `--once`. The current Compose deployment supports only one instance of each type, and multiple instances overwrite each other's health state. ## Troubleshooting ### Monitoring unavailable The Workers API reads health state from Redis. When Redis is unavailable, the page displays: ```text Worker health monitoring is unavailable. ``` Check Redis and ASP service status: ```bash docker compose ps ./scripts/doctor.sh ``` ### Degraded or Down Inspect the corresponding Compose service logs, for example: ```bash docker compose logs --tail=100 asp-worker-playbook docker compose logs -f asp-worker-dashboard-cache ``` After fixing the configuration or runtime problem, restart the affected service. The next automatic page refresh shows the new state after polling resumes. ## Boundaries * The heartbeat thread reports every 10 seconds. * A heartbeat older than 30 seconds is calculated as `Down`. * The platform does not automatically detect `Stalled`; long tasks remain `Running` and show their duration. * Worker Health represents process and polling-loop state. It does not replace business results, container status, or logs. ## Next Steps * [Restart & Operations](../../quick-start/operations/) — Check services, inspect logs, and restart Workers. * [Runtime](../runtime/) — Configure runtime parameters such as the Dashboard Worker refresh interval. * [Custom Console](../../development/custom-console/) — Inspect Module and Playbook definitions.