Documentation

LogShield is a deterministic CLI tool for sanitizing sensitive data from logs before they are shared, stored, or processed further. This documentation is authoritative.

Overview

LogShield reads log data from stdin or files, applies explicit rule-based detection, and writes safe, structure-preserving output to stdout.

Design Goals

Deterministic output (same input -> same output)
Zero false positives by design
Pipeline-native (STDIN -> STDOUT)
Local-only, no network, no telemetry

Installation

Install LogShield globally via npm:

bash
npm install -g logshield-cli

Verify installation:

bash
logshield --version

Basic Usage

Scan a log file:

bash
logshield scan app.log

Pipe logs via stdin:

bash
cat app.log | logshield scan
Auto-detection STDIN is auto-detected when input is piped. No additional flags required.

Output Behavior

LogShield is designed to be predictable and non-destructive.

What LogShield guarantees

  • Line order is preserved
  • Whitespace is preserved
  • Non-secret values are never modified
  • Only the value of detected secrets is replaced
  • Keys, field names, and surrounding text are untouched

Input Sources

LogShield supports two input modes:

1. File input

bash
logshield scan app.log

2. STDIN (pipe)

bash
cat app.log | logshield scan

When data is piped, LogShield automatically switches to stdin mode. The --stdin flag exists as an explicit override for edge cases.

Redaction Format

All redacted values follow this format:

format
<REDACTED_TYPE>

No hashing, masking, or partial replacement is performed. Examples:

Before
password=secret123 Authorization: Bearer eyJhbGciOiJIUzI1NiIs... x-api-key: 1234567890abcdef email: user@example.com
After (default mode, sanitized output):
password=<REDACTED_PASSWORD> Authorization: Bearer <REDACTED_TOKEN> x-api-key: <REDACTED_API_KEY> email: <REDACTED_EMAIL>

Determinism

LogShield is fully deterministic. This means:

  • The same input always produces the same output
  • There is no randomness or sampling
  • Results are reproducible across machines and runs
  • No heuristic scoring or context-dependent behavior

Determinism is critical for:

  • CI pipelines
  • Snapshot tests
  • Auditable incident workflows
  • Diff-based workflows
  • Reproducible builds

Flags Reference

Flag Description
scan Scan input logs for secrets
--strict Aggressive, security-first redaction. Fails on ambiguous matches. Intended for CI and production.
--dry-run Report detected redactions only. Does not output log content.
--stdin Force stdin mode (usually auto-detected)
--json Machine-readable JSON output for programmatic consumption
--summary Print compact redaction summary
--fail-on-detect Exit with code 1 if secrets are found (CI gate)
--version Print version
--help Show help

Exit Codes

LogShield uses explicit exit codes for automation. You should rely on exit codes in CI environments.

Code Meaning
0 Success, no secrets detected
1 Secrets detected (with --fail-on-detect)
2 Invalid arguments or usage error

Supported Secret Types

LogShield detects common secret patterns including:

  • Passwords
  • API key headers
  • Authorization Bearer tokens
  • JWTs
  • Emails
  • URLs with embedded credentials
  • Database credentials (DB_URL)
  • OAuth tokens (access_token, refresh_token)

Strict mode additionally detects:

  • Stripe keys (sk_live_, sk_test_)
  • AWS access keys (AKIA...)
  • AWS secret keys
  • Credit card numbers (Luhn-validated)

See the source code for the full rule list.

Common Pipelines

Local debugging

bash
cat debug.log | logshield scan --dry-run

CI validation

bash
logshield scan app.log --strict --fail-on-detect

Sanitize and save

bash
cat app.log | logshield scan > safe.log

Upload sanitized logs

bash
docker logs app | logshield scan | upload-logs

GitHub Actions

Basic setup:

yaml
- name: Install LogShield run: npm install -g logshield-cli - name: Run tests (sanitized) run: npm test 2>&1 | logshield scan

CI gate - fail if secrets detected:

yaml
- name: Check for secrets run: | npm test > test.log 2>&1 logshield scan --dry-run --fail-on-detect < test.log

For more advanced patterns (reusable workflows, Docker builds, conditional strict mode), see the GitHub Actions tutorial on the blog.

What LogShield is NOT

To avoid ambiguity, LogShield intentionally does not:

  • Send data to the cloud
  • Use AI or probabilistic models
  • Modify log structure
  • Remove entire lines
  • Perform partial masking (e.g., sk_live_****)
  • Learn or adapt over time

LogShield is designed to be boring, predictable, and safe.

Security Model

Local-only by design LogShield runs fully locally. No outbound network calls. No telemetry. No data persistence.

All detection rules are:

  • Explicit
  • Inspectable
  • Versioned

You can audit every rule applied to your logs by reviewing the source code.

License

LogShield is released under the Apache-2.0 License.

Support