# TOOLING STANDARDIZATION
> **Version**: 1.0 (2026-07-03)
> **Classification**: NEED_TO_KNOW
> **Location**: `Y:\documents\TOOLING_STANDARDIZATION.md` (LOCAL ONLY per OPS-09)
> **Related**: TOOLING_MAP.md (TOOL_ID registry), Per-tool docs in `Y:\documents\tools\`

---

## Overview

The NoName platform uses a **self-healing, zero-trust tooling infrastructure** deployed across 8 nodes. Every tool:

1. **Remains encrypted at rest** — AES-256-CBC with PBKDF2 (100k iterations)
2. **Decrypts to `/dev/shm` only at runtime** — memory-only filesystem, never touches disk
3. **Shreds plaintext after execution** — 3-pass overwrite + unlink
4. **Verifies HMAC before decryption** — ed25519 signatures prevent tampering
5. **Uses disguised filenames per node** — no two nodes share the same tool name
6. **Communicates exclusively over WG mesh** — `10.69.69.0/24`, never public IPs
7. **Is independently self-healing** — each tool can recover from failure without human intervention

---

## Architecture

```
┌─────────────────── LOCAL WORKSTATION (Y:\) ───────────────────┐
│                                                               │
│  Y:\{node_id}\tooling\                                        │
│  ├── raw\          ← Canonical source (identical all nodes)   │
│  ├── disguised\    ← Per-node renamed copies + engine.json    │
│  ├── enc\          ← AES-256-CBC encrypted + HMAC signatures  │
│  └── systemd\      ← Per-node systemd unit files              │
│                                                               │
│  Pipeline: raw → localize names → encrypt → sign → push       │
└───────────────────────────────────────────────────────────────┘
                           │ SCP/SSH via gabriella key
                           ▼
┌─────────────────── TARGET NODE ───────────────────────────────┐
│                                                               │
│  /opt/{disguise}/tools/       ← Encrypted .enc + .sig files   │
│  /opt/{disguise}/config/      ← WG stealth configs            │
│  /opt/{disguise}/keys/        ← WG private keys               │
│  /run/se/state/               ← Runtime state (tmpfs)         │
│  /dev/shm/.t_{node_id}/      ← Decrypted tools (tmpfs only)  │
│  /dev/shm/.k_{node_id}.*    ← Cached AES/HMAC keys (tmpfs)   │
│                                                               │
│  Key fetch: compass tunnel → Vault (10.69.69.8) → AES key    │
│  Execute:   HMAC verify → decrypt to /dev/shm → run → shred  │
└───────────────────────────────────────────────────────────────┘
```

---

## Per-Node Identity

| Node | ID | WG IP | Tool Dir | Disguise Theme | Daemon Name |
|------|--------|-------------|-------------------------------|----------------|----------------------|
| Shield | 414342 | 10.69.69.1 | `/opt/apache/engine/tools/` | Apache/httpd | `httpd-prefork-mgr` |
| Origin | 558201 | 10.69.69.2 | `/opt/php-worker/tools/` | PHP-FPM | `php-opcache-gc` |
| Proxy | 244939 | 10.69.69.3 | `/opt/cache-daemon/tools/` | Nginx cache | `nginx-cache-gc` |
| Filter | 333941 | 10.69.69.4 | `/opt/netfilter/tools/` | nftables | `nft-chainmon` |
| DNS | 199335 | 10.69.69.5 | `/opt/unbound/tools/` | Unbound | `unbound-resolvd` |
| Engine | 669427 | 10.69.69.6 | `/opt/apache/engine/tools/` | Postfix | `postfix-qmgr-aux` |
| Payment | 714820 | 10.69.69.7 | `/opt/systemd-journal/tools/` | systemd-journal | `journal-coalesce` |
| Vault | 869377 | 10.69.69.8 | `/opt/stunnel/tools/` | stunnel | `stunnel-cert-refresh` |

---

## Decrypt-and-Execute Pipeline

All tools on disk are `.enc` files. Execution flow:

```
1. s3rv1c3agent receives command (TOOL_ID)
2. engine.json maps TOOL_ID → disguised filename
3. decrypt-run.sh called with: {tool}.enc [args]
4. HMAC signature verified (.enc.sig file)
5. AES key fetched from Vault (10.69.69.8) via compass tunnel
   └─ Key cached in /dev/shm for 5 min (memory-only)
