# Kubernetes Resource Audit 0.2.0

This release is the supported public input path for TacitSoft Kubernetes evaluation. It adds optional usage sampling, a machine-readable advisor-input index, explicit capability coverage, and Bundle Contract `1.0.0`.

## Public and private boundary

The public collector reads, sanitizes, and packages metadata evidence. It captures Kubernetes inventory, request/limit and scheduling data, warning events, security posture metadata, image references, best-effort local lifecycle signals, optional offline image scan results, and best-effort metrics samples. The private evaluator remains responsible for summary CSVs, calculations, recommendations, findings, ruleset interpretation, and anonymized or full reports.

No private implementation, credentials, or customer data is included in this release.

## Safety and offline execution

- Collection runs locally and only talks to the Kubernetes API selected by `kubectl`.
- It never uploads a bundle, changes cluster resources, or performs remediation.
- It does not request Kubernetes `Secret` objects or values, workload environment values, arbitrary annotations, registry credentials, or unfiltered journals.
- Kubernetes API results pass through the bundled metadata sanitizer before being written.
- Optional Syft, Grype, Trivy, and version JSON inputs are normalized locally and are not copied into the bundle.
- `kubectl top` sampling is optional and fails safely when the metrics API or permission is unavailable.
- Generated inventory is classified as sensitive with `handling_state: raw` and `contains_sensitive_data: true`.
- `upload_safe_after_review: true` permits controlled internal upload after review; it does not make raw output customer-shareable.
- `redaction/coverage.json` records every artifact class as `raw`, `redacted`, `omitted`, or `not_collected` and is included in the checksum chain.
- Review context names, resource names, labels, annotations, images, addresses, and collected command errors before upload.

Use a read-only identity with only the `get` and `list` permissions needed for the resources in `bundle-spec.yaml`. Run with `--usage-samples 0` when metrics sampling is not approved.

## Install

```bash
tar -xzf k8s-resource-audit-0.2.0.tar.gz
./k8s-resource-audit/install.sh --prefix ./out/k8s-resource-audit
```

Dry run:

```bash
./k8s-resource-audit/install.sh --dry-run --prefix ./out/k8s-resource-audit
./out/k8s-resource-audit/run-collector.sh --dry-run --output ./out/k8s-bundle
```

## Collect

The default captures three usage samples, 15 seconds apart:

```bash
./out/k8s-resource-audit/run-collector.sh --output ./out/k8s-bundle
```

Choose a context or sampling window explicitly:

```bash
./out/k8s-resource-audit/run-collector.sh \
  --context production-readonly \
  --usage-samples 5 \
  --sample-interval 30 \
  --output ./out/k8s-bundle
```

Local image-supply-chain evidence can be supplied without granting registry access:

```bash
./out/k8s-resource-audit/run-collector.sh \
  --syft-json ./syft.json \
  --grype-json ./grype.json \
  --version-json ./versions.json \
  --output ./out/k8s-bundle
```

`--usage-samples` accepts `0` through `999`; sample artifact names use a fixed
three-digit sequence so validation details never need customer-derived filenames.

The output directory must be empty. This prevents stale artifacts from contradicting the declared capability coverage.

## Compatibility and coverage

The SaaS worker accepts this release only as collector `0.2.0`, bundle schema `2026.06`, Bundle Contract `1.0.0`, and a supported evaluator version. Unsupported combinations fail closed. A valid bundle may omit optional evidence, but it must declare that capability as `partial` or `unavailable`; generated reports then identify checks that could not run.

Historical collector `0.1.0` bundles with schema `2026.05` remain readable through the manual-review legacy adapter. Safety-revised `0.1.0` bundles with schema `2026.06` add redaction coverage and use the same capability-inference adapter. Neither combination can claim usage or advisor coverage it did not collect.

Before upload, inspect `bundle.json`, `redaction/coverage.json`, `manifest.json`, `checksums.sha256`, `collector.log`, `raw/`, and `normalized/`. Operator review alone does not redact raw content. If any artifact is edited or removed, regenerate the manifest and checksums so worker validation can detect the change.