feat: v0.3.2 - HeuristicMode enum and custom patterns dict support

BREAKING CHANGE: Replace flag_suspicious parameter with heuristics: HeuristicMode

This release adds fine-grained control over heuristic detection behavior with
three modes (DISABLED, FLAG, REDACT) and enables custom patterns from dict.

Added:
- HeuristicMode enum (DISABLED/FLAG/REDACT) for controlling heuristic behavior
- hash_sensitive_value() method for category-aware hashing
- Custom patterns from dict support (no temp files needed)
- 22 new tests for HeuristicMode functionality

Changed:
- BREAKING: Replace flag_suspicious bool with heuristics: HeuristicMode
- Custom patterns now applied first (precedence over generic patterns)
- Account ID and heuristics skip already-redacted values

Fixed:
- Custom patterns were loaded but never applied
- Account ID pattern re-hashing custom-redacted values
- Heuristics re-detecting values with multi-underscore prefixes

Closes #17

Author: kwschulz

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,29 +1,31 @@
----
-name: Bug report
-about: Report a bug in har-capture
-title: ''
-labels: bug
-assignees: ''
----
+______________________________________________________________________
+
+## name: Bug report about: Report a bug in har-capture title: '' labels: bug assignees: ''
 
 ## Description
+
 A clear description of the bug.
 
 ## Steps to Reproduce
+
+1.
+1.
 1.
-2.
-3.
 
 ## Expected Behavior
+
 What you expected to happen.
 
 ## Actual Behavior
+
 What actually happened.
 
 ## Environment
+
 - har-capture version:
 - Python version:
 - OS:
 
 ## Additional Context
+
 Any other context, error messages, or screenshots.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,19 +1,19 @@
----
-name: Feature request
-about: Suggest a new feature or enhancement
-title: ''
-labels: enhancement
-assignees: ''
----
+______________________________________________________________________
+
+## name: Feature request about: Suggest a new feature or enhancement title: '' labels: enhancement assignees: ''
 
 ## Problem Statement
+
 What problem does this feature solve?
 
 ## Proposed Solution
+
 How would you like this to work?
 
 ## Alternatives Considered
+
 Any alternative solutions or workarounds you've considered.
 
 ## Additional Context
+
 Any other context, examples, or mockups.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,18 +1,23 @@
 ## Summary
+
 Brief description of changes.
 
 ## Changes
+
 -
 
 ## Testing
+
 - [ ] Tests pass locally (`pytest`)
 - [ ] Linting passes (`ruff check .`)
 - [ ] Type checking passes (`mypy src/`)
 
 ## Related Issues
+
 Related to #
 
 ## Checklist
+
 - [ ] Code follows project style guidelines
 - [ ] Self-review completed
 - [ ] Documentation updated (if applicable)

CHANGELOG.md