6. Tool decrypted to /dev/shm/.t_{node_id}/{tool}
7. Tool executed with bash
8. Plaintext shredded (3-pass + unlink) — ALWAYS, even on error
```

**Key management:**
- AES keys stored on Vault at `/var/vault/keys/{node_id}.aes`
- HMAC keys stored on Vault at `/var/vault/keys/{node_id}.hmac`
- Keys fetched via SSH (gabriella key) over compass tunnel (172.28.47.x)
- Keys cached in `/dev/shm/.k_{node_id}.{aes|hmac}` — 5 min TTL

---

## Communication Patterns

### All tools → Engine (10.69.69.6:8301)
- Heartbeat (svcbeat) — every 30s
- Tool execution audit logging (log_to_db.sh) — every execution
- **SCLS encrypted audit logging (audit_logger.sh)** — every execution, via forge tunnel
- Security events (security-*.sh) — on detection
- Runtime telemetry (runtime-*.sh) — scheduled via cron

### All tools → Origin DB (10.69.69.2:3306)
- Store data queries (telemetry-cron.sh)
- Direct IP detection logging (direct-ip-detect.sh)
- Credential rotation records (svcpass)

### All tools → Vault (10.69.69.8)
- AES/HMAC key fetch for decryption (decrypt-run.sh)
- Credential vault queries (tvault)

### Exception: Proxy Public IP
- **Proxy (107.189.23.194)** is the ONLY node with a public-facing service
- DNS resolvers point A records to this IP
- All other nodes are WG-mesh-only — no public services

### Protected IP
- **10.69.69.10** (Operator VPN) — NEVER blocked, hardcoded whitelist in `direct-ip-detect.sh`

---

## Tool Categories (TOOL_ID Registry)

### 🔴 Core (daemon infrastructure)
| TOOL_ID | Generic Name | Function | Self-Healing | Per-Tool Doc |
|---------|-------------|----------|:------------:|:------------:|
| `a1f0` | s3rv1c3agent (daemon) | Central orchestrator, runs tools by TOOL_ID | Yes — auto-restart via systemd | [core.md](tools/core.md) |
| `a1f1` | s3rv1c3agent.sh (inspector) | Status checker, health probe | Yes | [core.md](tools/core.md) |

### 🟡 Auth (session gate)
| TOOL_ID | Generic Name | Function | Self-Healing | Per-Tool Doc |
|---------|-------------|----------|:------------:|:------------:|
| `b2e0` | hello.sh (session challenge) | SSH session check-in, rate limiting | Kills sshd on failure | [auth.md](tools/auth.md) |
| `b2e1` | goodbye.sh (session teardown) | Clean session exit, state cleanup | N/A | [auth.md](tools/auth.md) |

### 🟢 Libraries (shared code)
| TOOL_ID | Generic Name | Function | Per-Tool Doc |
|---------|-------------|----------|:------------:|
| `c3d0` | common.sh | Shared functions, logging, audit trail | [libraries.md](tools/libraries.md) |
| `c3d1` | se_client.sh | Encryption client, key management | [libraries.md](tools/libraries.md) |
| `c3d2` | veil.sh | Obfuscation layer, honeypot management | [libraries.md](tools/libraries.md) |

### 🔵 Telemetry (monitoring)
| TOOL_ID | Generic Name | Function | Per-Tool Doc |
|---------|-------------|----------|:------------:|
| `d4c0` | svcbeat | Heartbeat → Engine API (8301) | [telemetry.md](tools/telemetry.md) |
| `d4c1` | mesh_heartbeat.sh | WG mesh connectivity check | [telemetry.md](tools/telemetry.md) |
| `d4c2` | runtime-health.sh | System health metrics | [telemetry.md](tools/telemetry.md) |
| `d4c3` | runtime-logs.sh | Log aggregation + rotation | [telemetry.md](tools/telemetry.md) |
| `d4c4` | runtime-services.sh | Service state monitoring | [telemetry.md](tools/telemetry.md) |
| `d4c5` | runtime-verify.sh | Configuration drift detection | [telemetry.md](tools/telemetry.md) |
| `d4c6` | runtime-update.sh | Package update checker | [telemetry.md](tools/telemetry.md) |

### 🟣 Operations (system management)
| TOOL_ID | Generic Name | Function | Per-Tool Doc |
|---------|-------------|----------|:------------:|
| `e5b0` | svcfile | File integrity monitoring | [operations.md](tools/operations.md) |
| `e5b1` | svcfw | Firewall rule enforcement | [operations.md](tools/operations.md) |
| `e5b2` | svclock | Lock manager (chattr, flock) | [operations.md](tools/operations.md) |
| `e5b3` | svclog | Centralized log management | [operations.md](tools/operations.md) |
| `e5b4` | svcperm | Permission enforcement | [operations.md](tools/operations.md) |
| `e5b5` | svcrotate | Credential rotation trigger | [operations.md](tools/operations.md) |
| `e5b6` | svctrap | Intrusion trap management | [operations.md](tools/operations.md) |
| `e5b7` | svcboot | Boot sequence validator | [operations.md](tools/operations.md) |
| `e5b8` | svccfg | Config drift enforcement | [operations.md](tools/operations.md) |

### 🔴 Security (threat response)
| TOOL_ID | Generic Name | Function | Per-Tool Doc |
|---------|-------------|----------|:------------:|
| `f6a0` | svcpass | Password rotation engine | [security.md](tools/security.md) |
| `f6a1` | security-audit.sh | Full node security audit | [security.md](tools/security.md) |
| `f6a2` | security-auth.sh | SSH auth port rotation (svcauth) | [security.md](tools/security.md) |
| `f6a3` | security-crypto.sh | Crypto verification | [security.md](tools/security.md) |
| `f6a4` | security-detect.sh | Intrusion detection | [security.md](tools/security.md) |
| `f6a5` | security-password.sh | Password policy enforcement | [security.md](tools/security.md) |
| `f6a6` | security-password-verify.sh | Password hash verification | [security.md](tools/security.md) |
| `f6a7` | security-permissions.sh | File permission auditor | [security.md](tools/security.md) |
| `f6a8` | security-response.sh | Automated threat response | [security.md](tools/security.md) |
| `f6a9` | log_to_db.sh | Audit trail → Engine DB | [security.md](tools/security.md) |
| `scls` | audit_logger.sh | SCLS encrypted audit → Engine DB | [security.md](tools/security.md) |
| `scls` | gen_audit_keys.sh | Per-node SCLS key generation | [security.md](tools/security.md) |

### 🟠 Network / Data / Fleet / Recovery
| TOOL_ID | Generic Name | Function | Per-Tool Doc |
|---------|-------------|----------|:------------:|
| `1a00` | network-control.sh | WG interface management | [network.md](tools/network.md) |
| `1a01` | network-status.sh | Network health dashboard | [network.md](tools/network.md) |
| `2b00` | data-backup.sh | Encrypted backup creation | [data.md](tools/data.md) |
| `2b01` | data-integrity.sh | Data checksum verification | [data.md](tools/data.md) |
| `2b02` | data-restore.sh | Backup restoration | [data.md](tools/data.md) |
| `3c00` | fleet_audit.sh | Cross-node health check | [fleet.md](tools/fleet.md) |
| `3c01` | fleet_deploy.sh | Tool deployment orchestrator | [fleet.md](tools/fleet.md) |
| `3c02` | fleet_restart.sh | Service restart coordinator | [fleet.md](tools/fleet.md) |
| `3c03` | fleet_verify.sh | Post-deploy verification | [fleet.md](tools/fleet.md) |
| `4d00` | phoenix-core.sh | Self-healing orchestrator | [recovery.md](tools/recovery.md) |

### Node-Specific Tools
| TOOL_ID | Generic Name | Node | Per-Tool Doc |
|---------|-------------|------|:------------:|
| `6f00-6f07` | CE admin suite | Origin only | [admin.md](tools/admin.md) |
| `7a00` | tvault (vault client) | Origin only | [admin.md](tools/admin.md) |
| `8b00-8b09` | Mail suite | Engine only | [mail.md](tools/mail.md) |
| `9c00` | img-pipeline | Origin only | [media.md](tools/media.md) |
| `9c01` | tron-signer | Engine only | [crypto.md](tools/crypto.md) |
| `9d00` | Security analyzer (Mistral) | Engine only | [ai.md](tools/ai.md) |
| `0d00` | deploy.sh | Origin only | [deploy.md](tools/deploy.md) |

---

## Disguised Name Matrix

### Critical Tools (b2e0 hello / b2e1 goodbye)

| Node | b2e0 (Hello) | b2e1 (Goodbye) | b2e0 Path on Server |
|------|-------------|----------------|---------------------|
| Shield | `coredump-handler.sh` | `coredump-cleanup.sh` | `/opt/apache/engine/tools/coredump-handler.sh` |
| Origin | `nginx-maint.sh` | `nginx-purge.sh` | `/opt/php-worker/tools/nginx-maint.sh` |
| Proxy | `networkd-diag.sh` | `networkd-reset.sh` | `/opt/cache-daemon/tools/networkd-diag.sh` |
| Filter | `journal-compact.sh` | `journal-vacuum.sh` | `/opt/netfilter/tools/journal-compact.sh` |
| DNS | `resolved-sync.sh` | `resolved-flush.sh` | `/opt/unbound/tools/resolved-sync.sh` |
| Engine | `oomd-report.sh` | `oomd-cleanup.sh` | `/opt/apache/engine/tools/oomd-report.sh` |
| Payment | `journal-rotate.sh` | `journal-archive.sh` | `/opt/systemd-journal/tools/journal-rotate.sh` |
| Vault | `cert-renew-check.sh` | `cert-revoke-stale.sh` | `/opt/stunnel/tools/cert-renew-check.sh` |

### Core Daemon (a1f0 / a1f1)

| Node | a1f0 (Daemon) | a1f1 (Inspector) | systemd Unit |
|------|--------------|------------------|--------------|
| Shield | `httpd-prefork-mgr` | `httpd-prefork.sh` | `httpd-prefork-mgr.service` |
| Origin | `php-opcache-gc` | `php-opcache.sh` | `php-opcache-gc.service` |
| Proxy | `nginx-cache-gc` | `nginx-cache.sh` | `nginx-cache-gc.service` |
| Filter | `nft-chainmon` | `nft-chain.sh` | `nft-chainmon.service` |
| DNS | `unbound-resolvd` | `unbound-resolve.sh` | `unbound-resolvd.service` |
| Engine | `postfix-qmgr-aux` | `postfix-qmgr.sh` | `postfix-qmgr-aux.service` |
| Payment | `journal-coalesce` | `journal-coal.sh` | `journal-coalesce.service` |
| Vault | `stunnel-cert-refresh` | `stunnel-cert.sh` | `stunnel-cert-refresh.service` |

---

## engine.json Schema

Each node has an `engine.json` in its tool directory that tells s3rv1c3agent how to find tools:

```json
{
  "node_id": "869377",
  "node_role": "vault",
  "node_name": "Vault",
  "wg_ip": "10.69.69.8",
  "engine_url": "http://10.69.69.6:8301",
  "heartbeat_interval": 15,
  "log_level": "info",
  "tool_dir": "/opt/stunnel/tools",
  "tool_map": {
    "a1f0": "stunnel-cert-refresh",
    "b2e0": "cert-renew-check.sh",
    "b2e1": "cert-revoke-stale.sh",
    "c3d0": "common.sh",
    "d4c0": "svcbeat",
    "f6a0": "svcpass"
  }
}
```

**Key fields:**
- `node_id` — Matches IDENTIFICATION_MAP
- `wg_ip` — WG mesh IP (all communication uses this)
- `engine_url` — Engine C++ API endpoint for heartbeat/commands
- `tool_dir` — Where encrypted tools live on this node
- `tool_map` — TOOL_ID → local disguised filename

---

## Deployment Pipeline

```bash
# 1. Localize (already done in Y:\{node}\tooling\disguised\)
#    raw/hello.sh → disguised/coredump-handler.sh (Shield)

