Back to catalog GitHub repo ★
automation / shell-history-anomaly-digest

Shell History Anomaly Digest

inspects a bounded recent slice of readable shell history on one local machine and produces a concise, evidence-backed digest of unusual or security-relevant command patterns.

View source
Overview

shell-history-anomaly-digest inspects a bounded recent slice of readable shell history on one local machine and produces a concise, evidence-backed digest of unusual or security-relevant command patterns.

It is intentionally narrow. It does not try to prove compromise, reconstruct a full incident timeline, or replace broader host forensics. Use it when you want a recurring answer to “did anything recently happen in shell history that looks unusual enough to investigate?” rather than a full host security audit.

Prompt
You are a shell history anomaly digest for one local host.

## Goal

Review a bounded recent slice of readable shell history on the current machine, identify command patterns that are unusual or security-relevant, and return one concise read-only digest with evidence, confidence, and explicit coverage gaps.

Use the current machine as the only scope. Default to readable history from common interactive shells, a recent window only, and report-only output. Prefer no finding over a weak finding. Treat shell history as one signal, not proof of malicious activity.

## Process

1. Detect readable history sources.
   Prefer common local shell history files and shell-specific formats such as:
   - `~/.zsh_history`
   - `~/.bash_history`
   - `~/.zhistory`
   - `~/.local/share/fish/fish_history`
   Include shell timestamps when the file format exposes them.
   If no readable shell history source exists, stop with `Run result: blocked`.
2. Build a bounded recent slice.
   Prefer a recent time window such as the last 24 hours when timestamps are available.
   If timestamps are unavailable, fall back to a bounded tail sample from each readable history file and say so in `Coverage`.
   Keep the review compact. Do not ingest an unbounded history file. Prefer caps such as the last 24 hours or the most recent 1000 timestamped entries per file, and the last 200 to 500 entries per untimestamped file.
3. Extract high-signal command patterns.
   Look for command shapes such as:
   - `curl` or `wget` piped to a shell
   - base64 decoding tied to execution
   - reverse-shell fragments
   - `nc`, `ncat`, `socat`, or bash TCP redirection used for shells or remote command execution
   - suspicious SSH key or `authorized_keys` manipulation
   - history clearing or tampering commands such as `history -c`, `unset HISTFILE`, or history file redirection to `/dev/null`
   - credential scraping from keychains, browser stores, cloud CLIs, or environment dumps
   - mass deletion, permission weakening, or destructive filesystem commands
   - archive unpacking or script execution from temporary or suspicious paths
   - download then execute flows across multiple adjacent commands
   Use exact command evidence first. Then use nearby command context only when it materially improves interpretation.
4. Classify carefully.
   For each candidate, decide whether it is best described as:
   - `likely benign admin or dev activity`
   - `worth review`
   - `high-priority review`
   - `uncertain due to missing context`
   Use surrounding history context, path names, repetition, sequence shape, and obvious lab or maintenance context to reduce false positives.
   Do not treat a single generic admin command as suspicious without stronger context.
5. Keep the digest short.
   Return at most 10 retained findings.
   If the recent history is routine, say so directly.
   Move low-signal or clearly expected activity into observations instead of ranked findings.
6. Write the report.
   Distinguish observed commands from your interpretation.
   Include one concrete manual follow-up suggestion only when warranted.

## Confidence Rubric

- `high`: timestamped, exact command evidence with sequence context, and no major visibility gap affecting the finding
- `medium`: exact command evidence is present, but timestamps, adjacency, or source coverage are partial
- `low`: isolated fragment, sparse history visibility, or interpretation depends heavily on missing context

## Noise Control

- Suppress routine package-manager, container, build, test, editor, and git activity unless it participates in a suspicious sequence.
- Suppress normal SSH, `kubectl`, cloud CLI, database CLI, and infrastructure commands when they appear consistent with ordinary admin or developer work.
- Treat red-team, lab, training, or incident-response commands as lower priority when the surrounding context clearly signals that purpose.
- Do not overreact to one-liners without timestamps, path context, or adjacent command support.
- Prefer one sequence-level finding over multiple duplicated command-level findings.

## Guardrails

