PROOFPOINT

Authorized Research Workbench — installation and operating guide

PROOFPOINT is a local-first workbench for planning, controlling, documenting, and reporting authorized web security research. The browser application manages projects, authorization records, policy snapshots, scope, reconnaissance, evidence, verification, reports, and disclosure records. A small command-line agent performs the approved network requests from your computer.

This distribution is intentionally simple:

PROOFPOINT-WEB-AND-CLI/
├── README.md
├── WEB/       Upload these files to your web server
└── AGENT/     Run the local command-line agent from here

There is no npm install, package installation, compilation, server database, or application backend.

Use PROOFPOINT only on assets you own or are explicitly authorized to assess. Authorization, program policy, and confirmed scope remain the operator's responsibility.

Quick start

Extract the downloaded archive.
Upload everything inside WEB/ to the public folder on your web server.
Confirm that the uploaded index.html opens through an ordinary https:// address.
Open a command line in the local AGENT/ folder.

Run:

node run-agent.mjs https://your-server.example/proofpoint/

Replace the example address with the exact address where you uploaded WEB/.
Keep the command-line window open while using PROOFPOINT.
If Chrome asks whether the site may access devices on your local network, choose Allow.

The launcher opens the supplied webpage. The page and agent pair automatically; there is no token to copy.

How the two parts work

Part	Location	Purpose	Stores project data?
Web application	Your static web server	User interface, workflow, records, reports, and local project storage	In the browser on the current device
Command-line agent	Your computer	Enforces scope and sends approved read-only requests	Only bounded activity records and in-memory session state

The files uploaded to your server are static Hypertext Markup Language (HTML), Cascading Style Sheets (CSS), JavaScript, icons, and Progressive Web Application assets. Your web server does not need Node.js, PHP: Hypertext Preprocessor (PHP), Python, a database, or write access.

The agent listens only on the loopback interface at 127.0.0.1:3217. It is not exposed to other computers on your network. Each time it starts, it creates a new ephemeral session token and permits browser requests only from the web origin supplied on the command line.

Requirements

Web server

Any ordinary static web host or web server
Hypertext Transfer Protocol Secure (HTTPS) is strongly recommended
Correct JavaScript Multipurpose Internet Mail Extensions (MIME) type (text/javascript or application/javascript)
The ability to upload directories without flattening the assets/ folder

Apache, Nginx, Caddy, Cloudflare Pages, GitHub Pages, shared hosting, and similar static hosts are suitable.

Local computer

Node.js 22.13 or newer
Chrome or another modern Chromium-based browser is recommended
Permission to bind a local process to 127.0.0.1:3217
Network access from the computer to the authorized research target

Check Node.js before continuing:

node --version

If the command is missing or reports a version below 22.13, install the current Long-Term Support release from nodejs.org.

Install the web application

1. Choose the public address

PROOFPOINT can be installed at a domain root, subdomain, or subfolder. Examples:

https://proofpoint.example.com/
https://example.com/proofpoint/
https://tools.example.com/security/proofpoint/

Use the final public address when starting the command-line agent.

2. Upload the files

Upload the contents of WEB/, preserving the directory structure:

index.html
assets/
manifest.webmanifest
sw.js
favicon.svg
og.png
.htaccess
_headers

If PROOFPOINT should open at https://example.com/proofpoint/, upload the contents into the server directory mapped to /proofpoint/.

Do not rename the generated files inside assets/. The exact filenames are referenced by index.html.

3. Notes for common servers

Apache or shared hosting

The included .htaccess sets the directory index, JavaScript MIME type, security headers, and cache behavior. Make sure your upload tool includes hidden files so .htaccess is not omitted.

If the server rejects .htaccess, remove only that file and configure the equivalent settings in the host's control panel.

Nginx

No rewrite or application proxy is required. Serve the folder as static files. A minimal location resembles:

location /proofpoint/ {
    alias /var/www/proofpoint/;
    index index.html;
    try_files $uri $uri/ =404;
}

Ensure the server's standard MIME types file is loaded so .js files are returned as JavaScript.

Cloudflare Pages, Netlify, and similar hosts

Upload or publish WEB/ as the site's static output directory. The included _headers file is available for hosts that support that convention.

4. Verify the upload

Open the public address directly in the browser. Verify that:

the dark PROOFPOINT interface appears with normal styling;
the navigation buttons work;
the footer shows PROOFPOINT v1.0.0-rc.1;
the browser address starts with http:// or preferably https://, not file://.

