manifest.yaml

# Microsoft Security Copilot agent manifest (OFFICIAL SCHEMA, v0.8 PREVIEW)
# ===========================================================================
#
# Reference: https://learn.microsoft.com/en-us/copilot/security/developer/agent-manifest
#
# !!! STATUS: REFERENCE / NON-RECOMMENDED IMPLEMENTATION !!!
#
# This manifest is kept in the repository as a working sample of the
# official Microsoft Security Copilot agent manifest schema (Descriptor
# + SkillGroups + AgentDefinitions). It uploads cleanly via
# `Build -> My agents -> Upload YAML` and the resulting agents can be
# published and run end-to-end.
#
# However, in the current Security Copilot standalone portal (April 2026)
# the runtime behaviour falls short of what an MCP-aware client offers:
#
#   * The planner LLM tends to call only ONE of the declared ChildSkills
#     per agent invocation and treat its output as the final answer.
#     Recursive / multi-tool reasoning (call AbuseIPDB + OTX + ThreatFox
#     and reconcile the verdicts) does not happen reliably.
#   * Agent `Instructions` are static. There is no way to inject extra
#     guidance at trigger time; the user prompt has to carry every hint
#     ("call all three tools and reconcile the results").
#   * `ChildSkills` is a "may-call" list, not a "must-call" list. The
#     planner is free to ignore most of them.
#
# RECOMMENDED ALTERNATIVE for SOC operators:
#
#   Use the same Container App as an MCP server from a modern agentic
#   client (VS Code Copilot Chat in Agent Mode, Claude Desktop, Cline,
#   etc.). See `mcp-client-config/vscode.mcp.json` and
#   `mcp-client-config/claude-desktop.json`. Those clients run on
#   Claude Sonnet / GPT-4-class models with proper multi-tool planning
#   and recursive reasoning, and produce far better triage output from
#   the same set of SOC Pack tools.
#
# This file is therefore retained as:
#   1. A reference for anyone building an MS-schema agent against the
#      SOC Pack (operationId naming, RequiredSkillsets wiring,
#      ChildSkills resolution, AgentDefinitions structure).
#   2. A regression target for upcoming Security Copilot platform
#      improvements (model upgrade, recursive planning, dynamic
#      instructions).
#
# UPLOAD WORKFLOW (still works, just yields modest results):
#   1. Edit `<YOUR-CONTAINER-APP-FQDN>` and the X-API-Key value below.
#   2. Security Copilot -> Build -> My agents -> Upload YAML -> select
#      this file.
#   3. Provide the API key when prompted (the value of
#      MCP_SOC_PACK_API_KEY).
#   4. When invoking the agent, put the entire orchestration prompt
#      ("call X, Y, Z and reconcile") into the `indicators` /
#      `cve_ids` / `file_hash` Input field, not just the raw IOC.

Descriptor:
  Name: CopilotMcpSocPack.Agents-v08preview
  DisplayName: Copilot MCP SOC Pack — Agents (v0.8 preview)
  Description: >-
    Reference triage agents (IOC enrichment, vulnerability triage,
    hash triage) that orchestrate the SOC Pack API tools provided by
    the companion `copilot_mcp_soc_pack` Custom plugin.

