Plugins¶
Plugins extend AtDork with new commands without touching the core: a
plugin is a single Python file that declares a PLUGIN metadata dictionary
and a run() entry point. Installed through the package manager, every plugin
option surfaces on the main CLI using the mandatory --<plugin>-<option>
flag format, so plugin flags can never collide with core flags or with each
other.
atdork install @plugins/dorkbuilder
atdork --dorkbuilder-text "John wick" \
--dorkbuilder-type social-media \
--dorkbuilder-save dorks.txt
▶ plugin dorkbuilder (~/.atdork/packages/plugins/dorkbuilder/dorkbuilder.py)
10 dork(s) for "John wick" [category: social-media]
• site:linkedin.com/in "John wick"
• site:twitter.com "John wick" OR site:x.com "John wick"
...
✔ saved 10 dorks → dorks.txt
The plugin contract¶
A plugin is a .py file with one top-level PLUGIN literal dictionary and a
run(args, ctx) function:
PLUGIN = {
"name": "dorkbuilder", # becomes the --dorkbuilder trigger
"version": "1.0.0",
"description": "Build ready-to-run dork lists from text + a category",
"options": [
{"name": "text", "help": "Text to hunt for"},
{"name": "type", "choices": ["social-media", "all"],
"default": "social-media"},
{"name": "limit", "type": "int", "default": 0},
{"name": "list-types", "action": "store_true"},
],
}
def run(args, ctx) -> int:
text = args.dorkbuilder_text # dest: <plugin>_<option>
return 0
Mandatory flag format¶
Option names are declared in short form ("text"); the engine always
registers them as --<plugin>-<option> (--dorkbuilder-text). A full flag
whose prefix does not match --<plugin>- is rejected at registration and the
plugin is reported as invalid. Dests are always <plugin>_<option> with dashes
flipped to underscores (func-lain → --dorkbuilder-func-lain →
dorkbuilder_func_lain), so a plugin can never shadow a core flag.
PLUGIN keys¶
| Key | Required | Meaning |
|---|---|---|
name |
yes | Matches ^[a-z][a-z0-9_-]{1,30}$; becomes the trigger flag. |
version |
no | Shown by plugins list / plugins info. |
description |
no | Help text for the trigger flag. |
options |
no | List of option mappings (below). |
Option keys¶
| Key | Meaning |
|---|---|
name |
Short name ([a-z][a-z0-9_-]*), auto-prefixed to --<plugin>-<name>. |
help |
Help text for the flag. |
type |
str (default), int, or float. |
choices |
Non-empty list of allowed string values. |
default |
Default value when the flag is absent. |
action |
"store_true" for a boolean switch (no type/choices). |
How a plugin runs¶
A plugin is triggered by either:
- the bare flag
--<plugin>(store_true), or - implicitly, when any
--<plugin>-*argument appears on the command line.
Configuration defaults alone (plugins.options) never launch a plugin — only
real command-line arguments do. Every triggered plugin runs in order and the
first non-zero exit code wins.
atdork --dorkbuilder-list-types # implicit: one option is enough
atdork --dorkbuilder --dorkbuilder-text "x" # explicit trigger + option
Metadata is read with ast.literal_eval — listing and registering plugins
never executes plugin code. A plugin module is imported and run only when
it is actually triggered.
ctx: what a plugin gets¶
run(args, ctx) receives the parsed namespace plus a PluginContext:
| Attribute / method | Purpose |
|---|---|
ctx.console |
Rich console for output. |
ctx.workspace |
Active environment, or None. |
ctx.package_dir |
Local package store directory. |
ctx.version |
AtDork version string. |
ctx.results_dir |
Environment results directory (or CWD). |
ctx.get_setting(key, default) |
Read a configuration value. |
ctx.guard_write(path) |
Resolve an output path through the environment write guard. |
ctx.search(query, **kwargs) |
Run one dork search through the normal AtDork engine. |
Always write files through ctx.guard_write() — it enforces the active
environment root and rejects paths that escape it.
CLI¶
atdork plugins list¶
Every discovered plugin with its version, status (ready, disabled, or
invalid with the contract error), trigger flag, option count, and path.
atdork plugins info <name>¶
The full contract: version, description, source, path, install ref, status, and a table of every flag with its dest, type, default, and choices.
atdork plugins run <name> [--opt KEY=VALUE]¶
Run a plugin without the flag syntax. Each --opt is coerced using the
option's declared type. Handy for scripting:
Where plugins live¶
Discovery scans (later roots override earlier ones on a name collision):
- the package store
<store>/plugins/— populated byatdork install @plugins/<tool>; - every folder listed in
plugins.pathsin your configuration (handy for local development).
A tool folder (@plugins/<tool>/) may contain helper _*.py files; only files
with a valid PLUGIN literal become commands, and the rest are installed as
supporting modules.
Configuration¶
version: 2
plugins:
enabled: auto # "auto" (all installed) or an explicit allow-list
disabled: [] # plugin names to keep quiet
paths: [] # extra local folders to scan
options: # per-plugin option defaults (CLI still wins)
dorkbuilder:
type: social-media
enabled accepts "auto" (default) or a list of names; disabled always
wins. The section is validated fail-fast on load — unknown keys, wrong types,
and malformed option defaults are rejected before anything runs. API keys and
secrets are never stored in plaintext.
Installing plugins¶
Plugins ship in the Atdork-DB
repository under @plugins/:
atdork search dorkbuilder # find it
atdork install @plugins/dorkbuilder # whole tool folder (plugin + helpers)
atdork install @plugins/dorkbuilder/dorkbuilder.py # a single file
atdork plugins list # verify it's ready
Installing from anywhere¶
Plugins do not have to come from Atdork-DB — a raw module, a git repo or a third-party registry work the same way:
# a single module URL (must end in .py)
atdork install https://raw.githubusercontent.com/user/repo/main/tool/tool.py
# a git repository: one plugin, or pick one with '#<subpath>'
atdork install https://github.com/user/atdork-plugins
atdork install https://github.com/user/atdork-plugins#my-tool
atdork install https://github.com/user/atdork-plugins#tools/my-tool
atdork install https://github.com/user/repo --git-ref v1.2.0 # pin a tag
atdork install "https://github.com/amnottdevv/Atdork-DB#@plugins/dorkbuilder"
# a third-party registry declared once in the config
atdork plugins sources # list them
atdork install --source mine @plugins/my-tool
A registry is any repo that ships an Index.idn plus @plugins/<tool>/…
folders — the same layout as Atdork-DB:
# atdork.yaml (or <env>/.config/config.yml)
plugins:
sources:
mine:
url: https://github.com/user/atdork-plugins
ref: main # optional branch/tag
index: Index.idn # optional custom index path
Generate (or refresh) its index with:
atdork plugins publish @plugins/my-tool # print the lines
atdork plugins publish @plugins/my-tool --repo . --write # update Index.idn
git push # your registry is now installable
Every external install goes through the same contract gate: metadata is read
with AST (never executed), the name must match the plugin contract, files are
size-capped, and registry installs verify every file against the checksum
in that registry's Index.idn — a mismatch (or a missing sha256) aborts the
install. Index entries are validated too: a ref that contains .. or an
absolute path is rejected, and no install can write outside the local store.
Available plugins¶
| Plugin | What it does |
|---|---|
dorkbuilder |
Build ready-to-run dork lists from text + a category |
reportgen |
Summarize result files into an HTML/JSON report |
subdomain |
Discover indexed subdomains of a target via search dorks |
emaildork |
Build (and optionally run) email-discovery dorks |
vulndork |
Vulnerability-hunting dork sets by target / product / CVE |
geodork |
Geographically-scoped dork builder |
usernamehunt |
Find where a username/handle is used across the web |
Each tool ships with its own README.md. Browse them — with rendered
READMEs, options and source links — in the
web catalog's Plugins section.
Security¶
Plugin metadata is parsed with ast.literal_eval — reading PLUGIN never
executes code, so listing or registering plugins is side-effect free. A plugin
module is imported only when one of its flags is actually triggered on the
command line.
Because a triggered plugin is real Python that runs in your interpreter, the
trust model is the package manager: only install plugins from a repository you
trust (atdork install verifies the sha256 of every file against
Index.idn). Treat installing a plugin like installing any other package.
Installing from a URL, a git repo or plugins.sources is TOFU trust: the
checksum comes from that source, so adding a source means trusting everyone
who can push to it. Prefer tags/commit-pinned registries for shared setups, and
review a tool's code (atdork plugins info, the source link in the catalog)
before running it.
Output writing goes through ctx.guard_write(), which enforces the active
environment root — a plugin cannot write outside its workspace through the
guarded path. Invalid plugins (bad metadata, wrong prefix, missing run()) are
rejected at load time and reported by plugins list, never silently ignored.
Disable a plugin without uninstalling it via plugins.disabled in the
configuration.