# 2. Encrypt
openssl enc -aes-256-cbc -pbkdf2 -iter 100000 \
  -pass "pass:${AES_KEY}" \
  -in disguised/coredump-handler.sh \
  -out enc/coredump-handler.sh.enc

# 3. Sign
openssl dgst -sha256 -hmac "${HMAC_KEY}" \
  enc/coredump-handler.sh.enc | awk '{print $NF}' \
  > enc/coredump-handler.sh.enc.sig

# 4. Push to node
scp -i gabriella -P 9922 \
  enc/coredump-handler.sh.enc \
  enc/coredump-handler.sh.enc.sig \
  admin@10.69.69.1:/opt/apache/engine/tools/
```

---

## SCLS — Service Code Logging System (Deployed 2026-07-04)

Encrypted audit logging pipeline supplementing plaintext `sec_tool_runs`.

### Architecture

```
  Node Tool Execution
       │
       ▼
  audit_logger.sh (sourced by common.sh)
       │
       ├─ AES-256-CBC encrypt (per-node key) + gzip
       ├─ HMAC-SHA256 sign (canonical dot format)
       │
       ▼
  Async POST to Engine API
  ├─ Primary: forge tunnel (172.28.50.1:8301)
  └─ Fallback: wg7 mesh (10.69.69.6:8301)
       │
       ▼
  Engine DB: engine.sec_audit_log
  (encrypted at rest, decrypted on-demand)
       │
       ▼
  Dashboard → Audit Log tab
  (admin auth + rate-limited decryption)
