Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 8 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[![CI](https://github.com/php/tamis/actions/workflows/ci.yml/badge.svg)](https://github.com/php/tamis/actions/workflows/ci.yml)

tamis does a first-pass triage of private vulnerability reports on GitHub. When a new security advisory arrives, an LLM agent investigates it against the repository and tamis puts the findings on a private project board, or posts them as a comment on the advisory with `comment: true`.
tamis does a first-pass triage of private vulnerability reports on GitHub. When a new security advisory arrives, an LLM agent investigates it against the repository and tamis puts the findings on a private project board.

For each report, tamis:

Expand All @@ -14,7 +14,7 @@ For each report, tamis:

The maintainers keep the decision. tamis only prepares it.

A comment looks like this, with the cited code, the policy check and the severity folded in a details block. [How it works](docs/how-it-works.md#the-comment) shows the full layout.
A triage looks like this on the board, with the cited code, the policy check and the severity folded in a details block. [How it works](docs/how-it-works.md#the-triage) shows the full layout.

```markdown
### Automated triage
Expand Down Expand Up @@ -68,20 +68,19 @@ flowchart LR
confirm -->|exact or not| tamis
reader & dup & confirm -.->|model requests| proxy
proxy --> provider
tamis -->|checked, escaped comment| adv
tamis -.->|board item| board
tamis -->|"checked, escaped triage"| board
tamis -->|complete result| art
```

## Before installing

GitHub cannot post confidential advisory comments yet, so with `comment: true` the reporter reads the comment. tamis also sends the report to the model provider you choose. Check that your disclosure policy allows both.
tamis sends the report to the model provider you choose. Check that your disclosure policy allows it.

## Quick start

`tamis init` runs these three steps for you, all but installing the App, as [the setup guide](docs/setup.md#setup-in-one-command) shows. By hand:

1. Create a GitHub App for your organisation with the "Repository security advisories" permission in read and write. Install it on the project repository only.
1. Create a GitHub App for your organisation with the "Repository security advisories" permission and the organisation "Projects" permission, both in read and write. Install it on the project repository only.
2. In a private repository, store the App's client ID and private key, and an Anthropic or OpenAI API key or a [Codex access token](docs/configuration.md#codex-access-token).
3. Add this workflow to the private repository:

Expand Down Expand Up @@ -132,8 +131,8 @@ jobs:
bot-login: your-app-slug[bot]
# List every branch your project supports. Each ref must exist in the checkout.
references: master origin/release-branch
# Without a project board, post the triage on the advisory instead.
comment: true
# The private board the triages go on, created with `tamis create-board your-org`.
project: your-org/NUMBER
```

Pin the commit of a [release](https://github.com/php/tamis/releases) tag, since the action then runs the attested binary of that release instead of building tamis from source. Set `since` to the installation date so tamis leaves existing advisories alone. Keep the workflow repository private, since the action uploads the reports there as artifacts kept for seven days. The [setup guide](docs/setup.md) covers source branches and provider spending limits.
Expand All @@ -144,7 +143,7 @@ Pin the commit of a [release](https://github.com/php/tamis/releases) tag, since
|---|---|
| [Setup](docs/setup.md) | GitHub App, private repository, secrets and first run |
| [Configuration](docs/configuration.md) | Inputs, budgets, project guidance and engines |
| [How it works](docs/how-it-works.md) | The triage pipeline and the comment it posts |
| [How it works](docs/how-it-works.md) | The triage pipeline and what it puts on the board |
| [Security](docs/security.md) | Threat model, isolation and known limits |
| [Development](docs/development.md) | Building, testing and running locally |

Expand Down
8 changes: 4 additions & 4 deletions action.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
name: Tamis Security
description: First-pass LLM triage of new GitHub security advisories, on a private project board or as an advisory comment.
description: First-pass LLM triage of new GitHub security advisories, on a private project board.
author: Alexandre Daubois
branding:
icon: shield
Expand Down Expand Up @@ -40,8 +40,8 @@ inputs:
description: Image the agent runs in, instead of the tamis agent image pinned by digest and checked against its build attestation. It needs the agent CLI, git, curl and harness-proxy, and is not checked.
required: false
project:
description: Private organisation project kept in sync with the triaged advisories, as `org/number`. The token needs the organisation "Projects" permission in read and write.
required: false
description: Required. Private organisation project the triages go on, as `org/number`. The token needs the organisation "Projects" permission in read and write.
required: true
issues-repository:
description: Private repository the board items are created in as issues, so duplicates become sub-issues of their original report. Drafts when unset. tamis refuses a public repository and the repository of the advisories. The token needs the "Issues" permission in read on it, `issues-token` writes the issues.
required: false
Expand All @@ -52,7 +52,7 @@ inputs:
description: Close the advisory of an issue a maintainer closed as a duplicate, credit its reporter on the original report and tell them on the closed advisory. Needs `issues-repository`.
default: "false"
comment:
description: Post the triage as a comment on the advisory, and with `issues-repository` the link to each issue tamis creates. Off by default, every triage then only reaches `project`, which must be set.
description: Post on each advisory the link to the issue tamis creates for it in `issues-repository`.
default: "false"
references:
description: Whitespace-separated local git references, including each supported release branch. The first is analysed, and the cited code is located on it. All must have been fetched.
Expand Down
13 changes: 5 additions & 8 deletions cmd/tamis/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,6 @@ func initProject(ctx context.Context, args []string, out io.Writer) error {
references := fs.String("references", "", "whitespace-separated git references of every supported branch, the analysed one first")
provider := fs.String("engine", "claude", "LLM provider, claude or openai")
appName := fs.String("app-name", "", `name of the GitHub App, "<org>-tamis" by default`)
withBoard := fs.Bool("board", false, "also create a private project board and fill it instead of commenting")
packs := fs.String("packs", "", "whitespace-separated guidance packs added to the agent's method, such as php-src")
err := fs.Parse(args)
if errors.Is(err, flag.ErrHelp) {
Expand All @@ -97,7 +96,7 @@ func initProject(ctx context.Context, args []string, out io.Writer) error {
org, _, _ := strings.Cut(*repository, "/")
refs := strings.Fields(*references)
if org == "" || len(refs) == 0 {
return errors.New("usage: tamis init -repository org/name -references \"main ...\" [-runner name] [-engine claude|openai] [-app-name name] [-board] [-packs \"php-src ...\"]")
return errors.New("usage: tamis init -repository org/name -references \"main ...\" [-runner name] [-engine claude|openai] [-app-name name] [-packs \"php-src ...\"]")
}
if len(refs) > 10 {
return errors.New("-references must list at most ten references")
Expand All @@ -120,7 +119,6 @@ func initProject(ctx context.Context, args []string, out io.Writer) error {
APIKey: apiKey,
AppName: cmp.Or(*appName, org+"-tamis"),
Since: time.Now().UTC().Format(time.DateOnly),
Board: *withBoard,
Packs: strings.Fields(*packs),
}
app := func(ctx context.Context, org string, manifest map[string]any) (string, error) {
Expand Down Expand Up @@ -173,20 +171,19 @@ func run(ctx context.Context, log *slog.Logger) error {
if err != nil {
return err
}
comment := false
if v := os.Getenv("COMMENT"); v != "" {
if comment, err = strconv.ParseBool(v); err != nil {
if cfg.Link, err = strconv.ParseBool(v); err != nil {
return fmt.Errorf("COMMENT: %w", err)
}
}
cfg.NoComment = !comment
if v := os.Getenv("FORCE"); v != "" {
if cfg.Force, err = strconv.ParseBool(v); err != nil {
return fmt.Errorf("FORCE: %w", err)
}
}
// Without comments, triaging the backlog only fills the private board, so every advisory in triage goes.
if since.IsZero() && cfg.Advisory == "" && comment {
// Without comments, triaging the backlog only fills the private board, so every advisory in triage goes. With
// them, each of those advisories would get a comment.
if since.IsZero() && cfg.Advisory == "" && cfg.Link {
return errors.New("SINCE is required with COMMENT unless ADVISORY is set, so that existing advisories are left alone")
}
cfg.Since = since
Expand Down
13 changes: 6 additions & 7 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,19 @@
| Input | Default | Description |
|---|---|---|
| `api-key` | | Required. API key of the model provider, or a Codex access token with `engine: openai`. |
| `github-token` | | Required. Token able to read and comment the repository advisories. |
| `github-token` | | Required. Token able to read and comment the repository advisories, and to write `project`. |
| `references` | | Required, at most ten. Whitespace-separated local git references, one per supported branch. tamis analyses the first and locates the cited code on it. A missing reference fails the analysis. |
| `packs` | | Whitespace-separated [guidance packs](#guidance-packs) added to the agent's method, such as `php-src`. An unknown pack fails the run. |
| `since` | | Triage only advisories created after this date, `2026-10-22` or RFC 3339. Required with `comment: true` unless `advisory` is set. Without it, every advisory in triage goes on the board. |
| `since` | | Triage only advisories created after this date, `2026-10-22` or RFC 3339. Required with `comment: true` unless `advisory` is set, so existing advisories get no comment. Without it, every advisory in triage goes on the board. |
| `advisory` | | Triage this GHSA only, whatever its state and creation date. |
| `bot-login` | Owner of the token | Login tamis posts as, such as `my-app[bot]`. Required with a GitHub App token. |
| `repository` | Current repository | Repository owning the advisories. |
| `path` | `.` | Path of the repository checkout, relative to the workspace. |
| `engine` | `claude` | `claude` for Claude Code and the Anthropic API, `openai` for Codex and the OpenAI API. |
| `model` | `claude-opus-5-5` or `gpt-5.5` | Model of the reader, the duplicate search and the exact confirmation. `gpt-6.1-sol` with a Codex access token. |
| `daybreak` | `false` | Turns on OpenAI's Daybreak cyber access program in Codex. Needs `engine: openai` and an API key whose organisation OpenAI approved for it. |
| `comment` | `false` | Post the triage as a comment on the advisory, and with `issues-repository` a comment linking each advisory to the issue tamis creates for it. Off, every triage only reaches `project`, which must then be set, and the board records the failed attempts in `Attempts`. |
| `project` | | Private organisation project kept in sync with the advisories, as `org/number`. See [the project board](setup.md#5-project-board). |
| `comment` | `false` | With `issues-repository`, post on each advisory a comment linking it to the issue tamis creates for it. |
| `project` | | Required. Private organisation project the triages go on, as `org/number`, which records the failed attempts in `Attempts`. See [the project board](setup.md#5-project-board). |
| `issues-repository` | | Private repository the board items are created in as issues, so duplicates become sub-issues of their original report. Drafts when unset. See [the project board](setup.md#5-project-board). |
| `issues-token` | | Installation token for `issues-repository` only, with the "Issues" and organisation "Projects" permissions in read and write. Required with `issues-repository`. |
| `close-duplicates` | `false` | Closes the advisory of an issue a maintainer closed as a duplicate. Needs `issues-repository`. See [the project board](setup.md#5-project-board). |
Expand All @@ -27,7 +27,7 @@ The action refuses to run from a public workflow repository or from a `uses:` th

Outside GitHub Actions, tamis reads the same settings from environment variables: `LLM_API_KEY`, `GH_TOKEN`, `BOT_LOGIN`, `REPOSITORY`, `REPO_PATH`, `SINCE`, `ADVISORY`, `ENGINE`, `MODEL`, `DAYBREAK`, `RUNNER_IMAGE`, `REFERENCES`, `PROJECT`, `ISSUES_REPOSITORY`, `ISSUES_TOKEN`, `CLOSE_DUPLICATES`, `COMMENT` and `PACKS`. `OUTPUT_DIR` must name a private directory for the reports. The action creates it in the runner's temporary storage and uploads it to the workflow repository with a seven-day retention.

A local run alone also reads `FORCE=true`, which triages every selected advisory again, `ADVISORY` alone or every one in triage, and updates its board item even when it already holds a triage. It needs `COMMENT` off, and a failed new triage leaves the previous one on the board. The action has no such input.
A local run alone also reads `FORCE=true`, which triages every selected advisory again, `ADVISORY` alone or every one in triage, and updates its board item even when it already holds a triage. A failed new triage leaves the previous one on the board. The action has no such input.

## Source branches

Expand All @@ -42,7 +42,6 @@ The private artifact holds, per advisory:
| File | Contents |
|---|---|
| `.md` | The full report, with every duplicate the global search proposed and any duplicate search or confirmation that could not complete |
| `.comment.md` | The text the reporter sees, limited to the published exact duplicates and to the unpublished exact duplicates that passed the [one-candidate confirmation](how-it-works.md#3-duplicate-search) |
| `.agent-error.txt` | Written when an agent run fails. It keeps the agent's error output and the error events of its JSON output, which may quote the report. |

Each report names the source commit and the input revision it covers.
Expand Down Expand Up @@ -86,7 +85,7 @@ The agent checks the report against the files that define what the project treat
1. `SECURITY` with a `.md`, `.markdown`, `.rst`, `.txt` or `.adoc` extension, in any case,
2. then `AGENTS.md` and `CLAUDE.md`.

The comment lists the files the agent checked. Without any of them, tamis leaves the section out.
The triage lists the files the agent checked. Without any of them, tamis leaves the section out.

## Engines

Expand Down
4 changes: 2 additions & 2 deletions docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,10 +79,10 @@ It needs the [Renovate GitHub App](https://github.com/apps/renovate) installed o
tamis reads its configuration from environment variables, so it runs on any machine with Docker. From a checkout of the target repository:

```bash
REPOSITORY=your-org/your-project REPO_PATH=. ADVISORY=GHSA-xxxx-xxxx-xxxx ENGINE=claude GH_TOKEN="$(gh auth token)" LLM_API_KEY="$ANTHROPIC_API_KEY" RUNNER_IMAGE=tamis-agent:claude REFERENCES=HEAD OUTPUT_DIR=/private/path/to/reports ./tamis
REPOSITORY=your-org/your-project REPO_PATH=. ADVISORY=GHSA-xxxx-xxxx-xxxx ENGINE=claude GH_TOKEN="$(gh auth token)" LLM_API_KEY="$ANTHROPIC_API_KEY" RUNNER_IMAGE=tamis-agent:claude REFERENCES=HEAD PROJECT=your-org/NUMBER OUTPUT_DIR=/private/path/to/reports ./tamis
```

tamis posts the comment for real. It skips an advisory that already has a completed comment from the configured bot, even after edits to the report or new followup comments.
tamis writes the board item for real. It skips an advisory whose item already holds a triage, even after edits to the report or new followup comments.

## Layout

Expand Down
Loading
Loading