At this point, seeing Agent not connected is normal. Start the command-line agent next.

Run the command-line agent

The full public web address is the only required argument.

macOS

cd /path/to/PROOFPOINT-WEB-AND-CLI/AGENT
node run-agent.mjs https://your-server.example/proofpoint/

You can also double-click START-AGENT.command, enter the public address when prompted, and press Return.

If macOS does not permit the convenience launcher to run, use the node run-agent.mjs ... command above. The launcher does not require administrator privileges.

Windows

In PowerShell or Command Prompt:

cd C:\path\to\PROOFPOINT-WEB-AND-CLI\AGENT
node run-agent.mjs https://your-server.example/proofpoint/

You can also double-click START-AGENT-WINDOWS.cmd and enter the public address when prompted.

Linux

cd /path/to/PROOFPOINT-WEB-AND-CLI/AGENT
node run-agent.mjs https://your-server.example/proofpoint/

Or use:

./start-agent.sh https://your-server.example/proofpoint/

Expected command-line output

Successful startup includes:

PROOFPOINT local agent 1.0.0-rc.1 listening on http://127.0.0.1:3217
PROOFPOINT AGENT IS READY
The webpage will pair automatically. Keep this window open.

Leave this command-line window open. Press Control+C in that window when you are finished.

First launch

When the agent starts, it opens the supplied web address in your default browser. The webpage checks the local agent and synchronizes the current authorization, scope, and request limits.

Chrome may display a local-network-access permission prompt. Choose Allow. This permission allows the hosted page to communicate with the agent running on the same computer; it does not expose the agent to the public network.

Successful pairing is visible in three places:

the top status bar says Agent ready;
the sidebar footer shows the connected agent state;
Settings → Local research agent shows the version and instance information.

If the page was already open before the agent started, wait a moment. If it remains offline, open Settings and select Reconnect to command-line agent.

Set up a real project

PROOFPOINT deliberately separates authorization, policy, scope, active mode, and execution. A connected agent alone does not authorize a request.

1. Set the starting address

On Dashboard, enter the exact starting Uniform Resource Locator (URL) for the authorized target. Include the protocol and any nonstandard port:

https://app.example.com/
https://app.example.com:8443/

Changing the target can invalidate earlier assumptions. Review authorization and scope after a change.

2. Record authorization

Open Authorization and record the basis for the assessment. Complete the researcher identity or callsign and acknowledge the attestation.

For a public vulnerability disclosure or bug-bounty program, PROOFPOINT requires the current program interpretation before activating program-based authorization. For an owned asset or separately documented authorization, record the applicable basis and preserve the supporting documentation outside public exports.

3. Review the program policy

Open Program. You can:

run passive discovery for standard public policy locations;
paste or import policy text;
review parsed in-scope and out-of-scope signals;
review allowed and prohibited testing;
confirm the interpreted policy snapshot.

Policy parsing is an aid, not an authorization decision. A researcher must review and confirm the result.

4. Build and confirm scope

Open Scope and add explicit inclusion rules for the target. Exclusion rules always win. Rules can constrain protocol, port, method, exact host, wildcard host, or URL prefix.

After reviewing the rules, select Confirm scope snapshot. Editing a confirmed rule revokes the confirmation; confirm a new snapshot before active work.

5. Select an active mode

Open Recon and select Safe Active. Passive mode never permits active reconnaissance. Manual Verification is available for later human-controlled work, but Safe Active is the normal reconnaissance mode.

6. Review Recon readiness

The Recon page displays every preflight gate. Resolve all red items. When all gates are green, Run controlled recon becomes available.

Understand the Recon gates

Recon uses one visible readiness model. There is no separate hidden server-side checklist.

Gate	Passing condition	How to resolve it
Authorization	An active authorization basis is acknowledged	Open Authorization and complete the attestation
Scope snapshot	A current confirmed snapshot is selected	Open Scope, review the rules, and confirm the snapshot
Starting URL	The exact URL is allowed by the confirmed rules	Add or correct the matching host, protocol, port, and method rule
Research mode	The mode is not Passive	Select Safe Active on Recon
Execution path	The local agent is connected and ready	Start the command-line agent or reconnect from Settings
Emergency stop	The synchronized stop is released	Select Release stop
Request budget	At least one project request remains	Increase the ceiling in Settings after reviewing the impact

