apt-threat-hunt

name	apt-threat-hunt
description	Use when hunting for advanced persistent threat (APT) actor activity, tools, and infrastructure.
category	hunting
version	1.0.0
type	Skill
title	Skill: APT Threat Hunt
generated	{"by":"process:google-labs-jules","at":"2025-12-21T03:04:42.000Z"}

Runbook: APT Threat Hunt

Objective

Proactively hunt for Tactics, Techniques, and Procedures (TTPs) and Indicators of Compromise (IOCs) associated with a specific Advanced Persistent Threat (APT) group based on threat intelligence.

Scope

Focuses on SIEM log analysis and GTI correlation for specific TTPs and IOCs related to the target APT group. Excludes deep endpoint forensics unless findings warrant escalation.

Inputs

• ${THREAT_ACTOR_ID}: GTI Collection ID or name of the target APT group.
• ${HUNT_TIMEFRAME_HOURS}: Lookback period in hours (e.g., 168 for 7 days).
• (Optional) ${TARGET_SCOPE_QUERY}: UDM query fragment to narrow scope (e.g., specific host group, network segment).
• (Optional) ${HUNT_HYPOTHESIS}: Specific hypothesis guiding the hunt (e.g., "Searching for FIN11 exploiting MFT servers").
• (Optional) ${RELEVANT_GTI_REPORTS}: Comma-separated list of relevant GTI report IDs.
• (Optional) ${HUNT_CASE_ID}: SOAR case ID for tracking.

Tools

• gti-mcp: get_collection_report, get_entities_related_to_a_collection, get_collection_timeline_events, get_collection_mitre_tree, search_threat_actors (if starting with name)
• secops-mcp: search_security_events, lookup_entity, get_ioc_matches
• secops-soar: post_case_comment, list_cases
• write_report
• Common Steps: skills/common/find-relevant-soar-case/SKILL.md, skills/common/generate-report-file/SKILL.md

Workflow Steps & Diagram

1. Identify Actor & Gather Intelligence:
   • If starting with a name, use gti-mcp_search_threat_actors to find the ${THREAT_ACTOR_ID}.
   • Retrieve details about ${THREAT_ACTOR_ID} using gti-mcp_get_collection_report.
   • Analyze known TTPs using gti-mcp_get_collection_mitre_tree.
   • Analyze timelines using gti-mcp_get_collection_timeline_events. (Note: This may return no results for some actors).
   • Gather associated IOCs (IPs, domains, hashes, URLs) using gti-mcp_get_entities_related_to_a_collection for relevant relationship types (e.g., files, domains, urls). (Note: Not all relationship types may yield results). Let this be GTI_IOC_LIST.
2. Check SIEM IOC Matches: Use secops-mcp_get_ioc_matches covering ${HUNT_TIMEFRAME_HOURS} to see if any IOCs related to the actor are already flagged by integrated feeds. Correlate with GTI_IOC_LIST.
3. IOC-Based Search (SIEM):
   • For each relevant IOC type (e.g., IPs, domains, hashes, URLs) derived from GTI_IOC_LIST:
     • Construct appropriate UDM queries for secops-mcp_search_security_events.
     • Execute the search over ${HUNT_TIMEFRAME_HOURS}.
     • Analyze results for any hits. Let findings be IOC_SEARCH_FINDINGS. Document negative results as well.
4. TTP-Based Search (SIEM):
   • Develop Queries: Based on the MITRE techniques identified in Step 1 and the ${HUNT_HYPOTHESIS} (if provided), formulate specific secops-mcp_search_security_events UDM queries targeting indicators for the most relevant TTPs.
     • Suggestion: Use gti-mcp_get_threat_intel for specific TTP IDs identified in Step 1 to get detection ideas.
     • Combine technique-specific queries with ${TARGET_SCOPE_QUERY} if provided.
   • Execute Queries: Run the developed TTP queries over ${HUNT_TIMEFRAME_HOURS}. Iterate on queries if initial results are negative but the hypothesis remains strong.
   • Analyze results for anomalies or suspicious patterns matching the TTPs. Let findings be . Document negative results as well.

ADK Graph-Based Workflow Diagram

