Skip to content
Open
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
9 changes: 7 additions & 2 deletions docker/agent/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,16 @@ ARG CLAUDE_ARM64_LOCK=v2.1.319@sha256:2e7348ffc96d52ccb20e34c81240ebc92505edc84d
ARG CODEX_AMD64_LOCK=rust-v0.167.0@sha256:3bbf75e83de6b58aed28f2cf6e33ad423ec31fd4700a1457b94be557ea5a7c6e
ARG CODEX_ARM64_LOCK=rust-v0.167.0@sha256:0de261ecf1e7f3028a7952f03fca2093f749277d38590b78bb32f8567756bbb7
ARG HARNESS_VERSION=v0.1.21
ARG HARNESS_REPLACE=github.com/alexandre-daubois/harness@v0.1.12-0.20261116083615-135e53b30cb0

FROM golang:1.27.3-trixie@sha256:af1bfc2614ebb1dbd31af514b78740fd678850e76498762b425ecee4c5c6ea80 AS proxy
FROM golang:1.27.4-trixie@sha256:f18c3d73a184fb0582828510722e723b63a93f7188d11dd223d9be6f6880e65d AS proxy
ARG HARNESS_VERSION
ARG HARNESS_REPLACE
WORKDIR /build
# The egress proxy runs beside every untrusted agent container.
RUN GOBIN=/out CGO_ENABLED=0 go install -trimpath github.com/alpha-omega-security/harness/cmd/harness-proxy@${HARNESS_VERSION}
RUN go mod init tamis-agent-proxy \
&& go mod edit -require=github.com/alpha-omega-security/harness@${HARNESS_VERSION} -replace=github.com/alpha-omega-security/harness=${HARNESS_REPLACE} \
&& GOBIN=/out CGO_ENABLED=0 go install -mod=mod -trimpath github.com/alpha-omega-security/harness/cmd/harness-proxy

FROM debian:trixie-slim@sha256:a72b4433de1cf7d6bae0c4cee74d0547f58601a643b3375f070c51600d63b6b2 AS base
RUN apt-get update \
Expand Down
4 changes: 3 additions & 1 deletion docs/development.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Development

You need Go 1.27.3 and Docker.
You need Go 1.27.4 and Docker.

## Build and test

Expand Down Expand Up @@ -58,6 +58,8 @@ When that directory changes on `main`, the `Agent image` workflow publishes both

To bump an agent CLI, update its tag and the sha256 of each architecture's asset together in the Dockerfile. The workflow needs "Allow GitHub Actions to create and approve pull requests" in the repository settings.

Until harness publishes the sandbox resource-limit fixes, `go.mod` and `HARNESS_REPLACE` in the Dockerfile pin the same reviewed fork commit. Remove both replacements when upgrading to the upstream release that contains them.

## Releases

A `vYYYY.MM.DD.N` tag such as `v2026.10.25.1` runs the `Release` workflow. It builds tamis for Linux, macOS and Windows on amd64 and arm64, attests the six binaries and publishes them in a GitHub release. The action runs the Linux ones, the others serve local runs.
Expand Down
2 changes: 1 addition & 1 deletion docs/how-it-works.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ An agent, Claude Code or Codex, investigates the report in a throwaway container

- `/work/report.md` holds the report and its non-bot followup comments,
- `/work/src` holds the selected source branch, read-only and with its history,
- the agent can search public issues and pull requests through the GitHub API,
- the agent can search public issues and pull requests through a read-only GitHub service,
- it reads the security policy files when the repository has some,
- it writes its findings to `/work/report.json` against a JSON schema, first as soon as it has an answer, then as it learns more.

