yotta-logwatch

What it is

Security investigation often starts with logs: are there brute-force attempts in the login log, scans or webshell uploads in the Web access log, or suspicious commands in PowerShell script blocks? Yuancha packages these capabilities into a zero-dependency engine — no SIEM or external tools. It parses auth/secure, Web access logs (common/combined), PowerShell script-block logs, and Windows Event Log (Security/System) with the pure Python standard library, flags suspicious activity with heuristic rules, and outputs a timeline plus Chinese teaching-style explanations.

It is not tied to any single platform: it is an agent-agnostic toolkit that works in any agent supporting Agent Skills. Read-only local logs — no network, no proactive scanning, no modifications to any log content, and no resident service.

Core value

• Zero-dependency engine — four log parsers + detection rules built entirely with Python 3.8+ standard library; no SIEM or external scanners.
• Four log families — auth/secure (brute-force / abnormal login / sudo escalation), Web access logs (scans / webshell / traversal / SQLi / suspicious UA), PowerShell script blocks (encoded / download-execute / reflection / AMSI bypass / obfuscation), Windows Event Log (login failures / abnormal login / account ops / log clearing / suspicious process).
• Automatic type sniffing — no need to specify the log type; it judges by line heuristics, or force it with --type.
• Timeline + Chinese explanations — hits are sorted by time; each includes type, severity, evidence line, Chinese explanation and a review suggestion.
• Three output modes — text / JSON (clean stdout) / Markdown report; --output writes to a file.
• Tunable thresholds — brute-force count (--max-fail), time window (--window), 404 flood (--404-threshold).

Why use it

Commands

Quick start

Use python on Windows, python3 on Linux/macOS.

# Analyze a local auth log
python3 scripts/yotta_logwatch.py scan --path /var/log/auth.log

# Recursively scan all log-feature files under a directory and write a Markdown report
python3 scripts/yotta_logwatch.py scan --path /var/log/nginx --recursive --report report.md

# Force the Web type
python3 scripts/yotta_logwatch.py scan --path access.log --type web

# Show only medium and above
python3 scripts/yotta_logwatch.py scan --path auth.log --min-severity medium

# Tune brute-force / time-window thresholds
python3 scripts/yotta_logwatch.py scan --path auth.log --max-fail 3 --window 120

# Read from stdin (pipe)
type auth.log | python scripts/yotta_logwatch.py scan --stdin

# Print version
python3 scripts/yotta_logwatch.py --version

Exit codes: 0 = no hits; 1 = hits found; 4 = usage or read error.

Installation

Pick any of the four methods below; the order is the recommended priority. Skill files always come from npm (GitHub can be slow without a proxy; npm supports mirrors).

Method 1: npm one-liner (recommended)

# Optional China mirror: npm config set registry https://registry.npmmirror.com
npx -y @yottameta/yotta-logwatch --agent <agent-name>      # install to the agent's default user-level skills dir
npx -y @yottameta/yotta-logwatch --dir <your-skills-dir>   # point to the skills dir itself (e.g. ~/.codex/skills)

• --agent <name> installs to that agent's default user-level directory; --list shows each agent's default directory.
• --dir <path> installs to the given directory; for agents not in the preset list, point --dir at their skills directory.
• If the mirror has not synced the new package (404): add --registry=https://registry.npmjs.org/ (a proxy may be needed in China), or wait for the mirror cache.

Method 2: git clone (developers / git available)

git clone https://github.com/YottaMeta/yotta-logwatch.git <your-skills-dir>/yotta-logwatch

Method 3: GitHub Download ZIP (manual / no git)

On the GitHub repository YottaMeta/yotta-logwatch, click Code → Download ZIP, unzip it and put the yotta-logwatch folder into the agent's skills directory.

Method 4: install.sh (multi-agent one-liner script)

bash install.sh --agent <name>   # install to the agent's default user-level directory
bash install.sh --dir <path>     # install to the given directory
bash install.sh --list           # list agents -> default directories