graph TD
    START(["START"]) --> extract_apt_payload_node["1. extract_apt_payload_node<br/><i>(Extract Threat Actor Scope)</i>"]
    extract_apt_payload_node --> fetch_apt_threat_intel_node["2. fetch_apt_threat_intel_node<br/><i>(Fetch GTI Actor IOCs & TTPs)</i>"]
    fetch_apt_threat_intel_node --> search_apt_siem_events_node["3. search_apt_siem_events_node<br/><i>(SIEM Event & IOC Match Search)</i>"]
    search_apt_siem_events_node --> apt_hunt_router{"4. apt_hunt_router<br/><i>(Event.actions.route)</i>"}

    apt_hunt_router -- "CONFIRMED_APT_CAMPAIGN" --> handle_confirmed_apt_campaign_branch["5a. handle_confirmed_apt_campaign_branch<br/><i>(Trigger Emergency Containment)</i>"]
    apt_hunt_router -- "NO_APT_ACTIVITY" --> handle_no_apt_activity_branch["5b. handle_no_apt_activity_branch<br/><i>(Document Clean Hunt)</i>"]

    handle_confirmed_apt_campaign_branch --> document_apt_report_node["6. document_apt_report_node<br/><i>(SOAR Comment & Report Summary)</i>"]
    handle_no_apt_activity_branch --> document_apt_report_node

Sequence Diagram

sequenceDiagram
    participant Analyst/Hunter
    participant AutomatedAgent as Automated Agent (MCP Client)
    participant GTI as gti-mcp
    participant SIEM as secops-mcp
    participant SOAR as secops-soar
    participant FindCase as skills/common/find-relevant-soar-case/SKILL.md
    participant GenerateReport as skills/common/generate-report-file/SKILL.md

    Analyst/Hunter->>AutomatedAgent: Start APT Hunt\nInput: THREAT_ACTOR_ID, HUNT_TIMEFRAME_HOURS, ...

    %% Step 1: Intelligence Gathering
    opt Actor Name Provided instead of ID
        AutomatedAgent->>GTI: search_threat_actors(query=ActorName)
        GTI-->>AutomatedAgent: THREAT_ACTOR_ID
    end
    AutomatedAgent->>GTI: get_collection_report(id=THREAT_ACTOR_ID)
    GTI-->>AutomatedAgent: Actor Details
    AutomatedAgent->>GTI: get_collection_mitre_tree(id=THREAT_ACTOR_ID)
    GTI-->>AutomatedAgent: Actor TTPs
    AutomatedAgent->>GTI: get_collection_timeline_events(id=THREAT_ACTOR_ID)
    GTI-->>AutomatedAgent: Timeline (Optional - May be empty)
    Note over AutomatedAgent: Gather IOCs for each relevant type (files, domains, urls...)
    loop For each IOC Relationship R
        AutomatedAgent->>GTI: get_entities_related_to_a_collection(id=THREAT_ACTOR_ID, relationship_name=R)
        GTI-->>AutomatedAgent: Associated IOCs for type R (GTI_IOC_LIST)
    end

    %% Step 2: Check SIEM IOC Matches
    AutomatedAgent->>SIEM: get_ioc_matches(hours_back=HUNT_TIMEFRAME_HOURS)
    SIEM-->>AutomatedAgent: SIEM IOC Match Results
    Note over AutomatedAgent: Correlate matches with GTI_IOC_LIST

    %% Step 3: IOC-Based Search (SIEM)
    loop For each IOC Type/Value Ii in GTI_IOC_LIST
        Note over AutomatedAgent: Construct UDM query Qi for IOC Ii
        AutomatedAgent->>SIEM: search_security_events(text=Qi, hours_back=HUNT_TIMEFRAME_HOURS)
        SIEM-->>AutomatedAgent: IOC Search Results for Ii (IOC_SEARCH_FINDINGS)
    end

    %% Step 4: TTP-Based Search (SIEM)
    Note over AutomatedAgent: Develop TTP-based UDM queries Qt based on MITRE techniques & Hypothesis (Use get_threat_intel if needed)
    loop For each TTP Query Qt
        AutomatedAgent->>SIEM: search_security_events(text=Qt, hours_back=HUNT_TIMEFRAME_HOURS)
        SIEM-->>AutomatedAgent: TTP Search Results for Qt (TTP_SEARCH_FINDINGS)
    end

    %% Step 5: Enrich Findings
    opt Hits Found (IOC or TTP)
        Note over AutomatedAgent: Identify key Found_IOCs and Found_Entities (E1, E2...)
        loop For each Found Item Fi (IOC or Entity)
            AutomatedAgent->>SIEM: lookup_entity(entity_value=Fi)
            SIEM-->>AutomatedAgent: SIEM Summary for Fi
            AutomatedAgent->>GTI: get_..._report(ioc=Fi) %% Use appropriate GTI tool
            GTI-->>AutomatedAgent: GTI Enrichment for Fi (ENRICHMENT_RESULTS)
        end
    end

    %% Step 6: Check Related SOAR Cases
    opt Hits Found
        Note over AutomatedAgent: Prepare list of Found_IOCs + Found_Entities
        AutomatedAgent->>FindCase: Execute(Input: SEARCH_TERMS=[Found List], CASE_STATUS_FILTER="Opened")
        FindCase-->>AutomatedAgent: Results: RELATED_SOAR_CASES
    end

    %% Step 7: Document in SOAR (Optional)
    opt HUNT_CASE_ID provided
        Note over AutomatedAgent: Synthesize findings including RELATED_SOAR_CASES
        AutomatedAgent->>SOAR: post_case_comment(case_id=HUNT_CASE_ID, comment="APT Hunt Summary...")
        SOAR-->>AutomatedAgent: Comment Confirmation
    end

    %% Step 8: Generate Report
    Note over AutomatedAgent: Synthesize all findings (positive & negative, incl. related cases) into Markdown report content
    AutomatedAgent->>GenerateReport: Execute(Input: REPORT_CONTENT, REPORT_TYPE="apt_hunt_report", REPORT_NAME_SUFFIX=THREAT_ACTOR_ID)
    GenerateReport-->>AutomatedAgent: Results: REPORT_FILE_PATH, WRITE_STATUS

    %% Step 9: Escalation/Conclusion
    alt Confirmed Threat Found via Hunt
        Note over AutomatedAgent: Escalate findings (Create/Update Incident Case)
        AutomatedAgent->>Analyst/Hunter: attempt_completion(result="APT Hunt complete. Threat found and escalated. Report generated at REPORT_FILE_PATH.")
    else No Threat Found
        AutomatedAgent->>Analyst/Hunter: attempt_completion(result="APT Hunt complete. No significant findings. Report generated at REPORT_FILE_PATH.")
    end

