Stackurity Start free trial

Docs Using Stackurity

Reachability

Docs for v0.20.10 · Edit on GitHub

Most findings are in packages that are installed but never used: a library a dependency pulled in that no code of yours imports, or an operating-system package that no running program executes or loads. Reachability says, for each finding, whether its package is reached, and shows the evidence.

Status Meaning Evidence comes from
Reachable First-party code imports the package, or a running process executes it or has it loaded The collector that read the source or the processes
Not imported A direct dependency of an application or repository that no first-party source file imports and no other package depends on Repository scans and stackurity scan read the source files (Go, npm, Python, PHP)
Not running A host service that is off: not enabled, and none of its programs ran in 7 days of readings The agent reads the running processes; it needs read access to other users' processes, which is opt-in when the server is added
Not assessed (unknown) No evidence either way The default for every package, and what any collector that did not check reports

Not assessed counts as reachable. Nothing is ever shown as unreachable without evidence a person can check: each status other than unknown carries the collector's evidence lines ("no import of lodash in 214 source files under src/", "Its service (memcached.service) is not enabled, and none of its programs was running in any of the agent's readings of the last 7 days …"). A collection that does not assess a package sets it back to unknown, so an old claim never outlives the check that made it. The server stores a claim that a package is not reached only when its own records say the source can make it: not running only for a host, from that host's own agent (a token bound to the host, or the token the agent got when it enrolled, which is tied to the first host it reports), and not imported only for a repository, from the server's own repository scan or a token that is not an agent's. The batch must also come from the collector that makes the claim (linux-agent for dpkg and apk packages; lockfile-scanner for npm, Go, Composer and Python packages) with a coverage entry that says the reading was whole. Any other claim is stored as unknown.

Reachability is a statement about the asset as it was last collected: a package that is not running now may be started later, and code that does not import a package today may import it after the next deploy. That is why it lowers a priority by at most one level and never hides a finding.

Repositories and stackurity scan: not imported

When the server scans a repository, or stackurity scan scans a directory, it reads the first-party source files after the lockfiles, as data (nothing is run or built), with the scan's limits: 50,000 source files, 1 MiB of each and 256 MiB in all, the walk's own limits, and the same skipped directories (node_modules, vendor, .git, ignored files, nested checkouts). The coverage entry reachability says how many files of each language were read. When a limit was reached, or first-party source was skipped, its reason starts with partial: and says why, and the scan reports nothing as not imported. Skipped source is: a symbolic link to source or to a directory (not followed); gitignored source files and directories (generated code often is); a nested checkout; and a vendor/ that is not Go's or Composer's, or bower_components/. node_modules/ and Go's and Composer's vendor/ hold third-party code, which the lockfile's dependency graph covers, so a checkout with its dependencies installed (after npm ci) is read whole; a gitignored .env holds settings, not source, and does not make the reading partial. Its status is always checked: what reachability could read says nothing about whether the package list is whole, so it never counts as a coverage gap, an alert or a reason to hide a trust badge.

Ecosystem Reachable when Not imported when Otherwise not assessed
Go A non-test .go file imports a package of the module Never: go.mod and go.sum do not record which module requires which, so a module the program uses may use it Every module that is not reachable
npm An import, export … from, require() or import() names the package (lodash/fp counts as lodash) A direct dependency that no file imports or names, from a package-lock.json or npm-shrinkwrap.json (version 2 or 3) in which no other package depends on it No JavaScript or TypeScript files; a transitive dependency; a direct one that another package depends on; a lockfile without the dependency graph (yarn.lock, pnpm-lock.yaml, npm version 1); a lockfile with a workspace or file: dependency outside the scanned tree; a package whose program (its bin, such as tsc from typescript) is named in a script, Makefile, Dockerfile, Procfile or .env file; any require() or import() with a computed argument; a minified bundle (*.min.js, or a line over 5,000 characters), which may hold packages without importing them; the package is named as a string in source or configuration (client: 'pg', a plugin list, a package.json script), by its path under node_modules/ (a <script src> in a page or template), imported by a stylesheet (@use "~bootstrap/…"), preloaded (node -r, --require, --import or --loader, also in NODE_OPTIONS), or run with npx (in a Makefile, Dockerfile or script)
PHP (Composer) A name in its autoload namespace (from composer.lock) appears in PHP or configuration files (use Monolog\Logger, a class name in YAML) A direct dependency whose namespaces no PHP or configuration file names, and that no other package in composer.lock requires A transitive dependency, or a direct one another package requires; a package that provides or replaces another (provide, replace: guzzle provides psr/http-client-implementation, which other packages require without naming guzzle); a lockfile with a path package outside the scanned tree; the package autoloads files on every request, is a Composer plugin or Symfony bundle, registers itself with Laravel, has only a class map, or autoloads from the root namespace
Python An import or from names the package (dashes as underscores) Never: a distribution's import name can differ from its name (PyYAML is yaml), so a missing import proves nothing Every package that is not reachable

Each claim carries its evidence: the file that imports the package, or what was searched ("no import or require of left-pad in 214 JavaScript/TypeScript files, and not named in scripts or configuration"). Not imported is claimed only for a direct dependency that no other package in the lockfile depends on: a transitive dependency runs whenever the package that needs it does (body-parser under express), so it stays not assessed. A development dependency says so.

Servers before reachability refuse the field, so stackurity scan sends it only to servers whose GET /meta lists reachability.

Hosts: running or not running

