Concepts and glossary

This page defines the terms used across the documentation. Where a term has a loose industry meaning and a narrower Pentr meaning, the narrower one is given here. Terms that belong to one section, such as gated identifier or key-encryption key, are defined on that section's pages.

Artifact¶

A single piece of captured evidence from a run. Four kinds are written during a run: command logs (the command, its stdout and stderr, exit code and timing), request/response pairs, browser screenshots, and other, which holds the payload and file evidence items the agent attaches to findings. Each artifact is hashed with SHA-256 when it is produced and stored under that hash. Its record holds the phase it came from, its position in the run, and the findings it supports, if any. Identical bytes captured twice in one run are stored once, and the stored artifact is linked to each finding that attached them. A seal covers the artifacts of one run.

Asset¶

Something your organization registers and proves it owns: a domain, an IP address, a CIDR range or a URL. Ownership is proven per asset, and the asset's status records the proof: unverified, verified or attested. The status vocabulary also contains revoked, which the launch check refuses and which nothing in the product assigns. Only verified and attested assets can clear the launch check, and the status alone is not enough: a verified asset's proof is run again at launch, and an attested asset must not have expired. An asset is not a target — see target below.

Campaign¶

A recurring series of runs, produced by a schedule. Each engagement the schedule creates is an ordinary engagement with the same agent, the same evidence locker and the same report as a manually submitted one. Use "campaign" for the series and "engagement" for a single run in it.

Chain head¶

The hash of the last entry in a run's evidence chain. Each entry's hash covers the previous entry's hash, the artifact's own hash and the entry's metadata, so the chain head commits to every artifact in the run and to their order. For a run with no artifacts, the chain head is the chain's starting value. The signature block carries the chain head, and pentr-verify recomputes it from the artifacts.

Engagement¶

One run. An engagement carries its targets, its in-scope and out-of-scope lists, its rules of engagement and one framework. It has one status at a time. It is created pending. Submitting it moves it to queued, or to blocked when the launch check refuses it, and a blocked engagement can be submitted again. The scheduler moves a queued engagement to running, and the run ends completed or failed. cancelled is also in the status vocabulary, and nothing in the product assigns it. Lifecycle lists the transitions. An engagement is the unit that is sealed, reported, exported and shared.

Evidence locker¶

The zip export of a sealed engagement. It contains the manifest, the signature block, the raw signature, the organization's public key, an unsigned summary header, a README, and each sealed artifact stored under its SHA-256 hash. pentr-verify checks it offline, with no network, no database and no Pentr account. The locker holds the evidence, not the report: findings appear in it only as identifiers in manifest entries.

Finding¶

One security issue the agent recorded, with a title, a description, a severity from critical to info, the affected target, remediation advice, and the evidence items the agent attached, each also captured as an artifact. Each finding also has a status, one of unverified (the default), verified, not_exploitable or false_positive. The agent sets it during the run, an operator can change it in the console afterwards, and nothing checks it against the evidence. Findings additionally carry CVSS, CVEs, MITRE ATT&CK technique and tactic ids, and OWASP WSTG ids where they apply; the SARIF and CSV exports add CWE identifiers derived from the finding's text. Anatomy of a finding lists every field.

Framework¶

The compliance standard a run's report is mapped to, one per engagement. Six are included: SOC 2 Type II, ISO/IEC 27001:2022, PCI DSS v4.0, OWASP ASVS 4.0.3, NIST CSF 2.0 and ENS (RD 311/2022). Each is a list of controls plus tables that map MITRE ATT&CK technique ids, OWASP WSTG ids and keyword categories to those controls. A finding acquires control identifiers through the ATT&CK and WSTG tables; when those yield no control, the finding's text is matched against the keyword categories. The framework decides the labels in the report and the exports, and selects no phase, tool or check. It is recorded in the rules-of-engagement document and in the manifest, and it is not sent to the model.

Manifest¶

The JSON document describing a sealed run. Its fields include each artifact entry with its hash, kind, phase, size and entry hash, the chain head, the entry count, the framework, and a SHA-256 digest of the in-scope list, the out-of-scope list and the rules. The digest fixes what was declared without stating it: the scope itself is not in the manifest. The manifest's own hash is one field of the signature block, and the block is what is signed, so the signature covers the manifest indirectly.

Organization¶

The account boundary. Each asset, engagement and signing key belongs to one organization, and a share link belongs to one through its engagement. A solo organization is created for you the first time you make an authenticated request, with you as its owner. The owner role is required to attest to asset ownership. The API and the database spell it organization.

Phase¶

