Skip to content

docs/Add cryptography and key management - #42

Open
felpzw wants to merge 2 commits into
cloudflare:mainfrom
felpzw:add-cryptography-and-key-management
Open

felpzw wants to merge 2 commits into
cloudflare:mainfrom
felpzw:add-cryptography-and-key-management

Conversation

@felpzw

@felpzw felpzw commented Sep 19, 2026

Copy link
Copy Markdown

Summary

Adds a dedicated cryptography and key-management audit companion and integrates it into the existing audit workflow. Reviewers can now select focused cryptographic attack classes, receive inline examples, and track coverage through the current ledger contract.

Closes issue #39.

Changes

  • Add CRYPTOGRAPHY-AND-KEY-MANAGEMENT.md covering:
    • Weak algorithms, insecure randomness, and nonce/IV reuse.
    • Authenticated encryption, key derivation, and purpose separation.
    • JWT algorithm and key selection.
    • Password hashing and migration.
    • TLS and certificate validation.
    • Secret storage, KMS/HSM boundaries, rotation, revocation, and disposal.
  • Include vulnerable and corrected examples alongside each class, with explicit assumptions and validation criteria.
  • Add companion selection guidance to SKILL.md and ATTACK-CLASSES.md.
  • Extend reconnaissance with cryptographic surface mapping and a coverage-unit example using exact Markdown block references.
  • Cross-reference the web and cloud companions while preserving their identity-flow and infrastructure responsibilities.
  • Update the README file inventory.

Validation approach

Findings require a demonstrated trust-boundary violation and a meaningful security consequence. Algorithm names, missing KMS/HSM integration, or configuration preferences alone do not establish a vulnerability. Decisive facts unavailable from source remain needs_validation.

Coverage integration uses the existing contract without changes to the findings schema or either validator.

Testing

  • All 65 existing validator tests pass.
  • Skill metadata validation passes.
  • git diff --check passes.
  • Verified 16 exact Markdown block references and local document links.
  • Verified that all 10 attack classes contain inline vulnerable and corrected examples.
  • Validated a synthetic nonce-reuse coverage unit through planned, in_progress, and candidate states using the existing validator CLI.

The synthetic fixture used dummy data and remained outside the repository. No live services or real secrets were used.

- Cover cryptographic primitives, randomness, nonces, JWT, password
  hashing, TLS validation, and the complete secret and key lifecycle.
- Keep vulnerable and corrected examples beside their attack classes,
  with explicit assumptions and source-grounded validation criteria.
- Distinguish demonstrated boundary violations from hardening advice
  and deployment facts that still need validation.
- List the new companion in the README file inventory.

Refs cloudflare#39
- Route cryptographic boundaries from SKILL.md and ATTACK-CLASSES.md.
- Map cryptographic surfaces during reconnaissance and document exact
  companion references in a coverage-unit example.
- Connect JWT and TLS review with the web companion, and key storage
  and rotation with the cloud companion.
- Preserve the existing findings schema and coverage validators.

Validation:
- All 65 existing validator tests pass.
- Skill metadata validation and git diff --check pass.
- Check 16 exact Markdown block references and local document links.
- Validate a synthetic nonce-reuse unit through planned, in_progress,
  and candidate states using the existing coverage-validator CLI.

Refs cloudflare#39
>
> **Cryptography and key-management targets** (security-sensitive encryption, MACs/signatures, random credentials, nonces/IVs, password verifiers, JWT cryptography, TLS validation, or key storage/rotation/revocation): use [CRYPTOGRAPHY-AND-KEY-MANAGEMENT.md](CRYPTOGRAPHY-AND-KEY-MANAGEMENT.md).
>
> **Client-side and browser targets** (SPAs, browser extensions, embedded webviews, service workers, browser storage, cross-window messaging, CORS, WebSockets, or DOM rendering): use [CLIENT-SIDE.md](CLIENT-SIDE.md).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Client-side.md

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Merge i don't care wasted all my time with a angry wife chasing down to rouge agents in my local for fuck training excise

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants