dsh-web-recon

dsh-web-recon · Web system reconnaissance

English | 中文

A plugin for DeepSeek Harness. Work out how a web system operates — once.

The problem

The usual way an agent automates a web back-office is: screenshot, find the button, click, screenshot again. That approach has three faults:

1. Expensive. A screenshot costs thousands of tokens; a workflow costs dozens of screenshots.
2. Brittle. It keys on coordinates and pixels, so a redesign breaks everything.
3. Nothing is retained. Two hours spent working a system out is spent again in the next session.

Underneath the buttons there is an HTTP API. Underneath the pixels there is an accessibility tree. Both are far cheaper and far more stable.

This plugin turns one reconnaissance pass into a durable playbook for that system — its endpoints, how it authenticates, the controls worth knowing — so later work follows the playbook instead of the screen.

What it produces

One pass over a single-page application, actual output:

6 application endpoints identified; accessibility tree of 896 nodes
API hosts: api.gleif.org, challengemanagement.gleif.org

| Method | Host          | Path                     | Query            | Auth  |
| GET    | api.gleif.org | /api/v1/lei-records      | filter[fulltext] | none  |
| GET    | api.gleif.org | /api/v1/autocompletions  | q, field         | none  |
| GET    | challenge…    | /users/auth              | —                | XSRF  |

No button was clicked, and the system's search API is now known. Note that the UI and the API live on different hosts — the norm for a SPA, and something you can never discover by looking at the screen.

Install

dsh plugin --profile web add github:sherconan/dsh-web-recon

Plain JavaScript, no runtime dependencies, no build step. No Playwright, no downloaded browsers — it speaks the Chrome DevTools Protocol over Node's built-in WebSocket.

Requires Chrome, Chromium or Edge on the machine (or set DSH_WEB_RECON_CHROME to an executable).

Security boundary

This plugin touches signed-in sessions, so the boundary came first:

• A dedicated browser. It runs its own Chrome against its own user-data directory and never drives your everyday browser. The only sessions it can reach are the ones you signed into inside it. Your mail, your bank, your intranet are out of reach because they were never logged into here.
• An origin allow-list. Unauthorised origins are refused, not warned about. Authorisations are timestamped, so the list doubles as an audit trail.
• Credentials are yours to type. Signing in is the only action that opens a visible window, and you sign in yourself. Everything else runs headless. The plugin never types a password and never asks you for one.
• Summaries only. Raw captures and full trees never enter the conversation — returning them would hand back the tokens the plugin exists to save.

Tools

Tool	Purpose
web_site_authorize / web_site_revoke / web_site_list	Manage origin authorisation
web_browser_login	Open a visible window so you can sign in
web_browser_close	Shut the dedicated browser down
web_recon	Reconnoitre a page; build and accumulate its playbook
web_replay	Call an endpoint from the playbook — no screenshots, no clicking
web_playbook_list / web_playbook_get	Read what is already known (check this before reconnoitring again)

Replay: doing the work

With a playbook in hand, web_replay calls the endpoint directly:

• Credentials never pass through this plugin. The request is issued from a page inside the dedicated browser, so cookies, CSRF and CORS are handled exactly as the real application handles them. No credential value is read, stored or printed.
• Credential mode adapts. It tries with the session first; if the endpoint is public (CORS allows any origin, which by rule forbids credentialed requests) it retries once without credentials and tells you which mode succeeded.
• State-changing requests are refused by default. POST/PUT/PATCH/DELETE require the user's explicit agreement and an explicit opt-in flag; the model may not self-confirm.
• Responses are distilled to a status, a shape summary and a bounded excerpt, rather than dumped whole into context.

Where playbooks live

$DSH_HOME/web-recon/playbooks/<site>.json — readable, editable JSON. Repeat passes accumulate endpoints as a union, and anyone who knows the system can correct the file by hand.

Known limits

• Server-rendered pages expose no separate API; there the playbook's value is its control inventory.
• Some endpoints fire only after a specific action. Pass interact with a CSS selector to click once during the pass.
• Playbooks go stale when the target system is redesigned. Re-run reconnaissance; endpoints accumulate rather than replace.
• Playbooks record endpoint shapes, not field semantics. What a parameter means is still for you or the model to work out.
• No multi-step orchestration yet: chaining sign-in → list → process-each is still the model's job.

License

MIT