ferret-scan 2.1.2 → 2.3.0

package/dist/__tests__/atlasCatalog.test.js

@@ -0,0 +1,200 @@
+/**
+ * MITRE ATLAS Catalog Loader Tests
+ * Tests for parsing the STIX bundle and loadMitreAtlasTechniqueCatalog.
+ */
+jest.mock('node:fs');
+import * as fs from 'node:fs';
+import { parseMitreAtlasStixBundle, loadMitreAtlasTechniqueCatalog, } from '../mitre/atlasCatalog.js';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const mockFs = fs;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeStixBundle(techniques = []) {
+    return {
+        type: 'bundle',
+        id: 'bundle--test',
+        objects: techniques,
+    };
+}
+function makeAttackPattern(id, name, tactics = ['execution']) {
+    return {
+        type: 'attack-pattern',
+        name,
+        external_references: [
+            {
+                source_name: 'mitre-atlas',
+                external_id: id,
+                url: `https://atlas.mitre.org/techniques/${id}`,
+            },
+        ],
+        kill_chain_phases: tactics.map(t => ({ kill_chain_name: 'mitre-atlas', phase_name: t })),
+    };
+}
+function makeConfig(overrides = {}) {
+    return {
+        enabled: true,
+        sourceUrl: 'https://example.com/stix-atlas.json',
+        cachePath: '/tmp/test-atlas-cache.json',
+        cacheTtlHours: 24,
+        autoUpdate: false,
+        forceRefresh: false,
+        timeoutMs: 5000,
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// parseMitreAtlasStixBundle
+// ---------------------------------------------------------------------------
+describe('parseMitreAtlasStixBundle', () => {
+    it('returns empty object for null input', () => {
+        const result = parseMitreAtlasStixBundle(null);
+        expect(result).toEqual({});
+    });
+    it('returns empty object for non-object input', () => {
+        expect(parseMitreAtlasStixBundle('string')).toEqual({});
+        expect(parseMitreAtlasStixBundle(42)).toEqual({});
+    });
+    it('returns empty object when objects field is missing', () => {
+        expect(parseMitreAtlasStixBundle({})).toEqual({});
+    });
+    it('returns empty object when objects is not an array', () => {
+        expect(parseMitreAtlasStixBundle({ objects: 'not-array' })).toEqual({});
+    });
+    it('parses a valid STIX bundle with one technique', () => {
+        const bundle = makeStixBundle([makeAttackPattern('AML.T0051', 'LLM Prompt Injection')]);
+        const result = parseMitreAtlasStixBundle(bundle);
+        expect(result['AML.T0051']).toBeDefined();
+        expect(result['AML.T0051'].name).toBe('LLM Prompt Injection');
+        expect(result['AML.T0051'].tactics).toContain('execution');
+    });
+    it('parses multiple techniques', () => {
+        const bundle = makeStixBundle([
+            makeAttackPattern('AML.T0051', 'LLM Prompt Injection', ['execution']),
+            makeAttackPattern('AML.T0054', 'LLM Jailbreak', ['privilege-escalation']),
+        ]);
+        const result = parseMitreAtlasStixBundle(bundle);
+        expect(Object.keys(result)).toHaveLength(2);
+        expect(result['AML.T0054'].tactics).toContain('privilege-escalation');
+    });
+    it('skips objects that are not attack-patterns', () => {
+        const bundle = makeStixBundle([
+            { type: 'identity', name: 'MITRE' },
+            makeAttackPattern('AML.T0051', 'LLM Prompt Injection'),
+        ]);
+        const result = parseMitreAtlasStixBundle(bundle);
+        expect(Object.keys(result)).toHaveLength(1);
+    });
+    it('skips objects with invalid ID format', () => {
+        const bundle = makeStixBundle([
+            {
+                type: 'attack-pattern',
+                name: 'Invalid',
+                external_references: [
+                    { source_name: 'mitre-atlas', external_id: 'INVALID-ID' },
+                ],
+                kill_chain_phases: [],
+            },
+        ]);
+        const result = parseMitreAtlasStixBundle(bundle);
+        expect(Object.keys(result)).toHaveLength(0);
+    });
+    it('deduplicates tactics', () => {
+        const bundle = makeStixBundle([
+            {
+                type: 'attack-pattern',
+                name: 'Multi Tactic',
+                external_references: [
+                    { source_name: 'mitre-atlas', external_id: 'AML.T0053', url: 'https://atlas.mitre.org/techniques/AML.T0053' },
+                ],
+                kill_chain_phases: [
+                    { kill_chain_name: 'mitre-atlas', phase_name: 'execution' },
+                    { kill_chain_name: 'mitre-atlas', phase_name: 'execution' },
+                    { kill_chain_name: 'mitre-atlas', phase_name: 'privilege-escalation' },
+                ],
+            },
+        ]);
+        const result = parseMitreAtlasStixBundle(bundle);
+        const tactics = result['AML.T0053'].tactics;
+        expect(tactics).toHaveLength(2);
+        expect(new Set(tactics).size).toBe(2);
+    });
+    it('uses fallback URL when not provided in external reference', () => {
+        const bundle = makeStixBundle([
+            {
+                type: 'attack-pattern',
+                name: 'No URL',
+                external_references: [
+                    { source_name: 'mitre-atlas', external_id: 'AML.T0055' },
+                ],
+                kill_chain_phases: [],
+            },
+        ]);
+        const result = parseMitreAtlasStixBundle(bundle);
+        expect(result['AML.T0055'].url).toContain('AML.T0055');
+    });
+    it('handles subtechnique IDs (AML.T####.###)', () => {
+        const bundle = makeStixBundle([
+            makeAttackPattern('AML.T0011.002', 'Poisoned AI Agent Tool'),
+        ]);
+        const result = parseMitreAtlasStixBundle(bundle);
+        expect(result['AML.T0011.002']).toBeDefined();
+    });
+    it('handles array elements that are null or non-object gracefully', () => {
+        const bundle = { objects: [null, undefined, 42, makeAttackPattern('AML.T0051', 'LLM Prompt Injection')] };
+        const result = parseMitreAtlasStixBundle(bundle);
+        expect(result['AML.T0051']).toBeDefined();
+    });
+});
+// ---------------------------------------------------------------------------
+// loadMitreAtlasTechniqueCatalog
+// ---------------------------------------------------------------------------
+describe('loadMitreAtlasTechniqueCatalog', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    it('returns null when catalog is disabled', async () => {
+        const config = makeConfig({ enabled: false });
+        const result = await loadMitreAtlasTechniqueCatalog(config);
+        expect(result).toBeNull();
+    });
+    it('returns techniques from a fresh cache', async () => {
+        const bundle = makeStixBundle([makeAttackPattern('AML.T0051', 'LLM Prompt Injection')]);
+        mockFs.existsSync.mockReturnValue(true);
+        mockFs.statSync.mockReturnValue({ mtimeMs: Date.now() }); // fresh
+        mockFs.readFileSync.mockReturnValue(JSON.stringify(bundle));
+        const config = makeConfig();
+        const result = await loadMitreAtlasTechniqueCatalog(config);
+        expect(result).not.toBeNull();
+        expect(result['AML.T0051']).toBeDefined();
+    });
+    it('returns null when cache is stale and autoUpdate is false and no refresh', async () => {
+        const bundle = makeStixBundle([makeAttackPattern('AML.T0051', 'LLM Prompt Injection')]);
+        mockFs.existsSync.mockReturnValue(true);
+        // stale: modified 48 hours ago
+        mockFs.statSync.mockReturnValue({ mtimeMs: Date.now() - 48 * 60 * 60 * 1000 });
+        mockFs.readFileSync.mockReturnValue(JSON.stringify(bundle));
+        const config = makeConfig({ autoUpdate: false, forceRefresh: false });
+        // Cache is stale so cacheFresh = false, autoUpdate = false, won't refresh
+        // Falls back to stale cache
+        const result = await loadMitreAtlasTechniqueCatalog(config);
+        // stale cache is read as fallback
+        expect(result).not.toBeNull();
+    });
+    it('returns null when cache does not exist and autoUpdate is false', async () => {
+        mockFs.existsSync.mockReturnValue(false);
+        const config = makeConfig({ autoUpdate: false, forceRefresh: false });
+        const result = await loadMitreAtlasTechniqueCatalog(config);
+        expect(result).toBeNull();
+    });
+    it('returns null when parsed bundle produces empty techniques from fresh cache', async () => {
+        mockFs.existsSync.mockReturnValue(true);
+        mockFs.statSync.mockReturnValue({ mtimeMs: Date.now() });
+        mockFs.readFileSync.mockReturnValue(JSON.stringify({ objects: [] })); // no techniques
+        const config = makeConfig({ autoUpdate: false });
+        const result = await loadMitreAtlasTechniqueCatalog(config);
+        // empty techniques from cache, no autoUpdate, falls through to null
+        expect(result).toBeNull();
+    });
+});
+//# sourceMappingURL=atlasCatalog.test.js.map

package/dist/__tests__/atlasCatalogExtra.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MITRE ATLAS Catalog Extra Tests
+ * Tests for parseMitreAtlasStixBundle and loadMitreAtlasTechniqueCatalog
+ */
+export {};
+//# sourceMappingURL=atlasCatalogExtra.test.d.ts.map

package/dist/__tests__/atlasCatalogExtra.test.js

@@ -0,0 +1,215 @@
+/**
+ * MITRE ATLAS Catalog Extra Tests
+ * Tests for parseMitreAtlasStixBundle and loadMitreAtlasTechniqueCatalog
+ */
+import { parseMitreAtlasStixBundle, loadMitreAtlasTechniqueCatalog } from '../mitre/atlasCatalog.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+function makeConfig(overrides = {}) {
+    return {
+        enabled: true,
+        autoUpdate: false,
+        sourceUrl: 'https://example.com/stix-atlas.json',
+        cachePath: '/tmp/nonexistent-cache.json',
+        cacheTtlHours: 24,
+        timeoutMs: 5000,
+        forceRefresh: false,
+        ...overrides,
+    };
+}
+function makeStixBundle(techniques) {
+    return {
+        type: 'bundle',
+        objects: techniques.map(t => ({
+            type: 'attack-pattern',
+            name: t.name ?? 'Test Technique',
+            external_references: [
+                {
+                    source_name: 'mitre-atlas',
+                    external_id: t.externalId ?? 'AML.T0001',
+                    url: t.url ?? `https://atlas.mitre.org/techniques/${t.externalId ?? 'AML.T0001'}`,
+                },
+            ],
+            kill_chain_phases: (t.tactics ?? ['ml-attack-staging']).map(phase => ({
+                kill_chain_name: 'mitre-atlas',
+                phase_name: phase,
+            })),
+        })),
+    };
+}
+describe('parseMitreAtlasStixBundle', () => {
+    it('returns empty object for null input', () => {
+        expect(parseMitreAtlasStixBundle(null)).toEqual({});
+    });
+    it('returns empty object for non-object input', () => {
+        expect(parseMitreAtlasStixBundle('string')).toEqual({});
+        expect(parseMitreAtlasStixBundle(42)).toEqual({});
+    });
+    it('returns empty object for bundle with no objects', () => {
+        expect(parseMitreAtlasStixBundle({ type: 'bundle' })).toEqual({});
+    });
+    it('returns empty object for bundle with non-array objects', () => {
+        expect(parseMitreAtlasStixBundle({ objects: 'not an array' })).toEqual({});
+    });
+    it('parses a single technique', () => {
+        const bundle = makeStixBundle([{ externalId: 'AML.T0001', name: 'Technique 1', tactics: ['initial-access'] }]);
+        const result = parseMitreAtlasStixBundle(bundle);
+        expect(Object.keys(result)).toHaveLength(1);
+        expect(result['AML.T0001']).toBeDefined();
+        expect(result['AML.T0001']?.name).toBe('Technique 1');
+        expect(result['AML.T0001']?.id).toBe('AML.T0001');
+        expect(result['AML.T0001']?.tactics).toContain('initial-access');
+    });
+    it('parses multiple techniques', () => {
+        const bundle = makeStixBundle([
+            { externalId: 'AML.T0001', name: 'T1' },
+            { externalId: 'AML.T0002', name: 'T2' },
+            { externalId: 'AML.T0001.001', name: 'T1.1' },
+        ]);
+        const result = parseMitreAtlasStixBundle(bundle);
+        expect(Object.keys(result)).toHaveLength(3);
+    });
+    it('skips non-attack-pattern objects', () => {
+        const bundle = {
+            objects: [
+                { type: 'identity', name: 'ATLAS' },
+                { type: 'attack-pattern', name: 'Tech', external_references: [{ source_name: 'mitre-atlas', external_id: 'AML.T0001' }] },
+            ],
+        };
+        const result = parseMitreAtlasStixBundle(bundle);
+        expect(Object.keys(result)).toHaveLength(1);
+    });
+    it('skips objects with invalid AML IDs', () => {
+        const bundle = {
+            objects: [
+                {
+                    type: 'attack-pattern',
+                    name: 'Invalid',
+                    external_references: [{ source_name: 'mitre-atlas', external_id: 'INVALID-ID' }],
+                },
+                {
+                    type: 'attack-pattern',
+                    name: 'No ATLAS ref',
+                    external_references: [{ source_name: 'other', external_id: 'AML.T0001' }],
+                },
+            ],
+        };
+        const result = parseMitreAtlasStixBundle(bundle);
+        expect(Object.keys(result)).toHaveLength(0);
+    });
+    it('uses external_references URL when available', () => {
+        const bundle = makeStixBundle([{ externalId: 'AML.T0001', url: 'https://atlas.mitre.org/techniques/AML.T0001' }]);
+        const result = parseMitreAtlasStixBundle(bundle);
+        expect(result['AML.T0001']?.url).toBe('https://atlas.mitre.org/techniques/AML.T0001');
+    });
+    it('generates URL when not in external_references', () => {
+        const bundle = {
+            objects: [{
+                    type: 'attack-pattern',
+                    name: 'No URL Technique',
+                    external_references: [{ source_name: 'mitre-atlas', external_id: 'AML.T0099' }],
+                }],
+        };
+        const result = parseMitreAtlasStixBundle(bundle);
+        expect(result['AML.T0099']?.url).toContain('AML.T0099');
+    });
+    it('deduplicates tactics', () => {
+        const bundle = {
+            objects: [{
+                    type: 'attack-pattern',
+                    name: 'Multi Tactic',
+                    external_references: [{ source_name: 'mitre-atlas', external_id: 'AML.T0001' }],
+                    kill_chain_phases: [
+                        { phase_name: 'initial-access' },
+                        { phase_name: 'initial-access' }, // duplicate
+                        { phase_name: 'execution' },
+                    ],
+                }],
+        };
+        const result = parseMitreAtlasStixBundle(bundle);
+        expect(result['AML.T0001']?.tactics).toHaveLength(2);
+    });
+    it('handles null/non-object entries in objects array', () => {
+        const bundle = {
+            objects: [
+                null,
+                'string',
+                42,
+                {
+                    type: 'attack-pattern',
+                    name: 'Valid',
+                    external_references: [{ source_name: 'mitre-atlas', external_id: 'AML.T0001' }],
+                },
+            ],
+        };
+        const result = parseMitreAtlasStixBundle(bundle);
+        expect(Object.keys(result)).toHaveLength(1);
+    });
+});
+describe('loadMitreAtlasTechniqueCatalog', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ferret-atlas-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('returns null when disabled', async () => {
+        const result = await loadMitreAtlasTechniqueCatalog(makeConfig({ enabled: false }));
+        expect(result).toBeNull();
+    });
+    it('loads from fresh cache', async () => {
+        const cachePath = path.join(tmpDir, 'atlas-cache.json');
+        const bundle = makeStixBundle([{ externalId: 'AML.T0001', name: 'Cached Technique' }]);
+        fs.writeFileSync(cachePath, JSON.stringify(bundle));
+        const result = await loadMitreAtlasTechniqueCatalog(makeConfig({
+            cachePath,
+            cacheTtlHours: 168,
+            forceRefresh: false,
+        }));
+        expect(result).not.toBeNull();
+        expect(result?.['AML.T0001']?.name).toBe('Cached Technique');
+    });
+    it('returns null when no cache and no autoUpdate', async () => {
+        const cachePath = path.join(tmpDir, 'nonexistent-cache.json');
+        const result = await loadMitreAtlasTechniqueCatalog(makeConfig({
+            cachePath,
+            autoUpdate: false,
+            forceRefresh: false,
+        }));
+        expect(result).toBeNull();
+    });
+    it('fetches and caches when autoUpdate=true and no cache', async () => {
+        const bundle = makeStixBundle([{ externalId: 'AML.T0001', name: 'Fetched Technique' }]);
+        globalThis.fetch = jest.fn().mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve(bundle),
+        });
+        const cachePath = path.join(tmpDir, 'new-cache.json');
+        const result = await loadMitreAtlasTechniqueCatalog(makeConfig({
+            cachePath,
+            autoUpdate: true,
+            forceRefresh: false,
+        }));
+        expect(result).not.toBeNull();
+        expect(result?.['AML.T0001']?.name).toBe('Fetched Technique');
+        expect(fs.existsSync(cachePath)).toBe(true);
+    });
+    it('falls back to stale cache when fetch fails', async () => {
+        const cachePath = path.join(tmpDir, 'stale-cache.json');
+        const bundle = makeStixBundle([{ externalId: 'AML.T0001', name: 'Stale Technique' }]);
+        fs.writeFileSync(cachePath, JSON.stringify(bundle));
+        globalThis.fetch = jest.fn().mockRejectedValue(new Error('Network error'));
+        const result = await loadMitreAtlasTechniqueCatalog(makeConfig({
+            cachePath,
+            cacheTtlHours: 0, // Stale cache
+            autoUpdate: true,
+            forceRefresh: false,
+        }));
+        // Should fall back to stale cache
+        expect(result).not.toBeNull();
+        expect(result?.['AML.T0001']?.name).toBe('Stale Technique');
+    });
+});
+//# sourceMappingURL=atlasCatalogExtra.test.js.map

package/dist/__tests__/baseline.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Baseline Tests
+ * Tests for baseline management: create, add, remove, filter, validate, stats.
+ */
+export {};
+//# sourceMappingURL=baseline.test.d.ts.map