Immediately before Recon starts, the webpage sends the current authorization, scope snapshot, constraints, rate, concurrency, and request ceiling to the agent again. This prevents a stale agent configuration from silently disagreeing with the visible page.

Recon is intentionally bounded:

read-only retrieval;
same-origin crawling;
redirects recorded but not followed automatically;
explicit scope evaluation;
Domain Name System resolution and network-address checks;
rate, concurrency, timeout, page-count, and response-size ceilings;
synchronized emergency stop;
cross-origin discoveries recorded as blocked candidates.

Use the rest of the workflow

Dashboard

Review overall readiness, project metrics, the starting URL, request utilization, recent activity, and the guided workflow.

Authorization

Record the legal or contractual basis, researcher identity, timestamps, relevant program, and local authorization-document fingerprint.

Program

Preserve policy snapshots and structured interpretations. A policy change can revoke authorization or scope confirmation when the earlier decision depended on that policy.

Scope

Maintain the versioned default-deny rulebook. Use the destination evaluator to understand why a URL is allowed or blocked before attempting a request.

Recon

Run a controlled same-origin crawl and create versioned inventory snapshots of assets, endpoints, relationships, and public observations.

Candidates

Review possible findings. Recon and safe modules create observations or candidates—not automatically confirmed vulnerabilities.

Verification

Create a controlled verification plan, repeat scope and policy checks, define expected secure behavior, record reproduction/control/negative attempts, and evaluate severity. State-changing tests remain manual-only.

Evidence

Store local evidence records, create redacted derivatives, review redaction findings, and select only reviewed material for export. Unredacted originals are excluded from normal packages.

Reports

Generate and edit structured reports linked to the candidate, verification plan, scope, policy, and evidence records. Review every claim before marking a report ready.

Submission

Prepare a redacted handoff package, complete the submission checklist, submit through the program's official channel yourself, and record the disclosure event.

Easy and Advanced modes

Easy Mode keeps the core journey visible:

Dashboard → Authorization → Program → Scope → Recon → Candidates → Verification → Evidence → Reports → Submission

Advanced Mode adds asset inventory, safe test modules, detailed activity, extension controls, and deeper configuration. Switching modes does not delete project data.

Data storage, backup, and privacy

Where data is stored

Project records are stored in the browser's Indexed Database on the device and browser profile currently in use. The uploaded web server does not receive or store the project database.

This means:

another browser or computer has a separate project library;
https://example.com/proofpoint/ and http://example.com/proofpoint/ are different browser origins and do not share storage;
clearing cookies and site data can delete local PROOFPOINT projects;
private/incognito sessions are not appropriate for durable project work.

Agent secrets

The agent session token is generated at startup, retained in memory, and not written into project exports. Configured cookies, bearer tokens, or approved headers are held only in separated local storage or agent memory according to the selected workflow. They are not written into ordinary project exports or audit logs.

Back up a project

Before browser maintenance, server migration, or a PROOFPOINT update:

Open Settings.
Use Export encrypted archive for a portable protected backup.
Use a passphrase of at least 10 characters and store it safely.
Optionally export the safe project JavaScript Object Notation (JSON) file for inspection or interchange.
Confirm that the downloaded file exists before clearing any browser data.

Encrypted archives exclude agent tokens and separated identity secrets. Evidence export rules continue to exclude unreviewed or unredacted originals.

Update PROOFPOINT

Keep the WEB/ and AGENT/ folders from the same release together.

Export an encrypted project backup.
Stop the old agent with Control+C.
Replace the files on the web server with the contents of the new WEB/ folder. Preserve the new assets/ filenames exactly.
Replace the local AGENT/ folder with the new one.
Start the new agent using the same public web address.
Reload the webpage.

The web application uses a service worker and immutable generated asset names. If the old interface remains visible, perform a hard reload. Do not clear all site data unless you have first exported a verified project backup, because clearing site data also removes the local Indexed Database.

Troubleshooting

The page is unstyled, blank, or looks like plain text

Check the following:

Upload the entire assets/ directory without flattening or renaming it.
Confirm that index.html and assets/ are at the same relative level.
Open the site through its web address; do not double-click index.html or use a file:// URL.
Confirm that the server returns .js files as JavaScript rather than text/plain or HTML.
Check filename capitalization. Linux servers are case-sensitive.
If the host inserted its own error page for missing assets, correct the upload path rather than adding a Single Page Application rewrite.

The webpage says the agent is offline

