@marinjursic/prc-linux-arm64 0.1.0

package/bin/docs/scanner/infrastructure-policy.md

@@ -0,0 +1,64 @@
+# Infrastructure policy profile
+
+`prc/iac@0.1` combines bounded native checks with a reviewed Checkov 3.3.8
+analysis of inventoried Terraform, Kubernetes, and container definitions. It is
+applicable only when the inventory contains at least one of those inputs.
+
+## Run it
+
+Review `adapters/checkov-v3.3.8.yaml` in the release or repository root, then
+pre-pull the exact reviewed image:
+
+```bash
+docker pull docker.io/bridgecrew/checkov@sha256:c64ffb6d6fc8087c896341a2c697770a04a1cf558db04fa7b8129d8ca6bce336
+```
+
+Run the profile with an explicit local-verification capability grant:
+
+```bash
+./prc scan /path/to/project \
+  --profile prc/iac \
+  --mode verify-local \
+  --adapter-manifest adapters/checkov-v3.3.8.yaml
+```
+
+The ordinary `prc scan` command does not launch Checkov or any other external
+analyzer. The `verify-local` mode and exact manifest are both required.
+
+## What is evaluated
+
+The profile includes native checks for immutable container base identities,
+non-root container users, Terraform dependency locks, Kubernetes non-root
+workloads, privilege restrictions, Linux capabilities, seccomp, and container
+resource requests and limits. `PRC-A-IAC-001` additionally consumes only the
+`iac-policy` observations from the exact manifest digest bound into the catalog.
+
+Checkov receives a scanner-owned list containing exactly the inventoried
+Terraform, Kubernetes, and Dockerfile paths. A passing adapter result means that
+the checks embedded in this pinned image reported no violation for supported
+inputs. It does not prove deployed-state correctness, runtime behavior, cost,
+drift, accessibility of external modules, or coverage by future policies.
+
+## Isolation and failure behavior
+
+The adapter:
+
+- mounts a content-verified snapshot read-only and rechecks its digest before
+  and after execution;
+- runs as the invoking non-root identity with no network, dropped capabilities,
+  a read-only container filesystem, bounded resources, and scanner-owned
+  scratch;
+- disables policy downloads, result upload, external modules, variable
+  evaluation, and external checks;
+- runs outside the target working directory so `.checkov.yml` cannot change the
+  scanner-owned policy or hide passed results;
+- rejects inline suppressions, parsing errors, output drift, unexpected online
+  metadata, code disclosure, unbound paths, and unbounded records; and
+- accepts bounded graph entity objects only long enough to validate the native
+  report, then discards them so raw target configuration is not persisted in
+  normalized artifacts.
+
+A verified policy violation becomes a canonical finding in the detailed HTML
+report. Unsupported files, ambiguous outcomes, parser failures, and safety
+violations never become a pass. `prc scan` still does not modify Terraform,
+Kubernetes, Dockerfiles, cloud resources, clusters, or any other target.

package/bin/docs/scanner/kubernetes-workloads.md

