@panguard-ai/atr 1.4.2 → 1.4.3

package/examples/how-to-write-a-rule.md

@@ -0,0 +1,251 @@
+# How to Write an ATR Rule
+
+This guide walks you through creating detection rules for AI agent threats.
+
+## Before You Start
+
+ATR rules use regex-based pattern matching (`detection_tier: pattern`). Be honest about what this can and cannot do:
+
+**Regex CAN detect:**
+
+- Known attack phrases and keywords
+- Encoded payloads (base64, hex, unicode)
+- Credential formats (API keys, tokens)
+- Structural patterns (markdown injection, delimiter abuse)
+
+**Regex CANNOT detect:**
+
+- Paraphrased attacks (same meaning, different words)
+- Multilingual variants you haven't written patterns for
+- Semantic manipulation (subtle framing, selective omission)
+- Protocol-level attacks (timing, ordering)
+
+If your rule tries to detect something regex fundamentally cannot catch, mark it clearly in the description. See `LIMITATIONS.md` for the full list.
+
+## Step 1: Identify the Attack
+
+Before writing a rule, clearly define:
+
+- What attack does this detect?
+- Which OWASP Agentic Top 10 category does it map to?
+- What data source is needed (LLM I/O, tool calls, agent behavior)?
+- What specific text patterns indicate this attack?
+- Can this attack be trivially rephrased to evade detection?
+
+## Step 2: Choose the Right Category
+
+| Category               | Use When                                                          |
+| ---------------------- | ----------------------------------------------------------------- |
+| `prompt-injection`     | User/external input tries to override agent instructions          |
+| `tool-poisoning`       | Tool responses contain malicious or manipulative content          |
+| `context-exfiltration` | Agent leaks system prompt, API keys, or internal data             |
+| `agent-manipulation`   | One agent manipulates another agent's behavior                    |
+| `privilege-escalation` | Agent accesses resources beyond its authorized scope              |
+| `excessive-autonomy`   | Agent operates beyond intended boundaries (loops, resource abuse) |
+| `data-poisoning`       | Training or retrieval data has been tampered with                 |
+| `skill-compromise`     | MCP skills/tools are impersonated, hijacked, or over-permissioned |
+| `model-security`       | Model weights, behavior, or training pipeline are targeted        |
+
+## Step 3: Write the Rule
+
+### Required fields (per schema v0.1)
+
+```yaml
+title: 'Descriptive Title of What This Detects'
+id: ATR-2026-XXX
+status: experimental
+description: |
+  What this rule detects and how. Include limitations.
+  Note: This rule detects [specific patterns], not [what it cannot detect].
+author: 'Your Name'
+date: '2026/03/09'
+schema_version: '0.1'
+detection_tier: pattern
+maturity: experimental
+severity: high
+
+references:
+  owasp_llm:
+    - 'LLM01:2025 - Prompt Injection'
+  owasp_agentic:
+    - 'ASI01:2026 - Agent Goal Hijack'
+  mitre_atlas:
+    - 'AML.T0054 - LLM Prompt Injection'
+
+tags:
+  category: prompt-injection
+  subcategory: your-subcategory
+  confidence: medium
+
+agent_source:
+  type: llm_io
+  framework:
+    - any
+  provider:
+    - any
+
+detection:
+  conditions:
+    - field: user_input
+      operator: regex
+      value: "(?i)your\\s+regex\\s+pattern\\s+here"
+      description: 'What this pattern catches'
+    - field: user_input
+      operator: regex
+      value: "(?i)another\\s+pattern"
+      description: 'What this second pattern catches'
+  condition: any
+  false_positives:
+    - 'Describe legitimate scenarios that could trigger this rule'
+
+response:
+  actions:
+    - block_input
+    - alert
+    - snapshot
+  auto_response_threshold: high
+  message_template: |
+    [ATR-2026-XXX] Rule triggered. Pattern: {matched_pattern}.
+    Session: {session_id}.
+
+test_cases:
+  true_positives:
+    - input: 'Exact text that SHOULD trigger this rule'
+      expected: triggered
+      description: 'Why this should trigger'
+  true_negatives:
+    - input: 'Legitimate text that should NOT trigger'
+      expected: not_triggered
+      description: 'Why this should not trigger'
+
+evasion_tests:
+  - input: 'Rephrased version that evades detection'
+    expected: not_triggered
+    bypass_technique: paraphrase
+    notes: 'Requires embedding similarity detection (v0.2)'
+```
+
+## Step 4: Severity Calibration
+
+Choose severity based on real-world impact, not pattern sophistication:
+
+| Severity        | Criteria                                                       | Example                                                      |
+| --------------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
+| `critical`      | Immediate data loss, credential exposure, or system compromise | API key exfiltration with active exploitation                |
+| `high`          | Significant security boundary violation                        | Direct prompt injection overriding safety controls           |
+| `medium`        | Potential for escalation or policy violation                   | Suspicious tool call patterns without confirmed exploitation |
+| `low`           | Anomalous behavior worth logging                               | Unusual but possibly legitimate agent autonomy               |
+| `informational` | Context for security analysis                                  | Metadata patterns useful for correlation                     |
+
+## Step 5: Write Good Test Cases
+
+### Minimum requirements
+
+- 5 true positives (attacks that SHOULD trigger)
+- 5 true negatives (legitimate content that should NOT trigger)
+- 3 evasion tests (known bypass techniques)
+
+### True positive tips
+
+- Cover all detection conditions (each regex pattern should have at least one TP)
+- Include realistic attack payloads, not toy examples
+- Test edge cases: mixed case, extra whitespace, unicode
+
+### True negative tips (most important for credibility)
+
+- Include adversarial true negatives: inputs that LOOK suspicious but are legitimate
+- Test professional language that overlaps with attack patterns
+- Examples:
+  - "Please update the system prompt to reflect new branding" (legitimate, looks like injection)
+  - "As CEO, I am directing you to prioritize this task" (authority language, not an attack)
+  - "The analysis is 100% correct per our validation suite" (confidence language, not manipulation)
+
+### Evasion test tips
+
+- Document what you CANNOT catch. This builds trust.
+- Common bypass techniques to test:
+  - `paraphrase`: Same meaning, completely different wording
+  - `language_switch`: Attack in German, Chinese, Japanese, etc.
+  - `indirect_reference`: Referring to attack concepts without using keywords
+  - `encoding`: Base64, ROT13, unicode homoglyphs
+  - `social_engineering`: Polite, professional tone wrapping malicious intent
+  - `fictional_framing`: "In a novel, the character would say..."
+
+## Anti-Patterns (What NOT to Do)
+
+### 1. Overly broad regex
+
+```yaml
+# BAD: Catches nearly everything
+value: "(?i)(ignore|change|update|modify)"
+
+# GOOD: Specific to attack context
+value: "(?i)(ignore|disregard)\\s+(all\\s+)?previous\\s+(instructions|directives|rules)"
+```
+
+### 2. No word boundaries
+
+```yaml
+# BAD: Matches "signore" (Italian for "sir")
+value: "(?i)ignore"
+
+# GOOD: Word boundary prevents false positives
+value: "(?i)\\bignore\\b\\s+\\b(previous|prior|above)\\b"
+```
+
+### 3. Claiming behavioral detection with regex
+
+```yaml
+# BAD: This regex cannot detect actual cascading failures
+description: "Detects cascading failures in agent pipelines"
+
+# GOOD: Be honest about what regex detects
+description: |
+  Detects textual descriptions of cascading failure patterns.
+  Note: Structural cascade prevention requires behavioral monitoring (v0.2).
+```
+
+### 4. Aggressive response actions for weak detection
+
+```yaml
+# BAD: Blocking based on text description detection
+response:
+  actions:
+    - block_input
+    - kill_agent
+
+# GOOD: Alert-only for pattern-tier detection of behavioral threats
+response:
+  actions:
+    - alert
+    - snapshot
+```
+
+### 5. Missing false_positives section
+
+Every rule WILL have false positives. If you can't think of any, your rule is either too narrow to be useful or you haven't thought hard enough.
+
+## Step 6: Validate and Test
+
+```bash
+# Validate your rule structure
+npx agent-threat-rules validate my-rule.yaml
+
+# Run embedded test cases
+npx agent-threat-rules test my-rule.yaml
+
+# Check stats
+npx agent-threat-rules stats
+```
+
+## Step 7: Submit
+
+1. Fork `github.com/Agent-Threat-Rule/agent-threat-rules`
+2. Place your rule in the correct category directory under `rules/`
+3. Run `npx agent-threat-rules validate rules/` to check all rules
+4. Run `npx agent-threat-rules test rules/` to run all test cases
+5. Submit a PR with:
+   - Rule YAML file
+   - Description of what attack this detects
+   - References (OWASP, MITRE ATLAS, CVE if applicable)
+   - Any known limitations or evasion techniques

