dorksmith (PyPI)

Deterministic search-dork generator and OSINT/SOCMINT query engine as a pure-Python package with no dependencies (Python ≥ 3.10). Same engine and catalogs as the Dorksmith web app and the npm package, conformance-tested against the same golden fixtures.

pip install dorksmith

from dorksmith import generate, expand_handle, validate_query, search_url

result = generate("example.com", "domain", "public-documents",
                  options={"fileTypes": ["pdf", "docx"], "excludeTerms": ["jobs"], "maxVariants": 3})
for v in result.variants:
    print(f"{v.label:<14} {v.query}")
# Balanced       site:example.com (filetype:pdf OR filetype:docx) -jobs
# Precise        site:example.com filetype:pdf -jobs
# Title-focused  site:example.com (filetype:pdf OR filetype:docx) (intitle:report OR intitle:policy OR intitle:presentation OR intitle:"annual report") -jobs

search_url(result.variants[0].query)
# 'https://www.google.com/search?q=site%3Aexample.com%20%28filetype%3Apdf%20OR%20filetype%3Adocx%29%20-jobs'

handle = expand_handle("@alice42", categories=["developer"], max_platforms=3)
handle.profiles[0].url, handle.profiles[0].status
# ('https://github.com/alice42', 'not-checked')

validate_query("cache:example.com site:example.com or filetype:.pdf").warnings
# ["Lower-case 'or' is treated as an ordinary word; ...", "filetype: values take no leading dot ...", "cache: is deprecated: ..."]

Results are dataclasses; .to_dict() gives the same camelCase shape the npm package and the web app use.

API

options keys match the npm package: fileTypes, excludeTerms, after, before, site, maxVariants, organization, location, role, displayName.

Bring your own catalogs

from dorksmith import load_catalogs, validate_catalogs, generate
catalogs = load_catalogs("path/to/data")      # operators.google.json, intents.json, platforms.json, filetypes.json
assert validate_catalogs(catalogs) == []
generate("x", "keyword", "general-discovery", catalogs=catalogs)

CLI

dorksmith generate example.com --intent exposed-config-files --max 3
dorksmith generate "Alice Smith" --intent person-organization --organization "Example Corp"
dorksmith handle alice42 --categories developer --json
dorksmith validate 'cache:example.com site:example.com'
dorksmith intents

Exit codes: 0 ok, 2 invalid input (or a query with syntax errors for validate), 3 valid request that cannot be generated.

Development

python -m pip install -e ".[test]"
python scripts/sync_catalogs.py      # copies ../../data/*.json into src/dorksmith/data
python -m pytest -q                  # unit tests + the 153 golden fixtures from the monorepo
python -m build                      # sdist + wheel

Publishing is done by the py-package GitHub workflow when a py-v* tag is pushed, using PyPI trusted publishing (see the repository README).