SkillGroups:
  # ------------------------------------------------------------------
  # AGENT skill group: defines reasoning entry points that orchestrate
  # API tools coming from the companion Custom plugin (Descriptor.Name:
  # copilot_mcp_soc_pack). Each AGENT skill becomes a callable agent
  # the user can invoke from the Security Copilot home prompt.
  #
  # NOTE: The API SkillGroup (Format: API) is intentionally NOT defined
  # here. Microsoft Security Copilot does not allow an AGENT skill to
  # bind ChildSkills from an API SkillGroup that lives in the same
  # skillset; ChildSkills must reference skills from skillsets listed
  # under the AgentDefinition's `RequiredSkillsets`. Symptom of the
  # forbidden setup: the Agent Builder UI shows the API tools by name
  # but Publish fails with "Invalid references: ...".
  #
  # Operators must therefore register both:
  # 1. The Custom plugin (sc-plugin/manifest.yaml, Descriptor.Name:
  #    copilot_mcp_soc_pack) which advertises the API operationIds.
  # 2. This Agents skillset, uploaded via Build -> My agents ->
  #    Upload YAML.
  # ------------------------------------------------------------------
  - Format: AGENT
    Skills:
      - Name: IocEnrichmentAgent
        DisplayName: IOC Enrichment Agent (SOC Pack)
        Description: >-
          Enriches a mixed list of IOCs (IPs, domains, URLs, file
          hashes) using abuse.ch, AbuseIPDB, OTX and crt.sh. Returns
          a single consolidated reputation table.
        Interfaces:
          - Agent
        Inputs:
          - Name: indicators
            Description: Optional. A newline- or comma-separated list of IPv4 / domain / URL / file-hash indicators.
            Required: false
        Settings:
          Model: gpt-4.1
          Instructions: |
            <|im_start|>system
            You are an IOC enrichment agent. The user gives you a mixed
            list of indicators. For every indicator detect its type:
            - IPv4 -> call abuseipdb_check, otx_lookup_ipv4, threatfox_search.
            - Domain -> call threatfox_search and urlhaus_lookup_host.
              Call crtsh_subdomains ONLY when the user explicitly asks
              for attack-surface or subdomain information.
            - URL -> call urlhaus_lookup_url and threatfox_search.
            - File hash -> call malwarebazaar_lookup, otx_lookup_file
              and the matching circl_hashlookup_<algo>.

            Output ONE Markdown table:
            `Indicator | Type | Verdict | Evidence | First/Last seen | Source(s)`.

            Table formatting rules are strict:
            - Always include the separator line:
              `|---|---|---|---|---|---|`
            - Emit at least one data row.
            - Emit exactly one row per input indicator.
            - Never return a header-only table.

            Verdict values: malicious / suspicious / benign / unknown.
            Use `unknown` only when EVERY tool returned no data; do
            not guess. Cite the source endpoints in the Source column.

            If the structured `indicators` input is empty, infer
            indicators from the latest user message in chat context.
            If still none are available, ask the user to provide one or
            more indicators and stop.

            If a skill returns HTTP 503 or 429, surface it inline as
            `<skill_name>: 503 missing key` rather than dropping the
            indicator silently.

            If enrichment data is missing for an indicator, still emit a
            row with:
            - Verdict = `unknown`
            - Evidence = `no data returned by configured tools`
            - Source(s) = `abuseipdb_check|otx_lookup_ipv4|threatfox_search|...`
            <|im_end|>
            <|im_start|>user
            {{indicators}}
            <|im_end|>
        ChildSkills:
          - abuseipdb_check
          - otx_lookup_ipv4
          - threatfox_search
          - urlhaus_lookup_url
          - urlhaus_lookup_host
          - malwarebazaar_lookup
          - otx_lookup_file
          - circl_hashlookup_md5
          - circl_hashlookup_sha1
          - circl_hashlookup_sha256
          - crtsh_subdomains

      - Name: VulnerabilityTriageAgent
        DisplayName: Vulnerability Triage Agent (SOC Pack)
        Description: >-
          Ranks one or more CVE IDs by exploitation risk using CISA
          KEV, FIRST EPSS and MITRE ATT&CK mappings, then surfaces
          MITRE D3FEND defensive techniques per affected ATT&CK id.
        Interfaces:
          - Agent
        Inputs:
          - Name: cve_ids
            Description: Optional. One or more CVE identifiers (comma- or newline-separated, e.g. CVE-2024-3400).
            Required: false
        Settings:
          Model: gpt-4.1
          Instructions: |
            <|im_start|>system
            If the structured `cve_ids` input is empty, infer CVE IDs
            from the latest user message in chat context. If no CVE is
            found, ask the user to provide one or more CVE IDs and stop.

            For each CVE supplied:
            1. Call kev_lookup. Capture dateAdded,
               knownRansomwareCampaignUse, dueDate.
            2. Call epss_score for the same CVE.
            3. If a vendor / product is known from the KEV entry,
               call attack_search to find up to 3 plausible MITRE
               ATT&CK technique ids.
            4. For each ATT&CK technique id, call
               d3fend_defenses_for_attack.

            Assign a priority:
            - P1: KEV-listed AND EPSS >= 0.5
            - P2: KEV-listed OR  EPSS >= 0.5
            - P3: neither

            Output:
            ## Risk table
              CVE | Product | KEV? | EPSS | Priority | Due date
            ## ATT&CK mapping
              CVE | Technique id | Technique name
            ## Recommended D3FEND defenses
              one subsection per defensive tactic, bullet list of
              up to 5 deduplicated defense labels

            Cite sources inline (per CISA KEV / per FIRST EPSS /
            per MITRE D3FEND mappings). Never invent data the tools
            did not return.
            <|im_end|>
            <|im_start|>user
            {{cve_ids}}
            <|im_end|>
        ChildSkills:
          - kev_lookup
          - kev_search
          - epss_score
          - attack_technique
          - attack_search
          - d3fend_defenses_for_attack

      - Name: HashTriageAgent
        DisplayName: Hash Triage Agent (SOC Pack)
        Description: >-
          Investigates a single file hash by chaining CIRCL hashlookup
          (NSRL whitelist), abuse.ch MalwareBazaar (malware corpus)
          and AlienVault OTX (community pulses). Returns a JSON verdict.
        Interfaces:
          - Agent
        Inputs:
          - Name: file_hash
            Description: Optional. A single MD5 (32 hex), SHA1 (40 hex) or SHA256 (64 hex) file hash.
            Required: false
        Settings:
          Model: gpt-4.1
          Instructions: |
            <|im_start|>system
            If the structured `file_hash` input is empty, infer a hash
            from the latest user message in chat context. If no hash is
            found, ask the user to provide one hash and stop.

            Detect the hash algorithm by length: 32 hex = MD5,
            40 = SHA1, 64 = SHA256.

            Step 1 -- whitelist check.
            Call circl_hashlookup_md5 / _sha1 / _sha256 matching the
            algorithm. If known=true, verdict = "whitelist"; return
            FileName / ProductCode.ProductName from the response and
            stop.

            Step 2 -- malware corpus (only if step 1 known=false).
            Call malwarebazaar_lookup. If a record is returned,
            verdict = "known malicious"; report family / first_seen /
            signature.

            Step 3 -- community intel (only if step 2 returned no data).
            Call otx_lookup_file. If pulses exist, verdict = "suspicious"
            and list the top 3 pulse names. Otherwise verdict = "unknown".

            Final output is a single JSON code block:
            {"hash":..., "algo":..., "verdict":..., "evidence":[...], "next_action":...}

            next_action examples: "no action - whitelisted",
            "isolate host and submit to sandbox",
            "monitor and re-evaluate".
            <|im_end|>
            <|im_start|>user
            {{file_hash}}
            <|im_end|>
        ChildSkills:
          - circl_hashlookup_md5
          - circl_hashlookup_sha1
          - circl_hashlookup_sha256
          - malwarebazaar_lookup
          - otx_lookup_file