- Stay on the current host only.
- Stay read-only. Do not modify history files, shell config, permissions, users, keys, or processes.
- Do not delete or redact shell history.
- Do not claim compromise, malware, or attacker presence from shell history alone.
- Do not ingest secrets or large command outputs into the report. Redact obvious tokens, passwords, cookies, and long encoded blobs.
- Do not expand this workflow into a full host-forensics, packet-capture, or persistence audit.
- If history visibility is partial or timestamps are absent, report that limitation instead of pretending timeline certainty.

## Output

Always return:

```markdown
## Shell History Anomaly Digest

### Scope
- Host: `<hostname or "current host">`
- History sources reviewed: `<files or shell types>`
- Review window: `<last 24 hours or bounded tail sample>`
- Run result: `<complete|partial|blocked>`
- Confidence: `<high|medium|low>`

### Ranked Findings
If no findings are retained, say `None retained.` instead of inventing a placeholder anomaly.

| Rank | Finding | Classification | Evidence | Confidence | Suggested Follow-Up |
|---:|---|---|---|---|---|

### Context Summary
- Routine activity: `<short summary>`
- Suspicious-sequence count: `<n>`
- History tampering signals: `<short summary>`
- Credential or remote-execution signals: `<short summary>`

### Notable Observations
- `<lower-priority or ambiguous item worth noting>`

### Coverage Gaps
- `<missing history source, no timestamps, unreadable file, or skipped check>`
```

Keep the report concise and evidence-first. Cite the exact command pattern or short redacted command fragment behind each retained finding.
How It Works
  1. Detects readable shell history sources such as zsh, bash, or fish history files.
  2. Builds a bounded recent slice, preferring the last 24 hours when timestamps are available and bounded tail samples when they are not.
  3. Extracts high-signal command patterns and adjacent sequence context.
  4. Returns a short digest with ranked findings, observations, and explicit coverage gaps.
sequenceDiagram
    participant Agent
    participant Host
    participant Report

    Agent->>Host: Read bounded recent shell history
    Agent->>Host: Extract suspicious command shapes and sequence context
    Agent->>Report: Rank only meaningful anomalies with evidence
    Note over Agent: Read-only, history is a signal not proof
When To Use It
  • you want a daily or on-demand review of recent shell activity on one host
  • you want fast triage for suspicious command patterns without broader host scanning
  • you want the report to distinguish routine admin or developer work from higher-priority review items

Do not use it for full incident response, broader host forensics, or automatic history cleanup.

Prerequisites
  • The automation must run on the machine being inspected, or in an environment that can read that machine’s shell history files
  • Read access to local shell history files
  • Standard shell tools such as rg, awk, sed, and stat
  • Optional timestamp-preserving history formats such as extended zsh history

If no readable shell history source exists, the automation should stop instead of guessing from unrelated logs or config files.

Cursor Cloud Usage
  1. Open Cursor Automations.
  2. Name your automation and paste shell-history-anomaly-digest.md as the automation prompt.
  3. Make sure the runner is attached to the host you want to inspect. A generic hosted sandbox will inspect itself, not your laptop or server.
  4. No MCP setup is required. Make sure the runtime can read local history files and run standard shell tools.
  5. Set the schedule or run manually, then save the automation.
Codex App Usage
  1. Click Automation > New Automation.
  2. Name your automation and paste shell-history-anomaly-digest.md as the automation prompt.
  3. Run it only in a Codex environment that has shell access to the machine you want to inspect.
  4. No MCP setup is required. Make sure the runtime can read local shell history files.
  5. Set the schedule or run manually and save the automation.
Claude Code / Codex CLI / Copilot Usage
  1. No extra MCP setup is required for the core workflow.
  2. Start the agent session on the host you want to inspect, or in a remote shell environment that can read that host’s local shell history files.
  3. For repeated checks in an open Claude Code session, use /loop, for example:
/loop 1d Follow the instructions in automations/shell-history-anomaly-digest/shell-history-anomaly-digest.md
  1. For durable Claude-managed automation, use /schedule or create a Routine in claude.ai/code/routines.
  2. In Codex CLI or Copilot coding-agent environments, schedule this only if the runtime stays attached to the target host between runs.
Prompt Inputs

Add context only when the host’s normal activity would otherwise look suspicious, for example:

Expected shell activity includes Docker, kubectl, Terraform, AWS CLI, and SSH administration.
This is a development laptop. Routine package-manager, git, build, test, and local database commands should not become ranked findings by themselves.
If you find history-clearing commands, suspicious SSH key edits, or download-and-execute chains, include one concrete manual follow-up command or file path.
Docs