watchlight-enclave 0.2.1__tar.gz

watchlight_enclave-0.2.1/.gitignore

@@ -0,0 +1,18 @@
+# build + runtime
+target/
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+
+# enclave run artifacts
+.watchlight/
+runs/
+*.tgz
+
+# os
+.DS_Store
+
+# shoalscan scan output (the baseline and policy ARE committed)
+.shoalscan/runs/

watchlight_enclave-0.2.1/CHANGELOG.md

@@ -0,0 +1,303 @@
+# Changelog
+
+Notable changes to Watchlight AI Enclave. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## Three contracts, versioned separately
+
+This project has three promises, and only the first is what the version number
+on the tag tracks. Knowing which one a change touches is the difference between
+a routine upgrade and a broken pipeline.
+
+**1. The CLI surface and `enclave.yaml` schema.** What the tag versions.
+Pre-1.0, these may change in a minor release.
+
+**2. How strictly `wl-enclave verify` reads a bundle.** Not covered by the
+format version, and the one most likely to surprise you: *a stricter verifier
+is a breaking change for a CI gate even when the bundle format is identical.* A
+bundle that exited 0 on one version can exit 1 on the next because the verifier
+learned to notice something it used to miss. Every release that tightens
+`verify` says so under **Verifier** below, in those words.
+
+**3. The bundle format**, currently `wl-enclave-evidence/1`. This moves only
+when an older verifier would *misread* a newer bundle. Adding a field is not a
+bump, because old verifiers ignore unknown fields. Changing what an existing
+field means is a bump. This number has to age well: a bundle in someone's
+compliance archive must stay verifiable for as long as they keep it.
+
+1.0 is gated on the manifest reaching its final shape. Operator signing is in
+(see 0.2.0), but witness cosignatures ([#2–#6]) are the part that decides
+what a sealed manifest ultimately holds. Promising format stability before then
+would mean breaking that promise immediately.
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.2.1] — 2026-11-10
+
+**Packaging, documentation, and what `keygen` prints.** No change to
+`enclave.yaml`, to how strictly `verify` reads a bundle, or to the bundle
+format. Nothing here can change the verdict on a bundle you already hold. The
+one behavioural change is two output labels in `keygen`, which matters only if
+you parse them.
+
+This is also the release where the repository became public.
+
+This is the first release on PyPI: `pip install watchlight-enclave`. 0.2.0 was
+tagged before the publishing workflow existed, and a publish must come from a
+tag that carries it, so the first published version is this one. 0.2.0 remains
+a GitHub release and an install from source; nothing was published under it.
+
+### Added
+
+- **`publish-pypi.yml`** — publishing over OIDC trusted publishing, so no
+  long-lived API token exists in the repository or anywhere else. Manual, and
+  a dry run unless told otherwise. Four gates, each refusing rather than
+  warning, because a PyPI filename is permanent and a bad upload cannot be
+  corrected in place, only yanked:
+  - a publish must come from a `v*` tag;
+  - `pyproject.toml`, `wl_enclave.__version__` and the tag must agree, and
+    exactly one wheel and one sdist must name that version;
+  - no key or credential material in either distribution — `wl-enclave
+    keygen` writes Ed25519 private keys as `.pem` files, so a key left in the
+    working tree is a real way to publish one by accident — and no wheel
+    missing `evidence.py` or `signing.py`, since the verifier is the thing
+    third parties are promised;
+  - the built wheel is installed in a clean virtualenv and run, including
+    `keygen`, which exercises the lazy `cryptography` import through the real
+    entry point. An undeclared dependency would otherwise surface only when a
+    user tried to sign.
+- **`github-release.yml`** — release notes taken from this file rather than
+  written twice. The notes state which of the three contracts a release moved,
+  and a reader deciding whether an upgrade breaks their CI gate relies on that
+  being accurate; a second copy drifts. A missing or empty section for the
+  tagged version fails the run rather than falling back to generated notes.
+
+### Documentation
+
+- **[`SECURITY.md`](SECURITY.md)** — private disclosure, mirroring the
+  [Developer Edition](https://github.com/watchlight-ai-beacon/watchlight-de)
+  policy: same routes, same response windows, same safe harbour. It adds one
+  section that policy does not need — *what we treat as most severe*. A bundle
+  that understates what happened while still verifying ranks above remote code
+  execution in the CLI here, so the policy says so outright, lists the four
+  shapes it takes, and names the two limits that are already documented
+  (key-holder re-seal, and traffic the topology blocks but the guard never
+  sees) so nobody spends a weekend rediscovering them.
+- **[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)** — the Developer Edition file
+  verbatim, Contributor Covenant 2.1, reports to conduct@watchlight.ai.
+- **A package page of its own.** `readme` points at `README-pypi.md`, 4.2 kB
+  rather than 18 kB. The repository README is for someone deciding whether to
+  trust the design; a package page's job is to get you installed and then send
+  you to the repository, which is where the documentation lives.
+- **`[project.urls]`** was absent, so the package page had no route back to the
+  source. For a project whose claim is that you can read the verifier
+  yourself, that is the one link that has to work.
+- `CONTRIBUTING.md` told you to open a public issue for a weakness in the
+  evidence model and said a security policy was coming. Both are now wrong. It
+  also documents that `main` requires an approving review, and that the
+  maintainer bypass does not extend to the status checks.
+- The README dropped a duplicated paragraph and a status line claiming no
+  releases existed, and gained a section pointing at Developer Edition for
+  anyone who arrived via a bundle and wants to know where the decisions in it
+  come from.
+
+### Changed
+
+- **`keygen` says `private key` and `public key id`**, where it said `key` and
+  `key id`. One is a file to protect and the other is a string to publish, and
+  the old labels left the reader to work that out. Getting it backwards goes
+  wrong in both directions: pasting a private key into a ticket, or withholding
+  the one value a reviewer needs in order to pin a signer. The command now also
+  states that the private key stays in its file and is not copied into a
+  bundle, mounted into the sandbox, or sent anywhere — the question the old
+  output invited and did not answer. **If you parse `keygen` output, match on
+  `public key id`.**
+- `signing.exposed_by()` is documented correctly. It is the check that refuses
+  a run when the signing key sits inside a directory mounted into the sandbox,
+  which is the guard against an agent reading the key that signs its own
+  evidence. Its docstring described the symlink case backwards, and the test
+  covering that case was named for the opposite of what it asserted. The
+  behaviour was right; only the description was wrong.
+- The sdist is an explicit include list instead of hatchling's default, which
+  is the whole working tree minus VCS ignores. The files it had been sweeping
+  in were harmless — CI config, a scanner baseline — but the default is *open*,
+  so anything added to the repository later would ship by default and nobody
+  would find out until it was on an immutable index. `tests/` and `crates/`
+  are included deliberately: the forgery tests are how a third party confirms
+  the verifier refuses what it says it refuses, and the guard crate is where
+  record-before-forward lives.
+
+## [0.2.0] — 2026-11-10
+
+### Added
+
+- **`wl-enclave hosts [--since DATE]`** — every host the agent reached, across
+  runs, with verdict, attempt count, bytes each way and the address actually
+  dialled. The records existed from the first release and there was no way to
+  read them back, so the product recorded the thing it is best at and could not
+  show you. A run whose bundle does not verify is **excluded and announced**,
+  because a shorter, tidier host list is the one way this command could
+  mislead; the exit status is non-zero whenever the table is not both
+  trustworthy and complete, and the guard's coverage
+  (`http_connect` only) prints beside the answer rather than in a footnote.
+
+- **Signed manifests.** `wl-enclave keygen` writes an Ed25519 key (default
+  `~/.config/wl-enclave/signing.key`, mode 0600, outside both the repository
+  and the bundle); `run` seals a signature over the manifest body when a key
+  resolves. A key named explicitly — `--sign-key` or `$WL_ENCLAVE_SIGNING_KEY`
+  — that cannot be read is an error, because sealing unsigned after being asked
+  to sign is the kind of quiet downgrade this format exists to prevent. No key
+  anywhere still seals unsigned, so an install that never runs `keygen` behaves
+  as it did. [#2–#6]
+- **`verify --signer KEY_ID`** and **`verify --require-signature`**. The first
+  is the only form of the check that establishes *who* sealed a bundle. The
+  second accepts any key but requires one.
+- **`cosignatures` in every manifest**, written empty, and verified when
+  present. A witness the signer does not run is what would make a bundle
+  evidence against its operator rather than only against the agent; reserving
+  and checking the slot now means adding one later changes neither the bundle
+  format nor the verifier.
+
+### Changed
+
+- **`verify` grades signing in three steps rather than two.** The summary reads
+  `unsigned`, `self-signed`, or `signed by the expected key`. `self-signed` is
+  not a hedge: the public key travels inside the bundle, so a verifying
+  signature establishes that the manifest is unchanged and *not* who sealed it.
+  Anyone can produce a bundle in that state.
+- **One manifest payload.** Four seal sites built this independently and three
+  disagreed, which was survivable while the manifest was only read and is not
+  once it is signed.
+- New runtime dependency: `cryptography>=42.0`. Imported lazily, so verifying
+  an *unsigned* bundle still works if it is missing.
+
+### Verifier
+
+**This release does not tighten `verify` by default.** `--signer` and
+`--require-signature` are opt-in, so a gate standing on a bundle sealed by
+0.1.0 keeps passing. Two new ways to fail exist once you opt in: an unsigned
+bundle under `--require-signature` reads `incomplete` (everything in it is
+still true; what is missing is attribution), while a signature that does not
+verify, names a `key_id` its own public key does not produce, carries an
+unrecognised algorithm, or belongs to a key other than the pinned one reads
+`failed` (a contradiction, not a gap).
+
+### Format
+
+`wl-enclave-evidence/1` is unchanged. `signature` and `cosignatures` are added
+fields, and a verifier that predates them reports a signed bundle as
+`unsigned` — weaker than the truth, which is the only direction a stale
+verifier may err.
+
+### Known gaps
+
+- **A signature is not a completeness proof.** The key holder can truncate the
+  chain, write a `run.close` whose counts agree with what is left, re-seal, and
+  the bundle verifies as `ok` against a pinned key with a denial missing.
+  `tests/test_signing.py::test_a_key_holder_can_still_reseal_a_truncated_chain`
+  performs that forgery and asserts it *succeeds*, so the limit cannot become a
+  claim by accident. Only a witness cosignature closes it. [#2–#6]
+
+## [0.1.0] — 2026-11-05
+
+First tagged version. Previously unreleased, so there is no upgrade path to
+describe — but the entries below are the state of the three contracts as of
+this tag.
+
+### Evidence
+
+- **Four verdicts instead of a boolean.** `OK`, `INCOMPLETE`, `UNCONTAINED`,
+  `FAILED`, as the worst of three independent claims (integrity, containment,
+  completeness). Only `OK` exits 0, so a CI gate can branch on the exit code
+  alone. `UNCONTAINED` is deliberately not a milder `FAILED`: `FAILED` means
+  *do not trust this file*, `UNCONTAINED` means *trust it and act on what it
+  says*.
+- **Named controls with provenance.** Each control records whether it was in
+  force *and how that was established* — `runtime_readback`,
+  `network_topology`, `runtime_config_readback`, or
+  `requested_not_readback`. The last one establishes nothing, and that is
+  enforced rather than documented: a control resting on it is reported as
+  unverified whatever it claims.
+- **Containment and witnessing are separate claims.** A guard that dies on an
+  internal network leaves the sandbox *more* contained and *less* witnessed, so
+  that reads `INCOMPLETE`, not `UNCONTAINED`.
+- **Governing digests.** `config.attested` records the digest of `enclave.yaml`
+  and every policy file that governed the run.
+- **The guard build is identified.** `egress.guard_started` carries the image
+  digest the daemon ran (not self-reported, so the guard cannot lie about it)
+  and the version the binary announced on startup (self-reported, but the only
+  one that survives an image rebuilt under the same tag).
+
+### Verifier
+
+Stated here because this is the section future releases will use to warn you.
+
+- **`verify` requires records that must exist to exist.** A run must have
+  exactly one terminal record; a guard that started owes an attestation; a
+  `run.close` tally is cross-checked against the chain. Without these,
+  absence was indistinguishable from compliance and the emptiest bundle looked
+  like the cleanest one.
+- **`run.error` caps at `INCOMPLETE`.** A run that died during startup attested
+  nothing, and the absence of those records is not evidence of a clean run.
+- **Unrecognised control names are reported** rather than sorted into a claim
+  by guesswork.
+
+### Containment
+
+- **The sandbox never runs as root.** The driver passes `--user` regardless of
+  what the image declares, because an image with no `USER` directive runs as
+  uid 0 and most published base images have none. Attested as
+  `runs_as_non_root`, read with `id -u` from inside rather than from the
+  runtime's config.
+- **The evidence mask is confirmed by effect, not by configuration.** A canary
+  planted behind the mask must be unreadable from inside *and* a canary at an
+  unmasked path must be readable in the same probe round — otherwise "the mask
+  held" and "we could not observe anything" are the same observation.
+- Read-only rootfs, all capabilities dropped, `no-new-privileges`, and an
+  internal network with the egress guard as the only route.
+
+### Egress
+
+- **Recording is a precondition for forwarding.** If the guard cannot record an
+  attempt, it refuses the connection. A refused connection is a denial of
+  service the agent can see and the bundle explains; an unrecorded one is a
+  silent hole.
+- **Saturation notes have their own budget**, so a flood of cheap payload-free
+  connections cannot exhaust the budget that real records need and leave a
+  later tunnel unrecorded.
+- **Malformed requests are recorded** and claim no host, because none was
+  parsed. Guessing one would put an attacker-chosen string in the field a
+  reviewer reads as a destination.
+- Addresses are resolved once, validated, and the validated address is dialled
+  — never the hostname again, which is what DNS rebinding relies on. The
+  address actually dialled is recorded.
+
+### Known gaps
+
+Each is stated in the bundle or the docs rather than left to be discovered.
+
+- **Bundles are unsigned.** The chain catches edits, not truncation, and says
+  nothing about origin. `verify` prints this on every run. [#2–#6]
+  *(Addressed in part under Unreleased: manifests can now be signed, which
+  moves the forger from anyone with write access to the key holder. It does not
+  close truncation by the key holder.)*
+- **Traffic blocked by topology is not recorded.** A raw socket to an arbitrary
+  port has no route, so the guard never sees it: blocked, but not described.
+  The bundle states this in `blocked_not_recorded`. [#12]
+- **Decision records are cooperative.** The SDK is a library the agent calls.
+  An agent that does not call it produces no decision records, and the bundle
+  cannot distinguish that from an agent that made none. The egress records do
+  not have this problem, because the agent cannot route around the network
+  topology — so the two streams are not equally strong.
+- **The workspace is writable**, so a run can edit the rules the next run is
+  held to. Made visible with digests rather than prevented. [#13]
+
+[Unreleased]: https://github.com/watchlight-ai-beacon/watchlight-enclave/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/watchlight-ai-beacon/watchlight-enclave/releases/tag/v0.2.1
+[0.2.0]: https://github.com/watchlight-ai-beacon/watchlight-enclave/releases/tag/v0.2.0
+[0.1.0]: https://github.com/watchlight-ai-beacon/watchlight-enclave/releases/tag/v0.1.0
+[#2–#6]: https://github.com/watchlight-ai-beacon/watchlight-enclave/issues/2
+[#12]: https://github.com/watchlight-ai-beacon/watchlight-enclave/issues/12
+[#13]: https://github.com/watchlight-ai-beacon/watchlight-enclave/issues/13

watchlight_enclave-0.2.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,70 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**conduct@watchlight.ai**. All complaints will be reviewed and investigated
+promptly and fairly. All community leaders are obligated to respect the privacy
+and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+[homepage]: https://www.contributor-covenant.org

watchlight_enclave-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# Contributing
+
+A driver for a new sandbox, a guard for a new enforcement point, or a hole in
+the evidence model — all welcome, and none of them need our permission.
+
+## The one thing to internalise
+
+Everything here serves a single claim:
+
+> **A bundle must never be able to understate what happened.**
+
+A bundle that is missing records *while looking complete* is worse than one
+that admits a gap, because a clean bundle gets read as proof of innocence. So
+the codebase is tilted one way throughout: a layer that cannot record stops
+working rather than working quietly, a check that cannot be made says so, and
+where two readings are possible the pessimistic one is recorded.
+
+If a change makes a bundle quieter about its own limits, it is going the wrong
+way even if every test passes. [`docs/design/`](docs/design/README.md) explains
+the rest.
+
+## Getting set up
+
+```bash
+git clone https://github.com/watchlight-ai-beacon/watchlight-enclave
+cd watchlight-enclave
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+
+pytest -q
+cargo test --manifest-path crates/wl-enclave-egress/Cargo.toml --locked
+```
+
+You need a container runtime for the full suite. Docker, Colima and Podman all
+work.
+
+**Run the real thing before you believe the tests:**
+
+```bash
+wl-enclave -C examples/coder run --purpose "checking my change"
+wl-enclave verify examples/coder/runs/<id>/bundle
+```
+
+### A warning about your laptop
+
+Docker Desktop and Colima map file ownership permissively through virtiofs.
+Native Linux does not. A container running as a fixed unprivileged uid cannot
+write a bind-mounted file owned by the host user — which is why the guard once
+died on startup on Linux while passing on macOS every time.
+
+CI runs on Linux. If a change touches mounts, uids or anything the container
+writes back to the host, **let CI see it before you trust it.** That is not CI
+being pedantic; it is the only Linux most of us test on.
+
+## Before you open a PR
+
+```bash
+pytest -q
+cargo fmt --manifest-path crates/wl-enclave-egress/Cargo.toml
+cargo clippy --manifest-path crates/wl-enclave-egress/Cargo.toml --locked --all-targets -- -D warnings
+```
+
+Then make sure your test fails without your fix. Revert the fix, watch it fail,
+put it back. This is the step most worth doing and the easiest to skip — we
+have shipped a test that passed because its probe was aimed at a path that did
+not exist, which is indistinguishable from a test passing because the control
+holds.
+
+## Commits
+
+Conventional subjects — `fix:`, `feat:`, `docs:`, `ci:`, `chore:`, `!` for
+breaking — and every commit signed off under the
+[DCO](https://developercertificate.org/):
+
+```bash
+git commit -s
+```
+
+Commit bodies are for *why*, including what you tried that did not work. The
+diff covers what.
+
+## Review
+
+CI must be green — with one documented exception. The **end to end** job is
+flaky and is not a required check, because it is reporting a real race ([#22]):
+the sandbox is attested after the agent has started, so whether the evidence
+mask can be confirmed from inside depends on whether the agent is still alive
+when we probe. It passes when attestation wins and fails when it loses.
+
+It is excluded rather than masked with `continue-on-error`, because hiding a
+job that reports a real gap is the same mistake as a bundle that looks complete
+while omitting records. **If you see it pass, that is not evidence the race is
+gone** — and if you make it pass reliably, make sure you fixed the ordering
+rather than the assertion.
+
+[#22]: https://github.com/watchlight-ai-beacon/watchlight-enclave/issues/22
+
+Every pull request needs an approving review before it merges, and `main` takes
+no direct pushes. Approvals are dismissed when new commits land, so a review is
+of the code that actually merges rather than of an earlier draft. Maintainers
+can bypass this to land their own work; that is a deliberate exception for a
+small team, not the normal path, and it does not extend to the status checks.
+
+Beyond that, the questions a reviewer will actually ask:
+
+**Does a bundle still state its own limits?** A new field that could be absent,
+a new control that could be unverified, a new way a record could be dropped —
+does `verify` notice, or does it stay quiet?
+
+**Is the `verified_by` level honest?** `requested_not_readback` establishes
+nothing, and that is enforced. If you reach for it, the control is not
+established.
+
+**Could a second implementation satisfy this seam while producing weaker
+evidence, with nothing failing?** The question that matters most for drivers
+and guards, because weaker evidence looks identical to honest evidence in a
+bundle.
+
+**What breaks for someone with a CI gate?** If `verify` got stricter, say so in
+the CHANGELOG, in those words.
+
+## Reporting a weakness in the evidence model
+
+If you can make a bundle understate what happened, that is the most valuable
+bug report this project can receive — and it goes through
+[`SECURITY.md`](SECURITY.md), privately, not into a public issue.
+[Report a vulnerability](https://github.com/watchlight-ai-beacon/watchlight-enclave/security/advisories/new)
+on the Security tab, or mail security@watchlight.ai.
+
+That policy also lists what we already know and are not looking for reports
+about — chiefly that a holder of the signing key can re-seal a truncated chain
+— so you can tell quickly whether you have found something new.
+
+Attestation gaps are fair game too: a control that claims more than it
+established, a readback that reads back the thing we asked for, a probe that
+cannot tell "the control held" from "we could not observe anything".
+
+## Code of conduct
+
+By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
+Concerns go to conduct@watchlight.ai, which is read by people who can act on
+them.