Tanuki

Operator Non-Human Identity & Hybrid Active Directory Operator for Linux Workloads
Protocol-first, zero root privileges, zero host configuration footprint, zero noise.

Overview • Quick Start • Dual-Engine Architecture • Empirical Validation • Tooling & Usage • Decision Ladder • Repository Architecture • Lineage & Credits

---

Overview

Modern cloud-native and on-premise environments increasingly run Linux workloads (Kubernetes pods, autonomous AI coding agents, CI/CD runners, containerized batch workers) that must authenticate to enterprise Active Directory domains without full domain join, Kerberos daemon daemons (sssd/winbind), or administrative root privileges.

Tanuki is an autonomous, protocol-first Active Directory operator designed specifically for unprivileged Linux userspace execution. It enforces complete Purple Team lifecycle parity: pre-flight triage, cryptographic ticket negotiation, quantitative privilege tiering, closed-loop self-healing, and forensic audit telemetry.

Core Architectural Invariants

• Living off the Domain (Zero Dependencies): The Python Reference Engine operates strictly on the Python 3.10+ standard library (socket, struct, ctypes, hashlib, ssl). Zero external pip packages are required.
• Strictly Unprivileged Execution (UID 1000): Runs entirely in userspace. Never requires sudo, root privileges, or CAP_SYS_TIME.
• Zero Host Mutation: Never modifies /etc/krb5.conf, system PAM, or root system files. Configuration context is isolated strictly to the calling process and local in-memory session.
• Dual-Engine Parity: Maintained across both an accessible Python reference engine and a standalone, ultra-low latency Rust systems core (<0.96 ms execution, 1.8 MB statically linked musl binary).
• In-Memory Clock Skew Self-Healing: Automatically calculates and compensates for KDC time drift up to 420+ seconds directly in memory without modifying workstation system clocks.
• Quantitative Blast Radius Engine: Evaluates identity blast radius (0-100 score), classifies accounts into Active Directory tiers (Tier 0 / Tier 1 / Tier 2), and outputs deterministic PowerShell mitigation recipes for directory administrators.
• Cryptographic Zero-Trace Memory Purge: Implements NIST SP 800-88 cryptographic multi-pass zeroization across process memory, credential caches, and session artifacts.

---

Quick Start

1-Line Universal Install

# Automated installer (detects Rust musl binary or falls back to Python standard engine)
curl -sSfL https://raw.githubusercontent.com/Mafifrizi/tanuki/main/install.sh | bash

Manual Installation

Via Cargo (Rust Systems Core)

cargo install --path crates/tanuki-cli

Via Pipx or Pip (Python Reference Engine)

pipx install git+https://github.com/Mafifrizi/tanuki.git
# or
pip install --user .

Zero-Install Direct Execution

git clone https://github.com/Mafifrizi/tanuki.git
cd tanuki
python3 -m tanuki doctor --json

---

Dual-Engine Architecture

Tanuki is architected with strict behavioral parity between two production-grade implementations:

Feature / Metric	Python 3.10+ Reference Engine	Rust Systems Core (tanuki-cli)
Primary Focus	Auditable reference, zero pip dependencies	Ultra-low latency, standalone security operations
Binary / Packaging	Pure standard library (tanuki/)	1.8 MB static musl binary (crates/tanuki-cli/)
Execution Latency	~42.0 ms (CPython VM startup)	0.76 ms (Sub-millisecond native execution)
Memory Footprint	~14.2 MB RSS	~1.1 MB RSS
Host Requirements	Python 3.10+ runtime	Zero dependencies (Standalone static ELF)
Test Verification	502 unit tests passing (100% green)	20 integration tests passing (100% green)

---

Empirical Validation

Tanuki is empirically validated across a live hybrid infrastructure connecting an unprivileged Kali Linux workstation (192.168.56.105, UID 1000) directly to an Active Directory Domain Controller running Windows Server 2022 (192.168.56.106, DC01.lab.local).

Milestone 1: Pre-Flight Environment Diagnostic & Opsec Sensor Probe

Autonomous health audit inspecting DNS resolution, KDC reachability, keytab validity, clock drift, and local endpoint telemetry hooks.

Milestone 2: RFC 4120 Binary Keytab Inspection & Enctype Auditing

In-line parser dissecting raw keytab binary structures, extracting principal entries, Kerberos enctypes (AES-256 vs RC4), and Key Version Numbers (KVNO).

Milestone 3: Native Userspace TGT Acquisition & Clock Drift Tolerance

Direct userspace AS-REQ negotiation establishing Kerberos TGT without root permissions and dynamically healing workstation-KDC clock skew.

Milestone 4: Quantitative Blast Radius & Identity Privilege Tiering

Calculates blast radius impact (0-100 score), classifies account privileges (Tier 0/1/2), audits accessible SPNs, and generates deterministic Active Directory mitigation cmdlets.

Milestone 5: Closed-Loop Blue Team Forensic Telemetry on DC01

Forensic verification inspecting Windows Server 2022 Security Event Viewer, proving live ticket requests attributed to 192.168.56.105 with modern AES-256 (0x12).