tanuki

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.png"> <img src="assets/logo.png" alt="Tanuki Logo" width="220"> </picture> </p> <h1 align="center">Tanuki</h1> <p align="center"> <em>Linux Active Directory triage for AI coding agents. Protocol-first, zero noise.</em> </p> <p align="center"> <img src="https://img.shields.io/badge/version-1.2.1-blue.svg" alt="Version 1.2.1"> <img src="https://img.shields.io/badge/rust-1.75+-dea584.svg" alt="Rust 1.75+"> <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+"> <img src="https://img.shields.io/badge/dependencies-zero-success.svg" alt="Zero Dependencies"> <img src="https://img.shields.io/badge/standards-RFC_4120-orange.svg" alt="RFC 4120"> <img src="https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg" alt="License: MIT OR Apache-2.0"> <a href="https://youtu.be/wqZRYmEn0eY"><img src="https://img.shields.io/badge/demo-YouTube-red.svg?logo=youtube&logoColor=white" alt="Demo Video"></a> </p> <p align="center"> <a href="#quick-start">Quick Start</a> &bull; <a href="#dual-engine-architecture">Dual-Engine Architecture</a> &bull; <a href="#live-lab-empirical-validation">Live Lab Validation</a> &bull; <a href="https://youtu.be/wqZRYmEn0eY">Demo Video</a> &bull; <a href="#the-decision-ladder">Decision Ladder</a> &bull; <a href="#before--after">Before & After</a> &bull; <a href="#tooling--usage">Tooling & Usage</a> &bull; <a href="#agent-setup">Agent Setup</a> &bull; <a href="#lineage--credits">Lineage & Credits</a> </p>

---

Quick Start (1-Line Universal Install)

Tanuki is 100% plug-and-play. One command installs the unified CLI and configures AI Agent Skills for Claude Code, Cursor, and Google Antigravity:

Linux & macOS

curl -sSL https://raw.githubusercontent.com/Mafifrizi/tanuki/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/Mafifrizi/tanuki/main/install.ps1 | iex

Via Pipx / Pip / Cargo

# Pipx (Isolated CLI environment)
pipx install git+https://github.com/Mafifrizi/tanuki.git

# Local repository install
pip install .

# Note for Linux (Kali, Debian, Ubuntu): If ~/.local/bin is not in your PATH:
export PATH="$HOME/.local/bin:$PATH"

# Rust binary install
cargo install --path crates/tanuki-cli

Verify your installation:

# Direct CLI binary or universal Python module
tanuki --version
python3 -m tanuki --version

tanuki doctor
tanuki ladder
tanuki triage KRB_AP_ERR_SKEW

Dual-Engine Architecture

Tanuki ships two complementary implementations:

1. Rust Systems Core (crates/tanuki-cli): The primary high-performance engine for operator workstations, CI/CD security validation pipelines, and standalone deployment. It compiles into a single static binary with #![forbid(unsafe_code)], zero external dependencies, and execution times under 2 milliseconds.
2. Python Fallback Engine (scripts/): A zero-dependency script suite using only the Python standard library (struct, io, sys). It operates directly on remote target systems where dropping compiled binaries is prohibited or monitored by endpoint detection.

Both engines share an identical JSON schema and parsing specification.

---

Live Lab Empirical Validation

All protocol parsers, diagnostics, and CLI workflows are empirically validated across live virtualized lab environments:

• Active Directory Domain Controller: Windows Server 2022 (DC01.lab.local, IP: 192.168.56.106)
• Operator Workstation: Kali Linux 2024 (kraii@kraiiandreyy, IP: 192.168.56.105)

Full-Stack End-to-End Walkthrough (Live Lab Validation)

📺 Watch Demo Video: youtu.be/wqZRYmEn0eY - Full-stack operational walkthrough across live domain infrastructure.

Visual verification of the complete 3-act operational lifecycle across live domain infrastructure:

