# Reporting a vulnerability

> How to tell the maintainers about a suspected vulnerability in Reins, what to include, and how to tell a vulnerability from a documented limit.

## How to do it

Report a suspected vulnerability privately to the maintainers of the repository, not in a public issue. Include what you did, what happened and what you expected.

That is the whole policy as the [security model](../reference/security-model.md#reporting) states it. The repository is [offensiveadhd/reins](https://github.com/offensiveadhd/reins).

## What makes it useful

Reins gives an AI agent hands inside a web page, so the questions are always who the attacker is and what they gained. A message that answers them can be acted on quickly:

- **Who you were.** The security model names its attackers: another machine on the network, a web page in the person's browser, a local process, a manipulated agent, hostile page content, a kiosk visitor, someone editing the audit log.
- **What you did.** The frames you sent, or the page, or the commands. A proof against the running code is best: the reviews of version 0.1 gave most of their findings that way.
- **What happened, and what you expected.** Which numbered rule of [section 14 of the specification](../reference/specification.md#14-security-requirements), or which defence in the [threat table](../reference/security-model.md#threats-and-what-stops-them), did not hold.
- **The version**: the protocol version and the commit you tested.

## A vulnerability, or a known limit?

Read [What Reins does not protect against](../reference/security-model.md#what-reins-does-not-protect-against) first. It lists, among others:

- hostile script inside the app's own origin, which can also read and alter the chat;
- whoever holds an app's debugging connection, and an agent with `ui` in an adopted app;
- a person who chose `bypass`, and a standing rule that covers any arguments;
- a process running as the same OS user;
- a Reins folder that someone else can write;
- a surface key that the attacker can read;
- a page that chose to run inside a frame;
- a page with no key, in front of a fake hub;
- traffic confidentiality on loopback;
- a relay that withholds the tail of one direction;
- local denial of service;
- an audit log without a key or without an external head;
- a model that is talked into a bad but permitted action.

These are limits the project states on purpose. A way to turn one of them into something worse than the document says is worth sending in. So is a place where the code does not do what the specification says: the conformance suite marks the ones it knows with `it.fails` and a `SPEC MISMATCH` comment.

## What happens to a finding

The project's record so far is in the [Review](../reference/security-model.md#review) section of the security model: which parts were reviewed, what was found, what was changed, what is left as a stated limit, and which fixes have not been reviewed again. Fixes come with regression tests.

## Not a vulnerability?

A bug, a wrong page or a question belongs in an ordinary issue in the repository. See [Contributing](./contributing.md).
