1 files changed, 52 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2ead53b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,52 @@
+# brew-sploits
+
+Scan Homebrew for vulnerabilities that already have known exploits.
+
+`brew-sploits` reads the vulnerabilities that `brew vulns --json` reports for
+your installed formulae. For every real CVE identifier, it asks the fprox
+service whether public proof-of-concepts or exploitation activity exist. It
+prints one JSON report to stdout.
+
+## Output
+
+The report has four fields.
+
+- `exploited` lists the CVEs with known exploits.
+- `not_exploited` lists the CVEs with no known exploits.
+- `non_cve` lists the vulnerability IDs that are not CVEs, such as `OSV-*`.
+- `vulnerable_packages` lists the unique Homebrew formulae that the CVEs affect.
+
+For a single CVE, the tool marks it as exploited when either
+`.props.pageProps.cveInfo.proofOfConcepts` or
+`.props.pageProps.cveInfo.exploitedAt` holds at least one entry.
+
+## Requirements
+
+- Go 1.26 or later
+- Homebrew, with `brew` on `PATH`
+- Network access to `fprox.hrbrmstr.app`
+
+## Build
+
+Run `just build`. Or build the binary directly:
+
+```sh
+go build -o brew-sploits ./cmd/brew-sploits
+```
+
+## Usage
+
+Run the binary to scan and print the report. Use `--help` for the option list
+and `--version` for the version.
+
+```sh
+./brew-sploits
+./brew-sploits | jq '.exploited'
+./brew-sploits --help
+```
+
+## Limitations
+
+The tool skips any CVE that the fprox lookup fails to resolve. It writes a
+warning to stderr for each skipped CVE. It never labels a skipped CVE as
+exploited or not exploited.