cleansh 0.1.4

Sanitize your terminal output. One tool. One purpose.
Documentation

Cleansh – Sanitize Your Terminal Output, Securely.

CI Release crates.io License CodeQL Advanced CodeQL

Cleansh is a high‑trust, single‑purpose CLI tool designed to sanitize terminal output for safe sharing.
It prioritizes security by default, requires zero configuration to get started, and offers extendability when needed.
The project is in active development; while the latest v0.1.2 release addresses critical output formatting and stability,
your feedback is valued. Please report any issues you encounter.

Table of Contents

Section
1. Overview
2. Core Capabilities – Current Version (v0.1.2)
    2.1. Primary Redaction Categories
    2.2. Optional Features (with flags)
3. Usage Examples
4. Known Issues
5. Project Structure
6. Configuration Strategy
7. Clipboard Support
8. Sanitizer Engine Design
9. Logging and Error Handling
10. Testing and Validations
11. Packaging & Distribution
12. Metadata & License
13. Security by Default Principles
14. Future‑Proofing (Post v1.0 Aspirations)
15. Summary of Technology Stack

1. Overview

cleansh is a powerful and reliable command‑line utility designed to help you quickly and securely redact sensitive information from your terminal output.
Whether you're debugging, collaborating, or sharing logs, cleansh ensures that confidential data like IP addresses, email addresses,
and access tokens never leave your local environment unmasked. Piped directly from stdin or loaded from files, cleansh provides
a robust, pre‑configured solution for data sanitization, with flexible options for custom rules and output formats.

Sanitize your terminal output. One tool. One purpose.

2. Core Capabilities – Current Version (v0.1.2)

This version of cleansh focuses on providing essential sanitization features with a strong emphasis on security and ease of use,
building upon the "Precision View" introduced in v0.1.1. Based on our rigorously passing test suite, cleansh accurately masks:

2.1. Primary Redaction Categories:

  • Emails: Common email formats (e.g., user@example.com).
  • IP Addresses: IPv4 addresses (e.g., 192.168.1.1).
  • Tokens & Secrets: JWTs, AWS/GCP keys, SSH keys, hex secrets, and generic tokens.
  • Absolute Paths: Linux (/home/user/... → ~/home/user/...) and macOS paths (/Users/admin/... → ~/Users/admin/...).

2.2. Optional Features (with flags):

cleansh provides command‑line flags to customize its behavior, all thoroughly tested:

  • Copy to Clipboard (-c / --clipboard): Instantly copy sanitized output.
  • Diff View (-d / --diff): Show a colored, line‑by‑line diff of redactions.
  • Custom Config (--config <path>): Merge in your YAML redaction rules.
  • Output File (-o <path>): Write sanitized content to a file.

3. Usage Examples

Basic Sanitization (stdin):

echo "My email is test@example.com and my IP is 192.168.1.1." | cleansh

Docker Logs:

docker logs my-sensitive-container | cleansh

Kubectl Logs:

kubectl logs my-pod-with-secrets | cleansh

Clipboard:

git config --list | cleansh -c

Diff:

cat /var/log/app/errors.log | cleansh -d

Custom Rules:

cat secrets.txt | cleansh --config ./custom_rules.yaml

Save to File:

myscript.sh | cleansh -o safe.log

File Input:

cleansh  ./raw_log_file.txt

Combined:

mycmd | cleansh -d -o sanitized.txt

4. Known Issues

4.1. Windows Path Redaction

  • Severity: Medium — Windows paths (C:\Users\…) aren’t auto‑redacted yet.
  • Workaround: Add a custom YAML rule targeting ^[A-Z]:\\.*.

4.2. Custom‑Rule Overrides

  • Severity: Low — Broad “generic token” rules can override specific placeholders.
  • Workaround: Make custom patterns more precise.

5. Project Structure

cleansh/
|-- src/
|   |-- main.rs
|   |-- commands/
|   |-- tools/
|   |-- config/
|   |-- ui/
|   `-- tests/
|-- config/
|   `-- default_rules.yaml
|-- .env
|-- .gitignore
|-- Cargo.toml
|-- README.md
`-- LICENSE (MIT)

6. Configuration Strategy

6.1. Runtime Settings (.env)

LOG_LEVEL=info
CLIPBOARD_ENABLED=true
DEFAULT_CONFIG=./config/default_rules.yaml

6.2. Custom Rules (--config)

rules:
  - name: emp_id
    pattern: 'EMP-\d{5}'
    replace_with: '[EMPLOYEE_ID_REDACTED]'
    multiline: false
    dot_matches_new_line: false

7. Clipboard Support

  • macOS & Windows: Built‑in.
  • Linux: Requires xclip, xsel or wl-clipboard.

8. Sanitizer Engine Design

(in src/tools/sanitize_shell.rs)

  1. Strip ANSI escapes
  2. Apply built‑in regex rules
  3. Merge & apply custom YAML rules
  4. Output via stdout, clipboard, file, or diff

Performance via regex::RegexSet, security via compile‑time defaults.

9. Logging & Error Handling

  • Logging: log + env_logger, configurable via .env or --debug.
  • Errors: anyhow + thiserror, non‑fatal by default.

10. Testing & Validation

  • Unit Tests: Regex accuracy, path normalization, YAML parsing.
  • Integration Tests: stdin piping, clipboard mocks, file output, diff, no‑redaction case.

11. Packaging & Distribution

  • Prebuilt Binaries: GitHub Releases with cargo-dist.

  • Install Script:

    curl -sSf https://github.com/KarmaYama/cleansh/releases/download/v0.1.2/cleansh-installer.sh | sh

  • crates.io: cargo install cleansh (+ --force to update)

  • From Source:

    git clone https://github.com/KarmaYama/cleansh.git

cd cleansh

cargo build --release

cargo test

12. Metadata & License

12.1. Cargo.toml metadata

[package]

name = "cleansh"

version = "0.1.2"

edition = "2024"

license = "MIT"

repository = "https://github.com/KarmaYama/cleansh"

readme = "README.md"

12.2. License

This project is licensed under the MIT License.

13. Security by Default Principles

Feature Principle
No runtime eval All redaction via static regex, no code execution
Local‑only No network calls or telemetry
Immutable defaults Built‑in rules embedded at compile time
Path redaction Filesystem paths normalized to ~
YAML sandboxed Declarative custom rules only, no execution
Clipboard opt‑in -c flag required for clipboard copy

14. Future‑Proofing (Post v1.0 Aspirations)

  • Plugin architecture for external redactors
  • VS Code extension / Web GUI
  • WebAssembly build for browser sanitization
  • Git hooks integration (pre‑commit, pre‑push)
  • Enterprise tier: compliance‑focused redaction

15. Summary of Technology Stack

Area Stack/Choice
Language Rust
Config Format .env + YAML
CLI Parser clap
Regex Engine regex
ANSI Stripping strip-ansi-escapes
Diff Generation diffy
Clipboard arboard
Logging log, env_logger
Error Handling anyhow, thiserror
Packaging cargo-dist, curl install, cargo
License MIT

Precision redaction. Local‑only trust. Built for devs.