Skip to content
Back to search

osint-rail

Keyless OSINT: one seed in, a sourced dossier out, every claim with its URL.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shattradingle--osint-rail/badge.svg)](/listings/shattradingle--osint-rail)

HTML

<a href="/listings/shattradingle--osint-rail"><img src="/api/listings/shattradingle--osint-rail/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

$ uvx --from git+https://github.com/shattradingle/osint-rail osint-rail case example.com --depth 0
…
*Generated 2026-11-21T15:10:32Z | 10 requests | 25 sourced claims | 26 rows | 4.1s | stop: complete*

## Coverage

`matched 3 / weak 0 / absent 1 / unknown 1 of 5 checks | 10 requests | 4.1s | 25 claims`

| connector | seed | outcome | reason |
|---|---|---|---|
| otx | domain:example.com | unknown | otx rate-limited (429) |
| hackertarget | domain:example.com | matched |  |
| websearch | domain:example.com | matched |  |
| urlscan | domain:example.com | absent | 0 results |
| domain | domain:example.com | matched |  |
…

Measured 2026-11-21 on a home connection. Your numbers will differ: OTX was rate-limited on this run, and that row is the point.

| You have | Start at | |---|---| | an agent that should do the looking | [MCP](#mcp), two tools and no config | | a terminal | [Install](#install), then [Commands](#commands) | | doubts | [How it works](#how-it-works) and [Limits](#limits), both short |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 284 lines
  1. ![osint-rail: one seed in, a sourced dossier out](docs/banner.svg)
  2. # osint-rail
  3. **Keyless OSINT for people who have to show their work.** It replaces paid people-search
  4. APIs and one-off scrapers: one seed in, a sourced dossier out, and every line carries the
  5. URL it came from, the time it was fetched and the excerpt it was read from.
  6. [Quick start](#quick-start) · [Commands](#commands) · [MCP](#mcp) · [How it works](#how-it-works) · [Limits](#limits) · [Changelog](CHANGELOG.md)
  7. <sub>Part of the keyless stack — public data for agents, with receipts. No API key anywhere.</sub>
  8. [![ci](https://github.com/shattradingle/osint-rail/actions/workflows/ci.yml/badge.svg)](https://github.com/shattradingle/osint-rail/actions/workflows/ci.yml)
  9. [![release](https://img.shields.io/github/v/release/shattradingle/osint-rail)](https://github.com/shattradingle/osint-rail/releases)
  10. [![licence](https://img.shields.io/badge/licence-MIT-2dd4a7)](LICENSE)
  11. [![python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-4cc2ff)](pyproject.toml)
  12. 24 connectors cover usernames, emails, domains, IPs, names and URLs, pivoting breadth-first
  13. from every hit and storing the evidence in a local SQLite ledger. Stdlib only, Python 3.10+,
  14. no account and nothing to configure. When a source blocks the request it is recorded as
  15. UNKNOWN with the reason, never quietly turned into "not found".
  16. ## Quick start
  17. ```console
  18. $ uvx --from git+https://github.com/shattradingle/osint-rail osint-rail case example.com --depth 0
  19. …
  20. *Generated 2026-11-21T15:10:32Z | 10 requests | 25 sourced claims | 26 rows | 4.1s | stop: complete*
  21. ## Coverage
  22. `matched 3 / weak 0 / absent 1 / unknown 1 of 5 checks | 10 requests | 4.1s | 25 claims`
  23. | connector | seed | outcome | reason |
  24. |---|---|---|---|
  25. | otx | domain:example.com | unknown | otx rate-limited (429) |
  26. | hackertarget | domain:example.com | matched | |
  27. | websearch | domain:example.com | matched | |
  28. | urlscan | domain:example.com | absent | 0 results |
  29. | domain | domain:example.com | matched | |
  30. …
  31. ```
  32. Measured 2026-11-21 on a home connection. Your numbers will differ: OTX was
  33. rate-limited on this run, and that row is the point.
  34. | You have | Start at |
  35. |---|---|
  36. | an agent that should do the looking | [MCP](#mcp), two tools and no config |
  37. | a terminal | [Install](#install), then [Commands](#commands) |
  38. | doubts | [How it works](#how-it-works) and [Limits](#limits), both short |
  39. ## What a run actually gives you
  40. Every row in the ledger is one JSON object. This is a real row from an `example.com` run:
  41. ```json
  42. {
  43. "kind": "domain",
  44. "predicate": "rdap_registration",
  45. "value": "1995-08-14T04:00:00Z",
  46. "source": "rdap",
  47. "url": "https://rdap.org/domain/example.com",
  48. "excerpt": "{\"eventAction\": \"registration\", \"eventDate\": \"1995-08-14T04:00:00Z\"}",
  49. "confidence": 0.85,
  50. "fetched_at": "2026-11-21T15:07:22Z",
  51. "sensitivity": "public",
  52. "extra": {}
  53. }
  54. ```
  55. `kind`, `predicate` and `value` are the claim. `url`, `excerpt` and `fetched_at` are why you
  56. are allowed to repeat it. Claims are single-sourced unless two rows agree on the same value;
  57. the dossier says so in its own run notes rather than implying consensus.
  58. ## Comparison
  59. | feature | this | the alternative people use | why it matters |
  60. |---|---|---|---|
  61. | setup | `uvx`, no key, no account | paid people-search API: contract, key, per-lookup billing | a dossier costs time, not money or a ToS negotiation |
  62. | evidence | URL + fetch time + excerpt on every row | API records with no source, scrapers returning dicts | you can defend a line in a report or an email |
  63. | blocked source | `unknown` plus the reason | usually an empty list, indistinguishable from "no account" | silence is not evidence |
  64. | username coverage | a capped, audited sample of merged WhatsMyName + Maigret | Maigret and Sherlock ship the full, maintained site lists | **they are better at breadth**; run them when you want every site, run this when you want a ledger |
  65. | identity | deterministic merges, scored candidates with reasons | opaque confidence scores, or none at all | "same handle" stops being a conclusion |
  66. | agent use | CLI and MCP with one JSON object per run | REST API you have to wrap | the agent gets the evidence, not a summary of it |
  67. ## The rules the code enforces
  68. 1. **Evidence or nothing.** Every claim is built by one helper that requires a source URL,
  69. a fetch time and a non-empty excerpt ([connectors.py](src/osint_rail/connectors.py)), and
  70. the `claims` table has all three as `NOT NULL` ([model.py](src/osint_rail/model.py)).
  71. 2. **Tri-state, not boolean.** Every connector run stores one check: `matched`, `weak`,
  72. `absent` or `unknown` ([engine.py](src/osint_rail/engine.py)). A 403, 429, bot challenge,
  73. timeout or spent budget is `unknown` with the reason attached.
  74. 3. **Same handle is not the same person.** A merge needs a deterministic key: same account,
  75. same profile URL, same email, same IP. Name and bio similarity only produces a scored
  76. candidate link, with its reasons printed ([resolve.py](src/osint_rail/resolve.py)).
  77. 4. **Budgeted, polite, audited.** One HTTP client per case, capped by requests and wall
  78. clock, one request per second per host, and every request written to `requests` with its
  79. status and elapsed time ([net.py](src/osint_rail/net.py)).
  80. 5. **Public only.** No login, no CAPTCHA solving, no proxy rotation, no breach data, no fake
  81. accounts. A block is a stop; retrying 429s is how a research tool becomes a nuisance.
  82. 6. **No model memory.** The optional AI layer is off by default, sees only the claims this
  83. run fetched, and may only echo values that exist in them ([ai.py](src/osint_rail/ai.py)).
  84. ## How it works
  85. ```
  86. seed (username | email | domain | ip | name | url)
  87. │
  88. ├─ planners pick the connectors registered for that seed kind
  89. │ and drop anything above the allowed sensitivity
  90. │
  91. ├─ fan-out, concurrent, 1 request/s/host, one shared budget
  92. │ ├─ github ───── profile, commit emails ─────────┐
  93. │ ├─ gravatar ─── verified accounts ──────────────┤ new seeds, depth + 1
  94. │ ├─ domain ───── A, MX, NS, TXT, SPF, DMARC, RDAP ┤ (each is deduped, so a
  95. │ ├─ websearch ── top 10 mentions ────────────────┘ cycle cannot form)
  96. │ └─ whatsmyname ─ sampled registration probe
  97. │
  98. ├─ one check row per connector run: matched | weak | absent | unknown
  99. ├─ one claim row per finding: url · fetched_at · excerpt · confidence
  100. │
  101. ├─ SQLite (cases, claims, checks, requests, seeds)
  102. └─ markdown dossier + graph JSON + MCP response
  103. ```
  104. [docs/architecture.md](docs/architecture.md) traces the flow through the files, with the
  105. line where each rule is enforced.
  106. ## Install
  107. Python 3.10 or newer. Nothing else. `uvx` and `pipx` routes do not need a checkout:
  108. ```console
  109. # 1. run it once, no install
  110. uvx --from git+https://github.com/shattradingle/osint-rail osint-rail case torvalds --depth 1
  111. # 2. install the command
  112. pipx install git+https://github.com/shattradingle/osint-rail
  113. osint-rail case torvalds --depth 1
  114. # 3. install into the current environment
  115. pip install git+https://github.com/shattradingle/osint-rail
  116. osint-rail case torvalds --depth 1
  117. ```
  118. State lives in `$XDG_STATE_HOME/osint-rail` (usually `~/.local/state/osint-rail`), overridable
  119. with `OSINT_RAIL_HOME`. That directory holds `cases.db` and one `.md`, `.graph.json` and
  120. `.json` per case.
  121. ## Commands
  122. | command | what it does |
  123. |---|---|
  124. | `osint-rail case <seed>` | run a case; `--depth`, `--max-requests`, `--max-seconds`, `--max` |
  125. | `osint-rail probe <connector> <seed>` | run one connector and print its check, for testing |
  126. | `osint-rail show <case_id>` | re-render a stored case without touching the network |
  127. | `osint-rail list` | recent cases; `--limit` |
  128. | `osint-rail delete <case_id>` | remove the case and its claims, checks and requests |
  129. | `osint-rail connectors` | every connector, the seeds it accepts, its state |
  130. | `osint-rail mcp` | serve MCP over stdio |
  131. `--json` on `case`, `show`, `list`, `connectors` and `probe` prints exactly one object.
  132. `--quiet` prints nothing on success. `--no-color` disables ANSI colour (also honours `NO_COLOR`).
  133. Exit codes: `0` ok · `1` nothing found or the run could not complete · `2` every check was
  134. blocked · `64` usage error.
  135. ## MCP
  136. The server speaks line-delimited JSON-RPC 2.0 on stdin/stdout, so it drops into Claude Desktop,
  137. Cursor, DSH or any other stdio MCP client. It exposes three tools:
  138. `osint_case` (run and return the dossier), `osint_show` (re-render a stored case) and
  139. `osint_connectors` (what this install can ask). `osint_case` returns the markdown dossier
  140. plus `structuredContent` with the coverage counts.
  141. ```json
  142. {
  143. "mcpServers": {
  144. "osint-rail": {
  145. "command": "uvx",
  146. "args": ["--from", "git+https://github.com/shattradingle/osint-rail", "osint-rail", "mcp"]
  147. }
  148. }
  149. }
  150. ```
  151. ## Connectors
  152. Generated from `osint-rail connectors --json`; the list is the registry, not a copy.
  153. | connector | seeds | pulls |
  154. |---|---|---|
  155. | `github_commits` | email | GitHub commit search by author email (public commits) |
  156. | `gravatar` | email | Gravatar public profile by email hash |
  157. | `openpgp` | email | keys.openpgp.org key presence by email |
  158. | `chesscom` | username | Chess.com public player profile |
  159. | `codeberg` | username | Codeberg (Gitea) public user profile |
  160. | `github` | username | GitHub public profile + commit author emails |
  161. | `gitlab` | username | GitLab public user profile |
  162. | `hackernews` | username | Hacker News profile (about text, karma, creation date) |
  163. | `mastodon` | username | Mastodon.social account lookup (local instance only) |
  164. | `mojang` | username | Minecraft account UUID (Mojang API) |
  165. | `npm` | username | npm packages maintained by a username |
  166. | `pypi` | username | PyPI user page (published projects) |
  167. | `telegram` | username | Telegram public preview page (t.me) |
  168. | `whatsmyname` | username | Username registration probe over merged WhatsMyName + Maigret lists |
  169. | `bluesky` | handle | Bluesky public profile by handle |
  170. | `companieshouse` | name | UK Companies House officer search (public register) |
  171. | `orcid` | name | ORCID researcher search by name |
  172. | `domain` | domain | DNS records (A/MX/NS/TXT) + RDAP registration |
  173. | `hackertarget` | domain | hackertarget hostsearch: subdomains + IPs |
  174. | `otx` | domain | AlienVault OTX passive DNS (subdomains + IPs) |
  175. | `urlscan` | domain | urlscan.io public search for pages on a domain |
  176. | `websearch` | domain, email, handle, name, username | DuckDuckGo Lite web mentions (top 10, one query) |
  177. | `ip` | ip | ip-api geo/ASN + Shodan InternetDB ports/hostnames |
  178. | `page` | url | Public page extraction (title, description, mailto, tel, social links) |
  179. ## Limits
  180. Measured on 2026-11-21, on the same connection as the demo, and written down because the
  181. next person will hit them too.
  182. - **A quarter of the username sites do not answer.** A 270-site sweep (150 strong + 120 weak,
  183. the `--max` preset) returned `14 matched / 25 weak / 169 no / 62 blocked` for `torvalds`.
  184. 62 blocked is 23%. Blocked sites are `unknown`, so the run never claims they are empty.
  185. - **A "strong" username match is still a lead.** The same 14 sites reported a strong hit for
  186. `TorvaldsDB`, a different handle found through a pivot, and 2 of 35 sites did the same for a
  187. random 15-character string. Some sites return their profile markup for any string. That is
  188. why nothing is merged on a handle alone.
  189. - **GitHub's API refuses unauthenticated traffic from this network.** `github` and
  190. `github_commits` returned `HTTP 403` here. Unauthenticated REST is [60 requests an hour per
  191. IP](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api);
  192. setting `GITHUB_TOKEN` raises the ceiling. Nothing in this tool requires a token.
  193. - **PyPI serves a bot challenge** to the user page, recorded as `unknown`. The `pypi`
  194. connector will tell you it could not check, which is the intended behaviour.
  195. - **OTX rate-limits quietly.** One run in two returned `429`; `urlscan` returned zero pages
  196. for `example.com`. Both are recorded, neither is retried.
  197. - **Web search is one query.** DuckDuckGo Lite, top 10, no pagination, no link following.
  198. Treat mention rows as pointers to open by hand.
  199. - **No phone and no image connector.** There is no lawful keyless path for either that this
  200. repo is willing to ship. They are a documented gap, not a roadmap item.
  201. - **The username sweep downloads two community datasets on first use** (WhatsMyName, Maigret)
  202. and caches them in memory for the process. Offline, it reports `unknown`, not absence.
  203. - **`--max` spends the whole budget.** Depth 3, 480 requests, 150 strong + 120 weak site
  204. checks. Measured on `torvalds`: 28 checks, 480 requests, 21.2 s, 105 sourced claims,
  205. `12 matched / 0 weak / 11 absent / 5 unknown`. Extra checks buy more unknowns and more
  206. leads, not more certainty.
  207. - **The defaults are deliberately small**: depth 2, 120 requests, 180 seconds, 40 strong +
  208. 20 weak site checks. Start there, read the coverage line, then raise it.
  209. - **CI covers Python 3.10 to 3.13 on Linux and 3.12 on macOS and Windows.** The suite opens
  210. no sockets, so it runs the same everywhere.
  211. ## Ethics and scope
  212. Public data only. No login walls, no CAPTCHA solving, no proxy rotation to get around a
  213. block, no breach or stealer data, no fake accounts. A block is recorded as a stop, not
  214. worked around. What this produces is registrations and records with their sources, not a
  215. verdict about a person; deciding who is who is your job, and the dossier shows its working
  216. so someone else can check it.
  217. ## Tests
  218. 98 tests, offline, one seam (a fake transport) for all HTTP:
  219. ```console
  220. $ pytest -q
  221. 98 passed in 3.20s
  222. ```
  223. ## Part of the keyless stack
  224. Public data for agents, with receipts. No API key anywhere:
  225. - **[reddit-rail](https://github.com/shattradingle/reddit-rail)** — Reddit research for your agent: search threads and read whole comment trees.
  226. - **[osint-rail](https://github.com/shattradingle/osint-rail)** — one seed in, a sourced dossier out, every claim with its URL.
  227. - **[receipts](https://github.com/shattradingle/receipts)** — a research desk that only quotes what it fetched.
  228. ## Licence
  229. MIT. See [LICENSE](LICENSE). The username sweep reads community data sets that keep their
  230. own licences; check the [WhatsMyName](https://github.com/WebBreacher/WhatsMyName) and
  231. [Maigret](https://github.com/soxoj/maigret) repos before redistributing either.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.