@@ -7,6 +7,79 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-02-06
+
+### Added
+
+- **HeuristicMode Enum** - Fine-grained control over heuristic behavior with three modes:
+  - `DISABLED` (default) - Skip heuristics, only redact known patterns (safe, backward compatible)
+  - `FLAG` - Flag suspicious values for manual review (interactive mode)
+  - `REDACT` - Auto-redact suspicious values (automated workflows)
+- **Custom Patterns from Dict** - `custom_patterns` now accepts dict or file path
+  - Enables passing patterns directly from modem.yaml or other configs
+  - No need to write temporary files for API integration
+- **Category-Aware Hashing** - New `hash_sensitive_value()` method for heuristically-detected values
+  - Generates prefixed hashes: `WIFI_xxxxx`, `CRED_xxxxx`, `DEVICE_xxxxx`
+  - Preserves correlation while indicating detection category
+
+### Changed
+
+- **BREAKING**: Replaced `flag_suspicious` boolean with `heuristics: HeuristicMode` parameter
+  - Old: `sanitize_har(data, flag_suspicious=True)`
+  - New: `sanitize_har(data, heuristics=HeuristicMode.FLAG)`
+  - Affects: `sanitize_html()`, `sanitize_har()`, `sanitize_har_file()`, CLI, browser capture
+- **Custom Pattern Precedence** - Custom patterns now applied first, preventing generic patterns from overriding them
+- **Already-Redacted Protection** - Account ID and heuristic patterns skip already-redacted values (e.g., `MODEM_SN_xxxxx`)
+
+### Fixed
+
+- **Custom Patterns Not Applied** - Custom patterns were loaded but never applied during sanitization
+- **Pattern Re-Redaction** - Account ID pattern no longer re-hashes custom-redacted values
+- **Multi-Underscore Prefixes** - Heuristics now correctly skip prefixes with underscores (e.g., `MODEM_SN_`)
+
+### Migration Guide
+
+**For API Users:**
+
+```python
+# Before (v0.3.1)
+from har_capture.sanitization.har import sanitize_har_file
+sanitize_har_file(path, flag_suspicious=True)
+
+# After (v0.3.2)
+from har_capture.sanitization.har import sanitize_har_file
+from har_capture.sanitization.report import HeuristicMode
+
+# Interactive mode (manual review)
+sanitize_har_file(path, heuristics=HeuristicMode.FLAG)
+
+# Automated mode (auto-redact, may over-redact)
+sanitize_har_file(path, heuristics=HeuristicMode.REDACT)
+
+# Safe mode (default, only known patterns)
+sanitize_har_file(path, heuristics=HeuristicMode.DISABLED)
+# or simply: sanitize_har_file(path)
+```
+
+**For cable_modem_monitor Integration:**
+
+```python
+# Pass custom patterns as dict
+modem_patterns = {
+    "patterns": {
+        "modem_serial": {
+            "regex": r"SN[0-9]{10}",
+            "replacement_prefix": "MODEM_SN"
+        }
+    }
+}
+sanitize_har_file(
+    path,
+    heuristics=HeuristicMode.REDACT,
+    custom_patterns=modem_patterns  # Dict instead of file path
+)
+```
+
 ## [0.3.1] - 2026-02-04
 
 ### Fixed
@@ -26,7 +99,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Improved Instructions** - Clearer checkbox prompts ("Enter when done", pre-selected items noted)
 - **Better UX** - Simplified keybindings (A/N for all/none work now), removed redundant Ctrl+C mention
 
-## \[0.3.0\] - 2026-02-04
+## [0.3.0] - 2026-02-04
 
 ### Added
 
@@ -210,4 +283,7 @@ har-capture sanitize input.har --patterns custom-allowlist.json
 [0.2.3]: https://github.com/solentlabs/har-capture/compare/v0.2.2...v0.2.3
 [0.2.4]: https://github.com/solentlabs/har-capture/compare/v0.2.3...v0.2.4
 [0.2.5]: https://github.com/solentlabs/har-capture/compare/v0.2.4...v0.2.5
-[unreleased]: https://github.com/solentlabs/har-capture/compare/v0.2.5...HEAD
+[0.3.0]: https://github.com/solentlabs/har-capture/compare/v0.2.5...v0.3.0
+[0.3.1]: https://github.com/solentlabs/har-capture/compare/v0.3.0...v0.3.1
+[0.3.2]: https://github.com/solentlabs/har-capture/compare/v0.3.1...v0.3.2
+[unreleased]: https://github.com/solentlabs/har-capture/compare/v0.3.2...HEAD

README.md

@@ -141,6 +141,7 @@ pip install har-capture[full]
 
 ```python
 from har_capture.sanitization import sanitize_html, sanitize_har
+from har_capture.sanitization.report import HeuristicMode
 
 # Sanitize HTML (correlation-preserving by default)
 clean_html = sanitize_html(raw_html)
@@ -151,9 +152,26 @@ clean_html = sanitize_html(raw_html, salt="my-secret-key")
 # Use static placeholders (legacy mode)
 clean_html = sanitize_html(raw_html, salt=None)
 
+# Enable heuristic detection for WiFi credentials, SSIDs, device names
+# DISABLED (default): Only redact known patterns
+# FLAG: Flag suspicious values for manual review
+# REDACT: Auto-redact suspicious values (may over-redact)
+clean_html = sanitize_html(raw_html, heuristics=HeuristicMode.REDACT)
+
 # Sanitize HAR file
 from har_capture.sanitization import sanitize_har_file
 sanitize_har_file("capture.har")  # Creates capture.sanitized.har
+
+# Pass custom patterns as dict (e.g., from modem.yaml)
+custom_patterns = {
+    "patterns": {
+        "modem_serial": {
+            "regex": r"SN[0-9]{10}",
+            "replacement_prefix": "MODEM_SN"
+        }
+    }
+}
+sanitize_har_file("capture.har", custom_patterns=custom_patterns)
 ```
 
 ### CLI

