secops-agent-triage: AI Agentic Security Triage & MCP Workflow

secops-agent-triage is a portfolio Model Context Protocol (MCP) and CLI security-triage implementation for repeatable Tier 1 SOC alert analysis. It ingests raw security logs (Windows Event Logs, AWS CloudTrail, Syslog), extracts IOC entities, orchestrates configurable threat-intelligence adapters (VirusTotal, AbuseIPDB, AlienVault OTX), constructs inspectable decision traces, and outputs structured JSON assessments with legacy NIST SP 800-61 Rev. 2-style phases and MITRE ATT&CK technique mappings. NIST SP 800-61 Rev. 3 is the current guidance; deterministic mock mode is provided for offline verification.

⚡ 60-Second Quick Review Guide

Related MCP server: Splunk MCP for SOC Operations

🏗️ Architecture & Data Flow

graph TD
    Alert[Raw Security Alert: EVTX / CloudTrail / Syslog] --> Ingest[Ingestion Facade & Parser]
    Ingest --> Extract[Entity Extraction: IPs, Hashes, Domains, Accounts]
    
    subgraph Threat_Intel_Orchestration [Async Threat Intel Tools]
        VT[VirusTotal Tool]
        Abuse[AbuseIPDB Tool]
        OTX[AlienVault OTX Tool]
    end

    Extract --> VT
    Extract --> Abuse
    Extract --> OTX
    
    VT --> Engine[Verifiable Reasoning Engine]
    Abuse --> Engine
    OTX --> Engine
    
    Engine --> Trace[Step-by-Step Reasoning Trace Construction]
    Trace --> Mapper[NIST SP 800-61 & MITRE ATT&CK Mapper]
    Mapper --> Output[Structured TriageAssessment JSON]
    
    Output --> CLI[CLI Interface: secops-triage]
    Output --> MCP[MCP Server: stdio transport]

🚀 Installation & Setup

# Clone repository and navigate to folder
cd secops-agent-triage

# Install package in editable mode with test dependencies
pip install -e ".[test]"

💻 CLI Usage

The CLI (secops-triage or python -m secops_agent_triage.cli) accepts raw logs via string or file, auto-detects formats, and outputs structured TriageAssessment JSON.

1. Default Sample Run (Windows EventID 4688 Execution)

secops-triage --mock

2. File Ingestion

secops-triage --file sample_cloudtrail.json --format cloudtrail --mock --output-json assessment.json

3. Inline Raw Alert

secops-triage --raw "<165>1 2026-08-13T11:00:00Z edge-fw sshd 1234 - - Failed password for root from 192.0.2.1 port 22" --format syslog --mock

🤖 Model Context Protocol (MCP) Server Setup

secops-agent-triage exposes MCP tools for integration into AI agent workbenches (e.g. Claude Desktop, VS Code Antigravity IDE):

MCP Tools Provided:

• triage_security_alert: Complete alert ingestion, threat intel lookup, reasoning trace, and NIST/MITRE assessment.

• lookup_ip_reputation: Queries VirusTotal, AbuseIPDB, and AlienVault OTX for IP reputation.

• lookup_hash_reputation: Queries VirusTotal and AlienVault OTX for file hash reputation.

• lookup_domain_reputation: Queries VirusTotal and AlienVault OTX for domain reputation.

MCP Configuration (claude_desktop_config.json or mcp_settings.json):

{
  "mcpServers": {
    "secops-agent-triage": {
      "command": "python",
      "args": ["-m", "secops_agent_triage.mcp_server"],
      "env": {}
    }
  }
}

Mock mode is the safe default and needs no credentials. For live lookups, set VT_API_KEY, ABUSEIPDB_API_KEY, and/or OTX_API_KEY in the MCP client environment; never commit API keys to the configuration file.

🧪 Testing & Coverage

Run the unit and integration test suite:

pytest --cov=secops_agent_triage --cov-report=term-missing --cov-fail-under=90

Test Coverage Results:

TOTAL: 773 statements, 93.81% coverage
All 60 test cases PASSED.