nymric 0.1.0__tar.gz

nymric-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

nymric-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev,avatars]"
+      - run: ruff check .
+      - run: mypy nymric
+      - run: pytest -q --cov-fail-under=80

nymric-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1

nymric-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+*.md.out
+mosaic-*.md
+
+# secrets / local only
+.env
+.env.*
+*.pem
+*.key
+*.p12
+secrets/

nymric-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: detect-private-key
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20
+    hooks:
+      - id: ruff

nymric-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# changelog
+
+## 0.1.0
+
+first cut. async existence checks across 21 hand-verified sites, bio-link following to
+find associated accounts, optional avatar perceptual-hash matching, an email seed that
+pivots through gravatar's public profile, and the correlation mosaic (confirmed, likely,
+possible) with terminal, json, markdown and svg output.

nymric-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# contributing
+
+prs welcome. keep them small. the whole point is that the tool stays readable in one
+sitting.
+
+## adding a site
+
+sites are data, not code. drop an object into [nymric/data/sites.json](nymric/data/sites.json):
+
+```json
+{"name": "example", "url": "https://example.com/{}", "method": "status", "links": true}
+```
+
+`method: status` is judged on 200 vs 404. `method: text` needs a `found` marker (a string
+only real profiles contain) or an `absent` marker (the not-found string, for sites that
+200 either way). a `{}` in a marker gets the handle. set `links: true` if the profile is
+worth scraping for outbound handles.
+
+rules for a new site:
+
+- public data only. no logins, no auth, nothing meant to be private.
+- respect the site's tos and rate limits. conservative by default.
+- prefer a clean 200/404 split. only reach for a text marker when you have to, and say why.
+- 403, 429 and 5xx are inconclusive, never "missing".
+- check it by hand before you open the pr: one real account, one random string, and paste
+  what you saw.
+
+## what won't get merged
+
+anything that turns this into a target-package generator. block or anti-bot evasion,
+private-data access, scraping behind auth, or bulk "find everyone" features. see
+[ETHICS.md](ETHICS.md), it isn't decoration.
+
+## dev
+
+```
+pip install -e ".[dev,avatars]"
+pre-commit install
+ruff check .
+mypy nymric
+pytest
+```

nymric-0.1.0/DESIGN.md

