Audits
Faraday invites audits from experts and AIs. Each one is published here with Faraday's response to every finding, and the full prompt and output.
What an audit includes Submitting What Faraday does Published audits
What an audit includes
By an expert or an AI. This list is not a prompt by itself: write your own prompt for the audit, then add this list at its end.
Faraday's request for this audit. Follow it in the output:
1. Record what was audited: the repository (https://github.com/bitcoinpasada/faraday), the commit (git rev-parse HEAD), the date, any tools run, and for an AI, the model and its version.
2. State the scope: the areas covered, the parts of the code read, and the parts not read. docs/AUDIT.md lists where the cryptography is.
3. For each finding, give: a severity, the file and line, what goes wrong, how to trigger it, and whether it was confirmed by running code or only found by reading.
4. Write the output as Markdown in two files: audit.md for everything except critical and high findings, and private.md for critical and high findings only. Leave out private.md if there are none.
5. End audit.md with a summary of at most 150 words: what was examined, what was found, and an assessment of whether the code can be trusted with keys. If private.md exists, the summary gives its number of findings without describing them.
6. Redact personal information from both files: names, email addresses, usernames, and anything about the computer the audit ran on, including home directory paths, hostnames, IP addresses, the operating system and its version, hardware, and environment variables. Replace each with a placeholder such as <home>, <user> or <host>. Leave unchanged the names and addresses in Faraday's own code.
7. If private.md exists, hash it last, after step 6: run sha256sum private.md > private.md.sha256. If you cannot run commands, do not write a hash; say that it still needs to be made.
Severities:
- Critical: a key, seed or passphrase can be extracted; the device signs, or shows as approved, something the user did not approve; Faraday's output is wrong in a way that loses funds (an address it cannot spend from, a backup or shares that do not restore); or crafted input runs code on Faraday.
- High: the same, but only under specific conditions (physical access, a non-default setting, a rare input); a vault slot opens without its passphrase or reveals how many slots are used; the air gap fails; secrets outlive the session; a tampered image or upgrade is accepted; Faraday Starter writes to the wrong disk; the design makes a mistake that loses funds or exposes a key likely, through a missing warning or confirmation or a misleading label.
- Medium: a protection is weaker than intended but holds (a lower key-stretching cost); a crash from crafted input with no code run; public wallet data leaked.
- Low: a defect with no direct security effect, including a wrong result that Faraday detects and refuses.
- Note: an observation, not a defect.Areas to cover
A starting point for the audit's scope. Add them to the prompt as they are, change them, or write your own.
Areas to cover:
- Key material: whether a key, seed or passphrase can leave the device; the randomness and entropy behind key generation; nonces in ECDSA, Schnorr, MuSig2 and FROST signing.
- Signing: whether what the screen shows (amounts, fee, destinations, change) is what gets signed.
- Correct results: derivations, addresses, mnemonics, SLIP-39 and codex32 shares, backup files (.oskb, KDBX), MuSig2 and FROST, against published vectors and other implementations.
- The vault: each slot's passphrase opens only that slot, the key-stretching cost is the one stated, the file does not reveal how many slots are used, and a damaged file is detected.
- The air gap and what remains: no network interface comes up, secrets are written only where the user chooses, and none outlive the session.
- Untrusted input: PSBTs, QR codes, images and file systems from the online computer.
- The image and its tools: release verification, the Secure Boot keys, the upgrade, Faraday Starter's disk writing and checks, and what Faraday Companion stores.
- Access: the keyboard code and the passphrase prompts.
- Mistakes a person can make: where Faraday, Faraday Starter or Faraday Companion make an easy mistake possible that loses funds, exposes a key or locks a person out of their computer: a misleading label, steps in a confusing order, a risky action with no confirmation, a risky setup with no warning (a TV, a capture card or KVM, a wireless keyboard), a backup that can be skipped or left unchecked, and whether the warnings that exist come at the moment they are needed.- An expert audit has no prompt.md: audit.md describes its method.
- The files carry no names. A name or pseudonym for credit goes in the issue form.
- docs/AUDIT.md lists what Faraday computes, what is written in its own code and what comes from libraries.
Submitting
Through GitHub, not by email. A pseudonymous account is enough.
- Save the promptFor an AI audit, the exact prompt, with the list at its end, as prompt.md.
- Check for personal informationIn every file. A hashed file cannot be corrected afterwards without a new hash.
- Check the hashIf there is a private.md. The first command prints private.md: OK. If the AI could not make private.md.sha256, or private.md changed afterwards, the second makes it.
sha256sum -c private.md.sha256 sha256sum private.md > private.md.sha256 - Open an audit issueWith the audit form. Attach prompt.md and audit.md as files, not pasted text, and give the hash from private.md.sha256 if there is one.
- Send private.md privatelyIf there is one: in a private vulnerability report on the same repository, with the issue's number. The report takes no files: paste the whole of private.md into its Details field, between a line ~~~~~ above it and the same line below it. Only Faraday and you see it until it is published.
- Timestamp the hashOptional. OpenTimestamps anchors it in a Bitcoin block, so its date does not depend on GitHub keeping the issue.
Where each file goes
| prompt.md | The public issue | Everyone |
|---|---|---|
| audit.md | The public issue | Everyone |
| private.md | A private report, pasted | Faraday and the submitter, until published |
| The hash of private.md | The public issue's form | Everyone, from the day it is sent |
- The hash goes in the issue only, never in audit.md. The issue is what dates it.
- When the prompt itself points at a vulnerability, it goes in the private report too, and the issue carries its hash in its place.
- When private.md changes after it was sent, the new file goes in the private report and its new hash on the issue. Both hashes stay there.
What Faraday does
The same timeline is in the repository's SECURITY.md.
Within 15 days
A reply on the issue
The hash quoted back, and a verdict on each finding: confirmed and fixed, with the fixing commit; confirmed and open; could not reproduce; or not a bug.
Within 15 days
A private report with no issue
A reply on it within 15 days of its arrival.
Then
The entry, published
The submitter's summary, unedited, Faraday's response, and the full prompt and output, below.
Once fixed
private.md, published
No later than 90 days after the private report, fixed or not. Anyone can check it against the hash posted on the issue.
Published audits
Newest first. The current release is Faraday 0.1.2.
No audits have been published yet.
An entry records what was submitted and Faraday's verdict on each finding. It is not an endorsement, and it does not prove which model wrote the output. The hash shows that private.md, once published, is the file that was sent on the day of the issue.