Server certificate scan
A server certificate scan (source type Targets, API target_scan) reads the
certificates stored on the distribution targets a project already has.
It finds what a network scan cannot: certificates in files that no service presents, certificates
served on a port nobody scans, and the entries of the Windows certificate stores.
It never adds a target. You pick existing SSH targets (Linux) and WinRM, IIS and Exchange targets (Windows), and existing target groups of those types. Each target is reached with its own credential and connection settings, exactly as a deploy reaches it — the target's connect and command timeouts included (a Windows target whose command timeout is shorter than Time per server stops the scan there).
The form shows what is chosen — how many targets and groups, Linux and Windows apart, the first rows and any SSH target without a pinned host key — and Choose targets opens the full list: search by name or address, filter by type, Selected only to review and remove, and Select all to take every target the search matches. Targets and groups you are not an admin of are listed greyed out with No access and cannot be chosen. Nothing changes until you press Apply.
What it reads, and what it never reads
The scan only finds certificates. It never reads a private key out of a server, never exports one, never records where one is kept, and never imports anything by itself.
The script that runs on the server decides by content, not by file name, what may leave the server:
- A PEM file: only complete
CERTIFICATEandPKCS7blocks whose every line is base64 (lines may be indented). APKCS7block is decoded on the server first and sent only when it is a certificate bundle (see below) and nothing else; a block that is not stays on the server and the file counts as not fully read. A private key block in the same file is skipped. - A binary file: only the parts whose structure is a certificate — certificates stored back to
back are all sent, and the reading stops at the first part that is not one. A private key appended
after a certificate is counted, never sent. A PKCS#7 certificate bundle (signed data that carries
no content of its own — the kind
.p7bchain files are) sends that one structure; any other PKCS#7 (plain data, or signed data that carries content, which can hold anything) is reported by type only. A PKCS#12 (.pfx,.p12— or one renamed.crt), a private key in DER, an encrypted private key and anything unrecognised are reported by type only; their bytes stay on the server. - Each file is read once, at most 1 MiB of it, and only when it is still the regular file the search listed: a file replaced since by a link (or a pipe) is not followed, a file larger than 1 MiB is too big (listed, not read — its earlier locations are kept).
- A Windows store entry: its public certificate (and its friendly name).
CertAutoPilot checks the answer again on its side and refuses anything that is not a certificate.
A file that holds only a key, and a PKCS#12 file, are counted on the target's row (key / other files); a PKCS#12 file is listed by its path with the format PKCS#12 (not read), since it holds certificates too.
Read-only
Nothing is written on the server: on Linux the script is read from standard input, on Windows it travels on the command's standard input and runs in memory. The script creates, changes and deletes no file, no store entry and no setting. What any login leaves, the scan's login leaves too — measured on Ubuntu 24.04 and Windows Server 2022:
| Server | What changes | Why |
|---|---|---|
| Linux | the system's login records (auth.log, the journal, /run session entries) | the SSH login itself |
| Linux | the last access time of the certificate files it reads, at most once a day | the default relatime mount option (none with noatime); contents, modification and change times stay |
| Windows | the login account's own profile (NTUSER.DAT) and PowerShell's start-up cache in it (StartupProfileData-NonInteractive) | every WinRM PowerShell session; written when the session ends |
| Windows | nothing on the files it reads | Windows does not update last access times unless an administrator turned it on |
A login that has never signed in to a Windows server gets a user profile on its first session. Security software can notice a process that opens many certificate files; tell it about the login the scan uses.
Who can set it up
| Action | Needs |
|---|---|
| Create or change the source | project admin, and admin on every chosen target, every chosen group and every member of those groups |
| Run it (Scan now) | operator on the source |
| See what it found | viewer on the source |
The scan logs in to each target with that target's credential, so a viewer grant on one group member is enough to refuse saving the source. The admin who last saved the source is its owner: every run picks its targets with the owner's access as it is at that moment. A target added to a group later is read only when the owner is an admin of it; an owner who is deleted, deactivated or no longer a project admin stops the runs until an admin saves the source again.
Seeing the source means seeing what it found. A user granted the source (viewer is enough) sees every server it read — target names, addresses, error texts and the paths and stores of the certificates — also for targets that user has no grant on. Grant the source only to users who may know those servers.
The scan honours the target's SSH host-key pin: a pinned target that presents another key is not
read (SSH_HOST_KEY_MISMATCH). A target without a pin is read like a health check reads it — turn
on Verify host key on the target for the scan to talk only to the server it knows.
Where it looks
Linux — every local file system (find -xdev), looking at files named *.pem, *.crt,
*.cer, *.der, *.p7b, *.p7c, *.pfx, *.p12 and *.key (a file larger than 1 MiB is reported
too big, not read). Symbolic links
are not followed, except an extra path you give that is itself a link (it is searched). A path with
a line break in it is skipped. The server needs find, awk, od, dd, base64 and tr (busybox is
enough); a server without one fails with the missing commands named instead of reading as empty.
Tested on Alpine, busybox, Debian 9–12, Ubuntu 18.04–24.04, CentOS 7, Rocky/Alma 9, Oracle Linux 8,
Amazon Linux 2, RHEL UBI 9, Fedora, Arch and openSUSE Leap (container images, a non-root login).
- Standard leaves out
/usr(but searches/usr/local),/lib,/bin,/sbin,/boot,/snap, container layers (/var/lib/docker,containerd,containers), package databases and the system trust store (/etc/ssl/certs,/etc/pki/ca-trust,ca-certificates,/var/lib/ca-certificates, and bundles such asca-bundle.crt). - Everything leaves out only
/proc,/sys,/devand/run. - Also search: extra folders, searched even inside the left-out ones.
- Include the system trust store adds the trust store back.
CA certificates are kept apart. A root or an intermediate CA certificate the scan finds — in a
trust store or a CA file — and that no server serves goes to Inventory → CA certificates, marked
Root CA or Intermediate CA. It is not counted with the server certificates (inventory,
Overview, Insights), and it raises no finding, risk score or expiry alert. When one appears on or
leaves a target, Activity lists it (CA certificates added / removed, per target and day), and
the certificate's Found on targets card shows, with History, when it was first seen and when
it went from each place. A CA certificate that a server serves on a port stays a server certificate
— that is a misconfiguration the leaf_is_ca finding reports.
The scan runs as the target's login — there is no sudo. A folder the login cannot read is listed
on the target's row as folders the login cannot read.
Windows — the LocalMachine stores you choose (default My and WebHosting; the trust
stores Root, CA and AuthRoot only when allowed), and a file search over every fixed
drive with the same names as on Linux.
- Standard leaves out the Windows folder and
WindowsApps; Everything searches them too. - Junctions and other reparse points are not followed;
$Recycle.BinandSystem Volume Informationare never searched. - Stores only turns the file search off.
- An Exchange target is read on the server it connects to only.
Measured on our lab servers (Windows Server 2016 and 2022, 12–19 GB in use): the whole-drive search took about 9 seconds and the stores 1–4 seconds; on Linux the standard search took under a second and Everything about 15 seconds.
What a run records
Each certificate goes to the inventory like one a network scan found — with its risk, findings, expiry alerts and tags. Where it was found is recorded as a location:
| Column | Meaning |
|---|---|
| Server | the target, and the address the scan reached |
| Where | the file (with the certificate's position in a bundle) or Cert:\LocalMachine\<store> with the thumbprint |
| Format | PEM, DER, PKCS#7, PKCS#12 (not read), or Store |
A file holding a certificate and its CA certificates (a full chain) records the certificate; the CA certificates become its chain. A file of CA certificates only records them as they are.
A certificate's chain is built from every CA certificate the server holds, linked by name, key identifier and signature (SHA-1 signatures included, as for a network scan): the CA certificates in the same file first, then those in the server's other files and stores. A chain is at most 12 certificates long, like one a server presents.
Network scans and server certificate scans can see different parts of one certificate's chain — a server usually presents the certificate and its intermediate, while the server's disk may also hold the root. One chain is kept per certificate, and it does not swing back and forth between scans:
- the chain a server presents (network scan) is what clients get, so it replaces what a server certificate scan stored — unless the stored chain is that same chain continued further (up to the root), which is kept;
- a server certificate scan replaces a chain another server certificate scan stored, and replaces a network scan's chain only with that same chain continued further.
So the CA details and the expired root CA risk change only when the chain really changed. When a
scan does not know the chain at all (no issuer on the server, or the chain could not be finished
within the scan's limits), what is stored stays. A Windows
store entry carries only its own certificate, so a Windows scan also reads the Intermediate
Certification Authorities (CA) store — for chains only; those CA certificates are not listed in
the inventory unless you allow the trust stores. A CA certificate the server does not hold is not
fetched, and the chain stops below it.
The source's page shows Locations and Targets (each target's result in the last run, paged and filterable by result and by name or address — a running scan shows each target as it finishes: Read, Failed, Incomplete when a limit stopped the search or more than 50 folders could not be read, Skipped when the owner is not an admin of it, Not reached when the scan's time ran out before its turn). A certificate's page shows Found on targets — one row per file or store entry, with every source that found it there when several sources scan the same server (the certificate's location count counts places, not sources). The inventory filter Found on → Files / Windows stores lists every certificate a server certificate scan found.
When a location is gone
- A target read completely: a location not found again is gone — except in a folder or store
the scan could not read this time. A folder the server calls unreadable while listing files inside
it is not taken as unreadable; a folder that could not be read and whose name cannot be reported
(it contains a line break or characters the server's
findcannot print) makes the run Incomplete. - A file the scan found but could not read this time (it grew past 1 MiB, its permissions changed) keeps its locations — as does a folder or store that could not be read — but only for 30 days without being seen.
- A target that failed or stopped early keeps its locations; after 30 days without a complete read they are gone.
- A target the source's owner is no longer an admin of (or a member of a group the owner is no longer an admin of) is Skipped and keeps its locations; after 30 days they are gone.
- A target that left the source (removed, left its group, deleted) has its locations gone at the next run. When the source itself is deleted, everything it found goes with it — also what a run still going at that moment saves afterwards (a certificate it saved moments before leaves the inventory a few minutes later). A run that loses the source to another run marks nothing gone.
A certificate is removed from the inventory once no location and no network endpoint holds it.
A gone location stays in the list (Show gone) for 180 days, like a network endpoint that went away, then it is deleted. A location still found is never deleted, however long ago the last scan ran.
Managing a found certificate
A scan never imports anything. To manage a certificate it found, use Import on the certificate's page like for any discovered certificate: you upload its private key yourself, and CertAutoPilot does not connect to the server for it.
Misuse it is built against
- Only admins point it at servers. Saving needs admin on every target, group and group member; operators can only run it. Each run uses the access of the admin who saved it at that moment.
- Only certificates come back. The decision is made on the server by content, and checked again on CertAutoPilot's side; a key, a PKCS#12 file or anything else never leaves the server.
- A fixed script. The operator's settings reach the script only as quoted data: paths are
checked (absolute, no
.., no control characters) and quoted; Windows store names come from a fixed list. - A server that answers on its own terms (it ignores the script and prints what it likes) cannot fill the inventory or overload CertAutoPilot: one server's answer is capped at 64 MiB — past it the command is stopped on the server — 20,000 files, 20,000 store entries and 50,000 certificates. Paths, store names and other text it reports are bounded and cleaned, a Windows store entry counts only under the stores the source reads, and its thumbprint is computed from the certificate. Past a limit the rest is ignored and the target's row says so (Incomplete). Every certificate it sends must parse as one, and the work to build chains is bounded too.
- A connection that does not behave — a Windows listener that answers with something other than a WinRM reply, sends its answer a byte at a time, never reads the request or never finishes the TLS handshake — ends that server's request within its time limit; nothing waits on it after that.
- Credentials stay with their servers. Each target is reached with its own credential, which must be allowed for that address. A refused login stops the other targets that use the same credential in that run, so an account is not locked out.
- The owner keeps its rights. A run uses the access of the admin who last saved the source; when that admin no longer has admin on the source itself (or on the project), the run stops until an admin saves the source again.
- Bounded load. Time per server, a whole-scan deadline, the per-type concurrency limits, one run at a time per source, and Scan now limited to 10 a minute per project.
- SSH host keys. Without a pinned host key a scan trusts the server it reaches, like a health check. Pin the key on the target (Verify host key) so a password is only sent to the server you know.
Limits
| Setting | Default | Range |
|---|---|---|
| Files per server | 5000 | 1–20000 |
| Time per server | 120 s | 10–900 s |
| Time for the whole scan | 1500 s | 60–1500 s |
Linux and Windows servers are read side by side, each with its own limit (the distribution concurrency settings: SSH 10, Windows 8 by default); targets of one server (one address and SSH port, or one Windows host) one after another. Each server's results are saved as soon as it was read, so a scan that runs out of time keeps everything it read; the servers it did not reach are Not reached and their locations are kept. The order is shuffled on every run, so the same servers are not the ones left out each time.
Over all of that, one worker process reads at most 18 servers at once and works on their answers
within 1 GiB, shared by every scan of every source running there
(discovery.target_scan_max_parallel_hosts and discovery.target_scan_memory_mb in the
configuration). A server still waiting for its turn when
the scan's time ends is Not reached, and what was found there before is kept; an answer already
read is always saved. The time a server
waits for its turn does not count against its own Time per server.
Time per server is kept on the server too: a Linux scan stops itself a few seconds before it
(it ends everything it started — find, awk — and reports where it stopped), a Windows scan stops
its search at 80 % of it. A server that runs out of time is Incomplete, and everything it had
sent by then is kept; its locations are not taken for gone. On Windows the scan is sent on the
command's standard input and run in memory: nothing is written to the server's disk.
When a server refuses a credential (a wrong password, an unknown account), the other targets using the same credential (and, for SSH, the same user) are not tried in that run — each refused login counts towards an account lockout. Their rows say not attempted. Until one server has accepted or refused a credential in a run, the targets that share it log in one at a time, so a stale password costs one refused login whichever server is read first; a server that gives no verdict (unreachable, a changed host key, no answer) decides nothing and the next one is tried.
Files without one of the names above are not looked at; Java keystores are not read.
Upgrading
A server certificate scan can be created or changed only when every CertAutoPilot node runs 1.7.3
or later (409 CLUSTER_UPGRADE_REQUIRED otherwise). Do not bring back an older node afterwards: it
does not know these sources, and its clean-up can remove certificates found only on disk until the
next scan finds them again.
Video tutorial
Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →