diff --git a/CHANGELOG.md b/CHANGELOG.md index ad94076..d0c0d66 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,23 @@ # Changelog --- +## [2.9.2] - 2026-04-30 + +### Added +- Small HTML Docstring with project info + +### Changed +- **CSV Formula Injection Mitigation**: Cells starting with formula characters are now prefixed with a tab character (\t) and wrapped in double quotes instead of just the single quote prefix that was used previously + +## [2.9.1] - 2026-02-28 + +### Added +- **Function index generator**: Added `scripts/generate-function-index.py` to auto-generate `docs/FUNCTION_INDEX.generated.md` from runtime source function declarations. +- **Generated function inventory**: Added `docs/FUNCTION_INDEX.generated.md` as a machine-generated reference for maintainers. + +### Changed +- **Updated Documentation**: `DOCUMENTATION.md` has been simplified & updated to v2.9.0. +- **Documentation cross-linking**: Added references to curated and generated function indexes in `README.md` and `DOCUMENTATION.md`. +- **Release regeneration workflow**: `scripts/regenerate-release.sh` now regenerates `docs/FUNCTION_INDEX.generated.md` before rebuilding `release/` artifacts. ## [2.9.0] - 2026-02-22 @@ -815,7 +833,7 @@ handleDrop(event, phaseKey) // Performs assignment --- -## Development Notes for AI Agents +## Development Notes ### File Structure Understanding ``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3419966..219e8bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,6 +26,11 @@ Contributions are welcome. Please read the following guidelines before submittin - Follow existing code style and naming conventions - Keep functions focused and well-documented - Test drag-and-drop, import/export, and metadata editing +- Keep docs in sync with shipped behavior: + - Update `CHANGELOG.md` for user-visible and security-relevant changes + - Update `README.md` when setup, usage, or feature surface changes + - Update `DOCUMENTATION.md` for architecture/runtime behavior changes + - Update `docs/FUNCTION_INDEX.md` and regenerate `docs/FUNCTION_INDEX.generated.md` when function surfaces change ## Data Updates diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 81a16fb..0192cf8 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -1,8 +1,8 @@ # AttackFlow — Monolithic API Reference -> **Version:** 2.7.0 -> **Scope:** Documents the current inline JavaScript implementation in `index.html` and the companion `config.js` + `stix-config.js`. -> **Purpose:** Serve as the definitive reference for the v3.0 modular refactoring (see `DETACH.md`). +> **Version:** 2.9.0 +> **Scope:** Documents the current inline JavaScript implementation in `index.html` and companion `config.js` + `stix-config.js` (plus embedded iframe IPC surface used by `explorer.html` and `stix-builder.html`). +> **Purpose:** Definitive implementation reference for ongoing hardening and v3 modularization planning. --- @@ -10,1587 +10,560 @@ 1. [Architecture Overview](#1-architecture-overview) 2. [File Map](#2-file-map) -3. [config.js — Configuration & Theme Engine](#3-configjs--configuration--theme-engine) -4. [stix-config.js — STIX 2.1 Object Definitions](#4-stix-configjs--stix-21-object-definitions) -5. [Inline JS Sections (index.html)](#5-inline-js-sections-indexhtml) - - 5.1 [VERSION](#51-version) - - 5.2 [INPUT SECURITY](#52-input-security) - - 5.3 [METADATA HELPERS](#53-metadata-helpers) - - 5.4 [TYPE MAPPING CONSTANTS](#54-type-mapping-constants) - - 5.5 [ASSIGNMENT & PHASE LOGIC](#55-assignment--phase-logic) - - 5.6 [GROUP MANAGEMENT](#56-group-management) - - 5.7 [CONSTANTS & STATE](#57-constants--state) - - 5.8 [DATA LOADING](#58-data-loading) - - 5.9 [NAVIGATOR IMPORT](#59-navigator-import) - - 5.10 [VIEW & LAYER CONTROLS](#510-view--layer-controls) - - 5.11 [THEME RUNTIME](#511-theme-runtime) - - 5.12 [COMPACT MODE](#512-compact-mode) - - 5.13 [TAB & FILTER CONTROLS](#513-tab--filter-controls) - - 5.14 [ENTITY LIST RENDERING](#514-entity-list-rendering) - - 5.15 [STIX ITEM MANAGEMENT](#515-stix-item-management) - - 5.16 [STIX EDITOR MODAL](#516-stix-editor-modal) - - 5.17 [SELECTION & DETAIL PANEL](#517-selection--detail-panel) - - 5.18 [DRAG & DROP](#518-drag--drop) - - 5.19 [KILL CHAIN RENDERING](#519-kill-chain-rendering) - - 5.20 [RELATIONSHIP VIEW](#520-relationship-view) - - 5.21 [STATS & UTILITIES](#521-stats--utilities) - - 5.22 [EXPORT (JSON / CSV / STIX Bundle)](#522-export-json--csv--stix-bundle) - - 5.23 [IMPORT (Kill Chain)](#523-import-kill-chain) - - 5.24 [DROPDOWN UTILS](#524-dropdown-utils) - - 5.25 [METADATA EDITOR](#525-metadata-editor) - - 5.26 [MODALS (Usage Guide / Changelog)](#526-modals-usage-guide--changelog) - - 5.27 [TOAST NOTIFICATIONS](#527-toast-notifications) - - 5.28 [INITIALIZATION](#528-initialization) -6. [Data Types & Shapes](#6-data-types--shapes) -7. [Global Event Listeners](#7-global-event-listeners) +3. [What Changed Since v2.7.0](#3-what-changed-since-v270) +4. [config.js — Configuration & Theme Engine](#4-configjs--configuration--theme-engine) +5. [stix-config.js — STIX 2.1 Object Definitions](#5-stix-configjs--stix-21-object-definitions) +6. [Inline JS Sections (index.html)](#6-inline-js-sections-indexhtml) + - 6.1 [VERSION + INPUT SECURITY](#61-version--input-security) + - 6.2 [METADATA + TYPE MAPPING + ASSIGNMENT/GROUP LOGIC](#62-metadata--type-mapping--assignmentgroup-logic) + - 6.3 [STATE + PHASE MODEL + CORE HELPERS](#63-state--phase-model--core-helpers) + - 6.4 [DATA LOADING (SHARED CACHE + OFFLINE MODE)](#64-data-loading-shared-cache--offline-mode) + - 6.5 [LOCAL IFRAME IPC BRIDGE](#65-local-iframe-ipc-bridge) + - 6.6 [NAVIGATOR / TECHNIQUE IMPORTS](#66-navigator--technique-imports) + - 6.7 [VIEWS + THEME + COMPACT + COMMENTS](#67-views--theme--compact--comments) + - 6.8 [GLOBAL SEARCH + TAB/FILTER CONTROLS](#68-global-search--tabfilter-controls) + - 6.9 [ENTITY LIST, STIX LIBRARY, STIX EDITOR](#69-entity-list-stix-library-stix-editor) + - 6.10 [DETAIL VIEWS, DND, KILL CHAIN, RELATIONSHIPS](#610-detail-views-dnd-kill-chain-relationships) + - 6.11 [PHASE DETAILS MODAL + STATS](#611-phase-details-modal--stats) + - 6.12 [EXPORT / IMPORT (JSON, CSV, STIX)](#612-export--import-json-csv-stix) + - 6.13 [METADATA EDITOR + MODALS + INIT](#613-metadata-editor--modals--init) +7. [Data Types & Shapes](#7-data-types--shapes) 8. [Security Model](#8-security-model) -9. [Module Mapping (Current → v3.0)](#9-module-mapping-current--v30) +9. [Global Event Listeners](#9-global-event-listeners) +10. [Module Mapping (Current → v3.0)](#10-module-mapping-current--v30) --- ## 1. Architecture Overview -AttackFlow is a **single-page application** with all JavaScript inlined inside `index.html` (≈ 4,800 lines, starting at line ~2625). Two companion scripts — `config.js` and `stix-config.js` — are loaded via ` │ -│ │ -│ Static resources/ (6 JSON files) │ -│ Static frameworks/ (ATTCK JSON, CAPEC/CWE XML) │ -└────────────────────────────────────────────────────────┘ -``` - -**Key characteristics:** - -- All state is held in a single mutable `state` object. -- All DOM manipulation uses `innerHTML` string building and direct `classList` toggling. -- Security is enforced by a front-loaded `InputSecurity` object and event-level input guards. -- Drag & drop uses HTML5 native API with a global `dragData` object. -- Persistence is limited to `localStorage` for theme mode and compact mode. -- STIX 2.1 SDO types and field definitions are externalized in `stix-config.js` (19 types, 20+ vocabularies). -- Four entity types are supported: ATT&CK techniques, CAPEC patterns, CWE weaknesses, and STIX objects. +- No bundler, no module system, global-scope runtime. +- Mutable app state lives in a single `state` object. +- Rendering is template-string + `innerHTML` driven, protected by strict sanitization and validator guards. +- Companion scripts: + - `config.js` (theme/config/import behavior/debug toggles) + - `stix-config.js` (STIX SDO schemas + vocabularies + helpers) +- Embedded views: + - `explorer.html` + - `stix-builder.html` +- Local `file://` mode supports a hardened MessageChannel-based iframe bridge and shared-data broadcast path. --- ## 2. File Map -| File | Role | Lines | -|------|------|-------| -| `config.js` | CONFIG object, `resolveTheme()`, `applyConfigColors()` | 254 | -| `stix-config.js` | STIX 2.1 SDO definitions, vocabularies, helpers | 576 | -| `index.html` | HTML structure (1–~2624), CSS (embedded), inline JS (~2625–7415) | 7,415 | -| `resources/attack-techniques.json` | ATT&CK technique library | Fetched at runtime | -| `resources/capec-full.json` | CAPEC pattern library | Fetched at runtime | -| `resources/cwe-full.json` | CWE weakness library | Fetched at runtime | -| `resources/technique-to-capec.json` | ATT&CK → CAPEC mapping | Fetched at runtime | -| `resources/capec-to-technique.json` | CAPEC → ATT&CK mapping | Fetched at runtime | -| `resources/cwe-to-capec.json` | CWE → CAPEC mapping | Fetched at runtime | -| `resources/Nav_Layer_*.json` | ATT&CK Navigator layers (ENTERPRISE, ICS, MOBILE) | Loaded on demand | -| `examples/stix-demo.json` | Full-featured STIX demo (all 19 SDO types) | Example | -| `examples/Operation-Midnight-Eclipse-stix-bundle.json` | Exported STIX 2.1 bundle (25 SDOs + 18 SROs) | Example | +| File | Role | +|------|------| +| `index.html` | Main UI, CSS, and inline runtime (monolith, ~10.5k lines total) | +| `config.js` | App config, theme presets, feature flags, IPC debug/rate/bootstrap tuning | +| `stix-config.js` | STIX common fields, vocabularies, 19 SDO type definitions, helper APIs | +| `explorer.html` | Relationship Explorer iframe view | +| `stix-builder.html` | STIX Composer iframe view (theme + local IPC aware) | +| `resources/*.json` | Generated runtime datasets (ATT&CK/CAPEC/CWE + mappings + Navigator layers) | --- -## 3. config.js — Configuration & Theme Engine - -**Source:** `config.js` (254 lines) - -### 3.1 `CONFIG` Object - -Top-level configuration constant. Properties: - -| Property | Type | Description | -|----------|------|-------------| -| `version` | `string` | Application version (`'2.7.0'`) | -| `changelogUrl` | `string` | Path to CHANGELOG.md | -| `sources.capec` | `{domains, mechanisms}` | Paths to CAPEC XML source files | -| `sources.cwe` | `{hardware, software, all}` | Paths to CWE XML source files | -| `sources.attack` | `{version, enterprise, mobile, ics}` | ATT&CK STIX bundle paths & version | -| `sanitize.paths` | `string[]` | Glob patterns for JSON sanitization | -| `stixTypes` | `Array<{value, label}>` | 19 STIX 2.1 SDO type definitions for UI dropdowns | -| `phases` | `{in, through, out}` | Hex colors for kill chain super-phases | -| `frameworks` | `{attack, capec, cwe}` | Hex colors for framework entity types | -| `ui` | `object` | UI fallback colors (bg, text, border, accent) | -| `metaIcons` | `object` | Metadata icon colors (CVE, observable, link, comment, confidence) | -| `themes` | `{dark: {default: ...}, light: {default: ...}}` | Theme presets with ui + metaIcons overrides | -| `themeDefaults` | `{mode, scheme}` | Default theme mode (`'light'`) and scheme (`'default'`) | -| `themeMode` | `string` | Initial mode: `'light'`, `'dark'`, or `'auto'` | -| `display` | `object` | Max lengths for names, descriptions, mitigations, references, custom items, kill chain description | -| `navigation` | `{confirmOnLeave}` | Whether to show leave-site confirmation | - -#### `CONFIG.stixTypes` - -19 entries mapping STIX 2.1 SDO type names to human-readable labels: - -`attack-pattern`, `campaign`, `course-of-action`, `grouping`, `identity`, `indicator`, `infrastructure`, `intrusion-set`, `location`, `malware`, `malware-analysis`, `note`, `observed-data`, `opinion`, `report`, `threat-actor`, `tool`, `vulnerability`, `x-custom`. - -Used by `populateStixTypeDropdown()` and `VALID_STIX_TYPES` to constrain type selection. - -### 3.2 Functions +## 3. What Changed Since v2.7.0 -#### `resolveTheme(mode?, scheme?) → ThemeObject` +Major additions reflected in v2.9.0 runtime: -**Line:** config.js:187 -Merges the selected theme scheme's overrides with global CONFIG defaults. - -| Param | Type | Default | Description | -|-------|------|---------|-------------| -| `mode` | `string` | `CONFIG.themeDefaults.mode` | `'light'` or `'dark'` | -| `scheme` | `string` | `CONFIG.themeDefaults.scheme` | Scheme name within the mode | - -**Returns:** `{ phases, frameworks, ui, metaIcons }` — fully resolved theme. - -#### `applyConfigColors(theme?) → void` - -**Line:** config.js:198 -Sets CSS custom properties on `document.documentElement` from the resolved theme. - -| Param | Type | Default | Description | -|-------|------|---------|-------------| -| `theme` | `ThemeObject` | `resolveTheme()` | Pre-resolved theme, or auto-resolves | - -**Side effects:** Sets 20+ CSS custom properties (e.g. `--phase-in`, `--attack-color`, `--bg-dark`, `--meta-cve-bg`). +1. **Local iframe IPC hardening** + - Channel-only bootstrap (`AF_IPC_PORT_INIT`) with per-frame nonce binding. + - Allowlisted message types and payload keys. + - Request rate-limiting (token bucket) and bounded bootstrap retry/backoff. +2. **Shared dataset runtime cache** + - `window.getAttackFlowSharedData()` snapshot API with deep-frozen payload. + - Dataset shape + count + byte-size enforcement before cross-frame sharing. +3. **Offline `file://` data path** + - Local folder/file selector flow for required `resources/*.json` files. + - Graceful bypass path if user continues without data. +4. **Prototype pollution defenses expanded** + - `DANGEROUS_OBJECT_KEYS`, safe reviver parsing (`parseJsonSafe`), null-prototype object creation. +5. **UI/runtime features** + - Global search subsystem with ranking and sticky/expanded modes. + - Kill-chain comment visibility controls (`showComments`, toggles). + - Rich phase details modal with averages/CVE rollups/mitigation aggregation. + - Optional STIX Builder navigation toggle (`CONFIG.navigation.showStixBuilder`). +6. **STIX export evolution** + - Deterministic UUIDv5 IDs for ATT&CK techniques and mitigations in STIX bundle export. --- -## 4. stix-config.js — STIX 2.1 Object Definitions - -**Source:** `stix-config.js` (576 lines) - -Externalizes all STIX 2.1 specification knowledge. Loaded via `