Security model

What Pitwall protects, how, and what it does not protect yet.

Where each credential lives

Credential	Lives
Claude tokens	On the runner that uses them, readable by its user only. The server stores no Claude token
Git credentials that push	On the runner: its owner’s own. The GitHub App never pushes
The GitHub App’s private key	In the server’s environment
The Telegram bot token	In the server’s environment
Passwords	Hashed with argon2id
Session, invitation and reset tokens	256 random bits, given to you once; the server stores only their SHA-256
A runner’s credential	The same: 256 bits, shown once, stored as a hash. Revoking the runner deletes it

Agents

• An agent runs as the runner’s user, in the checkout of the ticket’s repository.
• It never loads the runner owner’s personal Claude configuration. It runs with its own Claude configuration directory, and instruction files above the checkout are excluded. Only the repository’s CLAUDE.md, the library definition and the library skills it names shape it.
• Review steps and chats are read-only: they get no Write or Edit tools.
• No merge without a person. The server merges only a pull request someone approved.

An agent’s tools are not confined to its checkout

An agent can read any file the runner’s user can, and a step that may write can change files outside its checkout. Run each runner as a dedicated user that holds nothing but what the agents need: its Claude tokens, git credentials for the projects’ repositories, and its workspace.

The network

• The runner opens every connection. The server never connects to a runner, so a runner needs no inbound port and no VPN.
• The server’s outbound calls are to GitHub and, with notifications on, to Telegram. Runners call Claude, and GitHub to clone and push.
• There is no telemetry. Nothing reports to anyone else.
• Every outbound call has a timeout.

Sign-in and the browser

Protection	How
Session cookie	HttpOnly, SameSite=Lax; Secure over HTTPS, or always with PITWALL_COOKIE_SECURE=true
Cross-site requests	Any request that changes something must carry an Origin naming the same host, or it is refused
Guessing passwords	5 failures per email or 20 per address within 15 minutes, then refused for a while. An unknown email answers like a wrong password
Forwarded headers	Believed only from the proxies listed in PITWALL_TRUSTED_PROXIES (Behind a reverse proxy)
Reset links	Printed by core user reset, never logged

Reporting a vulnerability

Not set up yet: there is no public repository to report it to. This section will say how once there is.