Method 1 uses the npm registry (npmmirror / npmjs) and does not depend on GitHub; Methods 2/3 use GitHub and may fail without a proxy in China.

Usage with an AI agent

1. Wire this repo's SKILL.md into any agent's skills / rules system (see Installation above).
2. When the user asks "are there brute-force attempts in the auth log?", run:

   python3 scripts/yotta_logwatch.py scan --path /var/log/auth.log
   

   You get a timeline of hits with type, severity, evidence and a Chinese explanation.
3. To focus on high-signal findings, filter by severity:

   python3 scripts/yotta_logwatch.py scan --path auth.log --min-severity high
   

4. For machine-readable output, use --json (clean stdout) for pipeline integration.
5. Always treat hits as "suspicious" prompts to verify manually — never as a confirmed attack.

Detection rules

Boundaries (security red line)

• Read-only local — no network, no proactive scanning, never modify / delete / write any log content.
• No exploitation — every hit is only a "suspicious prompt + review suggestion"; no exploitation details are provided.
• Authorization — only for explicitly authorized / self-owned assets / CTF ranges / teaching environments. Analyzing others' systems without authorization violates the law; the user bears responsibility.

Development & validation

• Tests: python scripts/test_yotta_logwatch.py (66 cases: sniffing / parsers / detection / pipeline / output / CLI exit codes 0/1/4; run inside the skill folder)
• Rule reference: references/auth-log-rules.md, references/web-log-rules.md, references/powershell-log-rules.md, references/windows-event-rules.md, references/analysis-spec.md

Changelog

• v0.2.7 (2026-08-29): Install docs alignment — unified four install methods (npx -y @yottameta/yotta-logwatch --agent/--dir, git clone, GitHub Download ZIP, install.sh --agent/--dir/--list), removed the legacy GitHub-clone installer and global-install (-g) recommendations; bilingual README install section synced to 发布规范 §3.3.1. No functional change.

• v0.2.6 (2026-08-27): Publish-metadata sync — ClawHub republished via web UI "New version" at v0.2.6 with display name "元察 yotta-logwatch"/slug yotta-logwatch; GitHub + npm bumped to v0.2.6 to keep the three sources aligned; no functional/engine/rule change.

• v0.2.5 (2026-08-27): Publish-metadata fix — republished with --name '元察 yotta-logwatch' (quoted as a single argument) so the ClawHub card now shows the Chinese display name; no functional/engine/rule change.

• v0.2.4 (2026-08-27): Publish-metadata fix attempt — passed --name 元察 yotta-logwatch without quotes, so the shell split the value and the --name did not take effect; ClawHub card still showed bare yotta-logwatch (fixed in v0.2.5); no functional/engine/rule change.

• v0.2.3 (2026-08-27): Clean republish — v0.2.2 tarball accidentally included pycache bytecode; 0.2.3 removes it (content identical), 0.2.2 deprecated on npm.

• v0.2.2 (2026-08-27): Docs fix — removed the repo-only tools/validate-skill.py reference from Development & validation (it is not shipped in the skill package); only the in-package test script remains.

• v0.2.1 (2026-08-27): Docs parity fix — README.zh-CN.md now covers all English sections (Usage with an AI agent / Detection rules / Boundaries / Development & validation / Changelog / License); EN/zh section structure aligned. No engine changes.

• v0.2.0 (2026-08-27): New Windows Event Log detection (winevt) — parses key=value / wevtutil text / XML exports of Security/System; 4625 brute-force aggregation, 4624 abnormal / admin / RDP logon, account created / deleted / locked, group member add, 1102 audit log cleared, 4688 suspicious process, 7045 service, 4698 scheduled task; plus the five-block analysis spec (references/analysis-spec.md). 66 tests green. See CHANGELOG.md.

• v0.1.0 (2026-08-27): Initial release — zero-dependency engine parsing auth/secure, Web access logs (common/combined) and PowerShell script blocks with automatic type sniffing; auth / web / powershell detection; text / JSON / Markdown output; 42 tests green.

License

MIT © YottaMeta — see LICENSE.