@@ -0,0 +1,63 @@
+# Kubernetes workload analysis
+
+The focused `prc/kubernetes@0.1` profile performs bounded, no-execution
+repository analysis of detected Kubernetes workload manifests. Its six
+assertions cover non-root execution, resource requests and limits, privileged
+host access, privilege escalation, Linux capabilities, and seccomp profiles.
+The same assertions are included in `prc/core-repository@1.0`.
+
+Run only the Kubernetes assertions with:
+
+```bash
+prc scan \
+  --target PATH \
+  --catalog-root PATH_TO_RELEASE \
+  --profile prc/kubernetes
+```
+
+## Security properties
+
+The native checks inspect `Pod`, `Deployment`, `StatefulSet`, `DaemonSet`,
+`ReplicaSet`, `Job`, and `CronJob` pod specifications. For ordinary, init, and
+ephemeral containers where the field is defined by Kubernetes, they verify:
+
+- `runAsNonRoot` is affirmed at pod or container scope and `runAsUser: 0` is
+  absent;
+- host networking, PID, and IPC namespaces remain unset or false, Windows
+  HostProcess remains unset or false, `hostPath` volumes are absent, and
+  containers are not privileged;
+- Linux containers explicitly set `allowPrivilegeEscalation: false`;
+- Linux containers drop `ALL` capabilities and add back at most
+  `NET_BIND_SERVICE`;
+- Linux containers inherit or select a `RuntimeDefault` or `Localhost` seccomp
+  profile; and
+- ordinary and init containers declare nonempty resource requests and limits.
+
+The security behavior follows the relevant Baseline and Restricted fields in
+the authoritative
+[Kubernetes Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/).
+The Linux-only privilege-escalation, capability, and seccomp requirements are
+not applied when `spec.os.name` is explicitly `windows`, matching the standard's
+operating-system distinction. The
+[Kubernetes security-context documentation](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/)
+explains how those fields affect container isolation.
+
+## Evidence and failure behavior
+
+Each result binds content-addressed evidence to the inventoried manifest. A
+failure reports bounded file, line, and column locations without executing
+`kubectl`, Helm, Kustomize, manifest hooks, or target code. A file over the
+native parser limit, malformed YAML, a duplicate mapping key, an alias, a
+mutation after inventory, or another unprovable parse condition returns an
+execution error and `unknown`, never a pass.
+
+## Deliberate limitations
+
+This profile is not a complete Pod Security Admission implementation. It does
+not render templates or overlays, inspect custom workload resources, resolve
+external values, validate every Kubernetes API field, prove that admission
+policy is enabled, inspect an image, contact a cluster, or prove what is
+deployed. It also does not infer a risk exception for workloads that
+intentionally need host or elevated access. Those cases require explicit,
+separately authorized evidence or a signed time-bounded exception; the native
+repository result remains a failure.

package/bin/docs/scanner/mcp-agent-integration.md

