Operational Troubleshooting Manual¶
Resolution protocols for common failure vectors encountered during large-scale network scanning sweeps.
1. Engine Backend Returning HTTP Code 429 (Rate-Limited)¶
- Symptom: Logs emit repetitive
429 Too Many Requestsnotifications, and result vectors drop to zero. - Mitigation Actions:
- Increase your standard processing delay footprint:
--delay 4. - Inject dynamic spacing algorithms into the engine loop:
--adaptive-delay. - Deploy an expansive distribution pool of network targets:
--proxy-file proxies.txt. - Shift target focus over to alternative data indexing platforms:
--backend startpageor--backend yandex.
- Increase your standard processing delay footprint:
2. Proxies Falling Out of Pool Sync¶
- Symptom: Runtime outputs show extensive proxy failures, or execution hangs inside connection timeouts.
- Mitigation Actions:
- Verify proxy routing string schema declaration definitions. Format must strictly align to:
scheme://user:pass@host:port. - Ensure that you deploy SOCKS5h variants (
socks5h://) when leveraging Tor networks to force DNS lookups down the remote proxy pipeline rather than parsing local leak nodes.
- Verify proxy routing string schema declaration definitions. Format must strictly align to:
3. CSV Output Rendering Corrupt or Displaying Security Warnings¶
- Symptom: Spreadsheet processors (Microsoft Excel, LibreOffice Calc) display warning flags regarding executable expressions or broken formatting blocks upon opening exported maps.
- Mitigation Actions:
- Update to the latest release:
pip install --upgrade atdork(current:1.4.1). - Distribution builds since
1.3.8incorporate a parsing pass (lib/storage.py) that strips or prefixes symbols (+,=,-,@) to block Formula Injection attacks.
- Update to the latest release:
4. "Atdork-DB repository not found"¶
- Symptom:
atdork search,atdork install, or--database-dorkexits withAtdork-DB repository not found. Looked in: ... - Cause: The dork database is a separate checkout that hasn't been cloned (or discovered) yet.
- Mitigation Actions:
- Clone it once:
git clone https://github.com/amnottdevv/Atdork-DB.git ~/Atdork-DB - Or point AtDork at an existing checkout:
--db-repo /path/to/Atdork-DBorexport ATDORK_DB_REPO=/path/to/Atdork-DB. - Docker users: the image bundles the database at
/opt/atdork-db— this error should never occur; if it does, you overrodeATDORK_DB_REPOwith a bad path.
- Clone it once:
5. "No package matches ''" or Ambiguous Shorthand¶
- Symptom:
install/uninstallfails withNo package matches ...(optionally with aDid you mean:line), orAmbiguous shorthand. - Mitigation Actions:
- Find the exact ref:
atdork search <keyword>or browse the web catalog. - Use the canonical form
@folder/file.txtwhen a shorthand prefix matches several folders. - Stale refs after manual DB edits? Rebuild the manifest inside the checkout:
atdork index --build.
- Find the exact ref:
6. Stale Dork Data¶
- Symptom: New folders or files (e.g. fresh GHDB sync) don't show up in
atdork search/atdork index. - Mitigation Actions:
- Refresh the checkout:
atdork update(agit pull --ff-onlyon Atdork-DB). - Verify you're reading the checkout you think: the discovery order is
--db-repo→ATDORK_DB_REPO→ configdb_repo→~/Atdork-DB→ sibling →./Atdork-DB.
- Refresh the checkout:
7. Docker: Installed Packages Don't Persist¶
- Symptom:
atdork install ...succeeds, but the nextdocker runshows an emptyatdork installed. - Cause: The container filesystem is ephemeral — each
docker runstarts fresh. - Mitigation Actions:
- Mount a volume over the store:
-v atdork-store:/home/atdork/.atdork. - Or skip the store entirely and run refs straight from the bundled database:
--database-dork @cve(works withoutinstall).
- Mount a volume over the store:
See Docker for volumes, bind mounts, and compose examples.
8. Environment: "… is not an AtDork environment" or "outside the environment"¶
- Symptom:
--env/ATDORK_ENVfails withmissing .atdork-env, or a path is rejected withresolves to '…' which is outside the environment. - Mitigation Actions:
- Create the workspace first:
atdork env create <path>— an environment is a plain folder with a marker, not any directory. - While an environment is active all writes must stay inside its root; relative paths already resolve against the root (
results/x.json→<root>/results/x.json), so prefer those. - Output still appearing in
./results/? No environment is actually active — verify withatdork env which. - Full guide: Environment.
- Create the workspace first:
9. Workflow: "'' not found" or Validation Errors¶
- Symptom:
atdork workflow run <name>/--run-workflowexits withWorkflow '…' not found, orworkflow validateprints schema errors. - Cause: The definition isn't in the merged sources (config
workflows:+ discovered files), or it violates the schema. - Mitigation Actions:
- List what AtDork actually sees:
atdork workflow list(each entry shows its source — config or file path). - Discovery looks for
workflow.yaml/workflows.yaml(etc.) in the active environment root and the current directory only — not in parent folders.atdork env whichtells you which root is active. - Fix schema errors with
atdork workflow validate— errors are prefixed with the exact path (workflows.<name>.steps[2]: …) and exit non-zero (CI-friendly). {target}errors mean a query uses the token but neither the workflow nor--targetprovides one.- Full reference: Workflows.
- List what AtDork actually sees:
10. Workflow: Step "below_threshold" / "failed" / Resuming¶
- Symptom: A step reports
below_threshold, or the run stops withfailed … (on_error: stop)and remaining steps never ran. - Cause:
below_thresholdsimply means fewer unique results thanwhen_results_belowafter theretry_withqueries merged (often normal for small targets).failedmeans every query of that step errored out (backends exhausted). - Mitigation Actions:
- Preview the exact queries first:
--dry-run(or--workflow-dry-run) — no searches, no credits. - Inspect the step's
retry_withlist — alternate, broader dorks are the intended fix for thin results. - After fixing the definition (or after a rate-limit cooldown), continue where the run stopped:
atdork workflow run <name> --resume— completed steps are skipped under the samerun_id. - Force a single step in isolation:
--step <name>. - State lives in
<env>/state/workflows/<name>.json(or~/.atdork/state/workflows/without an environment) — delete it for a truly fresh start.
- Preview the exact queries first:
11. Plugin: Flag "unrecognized arguments" or Plugin Won't Run¶
- Symptom:
atdork --dorkbuilder-...exits withunrecognized arguments, or a plugin listed byplugins listdoesn't fire. - Cause: The plugin isn't installed in the active package store (each environment has its own store), it's disabled in config, or its
PLUGINmetadata is invalid. - Mitigation Actions:
- List what the current environment actually sees:
atdork plugins list—readymeans the flags are registered. - Install into the active store:
atdork install @plugins/<tool>(useatdork env whichto confirm which store is active). - Check you're using the mandatory format
--<plugin>-<option>— a fully spelled flag with the wrong prefix is rejected at registration. - An
invalidentry prints the exact contract error (badname, wrong option prefix, missingrun()); fix the.pyand reinstall. - Config defaults alone (
plugins.options) never launch a plugin — a real--<plugin>or--<plugin>-*argument is required. - Full reference: Plugins.
- List what the current environment actually sees:
12. Plugin: Installing From a URL, Git Repo or Custom Source Fails¶
- Symptom:
git is required to install from a repository URL …,contains N plugins; pick one with '#<subpath>',checksum mismatch … refusing to install, orunknown plugin source '<name>'. - Cause: Missing git binary, an ambiguous repo layout, a registry whose files drifted from its
Index.idn, or a source that isn't declared in the active config layer. - Mitigation Actions:
- Install git (
apt install git/brew install git) — a single.pyURL needs no git, repository installs do. - Point at one tool inside a multi-plugin repo:
atdork install https://github.com/user/repo#my-tool. - A checksum mismatch means the registry index and its files disagree — re-run
atdork plugins publish @plugins/<tool> --repo . --writein that registry, push it, then retry. - Check what the active layer sees with
atdork plugins sources;--envuses the environment's config (<env>/.config/config.yml), not the working-directory file. - Share a registry safely by pinning it to a tag:
ref: v1.2.0underplugins.sources, or--git-ref v1.2.0for a URL install. - Full reference: Plugins.
- Install git (
13. Plugin: Execution Error or Output Rejected by Environment Guard¶
- Symptom:
Plugin error: …,Plugin '<name>' crashed: …, oroutput escapes the environment root. - Cause: The plugin raised an exception, returned a non-integer, or tried to write a path outside the active environment root.
- Mitigation Actions:
- Run it directly for the full traceback:
atdork plugins run <name> --opt k=v, or add--debug. - A
run()must return anintexit code (Nonecounts as 0) — a string/bool return is a contract violation. - The environment guard forces every write under the root — use
ctx.guard_write()and a relative path (results/report.html), or run without--env. - Silence a misbehaving plugin without uninstalling: add it to
plugins.disabledin config.
- Run it directly for the full traceback:
14. Watch: Nothing New, Wrong Findings, or No Notification¶
- Symptom:
watch runalways reports0 new, every result is reported as new on every run, or the webhook never fires. - Cause: The first run is a baseline by design; a changed dork target re-keys results; and quiet cycles (nothing new) never notify.
- Mitigation Actions:
- The very first
watch run <name>records a baseline and reports nothing as new — that is expected. Run it twice to see the delta. - Every run without new findings stays quiet (no notification). Only the baseline and real findings notify.
- Check what the watch holds:
atdork watch show <name>lists the dorks, stored options, run counter and the last new URLs. - Verify the dorks resolve before spending time/credits:
atdork watch run <name> --dry-run. - A different backend can return a different result set (so URLs may look "new"); pin the search options on
add(--max-results,--region,--backend) so cycles are comparable. - Reset the history by deleting
<env>/state/watch/<name>.json(orwatch remove+watch add) — the next run becomes a fresh baseline. - Confirm the watch state file is the one you think it is: environments keep their own (
atdork --env <path> watch list). - Full guide: Watch Mode.
- The very first