Merge pull request #38 from git-pkgs/update-readme

Update README with threat-model, sinks, and taxonomy documentation

Author: andrew

README.md

@@ -148,6 +148,81 @@ Missing recommended tooling:
 
 Tools built into the language runtime (go test, gofmt, cargo clippy, dart analyze, deno lint, etc.) are detected automatically when the language is present and won't show as missing.
 
+## Threat model
+
+`brief threat-model` unions the threat categories implied by all detected tools. Each tool definition carries taxonomy tags from [oss-taxonomy](https://github.com/ecosyste-ms/oss-taxonomy) that classify what it does (web framework, ORM, template engine, HTTP client, etc). A mapping table in `_threats.toml` resolves those tags to CWE/OWASP threat categories. The output is fully deterministic -- no AI, no heuristics, just lookup.
+
+```
+brief threat-model .
+brief threat-model --json .
+```
+
+A Rails project produces:
+
+```
+Detected: ruby
+Stack:    ActiveRecord, Bundler, GitHub Actions, RSpec, Rails, RuboCop, Ruby
+
+  auth_bypass        Authentication Bypass  [CWE-287 A07:2021]
+                     via Rails
+
+  csrf               Cross-Site Request Forgery  [CWE-352 A01:2021]
+                     via Rails
+
+  mass_assignment    Mass Assignment  [CWE-915 A08:2021]
+                     via ActiveRecord
+
+  sql_injection      SQL Injection  [CWE-89 A03:2021]
+                     via ActiveRecord
+
+  ssti               Server-Side Template Injection  [CWE-1336 A03:2021]
+                     via Rails
+
+  xss                Cross-Site Scripting  [CWE-79 A03:2021]
+                     via Rails
+```
+
+Rails carries `role:framework` + `layer:backend` which fires the backend-framework mapping (XSS, CSRF, SSRF, open redirect, path traversal, auth bypass). It also carries `function:templating` which fires XSS and SSTI, and `function:authentication` which fires auth bypass and session fixation. ActiveRecord carries `function:data-mapping` which fires SQL injection and mass assignment. Tools with no taxonomy contribute nothing, so projects using only linters and formatters get an empty threat list.
+
+Match is conjunctive: a tool must carry all of a mapping's tags to fire it. `role:framework` + `layer:frontend` fires a different (smaller) set than `role:framework` + `layer:backend`, so React and Express don't get the same threats.
+
+## Sinks
+
+A "sink" in security analysis is a function where untrusted data ends up doing something dangerous -- executing a SQL query, rendering HTML, spawning a shell process, opening a file path. `brief sinks` collects these from all detected tools and outputs the combined set relevant to this project's stack, so you know what to grep for without reading every tool's documentation.
+
+```
+brief sinks .
+brief sinks --json .
+```
+
+```
+ActiveRecord:
+  Arel.sql                 sql_injection        CWE-89
+                           Marks string as safe SQL, bypassing protections
+  find_by_sql              sql_injection        CWE-89
+  where                    sql_injection        CWE-89
+                           With string interpolation; safe with hash or parameterized array
+  order                    sql_injection        CWE-89
+                           Column name not parameterizable; allowlist instead
+
+Rails:
+  html_safe                xss                  CWE-79
+                           Marks string as safe, bypassing ActionView output escaping
+  redirect_to              open_redirect        CWE-601
+                           When target is from params
+  render inline:           ssti                 CWE-1336
+                           Renders string as ERB template
+
+Ruby:
+  eval                     code_injection       CWE-95
+  system                   command_injection    CWE-78
+  Marshal.load             deserialization      CWE-502
+```
+
+Language definitions carry stdlib sinks (eval, system, pickle.loads, etc). Frameworks carry their own (html_safe, dangerouslySetInnerHTML, redirect_to). ORMs carry raw query escape hatches (find_by_sql, $queryRawUnsafe, Arel.sql). Notes indicate when only some forms of a method are dangerous.
+
+The sink data covers 17 languages, 28 web frameworks, 17 ORMs, 15 HTTP clients, 13 template engines, 10 auth libraries, and more. The knowledge base carries over 700 sinks total.
+
 ## Enrichment
 
 `brief enrich` runs the same scan, then fetches metadata from external APIs about the project itself: what packages it publishes, their download counts and dependents, runtime end-of-life status, and OpenSSF Scorecard.
@@ -163,7 +238,7 @@ Data sources: [ecosyste.ms](https://ecosyste.ms) for published package metadata,
 <!-- brief:tools:start (generated by: brief list -readme tools) -->
 ## What it detects
 
-54 language ecosystems with 446 tool definitions across 20 categories.
+54 language ecosystems with 516 tool definitions across 20 categories.
 
 **Languages:** Ada, C, C#, C++, COBOL, Clojure, Common Lisp, Crystal, D, Dart, Deno, Elixir, Elm, Emacs Lisp, Erlang, F#, Fortran, GDScript, Gleam, Go, Groovy, Haskell, Haxe, Java, JavaScript, Julia, Kotlin, Lua, Mojo, Nim, Nix, OCaml, Objective-C, Odin, PHP, Perl, Prolog, Python, R, Racket, Roc, Ruby, Rust, Scala, Scheme, Solidity, Swift, Tcl, TypeScript, V, VHDL, Verilog, Zig.
 
@@ -179,7 +254,7 @@ Data sources: [ecosyste.ms](https://ecosyste.ms) for published package metadata,
 
 **Docs:** Docsify, Docusaurus, Dokka, Doxygen, ExDoc, Hugo, Javadoc, Jekyll, MkDocs, Nextra, Read the Docs, Redoc, Sphinx, Starlight, Storybook, Swagger UI, TypeDoc, VitePress, Yard, cargo doc, dart doc, deno doc, mdBook, phpDocumentor, pkgsite.
 
-**Build:** Actix Web, AdonisJS, Angular, Astro, Autotools, Axum, CMake, Chi, Django, Dune, Echo, Electron, Eleventy, Ember.js, Express, FastAPI, Fastify, Fiber, Flask, Flutter, Foundry, Gatsby, Gin, GoReleaser, Hardhat, Hono, Koa, Laravel, Less, Mage, Make, Meson, NestJS, Next.js, Nuxt, Parcel, Phoenix, PostCSS, Qwik, Rails, Rake, React, React Native, Remix, Rocket, Rollup, Rspack, SWC, Sass, Sinatra, SolidJS, Spring Boot, Svelte, SvelteKit, Symfony, Tailwind CSS, Tauri, UnoCSS, Vite, Vue, Webpack, cross, esbuild, tsup.
+**Build:** Actix Web, AdonisJS, Angular, Astro, Authlib, Autotools, Axum, CMake, CarrierWave, Chi, Devise, Django, Dune, EJS, Echo, Electron, Eleventy, Ember.js, Express, Faraday, FastAPI, Fastify, Fiber, Flask, Flutter, Formidable, Foundry, FreeMarker, Gatsby, Gin, GoReleaser, Gson, Guzzle, HTTParty, Haml, Handlebars, Hardhat, Hono, Invoke, Jackson, Jinja2, Koa, Laravel, Less, Liquid, Mage, Make, Mako, Meson, Multer, Mustache, NestJS, Newtonsoft.Json, Next.js, NextAuth.js, Nokogiri, Nunjucks, Nuxt, OkHttp, OmniAuth, Ox, PHP LDAP, Parcel, Passport, Phoenix, PostCSS, Pug, PyCryptodome, PyJWT, PyYAML, Qwik, Rails, Rake, React, React Native, Remix, RestClient, Resty, Rocket, Rollup, Rspack, SWC, Sass, ShellJS, Shrine, Sinatra, Slim, SnakeYAML, SolidJS, Spring Boot, Svelte, SvelteKit, Symfony, Tailwind CSS, Tauri, Thymeleaf, Twig, UnoCSS, Vite, Vue, Webpack, XStream, aiohttp, axios, bcrypt, bcrypt-ruby, cross, crypto-js, cryptography, defusedxml, esbuild, execa, fast-xml-parser, golang-jwt, got, httpx, js-yaml, jsonwebtoken, ldap3, ldapjs, lxml, net-ldap, node-fetch, python-jose, python-multipart, requests, reqwest, ruamel.yaml, ruby-jwt, sh, tsup, undici, urllib3, xml2js.
 
 **Codegen:** Buf, GraphQL Code Generator, OpenAPI, Protobuf, Thrift, Wire, ent, gRPC, mockgen, sqlc.
 
@@ -230,10 +305,22 @@ alternatives = ["rake spec", "rspec"]
 
 [config]
 files = [".rspec", "spec/spec_helper.rb"]
+
+[taxonomy]
+role = ["testing-framework"]
+function = ["testing"]
+
+[[security.sinks]]
+symbol = "let!"
+threat = "dos"
+cwe = "CWE-400"
+note = "Example only; RSpec doesn't actually have security sinks"
 ```
 
 The `default = true` flag marks a tool as the canonical choice for its category in that ecosystem. The `brief missing` command uses this to suggest the right tool when a category is absent.
 
+Tool definitions can carry two optional sections. `[taxonomy]` classifies what the tool does using terms from [oss-taxonomy](https://github.com/ecosyste-ms/oss-taxonomy): `role` (framework, library, linter), `function` (api-development, templating, data-mapping), `layer` (backend, frontend, data-layer), `domain` (web-development, blockchain). These tags pass through to the JSON output and drive the `threat-model` command. `[[security.sinks]]` lists known dangerous methods with their CWE references, used by the `sinks` command. Both are optional and populated incrementally.
+
 Detection uses five primitives: file/directory presence, dependency names from parsed manifests, file content matching, structured key existence (JSON/TOML), and ecosystem filtering to prevent cross-language false positives.
 
 ## Library usage