By the end of this post, you will have:

• A hook script that logs every Cursor tool call, from both the IDE and the CLI.
• The hook configuration, including the two deployment gotchas that cost us the most time.
• A way to deliver the collector to machines your device management cannot reach.
• an Elastic Agent filestream integration that parses the logs into structured fields
• ES|QL queries you can run to hunt across agent activity.
• The hardening and privacy decisions we made before rolling this out to the whole company.

Everything here works on the current 9.x release of the Elastic Stack.

Why AI coding agent activity is a blind spot

A coding agent with shell access is an automated operator on the endpoint. It runs curl, installs packages, edits configuration, and reads whatever files its task seems to require. From the point of view of endpoint detection and response (EDR) tooling, this is indistinguishable from the developer doing the same things, because it happens under the developer's account inside processes the developer launched.

That ambiguity matters in three situations:

1. During an incident, you need to know whether a command was typed by a person or generated by a model that may have been steered by a poisoned README or a malicious MCP server (think of T1059, Command and Scripting Interpreter, with the model as the interpreter).
2. uring threat hunting, you want to ask "which machines ran an agent that read a file matching *.pem last week?" and get an answer.
3. For governance, you need an inventory of which MCP servers your engineers actually connect to, because each one is a third party with tool-level access to a developer conversation.

The industry has converged on inventory as half of this problem: several major EDR and XDR vendors now ship Shadow AI discovery to find AI tools on endpoints. Inventory shows which machines have Cursor installed. Hooks record what Cursor does once it runs.

What are agent hooks?

Cursor can invoke an external program at defined points in the agent loop: when a session starts, before a shell command runs, after a file edit, when an MCP tool is called, when a sub-agent spawns. The agent writes a JSON payload describing the event to the program's stdin. For some events, the program's stdout response decides whether the action proceeds. Cursor is not alone in offering hooks like these: Claude Code exposes an equivalent set, and we will walk that side in a follow-up post. Here we stay on Cursor.

The stdout response property means hooks can be a control point. We deliberately chose to use them as a sensor instead. Our script approves everything and records everything, which is the same trade a flight recorder makes: it never flies the plane, but after something goes wrong it is the only honest witness. A blocking hook is one where Cursor pauses the action and waits for the hook's stdout response before proceeding: the agent won't run the shell command / call the MCP tool / read the file / spawn the sub-agent until the hook answers allow, deny, or ask. Blocking was tempting, and we may add targeted controls later, but for a first deployment the goal was visibility without breaking anyone's workflow. An agent rollout that slows developers down gets uninstalled.

The events we capture are below:

| Hook | Fires when | | :---- | :---- | | sessionStart / sessionEnd | A conversation begins or ends | | beforeShellExecution / afterShellExecution | A shell command runs | | beforeMCPExecution / afterMCPExecution | An MCP tool is called | | postToolUse / postToolUseFailure | Any tool call succeeds or fails | | afterFileEdit / beforeReadFile | The agent edits or reads a file | | subagentStart / subagentStop | A sub-agent spawns or completes | | stop | The agent loop ends |

How does the hook collector script work?

The full script is about 280 lines of bash with no dependencies, available in the elastic/elasticsearch-labs repository along with a PowerShell port for Windows (which will be shared at a later stage). It reads one JSON payload from stdin, extracts the fields we care about, and appends one line to a JSONL formatted date-rotated log file. Three design decisions shaped it.

Answer blocking hooks first. A sensor-only collector still registers the blocking events, because they carry the richest telemetry: beforeShellExecution captures the command before it runs, and `beforeReadFile` is the only read event Cursor offers. Registering them means Cursor pauses those actions and waits for a verdict, whether or not you ever intend to say no. The script therefore answers before it does anything else. If it crashed after the response was sent, nothing would hang; if it crashed before, the agent could stall on filesystem errors that have nothing to do with the user. So the very first thing the script does after reading stdin is approve (trimmed here to the Cursor events):

# Respond to blocking hooks before any filesystem work, so a
# logging failure can never hold up the agent.
if [[ "$INPUT" == *'"hook_event_name"'*'"beforeMCPExecution"'* ]] || \
   [[ "$INPUT" == *'"hook_event_name"'*'"beforeShellExecution"'* ]] || \
   [[ "$INPUT" == *'"hook_event_name"'*'"beforeReadFile"'* ]] || \
   [[ "$INPUT" == *'"hook_event_name"'*'"subagentStart"'* ]]; then
  echo '{"permission":"allow"}'
fi

In Cursor's response schema, allow proceeds, deny blocks, and ask forces a confirmation prompt. Cursor also fails open by default: if the hook process dies without responding, the action proceeds, and a hook that should block on failure can opt into failClosed: true instead. The combination means the worst case of a collector bug is a missing log line rather than a blocked engineer.