One of the seven stages of a run, in fixed order: pre-engagement, intelligence, threat modeling, vulnerability analysis, exploitation, post-exploitation and reporting. Pre-engagement renders the rules-of-engagement document and advances without a model call, which is why the console pipeline shows six stages. In the other phases the agent advances by declaring the phase complete; threat modeling also advances when it reaches its step cap. A phase advances only to the next one, and no phase is skipped or repeated. Each artifact and each finding records the phase it came from.

Rules of engagement¶

An engagement's rules: a maximum duration in minutes, a list of allowed actions and a list of denied actions. In the first phase of the run they are rendered, with the targets, the scope lists and the framework, into the rules-of-engagement document. The document is stored with the engagement and reproduced in the PDF report, and the rules are part of the digest in the manifest. The document is not sent to the model: of the engagement's settings, the model receives only the targets and the in-scope and out-of-scope lists. Rules of engagement describes what each rule does and what the scope guard enforces.

Schedule¶

The stored engagement template plus cadence that produces a campaign. Cadence is a standard five-field cron expression evaluated in an IANA timezone; the daily, weekly, monthly and quarterly presets compile to cron at 09:00 in that timezone. The server refuses an expression whose sampled fire times fall less than an hour apart on the local clock; Cadence describes the check and how it behaves at a daylight-saving change. A schedule that is overdue by several slots fires once and jumps to the next future occurrence rather than backfilling, and an occurrence that would exceed the organization's plan cap is skipped with the reason recorded.

Scope¶

What the agent may and may not touch in one run: an in-scope list and an out-of-scope list. During the run the scope guard checks each command before it is executed and each URL before it is fetched, out-of-scope first; a command in which it detects no target is allowed through.

When the rules-of-engagement document is rendered in the first phase, an out-of-scope network that overlaps an in-scope network, or a name on both lists, aborts the run in that phase. The run is still recorded as completed and sealed, with no artifacts. A single out-of-scope address is read as a network of one address, so excluding an address inside an in-scope range aborts the run. Names are compared as exact strings, so an out-of-scope name can narrow an in-scope wildcard: *.example.com in scope with secret.example.com out of scope is not an overlap, and the guard refuses that exact name but not names beneath it. Nothing checks for overlap at submit time. Scope covers how the two lists combine.

Seal¶

The act, performed once when a run's container exits zero with a results payload, of ordering the artifacts into a hash chain, building the manifest, and signing a canonical signature block with the organization's active signing key. The block carries a format version, the signature algorithm, the chain head, the manifest's hash, the key id and the signing time. The trigger is the clean exit and the payload, not the completeness of the work: a run stopped at the 500-step ceiling, or aborted after five consecutive failing steps, is sealed like any other.

Sealing is fail-closed: if the key-encryption key is unavailable or a signing step fails, no seal row is written and the run stays unsealed. Steps that ran before the failure may already have recorded control identifiers on the artifacts, stored the manifest, or generated the organization's first signing key. Sealing describes the behavior. There is no re-seal, so a run whose seal attempt failed stays unsealed. That run is completed, and its PDF report and its SARIF and CSV exports are still produced, with no evidence hashes; the PDF and SARIF state that the run is unsealed, and the CSV has no column that records it. A failed run has no report and no exports, and no unsealed run has a locker export.

Share link¶

A revocable, expiring, read-only link to one sealed engagement's manifest and locker, for a reader with no Pentr account. The token sits in the URL fragment, which browsers do not send in the request line or in Referer headers. The share page sends the token to the server in an X-Pentr-Share-Token request header, so an intermediary that logs request headers would record it; Share links describes both. Pentr stores only the token's SHA-256 hash. A share link is not scoped to a person: anyone the link reaches has the same access, and revoking it stops future access without affecting a copy already downloaded.

Signing key¶

The Ed25519 key pair your seals are signed with. Each organization has at most one active key, and one is generated when a run is sealed for an organization that has none. Generating or uploading a new key retires the active one. No endpoint deletes a key, so a seal signed by a retired key stays verifiable. Pentr holds the private half, stored wrapped, and no endpoint returns it; Key custody describes how it is held. The public half is what a verifier pins when running pentr-verify.

Target¶

A host, address range or application named in the scope of one run. Targets are per-engagement; assets are per-organization. Before an engagement can start, every target and every in-scope entry must be covered by a verified or attested asset whose proof holds at launch.

Target verification¶

The check that your organization controls an asset before Pentr tests it. For a domain, two automated methods exist: a TXT record at _pentr-verify.<domain> containing the asset's token, or that token served at https://<domain>/.well-known/pentr-verification.txt. For IP, CIDR and URL assets no automated method exists, and the only route is a written attestation by an organization owner, which expires after 90 days. Each attempt is recorded in an append-only log. At each launch, a verified asset's check is run again and an attested asset is checked only for expiry.