@@ -0,0 +1,138 @@
+# Read-only MCP agent integration
+
+The scanner can expose its deterministic inspect surface to Codex, Claude Code,
+or another local Model Context Protocol client. The MCP process is a read-only
+observer for one target selected by the operator at startup. It does not give a
+model a new write path, execute project commands, launch adapters or providers,
+store state, apply remediation, accept risk, or make a release decision.
+
+This separation is intentional: the agent may edit a workspace through its own
+reviewed tools, while the scanner independently rebuilds evidence and decides
+whether the exact target now satisfies the selected profile.
+
+## Start a path-locked server
+
+Build the scanner, then give the server absolute paths for both the trusted
+catalog and the repository being assessed:
+
+```bash
+go build -trimpath -o /absolute/path/prc ./cmd/prc
+
+/absolute/path/prc mcp serve \
+  --catalog-root /absolute/path/production-readiness-checklist \
+  --target /absolute/path/project \
+  --profile prc/core-repository
+```
+
+An optional validated configuration can be locked into the assessment:
+
+```bash
+/absolute/path/prc mcp serve \
+  --catalog-root /absolute/path/production-readiness-checklist \
+  --target /absolute/path/project \
+  --config /absolute/path/project/production-readiness.yaml
+```
+
+The server resolves catalog, target, and configuration symlinks once. The
+catalog is validated and loaded once, and the selected profile cannot change
+during that process. The target and configuration contents are read again for
+every plan or scan so edits made outside the server invalidate their prior
+content identities.
+
+The stdio process writes only newline-delimited JSON-RPC messages to stdout.
+Diagnostics use stderr. It supports the MCP `2025-11-25` and `2025-06-18`
+handshake revisions, advertises a fixed tool list, and emits both structured
+content and the same serialized JSON as text for older clients. See the official
+[MCP lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle),
+[stdio transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports),
+and [tool result](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
+contracts.
+
+## Available tools
+
+| Tool | Input | Result | Capability boundary |
+| --- | --- | --- | --- |
+| `prc_plan` | Empty object | Versioned inspect plan and execution DAG | Reads inventory; runs nothing |
+| `prc_scan` | Empty object | Versioned run identity, gate, bounded inventory summary, assertion results, evidence, and findings | Native inspect implementations only |
+| `prc_explain` | One `assertion_id` | Exact catalog assertion and sorted linked objectives | Catalog read only |
+
+All three definitions set MCP `readOnlyHint: true`, `destructiveHint: false`,
+and `openWorldHint: false`. Those annotations help a client present the tools,
+but the implementation also enforces the boundary: tool arguments cannot supply
+a target, catalog, configuration, command, adapter, provider, network host,
+secret, output path, or remediation mode.
+
+`prc_scan` omits the complete file inventory from the agent-facing payload to
+bound context size. It retains the inventory digest, plan digest, canonical run
+ID, evidence-linked result set, and canonical findings. Scanner errors are
+returned as visible MCP tool errors; they are never rewritten as passing results.
+
+## Connect Codex
+
+Codex local clients support command-launched stdio MCP servers. Register the
+scanner with the same absolute, operator-reviewed arguments:
+
+```bash
+codex mcp add production-readiness -- \
+  /absolute/path/prc mcp serve \
+  --catalog-root /absolute/path/production-readiness-checklist \
+  --target /absolute/path/project \
+  --profile prc/core-repository
+```
+
+Codex stores server configuration in user or trusted-project configuration;
+review that scope before enabling it. See the official
+[Codex MCP documentation](https://developers.openai.com/codex/mcp/).
+
+## Connect Claude Code
+
+Use a local scope unless the exact command should deliberately be shared with a
+team:
+
+```bash
+claude mcp add --transport stdio --scope local production-readiness -- \
+  /absolute/path/prc mcp serve \
+  --catalog-root /absolute/path/production-readiness-checklist \
+  --target /absolute/path/project \
+  --profile prc/core-repository
+```
+
+Confirm the connection with `claude mcp get production-readiness` or `/mcp`.
+Claude Code documents local stdio commands and the security implications of MCP
+configuration in its official
+[MCP guide](https://code.claude.com/docs/en/mcp).
+
+## Evidence-driven agent loop
+
+An agent using this server should follow one narrow loop:
+
+1. Call `prc_plan` and preserve every blocked or undetermined node.
+2. Call `prc_scan` and use its `run_id`, `plan_digest`, finding IDs, and evidence
+   as the baseline.
+3. Use `prc_explain` before changing code for an unfamiliar assertion.
+4. Propose or make one bounded change through the agent host's normal reviewed
+   filesystem tools, not through this MCP server.
+5. Call `prc_scan` again. A changed workspace must produce a new inventory,
+   plan, and run identity.
+6. Continue only while changes remain within the user's authority and the
+   scanner reports independently verifiable findings. Stop on unknown, manual,
+   policy, production-only, or organizational evidence that code cannot prove.
+
+The current `prc/core-repository@1.0` profile contains 40 repository assertions.
+A satisfied profile means only that this versioned profile passed for that exact
+inventory and evidence set. It does not mean that all 10,042 checklist controls,
+runtime behavior, production infrastructure, organizational processes, or
+unknown defects were autonomously verified.
+
+## Fail-closed limits
+
+The server rejects duplicate JSON keys, unknown request and tool fields,
+non-integer numeric request IDs, path-like tool arguments, messages larger than
+1 MiB, and successful tool payloads larger than 8 MiB. Calls are accepted only
+after the MCP initialization lifecycle completes. A clean stdin close ends the
+process normally; startup configuration failures use CLI exit `3`, and a broken
+stdio transport uses exit `4`.
+
+There is intentionally no MCP remediation tool. Use the scanner's
+[bounded isolated remediation](remediation.md) commands separately when their
+explicit candidate and policy controls fit the task.

package/bin/docs/scanner/openapi-contracts.md

@@ -0,0 +1,75 @@
+# OpenAPI contract analysis
+
+`PRC-A-API-001` through `PRC-A-API-003` are language-neutral, no-execution
+checks for the bounded root and directly declared operation structure of
+detected OpenAPI YAML and JSON documents. They are available as the focused
+`prc/api@0.1` profile and as part of `prc/core-repository@1.0`. Inventory recognizes the
+conventional `openapi.yaml`, `openapi.yml`, and `openapi.json` names, plus
+bounded YAML files with a top-level OpenAPI 3.x marker. Each detection is
+recorded as an `api-description` component and a sourced fact with an explicit
+limitation: a description does not prove that its API is implemented, reachable,
+or deployed.
+
+Run only these contract checks with:
+
+```bash
+prc scan --target PATH --catalog-root PATH_TO_RELEASE --profile prc/api
+```
+
+## What the rule proves
+
+For published OpenAPI 3.0, 3.1, and 3.2 feature versions, the native checks
+verifies that:
+
+- the file contains exactly one parseable YAML or JSON document with an object
+  root;
+- `openapi` is a nonempty supported semantic version string;
+- `info` is an object with nonempty string `title` and `version` fields;
+- OpenAPI 3.0 has a `paths` object; and
+- OpenAPI 3.1 and 3.2 have at least one object-valued `paths`, `components`, or
+  `webhooks` field;
+- every directly declared operation under `paths` or `webhooks` has a nonempty
+  Responses Object containing at least one valid response code or `default`;
+- every inline Response Object has its required nonempty `description`, while a
+  structurally valid `$ref` remains a reference rather than an invented pass for
+  its remote target; and
+- every declared `operationId` is a nonempty string and is unique within that
+  OpenAPI document. Because `operationId` is optional, the check does not require
+  one where the specification does not.
+
+These are requirements from the authoritative
+[OpenAPI 3.0.4 specification](https://spec.openapis.org/oas/v3.0.4.html),
+[OpenAPI 3.1.2 specification](https://spec.openapis.org/oas/v3.1.2.html), and
+[OpenAPI 3.2.0 specification](https://spec.openapis.org/oas/v3.2.0.html).
+OpenAPI 3.1 and 3.2 descriptions may legitimately describe only reusable
+components or webhooks, while 3.0 requires `paths`; an empty Paths Object is
+allowed by the specifications.
+
+Duplicate mapping keys, non-string mapping keys, missing required
+metadata, and incorrect root-field types produce a finding with bounded source
+locations. Invalid syntax produces Error/Unknown. A syntactically valid but
+unsupported feature version, such as a future 3.3 document, also produces
+Error/Unknown instead of a false Pass or Fail; a new benchmarked implementation
+version is required before the scanner claims support.
+
+## Bounds and evidence
+
+The implementation inspects at most 256 detected documents and 64 MiB in total.
+The shared native reader caps each parsed file at 4 MiB and verifies its bytes
+against the content-addressed inventory before parsing. YAML shape inspection is
+bounded to 100,000 nodes and 128 levels. The scanner records file-hash evidence,
+never document content, and reports at most 100 structural problems.
+
+## Deliberate limitations
+
+This is not a complete OpenAPI conformance validator. Operation checks cover
+operations declared directly under `paths` and `webhooks`, including the
+OpenAPI 3.2 `query` and `additionalOperations` fields. They do not resolve Path
+Item references, callbacks, multi-document descriptions, response references,
+or remote documents. A reference is therefore not proof that its target is
+valid. The checks also do not validate every nested object, compare the
+description with application routes or deployed behavior, lint API design, test
+requests, infer exposure, or decide compatibility. Full conformance, contract
+testing, reference resolution, and runtime drift require separately versioned
+adapters with explicit filesystem, process, network, authentication, target,
+and destructive-request policies.

package/bin/docs/scanner/private-key-armor.md

@@ -0,0 +1,44 @@
+# Bounded private-key armor inspection
+
+`PRC-A-CORE-031` is a deterministic, no-network guard against committing
+recognized armored private-key blocks. It inspects content-addressed files from
+the current inventory and never copies a matched marker or following key bytes
+into evidence, findings, logs, or reports. A failure identifies only the file
+path, inventory and content digests, and a redacted summary.
+
+The native rules cover private and encrypted private-key labels standardized by
+[RFC 7468](https://www.rfc-editor.org/info/rfc7468/), legacy RSA, EC, and DSA
+private-key labels, the
+[OpenSSH private-key format](https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.key),
+and armored PGP private-key blocks. Public-key and certificate armor is not a
+failure.
+
+## Fail-closed bounds
+
+The check scans recognized source, configuration, documentation,
+infrastructure, environment, and key-file paths. Repository dotfiles are also
+included, except platform metadata that is already excluded by inventory. It
+stops as Blocked/Unknown instead of returning Pass when any of these bounds
+would prevent complete inspection:
+
+- 10,000 candidate files;
+- 8 MiB per candidate file; or
+- 256 MiB across all candidate files.
+
+Every file is reopened without following a symlink and checked against its
+inventoried size, mode, and SHA-256 before its bytes are inspected. A target
+mutation is an execution error, never a passing result. Reports include at most
+100 violating locations while retaining the exact total count.
+
+## Deliberate limitations
+
+This check does not inspect Git history, ignored dependency/cache directories,
+binary or unrecognized file types, remote artifacts, container layers, secret
+stores, deployed environments, or arbitrary vendor API-token formats. It does
+not prove that a recognized key is live, but a detected private-key block is
+still a critical no-go because verification must not expose or exercise it.
+
+Broader secret detection belongs to a maintained, digest-pinned analysis
+adapter with a tool-specific benchmark corpus. Until such an adapter is
+published and authorized, `PRC-A-CORE-013` remains independently Blocked; this
+narrow native check must not be presented as complete secret-scanning coverage.

package/bin/docs/scanner/releases.md

@@ -0,0 +1,160 @@
+# Scanner releases and verification
+
+Scanner binaries use `scanner-vX.Y.Z` tags so their experimental product version
+does not collide with versions of the checklist corpus. A release is built only
+from the exact tagged commit. The workflow reruns the source, catalog, schema,
+security, benchmark, and pack gates before publishing anything.
+
+## Release contents
+
+Each scanner release contains:
+
+- Linux, macOS, and Windows archives for AMD64 and ARM64;
+- one dependency-free `@marinjursic/prc` npm launcher tarball and six exact
+  native npm platform tarballs for the same systems;
+- a binary with the scanner version, source revision, source timestamp, and Go
+  toolchain embedded in `prc version --format json`;
+- the exact compatible `catalog/`, `packs/`, and `schemas/` trees in every
+  archive, together with the catalog's human-readable objective sources and the
+  packs' benchmark fixtures;
+- a versioned release manifest binding artifact digests to the catalog and pack
+  validation digests;
+- a timestamp-free [CycloneDX 1.6](https://cyclonedx.org/specification/overview/)
+  module SBOM;
+- a canonical self-scan of the exact tagged source, executed by the packaged
+  binary against its bundled catalog without hiding blocked or manual results;
+- `SHA256SUMS`; and
+- GitHub-hosted Sigstore attestations for SLSA build provenance and the
+  CycloneDX SBOM predicate.
+
+The SBOM describes the scanner's Go module and resolved Go dependencies. It does
+not claim that the bundled catalog data, schemas, host operating system, or
+future adapter images are Go components; those files are integrity-bound by the
+archive checksum and release manifest instead. GitHub documents what its
+[artifact attestations](https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations)
+prove and how consumers should verify them.
+
+The builder fixes archive order, ownership, modes, paths, timestamps, binary
+metadata, and source identity. CI builds the complete release twice and requires
+a byte-for-byte directory comparison. This is a reproducibility check under the
+same declared CI toolchain; it is not a claim that provenance or reproducibility
+proves the artifact is secure.
+
+## Verify before running
+
+Download the archive, `SHA256SUMS`, release manifest, and SBOM from the same
+GitHub release. Verify the checksum from the directory containing those files:
+
+```bash
+sha256sum --check SHA256SUMS
+```
+
+On macOS, verify one downloaded archive against the matching line instead:
+
+```bash
+shasum -a 256 prc_0.1.0_darwin_arm64.tar.gz
+grep 'prc_0.1.0_darwin_arm64.tar.gz' SHA256SUMS
+```
+
+Then verify that GitHub's signed provenance binds the archive to this repository
+and release workflow:
+
+```bash
+gh attestation verify prc_0.1.0_linux_amd64.tar.gz \
+  --repo MarinJursic/production-readiness-checklist
+```
+
+Verify the separate CycloneDX SBOM attestation using its recognized predicate:
+
+```bash
+gh attestation verify prc_0.1.0_linux_amd64.tar.gz \
+  --repo MarinJursic/production-readiness-checklist \
+  --predicate-type https://cyclonedx.org/bom
+```
+
+Finally, inspect `prc_X.Y.Z_release-manifest.json` and compare its
+`source_commit`, catalog digest, pack digests, and artifact digest with the
+assessment scope you intend to use. Inspect `prc_X.Y.Z_self-scan.json` as a
+normal `prc.run/v0.12` report: a valid signed self-assessment may still be
+`environment_blocked` because organizational, production, or adapter evidence
+is deliberately unavailable in the release job. After extraction:
+
+```bash
+./prc_X.Y.Z_linux_amd64/prc version --format json
+```
+
+The release manifest also binds every npm tarball. Before the packages are
+published to npm, they can be tested directly from one release directory. On
+Linux x64, for example:
+
+```bash
+mkdir npm-smoke && cd npm-smoke
+npm install --ignore-scripts --offline --no-audit --no-fund --package-lock=false \
+  ../marinjursic-prc-linux-x64-X.Y.Z.tgz \
+  ../marinjursic-prc-X.Y.Z.tgz
+./node_modules/.bin/prc version --format json
+./node_modules/.bin/prc scan /path/to/project
+```
+
+The platform package contains the native binary and its exact catalog. The
+launcher checks the platform manifest and binary SHA-256 and never downloads a
+fallback or starts a binary found on `PATH`. Public npm publishing uses npm
+trusted publishing from the pinned release workflow, so the workflow refuses
+`NPM_TOKEN` and `NODE_AUTH_TOKEN`. It verifies all seven tarballs against the
+release manifest, publishes the six native packages before the launcher,
+verifies the registry SHA-512 for every package, and safely skips only an
+already-published version with exactly matching bytes. Because npm versions are
+immutable, any byte mismatch stops the release. The publisher also runs npm in
+a new empty working directory with user, global, and environment npm
+configuration removed, so a saved `.npmrc` token cannot silently replace OIDC.
+
+The release job builds once, uploads those exact bytes, then runs the matching
+native archive and npm launcher on Linux x64, Linux ARM64, macOS x64, macOS
+ARM64, Windows x64, and Windows ARM64. Publication starts only after every host
+has completed a real 10,042-control smoke scan.
+
+### One-time npm owner setup
+
+npm requires a package to exist before a trusted publisher can be configured.
+The owner must therefore bootstrap each of the seven package names once from
+the exact verified release tarballs, with npm's required human authentication.
+Then configure the same trusted-publisher identity on every package:
+
+- repository owner: `MarinJursic`;
+- repository: `production-readiness-checklist`;
+- workflow filename: `release-scanner.yml`; and
+- no GitHub environment unless the workflow is later changed to use one.
+
+After that one-time setup, `scanner-vX.Y.Z` tags use OIDC and no long-lived npm
+publishing secret. The release workflow requires Node.js 22.14 or newer and npm
+11.5.1 or newer for trusted publishing. npm provenance links a package to its
+build source; it does not prove the package has no unsafe code.
+
+Do not substitute a successful signature check for vulnerability review or a
+production-readiness decision. An attestation proves the signed claim's origin
+and integrity, not the absence of defects.
+
+## Release failure and revocation
+
+Publishing is fail closed: an invalid tag, test failure, benchmark regression,
+schema failure, vulnerability finding, non-reproducible output, checksum error,
+or attestation failure prevents release publication. A failed workflow is not a
+release and its temporary artifacts are not supported.
+
+If a signing identity, workflow dependency, tool, release asset, catalog, pack,
+or scanner version is compromised or materially incorrect, maintainers will:
+
+1. publish a private-to-public security advisory as coordination permits;
+2. mark the affected release and version as revoked, with the exact artifact
+   digests and reason;
+3. remove or revoke affected attestations where the platform supports it;
+4. never reuse the affected version or tag and never replace an asset under the
+   same name;
+5. publish a new patched version from a reviewed commit with new checksums,
+   SBOM, provenance, and compatibility manifest; and
+6. update bundled trust stores or registry revocations when a pack, adapter, or
+   publisher identity is affected.
+
+Consumers should stop using a revoked artifact even if its historical signature
+still verifies: verification establishes who produced it, not whether it remains
+approved.