fapolicyd 2.0: Writing fapolicyd Rules with Globs and Paths with Spaces

Fapolicyd rules normally explain what to do with each file type. They follow a pattern of "if this file type is trusted, allow it. If not deny it". But sometimes you have to carve out certain areas for specific uses. In those situations, fapolicyd policy normally uses exact values. An exact executable or object path is easy to review and does not match anything else by accident.

fapolicyd 2.0 adds two related rule-writing tools:

glob:     opt in to fnmatch-style matching for exe and path
"..."     keep one complete rule value together when it contains spaces

The important point is that quoting and globbing are separate. Quotes preserve spaces in a rule value. The glob: prefix requests pattern matching. A value can use neither, either one, or both.

Three ways to express a path

Use an exact path or exe value when the name is known:

allow perm=execute all : path=/usr/bin/id trust=1

Use dir when the policy applies to a complete subtree rooted at a fixed directory:

allow perm=open all : dir=/opt/vendor/ trust=1

Use glob: only when one or more path components must vary:

allow perm=execute all : path=glob:/opt/vendor/release-*/bin/tool trust=1

The glob: prefix is accepted only for subject exe and object path. A glob pattern must be an absolute path. dir deliberately remains a literal directory-prefix match, even if its text contains *, ?, or [.

Exact values, directory prefixes, and explicit globs express different policy shapes.

What a glob matches

Patterns use fnmatch(3) syntax and match the entire concrete path.

*        zero or more characters within one path component
?        exactly one character within one path component
[0-9]    one character from a bracket expression

Very important - wildcards do not cross /. For example:

glob:/home/*/bin/tool

matches:       /home/alice/bin/tool
does not match: /home/alice/project/bin/tool

A wildcard also does not match a leading period unless the pattern names the period explicitly. glob:/home/*/bin/tool does not match /home/.admin/bin/tool, while glob:/home/.*/bin/tool does.

Matching is case-sensitive. Recursive ** globstar matching is not supported. Bracket ranges and named character classes use the daemon's active locale, so use exact alternatives or explicit characters when the same policy must behave identically under every locale.

An unprefixed value remains exact, even if it contains metacharacters:

path=/tmp/name*

matches a literal file named /tmp/name*. To match names such as /tmp/name1, use path=glob:/tmp/name* instead.

fapolicyd obtains object paths from the event file descriptor and subject executable paths from /proc/<pid>/exe. Symbolic links have therefore already been followed. Rules normally match the target path, not the link name used by the application. Hard links and mount aliases can expose different concrete paths for one inode, so policy that must cover those aliases needs a value or
pattern for each reported path.

Paths and directories with spaces

Rule fields are separated by spaces. Enclose a complete string value in double quotes when that value contains a space. The quotes are syntax; they are not part of the path used for matching.

allow perm=execute all : path="/opt/Vendor Tools/bin/tool" trust=1
allow perm=open all : dir="/srv/Team Files/" trust=1
allow perm=open exe="/opt/Vendor Tools/bin/runner" : all

This applies to subject exe, subject and object dir, and object path. Double quotes also work in named string-set definitions and in each comma-separated string value.

To combine the features, quote the complete glob value, including the prefix:

allow perm=execute all : path="glob:/opt/Vendor Tools/release-*/bin/tool" trust=1
allow perm=open exe="glob:/opt/Vendor Tools/release-*/bin/runner" : all

The quotes are removed before glob validation and matching. A quoted dir="glob:/srv/Team Files/" is still an error: dir does not accept globs.

Quote the entire glob value when a pattern contains spaces.

Only double quotes are rule-file quoting. Shell-style single quotes and a backslash before a space are not rule-file quoting forms. %20 is also literal in a rule value; it does not become a space. Inside a quoted value, \" represents a double quote and \\ represents one backslash. Other backslashes are preserved so a glob can still quote its own metacharacters.

Named sets can mix exact values and globs

Named string sets are useful when several rules share a path list. Each pattern in a set or comma-separated value needs its own glob: prefix:

%vendor_tools="/opt/Vendor Tools/bin/tool","glob:/opt/Vendor Tools/release-*/bin/tool"

allow perm=execute all : path=%vendor_tools trust=1

The first set member is exact. The second is a pattern. The rule engine checks the exact values first, then evaluates the marked patterns when needed.

This does not change rule ordering. fapolicyd evaluates rules from top to bottom, and the first complete rule match decides the access. A broad glob before a narrower exact allow or deny can therefore determine the result first.

Keep trust separate from path selection

A glob determines whether a path fits a rule. It does not add the path to the trust database or prove who can write it.

For an allow rule covering a user-writable location, normally pair an object path glob with trust=1 or an explicit FILE_HASH constraint. A subject exe glob in such a location should normally include subject trust=1. The same guidance applies to exact paths when the location is writable by an untrusted principal.

Prefer exact paths, exact named sets, or dir when they express the policy. They are simpler to review and avoid pattern evaluation. Use a glob for the specific variable component that policy needs to express.

Safe syntax demos

The following validation demo creates a temporary policy file only. It does not load the rules into a running daemon. Run the following command:

tmp_rules="$(mktemp)" && \
printf '%s\n' 'allow perm=execute all : path="/tmp/first last/tool" trust=1' 'allow perm=execute all : path="glob:/tmp/first last/release-*/bin/tool" trust=1' > "$tmp_rules" && \
fapolicyd-cli --check-rules "$tmp_rules"; rc=$?; \
rm -f "$tmp_rules"; exit "$rc"

--check-rules validates quotes, the glob: prefix, the allowed attributes, and the absolute-path requirement. It does not expand a pattern or simulate which concrete paths it matches.

Use a deliberate invalid rule to see why a fixed subtree belongs in dir and a variable path belongs in path. Run the following command:

tmp_rules="$(mktemp)" && \
printf '%s\n' 'allow perm=execute all : dir="glob:/tmp/first last/" trust=1' > "$tmp_rules" && \
fapolicyd-cli --check-rules "$tmp_rules"; rc=$?; \
rm -f "$tmp_rules"; echo "exit status: $rc"

The command should report that glob: is valid only with exe and path.

For an installed rules.d policy, assemble and validate the candidate without replacing compiled.rules:

sudo fagenrules --check

If you are testing a source checkout, the focused parser and matching regressions are also available through:

make -C src/tests check TESTS=rules_test

The practical rule

Use quotes to keep a path with spaces together. Use glob: to make a path component variable. Use both by quoting the complete glob: value.

Keep dir for fixed subtrees, keep trust constraints separate from path selection, validate proposed rules before installation, and preserve rule order as part of the policy's meaning.

The complete reference is fapolicyd.rules(5). For release context, see the fapolicyd 2.0 overview article examining decision workers.

fapolicyd 2.0: Parallel Decision Workers and Policy Updates

fapolicyd 2.0 introduces parallel decision workers and several policy-authoring updates. Decision workers let the daemon process independent subjects in parallel. Also new in 2.0, policy authors can use explicit path globs, quote rule values that contain spaces, and extend the built-in %languages MIME set from a package rule fragment.

This is an overview of the release. The decision-worker architecture, glob rule contract, and Debian trust filter each have enough operational detail for future articles. Here, the goal is to show what changed, how to observe it, and where to start on a test system.

Parallel decision workers

fapolicyd receives permission events through fanotify, evaluates policy, and returns a response to the kernel. In 2.0, the fanotify reader acts as a dispatcher. It assigns each permission event to a decision worker, and that worker evaluates the event and owns the response.

The configuration option is:

decision_threads = 1

The default remains one worker. With a larger value, the dispatcher routes a process's events to one stable worker using its PID. That preserves the order seen by the subject startup and pattern-detection state for that process. It also means that a busy single process stays on one worker; worker parallelism comes from activity across independent processes.

Each worker owns an event queue, decision context, subject cache, object cache, and subject-slot defer array. This keeps mutable decision state local to the worker that evaluates the event. Queue, cache, and defer statistics remain available both as aggregate totals and as per-worker detail.

fapolicyd 2.0 dispatches each process's events to a stable decision worker.

 

Choosing a worker count

decision_threads is a capacity setting, not a value to maximize automatically. Start with the default and use the reports under a representative workload. Consider adding a worker when queue pressure is persistent: a high inter-thread maximum queue depth relative to q_size, a non-zero queue-full count, or a growing oldest queued age.

Inspect the relevant report sections, run the following commands :

fapolicyd-cli --check-status | sed -n '/Resource configuration:/,/Resource utilization:/p'
fapolicyd-cli --check-metrics | sed -n '/Inter-thread queue & defer activity:/,/Subject cache effectiveness:/p'

The per-worker lines matter. One worker with a deep queue while others are idle is useful evidence of routing skew. Stable process ownership is intentional, so queue-depth balancing does not move that process's events to another worker.

On a test system, change the count from one to two, restart fapolicyd, and compare the same workload and reports. If aggregate queue pressure decreases without undesirable resource pressure, increase in small steps and repeat the comparison. The configured count cannot exceed the number of online CPU cores or the daemon's resource limits.

The resource cost scales with the worker count. q_size, subj_cache_size, and obj_cache_size are per-worker settings, as is the derived defer-array capacity. Leaving those values unchanged increases total queue and cache capacity. Reducing them to hold memory use steady can increase cache collisions, evictions, and defer fallbacks. The daemon also reserves LMDB reader slots and validates the file-descriptor and fixed-memory budgets at
startup.

decision_threads requires a restart because workers and their resources are created during daemon startup:

# /etc/fapolicyd/fapolicyd.conf
decision_threads = 2

sudo systemctl restart fapolicyd

The worker follow-up article will cover routing, report interpretation, skew, capacity planning, and staged test workloads in more depth.

Worker health and service supervision

The status report identifies the configured worker count and reports health, current queue depth, maximum queue depth, queue-full count, and oldest queued age for each worker. The metrics report includes the corresponding aggregate and per-worker queue, cache, and defer counters. This makes it possible to distinguish overall pressure from a single hot worker.

When built with the default systemd watchdog support, the installed service uses Type=notify, runs fapolicyd in the foreground, and sets WatchdogSec=10s. The daemon reports readiness after startup and sends watchdog messages while the health monitor sees decision workers making progress. A stalled worker with queued work is recorded as a worker_stall failure action, after which systemd applies the unit's restart policy.

Use a systemd drop-in to adjust WatchdogSec for an environment with known slow storage. Builds configured with --disable-systemd-watchdog install the legacy forking service unit instead. See doc/systemd-watchdog.md in the source tree for the complete service contract.

Policy drop-ins and MIME classification

The installed %languages set identifies MIME types that policy treats as language or interpreter content. A package can add a MIME type without editing the distribution-owned definition. Place a naturally ordered macro fragment after 10-languages.rules and before policy rules:

# /etc/fapolicyd/rules.d/11-vendor-languages.rules
%languages+=application/x-vendor-script

The += form is limited to %languages. It adds to the existing set rather than replacing it, and a repeated MIME type is harmless. Run fagenrules after adding or removing the fragment. The MIME type must already be emitted by fapolicyd's file type detector or the system magic database; adding it to the set does not create file type detection.

The ignored-mount risk report now reads the effective compiled policy, so it also recognizes MIME types added through %languages+= fragments. This keeps the policy and the operational report aligned.

 

A package policy fragment can extend the effective %languages MIME set without replacing the distribution-owned definition.

Use --ftype-ext when a script needs both the supplied path and fapolicyd's MIME type. Each invocation writes two NUL-terminated fields to standard output: the path, followed by the MIME type. The interface is intentionally binary; use --ftype for interactive, MIME-only output.

A pathname component can contain spaces, tabs, newlines, quotes, backslashes, colons, terminal-control sequences, and other bytes except NUL and /. A line or colon delimiter could let one of those bytes create an apparent second record or misleading terminal output. NUL framing preserves the path/MIME boundary, but does not make a path safe for shell evaluation or terminal display.

A Bash consumer can read one or more pairs safely:

for file in "$@"; do
    fapolicyd-cli --ftype-ext="$file"
done |
while IFS= read -r -d '' path &&
    IFS= read -r -d '' mime
do
    printf 'path=%q mime=%q\n' "$path" "$mime"
done

Do not use command substitution, unquoted expansions, eval, or newline-delimited file lists for these values. Quote variables when passing paths to commands, and use find -print0 with the same NUL-aware read pattern when discovering paths.

Quoted rule values

Rule values for subject exe, subject or object dir, and object path can now use double quotes when the complete value contains a space:

allow perm=execute all : path="/opt/vendor/My Tool/bin/tool" trust=1

Double quotes also work in named string sets and comma-separated string values. They are rule-file syntax rather than part of the value used for matching. Use shell quoting, rather than rule quoting, when passing a path with spaces to a CLI command.

Explicit path globbing

Rules can now use fnmatch patterns for subject exe and object path attributes. Pattern matching is explicit: prefix a pattern with glob:. Unprefixed values remain exact, so a literal *, ?, or [ in an existing path rule keeps its exact-path meaning.

Patterns must be absolute paths. They do not match a leading period implicitly, and do not support recursive ** matching. The dir attribute remains a literal directory-prefix match. A glob selects a path; it does not make that path trusted, so allow rules for writable locations should normally retain trust=1 or an explicit FILE_HASH constraint.

Globbing will be covered in a future blog, including quoted glob values, named sets, literal metacharacters, rule order, symbolic-link behavior, and policy test cases.

Other operational changes

fagenrules now builds its output in a temporary file, validates it with the daemon policy parser, and atomically renames a successful candidate into compiled.rules. It prints a SHA-256 ruleset identity for an unchanged or installed ruleset. Use fagenrules --check before an update to determine whether the assembled policy differs without replacing compiled.rules. The rule assembler also handles rule-unit file names containing spaces.

For permission events that need a decision log, fapolicyd renders the selected record while the subject is still available, sends the fanotify response, then hands the owned text to the asynchronous logger. The bounded logger queue serializes accepted records through one drain thread.

The Debian debdb source applies fapolicyd-filter.conf before package-owned paths enter its helper-produced trust snapshot. On package sets where the filter excludes many files, this can reduce active LMDB pages, memory residency, and trust lookup time. Debian filter configuration and measurements will be covered in a future blog.

For RPM trust data, rpm_sha256_only=1 applies a SHA-256-or-stronger digest floor during RPM import and relevant SHA-256 or IMA integrity lookups. The configuration and integrity mode together determine whether that policy is appropriate for a system.

The practical takeaway

Use decision workers when reports show queue pressure under the workload that matters to the system. Begin at one, test two, and increase only when the measurements justify the additional per-worker resources.

Use glob: when a policy genuinely needs a variable path component, and use double quotes for a complete rule value with spaces. Package policy can extend %languages without replacing its base definition. Keep exact paths and dir matches where they express the policy, and retain trust constraints when a pattern can cover writable locations.

The relevant references are fapolicyd.conf(5), fapolicyd.state(5), fapolicyd.metrics(5), fapolicyd.rules(5), and fagenrules(8). The upstream project is fapolicyd on GitHub.

fapolicyd 1.6: Using fapolicyd's ignore_mounts Risk Report

ignore_mounts is a performance option that removes fapolicyd visibility from a mounted tree. That can be useful for data-only mounts with high file churn, such as cache, log, or content-serving partitions. It should not be used to make policy denials disappear, and it should not be used for trees that applications treat as code or runtime input.

The practical rule is:

• ignore_mounts is for data-only mounts.
• noexec is required, but noexec is only the first check.
• The risk report shows whether the ignored tree still looks like code. 

 

What ignore_mounts means

The ignore_mounts option is configured in fapolicyd.conf. It is a comma-separated list of absolute mount points that fapolicyd should not watch, even if the filesystem type is otherwise listed in watch_fs.

The paths must match the mount point names shown by /proc/mounts. The root filesystem is always monitored, and ignore_mounts cannot be combined with allow_filesystem_mark=1.

Each ignored mount must be mounted with noexec. If it is not, fapolicyd warns and monitors the mount instead.

That is the configuration side. The policy side is just as important: when a mount is ignored, fapolicyd does not receive the normal file access events for that mounted tree. Opens and reads inside that mount are not evaluated by fapolicyd policy.

This is why the option belongs on data-only mounts. It is reasonable to ignore a tree whose contents are logs, cache objects, uploaded documents, or other data that the workload does not load as code. It is not reasonable to ignore a runtime tree, plugin directory, dependency cache, developer workspace, or application install path.

Why noexec is required

The first guardrail is noexec. The Linux mount command documents noexec as a mount option that prevents direct execution of binaries from that filesystem mount(8).

That is necessary, but it is not sufficient.

noexec helps with direct execve() from the ignored mount. It does not mean the content is inert. A trusted program can still read files from that tree. Interpreters, plugin systems, Java runtimes, browser stacks, build tools, and application frameworks often treat files as instructions even when the kernel does not execute those files directly.

The risk is the blind spot. The kernel may block direct execution, but fapolicyd will not see a trusted runtime reading code-like content from an ignored mount.

noexec blocks direct execution, but ignored mounts still create blind spots for interpreter and plugin reads

What changed in fapolicyd 1.6

--check-ignore_mounts already existed. Earlier releases checked whether the ignored mount was mounted noexec and looked for files matching the %languages macro.

fapolicyd 1.6 expands that operational check. The command still starts with the mount itself: whether the path exists, whether it is a directory, whether it is a mount point, and whether noexec is present. It then reports several risk categories:

• executable regular files
• ELF/shared objects
• archives/JARs/ZIPs
• bytecode caches
• plugin/runtime directories
• language/interpreter files

This is a natural evolution of providing all necessary information to make an informed decision. It is a broader evidence report for administrators who already chose, or are considering, an ignored mount.

Run the configured check:

fapolicyd-cli --check-ignore_mounts

Check one proposed mount:

fapolicyd-cli --check-ignore_mounts=/path/to/mount

Use verbose mode when you need the evidence behind the counts:

fapolicyd-cli --check-ignore_mounts=/path/to/mount --verbose

The summary is the quick view. --verbose shows the matching paths, the category, and MIME information when file type detection is available.

What the categories mean

The categories are practical signals. They do not prove that a file is malicious. They answer a narrower question:

Does this ignored mount still look data-only?

Executable regular files are not automatically a vulnerability. On a mount that is supposed to be data-only, they are still useful evidence. An executable bit often means somebody expected the file to be run.

ELF/shared objects are native code. For a temporary download area, a few ELF files may be artifacts waiting to be scanned, unpacked, moved, or deleted. For a runtime path, plugin path, library path, application directory, or developer tree, they are a much stronger warning.

Archives/JARs/ZIPs are archives. They can hold documents, and they can hold code. JARs are the obvious case because Java runtimes consume them directly, but ZIP, wheel, egg, WAR, EAR, APK, tar, and compressed archives can also deliver programmatic content.

Bytecode caches are runtime-consumed programmatic content. Python .pyc files, Java .class files, WebAssembly modules, Emacs Lisp bytecode, Lua bytecode, and __pycache__ directories are all signals that the mount is not just inert data.

Plugin/runtime directories are directory-name signals, not proof. Names such as site-packages, node_modules, vendor, plugins, extensions, and gems should make an administrator ask which process reads from the tree and whether that process treats the contents as code.

Language/interpreter files are the original %languages style check. A trusted interpreter may still be able to run a script from an ignored noexec mount:

python3 /ignored/script.py

If fapolicyd is not watching that mount, it will not see the interpreter open the script.

Reading the report

Read the report as a risk review, not as a magic yes/no scanner.

A clean result is the easiest case:

• the mount exists
• the mount is noexec
• risky category counts are zero
• the mount is genuinely data-only
• write access is controlled
• the workload does not load code from it

That does not mean risk is literally zero. It means the mount matches the design intent of ignore_mounts.

A mixed result needs context. Archives in a controlled intake area, stale executable bits on inert files, language files that no trusted interpreter reads, or empty plugin-looking directories may be explainable. This is where --verbose matters:

fapolicyd-cli --check-ignore_mounts=/path/to/mount --verbose

If the output is explainable, fix what can be fixed and document what remains. Useful controls include:

• remove stale executable bits
• move code and plugins to watched filesystems
• split data and runtime dependencies onto separate mounts
• restrict write access to the ignored mount
• run the check after application updates
• scan archive contents in a separate intake process

Some results should stop the change. Do not ignore a mount that contains active runtime directories, dependency trees, shared objects, language source, bytecode, or JARs that applications use directly.

Common stop cases include developer workspaces, home directories, application install directories, plugin directories, Python virtual environments, node_modules trees, Java application trees full of jars, container or image build directories, and shared writable locations where users can add scripts or code.

The problem is not that every file in those directories is bad. The problem is that the mount is not data-only. Ignoring it trades away policy visibility in a place where policy visibility is useful.

The ignored-mount risk report helps sort data-only mounts from runtime content that should stay watched.

Exit status and review evidence

The command is usable in automation. A clean scan returns zero. Risk findings return non-zero so automated workflows can gate a proposed change.

For a proposed mount, capture both the report and the exit status:

fapolicyd-cli --check-ignore_mounts=/path/to/mount; echo "exit status: $?"

If the summary is not clean, include the verbose report:

fapolicyd-cli --check-ignore_mounts=/path/to/mount --verbose; echo "exit status: $?"

The exit status should not replace judgment. It should prevent accidental approval. A non-zero result means somebody needs to look at the matching paths and decide whether the mount is still appropriate for ignore_mounts.

For a change review, ask for:

• why the mount needs to be ignored
• proof that it is mounted noexec
• the --check-ignore_mounts summary
• the --verbose output if any category is non-zero

Show the active mount options:

findmnt -no TARGET,OPTIONS /path/to/mount

Then include the fapolicyd report:

fapolicyd-cli --check-ignore_mounts=/path/to/mount

That gives reviewers enough context to tell the difference between a data-only
cache partition and an application runtime tree.

A compact demo

A short demo can show why noexec and "data-only" are different claims. Use a throwaway mount, add representative files, run the checker, and remove the mount.

sudo mkdir -p /mnt/fapolicyd-ignore-demo
sudo mount -t tmpfs -o noexec,nosuid,nodev tmpfs /mnt/fapolicyd-ignore-demo
sudo install -m 755 /bin/true /mnt/fapolicyd-ignore-demo/native-helper
sudo mkdir -p /mnt/fapolicyd-ignore-demo/app/{__pycache__,site-packages}
printf 'print("hello")\n' | sudo tee /mnt/fapolicyd-ignore-demo/app/demo.py >/dev/null
printf 'not really bytecode\n' | sudo tee /mnt/fapolicyd-ignore-demo/app/__pycache__/demo.pyc >/dev/null
fapolicyd-cli --check-ignore_mounts=/mnt/fapolicyd-ignore-demo --verbose; echo "exit status: $?"
sudo umount /mnt/fapolicyd-ignore-demo
sudo rmdir /mnt/fapolicyd-ignore-demo

The useful part of the output is not the exact MIME string. It is that one ignored noexec mount can still produce concrete code-like risk categories.

The practical rule

ignore_mounts is a performance option with a security cost. Use it when the mount is data-only and the report agrees with that story.

If the report shows a few explainable artifacts, clean them up or add controls before moving ahead.

If the report shows active code, runtime dependencies, plugins, bytecode, shared objects, or interpreter files that applications use directly, do not ignore the mount. Split the data from the code, keep the runtime content on a watched filesystem, or solve the performance problem another way.

The improved --check-ignore_mounts report does not make the decision for you.
It gives you the evidence needed to make the decision defensibly.

fapolicyd 1.6: Manually Sizing the fapolicyd Trust Database

The earlier articles in this series separated fapolicyd status, metrics, and timing into reports that answer different questions. This article is about one practical status question:

How big should the trust database be?

The short answer is that most systems should use:

db_max_size = auto

A fixed value can still make sense when configuration management requires explicit limits, disk allocation needs review, or change control prefers known bounds. If you set the trust database size manually, you need to know what is being sized and how much room reloads can need.

This article explains generation-aware trust database state, the separate LMDB environment generation, and how to read the status report when choosing a manual db_max_size.

What the Trust Database Stores

Trust is one of the inputs used by fapolicyd policy. The trust database is the compact lookup table for trusted file records. The configured trust backends provide the input: rpmdb builds records from the package database, and the file backend reads local trust files for software that is not package-managed.

A dumped trust record shows the trust source, path, size, and recorded digest. The size and digest are used when the configured integrity mode asks fapolicyd to verify that the file on disk still matches the trusted record.

For sizing, think in records rather than path length. A trust entry occupies one fixed-size record slot. A short path and a long path still consume one record; they just leave different amounts of padding inside that record. The useful sizing questions are how many records exist, how many generations may be present during reload, and how much LMDB environment headroom remains.

The trust database is stored in LMDB. LMDB uses a memory-mapped environment with a configured maximum map size. That maximum is what `db_max_size` controls in fapolicyd.conf.

The current trust database code stores logical trust contents in named LMDB databases. A small metadata database records which named database is active. During reload, a separate candidate named "database" can be built from backend snapshots and then published as the new active generation.

If the map is too small, LMDB can return MDB_MAP_FULL. In practical terms, fapolicyd did not have enough LMDB map space to complete the write operation it was trying to do.

Why Generations Matter

It is tempting to describe a trust database reload as replacing old contents with new contents. For a live daemon, the more useful model is generation-aware state.

fapolicyd already performs reload, update, and new mount handling at controlled points in its event loop. The 1.6 work makes the identity and ownership of live state more explicit: decision configuration, rules, trust contents, and LMDB storage can be reported as distinct generations. That is an operational improvement today and a clearer ownership model for future decision workers.

There are two related but different generation concepts:

• Trust database generation   logical trust contents inside LMDB
• LMDB environment generation physical data.mdb file generation

The trust database generation is the normal trust reload mechanism. During a reload, fapolicyd builds a candidate named "database" inside the existing LMDB environment and imports backend snapshots into it. Only after the candidate is complete does the daemon publish it as the active trust database generation.

Readers that already started on the old generation keep using it until they finish. New readers move to the new generation. When no readers are left on the old generation, fapolicyd can reclaim it.

Trust database generations let fapolicyd publish a complete candidate while old readers finish on the previous generation.

This model is useful in three ways:

1. Readers get a stable generation for the decision they already started.
2. Failed reloads preserve the last good trust database.
3. Status can report active, retired, and delayed trust generations explicitly.

That last point is important for operations. The report can show which trust generation is active, when it took effect, how many entries it has, and whether retired generations are still waiting for readers to drain.

Environment Generations and High-Water Pages

The LMDB environment generation is not the normal trust reload mechanism. It identifies the physical LMDB environment itself.

LMDB stores data in data.mdb. The map size is the maximum size of that memory-mapped environment. It is not the same thing as active trust data, and it is not the same thing as resident memory. The kernel maps the environment and backs pages as they are used.

The high-water mark is the highest LMDB page number reached inside data.mdb. In the status report, Trust database allocated high-water pages is a storage/allocation measurement for the LMDB environment. It tells you how far the environment has grown, not how many pages the active trust generation currently needs.

Reload churn can make the high-water mark larger than the active trust database. LMDB is copy-on-write, and rebuild-style updates can leave free pages inside the environment. Those unused pages may be reused later, but the data.mdb file does not necessarily shrink just because the active generation is smaller. Compaction rewrites the environment so those holes no longer inflate the on-disk file. A smaller, denser environment can also slightly reduce lookup work, but the main benefit is storage cleanup.

Normal trust database generations publish logical contents inside the current environment. They do not replace the LMDB environment.

Environment replacement is the heavier operation. fapolicyd builds a replacement LMDB environment in a temporary directory from backend snapshots, validates it, closes the live environment during a controlled maintenance window, swaps the replacement data.mdb into place, and reopens LMDB. If validation, rename, or reopen fails, the old environment is preserved or restored.

 

Trust DB generations publish logical contents; LMDB environment generations mark physical data.mdb replacement.

 

That distinction matters for sizing. A normal reload needs enough space to build a candidate generation while the current generation still exists. Compaction resets the physical high-water mark, but it does not make an undersized manual map large enough. If the final active database and reload working set need more room than db_max_size provides, increasing the map size is the answer.

The Status Fields to Watch

Start with the status report:

fapolicyd-cli --check-status

For trust database sizing, capture the resource configuration and resource utilization sections:

fapolicyd-cli --check-status | sed -n '/Resource configuration:/,/Health indicators:/p'

The important fields are:

Trust database max pages
Trust database pages in use
Trust database allocated high-water pages
Retired trust database generations
Oldest retired trust database generation age
Max trust database generation reclaim delay
Trust database resize recommended
Trust database resize reason
Trust database resize target
Trust database compaction recommended
Trust database compaction reason
Trust database compaction target

Trust database pages in use is the active trust database footprint.

Trust database allocated high-water pages is the LMDB environment high-water mark: how much of data.mdb has been allocated inside the map. It can be higher than active pages after reload churn because unused pages may remain in the file until reuse or compaction.

Trust database resize recommended is the field to watch when you manually set db_max_size. It is shown only for numeric manual sizing. It is omitted when db_max_size = auto because auto mode is expected to size the map itself.

If the resize recommendation is yes, the status report also prints Trust database resize target. That is the recommended minimum size in MiB for reload headroom.

Why Reload Needs Headroom

This is the sizing change administrators are most likely to run into on 1.6.

The new trust database reload path builds a candidate generation while the current generation remains available to readers. For a period of time, the LMDB environment needs room for both generations, plus copy-on-write metadata and freelist work before old pages can be reused.

That means a manual map that was large enough for one active trust database may be too small for the 1.6 reload model. Manual sizing now has to account for roughly two trust generations being present during reload. The easier answer is to set:

db_max_size = auto

and let fapolicyd apply the same reload-headroom logic it reports in status.

The manual recommendation is based on reload headroom, not only the final active database size:

• active trust data should not consume the whole map
• reload working set should have room for current plus candidate generation

The active target is about steady-state operation. The reload target is about package updates, trust-file updates, and daemon reloads that would otherwise hit MDB_MAP_FULL.

Manual db_max_size needs room for the active trust DB, the candidate generation, and LMDB reload overhead.

How to Choose a Manual Size

If you still want a manual value, start from the daemon's recommendation. Run the status report after the trust database is current and after the system has the package set you expect to run in production.

If status says:

Trust database resize recommended: yes
Trust database resize target: N MiB

then N MiB is the minimum value to use for db_max_size.

Add margin on systems that change often. Package count can grow; language runtimes, developer tools, Java stacks, browser stacks, container tools, and large application suites can add many trusted files. Local trust files under /etc/fapolicyd/ can add entries outside the package database.

A reasonable manual process is to install the expected package set, add expected local trust files, restart fapolicyd, run fapolicyd-cli --check-status, use at least the reported target if resize is recommended, add local growth margin, and check again after several package update or trust reload cycles.

Changing db_max_size in the file does not replace the active LMDB map sizing policy. After editing /etc/fapolicyd/fapolicyd.conf, restart the daemon and check status again.

For fleets, prefer db_max_size = auto unless there is a specific reason to enforce one fixed value everywhere. Different VMs can have different package and local trust footprints, and auto mode lets each host size to its actual database.

Resize Is Not Compaction

The status report has both resize and compaction guidance because they solve different problems.

Resize means the configured map is too small for the reload target. The fix is to increase db_max_size or use auto sizing.

Compaction means the LMDB environment high-water mark is much larger than the active trust database footprint. The fix is a controlled environment rebuild, usually at startup or through the administrative compaction command.

These are easy to confuse. If active pages are large and the resize target is above your manual db_max_size, compaction will not solve the capacity problem. The rebuilt environment still has to fit the active data and future reload working set.

If active pages are modest but allocated high-water pages are high, status may recommend compaction. That is a file layout and high-water reset problem, not necessarily a sign that the final trust data is too large.

If compaction is recommended and you are in a maintenance window, use the administrative compaction command and then check status again:

sudo fapolicyd-cli --compact-trustdb && fapolicyd-cli --check-status

A successful controlled replacement should advance the LMDB environment generation.

What Can Make the Database Grow

More installed trusted files generally mean more trust database entries, but package count is not the only input. Developer workstations often have more language runtimes, interpreters, plugins, browser components, build tools, and nested toolchains than small servers. Local trust files can add application trees under /opt, vendor software outside the package manager, or internal tools copied by configuration management.

Path length is not a useful manual sizing heuristic. A 10-character path and a 400-character path both consume one trust record slot; the difference is padding inside the fixed record. Use the status report and its resize target rather than path shape.

Reload frequency matters for high-water behavior. Repeated package updates, trust updates, and reload tests can push LMDB's allocated high-water mark up even when the final active database returns to roughly the same size.

Long-lived readers matter for reclamation. If retired trust generations remain pinned, old named databases cannot be reclaimed yet. The status report shows retired generation count and age so you can tell whether readers are delaying cleanup.

What Happens If Manual Size Is Too Small

If the manual map is too small, fapolicyd will not silently increase it. On reload, fapolicyd tries to preserve the last good trust database if the new candidate cannot be built. That means a failed reload does not complete the update, but the old trust contents remain active.

The status report is meant to make that risk visible before it becomes an operational problem. The warning sign is:

Trust database resize recommended: yes

The action is to increase db_max_size to at least the reported target, with whatever additional margin your environment needs.

The Simpler Answer

Manual sizing can be done, and the status report gives enough information to distinguish three situations: the map is too small for reload headroom, the file high-water mark should be compacted, or old readers are delaying generation reclamation. That is better than guessing from a generic database-full message.

But LMDB map sizing still has to account for the active database, candidate generation, copy-on-write behavior, high-water growth, package churn, local trust files, and reader lifetimes. It is easy to choose a number that works today and is too small after the next package set change.

The recommended answer is to switch to:

db_max_size = auto

Auto sizing lets fapolicyd apply the same sizing logic when it starts or rebuilds the trust database. Manual sizing is still available for sites that need it, but auto sizing is the better default for most systems.

fapolicyd 1.6: Generation-Aware State and Worker-Ready Internals

The fapolicyd 1.5 release was about making important failure modes visible and making rule reloads transactional. The 1.6 release builds on that by making more live daemon state explicit, reportable, and easier to hand off safely.

The short version is:

Give live daemon state a generation identity.
Report that identity in status and metrics.
Preserve the last good trust database if a rebuild fails.
Move mutable decision state toward explicit ownership.

That sounds like a lot of internal engineering work, and it is. But it improves normal operations in visible ways. Reports can now say which generation of config, rules, trust content, and LMDB storage is active. A failed trust database rebuild should not destroy the last good trust database. A maintenance command should not silently replace the physical LMDB storage without a controlled handoff.

fapolicyd 1.6 makes more live state generation-aware. The daemon can report which generation is active, and the decision path can hold/pin the generation it needs while evaluating an access request.

This release also prepares the daemon for a future with multiple decision threads. It does not turn on a worker pool yet. Instead, it removes several shared mutable assumptions that would make a worker pool unsafe. That is really the importance of the 1.6 release - its preparation for the 2.0 release which will bring multiple decision worker threads.

 

fapolicyd 1.6 reports and manages live state as generations, giving decisions a coherent view of the state they use.

 

Generational configuration

Configuration reloads are easy to underestimate.

Some settings can only be set at startup. Queue size, cache size, daemon uid/gid, fanotify mark configuration, and the trust database map sizing policy are tied to long-lived runtime objects. They still require a restart.

Other settings affect decisions while the daemon is running. In 1.6, the decision-used settings are published as an immutable configuration generation. That currently includes fields such as permissive mode and integrity mode.

The important behavior is not just that the values can be reloaded. The important behavior is that a decision does not mix values from different reloads. When a permission event starts, fapolicyd pins the active decision configuration generation. That same generation is used while the event is constructed, evaluated, logged, audited, and answered.

This is the kind of operational property administrators expect from a long running policy daemon. Reloads should be observable. They should be atomic from the point of iew of work already in progress. They should leave enough evidence in status and metrics reports to explain which version of live state was active.

Run this on a test system with fapolicyd running:

printf 'Before reload:\n' && \
fapolicyd-cli --check-status | grep -E '^(Config generation|Ruleset generation|Trust database generation|LMDB environment generation):' && \
printf '\nMetrics context:\n' && \
fapolicyd-cli --check-metrics | grep -E '^(Last metrics reset|Config generation|Ruleset generation|Trust database generation|LMDB environment generation|Trust database entries|Trust DB lookups|Trust DB reader slots full):' && \
printf '\nAfter reload:\n' && \
sudo kill -HUP "$(cat /run/fapolicyd.pid)" && \
fapolicyd-cli --check-status | grep -E '^(Config generation|Ruleset generation|Trust database generation|LMDB environment generation):'

Before reload:
Config generation: 1 (effective since 2026-07-03 14:09:18 -0400)
Ruleset generation: 1 (effective since 2026-07-03 14:09:18 -0400)
Trust database generation: 1 (effective since 2026-07-03 14:09:24 -0400)
LMDB environment generation: 1 (effective since 2026-07-03 14:09:23 -0400)

Metrics context:
Last metrics reset: never
Config generation: 1 (effective since 2026-07-03 14:09:18 -0400)
Ruleset generation: 1 (effective since 2026-07-03 14:09:18 -0400)
Trust database generation: 1 (effective since 2026-07-03 14:09:24 -0400)
LMDB environment generation: 1 (effective since 2026-07-03 14:09:23 -0400)
Trust database entries: 213870
Trust DB lookups: 407
Trust DB reader slots full: 0

After reload:
Config generation: 2 (effective since 2026-07-03 14:09:54 -0400)
Ruleset generation: 1 (effective since 2026-07-03 14:09:18 -0400)
Trust database generation: 1 (effective since 2026-07-03 14:09:24 -0400)
LMDB environment generation: 1 (effective since 2026-07-03 14:09:23 -0400)

The exact numbers are not important. The point is that the status report now names the generations that make up the daemon's current decision state, and the metrics report carries the same context for the current counter window.

 

Rulesets are pinned during decisions

Rulesets are pinned during decisions

Rule reloads were already transactional before 1.6: a candidate ruleset is parsed and validated before it becomes the published policy, and a failed reload leaves the previous ruleset in place. In 1.6, that ruleset generation is reported alongside the active config generation, trust database generation, and LMDB environment generation.

The useful 1.6 point is not that older code used partial rules. It is that the daemon now exposes the active state boundaries more clearly, and those boundaries are the shape needed before multiple decision workers can evaluate events concurrently.

This matters even before fapolicyd becomes multi-threaded. A report can now say which ruleset generation was active. Metrics can be interpreted against a specific daemon state. Operators can reload policy and know whether the daemon accepted the new generation or kept the previous one.

It also matters for future concurrency work. Multiple decision threads should not need to stop just because a reload is preparing a new ruleset. They should be able to keep using the generation they started with while the daemon prepares and publishes the next one.

Trust reloads preserve the last good database

The largest operational change in 1.6 is the trust database model.

Trust data is one of fapolicyd's major policy inputs. Package backends and local trust files describe files that are expected to be present and trusted. The daemon stores that data in LMDB and consults it while making decisions.

Before 1.6, trust database reloads were serialized with decision processing, so live decisions were not meant to read a half-built database. The limitation was operational: rebuild work could stop normal decision processing, and failure handling around the active trust database was harder to reason about.

The 1.6 model is more explicit:

build a candidate trust database generation
validate it
publish metadata that makes it active
let old readers drain
reclaim retired generations later

If the candidate cannot be built, the active trust database remains active. If a decision is already reading an older generation, that reader can finish before the retired generation is reclaimed. If reloads arrive during an active rebuild, the daemon coalesces or queues them so that a configuration-changing reload is not silently lost.

A future detailed trust database sizing article will cover this in depth, including manual sizing, automatic sizing, high-water pages, and compaction. The main point for a release overview is that trust database publication is now generational, and failed reloads preserve the last good trust state.

Why the trust database file may need compaction

Most administrators do not need to know LMDB internals. The useful question is simpler:

Is the trust database content current, and is the storage file still a reasonable size?

Those are related, but they are not the same thing.

The trust database generation tells you which trusted-file list is active. When packages change or an administrator updates trust files, fapolicyd builds and publishes a new trust database generation. That answers the content question: "which trust data are new decisions using?"

The storage file is the file that holds that list on disk. After package updates, repeated trust reloads, or test rebuilds, the current trusted-file list may be normal size while the storage file still reflects earlier growth. That does not mean the trust data has problems. It means the database file may have holes that can be repacked to save space.

That is what the status report is trying to show with active pages and allocated high-water pages. Active pages describe the trust data currently in use. Allocated high-water pages describe how large the database file has grown internally. If the high-water number is much larger than the active size, the status report may recommend compaction.

Compaction means "build a clean replacement storage file from the current trust sources and swap it in safely." It is similar in spirit to vacuuming or repacking a database.

In fapolicyd 1.6, compaction is controlled. The daemon builds a clean replacement database file in a temporary directory from the current trust sources, validates it, briefly stops new trust database readers, swaps in the replacement, and reopens the database. If that fails, the old database file is preserved or restored.

The status and metrics reports call the storage-file generation the LMDB environment generation. You do not need that term for daily administration. The practical meaning is: this number changes when fapolicyd replaces the database storage file, such as after controlled compaction. The trust database generation changes when the trusted-file contents change.

In 1.6, db_max_size = auto is the default setting. Auto sizing now accounts for reload headroom - not only the final active database size. Manual numeric values are still supported, but the status report can now tell the administrator when a manual value is too small for safe reloads. When in doubt, use auto.

The (future) dedicated trust database sizing article has the commands to investigate and compact this state, so we will not duplicate that full walkthrough here.

Reports show the active generations

The status and metrics reports now identify more than one kind of generation.

fapolicyd-cli --check-status is still the place to ask whether the daemon is healthy and configured as expected. It now reports the active config generation, ruleset generation, trust database generation, LMDB environment generation, and trust database entry count.

fapolicyd-cli --check-metrics is still the place to ask what happened during the current counter window. It includes the same generation headers so the counter window has context.

That matters during investigations. If a denial happened after a rule reload, you want to know which ruleset generation was active. If package updates triggered trust reloads, you want to know which trust database generation is currently used by new decisions. If a compaction ran, you want to know the physical LMDB environment generation changed.

The reader-slot counter is worth keeping. Trust lookups now use private LMDB read transactions and cursors instead of one global read cursor. That is one of the changes needed before future decision workers can look up trust concurrently.

Worker-ready decision state

The daemon still runs with one decision thread in 1.6. But the hot path is now much closer to the shape needed for more than one.

Earlier code kept several decision-path objects in shared global or file-static state: subject and object caches, decision counters, syslog formatting buffers, deferral state, libmagic handles, device cache state, and LMDB read state.

That works only as long as one decision thread owns the world.

The 1.6 release introduces an internal decision_context object. Today there is one active context, so behavior stays compatible. The important change is ownership. Mutable decision state now has a clearer owner, which makes it possible for a later worker design to give each worker its own context instead of having all workers contend on hidden shared state.

 

fapolicyd 1.6 moves mutable decision state behind a context so future workers can own their state.

 

This does not mean all concurrency work is finished. It means the most obvious shared-state blockers are being removed before the worker pool exists.

 

Better policy diagnostics

The policy linter also became more useful.

The linter added in the previous release warned about policy rules that can accidentally let executable or programmatic content reach the default-allow path. In 1.6, those warnings became more actionable. The linter can now report rule numbers and source file-line locations when a specific rule is involved. It also warns when an old fapolicyd.rules file shadows compiled.rules during linting.

You can demonstrate this without changing the installed policy. Create a small temporary rules file that intentionally lacks a terminal execute deny:

tmp_rules="$(mktemp)" && \
printf 'allow perm=execute all : all\n' > "$tmp_rules" && \
fapolicyd-cli --check-rules "$tmp_rules" --lint; \
rc=$?; rm -f "$tmp_rules"; echo "exit status: $rc"

Rules file is valid (1 rules)
Policy lint warning: executable events can fall through; no terminal broad execute deny found after rule 1 at /tmp/tmp.SbkGW2TCQF:1
Policy lint hint: add a final "deny_audit perm=execute all : all" rule
Policy lint warning: %languages is not defined in /tmp/tmp.SbkGW2TCQF; programmatic ftype coverage cannot be checked
exit status: 1

The exact warning text may differ as the linter evolves, but the point of the demo is that the warning names the policy issue and points at the rule context that caused it.

The release also starts warning about dir=untrusted. That compatibility macro is deprecated and should be replaced with explicit object trust rules. Existing policies still parse, but administrators get a warning so they can plan the migration before the compatibility path is removed in a later major release.

For a safe local check, use a temporary rule:

tmp_rules="$(mktemp)" && \
printf 'allow perm=any dir=untrusted : path=/tmp/payload\n' > "$tmp_rules" && \
fapolicyd-cli --check-rules "$tmp_rules"; \
rc=$?; rm -f "$tmp_rules"; echo "exit status: $rc"
07/03/26 14:23:38 [ WARNING ]: rules: line:1: subject dir=untrusted is deprecated and will be removed in a future release
Rules file is valid (1 rules)
exit status: 0

 

Smaller operational improvements

Several smaller changes round out the release.

fapolicyd-cli --timer-stop now asks before replacing an existing timing report. Timing data can be expensive to collect because it is usually captured around a specific workload. Accidentally overwriting the report with a "timing not armed" result is frustrating, so the CLI now checks before it removes an existing report.

fapolicyd-cli --dump-db handles an empty active trust database correctly in the generation-based layout. fapolicyd-cli --check-trustdb now treats an empty database as success instead of a database walk failure. --check-path now reports trust database initialization failures instead of continuing after initialization failed.

 

ignore_mounts got a broader risk report

The ignored-mount checker was expanded in 1.6. It no longer looks only for files matching the %languages macro. It now reports risk categories such as executable regular files, ELF/shared objects, archives and JARs, bytecode caches, plugin/runtime directories, and language files.

That will be a future article because ignored mounts are easy to misuse. The overview version is simple: ignore_mounts is still for data-only mounts, and the checker now gives administrators better evidence before they decide a mount is safe to ignore.

 

The practical takeaway

fapolicyd 1.6 is not a release where the most important feature is one new command. The important change is the publication model.

Config, rules, trust contents, and physical LMDB storage now have clearer generation boundaries. Reports expose those boundaries. Decisions pin the state they started with. Failed trust reloads preserve the last good database. Mutable decision state is moving behind an ownership boundary that can support future workers.

The result is more explicit state identity, clearer failure handling for trust database rebuilds and compaction, better context in reports, and a cleaner path toward future multi-threaded decision handling.

The upstream project is here:
https://github.com/linux-application-whitelisting/fapolicyd

If you are new to fapolicyd itself, the Red Hat documentation on
blocking and allowing applications with fapolicyd is a useful starting point.

Introducing netcap --advanced

netcap has traditionally answered a narrow but useful question: which network-facing processes are running with capabilities? That is still a good starting point. Network daemons are usually the first place to look when reviewing local privilege because they are reachable by something outside the process itself.

The problem is that a useful security posture review needs a little more context. It is not enough to know that a process has a socket and some capabilities. An administrator also needs to know where the socket is bound, which interface makes it reachable, which systemd unit owns it, whether the process is still root, whether the bounding set was trimmed, whether ambient
capabilities are present, and whether basic exploit-resistance settings are enabled.

That is what netcap --advanced is for.

It is not a scanner in the network sense. It does not send packets. It reads the local system's own view of sockets and processes and turns that into an exposure and privilege report for the current network namespace.

netcap advanced joins local socket reachability with process privilege and hardening state.

What advanced mode changes

The historical mode is filtered. It looks for applications that use tcp, udp, raw, or packet sockets and also have capabilities. That is useful when the main question is "what network-facing process has privilege?"

Advanced mode changes the question. It inventories reachable binds and listeners regardless of whether the owning process currently has capabilities. Then it adds posture information for the owning process.

That distinction matters. A daemon with caps: (none) can still be important if it listens on every interface, runs as uid 0, has no seccomp filter, and is managed by a service unit that could be hardened. Conversely, a daemon with a small capability set may be acceptable if it binds only to loopback, runs as a dedicated user, has NoNewPrivileges=yes, and has a trimmed bounding set.

Advanced mode also covers protocol families that are easy to miss in ordinary checks. TCP listeners are included. UDP and UDPLITE bound sockets are included. RAW and PACKET sockets are included because they imply packet craft or packet capture behavior. SCTP and DCCP listeners are collected through NETLINK_SOCK_DIAG. VSOCK listeners are collected when the build and kernel support it. Bluetooth RFCOMM and HCI sockets are reported when the Bluetooth headers and procfs data are available.

This is why the output is organized as exposure planes:

• INET (external)
• INET (loopback)
• LINK-LAYER
• BLUETOOTH
• VSOCK

The report is local to the current network namespace. If you run it in a container namespace, you get that namespace's view. If you run it on the host, you get the host namespace's view.

For full results, run it as root. The code needs to read other processes' /proc/<pid>/fd entries so it can map socket inodes back to process owners. It also needs enough network privilege to query sock_diag for some protocols. Without those permissions, the output is best effort and can be incomplete.

How the report is built

The design is a "join" across local kernel interfaces. First, netcap --advanced snapshots interface addresses with getifaddrs(). This gives it the names and addresses that will be used later when it decides whether a bind belongs under INET (external) or INET (loopback).

Second, it walks /proc. For each process, it reads enough metadata to build the process node: command name, executable path, real uid, cgroup-derived systemd unit name, capability sets through libcap-ng, ambient capability state, bounding set state, NoNewPrivs, seccomp mode, and the current LSM label when it can be read.

While it is walking /proc/<pid>/fd, it also builds a socket inode ownership map. Procfs exposes socket file descriptors as symlinks such as socket:[123456]. The listener tables later report socket inodes. The inode map is what lets netcap say "this listening SCTP socket belongs to this
process and this unit."

Third, it reads protocol-specific socket sources. The ordinary internet socket tables come from /proc/net/tcp, /proc/net/tcp6, /proc/net/udp, /proc/net/udp6, and the related raw and udplite tables. Packet sockets come from /proc/net/packet. SCTP and DCCP listener data comes from NETLINK_SOCK_DIAG. VSOCK data comes from sock_diag when possible and falls back to /proc/net/vsock when it must. Bluetooth RFCOMM and HCI data comes from /proc/net/rfcomm, /proc/net/hci, and adapter information under /sys/class/bluetooth.

Fourth, it projects endpoints into the tree. A listener bound to 127.0.0.1 goes under loopback. A listener bound to a specific external address goes under the interface that owns that address. A wildcard bind, such as 0.0.0.0 or ::, is expanded onto the non-loopback interfaces so the tree
shows where that wildcard is reachable.

That last step is one of the most useful parts of the design. A process did not literally call bind() once per interface. But from an administrator's point of view, a wildcard listener is reachable through every non-loopback address in the namespace. The output chooses the administrative view over the raw syscall view.

Reading the tree

This is the basic hierarchy:

plane -> interface -> protocol -> bind -> port -> process -> caps/defenses/flags

For VSOCK, there is no network interface, so the VSOCK endpoints are rendered directly under the VSOCK plane.

The process line gives identity:

python3 (pid=1234 uid=0 exe=/usr/bin/python3.14 unit=netcap-demo.service)

The comm value is the kernel process name and can be truncated. The exe field is the full executable path when procfs allows it to be read. The unit field is extracted from the cgroup hierarchy and is limited to service or scope names that are useful for remediation.

The caps line shows the permitted capabilities as libcap-ng sees them. The best value is:

caps: (none)

caps: (full) means the process has full root-like capability privilege. Individual names such as net_admin, net_raw, sys_admin, setuid, or sys_ptrace need review in a network-facing process. The Linux capabilities(7) manual is the reference for what each capability allows.

Two annotations deserve special attention:

• [ambient-present]
• [open-ended-bounding]

Ambient capabilities are inherited across execve() and can surprise people because child programs keep the privilege unless the service takes care to clear it. An open-ended bounding set is not active privilege by itself, but it means the ceiling was not trimmed. A child process may still have a path to regain capabilities through file capabilities or other transitions.

The defenses section summarizes process hardening:

defenses
  runs_as_nonroot: no
  no_new_privs: no
  seccomp: disabled
  lsm: system_u:system_r:unconfined_service_t:s0

runs_as_nonroot is derived from the real uid. no_new_privs and seccomp
come from /proc/<pid>/status, which is documented in proc_pid_status(5). The kernel's
no_new_privs documentation explains why it is useful: it prevents a task from gaining new privilege through later exec transitions.

The flags section is where the report adds interpretation:

• wildcard-bind
• privileged-caps
• reuseport
• hypervisor-plane
• ssh-on-vsock-port-22
• proximity-plane

wildcard-bind means the daemon is bound to all addresses for that address family. privileged-caps means the process has one of the capability classes that is especially interesting for attack-surface review. reuseport means SO_REUSEPORT was detected on the socket. hypervisor-plane means VSOCK. ssh-on-vsock-port-22 means a VSOCK listener is using port 22. That does not prove it is SSH, but it is worth investigating because port 22 has a very specific operational meaning. proximity-plane means Bluetooth reachability.

First commands

Start by finding the interface names in the namespace you are reviewing.

$ netcap --advanced --list-interfaces
enp5s0
lo

Then collect the full tree without color so the output can be pasted into a ticket or report.

$ netcap --advanced --no-color

If one interface is the one that matters, filter the report.

netcap --advanced --interface enp5s0 --no-color
├─ INET (external)
│  └─ enp5s0
│     ├─ raw6
│     │  └─ *
│     │     └─ 58
│     │        └─ NetworkManager (pid=1999 uid=0 
│     │           exe=/usr/bin/NetworkManager unit=NetworkManager.service)
│     │           ├─ caps: dac_override, kill, setgid, setuid, 
│     │           │  net_bind_service, net_admin, net_raw, sys_module, 
│     │           │  sys_chroot, audit_write [open-ended-bounding]
│     │           ├─ defenses
│     │           │  ├─ runs_as_nonroot: no
│     │           │  ├─ no_new_privs: no
│     │           │  ├─ seccomp: disabled
│     │           │  └─ lsm: system_u:system_r:NetworkManager_t:s0
│     │           └─ flags
│     │              ├─ wildcard-bind
│     │              └─ privileged-caps
│     ├─ udp
│     │  └─ *
│     │     ├─ 5353
│     │     │  └─ avahi-daemon (pid=1735 uid=70 
│     │     │     exe=/usr/bin/avahi-daemon unit=avahi-daemon.service)
│     │     │     ├─ caps: (none)
│     │     │     ├─ defenses
│     │     │     │  ├─ runs_as_nonroot: yes
│     │     │     │  ├─ no_new_privs: no
│     │     │     │  ├─ seccomp: disabled
│     │     │     │  └─ lsm: system_u:system_r:avahi_t:s0
│     │     │     └─ flags
│     │     │        ├─ wildcard-bind
│     │     │        └─ reuseport
│     │     ├─ 50795
│     │     │  └─ firefox (pid=6947 uid=4325 
│     │     │     exe=/usr/lib64/firefox/firefox)
│     │     │     ├─ caps: (none)
│     │     │     ├─ defenses
│     │     │     │  ├─ runs_as_nonroot: yes
│     │     │     │  ├─ no_new_privs: no
│     │     │     │  ├─ seccomp: disabled
│     │     │     │  └─ lsm: 
│     │     │     │     unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.
│     │     │     │     c1023
│     │     │     └─ flags
│     │     │        └─ wildcard-bind
│     │     └─ 53013
│     │        └─ firefox (pid=6947 uid=4325 
│     │           exe=/usr/lib64/firefox/firefox)
│     │           ├─ caps: (none)
│     │           ├─ defenses
│     │           │  ├─ runs_as_nonroot: yes
│     │           │  ├─ no_new_privs: no
│     │           │  ├─ seccomp: disabled
│     │           │  └─ lsm: 
│     │           │     unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1
│     │           │     023
│     │           └─ flags
│     │              └─ wildcard-bind
│     └─ udp6
│        └─ *
│           └─ 5353
│              └─ avahi-daemon (pid=1735 uid=70 exe=/usr/bin/avahi-daemon 
│                 unit=avahi-daemon.service)
│                 ├─ caps: (none)
│                 ├─ defenses
│                 │  ├─ runs_as_nonroot: yes
│                 │  ├─ no_new_privs: no
│                 │  ├─ seccomp: disabled
│                 │  └─ lsm: system_u:system_r:avahi_t:s0
│                 └─ flags
│                    ├─ wildcard-bind
│                    └─ reuseport
└─ LINK-LAYER
   └─ enp5s0
      └─ packet
         └─ *
            └─ 2054
               └─ NetworkManager (pid=1999 uid=0 
                  exe=/usr/bin/NetworkManager unit=NetworkManager.service)
                  ├─ caps: dac_override, kill, setgid, setuid, 
                  │  net_bind_service, net_admin, net_raw, sys_module, 
                  │  sys_chroot, audit_write [open-ended-bounding]
                  ├─ defenses
                  │  ├─ runs_as_nonroot: no
                  │  ├─ no_new_privs: no
                  │  ├─ seccomp: disabled
                  │  └─ lsm: system_u:system_r:NetworkManager_t:s0
                  └─ flags
                     └─ privileged-caps

For automation, use JSON.

netcap --advanced --json

The tree is better for human triage. JSON is better for a nightly report, configuration drift check, or a small script that alerts on flags such as wildcard-bind, privileged-caps, hypervisor-plane, or proximity-plane.

Limits

netcap --advanced is a local snapshot. A process can start or exit while the report is being built. Some procfs entries can be hidden by permissions or mount options. SCTP, DCCP, and VSOCK discovery depends on kernel support and, for the sock_diag path, sufficient privilege. Bluetooth adapter mapping can be heuristic when the kernel does not expose enough adapter information for a socket.

The report also does not tell you if a service is supposed to be there. It tells you what is there, where it is reachable, who it runs as, what capabilities it has, and what hardening is visible. The administrator still has to decide whether that service belongs on the machine.

The upstream project is here: https://github.com/stevegrubb/libcap-ng.
For background on Linux capabilities, start with capabilities(7).
For VSOCK-specific background, see vsock(7).