| Act | Environment | Objectives & Validated Primitives | | :--- | :--- | :--- | | Act 1: Domain Controller Setup | Windows Server 2022 (DC01) | Domain discovery (nltest), SPN audit (setspn), and RFC 4120 AES-256 binary keytab export (ktpass, KVNO 9). | | Act 2: Unprivileged Linux Operator | Kali Linux 2024 (Naga) | Passive diagnostic (tanuki doctor), RFC 4120 tree audit (tanuki keytab), zero-root config synthesis (tanuki config), native ctypes TGT acquisition (tanuki auth), ticket health pass (tanuki doctor), and protocol triage (tanuki triage). | | Act 3: Closed-Loop Verification | Windows Server 2022 (DC01) | Domain Controller Security Event ID 4768 Audit Success for tanuki-nhi originating from client IP 192.168.56.105. |

Act 1: Domain Controller Service Setup & Keytab Provisioning (DC01)

Official RFC 4120 binary keytab export on the Domain Controller for service account LAB\tanuki-nhi with modern AES-256 (aes256-cts-hmac-sha1-96, KVNO 9):

<p align="center"> <img src="assets/lab-validation-act1-dc01-setup.png" alt="Act 1: Windows Server DC01 Setup and ktpass Export" width="850"> </p>

Act 2: Unprivileged Linux Operator Session & Health Validation (Naga)

1. Pre-Flight Health Diagnostic Baseline (tanuki doctor)

Passive, zero-packet pre-flight health diagnostic executing in 0.96 ms, accurately detecting unconfigured state, missing keytabs, and inactive ticket caches:

<p align="center"> <img src="assets/lab-validation-act2-naga-doctor-unconfigured.png" alt="Act 2.1: Pre-Flight Doctor Baseline" width="850"> </p>

2. RFC 4120 Keytab Ingestion & Tree Audit (tanuki keytab)

Parses binary keytab structures, extracts AES-256 principals, displays hierarchical principal trees, verifies KVNO 9, and provides automated kinit guidance:

<p align="center"> <img src="assets/lab-validation-act2-naga-keytab-tree.png" alt="Act 2.2: RFC 4120 Keytab Tree Hierarchy" width="850"> </p>

3. Zero-DNS Kerberos Configuration Generator (tanuki config)

Generates a local Kerberos configuration file (/tmp/lab_krb5.conf) enforcing RFC 4120 § 6.1 uppercase realm conventions, zero-DNS direct KDC IP routing, and hypervisor clock-skew tolerance:

<p align="center"> <img src="assets/lab-validation-act2-naga-config.png" alt="Act 2.3: Zero-DNS Configuration Generator" width="850"> </p>

4. Unprivileged Native TGT Acquisition (tanuki auth)

Acquires a Kerberos Ticket Granting Ticket (TGT) directly from the Domain Controller using Python standard library ctypes (libkrb5.so.3) without requiring root privileges, kinit binary on PATH, or external dependencies:

<p align="center"> <img src="assets/lab-validation-act2-naga-auth-live.png" alt="Act 2.4: Unprivileged TGT Acquisition via ctypes" width="850"> </p>

5. Post-Authentication Health Diagnostic Pass (tanuki doctor)

Confirms active AES-256 Kerberos ticket cache with 9h 59m 49s remaining lifetime, executing in 1.35 ms with zero network emission:

<p align="center"> <img src="assets/lab-validation-act2-naga-doctor-pass.png" alt="Act 2.5: Post-Auth Doctor Pass with AES-256 Session" width="850"> </p>

6. Kerberos Protocol Error Triage & Blue Telemetry Coupling (tanuki triage)

Couples tactical remediation commands with Blue Team detection telemetry (Auditd watch rules, Windows Event IDs 4768/4771, Sigma rules, and Falco signatures):

<p align="center"> <img src="assets/lab-validation-act2-naga-triage.png" alt="Act 2.6: Protocol Error Triage and Telemetry" width="850"> </p>

Act 3: Closed-Loop Domain Controller Telemetry Verification (DC01)

Native high-efficiency log query via wevtutil on the Domain Controller proving live Event ID 4768 Audit Success for account tanuki-nhi originating from 192.168.56.105 with Ticket Encryption Type 0x12 (aes256-cts-hmac-sha1-96):

<p align="center"> <img src="assets/lab-validation-act3-dc01-event4768.png" alt="Act 3: Windows Event ID 4768 Audit Success Verification" width="850"> </p>