On a Linux host the agent reads, on every report, which installed packages its running processes use. From /proc it reads each process's program (/proc/<pid>/exe), the names of the files in its memory map (/proc/<pid>/maps: its shared libraries) and its open sockets (/proc/<pid>/fd and the kernel's TCP tables), and matches the files against the dpkg or apk file lists. It never attaches to a process or reads its memory. Files are matched by path, so a container on the host that runs a program at the same path as a host package (its own /usr/lib/…/libssl.so.3) makes that host package reachable too: the match errs towards reachable, never towards not running. rpm hosts, and filesystems read with --root, are not assessed yet.

Status When
Reachable A running process is the package's program or has one of its files mapped ("Running: nginx (pid 812) is /usr/sbin/nginx.", "Loaded by nginx (pid 812): /usr/lib/x86_64-linux-gnu/libssl.so.3."), with the addresses that program listens on. The agent keeps a package reachable for 7 days after it last saw it running, across restarts.
Not running Only a service that is off: the package ships a systemd service or init script that nothing starts, its code is programs under bin or sbin that run as themselves (not scripts, links, setuid or setgid programs, or programs with file capabilities), and none of its programs was running in any reading for 7 days, during which the agent read every process of the host at least every 13 hours and the package (at this version) was installed. Nothing starts the service when: it is not enabled (no .wants, .requires or .upholds link, generated ones included; not static; not started by a runlevel; masked counts as off); no other unit names it or, for a template ([email protected]), any instance of it (Wants=, Requires=, BindsTo=, Upholds=, OnSuccess=, OnFailure=, Unit=, a socket's Service=, Also=, or a timer, socket or path unit of its name; in drop-ins, units linked in with systemctl link, /usr/local, transient and generated units too); no udev rule wants it (SYSTEMD_WANTS) and no D-Bus service activates it (SystemdService=); and no crontab, cron.* script or inetd configuration names the service or its programs. When a crontab directory or unit file cannot be read (Debian's /var/spool/cron/crontabs is closed to the agent's user), no package is called not running, and the coverage reason says so. It must see the kernel's own threads, which a container's PID namespace or hidepid hides; kernel threads are recognised by the kernel's flag in /proc/<pid>/stat, which no process can set. The agent keeps that history in its state directory (/var/lib/stackurity-agent); without one, or after a partial reading or a longer gap, it starts counting again. The evidence names the service, gives the readings' start, and says the package may still be started by hand or by another program.
Not assessed Everything else, including every command-line tool and anything with a program systemd runs by itself (generators, sleep and shutdown hooks): tools are started on demand (and some, such as pkexec, are attacked by being started), so not seeing them running says nothing. Also libraries and helpers (under /usr/lib, /usr/libexec, /opt), which other programs can load or start on demand (a PAM module on each login); packages with scripts, by extension or by a first line starting #! (a running script shows only its interpreter as its program), or with programs that are links to another program (Alpine's /bin/sh runs as busybox); anything started from cron, a systemd timer or socket, D-Bus or a hook; kernel packages, which have their own check (not_running_kernel); and every package when the agent could not read every process.

Process access is opt-in. The agent runs as an unprivileged user, and Linux lets it read other users' processes only with CAP_SYS_PTRACE. Without it the agent still sees programs started by their full path (/proc/<pid>/cmdline is readable by everyone), so it can mark a package reachable but never not running. To turn it on, tick See which packages are running under Assets › Add server, or run the installer again on a host that already reports (the host's page shows the command, under its attributes):

curl -fsSL https://<your server>/install/agent.sh | sudo STACKURITY_PROCESSES=1 sh

The service then gets AmbientCapabilities=CAP_SYS_PTRACE and a state directory. Like Docker access, CAP_SYS_PTRACE is equivalent to root on the host: it allows reading any process's memory through /proc/<pid>/mem, which cannot be blocked. The agent only reads the paths above, never process memory or environments. The service blocks the ptrace, process_vm_readv, process_vm_writev, pidfd_getfd and kcmp system calls, which narrows what the agent could be made to do but is not protection. STACKURITY_PROCESSES=0 turns it off; an upgrade keeps the setting. The host attribute process_access (on or off) shows which applies.

One reading is small whatever the host: at most 4,096 processes, 65,536 map lines per process and 50,000 distinct file names are kept, and the package file lists are streamed, not loaded. The coverage entry reachability/processes says how many processes were read; its reason starts with partial: when some could not be read or a limit was reached, and then no package is called not running; until the agent has 7 days of whole readings the reason says since when it has had them. Like the repository entry, its status is always checked, so it never counts as a coverage gap.

What it does to a priority

Edition Effect
Community The status and evidence are shown on the finding, in the explanation (explain_finding, why.reachability) and in the API. Priorities do not change.
Pro and Enterprise A finding that is not imported or not running is one priority level lower (P1 to P2, P2 to P3, P3 to P4; P4 stays P4), recorded as the factor Not reached with the evidence. It is never lowered when the finding is known exploited (CISA KEV) and its asset is internet-facing or its exposure is unknown: the factor Not reached, priority kept says so. The reachability filters and views are also part of these plans.

Lowering a priority never ends SOS: the SOS rules look at known exploitation, severity, exposure and environment (risk.md, "Score"), and an unreachable package on an exposed production server still raises one when they match. The step runs after the score is mapped to a priority, and its name is part of the risk policy version stored with each priority (risk.md, "Reproducibility and audit").