Deterministic, offline, map-based anonymization of IT infrastructure data in text files.

logmask is a Python CLI tool designed for MSP operational security. When engineers need to paste logs, configs, or transcripts into external tools — Claude, vendor support portals, community forums — they need to strip infrastructure identifiers first. logmask scans files for those identifiers, builds a persistent translation map, and performs single-pass replacement using an Aho-Corasick automaton. The tool is bidirectional: anonymize out, reveal back.

MSP engineers routinely share diagnostic data with third parties. Every log file, every config export, every support ticket risks leaking internal infrastructure topology — IP ranges, hostnames, domain names, user principal names, Active Directory SIDs. Manual redaction is slow, inconsistent, and error-prone.

logmask treats anonymization as a deterministic mapping problem rather than a search-and-destroy exercise. A persistent CSV map links each real identifier to a fake replacement. The same input with the same map always produces byte-identical output. Maps are human-readable and auditable — engineers can open them in Excel, hand-edit entries, and share them across teams.

The replacement engine uses an Aho-Corasick automaton for single-pass, longest-match-wins substitution. This means overlapping identifiers (a hostname embedded in a FQDN, a subnet containing individual IPs) are handled correctly without multiple passes or ordering dependencies.

The tool processes text files with comprehensive identifier detection across eight pattern types. The core replacement engine is correct and deterministic — known issues are documented in AGENTS.md and marked inline in source.

Five modules, no framework. Parsers are internal callables in a dictionary registry.

Translation maps are CSV files with two scope levels that merge at runtime:

Project map overrides global map on original_value key collision. Merge happens at runtime load, never mutates either source file.

logmask/
├── 📂 assets/                      # Repository images
├── 📂 docs/                        # Documentation
│   └── logmask-buidl-spec-v1.md    # Authoritative build specification
├── 📂 src/logmask/                 # Source (PEP 621 src layout)
│   ├── cli.py                      # argparse CLI — 6 commands
│   ├── scanner.py                  # Discovery engine
│   ├── map_engine.py               # CSV map CRUD, scope merge, fake generation
│   ├── replacer.py                 # Aho-Corasick automaton + single-pass replace
│   ├── models.py                   # Frozen dataclasses (data contracts)
│   └── 📂 parsers/                 # Detection registry
│       ├── ipv4.py                 # RFC1918 private IPs
│       ├── cidr.py                 # Subnet/CIDR notation
│       ├── hostname.py             # NetBIOS + FQDN (structural heuristics)
│       ├── identity.py             # UPNs, Entra GUIDs, Windows SIDs
│       └── network.py              # MAC addresses, UNC paths
├── 📂 tests/                       # Unit tests
│   ├── conftest.py                 # Synthetic log fixtures
│   ├── test_parsers.py
│   ├── test_map_engine.py
│   ├── test_replacer.py
│   └── test_roundtrip.py           # Anonymize → reveal → hash compare
├── AGENTS.md                       # Agent context (KiloCode, Claude Code)
├── CLAUDE.md                       # Claude Code context
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE                         # MIT (code)
├── LICENSE-DATA                    # CC BY 4.0 (documentation, data)
├── SECURITY.md
├── pyproject.toml                  # PEP 621 project config
└── README.md

• Python 3.10 or higher
• pip (no admin elevation required)
• Windows 10/11 (primary target) or any OS with Python 3.10+

# Clone the repository
git clone https://github.com/radioastronomyio/logmask.git
cd logmask

# Install in development mode
pip install -e ".[dev]"

All dependencies have pre-built Windows wheels on PyPI — no compiler toolchain required:

# Initialize a project (creates .logmask/ with empty map)
logmask init --client "Acme Corp"

# Scan files for infrastructure identifiers
logmask scan ./logs --ext .log .txt .json

# Anonymize — replace real values with fakes
logmask anonymize ./logs --out ./anonymized_logs

# Reveal — reverse the anonymization
logmask reveal ./anonymized_logs --out ./revealed_logs

# Inspect the translation map
logmask map show --scope project

# Run all tests
pytest

# Run with coverage
pytest --cov=src/logmask

# Run specific test file
pytest tests/test_parsers.py

Code is licensed under the MIT License — see LICENSE for details.

Documentation and non-code content is licensed under CC BY 4.0 — see LICENSE-DATA for details.

• pyahocorasick — Efficient multi-pattern matching
• Anthropic — Claude and the agent ecosystem that motivated this tool

Last Updated: 2026-03-01 | v0.1.0 Alpha | Core Build Complete