Expand Down
12 changes: 8 additions & 4 deletions docs/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ tamis reads text from an outside reporter, holds access to embargoed advisories
| Threat | Mitigation |
|---|---|
| A prompt injection makes the agent leak other advisories | See [Duplicate search isolation](#duplicate-search-isolation). |
| The agent leaks secrets | The container holds no secret. The model key stays on the runner, the GitHub token never enters the container, and the container gets a clean single-branch clone with an empty `.git/config`. |
| The agent exfiltrates data over the network | The container sits on an isolated internal network and only reaches a private egress sidecar. The model proxy pins the model and rejects remote URLs, remote MCP servers, hosted tools, stored conversations and background calls. |
| The agent leaks secrets | The container holds no secret. The model key stays on the runner, the GitHub token never enters the container, and the container gets only the selected commit and its history, with an empty `.git/config`. |
| The agent exfiltrates data over the network | The container sits on an isolated internal network and only reaches a private egress sidecar. Public GitHub access is a read-only service with no credentials or redirects. The model proxy pins the model and rejects remote URLs, remote MCP servers, hosted tools, stored conversations and background calls. |
| The triage loads a remote image carrying data, or pings people | tamis escapes all model text: no links, images, HTML, entities or mentions. |
| A report changes during triage | tamis hashes the title, description, metadata and non-bot comments, reads them again before publication and publishes nothing when the revision changed. It does not triage a completed advisory again after a later edit. |
| A reporter drains the model budget | Branches, agents and comparators share the advisory and run budgets. tamis bounds requests, bytes, output tokens and runtime, and one known reporter cannot take a whole run. A provider spending ceiling bounds costs across runs. |
Expand All @@ -34,12 +34,16 @@ tamis itself never logs report text, the identifiers of other advisories or prov
The agent runs through [harness](https://github.com/alpha-omega-security/harness), the isolation layer of [scrutineer](https://github.com/alpha-omega-security/scrutineer):

- a throwaway container per advisory, with a read-only root filesystem, all capabilities dropped and no new privileges,
- one single-branch clone of the analysed branch per execution, mounted read-only into each agent run, with no untracked files and an empty `.git/config`, while tamis only reads the commit of the other branches,
- an internal bridge network with both gateway modes set to `isolated` and IPv6 disabled, whose only peer is an authenticated egress proxy that allows the model proxy and `api.github.com`,
- one snapshot of the selected commit and its ancestors per execution, mounted read-only into each agent run, with no other branches, untracked files or repository configuration,
- an internal bridge network with both gateway modes set to `isolated` and IPv6 disabled, whose only peer is an authenticated egress proxy that allows the model proxy and, for the reader only, a public GitHub read service,
- a read-only workspace except for `report.json`, with memory, CPU, process and file-size limits,
- an image with only the agent CLI, git, curl, ripgrep and `harness-proxy`, each download checked against a pinned checksum,
- that image pinned by digest in each release, and checked by the action against its build attestation before use, like the tamis binary of a release.

The public GitHub service accepts issue and pull-request searches and selected issue, pull-request and commit reads for the source repository. It preserves pagination and PR diff/patch formats. It does not forward agent credentials, accept writes or follow redirects; offline duplicate agents cannot reach it.

Host-side diagnostics are bounded too: harness retains the last 64 KiB of stderr, drains JSONL records larger than 16 MiB and limits refusal-log traversal before constructing the log text. tamis keeps only the last 16 error messages, up to 4 KiB each.

## The model proxy

The model key never enters the container. A proxy on the runner gives each agent a random token and revokes it when the run ends.
Expand Down
4 changes: 3 additions & 1 deletion go.mod
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
module github.com/php/tamis

go 1.27.3
go 1.27.4

require (
github.com/alpha-omega-security/harness v0.1.21
Expand Down Expand Up @@ -40,3 +40,5 @@ tool (
gotest.tools/gotestsum
honnef.co/go/tools/cmd/staticcheck
)

replace github.com/alpha-omega-security/harness => github.com/alexandre-daubois/harness v0.1.12-0.20261116083615-135e53b30cb0
4 changes: 2 additions & 2 deletions go.sum
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk=
github.com/BurntSushi/toml v1.6.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
github.com/alpha-omega-security/harness v0.1.21 h1:iIpAbfuNSLmnyPmXqJHO4M2L/OVzfFQhZVOoSVLrabo=
github.com/alpha-omega-security/harness v0.1.21/go.mod h1:rlD5PLSKLYxoGsx9CigCgZ87/zDCuMVKPVEFX0UZqpQ=
github.com/alexandre-daubois/harness v0.1.12-0.20261116083615-135e53b30cb0 h1:kgJOqG/uBEpSnAk4pDpm4iRDC0LPyNf5xLk0vAwIuzw=
github.com/alexandre-daubois/harness v0.1.12-0.20261116083615-135e53b30cb0/go.mod h1:FVFnHq16HABtUOrQbOA1fbBoIfIsowI+B4ZR4fl1MuE=
github.com/bitfield/gotestdox v0.2.3 h1:H8Wy07kYacr3YSF5aJON/m9ASE+PGKOSufXkTjqQGb8=
github.com/bitfield/gotestdox v0.2.3/go.mod h1:bq/HemlNNqEvjOzy7brevVhzZD8WTGFDGq59DOIsHqI=
github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
Expand Down
132 changes: 132 additions & 0 deletions internal/sandbox/github.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
package sandbox

import (
"context"
"crypto/rand"
"errors"
"io"
"net"
"net/http"
"net/url"
"path"
"regexp"
"slices"
"strconv"
"strings"
"time"

"github.com/alpha-omega-security/harness/egress"
)

const maxGitHubResponse = 16 << 20

var (
publicRepository = regexp.MustCompile(`^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$`)
publicRepoRoute = regexp.MustCompile(`^/(issues(/[1-9][0-9]*(/(comments|events|timeline))?)?|pulls(/[1-9][0-9]*(/(comments|commits|files|reviews))?)?|commits(/[0-9a-fA-F]{7,40})?)$`)
)

type githubAPI struct {
repository, token, upstream string
client *http.Client
slots chan struct{}
}

func newGitHubAPI(repository string) (*githubAPI, error) {
if !publicRepository.MatchString(repository) || path.Clean(repository) != repository || strings.HasPrefix(repository, ".") {
return nil, errors.New("a source repository is required for public GitHub access")
}
return &githubAPI{
repository: repository,
token: rand.Text(),
upstream: "https://api.github.com",
client: &http.Client{Timeout: 30 * time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }},
slots: make(chan struct{}, 4),
}, nil
}

// The agent gets a capability for public reads, never GitHub credentials or a
// general-purpose HTTPS tunnel. Each reader run has its own server and lifetime.
func serveGitHub(ctx context.Context, repository string) (base, port string, close func(), err error) {
api, err := newGitHubAPI(repository)
if err != nil {
return "", "", nil, err
}
l, err := net.Listen("tcp", ":0")
if err != nil {
return "", "", nil, err
}
server := &http.Server{Handler: api, BaseContext: func(net.Listener) context.Context { return ctx }, ReadHeaderTimeout: 10 * time.Second, IdleTimeout: time.Minute, MaxHeaderBytes: 16 << 10}
go func() { _ = server.Serve(l) }()
port = strconv.Itoa(l.Addr().(*net.TCPAddr).Port)
return "http://" + net.JoinHostPort(egress.HostGatewayAlias, port) + "/" + api.token, port, func() { _ = server.Close() }, nil
}

func (a *githubAPI) ServeHTTP(w http.ResponseWriter, r *http.Request) {
route, ok := strings.CutPrefix(r.URL.Path, "/"+a.token)
if !ok || r.Method != http.MethodGet || r.ContentLength != 0 || r.URL.RawPath != "" || len(r.URL.RequestURI()) > 8192 || path.Clean(route) != route {
http.Error(w, "public GitHub request not permitted", http.StatusForbidden)
return
}
query, err := url.ParseQuery(r.URL.RawQuery)
if err != nil || !a.allowed(route, query) {
http.Error(w, "public GitHub request not permitted", http.StatusForbidden)
return
}
select {
case a.slots <- struct{}{}:
defer func() { <-a.slots }()
default:
http.Error(w, "too many public GitHub requests", http.StatusTooManyRequests)
return
}
if route == "/search/issues" {
query.Set("q", query.Get("q")+" repo:"+a.repository)
}
upstream, err := http.NewRequestWithContext(r.Context(), http.MethodGet, a.upstream+route+"?"+query.Encode(), nil)
if err != nil {
http.Error(w, "invalid public GitHub request", http.StatusBadRequest)
return
}
accept := r.Header.Get("Accept")
if !slices.Contains([]string{"application/vnd.github.diff", "application/vnd.github.patch"}, accept) {
accept = "application/vnd.github+json"
}
upstream.Header.Set("Accept", accept)
upstream.Header.Set("X-GitHub-Api-Version", "2022-11-28")
resp, err := a.client.Do(upstream)
if err != nil {
http.Error(w, "public GitHub request failed", http.StatusBadGateway)
return
}
defer resp.Body.Close()
body, err := io.ReadAll(io.LimitReader(resp.Body, maxGitHubResponse+1))
if err != nil || len(body) > maxGitHubResponse || resp.StatusCode >= 300 && resp.StatusCode < 400 {
http.Error(w, "invalid public GitHub response", http.StatusBadGateway)
return
}
for _, header := range []string{"Content-Type", "Retry-After", "X-RateLimit-Remaining", "X-RateLimit-Reset"} {
if value := resp.Header.Get(header); value != "" {
w.Header().Set(header, value)
}
}
if links := resp.Header.Get("Link"); links != "" {
w.Header().Set("Link", strings.ReplaceAll(links, a.upstream, "/"+a.token))
}
w.WriteHeader(resp.StatusCode)
_, _ = w.Write(body)
}

func (a *githubAPI) allowed(route string, query url.Values) bool {
if route != "/search/issues" {
suffix, ok := strings.CutPrefix(route, "/repos/"+a.repository)
if !ok || !publicRepoRoute.MatchString(suffix) {
return false
}
}
for key, values := range query {
if len(values) != 1 || len(values[0]) > 2000 || !slices.Contains([]string{"page", "per_page", "sort", "order", "direction", "state", "since", "sha", "path", "base", "head"}, key) && !(route == "/search/issues" && key == "q") {
return false
}
}
return true
}
127 changes: 127 additions & 0 deletions internal/sandbox/github_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
package sandbox

import (
"fmt"
"net/http"
"net/http/httptest"
"net/url"
"strings"
"sync/atomic"
"testing"

"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)

func TestPublicGitHubReadsIssuesAndPullRequestsWithoutCredentials(t *testing.T) {
var calls []string
upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
calls = append(calls, r.URL.Path)
assert.Equal(t, http.MethodGet, r.Method)
assert.Empty(t, r.Header.Get("Authorization"))
assert.Empty(t, r.Header.Get("Cookie"))
assert.Empty(t, r.Header.Get("X-Attacker"))
assert.Equal(t, "application/vnd.github.diff", r.Header.Get("Accept"))
if r.URL.Path == "/search/issues" {
assert.Equal(t, "foo repo:php/tamis", r.URL.Query().Get("q"))
}
w.Header().Set("Content-Type", "application/json")
w.Header().Set("X-RateLimit-Remaining", "12")
w.Header().Set("Link", "<http://"+r.Host+r.URL.Path+"?page=2>; rel=\"next\"")
fmt.Fprint(w, `{"ok":true}`)
}))
defer upstream.Close()
api, err := newGitHubAPI("php/tamis")
require.NoError(t, err)
api.upstream = upstream.URL
for _, route := range []string{
"/search/issues?q=foo",
"/repos/php/tamis/issues?state=all&page=2&per_page=100",
"/repos/php/tamis/issues/12",
"/repos/php/tamis/issues/12/comments",
"/repos/php/tamis/pulls/12",
"/repos/php/tamis/pulls/12/files",
"/repos/php/tamis/pulls/12/commits",
"/repos/php/tamis/pulls/12/reviews",
"/repos/php/tamis/commits/0123456",
} {
r := httptest.NewRequest(http.MethodGet, "/"+api.token+route, nil)
r.Header.Set("Authorization", "Bearer attacker-token")
r.Header.Set("Cookie", "secret=value")
r.Header.Set("X-Attacker", "value")
r.Header.Set("Accept", "application/vnd.github.diff")
w := httptest.NewRecorder()
api.ServeHTTP(w, r)
require.Equal(t, http.StatusOK, w.Code, route)
assert.JSONEq(t, `{"ok":true}`, w.Body.String())
assert.Equal(t, "12", w.Header().Get("X-RateLimit-Remaining"))
assert.Contains(t, w.Header().Get("Link"), "</"+api.token+"/")
}
require.Len(t, calls, 9)
}

