@panguard-ai/atr 1.4.2 → 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 (200) 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/coverage-analyzer.d.ts +0 -43
  29. package/dist/coverage-analyzer.d.ts.map +0 -1
  30. package/dist/coverage-analyzer.js +0 -329
  31. package/dist/coverage-analyzer.js.map +0 -1
  32. package/dist/engine.d.ts +0 -136
  33. package/dist/engine.d.ts.map +0 -1
  34. package/dist/engine.js +0 -781
  35. package/dist/engine.js.map +0 -1
  36. package/dist/index.d.ts +0 -26
  37. package/dist/index.d.ts.map +0 -1
  38. package/dist/index.js +0 -18
  39. package/dist/index.js.map +0 -1
  40. package/dist/loader.d.ts +0 -21
  41. package/dist/loader.d.ts.map +0 -1
  42. package/dist/loader.js +0 -149
  43. package/dist/loader.js.map +0 -1
  44. package/dist/mcp-server.d.ts +0 -13
  45. package/dist/mcp-server.d.ts.map +0 -1
  46. package/dist/mcp-server.js +0 -244
  47. package/dist/mcp-server.js.map +0 -1
  48. package/dist/mcp-tools/coverage-gaps.d.ts +0 -13
  49. package/dist/mcp-tools/coverage-gaps.d.ts.map +0 -1
  50. package/dist/mcp-tools/coverage-gaps.js +0 -57
  51. package/dist/mcp-tools/coverage-gaps.js.map +0 -1
  52. package/dist/mcp-tools/list-rules.d.ts +0 -17
  53. package/dist/mcp-tools/list-rules.d.ts.map +0 -1
  54. package/dist/mcp-tools/list-rules.js +0 -45
  55. package/dist/mcp-tools/list-rules.js.map +0 -1
  56. package/dist/mcp-tools/scan.d.ts +0 -18
  57. package/dist/mcp-tools/scan.d.ts.map +0 -1
  58. package/dist/mcp-tools/scan.js +0 -87
  59. package/dist/mcp-tools/scan.js.map +0 -1
  60. package/dist/mcp-tools/submit-proposal.d.ts +0 -12
  61. package/dist/mcp-tools/submit-proposal.d.ts.map +0 -1
  62. package/dist/mcp-tools/submit-proposal.js +0 -116
  63. package/dist/mcp-tools/submit-proposal.js.map +0 -1
  64. package/dist/mcp-tools/threat-summary.d.ts +0 -12
  65. package/dist/mcp-tools/threat-summary.d.ts.map +0 -1
  66. package/dist/mcp-tools/threat-summary.js +0 -72
  67. package/dist/mcp-tools/threat-summary.js.map +0 -1
  68. package/dist/mcp-tools/validate.d.ts +0 -15
  69. package/dist/mcp-tools/validate.d.ts.map +0 -1
  70. package/dist/mcp-tools/validate.js +0 -57
  71. package/dist/mcp-tools/validate.js.map +0 -1
  72. package/dist/modules/index.d.ts +0 -144
  73. package/dist/modules/index.d.ts.map +0 -1
  74. package/dist/modules/index.js +0 -82
  75. package/dist/modules/index.js.map +0 -1
  76. package/dist/modules/semantic.d.ts +0 -105
  77. package/dist/modules/semantic.d.ts.map +0 -1
  78. package/dist/modules/semantic.js +0 -289
  79. package/dist/modules/semantic.js.map +0 -1
  80. package/dist/modules/session.d.ts +0 -70
  81. package/dist/modules/session.d.ts.map +0 -1
  82. package/dist/modules/session.js +0 -163
  83. package/dist/modules/session.js.map +0 -1
  84. package/dist/rule-scaffolder.d.ts +0 -39
  85. package/dist/rule-scaffolder.d.ts.map +0 -1
  86. package/dist/rule-scaffolder.js +0 -171
  87. package/dist/rule-scaffolder.js.map +0 -1
  88. package/dist/session-tracker.d.ts +0 -56
  89. package/dist/session-tracker.d.ts.map +0 -1
  90. package/dist/session-tracker.js +0 -175
  91. package/dist/session-tracker.js.map +0 -1
  92. package/dist/skill-fingerprint.d.ts +0 -96
  93. package/dist/skill-fingerprint.d.ts.map +0 -1
  94. package/dist/skill-fingerprint.js +0 -336
  95. package/dist/skill-fingerprint.js.map +0 -1
  96. package/dist/types.d.ts +0 -211
  97. package/dist/types.d.ts.map +0 -1
  98. package/dist/types.js +0 -6
  99. package/dist/types.js.map +0 -1
  100. package/rules/agent-manipulation/ATR-2026-00030-cross-agent-attack.yaml +0 -177
  101. package/rules/agent-manipulation/ATR-2026-00032-goal-hijacking.yaml +0 -137
  102. package/rules/agent-manipulation/ATR-2026-00074-cross-agent-privilege-escalation.yaml +0 -117
  103. package/rules/agent-manipulation/ATR-2026-00076-inter-agent-message-spoofing.yaml +0 -167
  104. package/rules/agent-manipulation/ATR-2026-00077-human-trust-exploitation.yaml +0 -146
  105. package/rules/agent-manipulation/ATR-2026-00108-consensus-sybil-attack.yaml +0 -105
  106. package/rules/agent-manipulation/ATR-2026-00116-a2a-message-validation.yaml +0 -92
  107. package/rules/agent-manipulation/ATR-2026-00117-agent-identity-spoofing.yaml +0 -92
  108. package/rules/agent-manipulation/ATR-2026-00118-approval-fatigue.yaml +0 -89
  109. package/rules/agent-manipulation/ATR-2026-00119-social-engineering-via-agent.yaml +0 -89
  110. package/rules/agent-manipulation/ATR-2026-00132-casual-authority-escalation.yaml +0 -99
  111. package/rules/agent-manipulation/ATR-2026-00139-casual-authority-redirect.yaml +0 -53
  112. package/rules/context-exfiltration/ATR-2026-00020-system-prompt-leak.yaml +0 -177
  113. package/rules/context-exfiltration/ATR-2026-00021-api-key-exposure.yaml +0 -178
  114. package/rules/context-exfiltration/ATR-2026-00075-agent-memory-manipulation.yaml +0 -117
  115. package/rules/context-exfiltration/ATR-2026-00102-disguised-analytics-exfiltration.yaml +0 -71
  116. package/rules/context-exfiltration/ATR-2026-00113-credential-theft.yaml +0 -89
  117. package/rules/context-exfiltration/ATR-2026-00114-oauth-token-abuse.yaml +0 -89
  118. package/rules/context-exfiltration/ATR-2026-00115-env-var-harvesting.yaml +0 -90
  119. package/rules/context-exfiltration/ATR-2026-00136-tool-response-data-piggyback.yaml +0 -100
  120. package/rules/context-exfiltration/ATR-2026-00141-example-format-key-leak.yaml +0 -52
  121. package/rules/context-exfiltration/ATR-2026-00142-piggyback-transition-words.yaml +0 -55
  122. package/rules/context-exfiltration/ATR-2026-00145-obfuscated-key-disclosure.yaml +0 -49
  123. package/rules/context-exfiltration/ATR-2026-00146-env-var-existence-probe.yaml +0 -49
  124. package/rules/data-poisoning/ATR-2026-00070-data-poisoning.yaml +0 -162
  125. package/rules/excessive-autonomy/ATR-2026-00050-runaway-agent-loop.yaml +0 -136
  126. package/rules/excessive-autonomy/ATR-2026-00051-resource-exhaustion.yaml +0 -139
  127. package/rules/excessive-autonomy/ATR-2026-00052-cascading-failure.yaml +0 -155
  128. package/rules/excessive-autonomy/ATR-2026-00098-unauthorized-financial-action.yaml +0 -157
  129. package/rules/excessive-autonomy/ATR-2026-00099-high-risk-tool-gate.yaml +0 -176
  130. package/rules/model-security/ATR-2026-00072-model-behavior-extraction.yaml +0 -117
  131. package/rules/model-security/ATR-2026-00073-malicious-finetuning-data.yaml +0 -110
  132. package/rules/privilege-escalation/ATR-2026-00040-privilege-escalation.yaml +0 -177
  133. package/rules/privilege-escalation/ATR-2026-00041-scope-creep.yaml +0 -126
  134. package/rules/privilege-escalation/ATR-2026-00107-delayed-execution-bypass.yaml +0 -69
  135. package/rules/privilege-escalation/ATR-2026-00110-eval-injection.yaml +0 -92
  136. package/rules/privilege-escalation/ATR-2026-00111-shell-escape.yaml +0 -93
  137. package/rules/privilege-escalation/ATR-2026-00112-dynamic-import-exploitation.yaml +0 -89
  138. package/rules/privilege-escalation/ATR-2026-00143-casual-privilege-escalation.yaml +0 -53
  139. package/rules/privilege-escalation/ATR-2026-00144-rationalized-safety-bypass.yaml +0 -49
  140. package/rules/prompt-injection/ATR-2026-00001-direct-prompt-injection.yaml +0 -563
  141. package/rules/prompt-injection/ATR-2026-00002-indirect-prompt-injection.yaml +0 -216
  142. package/rules/prompt-injection/ATR-2026-00003-jailbreak-attempt.yaml +0 -397
  143. package/rules/prompt-injection/ATR-2026-00004-system-prompt-override.yaml +0 -308
  144. package/rules/prompt-injection/ATR-2026-00005-multi-turn-injection.yaml +0 -183
  145. package/rules/prompt-injection/ATR-2026-00080-encoding-evasion.yaml +0 -88
  146. package/rules/prompt-injection/ATR-2026-00081-semantic-multi-turn.yaml +0 -85
  147. package/rules/prompt-injection/ATR-2026-00082-fingerprint-evasion.yaml +0 -84
  148. package/rules/prompt-injection/ATR-2026-00083-indirect-tool-injection.yaml +0 -87
  149. package/rules/prompt-injection/ATR-2026-00084-structured-data-injection.yaml +0 -86
  150. package/rules/prompt-injection/ATR-2026-00085-audit-evasion.yaml +0 -84
  151. package/rules/prompt-injection/ATR-2026-00086-visual-spoofing.yaml +0 -88
  152. package/rules/prompt-injection/ATR-2026-00087-rule-probing.yaml +0 -82
  153. package/rules/prompt-injection/ATR-2026-00088-adaptive-countermeasure.yaml +0 -84
  154. package/rules/prompt-injection/ATR-2026-00089-polymorphic-skill.yaml +0 -85
  155. package/rules/prompt-injection/ATR-2026-00090-threat-intel-exfil.yaml +0 -84
  156. package/rules/prompt-injection/ATR-2026-00091-nested-payload.yaml +0 -88
  157. package/rules/prompt-injection/ATR-2026-00092-consensus-poisoning.yaml +0 -92
  158. package/rules/prompt-injection/ATR-2026-00093-gradual-escalation.yaml +0 -86
  159. package/rules/prompt-injection/ATR-2026-00094-audit-bypass.yaml +0 -86
  160. package/rules/prompt-injection/ATR-2026-00097-cjk-injection-patterns.yaml +0 -339
  161. package/rules/prompt-injection/ATR-2026-00104-persona-hijacking.yaml +0 -74
  162. package/rules/prompt-injection/ATR-2026-00130-indirect-authority-claim.yaml +0 -97
  163. package/rules/prompt-injection/ATR-2026-00131-fictional-academic-framing.yaml +0 -93
  164. package/rules/prompt-injection/ATR-2026-00133-paraphrase-injection.yaml +0 -111
  165. package/rules/prompt-injection/ATR-2026-00137-authority-claim-injection.yaml +0 -52
  166. package/rules/prompt-injection/ATR-2026-00138-fictional-framing-bypass.yaml +0 -51
  167. package/rules/prompt-injection/ATR-2026-00140-indirect-reference-reversal.yaml +0 -52
  168. package/rules/prompt-injection/ATR-2026-00148-language-switch-injection.yaml +0 -71
  169. package/rules/skill-compromise/ATR-2026-00060-skill-impersonation.yaml +0 -155
  170. package/rules/skill-compromise/ATR-2026-00061-description-behavior-mismatch.yaml +0 -100
  171. package/rules/skill-compromise/ATR-2026-00062-hidden-capability.yaml +0 -98
  172. package/rules/skill-compromise/ATR-2026-00063-skill-chain-attack.yaml +0 -99
  173. package/rules/skill-compromise/ATR-2026-00064-over-permissioned-skill.yaml +0 -117
  174. package/rules/skill-compromise/ATR-2026-00065-skill-update-attack.yaml +0 -95
  175. package/rules/skill-compromise/ATR-2026-00066-parameter-injection.yaml +0 -108
  176. package/rules/skill-compromise/ATR-2026-00120-skill-instruction-injection.yaml +0 -121
  177. package/rules/skill-compromise/ATR-2026-00121-skill-dangerous-script.yaml +0 -165
  178. package/rules/skill-compromise/ATR-2026-00122-skill-weaponized-instruction.yaml +0 -114
  179. package/rules/skill-compromise/ATR-2026-00123-skill-overreach-permissions.yaml +0 -118
  180. package/rules/skill-compromise/ATR-2026-00124-skill-name-squatting.yaml +0 -98
  181. package/rules/skill-compromise/ATR-2026-00125-context-poisoning-compaction.yaml +0 -93
  182. package/rules/skill-compromise/ATR-2026-00126-skill-rug-pull-setup.yaml +0 -99
  183. package/rules/skill-compromise/ATR-2026-00127-subcommand-overflow.yaml +0 -74
  184. package/rules/skill-compromise/ATR-2026-00128-html-comment-hidden-payload.yaml +0 -79
  185. package/rules/skill-compromise/ATR-2026-00129-unicode-smuggling.yaml +0 -73
  186. package/rules/skill-compromise/ATR-2026-00134-fork-claim-impersonation.yaml +0 -86
  187. package/rules/skill-compromise/ATR-2026-00135-exfil-url-in-instructions.yaml +0 -82
  188. package/rules/skill-compromise/ATR-2026-00147-fork-impersonation.yaml +0 -48
  189. package/rules/tool-poisoning/ATR-2026-00010-mcp-malicious-response.yaml +0 -239
  190. package/rules/tool-poisoning/ATR-2026-00011-tool-output-injection.yaml +0 -196
  191. package/rules/tool-poisoning/ATR-2026-00012-unauthorized-tool-call.yaml +0 -201
  192. package/rules/tool-poisoning/ATR-2026-00013-tool-ssrf.yaml +0 -219
  193. package/rules/tool-poisoning/ATR-2026-00095-supply-chain-poisoning.yaml +0 -93
  194. package/rules/tool-poisoning/ATR-2026-00096-registry-poisoning.yaml +0 -95
  195. package/rules/tool-poisoning/ATR-2026-00100-consent-bypass-instruction.yaml +0 -82
  196. package/rules/tool-poisoning/ATR-2026-00101-trust-escalation-override.yaml +0 -68
  197. package/rules/tool-poisoning/ATR-2026-00103-hidden-safety-bypass-instruction.yaml +0 -73
  198. package/rules/tool-poisoning/ATR-2026-00105-silent-action-concealment.yaml +0 -69
  199. package/rules/tool-poisoning/ATR-2026-00106-schema-description-contradiction.yaml +0 -68
  200. 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