Skip to main content

​
System Architecture

Panguard AI is a TypeScript monorepo with 13 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)                |
  +-------------------------------------------------------+
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.

​
13-Package Monorepo

The codebase is organized as a pnpm workspace monorepo. Each package has a single responsibility:
PackageLayerPurpose
@panguard-ai/coreSharedRule engine, monitors, AI providers, i18n, encryption
@panguard-ai/panguardEndpointCLI entry point (panguard command)
@panguard-ai/panguard-guardEndpointReal-time protection agent (5-stage AI pipeline)
@panguard-ai/panguard-scanEndpointSecurity scanner and risk scoring
@panguard-ai/panguard-chatEndpointNotification system (5 channels, 3 role formats)
@panguard-ai/panguard-trapEndpointHoneypot system (8 service types)
@panguard-ai/panguard-reportEndpointCompliance report generation (TCSA, ISO 27001, SOC 2)
@panguard-ai/panguard-authSharedOAuth flow, session management, tier gating
@panguard-ai/panguard-managerManagerFleet orchestration and agent registration
@panguard-ai/threat-cloudCloudCollective intelligence API server
@panguard-ai/panguard-webCloudWeb dashboard (Next.js)
@panguard-ai/adminCloudAdmin panel for Threat Cloud and user management
@panguard-ai/websiteCloudMarketing website (panguard.ai)

​
@panguard-ai/core — Shared Foundation

The core package is the foundation that every other package depends on. It provides:
  • Sigma rule parser and evaluator (boolean logic, aggregation, modifiers, wildcards)
  • YARA scanner with native engine support and regex fallback
  • 3000+ bundled Sigma rules, custom rule loading
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
  • 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)
  • English and Traditional Chinese
  • All CLI output, reports, and notifications are fully localized
  • Language selection via panguard init or --lang flag
  • OS detection (macOS, Linux, Windows)
  • Network interface enumeration
  • Running service inventory
  • Security tool detection (antivirus, EDR, IDS)
  • Hardware identifier collection for encryption key derivation

​
Tech Stack

TechnologyVersionPurpose
TypeScript5.7Primary language across all packages
Node.js22Runtime
pnpm9+Workspace-aware package manager
VitestLatestUnit and integration testing
esbuildLatestFast bundling for CLI distribution
better-sqlite3LatestEmbedded database for Threat Cloud and Guard state
Next.js14Web dashboard and marketing website

​
Cross-Platform Support

Panguard runs on all three major operating systems:
PlatformGuardScanTrapManager
macOS (ARM64, x64)YesYesYesYes
Linux (x64, ARM64)YesYesYesYes
Windows (x64)YesYesYesYes
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:
1

Event detected

A monitor in core (process, network, file, or log) detects a security-relevant event on the endpoint.
2

Layer 1 evaluation

The Sigma/YARA rule engine evaluates the event in under 1ms. If a rule matches, the event is classified and a response is triggered immediately.
3

AI escalation (if needed)

Unmatched events are forwarded to Layer 2 (local Ollama) or Layer 3 (Cloud AI) for deeper analysis via the FunnelRouter.
4

Response execution

Based on classification and confidence, the auto-response engine takes action: block IP, quarantine file, terminate process, or notify only.
5

Reporting and notification

Chat sends a notification via the configured channel. The event is logged for Guard status, security score updates, and compliance reports.
6

Threat Cloud upload (optional)

If Threat Cloud participation is enabled, anonymized indicators are uploaded to benefit the community.

Three-Layer AI

Deep dive into the Rules, Local AI, and Cloud AI funnel.

Guard Pipeline

The 5-stage AI agent pipeline inside Guard.

Manager

Fleet orchestration and centralized management.