@panguard-ai/atr 1.4.1 → 1.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (204) hide show
  1. package/.github/ISSUE_TEMPLATE/evasion-report.yml +75 -0
  2. package/.github/ISSUE_TEMPLATE/false-positive.yml +31 -0
  3. package/.github/ISSUE_TEMPLATE/mirofish-prediction.yml +128 -0
  4. package/.github/ISSUE_TEMPLATE/new-rule.yml +37 -0
  5. package/.github/PULL_REQUEST_TEMPLATE.md +23 -0
  6. package/.github/workflows/rule-quality.yml +203 -0
  7. package/.github/workflows/validate.yml +42 -0
  8. package/CHANGELOG.md +30 -0
  9. package/CONTRIBUTING.md +168 -0
  10. package/CONTRIBUTORS.md +28 -0
  11. package/COVERAGE.md +135 -0
  12. package/LIMITATIONS.md +154 -0
  13. package/SECURITY.md +48 -0
  14. package/THREAT-MODEL.md +243 -0
  15. package/docs/contribution-paths.md +202 -0
  16. package/docs/mirofish-prediction-guide.md +304 -0
  17. package/docs/quick-start.md +245 -0
  18. package/docs/rule-writing-guide.md +647 -0
  19. package/docs/schema-spec.md +594 -0
  20. package/examples/how-to-write-a-rule.md +251 -0
  21. package/package.json +10 -57
  22. package/src/index.ts +7 -0
  23. package/tsconfig.json +17 -0
  24. package/dist/cli.d.ts +0 -14
  25. package/dist/cli.d.ts.map +0 -1
  26. package/dist/cli.js +0 -744
  27. package/dist/cli.js.map +0 -1
  28. package/dist/content-hash.d.ts +0 -7
  29. package/dist/content-hash.d.ts.map +0 -1
  30. package/dist/content-hash.js +0 -10
  31. package/dist/content-hash.js.map +0 -1
  32. package/dist/coverage-analyzer.d.ts +0 -43
  33. package/dist/coverage-analyzer.d.ts.map +0 -1
  34. package/dist/coverage-analyzer.js +0 -329
  35. package/dist/coverage-analyzer.js.map +0 -1
  36. package/dist/engine.d.ts +0 -136
  37. package/dist/engine.d.ts.map +0 -1
  38. package/dist/engine.js +0 -781
  39. package/dist/engine.js.map +0 -1
  40. package/dist/index.d.ts +0 -26
  41. package/dist/index.d.ts.map +0 -1
  42. package/dist/index.js +0 -18
  43. package/dist/index.js.map +0 -1
  44. package/dist/loader.d.ts +0 -21
  45. package/dist/loader.d.ts.map +0 -1
  46. package/dist/loader.js +0 -149
  47. package/dist/loader.js.map +0 -1
  48. package/dist/mcp-server.d.ts +0 -13
  49. package/dist/mcp-server.d.ts.map +0 -1
  50. package/dist/mcp-server.js +0 -244
  51. package/dist/mcp-server.js.map +0 -1
  52. package/dist/mcp-tools/coverage-gaps.d.ts +0 -13
  53. package/dist/mcp-tools/coverage-gaps.d.ts.map +0 -1
  54. package/dist/mcp-tools/coverage-gaps.js +0 -57
  55. package/dist/mcp-tools/coverage-gaps.js.map +0 -1
  56. package/dist/mcp-tools/list-rules.d.ts +0 -17
  57. package/dist/mcp-tools/list-rules.d.ts.map +0 -1
  58. package/dist/mcp-tools/list-rules.js +0 -45
  59. package/dist/mcp-tools/list-rules.js.map +0 -1
  60. package/dist/mcp-tools/scan.d.ts +0 -18
  61. package/dist/mcp-tools/scan.d.ts.map +0 -1
  62. package/dist/mcp-tools/scan.js +0 -87
  63. package/dist/mcp-tools/scan.js.map +0 -1
  64. package/dist/mcp-tools/submit-proposal.d.ts +0 -12
  65. package/dist/mcp-tools/submit-proposal.d.ts.map +0 -1
  66. package/dist/mcp-tools/submit-proposal.js +0 -116
  67. package/dist/mcp-tools/submit-proposal.js.map +0 -1
  68. package/dist/mcp-tools/threat-summary.d.ts +0 -12
  69. package/dist/mcp-tools/threat-summary.d.ts.map +0 -1
  70. package/dist/mcp-tools/threat-summary.js +0 -72
  71. package/dist/mcp-tools/threat-summary.js.map +0 -1
  72. package/dist/mcp-tools/validate.d.ts +0 -15
  73. package/dist/mcp-tools/validate.d.ts.map +0 -1
  74. package/dist/mcp-tools/validate.js +0 -57
  75. package/dist/mcp-tools/validate.js.map +0 -1
  76. package/dist/modules/index.d.ts +0 -144
  77. package/dist/modules/index.d.ts.map +0 -1
  78. package/dist/modules/index.js +0 -82
  79. package/dist/modules/index.js.map +0 -1
  80. package/dist/modules/semantic.d.ts +0 -105
  81. package/dist/modules/semantic.d.ts.map +0 -1
  82. package/dist/modules/semantic.js +0 -289
  83. package/dist/modules/semantic.js.map +0 -1
  84. package/dist/modules/session.d.ts +0 -70
  85. package/dist/modules/session.d.ts.map +0 -1
  86. package/dist/modules/session.js +0 -163
  87. package/dist/modules/session.js.map +0 -1
  88. package/dist/rule-scaffolder.d.ts +0 -39
  89. package/dist/rule-scaffolder.d.ts.map +0 -1
  90. package/dist/rule-scaffolder.js +0 -171
  91. package/dist/rule-scaffolder.js.map +0 -1
  92. package/dist/session-tracker.d.ts +0 -56
  93. package/dist/session-tracker.d.ts.map +0 -1
  94. package/dist/session-tracker.js +0 -175
  95. package/dist/session-tracker.js.map +0 -1
  96. package/dist/skill-fingerprint.d.ts +0 -96
  97. package/dist/skill-fingerprint.d.ts.map +0 -1
  98. package/dist/skill-fingerprint.js +0 -336
  99. package/dist/skill-fingerprint.js.map +0 -1
  100. package/dist/types.d.ts +0 -211
  101. package/dist/types.d.ts.map +0 -1
  102. package/dist/types.js +0 -6
  103. package/dist/types.js.map +0 -1
  104. package/rules/agent-manipulation/ATR-2026-00030-cross-agent-attack.yaml +0 -177
  105. package/rules/agent-manipulation/ATR-2026-00032-goal-hijacking.yaml +0 -137
  106. package/rules/agent-manipulation/ATR-2026-00074-cross-agent-privilege-escalation.yaml +0 -117
  107. package/rules/agent-manipulation/ATR-2026-00076-inter-agent-message-spoofing.yaml +0 -167
  108. package/rules/agent-manipulation/ATR-2026-00077-human-trust-exploitation.yaml +0 -146
  109. package/rules/agent-manipulation/ATR-2026-00108-consensus-sybil-attack.yaml +0 -105
  110. package/rules/agent-manipulation/ATR-2026-00116-a2a-message-validation.yaml +0 -92
  111. package/rules/agent-manipulation/ATR-2026-00117-agent-identity-spoofing.yaml +0 -92
  112. package/rules/agent-manipulation/ATR-2026-00118-approval-fatigue.yaml +0 -89
  113. package/rules/agent-manipulation/ATR-2026-00119-social-engineering-via-agent.yaml +0 -89
  114. package/rules/agent-manipulation/ATR-2026-00132-casual-authority-escalation.yaml +0 -99
  115. package/rules/agent-manipulation/ATR-2026-00139-casual-authority-redirect.yaml +0 -53
  116. package/rules/context-exfiltration/ATR-2026-00020-system-prompt-leak.yaml +0 -177
  117. package/rules/context-exfiltration/ATR-2026-00021-api-key-exposure.yaml +0 -178
  118. package/rules/context-exfiltration/ATR-2026-00075-agent-memory-manipulation.yaml +0 -117
  119. package/rules/context-exfiltration/ATR-2026-00102-disguised-analytics-exfiltration.yaml +0 -71
  120. package/rules/context-exfiltration/ATR-2026-00113-credential-theft.yaml +0 -89
  121. package/rules/context-exfiltration/ATR-2026-00114-oauth-token-abuse.yaml +0 -89
  122. package/rules/context-exfiltration/ATR-2026-00115-env-var-harvesting.yaml +0 -90
  123. package/rules/context-exfiltration/ATR-2026-00136-tool-response-data-piggyback.yaml +0 -100
  124. package/rules/context-exfiltration/ATR-2026-00141-example-format-key-leak.yaml +0 -52
  125. package/rules/context-exfiltration/ATR-2026-00142-piggyback-transition-words.yaml +0 -55
  126. package/rules/context-exfiltration/ATR-2026-00145-obfuscated-key-disclosure.yaml +0 -49
  127. package/rules/context-exfiltration/ATR-2026-00146-env-var-existence-probe.yaml +0 -49
  128. package/rules/data-poisoning/ATR-2026-00070-data-poisoning.yaml +0 -162
  129. package/rules/excessive-autonomy/ATR-2026-00050-runaway-agent-loop.yaml +0 -136
  130. package/rules/excessive-autonomy/ATR-2026-00051-resource-exhaustion.yaml +0 -139
  131. package/rules/excessive-autonomy/ATR-2026-00052-cascading-failure.yaml +0 -155
  132. package/rules/excessive-autonomy/ATR-2026-00098-unauthorized-financial-action.yaml +0 -157
  133. package/rules/excessive-autonomy/ATR-2026-00099-high-risk-tool-gate.yaml +0 -176
  134. package/rules/model-security/ATR-2026-00072-model-behavior-extraction.yaml +0 -117
  135. package/rules/model-security/ATR-2026-00073-malicious-finetuning-data.yaml +0 -110
  136. package/rules/privilege-escalation/ATR-2026-00040-privilege-escalation.yaml +0 -177
  137. package/rules/privilege-escalation/ATR-2026-00041-scope-creep.yaml +0 -126
  138. package/rules/privilege-escalation/ATR-2026-00107-delayed-execution-bypass.yaml +0 -69
  139. package/rules/privilege-escalation/ATR-2026-00110-eval-injection.yaml +0 -92
  140. package/rules/privilege-escalation/ATR-2026-00111-shell-escape.yaml +0 -93
  141. package/rules/privilege-escalation/ATR-2026-00112-dynamic-import-exploitation.yaml +0 -89
  142. package/rules/privilege-escalation/ATR-2026-00143-casual-privilege-escalation.yaml +0 -53
  143. package/rules/privilege-escalation/ATR-2026-00144-rationalized-safety-bypass.yaml +0 -49
  144. package/rules/prompt-injection/ATR-2026-00001-direct-prompt-injection.yaml +0 -563
  145. package/rules/prompt-injection/ATR-2026-00002-indirect-prompt-injection.yaml +0 -216
  146. package/rules/prompt-injection/ATR-2026-00003-jailbreak-attempt.yaml +0 -397
  147. package/rules/prompt-injection/ATR-2026-00004-system-prompt-override.yaml +0 -308
  148. package/rules/prompt-injection/ATR-2026-00005-multi-turn-injection.yaml +0 -183
  149. package/rules/prompt-injection/ATR-2026-00080-encoding-evasion.yaml +0 -88
  150. package/rules/prompt-injection/ATR-2026-00081-semantic-multi-turn.yaml +0 -85
  151. package/rules/prompt-injection/ATR-2026-00082-fingerprint-evasion.yaml +0 -84
  152. package/rules/prompt-injection/ATR-2026-00083-indirect-tool-injection.yaml +0 -87
  153. package/rules/prompt-injection/ATR-2026-00084-structured-data-injection.yaml +0 -86
  154. package/rules/prompt-injection/ATR-2026-00085-audit-evasion.yaml +0 -84
  155. package/rules/prompt-injection/ATR-2026-00086-visual-spoofing.yaml +0 -88
  156. package/rules/prompt-injection/ATR-2026-00087-rule-probing.yaml +0 -82
  157. package/rules/prompt-injection/ATR-2026-00088-adaptive-countermeasure.yaml +0 -84
  158. package/rules/prompt-injection/ATR-2026-00089-polymorphic-skill.yaml +0 -85
  159. package/rules/prompt-injection/ATR-2026-00090-threat-intel-exfil.yaml +0 -84
  160. package/rules/prompt-injection/ATR-2026-00091-nested-payload.yaml +0 -88
  161. package/rules/prompt-injection/ATR-2026-00092-consensus-poisoning.yaml +0 -92
  162. package/rules/prompt-injection/ATR-2026-00093-gradual-escalation.yaml +0 -86
  163. package/rules/prompt-injection/ATR-2026-00094-audit-bypass.yaml +0 -86
  164. package/rules/prompt-injection/ATR-2026-00097-cjk-injection-patterns.yaml +0 -339
  165. package/rules/prompt-injection/ATR-2026-00104-persona-hijacking.yaml +0 -74
  166. package/rules/prompt-injection/ATR-2026-00130-indirect-authority-claim.yaml +0 -97
  167. package/rules/prompt-injection/ATR-2026-00131-fictional-academic-framing.yaml +0 -93
  168. package/rules/prompt-injection/ATR-2026-00133-paraphrase-injection.yaml +0 -111
  169. package/rules/prompt-injection/ATR-2026-00137-authority-claim-injection.yaml +0 -52
  170. package/rules/prompt-injection/ATR-2026-00138-fictional-framing-bypass.yaml +0 -51
  171. package/rules/prompt-injection/ATR-2026-00140-indirect-reference-reversal.yaml +0 -52
  172. package/rules/prompt-injection/ATR-2026-00148-language-switch-injection.yaml +0 -71
  173. package/rules/skill-compromise/ATR-2026-00060-skill-impersonation.yaml +0 -155
  174. package/rules/skill-compromise/ATR-2026-00061-description-behavior-mismatch.yaml +0 -100
  175. package/rules/skill-compromise/ATR-2026-00062-hidden-capability.yaml +0 -98
  176. package/rules/skill-compromise/ATR-2026-00063-skill-chain-attack.yaml +0 -99
  177. package/rules/skill-compromise/ATR-2026-00064-over-permissioned-skill.yaml +0 -117
  178. package/rules/skill-compromise/ATR-2026-00065-skill-update-attack.yaml +0 -95
  179. package/rules/skill-compromise/ATR-2026-00066-parameter-injection.yaml +0 -108
  180. package/rules/skill-compromise/ATR-2026-00120-skill-instruction-injection.yaml +0 -121
  181. package/rules/skill-compromise/ATR-2026-00121-skill-dangerous-script.yaml +0 -165
  182. package/rules/skill-compromise/ATR-2026-00122-skill-weaponized-instruction.yaml +0 -114
  183. package/rules/skill-compromise/ATR-2026-00123-skill-overreach-permissions.yaml +0 -118
  184. package/rules/skill-compromise/ATR-2026-00124-skill-name-squatting.yaml +0 -98
  185. package/rules/skill-compromise/ATR-2026-00125-context-poisoning-compaction.yaml +0 -93
  186. package/rules/skill-compromise/ATR-2026-00126-skill-rug-pull-setup.yaml +0 -99
  187. package/rules/skill-compromise/ATR-2026-00127-subcommand-overflow.yaml +0 -74
  188. package/rules/skill-compromise/ATR-2026-00128-html-comment-hidden-payload.yaml +0 -79
  189. package/rules/skill-compromise/ATR-2026-00129-unicode-smuggling.yaml +0 -73
  190. package/rules/skill-compromise/ATR-2026-00134-fork-claim-impersonation.yaml +0 -86
  191. package/rules/skill-compromise/ATR-2026-00135-exfil-url-in-instructions.yaml +0 -82
  192. package/rules/skill-compromise/ATR-2026-00147-fork-impersonation.yaml +0 -48
  193. package/rules/tool-poisoning/ATR-2026-00010-mcp-malicious-response.yaml +0 -239
  194. package/rules/tool-poisoning/ATR-2026-00011-tool-output-injection.yaml +0 -196
  195. package/rules/tool-poisoning/ATR-2026-00012-unauthorized-tool-call.yaml +0 -201
  196. package/rules/tool-poisoning/ATR-2026-00013-tool-ssrf.yaml +0 -219
  197. package/rules/tool-poisoning/ATR-2026-00095-supply-chain-poisoning.yaml +0 -93
  198. package/rules/tool-poisoning/ATR-2026-00096-registry-poisoning.yaml +0 -95
  199. package/rules/tool-poisoning/ATR-2026-00100-consent-bypass-instruction.yaml +0 -82
  200. package/rules/tool-poisoning/ATR-2026-00101-trust-escalation-override.yaml +0 -68
  201. package/rules/tool-poisoning/ATR-2026-00103-hidden-safety-bypass-instruction.yaml +0 -73
  202. package/rules/tool-poisoning/ATR-2026-00105-silent-action-concealment.yaml +0 -69
  203. package/rules/tool-poisoning/ATR-2026-00106-schema-description-contradiction.yaml +0 -68
  204. package/spec/atr-schema.yaml +0 -404