Detect which surface fired the hook. By surface we mean the client the agent ran in: the IDE, the CLI, or a remote session. A single log stream stays useful only if you can tell them apart, and the environment gives it away: the Cursor IDE is a VS Code fork, so hook processes it spawns inherit VS Code environment variables, while the CLI sets none of them (trimmed to the Cursor branch; the full script uses the same technique to tag other agents' surfaces)

if [[ "$INPUT" == *'"cursor_version"'* ]] || [ -n "${CURSOR_VERSION:-}" ]; then
  AGENT="cursor"
  if [ "${CURSOR_CODE_REMOTE:-}" = "true" ]; then
    IDE="remote"
  elif [ -n "${VSCODE_PID:-}" ] || [ -n "${VSCODE_CWD:-}" ] || [ -n "${VSCODE_IPC_HOOK:-}" ]; then
    IDE="cursor"      # the IDE is a VS Code fork; its env vars leak through
  else
    IDE="cursor-cli"  # the CLI sets none of them
  fi
fi

Promote the fields you will query. Each log entry carries the original hook payload under a raw key, plus identity (user, email, host) and a set of top-level fields extracted from the payload: hook_event_name, tool_name, command, file_path, mcp_server, model, session_id, and duration. A finished entry looks like this:

{
  "timestamp": "2026-06-02T09:14:31Z",
  "user": "adeveloper",
  "email": "adeveloper@example.com",
  "host": "macbook-dev42",
  "agent": "cursor",
  "ide": "cursor-cli",
  "model": "some-model-id",
  "session_id": "f3b9...",
  "hook_event_name": "beforeShellExecution",
  "tool_name": "Shell",
  "command": "npm test -- --watch=false",
  "file_path": null,
  "mcp_server": null,
  "final_status": null,
  "duration": null,
  "duration_ms": null,
  "event": { "kind": "event", "category": "process", "type": "start",
             "action": "beforeShellExecution", "outcome": null, "duration": null },
  "raw": { "...": "original hook payload, abridged" }
}

The event object follows Elastic Common Schema (ECS) conventions (event.category, event.type, event.outcome), which makes the data line up with the rest of your security indices for correlation. We did not start with these promoted fields, and the section on shipping explains why we added them.

The script keeps logs readable only by the owner (chmod 0600), rotates by date, and opportunistically deletes files older than 30 days. Local retention is short on purpose; Elasticsearch is the system of record.

Configuring Cursor hooks

Cursor reads a hooks.json that maps each event to a command. Deployed system-wide on macOS, it lives at /Library/Application Support/Cursor/hooks.json, and both the IDE and the CLI pick it up, so one file covers both surfaces:

{
  "version": 1,
  "hooks": {
    "sessionStart":          [{ "command": "/usr/local/share/ai-hooks/log-tool-calls.sh" }],
    "beforeShellExecution":  [{ "command": "/usr/local/share/ai-hooks/log-tool-calls.sh" }],
    "afterShellExecution":   [{ "command": "/usr/local/share/ai-hooks/log-tool-calls.sh" }],
    "beforeMCPExecution":    [{ "command": "/usr/local/share/ai-hooks/log-tool-calls.sh" }],
    "afterMCPExecution":     [{ "command": "/usr/local/share/ai-hooks/log-tool-calls.sh" }],
    "postToolUse":           [{ "command": "/usr/local/share/ai-hooks/log-tool-calls.sh" }],
    "postToolUseFailure":    [{ "command": "/usr/local/share/ai-hooks/log-tool-calls.sh" }],
    "afterFileEdit":         [{ "command": "/usr/local/share/ai-hooks/log-tool-calls.sh" }],
    "beforeReadFile":        [{ "command": "/usr/local/share/ai-hooks/log-tool-calls.sh" }],
    "subagentStart":         [{ "command": "/usr/local/share/ai-hooks/log-tool-calls.sh" }],
    "subagentStop":          [{ "command": "/usr/local/share/ai-hooks/log-tool-calls.sh" }],
    "sessionEnd":            [{ "command": "/usr/local/share/ai-hooks/log-tool-calls.sh" }],
    "stop":                  [{ "command": "/usr/local/share/ai-hooks/log-tool-calls.sh" }]
  }
}

Two gotchas cost us real time. The first: the script must not live under /Library/Application Support/. Cursor splits hook command paths on spaces, so a script under a path containing a space silently never runs. We keep the script at /usr/local/share/ai-hooks/ and only the JSON config under the Cursor directory.

The second: Cursor reads hooks.json only at startup, so the hooks stay dormant on every machine until Cursor restarts. Our deployment showed green everywhere while the pipeline stayed silent, and the fix was operational rather than technical: the MDM deployment tooling now detects a running Cursor and prompts the user to restart it. Budget for that restart in your rollout plan, because until it happens you are deployed but not collecting.

Cursor also ships a headless CLI agent (cursor-agent), the same one used in CI jobs or scripted runs, and it fires the same hooks as the IDE. Confirm that path is covered too:

cursor-agent --print "say hello"
tail -1 ~/.config/ai-hooks/logs/tool-calls-$(date -u +%F).jsonl

The output shows "agent":"cursor","ide":"cursor-cli" instead of ide=cursor, confirming the CLI path is tagged and captured separately from the IDE.

Deploying Cursor hooks without MDM

Not every machine sits under device management. Our macOS and Windows fleets received the script and hooks file through their management tooling, but our Linux workstations have no equivalent channel. What they do have is Cursor itself, enrolled in our enterprise tenant, and Cursor's console can push a hook configuration to every enrolled client through Cloud Distribution. The console distributes a command rather than files, so a hooks.json that points at /usr/local/share/ai-hooks/log-tool-calls.sh is useless if nothing ever placed that script on the box.

We solved this by making the hook command carry its own payload. The command holds the collector script gzipped and base64-encoded, pinned to a SHA-256 hash. On each invocation, it checks whether the installed script matches the hash, and if it is missing or stale, it decodes the payload, verifies the hash again before writing, installs the script to the user's Cursor directory, and then executes it. Every failure path exits zero, so a decode or write problem degrades to a missing log line rather than a broken agent, which is the same fail-open contract as the rest of the pipeline. A machine with no prior collector self-installs the first time an agent fires a hook, and a version bump is one hash change in the console. The full command is in the repository next to the collector.

Sending hook logs to Elasticsearch with Elastic Agent

As InfoSec is Customer Zero at Elastic, the Elastic Agent is already rolled out to every endpoint, so collection was one new integration policy: a Custom Logs (filestream) input pointed at the hook log glob, with a decode_json_fields processor to parse each line. Configuring the integration was done quickly; getting the log format right took much longer.

# Custom Logs (filestream) integration settings
paths:
  - /Users/*/.config/ai-hooks/logs/tool-calls-*.jsonl   # macOS
  - /home/*/.config/ai-hooks/logs/tool-calls-*.jsonl    # Linux
  - C:\Users\*\.config\ai-hooks\logs\tool-calls-*.jsonl # Windows
data_stream.dataset: ai_hooks
processors:
  - decode_json_fields:
      fields: ["message"]
      target: "ai_hooks"
      add_error_key: true

Each line of the JSONL log file becomes one event in a logs-ai_hooks-* data stream, with every field from that line under the ai_hooks.* prefix.

Here is the lesson that reshaped the log format. Our first version logged only identity plus the raw payload, on the theory that decode_json_fields would expand everything and Kibana would sort it out. That theory was technically true: the data was all there, nested under ai_hooks.raw.*, three levels deep, with payload shapes that varied by hook type. Building a dashboard on ai_hooks.raw.tool_input.command for one event type and ai_hooks.raw.command for another was miserable, and our nested format turned Discover sessions into archaeology.

We extended the script to promote the queryable fields (tool_name, command, file_path, mcp_server) to the top level, and every downstream artifact got simpler. If you adopt one thing from this post beyond the script itself, make it this: structure your log line for the queries you want to run, and keep raw as the escape hatch rather than the interface.

Hunting across agent activity with ES|QL

With promoted fields, the questions that motivated the project become ES|QL one-liners. Which tools do agents call most across the fleet:

FROM logs-ai_hooks-*
| WHERE ai_hooks.tool_name IS NOT NULL
| STATS calls = COUNT(*) BY ai_hooks.tool_name
| SORT calls DESC
| LIMIT 10

On our fleet, file reads dominate by roughly four to one over shell execution, which matched nobody's intuition: picture what a coding agent does and you picture it running commands, so shell felt like the obvious leader. Most of what an agent actually does is reconnaissance of your own codebase, reading before acting.

Every shell command an agent ran on a given host, newest first:

FROM logs-ai_hooks-*
| WHERE ai_hooks.hook_event_name == "beforeShellExecution"
  AND ai_hooks.host == "macbook-dev42"
| KEEP @timestamp, ai_hooks.user, ai_hooks.agent, ai_hooks.command
| SORT @timestamp DESC
| LIMIT 50

Agents that touched credential material (T1552.001, Credentials in Files):

FROM logs-ai_hooks-*
| WHERE ai_hooks.file_path LIKE "*.env"
   OR ai_hooks.file_path LIKE "*.pem"
   OR ai_hooks.file_path RLIKE ".*/credentials(\\.[A-Za-z0-9]+)?$"
| STATS reads = COUNT(*) BY ai_hooks.user, ai_hooks.host, ai_hooks.file_path
| SORT reads DESC

Expect this one to be noisy in a good way: agents read .env files constantly because that is where connection settings live. The value is the baseline. One tuning note: a bare *credentials* wildcard also matches project and plan file names that happen to contain the word, so we anchor the pattern to the filename itself, credentials or credentials.<ext>, to keep the results to actual credential files. Once you know a host normally shows about four such reads a day, twenty reads in an hour against paths outside the working repo is a signal worth a look. One operational note: ES|QL returns at most 1,000 rows unless you raise the `LIMIT``, so treat a result that comes back at exactly 1,000 rows as truncated.

Which MCP servers are in use, and how widely:

FROM logs-ai_hooks-*
| WHERE ai_hooks.mcp_server IS NOT NULL
| STATS calls = COUNT(*), users = COUNT_DISTINCT(ai_hooks.user) BY ai_hooks.mcp_server
| SORT users DESC

This query answers a question that has nothing to do with security: who's actually running which MCP server. Before hooks, our list of MCP servers in use was whatever people remembered to mention. After, it was a live table, and the long tail surprised us: more than 300 distinct servers, and 86% of them used by only one or two people.

Download-and-execute patterns worth reviewing (T1105, Ingress Tool Transfer):

FROM logs-ai_hooks-*
| WHERE ai_hooks.command LIKE "*curl*"
  AND (ai_hooks.command LIKE "*| sh*" OR ai_hooks.command LIKE "*| bash*")
| KEEP @timestamp, ai_hooks.user, ai_hooks.host, ai_hooks.command
| SORT @timestamp DESC

We run variants of these as saved queries behind two dashboards: an activity overview (events over time by surface, top tools, models in use, active machines) and a security monitor (shell commands, MCP calls, failed tool calls, file edits, per-user activity). Both are standard Lens panels over the same data stream; nothing about the visualization layer is exotic, which is the point of normalizing early.

Hardening and privacy for agent audit logs

Once this data existed, the decisions that mattered most had little to do with the pipeline.

• Restrict who can read it. Hook logs are a detailed record of how individual engineers work, so we treated them like DNS logs: useful in aggregate, sensitive per-person. In Elasticsearch we excluded the ai_hooks.* field namespace from general-purpose security roles using field-level security, leaving full access to the small team that owns the pipeline:

POST /_security/role/secops_general
{
  "indices": [
    {
      "names": ["logs-*"],
      "privileges": ["read"],
      "field_security": {
        "grant": ["*"],
        "except": ["ai_hooks.*"]
      }
    }
  ]
}

• Collect metadata and leave content alone. The script logs the command line, the file path, and the tool name. It does not log file contents, prompts, or model responses. That line is what made the rollout conversation with engineering straightforward instead of adversarial: we could state plainly that this is security telemetry, on par with process auditing, and that nobody is reading code or conversations.

• Say all of that out loud. We published an internal page describing exactly what is collected, who can query it, and why, before the fleet deployment started, and linked it from the rollout announcement. The questions we got afterward were about edge cases, and there was no pushback on the premise.

What 13 million tool calls reveal about AI coding agent behavior

The aggregate numbers from the first two months after the May rollout, rounded, came to over 13 million tool-call events from more than 1,100 machines and nearly 900 distinct users. The CLI surface alone accounts for nearly a fifth of the events, which we would never have guessed from install counts. The busiest single event type was postToolUse, and beforeReadFile came second. That confirmed the read-heavy profile held across the whole fleet, not only on early-adopter machines.

Those numbers arrived fast. The proof-of-concept ran on one laptop for about six weeks while the script grew the field promotion, the CLI detection, and a series of small survival fixes (resolve the home directory from the passwd database when HOME is unset; refuse to run without piped stdin so a stray manual invocation cannot hang on cat). Then management tooling pushed it to the whole fleet, and within a week the pipeline went from a trickle to nearly a million events.

Here are two operational notes for anyone repeating this. First, fail-open is the correct default and you should still measure it: postToolUseFailure events told us when hooks themselves misbehaved after agent updates. Second, agent vendors ship fast and hook payloads change; the raw field meant new payload fields were captured from day one even before we promoted them.

What are the limitations of hook-based AI agent auditing?

This section exists because a defender will ask all of these questions anyway.

A developer with admin rights can remove the hooks configuration or edit the script, and on macOS the per-user log file is writable by its owner before shipping. This is workforce telemetry under the same trust model as any endpoint agent, and it is tamper-evident at the fleet level (a host whose events stop while the machine stays active is itself a signal) rather than tamper-proof. Pair it with an inventory source you control, such as osquery, to detect machines where the agent is installed, but no hook events arrive. Elastic has released Shadow AI detection packs with OSquery Manager v1.3.3 that inventory local LLMs, MCP configurations, and AI browser extensions across the fleet; hooks tell you what agents do, OSquery tells you where they exist. If you want to build something more custom, this blog is here to help you out; a future post will cover OSquery packs and Shadow AI detection in depth.

Coverage is also bounded by the hook events the vendor chooses to expose. We see tool calls, and we do not see the prompt or the model's reasoning, so intent stays out of frame. A hostile agent steered through prompt injection would show up here only through its actions. That is still far more than we could see before, and actions are ultimately what an incident responder needs. Cloud Distribution-pushed hooks only reach the enterprise tenant, so a personal Cursor login is invisible to this pipeline.

Getting started: try it on one laptop

The collector script, the hooks configuration, the self-installing console command, and the platform installers are in the supporting repo. With Elastic Agent already deployed, the path from zero to first dashboard is short: install the script and the hooks file, then add one custom logs integration. Start on your own laptop, run one agent session, and look at what lands in logs-ai_hooks-*. The first time you watch an agent's afternoon of work replay as structured events, you will have a much more concrete opinion about what your fleet's blind spot has been hiding.

The full path from config file to dashboard looks like this:

Why developer workstations are the npm supply-chain gap

CI/CD pipelines have their own supply-chain guardrails that can be managed at the enterprise level. Workstations are where the gap usually sits. A developer running npm install on a freshly compromised package is a different surface from the build pipeline, and the package manager itself is the right place to apply a delay before a fresh release becomes installable. npm's min-release-age setting, available since npm 11.10, does exactly that: the value is a number of days, and npm excludes any version published more recently from resolution. In MITRE ATT\&CK terms, the technique it blunts is Compromise Software Dependencies and Development Tools (T1195.001).

Most other package managers have an equivalent flag; cooldowns.dev tracks which ones, what each flag is called, and recommended values. This post focuses on npm, and recent attacks have happened, but the technique applies to any of them.

We enforce the setting with Jamf: a script writes min-release-age=7 to each user's .npmrc and the machine-global npmrc, and re-applies once a day. A removal therefore self-heals within 24 hours, and the telemetry is what makes the removal visible at all: the 6-hour heartbeat catches the gap window before Jamf closes it, and shows us which hosts keep removing the setting.

What does an npm cooldown config file look like?

The target is small: npm writes the setting to a user-level .npmrc, typically 10 to 50 bytes.

~/.npmrc    →    min-release-age=7        # days

Machine-global settings live in a handful of well-known paths (/opt/homebrew/etc/npmrc and /usr/local/etc/npmrc on macOS, /etc/npmrc and /usr/lib/node_modules/npm/.npmrc on Linux), so a complete inventory has to include those paths too. While we haven’t deployed a Windows version yet, we did include all the details to make this work in the Linux and Windows variants section. These can be found in the section Linux and Windows variants.

Two ingredients made this look easy. First, as InfoSec is Customer Zero at Elastic, the Elastic Agent is already rolled out to every endpoint and runs with the privileges to read these files. Second, the schema is essentially flat: one key, one value, one config file. So in theory, you configure a file input, tail the cooldown lines, and ship them to Elasticsearch.

The complication is that auth tokens for private registries (//registry.npmjs.org/:_authToken=...) live in the same .npmrc file. None of that can leave the host. Any approach has to filter the file body before it transits anywhere.

First approach: Monitoring .npmrc with the Custom Logs Filestream integration

The Custom Logs Filestream integration in Fleet wraps Filebeat's modern filestream input and lets you specify path globs and an ingest pipeline. Note: this is a distinct Fleet integration from the older "Custom Logs" integration, which wraps the legacy log input. The two have different configuration surfaces and file-identity models, so if you're migrating between them the reference linked above is worth reading before either direction.

We configured the integration across all users on macOS, plus the system-global npm paths:

/Users/*/.npmrc
/opt/homebrew/etc/npmrc
/usr/local/etc/npmrc
/etc/npmrc

The ingest pipeline did four things:

1. Grok the message field to pull out the min-release-age=value pair.
2. Drop any line whose key wasn't min-release-age, so registry auth tokens never made it into Elasticsearch.
3. Convert the value to a long.
4. Remove the raw message and event.original fields before indexing.

It worked, with three caveats that changed our minds about whether it was the right integration for this job.

Three filestream behaviours that don't fit config file monitoring

Native file identity beats fingerprint for small files

Filebeat's default file identity strategy is "fingerprint", which hashes the first N bytes of a file to give it a stable ID across rotations. The fingerprint length defaults to 1024 bytes, and a file shorter than that minimum is silently held back from ingestion until it grows. A 22-byte .npmrc will never grow, so the data never moves. This is in line with the description of the Filestream integration and also apparent in the agent logs:

"ingestion from some files will be delayed, files need to be at least
 1024 in size for ingestion to start"

The fix is to switch the integration's advanced options to use native file identity, which uses inode plus device and has no size floor. In our deployment on Elastic Agent 9.x, disabling fingerprint alone did not fall back to native; we had to flip both toggles explicitly.

clean_inactive and ignore_older are coupled

We wanted periodic re-emission of each config file so a stale event could be distinguished from a current one. filestream's clean_inactive is the right knob for that, but it requires ignore_older to also be set. Together they cleanly trim files that haven't moved recently, which is useful for rotating log files and not useful for static config files that may sit unchanged for months. We disabled clean_inactive.

Filestream emits on append, not on removal

This third learning is structural rather than a config gotcha. filestream is designed for log tailing: when bytes arrive at the end of a file, an event is emitted. When content disappears (because npm rewrites .npmrc without the cooldown line, or because the file is deleted), filestream sees a modification, but every resulting line is dropped by our allowlist filter, and nothing reaches Elasticsearch. The last "set" event for that host stays in the index indefinitely.

For application logs that's correct behavior, since log lines aren't usually retracted. For config file state monitoring, removal is the signal the adoption campaign needs most, and it never arrives. That's why we switched to CEL.

Why nvm inflates npm version counts for cooldown adoption

Machines routinely report more than one npm version, because every Node.js version installed through nvm (Node Version Manager) ships its own npm binary. The distortion stood out as soon as we checked test pulls from our osquery manager integration package-version inventory: one machine reported 34 distinct npm versions.

The config side of this is forgiving. npm config set min-release-age 7 writes to the user-level ~/.npmrc, and every npm installation on the machine reads that file, including the per-Node copies nvm installs. Enforcement is the strict side: versions older than 11.10 ignore the key. A machine carrying npm 11.12 in one nvm environment and npm 10.9 in another is only protected when the newer npm is the one running npm install. A count of machines with any capable npm overstates who is protected, which is one more reason to track the config file directly rather than infer adoption from version counts.

Second approach: Monitoring .npmrc with CEL snapshot semantics

The CEL input in Elastic Agent was designed for HTTP API polling, but it also exposes a file() function and a dir() function for filesystem access. That enables a different model from filestream. filestream tails lines as they arrive; CEL takes a snapshot of the whole file each interval. For state monitoring, the snapshot is what we want: the unit of interest is the current contents of .npmrc as a whole.

Here is the complete script we run, trimmed to npm (our production version watches the other package managers' config files with the same pattern, and carries an extra guard for non-UTF-8 file content):

(
  (
    try(dir("/Users")).as(entries, type(entries) != type("") ?
      entries.filter(u,
        u.is_dir
        && !string(u.name).startsWith(".")
        && string(u.name) != "Shared"
        && string(u.name) != "Guest"
      ).map(u, "/Users/" + string(u.name) + "/.npmrc")
    : [])
  ) + (
    try(dir("/home")).as(entries, type(entries) != type("") ?
      entries.filter(u,
        u.is_dir
        && !string(u.name).startsWith(".")
      ).map(u, "/home/" + string(u.name) + "/.npmrc")
    : [])
  ) + (has(state.files) ? state.files : [])
).map(f,
  try(file(f)).as(content,
    type(content) == type("") ?
      {"file": f, "exists": false}
    :
      {"file": f, "body": string(content),
       "hash": content.sha256().hex(), "exists": true}
  )
).as(file_data, {
  "events": file_data.filter(fd, fd.exists).map(fd, {
    "message": fd.body,
    "file": {"path": fd.file, "hash": {"sha256": fd.hash}},
  }),
  "cursor": {"hashes": file_data.filter(fd, fd.exists)
    .map(fd, {"file": fd.file, "hash": fd.hash})},
  "url": state.url,
  "files": has(state.files) ? state.files : [],
})

The first block enumerates user home directories at runtime, with filtering that path globs can't express, and appends the machine-global paths from state.files. try(dir(...)) and try(file(...)) return an error string when the path doesn't exist, so each block checks the type of the result and collapses a missing directory or file to an empty result. A macOS host has no /home, a Linux host has no /Users, and the same script runs on both.

The initial state supplies the global paths and the poll interval is 6 hours:

files:
  - /opt/homebrew/etc/npmrc
  - /usr/local/etc/npmrc
  - /etc/npmrc
  - /usr/lib/node_modules/npm/.npmrc

An aside on Fleet: the integration to add in the UI is called "Custom API using Common Expression Language", not "CEL". It exposes the full CEL runtime including file system access. Set resource.url: file:///dev/null to satisfy the required URL field without making an HTTP request, and put the initial state in the "Custom request cursor" YAML at the bottom of the form.

How the CEL integration evolved: emit-on-change, tombstones and heartbeat

The CEL snapshot integration shown above is the third version. The path there is the useful part.

Version one emitted only on change. Each heartbeat hashed every file and emitted an event only when the hash differs from the cursor, the state the input persists between runs. Efficient, and it produced the removal signal cleanly: npm rewrites .npmrc in place when a setting changes, the hash moves, the new snapshot carries no min-release-age line, and the ingest pipeline marks the event cooldown.absent = true.

Version two added a deletion tombstone. Hash comparison can't see a file that stopped existing (npm config delete min-release-age removes .npmrc entirely when it's the only setting), because version one filtered out non-existent files before emitting. A one-block extension emitted a stub event, once, for any file that was in the cursor but no longer on disk.

Version three replaced both with a heartbeat, because the dashboard demanded it. The adoption dashboard counts hosts whose cooldown state falls inside the selected time window. Under emit-on-change, a host that sets a cooldown emits exactly one event and then goes silent. Once that single event ages past the dashboard's window (say, now-7d), the host disappears from the "adopted" count even though the cooldown is still in place. We watched adoption climb during rollout and then start to erode a few days later, purely as an artifact of one-shot events aging out of the window. The telemetry was correct; the time-windowed view of it was not.

So the final integration re-emits each existing file's current state on every 6-hour heartbeat. Every host re-reports its cooldown posture four times a day, the windowed dashboard reflects live state, and a host that stops appearing is genuinely offline rather than merely quiet. Removal of the cooldown line still surfaces as cooldown.absent = true in the next snapshot, and a deleted file drops out of subsequent snapshots, so the tombstone becomes unnecessary.

The cost is volume: a snapshot per file per host per interval instead of one event per change. At a 6-hour cadence that is a few thousand small documents a day across the fleet, which is immaterial. At a 60-second interval it stops being immaterial: always-emitting at 60s ships the same unchanged state every minute, which we measured at roughly a thousand-fold more documents for zero added signal. If you adopt the heartbeat, set the interval in hours.

The detection latency for a removal is the heartbeat interval, 6 hours in our case. For an adoption campaign measured over days and weeks against a 7-day cooldown, that is not a meaningful constraint. If you need lower-latency, discrete removal events for alerting, run the emit-on-change variant instead; the snapshot model supports both.

How to filter .npmrc auth tokens before they leave the host

A snapshot-based integration sends the whole file body across the wire to the ingest pipeline. That's fine for config keys; it is not fine for .npmrc registry auth tokens. Filtering at the ingest pipeline is too late, because by then the tokens have already transited the network.

The fix is an agent-side script processor in the integration's Advanced options → Processors field. It keeps only min-release-age lines and drops everything else before the event leaves the workstation:

- script:
    lang: javascript
    source: >
      function process(event) {
        var msg = event.Get("message");
        if (msg == null) return;
        var filtered = [];
        var lines = msg.split('\n');
        for (var i = 0; i < lines.length; i++) {
          var line = lines[i].trim();
          if (line.indexOf('min-release-age') === 0) {
            filtered.push(line);
          }
        }
        event.Put("message", filtered.join('\n'));
      }

Tokens never reach the wire. We verified by adding a test token to a .npmrc on a managed host, running a cycle, and confirming zero search hits for the token string in Elasticsearch.

The npm cooldown ingest pipeline

The pipeline below is the npm-only variant of the one we run in production, and it is short enough to show whole. Grok extracts the key and value, a Set processor turns "no key found" into the explicit removal signal, and the raw message is removed before indexing:

PUT _ingest/pipeline/npm-cooldown-workstation
{
  "description": "Parses min-release-age from .npmrc snapshots",
  "processors": [
    {
      "grok": {
        "field": "message",
        "patterns": [
          "(?<cooldown.key>min-release-age)\\s*=\\s*(?<cooldown.value>[^\\n\\r]*)"
        ],
        "ignore_missing": true,
        "ignore_failure": true
      }
    },
    {
      "set": {
        "if": "ctx.cooldown?.key == null",
        "field": "cooldown.absent",
        "value": true
      }
    },
    {
      "set": {
        "if": "ctx.cooldown?.key != null",
        "field": "cooldown.unit",
        "value": "days"
      }
    },
    {
      "convert": {
        "field": "cooldown.value",
        "type": "long",
        "ignore_missing": true,
        "ignore_failure": true
      }
    },
    {
      "remove": {
        "field": ["message", "event.original"],
        "ignore_missing": true
      }
    }
  ]
}

Two details earned their place the hard way. The value capture is [^\n\r]*, which stops at both LF and CRLF line endings; an earlier revision used [^ \r]*, which truncated any value containing a space and could run across newlines. And cooldown.unit is set explicitly even though npm's unit is always days, because dashboard rows that read 7 days stay unambiguous when the telemetry later grows beyond npm.

The cooldown.absent = true event is the payoff. The host was in the index six hours ago with cooldown.key = min-release-age; the next snapshot has no key; the dashboard shows the transition. That is the removal signal filestream could not produce.

CEL vs. filestream for config file monitoring

We ran both in parallel for a few weeks and then made a call.

The core reason is the shape of the data. filestream is built for append-only logs, where new lines arrive at the end of a file and the job is to harvest them. .npmrc is a state file: npm rewrites it in place when a setting changes and deletes it when the last setting is removed. The question the telemetry needs to answer, "what is the cooldown state of this host right now, and when did it change," is a question about the current contents of a file. Tail offsets can't answer it.

| | CEL | Filestream | | :---- | :---- | :---- | | Designed for | State files (snapshot + hash) | Append-only logs (tail) | | Cooldown-line removal detection | Yes (next snapshot marks cooldown.absent) | No | | File deletion detection | Yes (host drops out of snapshots) | No | | Snapshot semantics | Whole file | Per line | | Auth-token posture | Filtered agent-side before transit | Same (agent-side allowlist) | | Fleet integration | Custom API using Common Expression Language | Custom Logs Filestream | | Config complexity | ~40-line CEL integration | Declarative path globs | | State refresh / latency | 6h heartbeat | ~10s (tail) |

Running both meant every config change produced two events into two separate datasets, and we maintained two ingest pipelines with dashboards split across indices. The complexity cost outweighs any redundancy benefit, and the only thing filestream gives that CEL doesn't is faster detection latency, which is not a meaningful constraint for adoption tracking on a 7-day cooldown.

We also considered osquery and auditd before settling on CEL. osquery can read config file contents on a schedule through its file and file_lines tables, and auditd can fire on file writes, but neither produces a clean current-state signal across ingestion, and both would mean standing up a second collection path next to the agent already deployed for endpoint telemetry.

CEL won. End-to-end validation on a single macOS workstation:

| Scenario | Expected | Result | | :---- | :---- | :---- | | npm config set min-release-age 5 | cooldown.key = min-release-age, cooldown.value = 5 | Pass | | .npmrc exists with no cooldown key | cooldown.absent = true | Pass | | npm config delete min-release-age (deletes the file) | path absent from subsequent snapshots | Pass | | Auth token line in .npmrc | No token in Elasticsearch | Pass |

npm cooldown monitoring on Linux and Windows

macOS was the primary platform; the design generalizes cleanly.

Linux needed no integration change at all. The /home block in the integration above already covers it: on each platform, the directory that doesn't exist fails the type check and collapses to an empty list, and the other side fills in. The Linux variant runs the same integration through the same ingest pipeline into the same dataset, with /etc/npmrc and /usr/lib/node_modules/npm/.npmrc in the global watch list.

Windows is a separate integration on the same dataset, and it's the one variant we designed but haven't deployed: our own fleet has too few Windows machines to justify the rollout yet. We're documenting it anyway because Windows is the most common OS in corporate fleets, so for many readers this variant is the one that matters most. The integration enumerates C:/Users/* (forward slashes work on Windows under Go/CEL), excludes Public, Default, and Default User, and watches each user's .npmrc plus the system globals under C:/ProgramData. The Grok pattern's value capture, [^\n\r]*, stops at both LF and CRLF line endings, so it works unchanged on Windows without capturing the trailing \r in the value. The agent-side script processor is also unchanged.

Rollout status and extending beyond npm

The pipeline is now reporting from several hundred macOS, each re-emitting its current npm cooldown state on the 6-hour heartbeat. We're sharing the technique at this stage so other security engineering teams can build on it; once the rollout reaches the full fleet we'll follow up with an org-wide adoption-rate post. The Windows variant stays on the shelf until our Windows population justifies the rollout; if your fleet is Windows-heavy, the design in this post is ready to adapt.

In production the same integration already watches the config files for pip, uv, pnpm, yarn Berry, and bun. That expansion deserves its own post, because cooldown values are not unit-comparable across package managers, and one manager's documentation and implementation disagree about the unit by three orders of magnitude. If you're extending this design beyond npm, check cooldowns.dev for each flag's unit before you compare values across tools.

What we learned about npm cooldown monitoring with Elastic Agent

• npm cooldown adoption telemetry is state monitoring. The signal that matters most is a host removing min-release-age, and append-driven log tailing cannot see that happen.
• A snapshot-based CEL integration produces the removal signal directly: re-emit each .npmrc's current state on a 6-hour heartbeat, and a removal shows up as the key's absence in the next snapshot.
• A time-windowed adoption dashboard needs the heartbeat, not one-shot change events, which age out of the window and make adoption look like it's eroding when it isn't.
• Small config files (under 1024 bytes) need native file identity, not fingerprint, regardless of which integration you use.
• An agent-side script processor keeps .npmrc registry auth tokens on the workstation: tokens never reach the wire.
• nvm inflates capability counts: each Node.js version ships its own npm, all of them read the shared ~/.npmrc, but only npm 11.10+ enforces the key. Track the config file, count enforcement-capable versions separately.