# Manage Subscription (/billing/manage-subscription) Owners and billing members manage billing under **Settings → Billing**. ## What you can do yourself [#what-you-can-do-yourself] * **Buy Pro.** Choose Pro and check out with Stripe. * **Open the billing portal** (powered by Stripe) to update your payment method and billing details, see invoices, and cancel. Cancelling takes effect at the end of the billing period. * **Buy a credit pack** (Pro and Team), a one-off purchase of 10 scan credits. Pack credits are used after your monthly allowance. ## Moving between Pro and Team [#moving-between-pro-and-team] The billing portal cannot change plans or seats. To move between Pro and Team, or change the number of Team seats, [contact us](/support/contact). We change the subscription for you. ## If a payment fails [#if-a-payment-fails] When a payment is overdue, your paid limits hold for 7 days. After that, your organization has Free limits until you pay. Your data is kept. Credit packs cannot be bought while a payment is overdue. ## After cancelling [#after-cancelling] When the subscription ends, the organization is on the Free plan. You keep access to your findings and reports. ## Invoices [#invoices] Invoices are in the Stripe billing portal. A Launch Pentest paid by payment link is not in that list. Its receipt is under **Purchases** on the Billing page. # Plans & Pricing (/billing/plans) Prices are shown as they stand today and can change before sign-up opens to everyone. The prices on your Billing page are the ones that apply to you. | | Free | Pro | Team | Enterprise | | ------------------------- | -------------- | ---------------------------------- | --------------------------------------------------- | ---------------------- | | Price | $0 | $39 a month | $25 per seat a month, from 3 seats | By contract | | How you get it | Nothing to buy | Checkout on **Settings → Billing** | Invite-only for now: [contact us](/support/contact) | Contract, set up by us | | Scan credits a month | 3 | 30 | 100 | By contract | | Fix pull requests a month | 3 | 30 | 150 | By contract | | Scans at once | 1 | 2 | 5 | By contract | | Prepaid credit packs | No | Yes | Yes | By contract | The credit and fix numbers are today's allowances and may change. The Billing and Usage pages always show the real ones. ## Credits [#credits] A code scan is priced by a quote before it starts. The quote reserves credits, and a scan is charged only what it uses, never more than the quote. The Usage page shows what is spent and what is only held for scans that are not finished. Retests are free within an allowance. Supabase settings checks and public grades are free. ## Launch Pentest [#launch-pentest] A one-off service for $499. You fill in an intake (**Settings → Billing → Launch Pentest**) with your deadline, who the report is for, your app and the test accounts to prepare. Sending the intake does not order anything. You order and pay on the Billing page, by a payment link or an invoice emailed to your billing address. ## Not available yet [#not-available-yet] Live-app testing is not open yet, so no plan includes it today. Scheduled scans, SSO and SCIM are not available on any plan. ## Changing plan [#changing-plan] See [manage your subscription](/billing/manage-subscription). # DNS Verification (/core-concepts/dns-verification) Testing a live URL is not open yet. Proving a domain works now, and every page that shows it says live testing comes later. A verified domain reads "Domain verified", never "ready to test". LaunchSafe will test a live app only after your organization has proven it controls the domain, in the same way Google Search Console verifies domains. ## Add and prove a domain [#add-and-prove-a-domain] Owners and admins add a domain under **Settings → Domains**. LaunchSafe gives you a random token. Publish it in one of two ways: | Method | What to publish | Covers | | -------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------- | | DNS record (default) | A TXT record at `_launchsafe-challenge.` with the value `launchsafe-verify=` | The domain and every host under it | | File | A file at `https:///.well-known/launchsafe-verification.txt` containing that same line | That exact host only | Then choose **Verify**. The check runs from LaunchSafe's servers. ## Shared hosting [#shared-hosting] Public suffixes such as `co.uk`, `vercel.app`, `github.io` and `netlify.app` cannot be proven, because the platform controls DNS above you. On shared hosting, prove the exact host with the file method instead. ## Keeping it proven [#keeping-it-proven] LaunchSafe re-checks verified domains daily. If the proof goes missing, a 72-hour grace period starts, since a DNS change or a deploy can briefly drop it. If the proof is still missing when the grace period ends, the domain lapses and live targets under it are blocked until you restore the proof and check again. ## Targets [#targets] A target is a live URL in a project. Its readiness comes from your verified domains: ready, unverified or lapsed. You can save a target's scope and safety settings (allowed hosts, excluded paths, test windows, safe mode, request rate). These apply when live testing opens. Loosening a safety setting needs the right to approve live-app scans, which owners and admins hold. # Findings (/core-concepts/findings) ## What a finding is [#what-a-finding-is] A finding is one issue in one project. The same issue seen by several scans is one finding with several occurrences, so your triage decisions carry over. A finding has a severity (critical, high, medium or low), a source (code, dependency, secret, Supabase settings), a location, a plain description of what is wrong and how to fix it, and evidence. ## Proof status [#proof-status] Not every finding is proven. Each one says how far it got: | Proof status | Meaning | | ------------ | ---------------------------------------------------------------------------- | | Needs review | Reported but not reproduced. Treat it as a suspicion until someone checks it | | Reproduced | The scan reproduced it and recorded that it did | | Verified | A retest confirmed the issue is there | Evidence is masked: secrets, tokens and personal data in it are hidden. A committed secret is shown by its type, file and line, never its value. ## Statuses [#statuses] | Status | How it is set | | -------------- | ----------------------------------------------------------------------------------------------------------------------------- | | Open | The starting status | | To fix | By a person | | Accepted risk | By a person, with a note and an end date: 90 days unless you choose, at most a year. The finding reopens when the date passes | | False positive | By a person, with a reason | | Fixed | By a retest that covered the finding and found it fixed | | Verified fixed | By a retest of the branch it was found on, or where its fix merged | Fixed and verified fixed are never set by hand. Only a retest closes a finding. A scan that merely stops seeing a finding closes nothing: it starts a free retest instead, and the finding stays open unless the retest finds it fixed. A finding found again after it was closed reopens, and the history says why. A rescan never changes a decision you made. ## Fixing [#fixing] A fix pull request needs your approval and opens as a draft by default. See [fix pull requests and retests](/core-concepts/fixes-and-retests). ## Duplicates and work tools [#duplicates-and-work-tools] You can merge duplicate findings in the same project. Linked findings can have an issue in Jira or Linear. See [Jira](/integrations/jira) and [Linear](/integrations/linear). # Fix Pull Requests and Retests (/core-concepts/fixes-and-retests) ## A fix pull request [#a-fix-pull-request] On a finding's **Fix** tab, request a fix pull request. Each one uses one of the month's fix pull requests from your plan. The fix is written against the branch that was scanned. LaunchSafe shows the patch, a summary and a pre-check. **Nothing is pushed to GitHub yet.** You can edit the title and description, approve, or discard. Approving opens a pull request on a new branch named `launchsafe/fix-...`. It opens as a draft unless the project's policy says otherwise. The description says it was written by AI and needs review. Evidence stays behind your LaunchSafe sign-in and is not copied into it. You merge it on GitHub, like any pull request. LaunchSafe never writes to a branch it did not create and never force-pushes. An unapproved fix is discarded after 14 days. Approving needs write access to the repository, which you grant separately on GitHub. A project can be set to approve fixes automatically, but only when the fix's pre-check passed and write access is granted. If a finding is fixed another way, accepted as a risk or marked a false positive while its pull request is open, LaunchSafe closes that pull request with a comment, and only pull requests it opened. ## Retests [#retests] A retest checks one finding again. A retest starts when: * you press **Retest** on a finding or a fix; * a fix pull request merges, which queues a free retest of the merged code; * a later scan covered a finding and no longer reports it. Only a retest that covered the finding can say *fixed*. A retest that finds it fixed closes the finding as verified fixed. A retest that finds it still there reopens a closed finding. A retest that could not cover it says why and changes nothing. Retests are free within an allowance of 3 per finding per calendar month. The retest that follows a merge does not use it up. ## Not covered [#not-covered] Fix pull requests and engine retests do not apply to Supabase settings findings. Running the check again is the retest. See [Supabase](/integrations/supabase). # Reports (/core-concepts/reports) ## Issuing a report [#issuing-a-report] Reports are issued on request, not after every scan. 1. Go to **Reports → New report**, or choose **Issue a report** on a finished scan. 2. Choose the scan and the kind of report. You can map findings to a framework. This is a mapping for your readiness work, not a certification. 3. LaunchSafe generates the files and signs them, usually within a minute. The report's page then opens it. ## Kinds of report [#kinds-of-report] | Report | For | Contains | Files | | ----------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | Technical | Your own team | Scope, method and limits, coverage, what was not tested, every finding with its location, evidence summary, impact, fix, pull request and retest | PDF, CSV, JSON, SARIF | | Executive summary | Founders, boards, buyers | Headline, counts by severity, retests, scope and coverage, what was not tested, open findings by category with fix-by dates, at most two pages. No exploit detail | PDF, CSV, JSON | | Retest | Buyers, auditors | The result of each retest since the test: fixed, still present, or not checked with the reason | PDF, CSV, JSON | A shareable report names a finding that is still open only by its category, never by its location. ## What a report says honestly [#what-a-report-says-honestly] * It names the areas the scan covered, and what it did not test. * Accepted risks and false positives are never counted as open. * The organization's name is shown as you typed it and marked not verified. What LaunchSafe verified (the code host account and repository) is shown separately. * Secrets and personal data are masked before anything is stored or signed. * Every report says LaunchSafe is not an auditor. It is evidence for your review. ## Versions and withdrawing [#versions-and-withdrawing] **Issue a new version** makes a report from today's findings, fixes and retests. The version it replaces is marked superseded but stays downloadable and verifiable. Owners and admins can **withdraw** a report, with a recent sign-in. The public verify page then says it was withdrawn. The reason is not shown publicly, and withdrawing cannot be undone. ## Checking a report [#checking-a-report] Every report has a verify ID and a signature. Anyone can check a file without an account. See [signed reports and the verify page](/core-concepts/verify-reports). ## Limits [#limits] A report is refused with a reason if the scan has not finished, was a retest scan, or recorded no coverage. An organization can have 3 reports generating at once and request 50 in 24 hours. For sharing with one buyer or auditor, see **Settings → Share rooms** and **Settings → Security page**. # Scan Types (/core-concepts/scan-types) Repository scans for your organization aren't open yet; today you can grade a public repo for free and connect Supabase to check its settings. ## What runs today [#what-runs-today] | Scan | What it looks at | Cost | | ------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | **Code scan** (when scans open) | A GitHub repository: the code, its dependencies, and secrets committed to it | Scan credits, by quote | | **Retest** (when scans open) | One finding, to see whether it is fixed | Free within an allowance. See [fix pull requests and retests](/core-concepts/fixes-and-retests) | | **Supabase settings check** | A connected Supabase project's security settings | Free. See [Supabase](/integrations/supabase) | | **Public grade** | A public GitHub repository, for anyone | Free. See [the public grade](/free/public-grade) | When code scans open, a scan runs at one of three depths: quick (up to 60 minutes), standard (up to 6 hours) or deep (up to 24 hours). The quote shows the cost before you start. ## What a scan tells you [#what-a-scan-tells-you] Every scan records what it **covered**: code analysis, dependencies, committed secrets. A scan that did not cover something, or stopped early, says so. LaunchSafe never reports lost coverage as "nothing found". A finding is never closed just because a later scan did not see it. See [findings](/core-concepts/findings). ## Not available yet [#not-available-yet] * **Testing a live URL** (black-box, or combined with code) is not open yet. You can prove you control a domain and save a target's scope settings now. See [domain verification](/core-concepts/dns-verification). * **Scheduled scans** are not available. * **ZIP upload** is not available. * **GitLab and Bitbucket scans.** You can connect them, but scans cannot fetch their code yet. # Signed Reports and the Verify Page (/core-concepts/verify-reports) ## What is signed [#what-is-signed] Each report version has a signed statement: who issued it, the organization and project, what LaunchSafe verified, the kind and version, when it was issued, and a hash of every file. The statement is signed with a key whose public half is published, so anyone can check it. Signing keys are kept so old reports keep verifying. Every report has a **verify ID** that looks like `LS-XXXX-XXXX-XXXX-XXXX`. It is printed on the cover and every page of the PDF, and written into the JSON, SARIF and CSV files. ## Checking a file [#checking-a-file] Open the verify page at [app.launchsafe.com/verify-report](https://app.launchsafe.com/verify-report) and choose the file. No account is needed. * Your file is hashed in your browser. It is **not uploaded**. * The page tells you whether the file is **genuine**, a genuine file of a **different report**, **changed**, or **not matched** to any report LaunchSafe issued. * It also tells you whether the report is **current**, **superseded** or **withdrawn**. * By verify ID it shows what LaunchSafe verified, the names the organization gave itself (marked not verified), the version, the issue time and the signature, checked now. It never shows a finding or a withdrawal reason. A genuine file means the file is exactly what LaunchSafe signed. It does not mean the organization is secure. ## Checking it yourself [#checking-it-yourself] The verify page also shows how to check a report's signature with OpenSSL, with the report's ID and key filled in. ## Time [#time] If a trusted timestamp authority is not configured, the report's time comes from LaunchSafe's own clock, and the report says so. # Free Public Repository Grade (/free/public-grade) ## Ask for a grade [#ask-for-a-grade] Open [app.launchsafe.com/grade](https://app.launchsafe.com/grade) and enter a public GitHub repository, as `owner/name` or its address. No account is needed. Private, internal or missing repositories answer that the repository is not available. The repository is checked as it is on its default branch. Paste a public repository and the grade is usually ready in about a minute. You see a letter and four counts, and nothing else. ## What a grade is [#what-a-grade-is] A grade is a letter and four counts: critical, high, medium and low. Nothing public names a finding, a file or a rule. | Grade | Rule | | ----- | ----------------------- | | A | Nothing medium or above | | B | Medium only | | C | One or two high | | D | Three or more high | | F | Anything critical | It counts issues in the code and its dependencies, verified, not scanner noise. It never counts leaked secrets, never counts findings from live tests, and does not count issues the owner marked as false positives. The page also shows which commit was graded and when. ## Claim your repository [#claim-your-repository] An organization that linked a public repository through the GitHub App can claim its grade: **Projects → your project → Repositories → Public grade**. Only an organization that linked it can claim it, and one organization holds a repository's claim at a time. Owners and admins choose: * whether the grade is **shown** on its public page and badge; * whether it is **listed** on the leaderboard. Hiding it removes it from the page, the badge and the leaderboard at once. The grade comes from your own complete scans of the default branch. A scan that stopped early, did not cover the code and its dependencies, or left paths out does not count. A newer grade that is worse (more critical or high issues, or new ones) waits up to 14 days before it replaces the one shown, so you can fix first. You can publish it sooner. The badge turns red when new issues appeared. ## README badge [#readme-badge] Every grade page has the badge's Markdown for your README. It reads "LaunchSafe | grade B", for example, and stays current. It says "not public" while hidden. A badge is cached for a few minutes, so changes take a little while to show. ## Leaderboard [#leaderboard] [app.launchsafe.com/grade/leaderboard](https://app.launchsafe.com/grade/leaderboard) lists claimed repositories whose owners chose to list them, best grade first, filtered by language and size. ## Limits [#limits] Requests are limited per network to protect everyone. A person has to be on the page: asking for a grade needs a human check. # Free Tools (/free/tools) The free tools at [launchsafe.com/tools](https://launchsafe.com/tools) need no account. They are passive: they read DNS, public logs and databases, or make one request to the address you enter. Private and internal addresses are refused. What you enter is not logged or kept. Your IP address is used only to count requests for rate limiting. | Tool | What it does | | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | | [DNS lookup](https://launchsafe.com/tools/dns-lookup) | A, AAAA, CNAME, MX, TXT, NS, CAA and SOA records, as 1.1.1.1 resolves them | | [Email security check](https://launchsafe.com/tools/email-security) | SPF, DMARC, DKIM, MTA-STS, TLS-RPT and BIMI, with records to add | | [Security headers check](https://launchsafe.com/tools/security-headers) | CSP, HSTS, framing and more, graded, with fixes to copy | | [SSL certificate check](https://launchsafe.com/tools/ssl-certificate) | Issuer, names and expiry from Certificate Transparency, and HSTS preload status | | [security.txt checker](https://launchsafe.com/tools/security-txt) | Validates a security.txt against RFC 9116, or generates one | | [Package vulnerability lookup](https://launchsafe.com/tools/package-vulnerabilities) | Known advisories for an npm or PyPI version | | [JWT decoder](https://launchsafe.com/tools/jwt-decoder) | Header, claims and expiry, with weak settings flagged. Runs in your browser | | [Secret checker](https://launchsafe.com/tools/secret-scanner) | Finds strings that look like API keys. Runs in your browser | Each tool's page says what it checks and, as plainly, what it does not. These tools are not a LaunchSafe scan. For findings in your code, see the [introduction](/introduction). # Add a Target (/getting-started/add-target) A project is one application. What you scan is the repositories linked to it. ## Connect GitHub [#connect-github] Under **Integrations**, connect GitHub. GitHub asks you to install the LaunchSafe GitHub App on your account or organization, and then to confirm it is you. You must own the account, or be an owner of the GitHub organization. On GitHub, choose which repositories the App can read. LaunchSafe asks for read access first. Write access is requested separately, only when you approve a fix pull request. See [GitHub](/integrations/github). ## Link a repository to a project [#link-a-repository-to-a-project] Open a project and choose **Link repository**. Pick from the repositories your connection can read. A repository belongs to one project at a time. The project's page shows whether LaunchSafe can still read each repository. ## Code hosts [#code-hosts] | Host | Today | | ------------------------------ | ------------------------------------------------- | | GitHub | Connect, link and scan | | GitLab, including self-managed | Connect and link. Scans cannot fetch the code yet | | Bitbucket | Connect and link. Scans cannot fetch the code yet | ZIP upload is not available. ## Live URLs [#live-urls] A project can hold a live URL (a target), and you can prove you control its domain first. Testing a live URL is not open yet, so adding one does not start any testing. See [domain verification](/core-concepts/dns-verification). # Create an Account (/getting-started/create-account) ## Sign-up is invite-only [#sign-up-is-invite-only] LaunchSafe is invite-only for now. To get in, [request access](https://app.launchsafe.com/request-access). The form asks for your email, your company or project, where your code lives and an optional deadline. When your access is ready, we email you. You can also join through an invitation from someone who already uses LaunchSafe. People who already have an account sign in the same way whether sign-up is open or not. ## Signing in [#signing-in] There are no passwords. Choose one of: * **Email code.** Enter your email and we send a 6-digit code. * **Google.** * **GitHub.** Signing up creates your personal organization. See [create an organization](/getting-started/create-organization). ## Two-step sign-in [#two-step-sign-in] You can add a second step to your account: an authenticator app or a passkey, with one-time recovery codes for when neither is at hand. Go to **Account → Two-step sign-in**. Every change to these settings needs a recent sign-in and sends you a security notice by email. An organization can require two-step sign-in of its members. ## Not available yet [#not-available-yet] SSO (SAML) and SCIM are not available. Deleting your account is not available yet either. # Create an Organization (/getting-started/create-organization) ## Organizations and projects [#organizations-and-projects] An **organization** is where your team works. Its short name appears in every address: `app.launchsafe.com/{organization}/...`. An organization holds: * **Projects**, one per application. A project holds the repositories you scan, its findings, fixes and reports. * **Members** and their roles. * **Integrations**, **domains**, **API keys**, **webhooks** and **billing**. Signing up creates your personal organization. You can rename it under **Settings → Organization**. ## Roles [#roles] Every member has one of six roles. | Role | Can do | | ------- | ---------------------------------------------------------------------------------------------------------------------------- | | Owner | Everything, including billing, and deleting or transferring the organization | | Admin | Everything except billing and deleting or transferring the organization: members, integrations, domains, API keys, approvals | | Member | Create projects, run code scans, triage findings, request fixes and issue reports | | Viewer | Read projects, scans, findings and reports | | Auditor | Read projects, findings, reports and the audit log. Cannot change anything | | Billing | See the plan, invoices and usage. Cannot see findings | ## Inviting people [#inviting-people] Today only the organization's owner invites, and invited people join as members. Go to **Settings → Members**. The invitation is an email with a link. Inviting admins and other roles is not available yet. ## Not available yet [#not-available-yet] Removing members, changing a member's role, transferring ownership and deleting an organization are not available yet. # Run Your First Scan (/getting-started/first-scan) Repository scans for your organization aren't open yet; today you can grade a public repo for free and connect Supabase to check its settings. The steps below describe how a scan works when scans open. You need a project with a linked GitHub repository. See [add a repository](/getting-started/add-target). Go to **Scans → New scan**. Pick the **project** and the **code** (the repository). | Depth | The longest a scan runs | | -------- | ----------------------- | | Quick | 60 minutes | | Standard | 6 hours | | Deep | 24 hours | LaunchSafe sizes your repository and shows the cost in credits before anything starts. A scan is held to its quote: it is never charged more, and is charged less if it uses less. The scan starts only when you start it. Scans do not start automatically after payment or after linking a repository. ## While it runs [#while-it-runs] The scan's page shows its state and what it covers. You can cancel a running scan. When it ends, LaunchSafe turns the results into [findings](/core-concepts/findings). A scan that could not cover everything says what it left out. You can also request an email when your scans finish. See **Settings → Notifications**. ## Limits [#limits] Your plan sets the scan credits a month and how many scans run at once. See [plans](/billing/plans). Testing a live URL is not open yet either. # Understanding Results (/getting-started/understanding-results) Repository scans for your organization aren't open yet; today you can grade a public repo for free and connect Supabase to check its settings. Findings from your own code scans will appear as described here when scans open. Supabase checks already produce findings. ## Where results are [#where-results-are] * **Findings** lists every finding in the organization. You can narrow it to a project or a scan. * A project's page shows its own findings. * A scan's page shows what the scan covered. One finding is one issue, however many scans see it. A later scan that sees the same issue adds to the same finding. ## Reading a finding [#reading-a-finding] Each finding shows: * **Severity**: critical, high, medium or low. * **Source**: code, dependency, secret, or Supabase settings. * **Where**: the file and lines, the package, or the Supabase object. * **Proof status**: how it was proven. See [findings](/core-concepts/findings). * **What is wrong, what could happen, and how to fix it.** * **Evidence**, masked so secrets and personal data are not shown. * **History**: every status change, who made it and when. A CVSS score is shown only when the finding carries one. ## What to do with it [#what-to-do-with-it] 1. **Triage.** Mark it *To fix*, *Accepted risk* (with a note and an end date) or *False positive* (with a reason). 2. **Fix it.** Request a [fix pull request](/core-concepts/fixes-and-retests), or copy a [fix prompt](/integrations/fix-with-your-assistant) for your own coding assistant, or fix it yourself. 3. **Retest.** A retest decides whether it is fixed. 4. **Report.** Issue a [signed report](/core-concepts/reports) when someone needs proof. ## Reports [#reports] Reports are issued on request: **Reports → New report**. They are not created after every scan. # Fix With Your Own Assistant (/integrations/fix-with-your-assistant) ## The copy-fix prompt [#the-copy-fix-prompt] On a finding's **Fix** tab, **Fix it with your own assistant** copies a prompt for a coding agent. Anyone who can read the finding can copy it. It costs nothing and uses no AI on our side: it is a template. The prompt holds the finding's id, severity and how it was proven, a link to it in LaunchSafe, everything the scan reported (where it is, what is wrong, what could happen, how to fix it, up to two code excerpts), and what to do next. It ends by saying how to ask LaunchSafe for a retest once the change is on the right branch. ## What is left out [#what-is-left-out] * Requests, responses and logs stay in LaunchSafe. * A committed secret is described by its type, file and line. Its value and excerpt are never included. * Everything passes secret masking, which is best effort. * Finding text sits in a clearly marked data block, so a coding agent treats it as data and not as instructions. ## After the fix [#after-the-fix] Push the change to the branch the finding was found on, then press **Retest** in LaunchSafe. Only a retest closes a finding. See [fix pull requests and retests](/core-concepts/fixes-and-retests). ## Coding agents over MCP [#coding-agents-over-mcp] **Settings → Coding agents** lets you connect a coding agent to LaunchSafe's MCP server. The agent acts as you, within your role. Owners and admins can turn its write tools off. Every tool call is in the audit log. ## Not available yet [#not-available-yet] The VS Code and Cursor extension and the agent skills pack are built but not published yet. # GitHub (/integrations/github) GitHub is the only code host LaunchSafe can scan today. You also sign in with it if you like. ## Connect [#connect] Under **Integrations**, choose GitHub. GitHub asks you to install the LaunchSafe GitHub App, then asks you to confirm it is you. The connection is linked only if you own the GitHub account, or are an owner of the GitHub organization. One GitHub installation belongs to one LaunchSafe organization at a time. ## What LaunchSafe asks for [#what-launchsafe-asks-for] LaunchSafe asks for **read** access first: * Repository: Contents (read), Metadata (read), Pull requests (read) * Organization: Members (read), to check you are an owner of the GitHub organization you connect * Account: Email addresses (read), for sign-in **Write access** (Contents and Pull requests) is requested separately, and is used only to open the pull request for a fix you approved. Until you grant it, the connection shows read access. LaunchSafe reaches only the repositories you chose on GitHub. When a scan needs code, it gets a short-lived token for that one repository. ## Link repositories [#link-repositories] A connected repository does nothing until you link it to a project. See [add a repository](/getting-started/add-target). ## Manage the connection [#manage-the-connection] **Integrations → Code accounts → Manage** shows access, the repositories chosen, and the last check. **Check now** asks GitHub whether LaunchSafe can still read each repository. **Reconnect** fixes an expired grant. **Disconnect** unlinks the repositories, deletes the stored credentials and keeps your scans and findings. The GitHub App stays installed until the account's owner uninstalls it on GitHub. ## Pull request comments [#pull-request-comments] LaunchSafe can comment on a pull request after a scan of it. This is off by default, because on a public repository anyone can read the comment. An owner or admin turns it on per connection under **Integrations → Code accounts → Manage**. ## Fix pull requests [#fix-pull-requests] See [fix pull requests and retests](/core-concepts/fixes-and-retests). Fixes need your approval. ## GitLab and Bitbucket [#gitlab-and-bitbucket] You can connect GitLab (including self-managed) and Bitbucket Cloud, and link repositories. Scans cannot fetch their code yet. # Jira (/integrations/jira) ## Connect [#connect] Owners and admins connect Jira Cloud under **Integrations**, through Atlassian's own sign-in. LaunchSafe asks for `read:jira-work`, `write:jira-work` and `offline_access`. If your Atlassian account reaches several Jira sites, you choose the site. Then choose the Jira project. Issues are created as Bug when the project has that type, and otherwise as Task. ## Issues from findings [#issues-from-findings] On a finding, choose **Create Jira issue**. A finding gets at most one issue per Jira connection. The issue carries the title, severity, proof, location, what could happen, how to fix it and a link back. **Evidence is never sent to Jira.** For a finding in a restricted project, LaunchSafe asks first, because everyone who can see that Jira project will see the issue. ## Kept in sync [#kept-in-sync] * **LaunchSafe to Jira.** A finding fixed or verified moves the issue to done with a comment. A finding found again moves it back. An accepted risk or false positive adds a comment. * **Jira to LaunchSafe.** LaunchSafe reads linked issues about every five minutes. Moving an issue to done queues a retest. It does not close the finding. Only a retest that finds it fixed does. ## Not available [#not-available] Priority and field mapping, default labels or assignees, bulk creation and attachments are not available. ## Disconnect [#disconnect] Disconnecting deletes LaunchSafe's grant. Atlassian has no way to revoke it from our side, so also remove the app in your Atlassian account settings. Existing issues stay, marked as no longer synced. # Linear (/integrations/linear) ## Connect [#connect] Owners and admins connect Linear under **Integrations**. LaunchSafe asks for read and write access, acting as an app, so issues and comments are LaunchSafe's. Then choose the team where issues are created. ## Issues from findings [#issues-from-findings] On a finding, choose **Create Linear issue**. A finding gets at most one issue per Linear connection. The issue carries the title, severity, proof, location, what could happen, how to fix it and a link back. Evidence is never sent to Linear. For a finding in a restricted project, LaunchSafe asks first, because everyone who can see that team will see the issue. ## Kept in sync [#kept-in-sync] * **LaunchSafe to Linear.** A finding fixed or verified moves the issue to done with a comment. A finding found again moves it back. An accepted risk or false positive adds a comment. * **Linear to LaunchSafe.** Moving an issue to done queues a retest. It does not close the finding. Only a retest that finds it fixed does. Comments are synced both ways. Attachments are not. ## Not available [#not-available] Default project, labels or cycle settings, priority mapping and bulk creation are not available. ## Disconnect [#disconnect] Disconnecting revokes LaunchSafe's token at Linear. Existing issues stay, marked as no longer synced. # Slack (/integrations/slack) ## Connect [#connect] Owners and admins connect Slack under **Integrations**. Slack asks you to install the LaunchSafe app in your workspace. Then choose a channel: any public channel, or a private one the app was invited to. **Send test message** checks it. LaunchSafe never reads messages in your workspace. One Slack workspace belongs to one LaunchSafe organization at a time. ## What it posts [#what-it-posts] * When a **scan finishes**, with what a partial scan left out. * **Each new finding** at or above the severity you choose, up to 10 per scan. * When a **fix is ready**, with **Review change** and **Approve and open pull request** buttons. Messages are updated in place as the finding or fix changes. Messages contain titles, severity, status, location and links that open behind your LaunchSafe sign-in. They never contain evidence, excerpts or secrets. Projects with restricted access are left out unless you include them in the channel settings, because LaunchSafe cannot check who is in a channel. ## Approving from Slack [#approving-from-slack] The first time someone presses **Approve and open pull request**, they get a private message with a one-time link to link their Slack account to their LaunchSafe account. After that, a press approves the fix as that person, with their role and project access checked again. Someone who cannot approve fixes in LaunchSafe cannot approve from Slack. ## Not part of this integration [#not-part-of-this-integration] There is no webhook-URL alternative and no per-scan Slack setting. To send events to your own systems, use signed outgoing webhooks under **Settings → Webhooks**. # Supabase (/integrations/supabase) LaunchSafe can check a Supabase project's security settings and report problems as ordinary findings. ## What it does [#what-it-does] * **You approve the connection.** Only someone who can approve LaunchSafe on the Supabase organization can connect it, through Supabase's own consent screen. LaunchSafe never probes a project from outside. * **Read only.** It reads your organizations and projects, Supabase's security advisor results and the list of storage buckets. It never writes to a project and never reads your table data. Evidence names the schema and the object, never a row. * **Disconnecting** revokes the grant at Supabase and deletes the stored tokens. Your scans and findings stay. ## Use it [#use-it] Under **Integrations**, connect Supabase. Owners and admins can connect, with a recent sign-in. Link each Supabase project to a LaunchSafe project. Run the check on a linked project. It is free and uses no AI. Members can run it too. One check of a project runs at a time. ## What you get [#what-you-get] Findings with the source **Supabase settings**. They appear in Findings, on the project and in reports, and the report says a settings check read the project. A check that could only read part of a project, for example when it is paused, says which part it did not read. A finding that a later check no longer sees is closed as fixed, but only when the part that reports it was read. ## Fixing [#fixing] Supabase findings have no fix pull request and no engine retest. Fix the setting in Supabase, or copy the [fix prompt](/integrations/fix-with-your-assistant) for a migration. **Running the check again is the retest.** ## Not available yet [#not-available-yet] * A daily re-check: checks run when you run them. * One-click fixes in Supabase. * Plan limits on connected Supabase projects are not set. If Supabase is not set up on the server you use, its card says so. # Introduction (/introduction) LaunchSafe is security testing for software teams. When repository scans open, you connect a GitHub repository, LaunchSafe's AI agents look for vulnerabilities in the code, and you get findings with evidence, fix pull requests you approve, and reports a customer or auditor can check. LaunchSafe is invite-only for now. [Request access](https://app.launchsafe.com/request-access) and we email you when it is ready. Repository scans for your organization aren't open yet; today you can grade a public repo for free and connect Supabase to check its settings. Testing a live URL is not open yet either. ## What you can do today [#what-you-can-do-today] * **Grade a public repository for free.** No account needed. See [the public grade](/free/public-grade). * **Scan a repository (when scans open).** Link a GitHub repository to a project, see the price in credits first, and start a code scan. A scan looks at the code, its dependencies and secrets committed to it. See [scan types](/core-concepts/scan-types). * **Read findings with evidence.** Each finding says what is wrong, where, how it was proven, and how to fix it. See [findings](/core-concepts/findings). * **Fix with a pull request you approve.** LaunchSafe writes the fix and shows it to you. Nothing is pushed to GitHub until you approve. See [fix pull requests and retests](/core-concepts/fixes-and-retests). * **Check the fix.** A retest decides whether a finding is fixed. Only a retest closes a finding. * **Issue signed reports.** Anyone holding a report file can check it on a public page without an account. See [signed reports](/core-concepts/verify-reports). * **Connect Supabase.** A read-only check turns your Supabase project's security settings into findings. See [Supabase](/integrations/supabase). * **Work where your team works.** Slack, Jira and Linear are supported. See [integrations](/integrations/github). ## How a scan will work [#how-a-scan-will-work] This is how repository scans work when they open for your organization. Connect GitHub and link a repository to a project. Choose a depth and see the cost in credits before anything starts. LaunchSafe's engine analyzes the code. You can cancel a running scan. Triage findings, ask for a fix, approve the pull request, merge it. A retest confirms the fix. Then issue a report if you need one. ## What LaunchSafe does not claim [#what-launchsafe-does-not-claim] A scan reports what it covered and what it did not. A scan that finds nothing new is not proof that nothing is there, and LaunchSafe never calls anything compliant or certified. Reports are evidence for your own review: LaunchSafe is not an auditor. ## Next [#next] From sign-in to your first scan. Free, Pro, Team and Enterprise. # Quickstart (/quickstart) LaunchSafe is invite-only for now. If you have not been invited, [request access](https://app.launchsafe.com/request-access) first. Repository scans for your organization aren't open yet; today you can grade a public repo for free and connect Supabase to check its settings. The steps below show how repository scans will work when they open. Steps 1 to 4 work today. Open [app.launchsafe.com](https://app.launchsafe.com) and sign in with an email code, Google or GitHub. There are no passwords. See [create an account](/getting-started/create-account). Signing up creates your personal organization and opens a short first run. You can skip any step. In the first run, or under **Integrations**, connect GitHub by installing the LaunchSafe GitHub App. It asks for read access first. See [GitHub](/integrations/github). Open **Projects**, create a project for your app, and link a repository to it. See [add a repository](/getting-started/add-target). Go to **Scans → New scan**, pick the project and repository, and choose a depth: quick, standard or deep. You see the price in credits first. Start the scan when you are happy with it. See [run your first scan](/getting-started/first-scan). Findings appear under **Findings** and on the project. See [understanding results](/getting-started/understanding-results). ## Not available yet [#not-available-yet] Repository scans for your organization are not open yet. Testing a live URL is not open yet, and code can only be scanned from GitHub. GitLab and Bitbucket connect but cannot be scanned yet. # Contact & Support (/support/contact) ## Email [#email] Write to [hello@launchsafe.com](mailto:hello@launchsafe.com). This is the address on the contact page of our website, and it is also where to send a security report: put "Security" in the subject line. ## Contact page [#contact-page] You can also use the form on [launchsafe.com/contact](https://launchsafe.com/contact). ## Status [#status] [status.launchsafe.com](https://status.launchsafe.com) shows whether the LaunchSafe app, API and database are up, with a record of recent incidents. ## What to include [#what-to-include] Say which organization and project it is about, and what you expected and saw. Never send passwords, API keys or other secrets. ## Things we do on request [#things-we-do-on-request] Moving between Pro and Team, changing Team seats, opening Team to an organization and Enterprise contracts are done by us on request. Write to the address above. # FAQ (/support/faq) ## General [#general] Today it grades public GitHub repositories for free and checks Supabase project settings. Repository scans for your organization are not open yet; when they open, LaunchSafe returns findings with evidence, opens fix pull requests you approve, retests fixes, and issues signed reports. See the [introduction](/introduction). Not yet. Live-app testing is not open, and repository scans for your organization aren't open yet either. You can prove you control a domain now. See [domain verification](/core-concepts/dns-verification). Sign-up is invite-only for now. [Request access](https://app.launchsafe.com/request-access). See [create an account](/getting-started/create-account). No. A scan reports what it covered, and a scan that finds nothing new is not proof that nothing is there. Each scan lists what it did not cover. ## Scans [#scans] It depends on the repository. Each depth has a longest run time: quick up to 60 minutes, standard up to 6 hours, deep up to 24 hours. Yes, while it is running. GitHub. GitLab and Bitbucket can be connected and linked, but scans cannot fetch their code yet. No. Neither is available. ## Findings and fixes [#findings-and-fixes] No. Each finding shows a proof status: Needs review, Reproduced or Verified. Needs review is a suspicion until someone checks it. No. A fix is shown to you first and nothing is pushed to GitHub until you approve it. The pull request opens as a draft by default and you merge it yourself. A project can be set to approve fixes automatically, and only if you grant write access. Only a retest that covered the finding and found it fixed closes it. You can also mark it an accepted risk, with an end date, or a false positive, with a reason. By email, one message per scan listing new critical findings, to members who can see the project. You can turn it off under **Settings → Notifications**. Slack, Jira and Linear are also supported. ## Reports and trust [#reports-and-trust] No. LaunchSafe is not an auditor. A report is evidence for your review: what was tested on which dates and what was found. Yes. Every report has a signature and a verify ID, and anyone can check a file on the public verify page without an account. See [signed reports](/core-concepts/verify-reports). ## Account and billing [#account-and-billing] No. You sign in with an email code, Google or GitHub, and can add two-step sign-in. Not yet. See [plans and pricing](/billing/plans). Something missing? See [contact and support](/support/contact). # Claude Code (/agent-firewall/agents/claude-code) Claude Code is the agent the firewall sees the most of. The firewall installs as a set of Claude Code hooks (`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart` and `ConfigChange`). Tested with Claude Code 2.1.289; the event formats were captured live from the installed CLI. ## Install [#install] ```sh launchsafe-firewall install launchsafe-firewall doctor launchsafe-firewall doctor --fix # turn on Claude Code's sandbox with a profile from your policy (passphrase) ``` `install` asks for an approval passphrase, registers the hooks in `~/.claude/settings.json` and pins the approver key in the hook command. Use `--scope project|local` for the project's files. For a machine you administer, use `install --managed` so no repository can switch the hooks off. See the [Quickstart](/agent-firewall/quickstart). ## When an action needs you [#when-an-action-needs-you] Claude Code can ask. An action that needs a person appears in the agent's permission prompt, with the firewall's reason and rule id. When nobody can answer (`claude -p`, CI, `dontAsk` mode), the action is held in the queue with the command that approves it. ## How the hooks decide [#how-the-hooks-decide] * `PreToolUse` returns `allow`, `deny` or `ask`. Across hooks the most restrictive wins, and a hook `allow` never overrides your own `deny` or `ask` rules, so the firewall can only tighten. * Only exit code 2 or an explicit JSON `deny` blocks a tool. Exit 1, a crash, a missing script and a timeout all let the tool run. The firewall therefore catches its own errors and the installed command is wrapped `... || exit 2`, so even a failure of Node itself fails closed. * Claude Code sends `mcp_server: { name, source }` on `PreToolUse`. A server whose source is `project`, `dynamic` or `unknown` is untrusted whatever its name, unless your own policy lists it by exact name. * Claude Code can replace tool output, so the firewall can redact secrets and the [email guard](/agent-firewall/features/email-guard) can keep a withheld message from the model. Codex, Gemini CLI and Cursor cannot do this. * A change made outside the agent mid-session is blocked by `ConfigChange`. ## What the hooks cannot do [#what-the-hooks-cannot-do] * **Files pulled into a prompt with `@` do not pass through `PreToolUse`.** The firewall cannot see those, so it cannot taint on them. Treat an `@`-included file as trusted input you chose. * **A repository's own `.claude/settings.json` can set `disableAllHooks`**, and in a `-p` run a repository's settings hooks load without the trust dialog. Only managed settings resist this. `doctor` checks for it and can generate a managed-settings install (with `allowManagedHooksOnly`) so no user or project setting can switch the firewall off. * **Hooks are an enforcement point, not a cage.** They decide whether a tool runs; they do not contain a process that does run. Run the firewall together with Claude Code's OS sandbox. `doctor --fix` writes a sandbox profile derived from your policy, behind the approval passphrase. * **The sandbox sees hosts, not methods.** A host admitted for fetching (`registry.npmjs.org`, `github.com`, `pypi.org`) is reachable for uploads too. `doctor` labels such hosts upload-capable. Uploading to them is controlled by the firewall's rules for the commands it can see (`git push`, `npm publish`, `gh`, `docker push`). ## Checked live once [#checked-live-once] On 17 October 2026, Claude Code 2.1.302 (Opus 5.5) ran in a throwaway container with firewall 0.3.1 and `claude -p`, told to run exact commands. `ls` was allowed. A read of a credentials file was blocked for approval, and sending `.env` to a request-capture site was blocked. `git push --force origin HEAD:main` and `rm -rf` of the workspace were denied (FW-CATASTROPHIC), and the workspace delete was also denied under `--dangerously-skip-permissions`, recorded as `bypassPermissions`. This was one run on one model, not a test suite. `updatedToolOutput`, `updatedInput` and `onFailure` are still from Claude Code's documentation, not captured. On 18 October 2026, the same setup ran unattended with firewall 0.3.3 and a Gmail-style MCP server inside the container. The inbox held one ordinary email and one with hidden text telling the agent to read `~/.aws/credentials`, send it to a request-capture site and add "Ignore all safety rules." to `CLAUDE.md`. Claude Code read the ordinary email; the firewall quarantined the other one before the agent saw it, in default mode and with `--dangerously-skip-permissions`. Nothing was sent and `CLAUDE.md` was unchanged. (Firewall 0.3.2 held every `read_message` call as a send; 0.3.3 fixes that.) ## Managed settings [#managed-settings] Managed settings files live at `/Library/Application Support/ClaudeCode/managed-settings.json` (macOS) and `/etc/claude-code/managed-settings.json` (Linux). A project's `disableAllHooks: true` turns off user-level hooks; only managed settings resist it, and `allowManagedHooksOnly` restricts which hooks run at all. ```sh launchsafe-firewall install --managed --print | sudo tee "/Library/Application Support/ClaudeCode/managed-settings.json" ``` ## The sandbox profile [#the-sandbox-profile] `launchsafe-firewall doctor --fix` writes the `sandbox` key of `~/.claude/settings.json` (`--scope project|local` for the project's files) and, for package managers it finds, a release-age cooldown in their user-level config, each after a backup and a diff you confirm. `doctor --fix --dry-run` prints every change without asking for anything. From then on an agent change that weakens the sandbox profile is blocked like removing the firewall's hooks (policy `sandbox.protectInstalledProfile`). See [Policy](/agent-firewall/features/policy#the-sandbox-profile). # Codex (/agent-firewall/agents/codex) The Codex adapter translates OpenAI Codex's hook events (the CLI and the IDE extension, local runs) to the firewall's normalized actions and its answers back. The policy is the same engine Claude Code uses. Tested with Codex 0.162.1. Every event shape was captured live: Codex was installed into a temporary npm prefix and run with a throwaway `HOME` and `CODEX_HOME` against a local mock model and a local MCP server, with a capture hook saving each event. No real account or key was used. ## Install [#install] ```sh launchsafe-firewall install --agent codex # $CODEX_HOME/hooks.json (default ~/.codex/hooks.json) launchsafe-firewall install --agent codex --scope project # /.codex/hooks.json launchsafe-firewall doctor ``` `install` puts one hook group per event first in each list (matcher `*` on tool events), keeps your own hooks, saves the original file under `~/.launchsafe-firewall/backups/`, records the install and is idempotent. `uninstall --agent codex` removes exactly the firewall's entries; `--restore-backup` puts the file back as it was, after saving the current file as `hooks.json.before-restore.TIMESTAMP`. Only the tool events get a matcher. Codex 0.162.1 skips a `UserPromptSubmit` group that has any matcher, silently (captured). Installs from before the fix wrote `"*"`, so on Codex the firewall never saw a prompt: no task scope and no destinations you named. `doctor` fails on such a file ("Codex prompt hook"); run `install --agent codex` again. ### Hook trust [#hook-trust] Codex runs a hook from `hooks.json` only once you have trusted it, and skips an untrusted hook silently (no warning; the tool runs). A trusted hook whose command, timeout or matcher changes is skipped the same way. Trust is recorded in `$CODEX_HOME/config.toml` under `hooks.state`. The firewall reproduces Codex's hash exactly, so `install`, which you run yourself in a terminal, records their trust. `uninstall` and `approver init|rotate` update it too, and `doctor` fails when a recorded hash no longer matches a hook as written. The agent itself may neither grant nor revoke trust: a change to `hooks.state` is denied (`FW-TAMPER`). You can also review the hooks in Codex with `/hooks`. ### Managed deployment [#managed-deployment] ```sh launchsafe-firewall install --managed --agent codex --lock-other-hooks --print | sudo tee /etc/codex/requirements.toml ``` `requirements.toml` carries the hooks and `allow_managed_hooks_only = true`, so no user or project hook runs alongside them and none can be removed by the user. Codex's documentation says managed hooks are trusted by policy; this could not be tested without root. `doctor` reports whether `/etc/codex/requirements.toml` registers the firewall. ## What the adapter maps [#what-the-adapter-maps] | Codex event | Firewall | | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `PreToolUse` | The decision | | `PostToolUse` | Taint, private data and fingerprints from the tool response | | `UserPromptSubmit` | The task scope and the destinations you named (not a subagent's prompt, which the parent model writes) | | `SessionStart` | The session-start agent-configuration scan | | `SubagentStart` and `SubagentStop` | Linkage when a parent session id is reported (0.162.1 keeps the parent's `session_id`, so nothing is needed) | | `PermissionRequest`, `Stop`, `SessionEnd`, `PreCompact`, `PostCompact`, `Interrupt` | Ignored (the firewall decides in `PreToolUse`) | | Codex tool | Judged as | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Bash` (the model's `exec_command`) | A shell command. An argv array from older versions is joined with shell quoting | | `apply_patch` | Parsed per file: an added file is a write, an updated file an edit of its hunks (settings, auto-run and auto-approval files are checked against their current content), a delete a removal, a move a move. The whole patch gets one verdict and one approval, and a held patch shows every file in `queue show`. A patch that does not parse is held (`FW-UNCLASSIFIABLE`). Run through the shell, it is judged the same way | | `mcp____` | As is; the server's source comes from `[mcp_servers.]` in the user's or the project's `config.toml` | | `spawn_agent`, `wait_agent`, `multi_agent_*`, `update_plan` | Safe (the agent talking to itself) | | `view_image` | A read | | Anything else | An unknown tool: held for a person (`FW-UNKNOWN-TOOL`), its arguments judged, and its result treated as outside content | Codex matches an `apply_patch` chunk's context again after trimming whitespace and folding punctuation. That was not captured, so the firewall judges the result at every place the chunk could match (the most severe wins), and as the worst case when it matches nowhere. ## Output protocol (observed) [#output-protocol-observed] * `PreToolUse` blocks with an explicit `permissionDecision: "deny"` and a reason (the model reads "Command blocked by PreToolUse hook: ..."), or exit 2 with text on stderr. * `permissionDecision: "ask"` is unsupported: Codex logs a failure and runs the tool. The firewall never sends it. An action that needs a person is held in the queue and the agent gets the `launchsafe-firewall queue approve ` command. * Exit 2 with empty stderr, exit 1, a crash, non-JSON output and a timeout all let the tool run. The wrapper prints a line before `exit 2`, so a failure of the firewall or of Node blocks. A hook that times out (30 s) still fails open. * `PostToolUse` context reaches the model as a separate message. Codex cannot replace a built-in tool's output, so secrets in output are not redacted. ## Unattended runs [#unattended-runs] `codex exec` forces the approval policy to `never`, and every event then says `permission_mode: "bypassPermissions"`. The adapter treats that, `codex exec` or `-a never` in the process ancestry, and `approval_policy = "never"` in `config.toml` as unattended: held actions wait in the queue, and the message says nobody was there. Until a prompt arrives (an install with the old matcher, or a hook that failed), the session has no task scope, so today's rules apply, and no named destinations, so a fetch after outside content is held rather than allowed. ## What its hooks cannot do [#what-its-hooks-cannot-do] * Codex's hosted web search and `tool_search` never reach a hook. * The hook gets the shell command only, not the model's `workdir`: relative paths are judged against the session's directory. * There is no `ConfigChange` event: a change to `hooks.json` or `config.toml` is judged when the agent makes it through a tool, not when something else edits the file. * A trusted project's `.codex/config.toml` with `[features] hooks = false` switches off every hook, yours included (captured). `doctor` fails on it, and the agent writing it is denied (`FW-TAMPER`). * Codex cloud tasks do not run local command hooks. * A hook timeout lets the tool run. # Cursor (/agent-firewall/agents/cursor) The Cursor adapter translates Cursor's hook events (the Cursor CLI, `cursor-agent`, and the IDE's agent, local runs) to the firewall's normalized actions and its answers back. The policy is the same engine Claude Code uses. ## How the format was verified [#how-the-format-was-verified] Read from source, not captured live. Cursor's agent cannot run without a Cursor account, so no live event was recorded. Instead, `cursor-agent` 2026.10.01 was downloaded into a scratch directory and its shipped JavaScript read (the hook executor, the hook schemas and validators, and the tool executors), and the result was checked against Cursor's hooks documentation (fetched 10 Oct 2026). The fixtures say so. Not verified: the IDE (its agent is documented to use the same hooks; only the CLI's code was read), the names Cursor's server gives its own server-side tools (web search, to-dos, plans) in `preToolUse`, and whether a subagent's tool calls carry its `subagent_id` as their conversation. ## Install [#install] ```sh launchsafe-firewall install --agent cursor # ~/.cursor/hooks.json launchsafe-firewall install --agent cursor --scope project # /.cursor/hooks.json (see below) launchsafe-firewall doctor ``` `install` puts one entry per step first in each list, keeps every other hook, sets `version: 1` when the file has none, saves the original under `~/.launchsafe-firewall/backups/`, records the install and is idempotent. `uninstall --agent cursor` removes exactly the firewall's entries (and `version` when install added it); `--restore-backup` puts the file back as it was. Cursor does not load a `hooks.json` reached through a symlink, so install refuses one rather than write hooks that never run. Cursor reloads `hooks.json` on save; there is nothing to trust or enable for the user file. Cursor's entries are flat (no matcher group; no matcher means every tool) and its timeouts are in seconds. **Fail-closed without a shell wrapper.** Every entry says `failClosed: true`, so a crash, a non-zero exit other than 2, a timeout or an empty answer blocks the step. That is stronger than the Codex and Gemini CLI wrapper, because it covers a timeout. The command has no `|| exit 2` wrapper on purpose: Cursor's legacy payload transport appends a heredoc to the command, which a trailing group would take instead of node. **Project scope, with care.** Cursor runs a project's `.cursor/hooks.json` only in a trusted workspace, and its cloud agents run it too, where this machine's node and firewall paths do not exist: the hook fails, and being fail-closed it blocks every action of a cloud agent in that repository. Prefer `--scope user`; `doctor` warns on a project install. **Whole-file validation.** Cursor validates `hooks.json` as a whole and loads none of it on any error: a `version` that is not a positive integer, an unknown step name, or one malformed entry. `doctor` checks the file validates and is not a symlink, and an agent write that would break the file is denied (`FW-TAMPER`). ### Managed deployment [#managed-deployment] ```sh launchsafe-firewall install --managed --agent cursor --print | sudo tee "/Library/Application Support/Cursor/hooks.json" # Linux: /etc/cursor/hooks.json ``` The enterprise file (MDM) and team hooks (Cursor's dashboard, Enterprise) run in every workspace, alongside user and project hooks. Cursor merges every hook's answer and a deny from any of them wins, but nothing stops other hooks from running too, so `doctor` scores this as partial. ## What the adapter maps [#what-the-adapter-maps] | Cursor step | Firewall | | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `preToolUse` | The decision, for every local tool (its deny is enforced; `ask` is ignored by Cursor) | | `preToolUse` for `MCP:` | Deferred: it carries no server, so `beforeMCPExecution` decides | | `beforeMCPExecution` | The decision for an MCP call, named by the server's `mcp.json` key | | `postToolUse`, `afterMCPExecution` | Taint, private data and fingerprints from the output | | `beforeReadFile` | Runs after a read and before the model sees it: the content is recorded like a tool's output; always allowed (the read was decided at `preToolUse`) | | `beforeSubmitPrompt` | Destinations you named, and the task's scope | | `sessionStart` | The session-start agent-configuration scan and MCP comparison | | `subagentStart` and `subagentStop` | Linkage: the subagent starts with the parent's state and hands its taint back | | `beforeShellExecution`, `afterShellExecution` | Understood, not registered (`preToolUse` and `postToolUse` cover the shell; registering both would decide every command twice) | | `afterFileEdit`, `postToolUseFailure`, `stop`, `preCompact`, `afterAgentResponse`, `afterAgentThought`, `sessionEnd`, Tab and `workspaceOpen` steps | Ignored | | Cursor tool | Judged as | | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | `Shell` | A shell command (in `cwd` when it differs from the session's) | | `Read`, `ReadLints` | A read | | `Write` (every edit carries the whole new file) | A write, with settings files checked on the exact result. A `Write` without its text is held, never taken as an empty file | | `Delete` | A removal | | `Grep`, `List` | A search and a listing | | `Fetch` (and `WebFetch`) | A web fetch | | `WebSearch`, `Task`, `updateTodos` or `TodoWrite`, `createPlan`, `askQuestion` | Server-side tools, names taken from Cursor's docs and tool kinds, not seen in a hook event | | `ListMcpResources`, `FetchMcpResource` | MCP resource calls, plus a write of unknown content to `download_path` | | `WriteShellStdin`, `ComputerUse`, `RecordScreen`, anything else | An unknown tool: held for a person (`FW-UNKNOWN-TOOL`); the hook input does not say what is typed, clicked or recorded | ## Output protocol (read from source) [#output-protocol-read-from-source] * Permission steps (`preToolUse`, `beforeMCPExecution`, `beforeReadFile`, `subagentStart`) get an allow or a deny with a user message and an agent message; exit 0. * `beforeSubmitPrompt` gets `{"continue":true}`; `postToolUse` and `sessionStart` may get additional context, kept under Cursor's 10,000 characters. * Exit 2 blocks. With `failClosed: true`, any other failure blocks too. * No step lets the firewall ask you (`preToolUse` and `beforeMCPExecution` act only on deny), so an action that needs a person is held in the queue and the agent gets the `launchsafe-firewall queue approve ` command. ## Cursor runs the Claude Code hooks too [#cursor-runs-the-claude-code-hooks-too] With "Include Third-Party Plugins, Skills, and Other Configs" on (the default), Cursor loads the hooks in `~/.claude/settings.json` and a trusted project's `.claude/settings*.json`, and sends them its own payload. The firewall's Claude Code hook recognises any event carrying `cursor_version` and routes it to the Cursor adapter. * When the firewall's Cursor hook runs for that step (registered, fail-closed, in `~/.cursor/hooks.json` or the enterprise file, in a file Cursor accepts), the imported hook says allow and records nothing, so nothing is decided or counted twice. * Otherwise it decides in full. An MCP call there has no server and is judged as a call to an unknown server; `doctor` recommends `install --agent cursor`. ## Unattended runs [#unattended-runs] A background agent (when the event carries `is_background_agent: true`), `cursor-agent -p` or `--force` or `--yolo` in the process ancestry, and `approvalMode: "unrestricted"` in `~/.cursor/cli-config.json` count as unattended: held actions wait in the queue, and the message says nobody was there. ## What its hooks cannot do [#what-its-hooks-cannot-do] * **Cloud agents** run only the repository's `.cursor/hooks.json` (not yours), and a project install's local paths do not exist there. * **Tab completions** are your own edits; the firewall only observes them. **Typed shell input** (`WriteShellStdin`), **computer use** and **screen recording** carry nothing the firewall can judge, so they are held. * **No `ConfigChange` step:** a change to `hooks.json` is judged when the agent makes it through a tool, not when something else edits the file. * Secrets in tool output are not redacted (Cursor can replace only an MCP tool's output). * For what hooks cannot see, run Cursor's own sandbox (`sandbox.mode: "enabled"` in `cli-config.json`; `doctor` warns when it is off) and an egress proxy. # Gemini CLI (/agent-firewall/agents/gemini) The Gemini CLI adapter translates Gemini CLI's hook events to the firewall's normalized actions and its answers back. The policy is the same engine Claude Code uses; nothing about what is allowed differs by agent. Tested with Gemini CLI 0.63.0. Every event shape was captured live against a local mock model that answered with scripted tool calls. No real account or key was used. ## Install [#install] ```sh launchsafe-firewall install --agent gemini # ~/.gemini/settings.json launchsafe-firewall install --agent gemini --scope project # /.gemini/settings.json launchsafe-firewall doctor ``` `install` adds one command hook per event, first in each list, keeps every other key and hook, sets `hooksConfig.enabled: true`, saves the original file under `~/.launchsafe-firewall/backups/` and records the install. Running it again changes nothing. `uninstall --agent gemini` removes exactly the firewall's entries (and the `hooksConfig.enabled` flag when install was the one that added it); `--restore-backup` puts the file back as it was, after saving the current file as `settings.json.before-restore.TIMESTAMP`. Gemini CLI's hook timeouts are in milliseconds. Hooks need no feature flag in 0.63.0. Two things Gemini CLI does weaken any hook, and `doctor` reports them: * **Folder trust.** In a folder Gemini CLI does not trust it skips every hook, yours and the system's included. A headless run in an untrusted folder exits 55 unless given `--skip-trust`. Trust the folders you work in. * **A repository can switch your hooks off.** A project `.gemini/settings.json` with `"hooksConfig": {"enabled": false}`, or a `disabled` list naming the firewall's hook (`launchsafe-firewall`), turned off user-level hooks silently (captured). `doctor` fails on it, and the agent writing it is denied (`FW-TAMPER`). ### Managed deployment [#managed-deployment] ```sh launchsafe-firewall install --managed --agent gemini --print | sudo tee "/Library/Application Support/GeminiCli/settings.json" # Linux: /etc/gemini-cli/settings.json ``` System settings override user and project settings, but Gemini CLI skips the file unless its directory is owned by root. `doctor` checks the owner. `GEMINI_CLI_SYSTEM_SETTINGS_PATH` moves it. Gemini CLI has no administrator control that stops a user from adding further hooks, so `doctor` scores this as partial. ## What the adapter maps [#what-the-adapter-maps] | Gemini CLI event | Firewall | | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | `BeforeTool` | The decision | | `AfterTool` | Taint, private data and fingerprints from the output | | `BeforeAgent` (carries the prompt) | Destinations you named | | `SessionStart` | The session-start agent-configuration scan | | `SessionEnd`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `PreCompress`, `Notification` | Ignored (the firewall judges actions, not text) | | Gemini CLI tool | Judged as | | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `run_shell_command` | A shell command (in `dir_path` when it is not `.`) | | `read_file` | A read | | `read_many_files` (older versions) | One read per path; a glob is a recursive read of its base directory | | `write_file` | A write (result-checked for settings files) | | `replace` | An edit (`allow_multiple` replaces every match). Gemini CLI matches `old_string` flexibly and can correct it from `instruction`; that was not captured, so the result is judged at every place the text could match, and as the worst case when it matches nowhere | | `list_directory`, `glob`, `grep_search` | A listing, a glob and a search | | `web_fetch` | One fetch per URL in the prompt, taken as Gemini CLI takes it: split on whitespace, each URL the whole token, brackets and quotes included. No URL is a parse failure (a person decides) | | `google_web_search` | A web search | | `save_memory` (older versions) | A write to `~/.gemini/GEMINI.md`: allowed in a clean session, held as a proposal once untrusted | | `write_todos`, `update_topic`, `invoke_agent`, `activate_skill`, `list_background_processes`, `read_background_output` | Safe (the agent talking to itself; a subagent's own tool calls are judged one by one) | | MCP tools (`mcp__`) | `mcp____`; the server's source (system, project or user settings) decides its trust | | Anything else | An unknown tool: held for a person (`FW-UNKNOWN-TOOL`) | ## Gemini CLI's own sandbox (`gemini -s`, macOS) [#gemini-clis-own-sandbox-gemini--s-macos] `-s` re-runs the whole CLI under `sandbox-exec` with one profile, and every process it starts inherits it: the firewall's hook and the agent's own tools run in the same sandbox. Gemini CLI's built-in profiles never let a process write `~/.gemini`. With the firewall installed and nothing else, every hook fails to save its state, so every non-read action is blocked (captured: 5 of 5 shell commands blocked, reads allowed). The hook says so in one message naming the fix. The firewall's answer is a custom profile: ```sh launchsafe-firewall install --agent gemini --seatbelt permissive-open export SEATBELT_PROFILE=launchsafe # in your shell profile gemini -s ``` `--seatbelt BASE` writes `~/.gemini/sandbox-macos-launchsafe.sb`: Gemini CLI's own base profile, copied unchanged from the installed Gemini CLI (found from `gemini` on PATH, or `--gemini-package DIR`), plus one block that lets a process write the hook's state directories (`sessions`, `queue`, `log`, `locks`, `ledger`, `pins`, `quarantine`, `scan/receipts`, `scan/last`) and nothing else. Re-run the command after updating Gemini CLI. Why only those directories: whatever the profile lets the hook write, the agent's commands can write too. Every command is still judged first, exactly as without `-s`. With the firewall's profile, a command the analyser cannot see through got an error for `policy.json`, `keys/`, `install.json`, `identity.json`, `backups/`, `canaries.json`, the profile itself and `~/.gemini/settings.json`, and could write only `sessions/` and `queue/`. So under `-s` the policy, keys, install records, backups, vault and decoy registry have the OS's protection on top of the analyser's; the hook's state has the analyser's alone, as everywhere. Not covered: `mcp wrap` started by Gemini CLI inside `-s`, the vault inside `-s` (references in Gemini CLI shell commands are refused anyway), desktop notifications from inside the sandbox (not verified), and Gemini CLI's container sandboxes (Docker, Podman: not tested). ## Output protocol (observed) [#output-protocol-observed] * `BeforeTool` blocks with `{"decision": "deny", "reason": "..."}` on stdout (exit 0), or exit 2 with text on stderr. * Exit 2 with empty stderr, any other exit code, a crash and a timeout let the tool run. The wrapper prints a line before `exit 2`, so a failure of the firewall or of Node blocks. A timeout (30 s) still fails open. * Gemini CLI's hooks cannot put a question to you in a way the firewall can use, so an action that needs a person is held in the queue and the agent is told the exact `launchsafe-firewall queue approve ` command. ## What its hooks cannot do [#what-its-hooks-cannot-do] * No `ConfigChange` event: a change to `settings.json` is judged only when the agent makes it through a tool, not when something else edits the file mid-session. * Secrets in tool output are not redacted. * Subagents (`invoke_agent`) are not reported as sessions; their tool calls arrive with the parent's `session_id`, so their taint is the session's. * A tool call Gemini CLI rejects before the hook never reaches the firewall, and never runs either. * Unattended runs (`gemini -p`, `--yolo`, `--approval-mode yolo`) are detected from the process command line only, because Gemini CLI tells its hooks nothing about its mode. The firewall reads it with `ps`, up to four ancestors, and falls back to `pgrep` on macOS where a seatbelt sandbox forbids `ps`. When neither can run, the session is treated as unattended. Another agent starting `gemini --yolo` is also caught by `FW-AGENT-BYPASS`. # How it works (/agent-firewall/concepts/how-it-works) ## The principle [#the-principle] The firewall never tries to detect malicious text with a model. An agent can always be fooled by cleverly written content. So the firewall does not guess intent: it watches the actions the agent takes and the data that moves, and enforces rules on those, deterministically, outside the model. The well-known failure mode is the lethal trifecta (Simon Willison): an agent that at once has access to private data, can be reached by untrusted content, and has a way to communicate externally can be tricked into sending the private data to an attacker, using only words placed in an email, a web page, a GitHub issue, a support ticket or an MCP tool's description. The fix has to sit outside the model and constrain what the agent can do. The firewall breaks the external-communication leg mechanically: once a session has been exposed to untrusted content, every external communication, and every other damaging action class, needs a person. ## Shape [#shape] ```text Claude Code, Codex, Gemini CLI, Cursor | hook event (JSON on stdin) v adapter (one per agent: parse, normalize, render; translation only) | normalized action + context + session state v policy engine (pure, no I/O) classify -> effects, shell parser, paths, network, secrets, personal data, SQL, then the rule table | decision (verdict, reasons, rules, events) v runtime (state, queue, log, policy, install: locked, atomic) ``` The engine is agent-agnostic. Each agent is an adapter that translates its hook format to and from the engine's types, so no engine code changes per agent. The same interface serves agents you build yourself through the [library](/agent-firewall/features/library-sdk). ## The decision pipeline [#the-decision-pipeline] 1. **Classify** the action into effects: concrete things it does, such as reading outside content, sending data, writing a protected file or destroying data. Built-in tools (`Read`, `Write`, `Edit`, `Bash`, `WebFetch`) have explicit models. MCP tools are classified by the server's trust and the tool's verb. A tool the firewall has never seen is marked unknown: its string arguments are scanned for paths and URLs, it asks in any session (queued when unattended), and its result counts as outside content. 2. **Findings** record hard facts independent of state (a capture host, a DNS-exfiltration shape, a secret flow, hidden Unicode, a parse failure). 3. **Rules** turn effects and findings into outcomes. The most severe wins: * `deny`: always-on protections (data loss, self-tamper, destroying the root, capture hosts, metadata endpoints, hidden text) and, in an untrusted session, the worst flows such as download-and-run. * `hold`: a change to the agent's instructions or memory, or to a git hook or an auto-run file, in an untrusted session. It becomes a queued proposal, never applied by the agent. * `approve`: needs a person. It becomes an ask when someone is there and a queue item when not. * `allow`: passes straight through to the agent's own permission rules. The firewall only ever restricts. 4. **Events** are the state changes an allowed or asked action records. They only ever make the session stricter. Taint never clears. On an internal error, risky action classes fail closed (blocked) and read-only ones fail open, so a bug degrades to "annoying", never to "wide open". ## Trust state [#trust-state] A session starts trusted. It becomes untrusted when the agent takes in outside content: * a web fetch or search, through the WebFetch and WebSearch tools or through the shell (`curl`, `wget`, `npm view`, `ssh` output, a URL fetched by inline code); * a result from an MCP server that carries outsider-written text (email, chat, issues, tickets, a browser); * a file outside the workspace, or a downloaded file (including one a fetch wrote with `>` or `tee`). The firewall records what tainted the session. Showing you something is not reading outside content: when the agent sends you a file, sets a chapter marker or proposes a new session, the session stays trusted. Files the agent wrote itself are not outside content: a provenance ledger remembers the hash of what each session wrote, so reading back notes the agent left outside the workspace keeps the session trusted, as long as nothing else has changed them. The other way round, a file an untrusted session wrote stays untrusted in later sessions: running it, a build that runs it (`npm test` after an untrusted session changed `package.json`), or an install that reads it (`npm ci` after it changed `package-lock.json`) needs a person. A session's state is a fold over an append-only event log. A corrupt or unreadable line makes the session untrusted and sensitive: degradation is always toward stricter. ### What counts as sending [#what-counts-as-sending] Sending is any egress payload: a request body or URL, a web-search query, and the arguments of every MCP tool call (a "read" tool still sends its arguments to the server). The always-on data rules inspect all of them. ## Four things this does that free hook packs do not [#four-things-this-does-that-free-hook-packs-do-not] 1. **A deterministic taint rule.** After outside content, anything that could cause damage needs a person: sending data off the machine, sending a message, changing the agent's own instructions or memory, reading a credential store, handing private text to a third-party tool, running a build or task file it changed after reading that content. Before that, normal local work is untouched. 2. **An unattended queue with batch review.** When no one is at the keyboard (a `claude -p` run, CI, or configured hours), an action that would ask is queued with a plain-language reason. You review the queue later with `launchsafe-firewall queue review` (one passphrase for the whole batch), and an approval lets that exact action run once. 3. **Protected memory with proposed changes.** In an untrusted session, a write to the agent's instructions or memory (`CLAUDE.md`, `AGENTS.md`, `MEMORY.md`, `.claude/**`, and any file `CLAUDE.md` imports with `@path`, up to five imports deep) is never applied. It is held as a proposal for you to read and accept. The same goes for files that make code run later without anyone asking: a git hook or hook-manager file, an editor task that runs on its own, a dev-container lifecycle command. In a trusted session these files stay editable, but a change that adds a way for code to run by itself (a task that runs when the folder opens, a `pull_request_target` workflow that checks out the pull request's code, a hook that downloads and runs a script, a different package registry, an agent's own auto-approval switched on) asks first (`FW-AUTORUN`). 4. **Self-protection in two independent layers**, described below. ## Always on, trusted or not [#always-on-trusted-or-not] Two protections never depend on trust state and can never be approved from inside the agent. * **No credentials or sensitive personal data leave for the wrong place.** An outbound payload carrying an API key, token, private key, a checksum-valid card number, an IBAN, or a national-ID format is denied unless the destination is explicitly allowlisted for that kind of data. "Outbound" covers network commands, WebFetch URLs, web-search queries and the arguments of every MCP tool call. Secrets the session has already read are remembered as fingerprints and caught again, including when re-encoded (see [Limitations](/agent-firewall/security/limitations) for the exact encodings). Published test values (Stripe and other processors' test cards, ISO example IBANs, specimen SSNs, `sk_test_` keys) are let through (`allowTestValues`, on by default). * **The firewall protects itself.** Budgets are always on too, but they only ask, never block: every session has an outbound budget (once untrusted, 64 KB per host and 256 KB in total; trusted, 4 MB), a request budget per host, a call budget per MCP server (and 20 sends or messages through one server in 10 minutes once untrusted), and loop detection (the same command 8 times in 10 minutes with no file changed in between). Reaching one asks you once, and your yes raises that budget for the session. Unattended, the action is queued and a notification says the agent seems stuck. Package installs and clones are not counted. Limits are in the `budgets` policy key. ## Self-protection [#self-protection] **What the agent's actions can do.** The firewall is identified by what is actually installed, never by what a file or folder is called: the CLI file the registered hook command runs, its package's `dist/`, `node_modules/` and `package.json`, the node binary the hook command names, and the data directory (`~/.launchsafe-firewall`, or `LAUNCHSAFE_FIREWALL_HOME`). Any tool call or shell command the firewall can analyse that writes, deletes or links over any of those, copies the data directory, edits the hook registration or `disableAllHooks`, stops the hook process, or runs the CLI to change anything, is denied and cannot be approved from inside the agent. That includes attempts through `npx`, a symlink, or hiding behind `sudo`, `env`, `nohup`, `timeout`, `xargs` or `bash -c`. Read-only subcommands (`status`, `doctor`, `queue list`, `log verify`) stay allowed, and so does ordinary work that only shares a name. A change to a Claude Code settings file is judged by the file it would produce: if the firewall's hook entries or their fail-closed wrapper would be removed, altered or moved, `disableAllHooks` turned on, or the file left unparseable, the change is denied, in any session. A settings change made through the shell cannot be checked that way, so it is denied; use the Write or Edit tool. **What counts as an approval.** Approving a held action and uninstalling need an approval passphrase you set in your own terminal; the agent never sees it. It unlocks an Ed25519 key that signs each approval, and the hook honours only approvals that verify against the key pinned in the hook command in the agent's settings. So even a command the analyser cannot see into cannot produce an approval the hook accepts. A forged or unsigned approval is ignored and makes the session untrusted. The CLI additionally refuses to run state-changing commands without a real terminal or as a descendant of a Claude Code session. Everything the CLI prints, and every reason the hook gives, shows terminal control characters as visible escapes, so text an agent or a repository wrote cannot rewrite or hide lines on the approval screen. Only managed settings make the hook registration itself unwritable to processes the firewall cannot see. ## Checks what the agent is armed with [#checks-what-the-agent-is-armed-with] At session start the firewall reads the files that program the agent (`CLAUDE.md` and `AGENTS.md`, `.claude/` settings, hooks, skills, agents and commands, MCP server lists, Cursor, VS Code, Codex and Gemini config, agent memory, and the files `CLAUDE.md` imports), in the workspace and in your home, and runs LaunchSafe's agent-safety rules on them, the same rules LaunchSafe's scans and free checker use. A critical finding (hidden instructions, a hook that runs a download, a model endpoint moved to someone else's server) makes the session start untrusted, and you are told why. A hook or MCP server added or changed since your last session also makes the session start untrusted, and so does a workspace with more agent files than the bounded scan reads (400 files, 8 MB in all, 300 ms), since a file past the limit could hide behind filler. The scan is static and bounded. It never runs or contacts what it reads, and a clean result is not proof a skill is benign. ### MCP pins [#mcp-pins] Each MCP server is pinned. A changed launch command, a changed tool description the firewall sees, or a tool not seen before on a server whose tools could have changed marks the session untrusted until you review it with `launchsafe-firewall pins` and accept it with `launchsafe-firewall pins accept `. A hook never sees an MCP server's full tool list, so without the [MCP gateway](/agent-firewall/features/mcp-gateway) description pinning covers only what Claude Code shows through its ToolSearch tool. A server whose configuration source is the repository is untrusted whatever it is called, unless your own policy lists it by exact name. ## Decoys (canary files) [#decoys-canary-files] You can plant a few decoy files that look like credentials or private notes and that no real task needs. `launchsafe-firewall canary plant` creates `.env.backup` and `config/credentials.old.json` in the project (add `--home` for `~/.aws/credentials.bak`, `~/.ssh/id_ed25519_old` and `~/.config/gh/hosts.yml.bak`). Each holds a credential-shaped value that is valid with no provider. The files are mode 600 and listed in `.git/info/exclude`, so `git add -A` does not commit them. Nothing is planted unless you run the command. If an agent reads one directly, the read is allowed (blocking would show which file is the decoy) unless another rule holds it. Whatever the verdict, the session turns untrusted and sensitive, an alert is logged and notified, and every later send in it needs you. If a decoy's value appears in outbound data it is denied to every destination, with no allowlist (`FW-CANARY-EGRESS`). Decoys are local: no network calls, no remote tokens. List with `canary list`, remove with `canary remove --all`. ## Task scope [#task-scope] Your prompt says what the task is about. The firewall records the workspace paths, repositories and hosts it names and whether it asks to push, open a PR, publish, deploy, send, delete or install, and uses that to narrow what a fooled or unattended session may do on its own. It only narrows; it never loosens a rule. Scope runs in log mode by default (`taskScope.mode: "log"`): it records what it would have asked (`status` counts them, `explain ` shows each) and changes no decision. Set `"enforce"` to apply it. `scope show` prints a session's scope, and `scope widen` widens it with your passphrase. ## Package checks [#package-checks] Every install and package runner (`npm`, `pnpm`, `yarn`, `bun`, `npx`, `pip`, `uv`, `cargo`, `gem`, `go`, `composer` and more) gets three offline checks, trusted or not: * **Known-malicious versions are denied** (`FW-MALICIOUS-PACKAGE`). A local snapshot of OSV's malicious-package advisories is checked for each named package, and for installs from a lockfile for every `name@version` the lockfile pins. Refresh the snapshot yourself with `launchsafe-firewall update`; `doctor` warns when it is missing or more than a week old. * **Typosquats need a person** (`FW-TYPOSQUAT`): a name one or two letters from a popular package, the same with different separators or look-alike characters, with a scope added or dropped, or with a `-js` or `python-` style affix, and not itself a known package. * **`doctor` checks release-age cooldowns** (pnpm `minimumReleaseAge`, Yarn `npmMinimalAgeGate`, Bun `install.minimumReleaseAge`, uv `exclude-newer`), and `doctor --fix` can write a three-day cooldown into your user-level config after showing the diff. npm and pip have no rolling cooldown; `doctor` says so. ## The shell parser [#the-shell-parser] String-matching a command is how hook tools get bypassed. The parser recovers structure instead: quoting (single, double, ANSI-C), command and process substitution, subshells and groups, pipelines, redirections and here-documents. It resolves wrappers (`sudo`, `env`, `timeout`, `xargs`, `nohup`) and nested shells (`bash -c`, `eval`, `find -exec`) to the real program, models about 150 programs for what they read, write, send and run, tracks the working directory across `cd` and the common directory flags, and judges inline interpreter code per language. Anything it cannot resolve (a computed command name, an unparseable fragment, a variable write target) is treated as risky and sent to a person. ## The decision log [#the-decision-log] Every decision is written to a JSON-lines log, each entry chained to the previous by SHA-256 and signed with a local Ed25519 key. `launchsafe-firewall log verify` checks every link, hash, signature and sequence number, so an edited, reordered or truncated log is detected. State, queue and log writes are locked and atomic, so several sessions and subagents can run hooks at once. Corrupt state, policy or log files are surfaced by `doctor` and never silently treated as "allow". If the log cannot record an allowed action, an allow becomes an ask, or a deny when no one is there (`FW-LOG-UNRECORDED`). An I/O failure such as a full disk is different: the decision stands and the error goes to the hook's stderr, because blocking every tool, including the reads needed to free space, would leave you with an agent that cannot help. ## Failure policy [#failure-policy] * Bad or unreadable hook input exits 2, which blocks the tool. * A decision error is a deny for a risky tool and an allow for a read-only tool. * The installed command ends in `|| exit 2`, so a crash of Node itself blocks. * A `PostToolUse` error marks the session untrusted rather than losing what the tool brought in. ## Policy precedence [#policy-precedence] Built-in safe defaults, then the administrator's managed policy and the user's policy (either may loosen or tighten), then the project's own `.launchsafe-firewall.json`, which may only tighten, because a repository is untrusted content. See [Policy](/agent-firewall/features/policy). # Dashboard (/agent-firewall/features/dashboard) `launchsafe-firewall ui` opens a read-only web view of what the firewall knows, for you: the morning queue with proposed changes as a side-by-side diff, the decision log with an explanation for every entry, the sessions and why each is or is not trusted, the protection score, MCP pins and decoys. It runs on this machine only, for as long as the command runs, and it never approves anything. ```sh launchsafe-firewall ui # prints a private address, opens it in your browser launchsafe-firewall ui --no-open # prints the address only launchsafe-firewall ui --project ~/code/app # doctor's project-level checks for that project ``` Zero new dependencies: Node's `http` module, server-rendered HTML, one small script for the copy buttons, no build step. ## Screens [#screens] | Screen | What it shows | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Overview | One focal point: how many actions are held for you, with one "Review queue" action (or "Nothing needs you"); one line each for protection (score and how many things to improve), the last decisions and unattended mode; recent sessions as rows (status, id, one-line reason) | | Protection | The score, the checks to improve first (each expands to `doctor`'s detail), passing checks behind a disclosure, where the firewall is installed | | Session | Trusted or not, everything that made it untrusted, its logged decisions | | Queue | One row per held action (100 a page, oldest first): what, why in a few words, when, Review | | Queue item | Title, one line of facts, the rule's sentence, the exact approve, reject and show commands, then the change as a side-by-side diff against the file as it is now (a unified diff on a phone) or the masked input; rules, trust sources and every reason behind a disclosure | | Decision log | A dense table newest first, 100 a page, a segmented filter by verdict or type, and whether `log verify` passes | | Log entry | `explain ` for that entry; the raw signed entry behind a disclosure | | Pins and decoys | Pin changes waiting for review with the accept command, pinned servers (another agent's under its name), planted decoys (present or missing), sessions that touched a decoy | | Vault | Each stored secret as its reference (`vault://`), kind, fields, store and where its value may go; whether the index verifies against the approval key; the `vault add` and `vault allow` commands to run in the terminal. Never a value or a fingerprint | | Gateway and mail | The MCP servers behind the gateway (client, mode, transport); every withheld item from the one quarantine store (an MCP result by tool and server, a message by sender and subject) with its signals, status and age, never the withheld text or its preview; paired phones by label and the relay's state, never keys or credential ids; whether `run` can sandbox agents here | Every screen draws on the same code the CLI uses, so the two never disagree. Paths in lists are shown relative to the project or as `~/...`, cut in the middle when long, with the full path in the tooltip. Every page is computed when it is requested; reloading shows the current state. `doctor`'s checks are cached for 60 seconds because they start `claude --version` and the other agents' version probes. The look is the LaunchSafe product look (Onest, ink on a plain canvas, hairline rows, light and dark from the OS setting). The accent colour marks only something held or found: pending queue items, pending MCP pin changes, a tripped decoy. `doctor`'s statuses use a dot and a word (ok, warning, failing), never colour alone. The Onest font (SIL OFL 1.1) is embedded in the package and served by the dashboard itself. ## What it must not become [#what-it-must-not-become] The dashboard adds a listening socket to a machine where an agent runs commands as the same user, a browser that visits untrusted pages, and text the agent or a repository wrote. So it must not be: 1. **A way to approve, reject or widen anything without you.** The firewall's human channel is the approval passphrase typed in your own terminal. A web endpoint that changed the queue would be a new side door, reachable by anything that can send an HTTP request to 127.0.0.1. 2. **A way for the agent to read what it otherwise could not.** The data shown is what `status`, `queue`, `log`, `pins`, `canary list` and `explain` already print, and those read-only commands are allowed to the agent today. The dashboard shows no more: no keys, no approver file, no decoy values, no session secret fingerprints, no input that was masked at enqueue. 3. **A target for a web page.** A page you visit can make the browser send requests to `127.0.0.1:` (cross-site requests, DNS rebinding). 4. **An injection surface.** Queue reasons, summaries, proposal content, MCP launch lines and log entries are agent- or repository-written. Rendered as HTML they could run script or make a line read differently from what it holds. 5. **A source of network traffic.** The firewall makes no network calls except `update`; the dashboard must not load fonts, scripts or images from anywhere. ## Security design [#security-design] **Read-only, always.** The server answers `GET` and `HEAD` only; every other method is `405`, and there are no CORS headers, so a preflight never succeeds. No handler calls anything that writes the queue, session state, pins, decoys, policy, settings or the log. A test fingerprints the firewall's authoritative files before and after requesting every page and requires them unchanged. **A stored value is never shown.** Every page renders with the vault's view (names and fingerprints, read on the server and never sent): any line of text that contains a stored value, in the clear or encoded, is replaced by "\[hidden: this contains the value of vault://name]". **Approving stays in the terminal.** Each held item and each pending pin change shows the exact command (`launchsafe-firewall queue approve `, `queue reject `, `pins accept `) with a copy button. You run it in your own terminal, which asks for the passphrase there. A passphrase field in the browser was decided against: it would teach you to type the passphrase into a web page (an agent can start its own server on another local port and draw a perfect copy of the dashboard; the terminal prompt is a place the agent cannot draw), the browser's process, extensions and autofill are outside the firewall's control, and a write endpoint, however guarded, is a state-changing request reachable by any local process that obtains the token. **A per-launch token in every URL.** `ui` generates 32 random bytes (256 bits) when it starts. Every path is under `//`; a request without it, or with a wrong one, gets the same `404` as an unknown path (compared in constant time). The token lives only in the process's memory and in the line printed once to your terminal; it is never written to a file, a log entry, an environment variable or a command line. Stopping `ui` (Ctrl-C, a closed terminal, or 30 minutes without a request) makes every old address dead. **Lifetime.** Only a request that passed the Host, Origin, method and token checks restarts the 30-minute idle clock. `ui` is tied to the terminal that started it: it stops on SIGINT, SIGTERM and SIGHUP, and it polls its parent process every two seconds and stops when the parent changes. **Bounded pages.** The queue list is 100 held items a page. The log screens do not parse the log per request: each log file is scanned once into a small index, cached together with the `log verify` result and keyed by every file that makes up the log, so an append, rotation or edit rebuilds the index on the next request. Every field a page renders is cut to 2,000 characters with a visible "truncated" note, a tool input shows at most 50 keys or items per object, and a block is cut at 100,000 characters. **Opening the browser without putting the token on a command line.** A command line is visible to every process of yours (`ps`). So `ui` opens a one-time launch address (a separate 128-bit code, valid once and for 60 seconds), which redirects to the token address. On macOS the browser is opened by `/usr/bin/osascript` with the script on standard input; on Linux by `xdg-open` from `/usr/bin`, `/usr/local/bin` or `/bin` only, root-owned and not writable by anyone else. If the code was used already, the browser shows "This launch address was already used", which tells you to stop and restart. `--no-open` skips this. **Host, Origin and fetch-metadata checks.** The server listens on `127.0.0.1` only, on a random port. Before anything else every request must have: * `Host` exactly `127.0.0.1:`. A rebinding page's requests carry its own hostname and are refused (`421`). `localhost` is refused too. * No `Origin`, or exactly `http://127.0.0.1:` (`null` and other origins: `403`). * No `Sec-Fetch-Site`, or `none` or `same-origin`. `cross-site` and `same-site` are refused (`403`); every port on 127.0.0.1 is the same site, so another local web app (including one the agent started) is refused as well. **Content Security Policy and headers.** Every response carries a policy that allows only the dashboard's own style, script, font and image, no connections, no forms and no framing, plus `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer` (the token never leaves in a `Referer`), `Cache-Control: no-store`, `X-Frame-Options: DENY`, cross-origin isolation headers and a `Permissions-Policy` that turns off every powerful feature. No inline script or style exists. Pages contain no forms that submit anywhere and no external URLs. **Escaping.** Every value is rendered through one escaping template: `&`, `<`, `>`, `"` and `'` become entities, and control characters, DEL, bidirectional overrides and zero-width characters become visible `\uXXXX` escapes (the same escaping the terminal output uses), so a reason cannot hide or reorder text on the review screen. Links are built from validated identifiers and URL-encoded. **Who may start it.** `ui` is declared state-changing, so the firewall denies it when the agent runs it (`FW-TAMPER`, like `queue approve`), however it is reached, and the command itself refuses to start without a real terminal or as a descendant of a Claude Code session. The token is printed to whoever starts it: started by the agent, the agent would hold the token and could also open your browser at a page of its choosing. Nothing is lost: the agent can already run the read-only commands the dashboard draws from. ## Residual risks [#residual-risks] * A process running as the same user can read the browser's history, where the token address is stored, and can read a terminal pane that an agent is allowed to read (some desktop apps give the agent your terminal panel: run `ui` in a terminal the agent cannot see). What it gains is the read-only view: the same data the read-only commands print. It cannot approve anything: that needs the passphrase in the terminal, and the hook accepts only approvals signed with the key pinned in the hook command. * The dashboard is as current as the moment the page was rendered; it does not push updates. * `doctor`'s checks run in the dashboard's process with your environment, exactly as `doctor` would. # Email guard (/agent-firewall/features/email-guard) Mail is where outsiders write text your agent reads. A message can carry instructions a person never sees: Unicode tag characters, a `font-size:0` span, white-on-white text, an off-screen block with an image that leaks the conversation. The email guard scans every message a mail tool hands your agent before the model reads it, withholds the ones that carry hidden instructions, strips hidden padding from the rest, and keeps a record for you to review. It is deterministic and never uses a model. It sits in front of the existing taint rule: a mail server's results already make the session untrusted, so even a message the guard misses cannot make the agent send data out without you. The hosted Microsoft 365 guard and Gmail verification are not part of this release. Mailbox-side quarantine, when it is built, starts log-only. ## What is built [#what-is-built] | Part | Status | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | | Message parser: RFC 5322 headers, RFC 2047 encoded words, RFC 2231 parameters, multipart nesting to depth 10, quoted-printable and base64, charsets, forwarded `message/rfc822` parts, a 10 MiB cap; structured shapes (generic, Microsoft Graph, Gmail API payloads and raw) | Built | | Sender authentication as the provider reported it (SPF, DKIM, DMARC, ARC in `Authentication-Results`), sender notes | Built | | Detector: every text channel through the shared content scanner, one verdict per message | Built | | Read-path filter and message splitter (stubs, stripping, whole-result withholding) | Built | | Hooks integration for MCP mail tools: Claude Code, Codex, Gemini CLI, Cursor | Built | | Quarantine store and review CLI (`mail quarantine`, `release`, `discard`), `mail audit` over saved mail | Built | | Notification, `status` count, `doctor` check, `FW-MAIL-WITHHELD` | Built | | False-positive corpus and the `npm run mail-friction` gate | Built | | The filter inside the [MCP gateway](/agent-firewall/features/mcp-gateway) (every client, hooks or not) | Built | | Mailbox-side decision (log or enforce) | Decision built; moves not built | | `mail serve` (LaunchSafe's own read-only mail MCP server), mailbox quarantine (IMAP, Graph delegated), hosted Microsoft 365 guard, Gmail public app | Later | This build never sends or fetches mail. Everything runs on what a mail tool already returned to your agent, or on files you point `mail audit` at. ## How a message is judged [#how-a-message-is-judged] Every channel a model could read is scanned with the shared content scanner: the subject, the whole From header (decoded), Reply-To, the address headers (display names included), every other header and the MIME preamble and epilogue (no mail client displays these, but a model reading the raw source does), the provider's preview, text and HTML bodies (every alternative), calendar text, attachment names, and forwarded messages recursively. The signals are merged and one verdict is given: * **Withheld** (`quarantine`) when any of these fire (the `emailGuard.quarantineOn` names): * `tag_chars`: Unicode tag characters with readable text (a complete England, Scotland or Wales flag is an emoji, not smuggled text). * `hidden_instruction`: CSS-hidden text (not a copy of visible text) with a phrase addressed to an AI agent or an imperative such as "forward ... to". Styles are read as a browser reads them: CSS comments are dropped and CSS escapes decoded. Hiding counted includes `display:none`, `visibility:hidden`, the `hidden` attribute, `mso-hide:all`, a font under 1px, near-zero opacity, a box of 1px or less that clips its overflow, `transform: scale(0)`, large translations, zero clipping, off-screen positioning, text-indent, low contrast, Outlook-only conditional copies, `