---

The Decision Ladder

Before proposing any triage command or query, Tanuki follows a 5-level operational ladder:

Level 5  [ Deterministic Output ]  --> [Target] -> [Exact Command] -> [Artifact]
   ▲
Level 4  [ Targeted Vectors    ]  --> ADCS ESC templates, RBCD, Shadow Credentials
   ▲
Level 3  [ Machine Identity    ]  --> Leverage host keytabs and service principals (LotD)
   ▲
Level 2  [ OPSEC Guardrails    ]  --> Enforce AES-256; strictly ban RC4 and password spraying
   ▲
Level 1  [ Local Passive First ]  --> Triage /etc/krb5.keytab & SSSD KCM before network packets

1. Local Passive First: Inspect local files (/etc/krb5.keytab, /etc/sssd/sssd.conf, KCM stores) before sending packets over the wire.
2. OPSEC Guardrails: Enforce AES-256 (aes256-cts-hmac-sha1-96). Strictly forbid RC4 downgrade attacks and account spraying.
3. Machine Identity (Living off the Domain): Validate host keytabs and managed identities before requesting human user credentials.
4. Targeted Vectors: Focus triage on specific certificate templates (ADCS), resource-based delegation, and Kerberos error codes.
5. Deterministic Output: Return exact CLI invocations, target endpoints, and expected artifacts instead of general explanations.

---

Before & After

| Scenario | Generic Coding Agent | With Tanuki | | :--- | :--- | :--- | | Service LDAP Query Fails | Proposes ldapsearch -x -D "admin@corp" -W asking operator for cleartext credentials. | Inspects local keytab, acquires machine ticket via AES-256, and issues ldapsearch -Y GSSAPI with existing credentials. | | Kerberos Error Handling | Recommends editing /etc/krb5.conf to add allow_weak_crypto = true. | Diagnoses specific Kerberos error code (KDC_ERR_ETYPE_NOSUPP or clock skew) and fixes encryption types without weakening security. | | Ticket Cache Extraction | Searches only for /tmp/krb5cc_%{uid}, reports no tickets found when SSSD KCM is active. | Parses /var/lib/sss/secrets/secrets.ldb directly to extract active CCACHE v4 streams. |

---

Tooling & Usage

1. Rust Systems Core (crates/tanuki-cli)

Build the standalone binary:

cargo build --release --manifest-path crates/tanuki-cli/Cargo.toml

Run proactive pre-flight health diagnostics (<5ms, zero network packets):

tanuki doctor runs deterministic, zero-network pre-flight diagnostics across local Active Directory components in under 5 milliseconds:

• Keytab permissions and format: Audits /etc/krb5.keytab permissions (flags world-readable 0644/0666 permissions vs secure 0600) and validates RFC 4120 binary header magic (0x0502).
• Realm capitalization: Audits /etc/krb5.conf for lowercase realm declarations across [libdefaults] and [realms], honoring KRB5_CONFIG environment variable precedence.
• SSSD daemon and socket status: Validates /var/lib/sss/pipes/kcm socket presence and /var/run/sssd.pid daemon state.
• Ticket cache lifetimes: Evaluates remaining ticket validity across MIT CCACHE v4 streams (0x0504) and Linux Kernel Keyring (KEYRING:persistent: / /proc/keys).
• Host client tooling: Passively audits availability of kinit/klist on $PATH in <0.5ms and provides package recommendations for Debian/Kali (krb5-user) and RHEL (krb5-workstation).

# Terminal checklist output
tanuki doctor

# Structured JSON export for automated agent ingestion
tanuki doctor --json

# Custom target paths
tanuki doctor --keytab /custom/krb5.keytab --krb5-conf /custom/krb5.conf

Generate zero-DNS unprivileged Kerberos configuration (RFC 4120):

# Generate unprivileged configuration directly targeting KDC IP (zero root, zero DNS dependency)
tanuki config --realm CORP.LOCAL --kdc 192.168.56.106 -o ./krb5.conf

# Activate in current unprivileged shell session
export KRB5_CONFIG=$(pwd)/krb5.conf

Inspect binary keytabs (RFC 4120):

# Human-re