[Network Packet Capture]: Implement conditional installation behaviour for the Network Packet Capture integration on Windows

[tanja-milicic]

Integration Name

Network Packet Capture [network_traffic]

Dataset Name

No response

Integration Version

1.34.2

Agent Version

9.3

OS Version and Architecture

Windows

User Goal

Currently, a toggle labeled “Never Install Npcap on Windows” prevents any installation attempts. Introduce a more flexible option that installs Npcap only if a compatible version is not already present, and skips installation when one is detected.

Implement conditional installation behaviour for the Network Packet Capture integration on Windows:

• Detect if Npcap is installed.
• If not installed, install the bundled/required Npcap version.
• If installed, validate version and configuration (e.g., WinPcap API-compatible mode) and either use it as-is if compatible or present a prompt/actionable message to upgrade.
• Avoid failing with a non-actionable exit code (e.g., exit 2 when already installed). Instead, surface a clear status and next steps.

Existing Features

There is a “Never Install Npcap on Windows” toggle - when enabled, the integration never attempts to install the bundled Npcap. If Npcap is missing, the integration fails to function. If a different Npcap version is present, the integration attempts to use it but may have limited or unsupported functionality.

What did you see?

An Error in the Network Packet Capture Integration because Npcap could not be installed with exit 2

Anything else?

No response

[github-actions]

tl;dr: I recommend implementing this as policy-time conditional behavior (not package install-time conditions): add a Windows condition variable to network_traffic and wire it into all packet stream templates, while making the existing never_install toggle visible to users.

Recommendation

Use a runtime condition in the network_traffic policy template so Windows behavior is explicit and controllable in Fleet. The package manifest conditions schema is for stack/package compatibility (Kibana/Agent/subscription), not host OS targeting, so this should be solved in input/stream templates.

Findings

1. network_traffic already has a Windows-specific Npcap toggle, but it is hidden from users:
   • packages/network_traffic/manifest.yml:27-42 (never_install, show_user: false).
2. Npcap wiring exists in stream templates, but there is no host-platform condition in those templates:
   • Example: packages/network_traffic/data_stream/flow/agent/stream/flow.yml.hbs:38-41.
   • Example: packages/network_traffic/data_stream/dns/agent/stream/dns.yml.hbs:56-59.
   • Repository-wide check shows no condition: lines in packages/network_traffic/**/*.yml.hbs.
3. This repo already uses ${host.platform} runtime gating patterns in stream/input templates:
   • packages/windows_etw/agent/input/etw.yml.hbs:1
   • packages/journald/agent/input/journald.yml.hbs:1-4
   • packages/system/manifest.yml:55-63 (user-exposed condition var pattern).
4. Historical context confirms Npcap behavior was introduced previously:
   • packages/network_traffic/changelog.yml:182-186 (PR #5888).
   • Docs explicitly call out bundled Npcap on Windows: packages/network_traffic/docs/README.md:5896-5898.
5. manifest installability conditions are not host-platform selectors:
   • docs/extend/manifest-spec.md:112-169 (conditions for Elastic/Kibana/Agent compatibility).

Verification

I ran local checks in the workspace:

$ nl -ba packages/network_traffic/manifest.yml | sed -n '20,45p'
... shows never_install var at lines 27-42 with show_user: false ...

$ grep -R --line-number '^condition:' packages/network_traffic --include='*.yml.hbs'
# (no output)

$ grep -R --line-number 'never_install: true' packages/network_traffic/data_stream --include='*.yml.hbs' | wc -l
16

$ grep -R --line-number 'never_install: true' packages/network_traffic/data_stream --include='*.yml.hbs' | head -n 5
packages/network_traffic/data_stream/http/agent/stream/http.yml.hbs:103:  never_install: true
packages/network_traffic/data_stream/pgsql/agent/stream/pgsql.yml.hbs:52:  never_install: true
packages/network_traffic/data_stream/cassandra/agent/stream/cassandra.yml.hbs:64:  never_install: true
packages/network_traffic/data_stream/mongodb/agent/stream/mongodb.yml.hbs:58:  never_install: true
packages/network_traffic/data_stream/tls/agent/stream/tls.yml.hbs:55:  never_install: true

Detailed Action Plan

1. In packages/network_traffic/manifest.yml (under packet input vars near never_install), add a user-visible condition var:
   • name: condition
   • type: text
   • show_user: true
   • sensible default for Windows behavior (e.g., ${host.platform} == 'windows' for Windows-only execution, depending on desired semantics).
2. In all stream templates under packages/network_traffic/data_stream/*/agent/stream/*.yml.hbs, render the condition near the top using the same style as journald templates, e.g.:
   • if condition provided: condition: {{condition}}
   • else fallback to intended default.
3. Keep npcap.never_install propagation as-is (already present in all 16 stream templates), but make never_install visible if the UX goal is user control on Windows hosts.
4. Add/update package tests under packages/network_traffic/_dev/test to validate rendered policy for:
   • Windows host + default condition,
   • non-Windows host behavior,
   • never_install: true/false behavior.
5. Update packages/network_traffic/changelog.yml with an enhancement entry describing conditional Windows installation behavior.

Related Items

Type	Link	Relevance
Issue	#18539	Current triage target
PR	#5888	Introduced never_install support for Npcap
File	packages/network_traffic/manifest.yml	Contains hidden never_install var and policy template vars
File	packages/network_traffic/data_stream/flow/agent/stream/flow.yml.hbs	Representative stream template lacking condition:
File	packages/journald/agent/input/journald.yml.hbs	Existing conditional template pattern (${host.platform} + user condition)
Spec	docs/extend/manifest-spec.md	Confirms package conditions are compatibility-oriented, not host OS gating

Note

🔒 Integrity filter blocked 28 items

The following items were blocked because they don't meet the GitHub integrity level.

• #18539 issue_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #18539 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #13566 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #7641 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #11952 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14312 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #15679 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #9192 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #11665 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #5763 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #6582 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #3525 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #2363 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #17560 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #15665 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14648 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• ... and 12 more items

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

---

What is this? | From workflow: Issue Triage

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[elasticmachine]

Pinging @elastic/sec-linux-platform (Team:Security-Linux Platform)