Completion Criteria

Intelligence gathered, IOCs and TTPs searched in SIEM, findings analyzed and enriched (if applicable), results documented in SOAR (optional), and a final report generated. Appropriate escalation or conclusion based on findings.

Rubrics

The following rubric is used to evaluate the execution of this Threat Hunt/Analysis runbook by an LLM agent.

Grading Scale (0-100 Points)

Criteria	Points	Description
Scope & Query	25	Defined a clear scope and executed effective queries (UDM, search).
Data Analysis	30	Analyzed results to identify patterns, anomalies, or malicious behavior.
Findings	15	Accurately identified and filtered findings (True Positives vs. False Positives).
Documentation	15	Documented the hunt methodology and results clearly.
Operational Artifacts	15	Produced required artifacts: Sequence diagram, execution metadata (date/cost), and summary.

Evaluation Criteria Details

1. Scope & Query (25 Points)

• 10 pts: Correctly defined the time range and entities/indicators for the hunt.
• 15 pts: Constructed and executed valid, efficient queries to retrieve relevant data.

2. Data Analysis (30 Points)

• 15 pts: Effectively analyzed the returned data for the hypothesized threat.
• 15 pts: Correlated events or indicators to strengthen the analysis.

3. Findings (15 Points)

• 15 pts: Correctly classified the findings and provided evidence for the conclusion.

4. Documentation (15 Points)

• 15 pts: Recorded the hunt process, queries used, and findings in the system of record.

5. Operational Artifacts (15 Points)

• 5 pts: Sequence Diagram: Produced a Mermaid sequence diagram visualizing the steps taken.
• 5 pts: Execution Metadata: Recorded the date, duration, and estimated token cost.
• 5 pts: Summary Report: Generated a concise summary of the actions and outcomes.