@@ -0,0 +1,83 @@
+# design notes
+
+how nymric works, and why it's built this way. the decisions matter more than the code,
+so they're written down.
+
+## the pipeline
+
+```
+seed -> probe every site -> pull bio links -> stitch the mosaic -> show it
+                                  ^
+                email seed -> gravatar (resolves to a username first)
+```
+
+one small file per step. `probe` (does the handle exist?), `links` (what other handles
+does the profile point at?), `faces` (do the avatars match?), `stitch` (put it together
+with a confidence), `show` (render), `mailto` (email to gravatar to username). sites live
+as data in `sites.json`, so coverage is a config change, never a code change.
+
+## detecting existence
+
+two methods, both unauthenticated.
+
+status sites are judged on 200 vs 404, which is clean when a site bothers to 404. text
+sites return 200 for everything, so we match a marker instead: `found` is a string only
+real profiles contain (hacker news has `karma:`), and `absent` is the not-found string, so
+the profile exists when that string is missing (steam's "could not be found").
+
+the rule that matters: 403, 429 and 5xx are inconclusive, never "missing". an anti-bot
+block is not evidence the account is absent. this is the single biggest source of junk in
+existence tools that don't draw the distinction, and it's why reddit got cut. its edge
+returns byte-identical 403s for real and fake users when you aren't logged in, so there is
+no honest way to check it unauthenticated.
+
+## three ways it correlates
+
+existence is the boring part. the point is deciding which accounts are the same person.
+
+bio links come first. fetch a found profile, pull the outbound handles it advertises, and
+if two accounts point at each other (or both at a third we already found) that's a link.
+the extractor is strict on purpose: it drops same-platform self links, reserved and brand
+words, asset files, and anything that isn't a bare profile path, because a github page
+linking to `github.com/features` is chrome, not a person.
+
+avatars come second. perceptual-hash (a 64-bit dhash) each profile picture and compare
+across platforms. a near-identical match (hamming distance 6 or less) is a same-person
+signal even when no bio connects them. comparing only across different sites, plus a tight
+threshold, plus dropping near-flat images, keeps a platform's default avatar from forging a
+match.
+
+email is the third door in. an email seed is md5-hashed and looked up against gravatar's
+public profile json, and its `preferredUsername` becomes the handle everything else runs
+on. gravatar, not holehe-style password-reset probing, because reset-abuse would
+contradict the project's own ethics.
+
+## confidence
+
+confirmed means a bio cross-link or an avatar match ties it to another found account.
+likely means an associated account two or more bios point at. possible means it exists but
+nothing corroborates it, and it's called out as a maybe-namesake rather than sold as a sure
+thing, because usernames aren't unique.
+
+every edge carries the reason it exists ("cross-linked from devto, keybase", "same avatar
+as mastodon"), so the score is auditable instead of a black box. no ai in the core path.
+
+## why curated, not 3000 sites
+
+big lists rot. they quietly pile up broken detectors and false positives. the 21 sites
+here were each probed with a real handle and a fake one before shipping, and the ones that
+couldn't cleanly tell the two apart were cut. quality over coverage is the feature, and the
+data-driven design means the list can grow the same careful way.
+
+## concurrency
+
+one shared httpx client, a bounded semaphore (default 10) so it stays polite, and honest
+handling of redirects and timeouts. avatar fetches ride the same client. it's fast because
+it queries a curated set, not because it hammers anyone.
+
+## limits and what's next
+
+markers break when a site redesigns, but they're data so the fix is one line. avatar
+matching needs the optional pillow extra and falls back to bio-links-only without it. next
+on the list: per-detector freshness hints, an avatar cache, a graphviz export of the
+mosaic, and a config file for custom site sets.

nymric-0.1.0/ETHICS.md

@@ -0,0 +1,32 @@
+# ethics and scope
+
+nymric builds a map of someone's public footprint. that's genuinely useful for checking
+your own exposure, brand and impersonation monitoring, or authorized research. it's also
+the exact shape of thing that helps a stalker. so, a few ground rules, and they're not
+decoration.
+
+public data only. it reads pages and public apis anyone can open in a browser. no logins,
+no auth, nothing behind an access control, no password-reset probing. if a site needs you
+signed in to see something, nymric doesn't touch it. email seeds go through gravatar's
+public profile api and nothing else.
+
+a match is a lead, not a verdict. the same handle on two sites is not proof of the same
+human. results carry a confidence and a reason on purpose. don't publish or act on a "same
+person" guess you haven't verified, because being wrong hurts an innocent bystander.
+
+be polite. concurrency is low by default, and 403 / 429 / 5xx are treated as inconclusive,
+never as "this account doesn't exist". don't crank the knobs to hammer a service. slow is
+sustainable.
+
+no harassment, stalking, doxxing, or intimidation. don't run this on a private person
+without a lawful, consented, or authorized basis, and don't use it to build a target
+package for someone else to do the same.
+
+keep little. it stores nothing by default. if you export a report, treat it as sensitive
+personal data. encrypt it, scope who can read it, delete it when you're done.
+
+the law still applies to public data. gdpr, ccpa, and computer-misuse, anti-stalking, and
+harassment statutes don't stop mattering just because the data was public. when in doubt,
+get authorization in writing or don't run the query.
+
+provided for lawful research only, with no warranty. you're responsible for how you use it.

nymric-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 m1h
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nymric-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: nymric
+Version: 0.1.0
+Summary: trace a username or email across public sites and correlate the accounts
+Project-URL: Homepage, https://github.com/m1h/nymric
+Project-URL: Issues, https://github.com/m1h/nymric/issues
+Author: m1h
+License-Expression: MIT
+License-File: LICENSE
+Keywords: correlation,footprint,osint,recon,username
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13
+Provides-Extra: avatars
+Requires-Dist: pillow>=10; extra == 'avatars'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pillow>=10; extra == 'dev'
+Requires-Dist: pre-commit>=3; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nymric
+
+![ci](https://github.com/m1h/nymric/actions/workflows/ci.yml/badge.svg)
+![python](https://img.shields.io/badge/python-3.11%2B-blue)
+![license](https://img.shields.io/badge/license-MIT-green)
+
+check a username (or an email) across a pile of public sites, follow the links on
+whatever profiles show up, and stitch it all into one picture of a single person with a
+confidence on each piece.
+
+> tiles, not a photograph. a match is a lead, not proof.
+
+![demo](docs/demo.svg)
+
+## the idea
+
+most tools here (sherlock, whatsmyname, enola) answer one question: does this handle
+exist on N sites. useful, but you get a flat wall of hits and you're the one left working
+out which are the same person and which are some stranger with the same name. nymric
+spends its effort on that second part.
+
+## what it does
+
+- checks a username across a curated set of sites, all at once
+- reads the outbound links on the profiles that expose them and pulls the person's other
+  accounts out of the bio (their twitter, twitch, a linked github, whatever)
+- ties it together. if dev.to and keybase both point at a github we found, that github is
+  `confirmed`. a lone hit with nothing backing it is `possible` (might be a stranger),
+  not dressed up as a sure thing
+- matches profile pictures too. two accounts with the same photo (perceptual hash, run on
+  your machine) is a `confirmed` link even when no bio connects them
+- takes an email as well. it hashes the email, finds the public gravatar profile, and
+  pivots on the username that comes back. no password-reset probing, just what gravatar
+  already hands out
+- prints a short mosaic, or `--json` / `--md` / `--svg` if you want it elsewhere
+
+## what it's for, and what it won't do
+
+it's for checking your own exposure, brand and impersonation monitoring, and authorized
+research. it won't do logins, auth, anything behind a wall, bulk "find everyone", or
+dodging anti-bot. public data only. the [ethics](ETHICS.md) file is short and it's the
+actual point.
+
+## install
+
+the easy way (once it's on pypi):
+
+```
+pipx install nymric
+```
+
+or from source:
+
+```
+git clone https://github.com/m1h/nymric
+cd nymric
+pip install .
+```
+
+python 3.11+, two deps (httpx, rich). want avatar matching too? `pip install "nymric[avatars]"`
+pulls in pillow. everything else runs without it.
+
+## quickstart
+
+point it at a handle:
+
+```
+nymric torvalds
+```
+
+you get back the accounts that handle shows up on, grouped by how sure it is they're the
+same person, each with the reason why. add `--json` or `--md report.md` to save it. the
+picture at the top of this readme is a real run.
+
+## usage
+
+```
+nymric <username|email> [options]
+
+  -s, --sites NAME...   only these sites (e.g. -s github lichess)
+  -c, --concurrency N   parallel requests (default 10)
+  -t, --timeout SECS    per-request timeout (default 10)
+      --no-follow       don't follow bio links, existence only
+      --no-avatars      don't hash profile pictures
+      --ua STRING       user-agent override
+      --json            json to stdout
+      --md FILE          also write a markdown report
+      --svg FILE         also save an svg screenshot
+  -V, --version
+```
+
+give it an email instead and it goes through gravatar first:
+
+```
+nymric someone@example.com
+```
+
+## how it compares
+
+| tool | what you get back |
+|---|---|
+| sherlock / enola | whether the handle exists on ~400 sites (flat list, verify it yourself) |
+| whatsmyname | a curated existence dataset and a browser app |
+| maigret | existence plus a recursive search of the same handle, big dump |
+| nymric | follows bio links to the person's other accounts and ties them into one mosaic, each piece with a confidence and the reason it's there |
+
+## how it works
+
+every site is a row of data, not code, in [nymric/data/sites.json](nymric/data/sites.json):
+
+```json
+{"name": "github", "url": "https://github.com/{}", "method": "status", "links": true}
+```
+
+`status` sites are judged on 200 vs 404. `text` sites carry a `found` marker (a string
+only real profiles contain) or an `absent` marker (the "not found" string, for sites like
+steam that return 200 either way). a `{}` in a marker gets the handle.
+
+the rule that matters most: 403 / 429 / 5xx never count as "missing", they count as
+inconclusive. a bot-block is not proof the account isn't there. that is the biggest source
+of junk results in tools that skip it, and it's why reddit isn't on the list (its edge
+serves identical 403s for real and fake users when you aren't logged in).
+
+adding a site is a json edit. the rest is a handful of small files: `probe`, `links`,
+`stitch`, `faces`, `mailto`. there's a longer writeup in [DESIGN.md](DESIGN.md).
+
+## honest about the limits
+
+- usernames aren't unique. a `possible` hit really might be someone else. that's why it's
+  flagged instead of hidden.
+- the list is small on purpose (21 sites). big lists rot. these are ones that behave
+  without an anti-bot wall. reddit, instagram, tiktok, x need auth or block you, so they're
+  left out instead of faked.
+- markers break when a site redesigns. it's data, so the fix is one line.
+
+## prior art
+
+built on the shoulders of [sherlock](https://github.com/sherlock-project/sherlock),
+[maigret](https://github.com/soxoj/maigret), and the
+[whatsmyname](https://github.com/WebBreacher/WhatsMyName) dataset. the angle here is the
+correlation layer they leave to you.
+
+## license
+
+MIT. lawful research only, no warranty.

nymric-0.1.0/README.md

@@ -0,0 +1,145 @@
+# nymric
+
+![ci](https://github.com/m1h/nymric/actions/workflows/ci.yml/badge.svg)
+![python](https://img.shields.io/badge/python-3.11%2B-blue)
+![license](https://img.shields.io/badge/license-MIT-green)
+
+check a username (or an email) across a pile of public sites, follow the links on
+whatever profiles show up, and stitch it all into one picture of a single person with a
+confidence on each piece.
+
+> tiles, not a photograph. a match is a lead, not proof.
+
+![demo](docs/demo.svg)
+
+## the idea
+
+most tools here (sherlock, whatsmyname, enola) answer one question: does this handle
+exist on N sites. useful, but you get a flat wall of hits and you're the one left working
+out which are the same person and which are some stranger with the same name. nymric
+spends its effort on that second part.
+
+## what it does
+
+- checks a username across a curated set of sites, all at once
+- reads the outbound links on the profiles that expose them and pulls the person's other
+  accounts out of the bio (their twitter, twitch, a linked github, whatever)
+- ties it together. if dev.to and keybase both point at a github we found, that github is
+  `confirmed`. a lone hit with nothing backing it is `possible` (might be a stranger),
+  not dressed up as a sure thing
+- matches profile pictures too. two accounts with the same photo (perceptual hash, run on
+  your machine) is a `confirmed` link even when no bio connects them
+- takes an email as well. it hashes the email, finds the public gravatar profile, and
+  pivots on the username that comes back. no password-reset probing, just what gravatar
+  already hands out
+- prints a short mosaic, or `--json` / `--md` / `--svg` if you want it elsewhere
+
+## what it's for, and what it won't do
+
+it's for checking your own exposure, brand and impersonation monitoring, and authorized
+research. it won't do logins, auth, anything behind a wall, bulk "find everyone", or
+dodging anti-bot. public data only. the [ethics](ETHICS.md) file is short and it's the
+actual point.
+
+## install
+
+the easy way (once it's on pypi):
+
+```
+pipx install nymric
+```
+
+or from source:
+
+```
+git clone https://github.com/m1h/nymric
+cd nymric
+pip install .
+```
+
+python 3.11+, two deps (httpx, rich). want avatar matching too? `pip install "nymric[avatars]"`
+pulls in pillow. everything else runs without it.
+
+## quickstart
+
+point it at a handle:
+
+```
+nymric torvalds
+```
+
+you get back the accounts that handle shows up on, grouped by how sure it is they're the
+same person, each with the reason why. add `--json` or `--md report.md` to save it. the
+picture at the top of this readme is a real run.
+
+## usage
+
+```
+nymric <username|email> [options]
+
+  -s, --sites NAME...   only these sites (e.g. -s github lichess)
+  -c, --concurrency N   parallel requests (default 10)
+  -t, --timeout SECS    per-request timeout (default 10)
+      --no-follow       don't follow bio links, existence only
+      --no-avatars      don't hash profile pictures
+      --ua STRING       user-agent override
+      --json            json to stdout
+      --md FILE          also write a markdown report
+      --svg FILE         also save an svg screenshot
+  -V, --version
+```
+
+give it an email instead and it goes through gravatar first:
+
+```
+nymric someone@example.com
+```
+
+## how it compares
+
+| tool | what you get back |
+|---|---|
+| sherlock / enola | whether the handle exists on ~400 sites (flat list, verify it yourself) |
+| whatsmyname | a curated existence dataset and a browser app |
+| maigret | existence plus a recursive search of the same handle, big dump |
+| nymric | follows bio links to the person's other accounts and ties them into one mosaic, each piece with a confidence and the reason it's there |
+
+## how it works
+
+every site is a row of data, not code, in [nymric/data/sites.json](nymric/data/sites.json):
+
+```json
+{"name": "github", "url": "https://github.com/{}", "method": "status", "links": true}
+```
+
+`status` sites are judged on 200 vs 404. `text` sites carry a `found` marker (a string
+only real profiles contain) or an `absent` marker (the "not found" string, for sites like
+steam that return 200 either way). a `{}` in a marker gets the handle.
+
+the rule that matters most: 403 / 429 / 5xx never count as "missing", they count as
+inconclusive. a bot-block is not proof the account isn't there. that is the biggest source
+of junk results in tools that skip it, and it's why reddit isn't on the list (its edge
+serves identical 403s for real and fake users when you aren't logged in).
+
+adding a site is a json edit. the rest is a handful of small files: `probe`, `links`,
+`stitch`, `faces`, `mailto`. there's a longer writeup in [DESIGN.md](DESIGN.md).
+
+## honest about the limits
+
+- usernames aren't unique. a `possible` hit really might be someone else. that's why it's
+  flagged instead of hidden.
+- the list is small on purpose (21 sites). big lists rot. these are ones that behave
+  without an anti-bot wall. reddit, instagram, tiktok, x need auth or block you, so they're
+  left out instead of faked.
+- markers break when a site redesigns. it's data, so the fix is one line.
+
+## prior art
+
+built on the shoulders of [sherlock](https://github.com/sherlock-project/sherlock),
+[maigret](https://github.com/soxoj/maigret), and the
+[whatsmyname](https://github.com/WebBreacher/WhatsMyName) dataset. the angle here is the
+correlation layer they leave to you.
+
+## license
+
+MIT. lawful research only, no warranty.

nymric-0.1.0/SECURITY.md

@@ -0,0 +1,21 @@
+# security
+
+## reporting
+
+if you find a security issue in nymric itself (not in a site it queries), please don't
+open a public issue. use github's private "report a vulnerability" flow, and give it a few
+days before disclosing. i'll credit you unless you'd rather stay anonymous.
+
+## in scope
+
+nymric only reads public data. no auth, nothing behind an access control, no
+password-reset probing (see [ETHICS.md](ETHICS.md)). worth flagging:
+
+- an ssrf-style bug where a crafted bio link makes the tool fetch somewhere it shouldn't
+- a site module that reaches a private or authenticated endpoint
+- anything that lets it be pointed at a target harder than the polite defaults allow
+
+## not in scope
+
+- a site changing its markup so a detector goes stale. that's a normal bug, open a pr.
+- a queried site rate-limiting or blocking you. expected, don't work around it.