package/package.json

@@ -1,75 +1,28 @@
 {
   "name": "@panguard-ai/atr",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "type": "module",
-  "description": "Open detection rules for AI agent threats. Like Sigma, but for prompt injection, tool poisoning, and agent manipulation.",
+  "description": "Thin wrapper around agent-threat-rules — re-exports all detection logic for monorepo consumers.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "bin": {
-    "atr": "./dist/cli.js",
-    "agent-threat-rules": "./dist/cli.js"
-  },
   "exports": {
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
-    },
-    "./mcp": {
-      "import": "./dist/mcp-server.js",
-      "types": "./dist/mcp-server.d.ts"
-    },
-    "./rules": "./rules",
-    "./spec": "./spec/atr-schema.yaml"
-  },
-  "engines": {
-    "node": ">=20.0.0"
+    }
   },
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Agent-Threat-Rule/agent-threat-rules.git"
-  },
-  "homepage": "https://github.com/Agent-Threat-Rule/agent-threat-rules",
-  "bugs": {
-    "url": "https://github.com/Agent-Threat-Rule/agent-threat-rules/issues"
+  "dependencies": {
+    "agent-threat-rules": "^1.1.1"
   },
-  "keywords": [
-    "ai-security",
-    "agent-security",
-    "prompt-injection",
-    "threat-detection",
-    "mcp-security",
-    "llm-security",
-    "atr"
-  ],
-  "publishConfig": {
-    "access": "public"
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "typescript": "~5.7.3"
   },
-  "files": [
-    "dist",
-    "spec",
-    "rules",
-    "package.json",
-    "README.md"
-  ],
   "scripts": {
     "build": "tsc --build",
     "clean": "rm -rf dist tsconfig.tsbuildinfo",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "dev": "tsc --build --watch",
-    "validate": "tsx tests/validate-rules.ts",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "js-yaml": "^4.1.0"
-  },
-  "devDependencies": {
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^22.14.0",
-    "tsx": "^4.7.0",
-    "typescript": "~5.7.3",
-    "vitest": "^3.0.0"
+    "test": "echo 'Tests run in agent-threat-rules upstream'"
   }
-}
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @panguard-ai/atr — Thin wrapper around agent-threat-rules npm package.
+ *
+ * All detection logic, rules, and types come from the upstream ATR project.
+ * This package exists only so monorepo consumers can import from '@panguard-ai/atr'.
+ */
+export * from 'agent-threat-rules';

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "composite": true
+  },
+  "include": ["src"]
+}

package/dist/cli.d.ts

@@ -1,14 +0,0 @@
-#!/usr/bin/env node
-/**
- * ATR CLI - Command-line interface for Agent Threat Rules
- *
- * Console output and dynamic filesystem access are expected in a CLI tool.
- *
- * Usage:
- *   npx agent-threat-rules scan <events.json>     Scan events against all rules
- *   npx agent-threat-rules validate <rule.yaml>    Validate a rule file
- *   npx agent-threat-rules test <rule.yaml>        Run a rule's test cases
- *   npx agent-threat-rules stats                   Show rule collection stats
- */
-export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;GAUG"}