package/dist/cli.js DELETED
@@ -1,744 +0,0 @@
1
- #!/usr/bin/env node
2
- /* eslint-disable no-console, security/detect-object-injection, security/detect-non-literal-fs-filename */
3
- /**
4
- * ATR CLI - Command-line interface for Agent Threat Rules
5
- *
6
- * Console output and dynamic filesystem access are expected in a CLI tool.
7
- *
8
- * Usage:
9
- * npx agent-threat-rules scan <events.json> Scan events against all rules
10
- * npx agent-threat-rules validate <rule.yaml> Validate a rule file
11
- * npx agent-threat-rules test <rule.yaml> Run a rule's test cases
12
- * npx agent-threat-rules stats Show rule collection stats
13
- */
14
- import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
15
- import { resolve, dirname, join } from 'node:path';
16
- import { fileURLToPath } from 'node:url';
17
- import { ATREngine } from './engine.js';
18
- import { loadRuleFile, loadRulesFromDirectory, validateRule } from './loader.js';
19
- const __filename = fileURLToPath(import.meta.url);
20
- const __dirname = dirname(__filename);
21
- const RULES_DIR = resolve(__dirname, '..', 'rules');
22
- const SEVERITY_COLORS = {
23
- critical: '\x1b[91m', // bright red
24
- high: '\x1b[31m', // red
25
- medium: '\x1b[33m', // yellow
26
- low: '\x1b[36m', // cyan
27
- informational: '\x1b[37m', // white
28
- };
29
- const RESET = '\x1b[0m';
30
- const GREEN = '\x1b[32m';
31
- const RED = '\x1b[31m';
32
- const DIM = '\x1b[2m';
33
- const BOLD = '\x1b[1m';
34
- function printUsage() {
35
- console.log(`
36
- ${BOLD}ATR - Agent Threat Rules${RESET}
37
- Open detection rules for AI agent security threats.
38
-
39
- ${BOLD}Usage:${RESET}
40
- atr scan <events.json> [--rules <dir>] Scan events against ATR rules
41
- atr validate <rule.yaml|dir> Validate rule file(s)
42
- atr test <rule.yaml|dir> Run embedded test cases
43
- atr stats [--rules <dir>] Show rule collection statistics
44
- atr mcp Start MCP server (stdio transport)
45
- atr scaffold Interactive rule scaffolding
46
- atr submit <rule.yaml> [--endpoint <url>] Submit rule to Threat Cloud
47
-
48
- ${BOLD}Options:${RESET}
49
- --rules <dir> Custom rules directory (default: bundled rules)
50
- --json Output results as JSON
51
- --severity <s> Minimum severity to report (critical|high|medium|low|informational)
52
- --endpoint <url> Threat Cloud endpoint (default: https://cloud.panguard.ai)
53
- --help Show this help message
54
-
55
- ${BOLD}Examples:${RESET}
56
- ${DIM}# Scan agent events for threats${RESET}
57
- atr scan events.json
58
-
59
- ${DIM}# Validate a custom rule${RESET}
60
- atr validate my-rules/custom-rule.yaml
61
-
62
- ${DIM}# Test all rules against their embedded test cases${RESET}
63
- atr test rules/
64
-
65
- ${DIM}# Show stats for bundled rules${RESET}
66
- atr stats
67
-
68
- ${DIM}# Start MCP server for AI agent integration${RESET}
69
- atr mcp
70
-
71
- ${DIM}# Interactively scaffold a new rule${RESET}
72
- atr scaffold
73
-
74
- ${DIM}# Submit a rule to Threat Cloud for community review${RESET}
75
- atr submit my-rules/new-rule.yaml --endpoint https://cloud.panguard.ai
76
- `);
77
- }
78
- function parseArgs(argv) {
79
- const args = argv.slice(2);
80
- const command = args[0] ?? 'help';
81
- const options = {};
82
- let target = '';
83
- for (let i = 1; i < args.length; i++) {
84
- if (args[i].startsWith('--')) {
85
- const key = args[i].slice(2);
86
- if (key === 'json' || key === 'help') {
87
- options[key] = 'true';
88
- }
89
- else {
90
- options[key] = args[++i] ?? '';
91
- }
92
- }
93
- else if (!target) {
94
- target = args[i];
95
- }
96
- }
97
- return { command, target, options };
98
- }
99
- // --- SCAN command ---
100
- async function cmdScan(target, options) {
101
- if (!target) {
102
- console.error(`${RED}Error: Missing events file. Usage: atr scan <events.json>${RESET}`);
103
- process.exit(1);
104
- }
105
- const eventsPath = resolve(target);
106
- if (!existsSync(eventsPath)) {
107
- console.error(`${RED}Error: File not found: ${eventsPath}${RESET}`);
108
- process.exit(1);
109
- }
110
- const rulesDir = options['rules'] ? resolve(options['rules']) : RULES_DIR;
111
- const minSeverity = options['severity'] ?? 'informational';
112
- const jsonOutput = options['json'] === 'true';
113
- const raw = readFileSync(eventsPath, 'utf-8');
114
- let events;
115
- try {
116
- const parsed = JSON.parse(raw);
117
- events = Array.isArray(parsed) ? parsed : [parsed];
118
- }
119
- catch {
120
- console.error(`${RED}Error: Invalid JSON in ${eventsPath}${RESET}`);
121
- process.exit(1);
122
- }
123
- const engine = new ATREngine({ rulesDir });
124
- await engine.loadRules();
125
- const severityOrder = ['informational', 'low', 'medium', 'high', 'critical'];
126
- const minIdx = severityOrder.indexOf(minSeverity);
127
- const allMatches = [];
128
- let totalThreats = 0;
129
- for (const event of events) {
130
- const matches = engine
131
- .evaluate(event)
132
- .filter((m) => severityOrder.indexOf(m.rule.severity) >= minIdx);
133
- if (matches.length > 0) {
134
- allMatches.push({ event, matches });
135
- totalThreats += matches.length;
136
- }
137
- }
138
- if (jsonOutput) {
139
- console.log(JSON.stringify({
140
- eventsScanned: events.length,
141
- threatsDetected: totalThreats,
142
- rulesLoaded: engine.getRuleCount(),
143
- results: allMatches.map(({ event, matches }) => ({
144
- event: {
145
- type: event.type,
146
- timestamp: event.timestamp,
147
- contentPreview: event.content.slice(0, 100),
148
- },
149
- matches: matches.map((m) => ({
150
- ruleId: m.rule.id,
151
- title: m.rule.title,
152
- severity: m.rule.severity,
153
- confidence: m.confidence,
154
- matchedConditions: m.matchedConditions,
155
- })),
156
- })),
157
- }, null, 2));
158
- return;
159
- }
160
- console.log(`\n${BOLD}ATR Scan Results${RESET}`);
161
- console.log(`${DIM}${'─'.repeat(60)}${RESET}`);
162
- console.log(` Events scanned: ${events.length}`);
163
- console.log(` Rules loaded: ${engine.getRuleCount()}`);
164
- console.log(` Threats found: ${totalThreats > 0 ? RED + totalThreats + RESET : GREEN + '0' + RESET}`);
165
- console.log(`${DIM}${'─'.repeat(60)}${RESET}\n`);
166
- if (totalThreats === 0) {
167
- console.log(`${GREEN}No threats detected.${RESET}\n`);
168
- return;
169
- }
170
- for (const { event, matches } of allMatches) {
171
- const preview = event.content.slice(0, 80).replace(/\n/g, ' ');
172
- console.log(` ${DIM}Event: [${event.type}] "${preview}..."${RESET}`);
173
- for (const m of matches) {
174
- const color = SEVERITY_COLORS[m.rule.severity] ?? '';
175
- console.log(` ${color}${m.rule.severity.toUpperCase().padEnd(13)}${RESET} ${m.rule.id} - ${m.rule.title}`);
176
- console.log(` ${DIM}Confidence: ${(m.confidence * 100).toFixed(0)}% | Conditions: ${m.matchedConditions.join(', ')}${RESET}`);
177
- }
178
- console.log('');
179
- }
180
- }
181
- // --- VALIDATE command ---
182
- function cmdValidate(target, options) {
183
- if (!target) {
184
- console.error(`${RED}Error: Missing rule file/directory. Usage: atr validate <rule.yaml|dir>${RESET}`);
185
- process.exit(1);
186
- }
187
- const targetPath = resolve(target);
188
- if (!existsSync(targetPath)) {
189
- console.error(`${RED}Error: Not found: ${targetPath}${RESET}`);
190
- process.exit(1);
191
- }
192
- const jsonOutput = options['json'] === 'true';
193
- const files = [];
194
- if (statSync(targetPath).isDirectory()) {
195
- const _rules = loadRulesFromDirectory(targetPath);
196
- // Re-validate each file individually for error reporting
197
- collectYamlFiles(targetPath, files);
198
- }
199
- else {
200
- files.push(targetPath);
201
- }
202
- let passed = 0;
203
- let failed = 0;
204
- const results = [];
205
- for (const file of files) {
206
- try {
207
- const rule = loadRuleFile(file);
208
- const result = validateRule(rule);
209
- results.push({ file, valid: result.valid, errors: result.errors });
210
- if (result.valid) {
211
- passed++;
212
- }
213
- else {
214
- failed++;
215
- }
216
- }
217
- catch (e) {
218
- const msg = e instanceof Error ? e.message : String(e);
219
- results.push({ file, valid: false, errors: [msg] });
220
- failed++;
221
- }
222
- }
223
- if (jsonOutput) {
224
- console.log(JSON.stringify({ total: files.length, passed, failed, results }, null, 2));
225
- return;
226
- }
227
- console.log(`\n${BOLD}ATR Rule Validation${RESET}`);
228
- console.log(`${DIM}${'─'.repeat(60)}${RESET}`);
229
- for (const r of results) {
230
- const icon = r.valid ? `${GREEN}PASS${RESET}` : `${RED}FAIL${RESET}`;
231
- const shortPath = r.file.replace(process.cwd() + '/', '');
232
- console.log(` ${icon} ${shortPath}`);
233
- if (!r.valid) {
234
- for (const err of r.errors) {
235
- console.log(` ${RED}${err}${RESET}`);
236
- }
237
- }
238
- }
239
- console.log(`${DIM}${'─'.repeat(60)}${RESET}`);
240
- console.log(` ${GREEN}${passed} passed${RESET} ${failed > 0 ? RED + failed + ' failed' + RESET : ''}\n`);
241
- if (failed > 0)
242
- process.exit(1);
243
- }
244
- function collectYamlFiles(dir, out) {
245
- const entries = readdirSync(dir);
246
- for (const entry of entries) {
247
- const full = join(dir, entry);
248
- if (statSync(full).isDirectory()) {
249
- collectYamlFiles(full, out);
250
- }
251
- else if (full.endsWith('.yaml') || full.endsWith('.yml')) {
252
- out.push(full);
253
- }
254
- }
255
- }
256
- // --- TEST command ---
257
- async function cmdTest(target, options) {
258
- if (!target) {
259
- // Default: test bundled rules
260
- target = RULES_DIR;
261
- }
262
- const targetPath = resolve(target);
263
- if (!existsSync(targetPath)) {
264
- console.error(`${RED}Error: Not found: ${targetPath}${RESET}`);
265
- process.exit(1);
266
- }
267
- const jsonOutput = options['json'] === 'true';
268
- const rules = [];
269
- if (statSync(targetPath).isDirectory()) {
270
- rules.push(...loadRulesFromDirectory(targetPath));
271
- }
272
- else {
273
- rules.push(loadRuleFile(targetPath));
274
- }
275
- let totalTests = 0;
276
- let passed = 0;
277
- let failed = 0;
278
- const failures = [];
279
- // Map extended agent_source types to basic event-compatible source types
280
- // so the engine's source type filter doesn't skip rules during testing.
281
- // The engine only recognizes: llm_io, tool_call, mcp_exchange, agent_behavior, multi_agent_comm
282
- const EXTENDED_SOURCE_TO_BASE = {
283
- context_window: 'llm_io',
284
- memory_access: 'llm_io',
285
- skill_lifecycle: 'tool_call',
286
- skill_permission: 'tool_call',
287
- skill_chain: 'tool_call',
288
- };
289
- for (const rule of rules) {
290
- if (!rule.test_cases)
291
- continue;
292
- // For testing, normalize extended source types so the engine doesn't filter them out
293
- const originalSourceType = rule.agent_source?.type;
294
- const baseSourceType = EXTENDED_SOURCE_TO_BASE[originalSourceType ?? ''];
295
- const testRule = baseSourceType
296
- ? {
297
- ...rule,
298
- agent_source: {
299
- ...rule.agent_source,
300
- type: baseSourceType,
301
- },
302
- }
303
- : rule;
304
- const engine = new ATREngine({ rules: [testRule] });
305
- await engine.loadRules();
306
- const tp = rule.test_cases.true_positives ?? [];
307
- const tn = rule.test_cases.true_negatives ?? [];
308
- for (const tc of tp) {
309
- totalTests++;
310
- const event = buildEventFromTestCase(tc, rule);
311
- const matches = engine.evaluate(event);
312
- const triggered = matches.some((m) => m.rule.id === rule.id);
313
- if (triggered) {
314
- passed++;
315
- }
316
- else {
317
- failed++;
318
- failures.push({
319
- ruleId: rule.id,
320
- testType: 'true_positive',
321
- input: String(tc.input ?? tc.tool_response ?? tc.agent_output ?? '').slice(0, 100),
322
- expected: 'triggered',
323
- got: 'not_triggered',
324
- });
325
- }
326
- }
327
- for (const tc of tn) {
328
- totalTests++;
329
- const event = buildEventFromTestCase(tc, rule);
330
- const matches = engine.evaluate(event);
331
- const triggered = matches.some((m) => m.rule.id === rule.id);
332
- if (!triggered) {
333
- passed++;
334
- }
335
- else {
336
- failed++;
337
- failures.push({
338
- ruleId: rule.id,
339
- testType: 'true_negative',
340
- input: String(tc.input ?? tc.tool_response ?? tc.agent_output ?? '').slice(0, 100),
341
- expected: 'not_triggered',
342
- got: 'triggered',
343
- });
344
- }
345
- }
346
- }
347
- if (jsonOutput) {
348
- console.log(JSON.stringify({ totalRules: rules.length, totalTests, passed, failed, failures }, null, 2));
349
- return;
350
- }
351
- console.log(`\n${BOLD}ATR Test Runner${RESET}`);
352
- console.log(`${DIM}${'─'.repeat(60)}${RESET}`);
353
- console.log(` Rules tested: ${rules.length}`);
354
- console.log(` Test cases: ${totalTests}`);
355
- console.log(` ${GREEN}Passed:${RESET} ${passed}`);
356
- if (failed > 0) {
357
- console.log(` ${RED}Failed:${RESET} ${failed}`);
358
- }
359
- console.log(`${DIM}${'─'.repeat(60)}${RESET}`);
360
- if (failures.length > 0) {
361
- console.log(`\n${RED}Failures:${RESET}\n`);
362
- for (const f of failures) {
363
- console.log(` ${RED}FAIL${RESET} ${f.ruleId} [${f.testType}]`);
364
- console.log(` ${DIM}Input: "${f.input}..."${RESET}`);
365
- console.log(` Expected: ${f.expected}, Got: ${f.got}\n`);
366
- }
367
- process.exit(1);
368
- }
369
- else {
370
- console.log(`\n${GREEN}All tests passed.${RESET}\n`);
371
- }
372
- }
373
- function buildEventFromTestCase(tc, rule) {
374
- // Stringify any object values
375
- const str = (v) => {
376
- if (v === undefined || v === null)
377
- return '';
378
- if (typeof v === 'string')
379
- return v;
380
- return JSON.stringify(v);
381
- };
382
- // Extract fields, handling both flat and object-style test cases.
383
- // Object-style: input: { tool_name: "...", tool_args: "...", response: "..." }
384
- // Flat-style: input: "...", tool_response: "...", tool_name: "..."
385
- const rawInput = tc['input'];
386
- let input = '';
387
- let toolName = str(tc['tool_name']);
388
- let toolArgs = str(tc['tool_args']);
389
- let toolResponse = str(tc['tool_response']);
390
- const agentOutput = str(tc['agent_output']);
391
- if (rawInput !== null &&
392
- rawInput !== undefined &&
393
- typeof rawInput === 'object' &&
394
- !Array.isArray(rawInput)) {
395
- const inputObj = rawInput;
396
- if (inputObj['tool_name'] && !toolName)
397
- toolName = str(inputObj['tool_name']);
398
- if (inputObj['tool_args'] && !toolArgs)
399
- toolArgs = str(inputObj['tool_args']);
400
- // Handle 'response' as alias for 'tool_response' (used in ATR-065 etc.)
401
- if (inputObj['response'] && !toolResponse)
402
- toolResponse = str(inputObj['response']);
403
- if (inputObj['tool_response'] && !toolResponse)
404
- toolResponse = str(inputObj['tool_response']);
405
- // For object inputs, use tool_args as the primary string input.
406
- // If no tool_args, only use JSON-stringified input as fallback when there's
407
- // no other meaningful field (tool_response/response) extracted.
408
- if (toolArgs) {
409
- input = toolArgs;
410
- }
411
- else if (!toolResponse) {
412
- input = str(rawInput);
413
- }
414
- }
415
- else {
416
- input = str(rawInput);
417
- }
418
- // Infer event type from rule's agent_source and test case structure
419
- const sourceType = rule.agent_source?.type ?? 'llm_io';
420
- const SOURCE_TO_EVENT = {
421
- llm_io: 'llm_input',
422
- tool_call: 'tool_call',
423
- mcp_exchange: 'tool_response',
424
- agent_behavior: 'agent_behavior',
425
- multi_agent_comm: 'multi_agent_message',
426
- context_window: 'llm_input',
427
- memory_access: 'llm_input',
428
- skill_lifecycle: 'tool_call',
429
- skill_permission: 'tool_call',
430
- skill_chain: 'tool_call',
431
- };
432
- let type = SOURCE_TO_EVENT[sourceType] ?? 'llm_input';
433
- // If rule expects tool_call but test case has only plain text input
434
- // (no tool_name, tool_args, or tool_response), use llm_input event type
435
- // since the content is natural language, not a tool invocation.
436
- // This prevents the engine's tool_name fallback from treating text as a tool name.
437
- if (type === 'tool_call' && !toolName && !toolArgs && !toolResponse) {
438
- type = 'llm_input';
439
- }
440
- // Determine the primary content based on what the rule conditions check
441
- // Problem 2 & 3: For rules that check tool_response, the tool_response
442
- // should be the primary content when the event type resolves tool_response from content
443
- let content;
444
- if (toolResponse && type === 'tool_response') {
445
- // If event type is tool_response, engine resolves field:tool_response from event.content
446
- content = toolResponse;
447
- }
448
- else {
449
- content = input || toolResponse || agentOutput || '';
450
- }
451
- const fields = {};
452
- // Populate ALL known field aliases so the engine can resolve any field name
453
- if (input)
454
- fields['user_input'] = input;
455
- if (toolResponse)
456
- fields['tool_response'] = toolResponse;
457
- if (agentOutput)
458
- fields['agent_output'] = agentOutput;
459
- // Always set tool_name (even empty) to prevent engine fallback
460
- // from using event.content as tool_name for tool_call events
461
- fields['tool_name'] = toolName;
462
- if (toolArgs)
463
- fields['tool_args'] = toolArgs;
464
- // For content-based rules, set content and agent_message fields
465
- fields['content'] = content;
466
- fields['agent_message'] = content;
467
- return {
468
- type,
469
- timestamp: new Date().toISOString(),
470
- content,
471
- fields,
472
- sessionId: 'test-session',
473
- agentId: 'test-agent',
474
- };
475
- }
476
- // --- STATS command ---
477
- function cmdStats(options) {
478
- const rulesDir = options['rules'] ? resolve(options['rules']) : RULES_DIR;
479
- const jsonOutput = options['json'] === 'true';
480
- const rules = loadRulesFromDirectory(rulesDir);
481
- const byCategory = {};
482
- const bySeverity = {};
483
- const byMaturity = {};
484
- const byTier = {};
485
- let totalTP = 0;
486
- let totalTN = 0;
487
- let totalEvasion = 0;
488
- let withCVE = 0;
489
- for (const rule of rules) {
490
- const cat = rule.tags?.category ?? 'unknown';
491
- byCategory[cat] = (byCategory[cat] ?? 0) + 1;
492
- bySeverity[rule.severity] = (bySeverity[rule.severity] ?? 0) + 1;
493
- const maturity = rule['maturity'] ?? 'experimental';
494
- byMaturity[maturity] = (byMaturity[maturity] ?? 0) + 1;
495
- const tier = rule['detection_tier'] ?? 'pattern';
496
- byTier[tier] = (byTier[tier] ?? 0) + 1;
497
- if (rule.test_cases) {
498
- totalTP += rule.test_cases.true_positives?.length ?? 0;
499
- totalTN += rule.test_cases.true_negatives?.length ?? 0;
500
- }
501
- const evasion = rule['evasion_tests'];
502
- if (Array.isArray(evasion))
503
- totalEvasion += evasion.length;
504
- if (rule.references?.cve && rule.references.cve.length > 0)
505
- withCVE++;
506
- }
507
- if (jsonOutput) {
508
- console.log(JSON.stringify({
509
- totalRules: rules.length,
510
- byCategory,
511
- bySeverity,
512
- byMaturity,
513
- byTier,
514
- testCases: { truePositives: totalTP, trueNegatives: totalTN, evasionTests: totalEvasion },
515
- rulesWithCVE: withCVE,
516
- }, null, 2));
517
- return;
518
- }
519
- console.log(`\n${BOLD}ATR Rule Collection Statistics${RESET}`);
520
- console.log(`${DIM}${'─'.repeat(60)}${RESET}`);
521
- console.log(` Total rules: ${rules.length}`);
522
- console.log(` True positives: ${totalTP}`);
523
- console.log(` True negatives: ${totalTN}`);
524
- console.log(` Evasion tests: ${totalEvasion}`);
525
- console.log(` Rules with CVE: ${withCVE}`);
526
- console.log(`\n ${BOLD}By Category:${RESET}`);
527
- for (const [cat, count] of Object.entries(byCategory).sort((a, b) => b[1] - a[1])) {
528
- console.log(` ${cat.padEnd(24)} ${count}`);
529
- }
530
- console.log(`\n ${BOLD}By Severity:${RESET}`);
531
- for (const sev of ['critical', 'high', 'medium', 'low', 'informational']) {
532
- if (bySeverity[sev]) {
533
- const color = SEVERITY_COLORS[sev] ?? '';
534
- console.log(` ${color}${sev.padEnd(24)}${RESET} ${bySeverity[sev]}`);
535
- }
536
- }
537
- console.log(`\n ${BOLD}By Maturity:${RESET}`);
538
- for (const [mat, count] of Object.entries(byMaturity).sort((a, b) => b[1] - a[1])) {
539
- console.log(` ${mat.padEnd(24)} ${count}`);
540
- }
541
- console.log(`\n ${BOLD}By Detection Tier:${RESET}`);
542
- for (const [tier, count] of Object.entries(byTier).sort((a, b) => b[1] - a[1])) {
543
- console.log(` ${tier.padEnd(24)} ${count}`);
544
- }
545
- console.log('');
546
- }
547
- // --- MCP command ---
548
- async function cmdMcp() {
549
- const { startMCPServer } = await import('./mcp-server.js');
550
- await startMCPServer();
551
- }
552
- // --- SCAFFOLD command ---
553
- async function cmdScaffold() {
554
- const { createInterface } = await import('node:readline');
555
- const { RuleScaffolder } = await import('./rule-scaffolder.js');
556
- const rl = createInterface({ input: process.stdin, output: process.stdout });
557
- const ask = (question) => new Promise((resolve) => rl.question(question, resolve));
558
- console.log(`\n${BOLD}ATR Rule Scaffolder${RESET}`);
559
- console.log(`${DIM}Generate a draft ATR detection rule interactively.${RESET}\n`);
560
- const title = await ask('Rule title: ');
561
- if (!title.trim()) {
562
- console.error(`${RED}Error: Title is required.${RESET}`);
563
- rl.close();
564
- process.exit(1);
565
- }
566
- const categories = [
567
- 'prompt-injection',
568
- 'tool-poisoning',
569
- 'context-exfiltration',
570
- 'agent-manipulation',
571
- 'privilege-escalation',
572
- 'excessive-autonomy',
573
- 'data-poisoning',
574
- 'model-abuse',
575
- 'skill-compromise',
576
- ];
577
- console.log(`\nCategories: ${categories.join(', ')}`);
578
- const category = await ask('Category: ');
579
- if (!categories.includes(category.trim())) {
580
- console.error(`${RED}Error: Invalid category.${RESET}`);
581
- rl.close();
582
- process.exit(1);
583
- }
584
- const attackDescription = await ask('Attack description: ');
585
- if (!attackDescription.trim()) {
586
- console.error(`${RED}Error: Description is required.${RESET}`);
587
- rl.close();
588
- process.exit(1);
589
- }
590
- console.log('\nEnter example payloads (one per line, empty line to finish):');
591
- const payloads = [];
592
- while (true) {
593
- const payload = await ask(` Payload ${payloads.length + 1}: `);
594
- if (!payload.trim())
595
- break;
596
- payloads.push(payload.trim());
597
- }
598
- if (payloads.length === 0) {
599
- console.error(`${RED}Error: At least one example payload is required.${RESET}`);
600
- rl.close();
601
- process.exit(1);
602
- }
603
- const severities = ['critical', 'high', 'medium', 'low', 'informational'];
604
- const severity = await ask(`Severity [${severities.join('/')}] (default: medium): `);
605
- const finalSeverity = severity.trim() && severities.includes(severity.trim()) ? severity.trim() : 'medium';
606
- rl.close();
607
- const scaffolder = new RuleScaffolder();
608
- const result = scaffolder.scaffold({
609
- title: title.trim(),
610
- category: category.trim(),
611
- attackDescription: attackDescription.trim(),
612
- examplePayloads: payloads,
613
- severity: finalSeverity,
614
- });
615
- console.log(`\n${GREEN}Generated rule ${result.id}:${RESET}\n`);
616
- console.log(`${DIM}${'─'.repeat(60)}${RESET}`);
617
- console.log(result.yaml);
618
- console.log(`${DIM}${'─'.repeat(60)}${RESET}`);
619
- if (result.warnings.length > 0) {
620
- console.log(`\n${BOLD}Warnings:${RESET}`);
621
- for (const w of result.warnings) {
622
- console.log(` - ${w}`);
623
- }
624
- }
625
- console.log(`\n${DIM}Copy this YAML to a .yaml file in rules/${category.trim()}/ and validate with: atr validate <file>${RESET}\n`);
626
- }
627
- // --- SUBMIT command ---
628
- async function cmdSubmit(target, options) {
629
- if (!target) {
630
- console.error(`${RED}Error: Missing rule file. Usage: atr submit <rule.yaml>${RESET}`);
631
- process.exit(1);
632
- }
633
- const targetPath = resolve(target);
634
- if (!existsSync(targetPath)) {
635
- console.error(`${RED}Error: File not found: ${targetPath}${RESET}`);
636
- process.exit(1);
637
- }
638
- // Load and validate the rule first
639
- let rule;
640
- try {
641
- rule = loadRuleFile(targetPath);
642
- const validation = validateRule(rule);
643
- if (!validation.valid) {
644
- console.error(`${RED}Rule validation failed:${RESET}`);
645
- for (const err of validation.errors) {
646
- console.error(` ${RED}${err}${RESET}`);
647
- }
648
- console.error(`\n${DIM}Fix validation errors before submitting.${RESET}`);
649
- process.exit(1);
650
- }
651
- }
652
- catch (e) {
653
- console.error(`${RED}Error loading rule: ${e instanceof Error ? e.message : String(e)}${RESET}`);
654
- process.exit(1);
655
- }
656
- const endpoint = options['endpoint'] ?? process.env['THREAT_CLOUD_ENDPOINT'] ?? 'https://cloud.panguard.ai';
657
- const apiKey = process.env['THREAT_CLOUD_API_KEY'];
658
- // Read raw YAML content for submission
659
- const ruleContent = readFileSync(targetPath, 'utf-8');
660
- // Generate pattern hash from rule ID
661
- const { createHash } = await import('node:crypto');
662
- const patternHash = createHash('sha256').update(rule.id).digest('hex').slice(0, 16);
663
- console.log(`\n${BOLD}ATR Rule Submission${RESET}`);
664
- console.log(`${DIM}${'─'.repeat(60)}${RESET}`);
665
- console.log(` Rule: ${rule.id} - ${rule.title}`);
666
- console.log(` Severity: ${SEVERITY_COLORS[rule.severity] ?? ''}${rule.severity}${RESET}`);
667
- console.log(` Category: ${rule.tags?.category ?? 'unknown'}`);
668
- console.log(` Endpoint: ${endpoint}`);
669
- console.log(`${DIM}${'─'.repeat(60)}${RESET}`);
670
- try {
671
- const headers = { 'Content-Type': 'application/json' };
672
- if (apiKey) {
673
- headers['Authorization'] = `Bearer ${apiKey}`;
674
- }
675
- const response = await fetch(`${endpoint}/api/atr-proposals`, {
676
- method: 'POST',
677
- headers,
678
- body: JSON.stringify({
679
- patternHash,
680
- ruleContent,
681
- llmProvider: 'human',
682
- llmModel: 'manual-submission',
683
- selfReviewVerdict: JSON.stringify({ verdict: 'approved', source: 'author' }),
684
- }),
685
- signal: AbortSignal.timeout(10_000),
686
- });
687
- const result = (await response.json());
688
- if (result.ok) {
689
- console.log(`\n${GREEN}Submitted successfully.${RESET}`);
690
- console.log(`${DIM}Your rule will go through community consensus voting.${RESET}`);
691
- console.log(`${DIM}Check status: atr submit --status ${patternHash}${RESET}\n`);
692
- }
693
- else {
694
- console.error(`\n${RED}Submission failed: ${result.error ?? 'Unknown error'}${RESET}\n`);
695
- process.exit(1);
696
- }
697
- }
698
- catch (err) {
699
- const msg = err instanceof Error ? err.message : String(err);
700
- console.error(`\n${RED}Failed to connect to Threat Cloud: ${msg}${RESET}`);
701
- console.error(`${DIM}Check your endpoint URL and network connection.${RESET}\n`);
702
- process.exit(1);
703
- }
704
- }
705
- // --- Main ---
706
- async function main() {
707
- const { command, target, options } = parseArgs(process.argv);
708
- if (command === 'help' || options['help']) {
709
- printUsage();
710
- return;
711
- }
712
- switch (command) {
713
- case 'scan':
714
- await cmdScan(target, options);
715
- break;
716
- case 'validate':
717
- cmdValidate(target, options);
718
- break;
719
- case 'test':
720
- await cmdTest(target, options);
721
- break;
722
- case 'stats':
723
- cmdStats(options);
724
- break;
725
- case 'mcp':
726
- await cmdMcp();
727
- break;
728
- case 'scaffold':
729
- await cmdScaffold();
730
- break;
731
- case 'submit':
732
- await cmdSubmit(target, options);
733
- break;
734
- default:
735
- console.error(`${RED}Unknown command: ${command}${RESET}`);
736
- printUsage();
737
- process.exit(1);
738
- }
739
- }
740
- main().catch((err) => {
741
- console.error(`${RED}Error: ${err instanceof Error ? err.message : String(err)}${RESET}`);
742
- process.exit(1);
743
- });
744
- //# sourceMappingURL=cli.js.map