SECURITY.md

@@ -7,6 +7,7 @@ If you discover a security vulnerability in har-capture, please report it privat
 **[Report a vulnerability](https://github.com/solentlabs/har-capture/security/advisories/new)**
 
 Please include:
+
 - Description of the vulnerability
 - Steps to reproduce
 - Potential impact
@@ -21,6 +22,7 @@ Please include:
 ## Scope
 
 This policy covers:
+
 - PII leakage in sanitization (patterns missing sensitive data)
 - Credential exposure in HAR files
 - Code injection via malicious HAR input

docs/RESEARCH.md

@@ -14,18 +14,18 @@
 
 ### Alternative Tools Evaluated
 
-| Project | Language | Type | Notes |
-|---------|----------|------|-------|
-| [Google har-sanitizer](https://github.com/google/har-sanitizer) | Python/JS | Web UI + REST API | No CLI, needs tests |
-| [Cloudflare har-sanitizer](https://blog.cloudflare.com/introducing-har-sanitizer-secure-har-sharing/) | JS | Web UI | JWT-focused |
-| [Edgio/har-tools](https://github.com/Edgio/har-tools) | JS | Web UI | Drag-drop interface |
-| [AbregaInc/har-cleaner](https://github.com/AbregaInc/har-cleaner) | TypeScript | Library | Jira integration |
-| [jfromaniello/har-sanitizer](https://github.com/jfromaniello/har-sanitizer) | JS | Library | Basic sanitization |
+| Project                                                                                               | Language   | Type              | Notes               |
+| ----------------------------------------------------------------------------------------------------- | ---------- | ----------------- | ------------------- |
+| [Google har-sanitizer](https://github.com/google/har-sanitizer)                                       | Python/JS  | Web UI + REST API | No CLI, needs tests |
+| [Cloudflare har-sanitizer](https://blog.cloudflare.com/introducing-har-sanitizer-secure-har-sharing/) | JS         | Web UI            | JWT-focused         |
+| [Edgio/har-tools](https://github.com/Edgio/har-tools)                                                 | JS         | Web UI            | Drag-drop interface |
+| [AbregaInc/har-cleaner](https://github.com/AbregaInc/har-cleaner)                                     | TypeScript | Library           | Jira integration    |
+| [jfromaniello/har-sanitizer](https://github.com/jfromaniello/har-sanitizer)                           | JS         | Library           | Basic sanitization  |
 
 ### Related Projects
 
-| Project | Purpose |
-|---------|---------|
+| Project                                                                                                                | Purpose                         |
+| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
 | [GSMA TSG Diagnostic Interface](https://github.com/GSMATerminals/TSG-IoT-devices-Standard-Diagnostic-Interface-Public) | Modem logging for Cat-M1/NB-IoT |
-| [NYU IoT Inspector](https://github.com/nyu-mlab/iot-inspector-client) | Smart home traffic analysis |
-| [IoTShark](https://github.com/sahilmgandhi/IotShark) | IoT traffic monitoring |
+| [NYU IoT Inspector](https://github.com/nyu-mlab/iot-inspector-client)                                                  | Smart home traffic analysis     |
+| [IoTShark](https://github.com/sahilmgandhi/IotShark)                                                                   | IoT traffic monitoring          |

src/har_capture/capture/browser.py

@@ -27,6 +27,7 @@
     install_browser_deps,
 )
 from har_capture.patterns import get_bloat_extensions
+from har_capture.sanitization.report import HeuristicMode
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -436,7 +437,7 @@ def _cleanup_temp() -> None:
             _, sanitization_report = sanitize_har_file(
                 str(temp_path),
                 str(sanitized_output),
-                flag_suspicious=interactive,
+                heuristics=HeuristicMode.FLAG if interactive else HeuristicMode.DISABLED,
             )
             result.sanitized_path = sanitized_output
             result.sanitization_report = sanitization_report

src/har_capture/cli/sanitize.py

@@ -11,6 +11,7 @@
 import typer
 
 from har_capture.patterns import PatternLoadError
+from har_capture.sanitization.report import HeuristicMode
 
 
 def sanitize(
@@ -163,16 +164,17 @@ def sanitize(
             else:
                 typer.echo("  (Non-interactive mode: proceeding anyway)")
 
-        # Enable flag_suspicious when interactive mode is requested (even without TTY)
-        flag_suspicious = run_heuristics
+        # Determine heuristics mode
+        # Interactive mode enables heuristics for flagging suspicious values
+        heuristics = HeuristicMode.FLAG if run_heuristics else HeuristicMode.DISABLED
 
         result_path, sanitization_report = sanitize_har_file(
             str(input_file),
             output_path,
             salt=effective_salt,
             custom_patterns=custom_patterns,
             max_size=max_size_bytes,
-            flag_suspicious=flag_suspicious,
+            heuristics=heuristics,
         )
 
         # Interactive review mode (requires TTY)

src/har_capture/patterns/README.md

@@ -4,12 +4,12 @@ This directory contains JSON configuration files for PII detection, sanitization
 
 ## Files
 
-| File | Purpose |
-|------|---------|
-| `pii.json` | PII detection patterns (MAC, IP, email, etc.) |
-| `sensitive.json` | Sensitive headers and form field patterns |
+| File             | Purpose                                          |
+| ---------------- | ------------------------------------------------ |
+| `pii.json`       | PII detection patterns (MAC, IP, email, etc.)    |
+| `sensitive.json` | Sensitive headers and form field patterns        |
 | `allowlist.json` | Patterns for recognizing already-redacted values |
-| `capture.json` | File extensions to filter during capture |
+| `capture.json`   | File extensions to filter during capture         |
 
 ## File Schemas
 
@@ -32,6 +32,7 @@ Defines regex patterns for detecting PII in content.
 ```
 
 **Fields:**
+
 - `regex`: Python regex pattern
 - `replacement_prefix`: Prefix for hashed replacement (e.g., `MAC` → `02:xx:xx:xx:xx:xx`)
 - `flags`: Optional list of regex flags (`IGNORECASE`, `MULTILINE`, `DOTALL`)
@@ -57,6 +58,7 @@ Defines sensitive HTTP headers and form fields to redact.
 ```
 
 **Fields:**
+
 - `headers.full_redact`: Headers to completely redact
 - `headers.cookie_redact`: Headers where cookie values are redacted but names preserved
 - `fields.patterns`: Regex patterns matching sensitive form field names
@@ -84,6 +86,7 @@ Defines patterns for recognizing already-redacted values (to avoid double-flaggi
 ```
 
 **Fields:**
+
 - `static_placeholders.values`: Exact values produced when `salt=None`
 - `format_preserving_patterns`: Regex patterns for RFC-reserved ranges
 - `hash_prefixes.values`: Prefixes for non-format-preserving hashes (`PREFIX_xxxxxxxx`)
@@ -104,6 +107,7 @@ Defines file extensions to filter during HAR capture.
 ```
 
 **Fields:**
+
 - Categories can be selectively included via CLI flags (`--include-fonts`, etc.)
 
 ## Custom Patterns
@@ -177,8 +181,8 @@ sanitize_har(har_data, custom_patterns="your_project/patterns/modem.json")
 To add patterns to the core library:
 
 1. Patterns should be **universally applicable** (not domain-specific)
-2. Include a clear `description` for each pattern
-3. Test patterns don't cause false positives on common data
-4. Submit a PR with examples of what the pattern matches
+1. Include a clear `description` for each pattern
+1. Test patterns don't cause false positives on common data
+1. Submit a PR with examples of what the pattern matches
 
 For vendor or domain-specific patterns, maintain them in your own project and pass via `custom_patterns`.