charles/claude-hooks
1
0
Fork 0
Code Issues 10 Pull requests Projects Releases Packages 1 Wiki Activity Actions

Observability: auditd rule to catch external docker stop / docker rm calls on claude-hooks-* containers #149

New issue
Closed
opened 2026-04-20 14:18:43 +00:00 by claude-desktop · 0 comments
claude-desktop commented 2026-04-20 14:18:43 +00:00
Collaborator
Copy link

User story

As the operator, I want an auditd rule that logs the calling PID + command line + cwd every time docker stop or docker rm is invoked against a claude-hooks-* container, so that the next time dev-default silently vanishes (#132) we have the caller identity instead of another round of guessing.

Context

#132's investigation (see comment #132 (comment)) ruled out every obvious candidate — no OOM, no restart-policy exhaustion, no service-side reconcileOne call, no shell history, no cron. Yet dockerd logs stopping restart-manager 6× today for dev-default exclusively. Something external is calling docker stop/rm and we can't see who.

auditd with a rule on the docker binary's execve (+ a filter that fires only when the argv contains stop or rm and a claude-hooks- name) would capture the caller's PID, executable path, cwd, and command line for every invocation. That's the one piece of information that would turn this from "mystery" into "we know which process is doing it and can fix or kill it."

Acceptance criteria

Rule file

  • New ops/audit/claude-hooks-docker.rules in the repo — auditd format, one rule per line.
  • Fires on execve of /usr/bin/docker (or wherever which docker points on the deployment host — detect at install time) when argv contains stop or rm AND argv[n] matches claude-hooks-*. Use a -k claude-hooks-docker audit key so the operator can grep results cleanly.
  • Scope to uid 1000 (the operator) and uid 0 (root) — we want to see both sudo/direct and any system-invoked removals.

Install path

  • just audit-install recipe that:
    1. Copies the rules file into /etc/audit/rules.d/ (requires sudo — recipe runs sudo install, prompts).
    2. Runs sudo augenrules --load to apply.
    3. Prints a one-line confirmation + the ausearch -k claude-hooks-docker -ts today command the operator would run to read the logs.
  • just audit-tail recipe: tails ausearch -k claude-hooks-docker --line-buffered in follow mode, filtered to human-readable lines (use aureport -k or parse ausearch output to the fields operators actually need: timestamp, PID, exe, argv, cwd).

Docs

  • README — new "Debugging with auditd" section: how to install the rules, how to read them, how to uninstall.
  • CLAUDE.md Commands section: just audit-install / just audit-tail.

Validation

  • Trigger a docker stop claude-hooks-<test-instance> manually; confirm the entry appears via ausearch -k claude-hooks-docker with operator's shell PID.
  • Trigger via a subprocess (bash -c 'docker stop claude-hooks-…'); confirm the subprocess + its parent are both logged.
  • Wait for (or force) another dev-default disappearance; inspect the audit log and identify the caller. Paste the finding into a comment on #132 and close that issue with the root cause, linked fix if applicable.

Out of scope

  • Automated alerting on audit events (operator-driven inspection is enough for now).
  • A dashboard surface for the audit log — terminal ausearch is fine.
  • Rules for operations other than stop/rm (no interest in auditing docker run or exec).

References

  • Investigation on #132: #132 (comment) (the "who's calling docker stop?" gap this ticket closes).
  • Watchdog that currently recovers (but can't diagnose) the vanishings: src/container-watchdog.ts (from #134).
  • Host: charles-desktop, Arch Linux, systemd-based, auditd should install via pacman -S audit.

Dependencies

  • Blocked by: nothing.
  • Blocks: closing #132.
  • Branch off: main.
## User story As the **operator**, I want an `auditd` rule that logs the calling PID + command line + cwd every time `docker stop` or `docker rm` is invoked against a `claude-hooks-*` container, so that the next time `dev-default` silently vanishes (#132) we have the caller identity instead of another round of guessing. ## Context #132's investigation (see comment https://forge.jacquin.app/charles/claude-hooks/issues/132#issuecomment-6640) ruled out every obvious candidate — no OOM, no restart-policy exhaustion, no service-side `reconcileOne` call, no shell history, no cron. Yet dockerd logs `stopping restart-manager` 6× today for `dev-default` exclusively. Something external is calling `docker stop`/`rm` and we can't see who. `auditd` with a rule on the `docker` binary's `execve` (+ a filter that fires only when the argv contains `stop` or `rm` and a `claude-hooks-` name) would capture the caller's PID, executable path, cwd, and command line for every invocation. That's the one piece of information that would turn this from "mystery" into "we know which process is doing it and can fix or kill it." ## Acceptance criteria ### Rule file - [ ] New `ops/audit/claude-hooks-docker.rules` in the repo — auditd format, one rule per line. - [ ] Fires on `execve` of `/usr/bin/docker` (or wherever `which docker` points on the deployment host — detect at install time) when argv contains `stop` or `rm` AND argv[n] matches `claude-hooks-*`. Use a `-k claude-hooks-docker` audit key so the operator can grep results cleanly. - [ ] Scope to uid 1000 (the operator) and uid 0 (root) — we want to see both sudo/direct and any system-invoked removals. ### Install path - [ ] `just audit-install` recipe that: 1. Copies the rules file into `/etc/audit/rules.d/` (requires sudo — recipe runs `sudo install`, prompts). 2. Runs `sudo augenrules --load` to apply. 3. Prints a one-line confirmation + the `ausearch -k claude-hooks-docker -ts today` command the operator would run to read the logs. - [ ] `just audit-tail` recipe: tails `ausearch -k claude-hooks-docker --line-buffered` in follow mode, filtered to human-readable lines (use `aureport -k` or parse ausearch output to the fields operators actually need: timestamp, PID, exe, argv, cwd). ### Docs - [ ] README — new "Debugging with auditd" section: how to install the rules, how to read them, how to uninstall. - [ ] CLAUDE.md Commands section: `just audit-install` / `just audit-tail`. ### Validation - [ ] Trigger a `docker stop claude-hooks-<test-instance>` manually; confirm the entry appears via `ausearch -k claude-hooks-docker` with operator's shell PID. - [ ] Trigger via a subprocess (`bash -c 'docker stop claude-hooks-…'`); confirm the subprocess + its parent are both logged. - [ ] Wait for (or force) another dev-default disappearance; inspect the audit log and identify the caller. **Paste the finding into a comment on #132** and close that issue with the root cause, linked fix if applicable. ## Out of scope - Automated alerting on audit events (operator-driven inspection is enough for now). - A dashboard surface for the audit log — terminal `ausearch` is fine. - Rules for operations other than `stop`/`rm` (no interest in auditing `docker run` or `exec`). ## References - Investigation on #132: https://forge.jacquin.app/charles/claude-hooks/issues/132#issuecomment-6640 (the "who's calling docker stop?" gap this ticket closes). - Watchdog that currently recovers (but can't diagnose) the vanishings: `src/container-watchdog.ts` (from #134). - Host: `charles-desktop`, Arch Linux, systemd-based, `auditd` should install via `pacman -S audit`. ## Dependencies - **Blocked by:** nothing. - **Blocks:** closing #132. - **Branch off:** `main`.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
chore/sync-pre-push-from-forge-base
fix/flows-yaml-dispatch-identity
feat/board-tap-to-assign
dev/1107
code-lead/1106
code-lead/1108
dev/1104
code-lead/1103
code-lead/1080
dev/1087
feat/flows-yaml-ci-events
chore/board-drop-stalled-and-density-controls
fix/flows-yaml-routes-always-register
flows-yaml/api-defaults
dev/1023
fix/event-log-history-bleed
fix/janitor-fix-ci-logs-and-cap
dev/1022
fix/board-card-provider
code-lead/1036
dev/1025
code-lead/1020
dev/1017
code-lead/1026
feat/web-shortcut-registry-1018
dev/1015
code-lead/1009
code-lead/1008
dev/975
dev/969
dev/973
dev/967
code-lead/968
code-lead/953
dev/970
dev/976
code-lead/966
code-lead/956
code-lead/951
dev/962
dev/963
dev/977
dev/955
dev/983
dev/961
dev/974
code-lead/950
code-lead/939
dev/941
dev/940
dev/937
dev/938
dev/936
dev/935
feat/web-i18n-fr-locale
feat/spec-editor-ui-polish
chore/drop-legacy-compat
fix/skills-drop-preview-pane
fix/882-skills-safety-rail
dev/911
dev/909
dev/923
dev/917
dev/915
feat/879-sr11-m2-drop-legacy-skill
code-lead/873
dev/881
code-lead/869
dev/867
code-lead/845
code-lead/843
code-lead/844
dev/837
dev/861
dev/849
code-lead/837
code-lead/842
fix/dedup-rebase-inflight
dev/838
code-lead/847
dev/833
code-lead/848
pr/838
code-lead/841
feat/settings-save-bar/836
code-lead/840
dev/846
code-lead/839
dev/832
fix/board-sse-stale-cache
dev/834
dev/835
feat/settings-breadcrumbs
feat/forge-oauth-credentials
refactor/service-config-consolidation
feat/agent-tokens-to-secrets
feat/gitlab-oauth-to-db
feat/authelia-rip-and-voice-fixes
fix/rebase-storm-and-dead-letter
code-lead/797
code-lead/796
dev/811
code-lead/798
dev/810
code-lead/795
dev/808
code-lead/794
dev/805
dev/802
dev/803
feat/avatar-menu-settings-entry
feat/per-agent-token-tracking
dev/793
dev/747
dev/752
code-lead/790
code-lead/759
dev/756
dev/760
dev/741
dev/767
dev/740
dev/709
dev/644
dev/637
boss/614
dev/600
dev/611
dev/585
fix/login-bonus-fixes
boss/544
dev/542
refactor/api-prefix-and-session-gate
dev/489
boss/531
boss/518
dev/499
boss/516
dev/530
dev/517
dev/519
dev/515
dev/522
dev/503
dev/471
boss/329
dev/417
dev/418
dev/402
boss/327
dev/334
dev/332
boss/326
boss/325
dev/331
boss/324
boss/323
boss/322
dev/294
test/s11-task-analytics
dev/262
boss/270
dev/268
foreman/ui-consolidation-spec
dev/234
boss/196
boss/176
boss/164
fix/124-session-persist-bind
boss/52
dev/87
boss/73
dev/77
dev/81
dev/82
boss/79
dev/42
dev/35
boss/7
No results found.
Labels
Clear labels   
area:agents
Agent types, pool scheduling, per-instance config

  
area:dashboard
Dashboard UI and observability surfaces

  
area:database
DB layer — schema, migrations, ORM, raw SQL

  
area:design
UI/UX mockup work — routes to designer agent

  
area:design-review
Design review dispatch — routes to design-reviewer agent

  
area:flows
Flow runner — YAML loader, executor, op registry, expression eval

  
area:infra
Deployment, isolation, containers, systemd units

  
area:meta
Tracking, scaffolding, project setup

  
area:security
Security — routes to reviewer-security (opus)

  
area:sessions
Session-id store, Claude SDK resume logic

  
area:webhook
Forgejo webhook routing and handlers

  
area:workdir
Clone cache, worktrees, git identity

  
security
Security-sensitive issue

  
type:bug
Bug

  
type:chore
Chore

  
type:meta
Tracking or decisions, not implementation work

  
type:user-story
User story

No labels
area:agents
area:dashboard
area:database
area:design
area:design-review
area:flows
area:infra
area:meta
area:security
area:sessions
area:webhook
area:workdir
security
type:bug
type:chore
type:meta
type:user-story
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
code-lead
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
charles/claude-hooks#149
No description provided.