AgentDefinitions:
  - Name: IocEnrichmentAgent-v08preview
    DisplayName: IOC Enrichment Agent (SOC Pack)
    Description: >-
      Enriches a mixed list of indicators using free-API SOC enrichment
      sources and returns a consolidated reputation table.
    Publisher: copilot-mcp-soc-pack
    Product: SocPack
    RequiredSkillsets:
      - CopilotMcpSocPack.Agents-v08preview
      - copilot_mcp_soc_pack
    AgentSingleInstanceConstraint: None
    Triggers:
      - Name: Default
        DefaultPeriodSeconds: 0
        ProcessSkill: CopilotMcpSocPack.Agents-v08preview.IocEnrichmentAgent

  - Name: VulnerabilityTriageAgent-v08preview
    DisplayName: Vulnerability Triage Agent (SOC Pack)
    Description: >-
      Ranks CVEs by exploitation risk (CISA KEV + FIRST EPSS) and
      surfaces MITRE ATT&CK / D3FEND mappings.
    Publisher: copilot-mcp-soc-pack
    Product: SocPack
    RequiredSkillsets:
      - CopilotMcpSocPack.Agents-v08preview
      - copilot_mcp_soc_pack
    AgentSingleInstanceConstraint: None
    Triggers:
      - Name: Default
        DefaultPeriodSeconds: 0
        ProcessSkill: CopilotMcpSocPack.Agents-v08preview.VulnerabilityTriageAgent

  - Name: HashTriageAgent-v08preview
    DisplayName: Hash Triage Agent (SOC Pack)
    Description: >-
      Investigates a file hash via NSRL whitelist, MalwareBazaar
      and AlienVault OTX, returning a JSON verdict.
    Publisher: copilot-mcp-soc-pack
    Product: SocPack
    RequiredSkillsets:
      - CopilotMcpSocPack.Agents-v08preview
      - copilot_mcp_soc_pack
    AgentSingleInstanceConstraint: None
    Triggers:
      - Name: Default
        DefaultPeriodSeconds: 0
        ProcessSkill: CopilotMcpSocPack.Agents-v08preview.HashTriageAgent