Confirm that the command-line window contains PROOFPOINT AGENT IS READY.
Keep that window open.
Confirm that the command used the final public web address.
In Chrome, open the site's permissions and allow local-network access.
Return to Settings and select Reconnect to command-line agent.
Confirm that security software is not blocking Node.js from listening on 127.0.0.1:3217.
Stop any other PROOFPOINT agent before starting a new one.

The agent says `Origin rejected`

Stop the agent with Control+C and restart it using the address currently shown in the browser:

node run-agent.mjs https://actual-server.example/exact/path/

The security boundary uses the address origin: protocol, hostname, and port. For example, http://example.com, https://example.com, and https://tools.example.com are different origins.

Port 3217 is already in use

Only one automatic-pairing agent should run at a time. Stop the earlier terminal process. To identify the listener:

macOS or Linux:

lsof -nP -iTCP:3217 -sTCP:LISTEN

Windows:

netstat -ano | findstr :3217

Do not terminate an unfamiliar process until you have identified it.

All top indicators are green, but Recon is blocked

Open Recon and read the seven-item preflight. The top status bar summarizes authorization, scope, and agent state; Recon additionally evaluates the exact starting URL, research mode, emergency-stop state, and remaining request budget.

Each failed gate has a direct action. The Run button activates only when the same displayed gate model reports complete readiness.

The Starting URL gate is blocked

The target must match a confirmed inclusion rule. Check:

exact hostname;
http versus https;
explicit nonstandard port;
allowed read-only methods;
a more specific exclusion rule;
whether a scope edit revoked confirmation.

After correcting a rule, confirm a new scope snapshot.

The agent is connected, but a request is blocked

Read the returned reason and the agent activity record. Common intentional blocks include:

missing authorization or scope confirmation;
destination outside the confirmed rulebook;
private, loopback, link-local, or metadata-network destination;
disallowed protocol, port, method, or test window;
emergency stop;
request, rate, or concurrency ceiling;
redirect to a different destination;
response larger than the configured safety ceiling.

Do not bypass a block until the authorization and scope record justify the change.

Project data appears to be missing

Confirm that you are using the same:

browser profile;
protocol (https versus http);
hostname or subdomain;
port;
installed path.

Browser storage belongs to the complete origin. If the server address changed, import a previously exported encrypted archive into the new origin.

An update still shows the old interface

Confirm that the new index.html and generated assets were uploaded.
Perform a hard reload.
Close duplicate PROOFPOINT tabs.
Restart the agent from the matching release.

Avoid clearing all site data unless an encrypted backup has been exported, because that action removes locally stored projects.

The convenience launcher does not open

Use the direct command instead:

node run-agent.mjs https://your-server.example/proofpoint/

This is the canonical startup method; the operating-system launchers are only shortcuts.

Security model

PROOFPOINT is designed to fail closed:

the agent binds to loopback only;
the browser origin is explicitly allow-listed at agent startup;
pairing uses a new ephemeral token for each run;
authorization and confirmed scope are synchronized before active work;
exclusions take precedence over inclusions;
automated methods are limited to GET, HEAD, and OPTIONS;
state-changing methods remain manual-only;
private, loopback, link-local, and metadata destinations are blocked in normal operation;
redirects are never followed automatically;
active requests are rate-, concurrency-, timeout-, count-, and size-limited;
emergency stop state is synchronized;
raw secrets and unredacted evidence are excluded from normal logs and exports;
there is no telemetry.

The browser application is not a substitute for written authorization, policy review, legal review, or researcher judgment.

The stripped two-folder package does not include the fictional localhost target from the larger development repository. Use an explicitly authorized real target, and expect private or loopback targets to be blocked by the normal agent safety policy.

Stop or remove PROOFPOINT

Stop the agent

Press Control+C in the agent command-line window. Closing the terminal also stops the local process.

Remove the local agent

Stop the process and delete the local AGENT/ folder. The agent does not install a service or background daemon.

Remove the web application

Delete the uploaded PROOFPOINT files from the web server.

Remove local browser data

After exporting any records you need, use PROOFPOINT's Fresh Start control or remove the site's browser data. This action is destructive and removes locally stored projects, recovery points, and separated local records for that origin.

PROOFPOINT v1.0.0-rc.1
Local-first · No telemetry · Authorized use only

Name		Name	Last commit message	Last commit date
AGENT		AGENT
WEB		WEB
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
README.txt		README.txt

Uh oh!

Latest commit

History

Folders and files

Repository files navigation