```

### Key Files

| File | Location | Purpose |
|------|----------|---------|
| `audit_logger.sh` | `tooling/raw/` (all nodes) | Encrypt + HMAC + async POST |
| `gen_audit_keys.sh` | `tooling/raw/` (Engine) | Per-node AES-256 key generation |
| `06-scls.sql` | `build-v2/database/` | 4 tables: sec_audit_log, sec_audit_decryptions, sec_audit_rate_limits, sec_tool_registry |
| `api/audit/log.php` | `dashboard/api/` (Origin) | HMAC-verified ingest endpoint |
| `api/audit/decrypt.php` | `dashboard/api/` (Origin) | Rate-limited on-demand decryption |
| `api/audit/stream.php` | `dashboard/api/` (Origin) | SSE real-time event stream |
| `tabs/audit.php` | `dashboard/tabs/` (Origin) | Dashboard Audit Log tab |

### Encryption

- **Algorithm**: AES-256-CBC
- **Key**: Per-node, 256-bit (64-char hex), stored at `/opt/binary/config/.k7x9m2/audit.key`
- **IV**: Random 16 bytes per event
- **Compression**: gzip -9 before encryption
- **HMAC**: SHA-256, canonical dot format (ts.nonce.POST.path.body)

### Decryption (Admin Dashboard)

- **Auth**: 3-phase admin auth + RBAC `decrypt.pii` role
- **Rate limit**: 10 decryptions/minute per admin (sliding window)
- **Audit trail**: Every decryption logged to `sec_audit_decryptions`
- **Key source**: Local file `/opt/sysc/engine/vault/node_keys/<nid>.key`

### HMAC Format (Canonical — CRY-02)

All 13 bash tools now use the canonical dot format (fixed 2026-07-04):
```
HMAC-SHA256( ts + "." + nonce + "." + METHOD + "." + path + "." + body )
```
Headers: `x-engine-ts`, `x-engine-nonce`, `x-engine-sig`, `x-engine-node`

---

## Cross-References

| Document | Purpose |
|----------|---------|
| [TOOLING_MAP.md](TOOLING_MAP.md) | TOOL_ID registry + per-node name tables |
| [IDENTIFICATION_MAP.md](IDENTIFICATION_MAP.md) | Node identity, IPs, service accounts |
| [PORT_STANDARDIZATION.md](PORT_STANDARDIZATION.md) | Port assignments per node |
| [PERMISSIONS_STANDARDIZATION.md](PERMISSIONS_STANDARDIZATION.md) | File permissions, SELinux, immutability |
| [WIREGUARD_MAP.md](WIREGUARD_MAP.md) | Tunnel topology and subnet assignments |
| Per-tool docs in `tools/` | Detailed per-category documentation |