func TestPublicGitHubRefusesWritesAndOtherResources(t *testing.T) {
var calls atomic.Int32
upstream := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) { calls.Add(1) }))
defer upstream.Close()
api, err := newGitHubAPI("php/tamis")
require.NoError(t, err)
api.upstream = upstream.URL
for _, tc := range []struct{ method, route, body string }{
{http.MethodPost, "/repos/php/tamis/issues", `{}`},
{http.MethodGet, "/repos/php/tamis/issues", `{}`},
{http.MethodConnect, "/repos/php/tamis/issues", ""},
{http.MethodGet, "/gists", ""},
{http.MethodGet, "/issues/12", ""},
{http.MethodGet, "/repos/attacker/repo/issues", ""},
{http.MethodGet, "/repos/php/tamis/security-advisories", ""},
{http.MethodGet, "/repos/php/tamis/contents/README.md", ""},
{http.MethodGet, "/repos/php/tamis/../other/issues", ""},
{http.MethodGet, "/repos/php/tamis/%69ssues", ""},
{http.MethodGet, "/search/issues?access_token=attacker", ""},
{http.MethodGet, "/search/issues?q=one&q=two", ""},
{http.MethodGet, "/search/issues?q=" + strings.Repeat("x", 2001), ""},
} {
r := httptest.NewRequest(tc.method, "/"+api.token+tc.route, strings.NewReader(tc.body))
w := httptest.NewRecorder()
api.ServeHTTP(w, r)
assert.Equal(t, http.StatusForbidden, w.Code, tc.route)
}
w := httptest.NewRecorder()
api.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/wrong-token/search/issues?q=foo", nil))
assert.Equal(t, http.StatusForbidden, w.Code)
assert.Zero(t, calls.Load())
for _, repository := range []string{"", "php", "../repo", "php/..", "php/repo/extra", "php/repo?x=1"} {
_, err := newGitHubAPI(repository)
require.Error(t, err, repository)
}
}

func TestPublicGitHubBoundsResponsesAndRefusesRedirects(t *testing.T) {
var followed atomic.Int32
destination := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) { followed.Add(1) }))
defer destination.Close()
upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Query().Get("page") == "2" {
fmt.Fprint(w, strings.Repeat("x", maxGitHubResponse+1))
return
}
http.Redirect(w, r, destination.URL, http.StatusFound)
}))
defer upstream.Close()
api, err := newGitHubAPI("php/tamis")
require.NoError(t, err)
api.upstream = upstream.URL
for _, page := range []string{"1", "2"} {
w := httptest.NewRecorder()
api.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/"+api.token+"/repos/php/tamis/issues?page="+page, nil))
assert.Equal(t, http.StatusBadGateway, w.Code)
}
assert.Zero(t, followed.Load())
for range cap(api.slots) {
api.slots <- struct{}{}
}
w := httptest.NewRecorder()
api.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/"+api.token+"/search/issues?q="+url.QueryEscape("foo"), nil))
assert.Equal(t, http.StatusTooManyRequests, w.Code)
}
Loading
Loading