diff --git a/docs/argus-hub/mcp.md b/docs/argus-hub/mcp.md index b1408579..5ce062be 100644 --- a/docs/argus-hub/mcp.md +++ b/docs/argus-hub/mcp.md @@ -59,7 +59,10 @@ share one set of filters: `query_tasks` adds `q` (free-text search), `outcome` (comma-separated `success`, `failure`, `unknown`) and paging with `limit` (default 50, -maximum 200) and `offset`. `query_users` only takes `group`. It's a +maximum 200) and `offset`. `query_tasks` and `query_task_quality` both take +`flagged`, where `1` narrows to tasks carrying a +[credential warning](/argus-hub/tasks#credential-warnings). +`query_users` only takes `group`. It's a roster, not a windowed report, so it's the tool to call first to find a `userId` before scoping the others. @@ -69,7 +72,7 @@ roster, not a windowed report, so it's the tool to call first to find a |---|---| | `query_users` | The roster: user IDs, display names, emails, group, last-sync time, sessions, tokens and cost. | | `query_activity` | Usage and cost over the window, plus the same figures for the prior window for comparison. | -| `query_tasks` | A paged, filterable list of tasks, with outcome counts for the filtered set. | +| `query_tasks` | A paged, filterable list of tasks, with outcome counts for the filtered set and how many carry a credential warning. | | `query_task_quality` | Success, frustration and friction rates, outcomes over time, and the top failure signals. | | `query_tool_usage` | Which tools, skills and MCP servers people use, and how usage compares across sources. | | `list_labels` | Every [Argus Hub label](/argus-hub/tasks#argus-hub-labels) defined on this Argus Hub, with how many tasks carry it. | diff --git a/docs/argus-hub/tasks.md b/docs/argus-hub/tasks.md index f889fbdf..5d49589d 100644 --- a/docs/argus-hub/tasks.md +++ b/docs/argus-hub/tasks.md @@ -64,6 +64,22 @@ client. It's measured for Claude sessions only, so a count of zero and "no data" show as different things, and an observed-sessions count makes clear how much of the window that friction reading actually covers. +## Credential warnings + +When someone's session text looked like it held a credential, their Argus sends a +flag along with the affected tasks, and this view surfaces it. A warning under the +page heading counts the tasks it covers in the current window, and **Show only +these** narrows the view to them. Each one carries a **Credential warning** pill in +the list. + +The details stay on that person's machine. Argus Hub knows only that a task was +affected, not what kind of credential it was or where in the session it appeared, so +acting on one means asking that person to rotate it. Dismissing the warning in their +own Argus hides their banner and leaves this flag in place, since one person having +read a warning isn't the organization having dealt with it. See +[Credential warnings](/sessions#credential-warnings) for what they see, and +[Privacy and Security](/privacy#credential-warnings) for what crosses the wire. + ## Argus Hub labels Argus Hub labels are separate from the labels you set on a session in the Argus diff --git a/docs/cli-reference.md b/docs/cli-reference.md index ec8622de..2c5de07f 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -27,7 +27,7 @@ npx @agentdeploymentco/argus | `index delete` | Remove the session ids you name from the store. | | `sync` | Upload a usage snapshot to an [Argus Hub](/terminology#argus-hub). | | `run` | Do it all: keep the index current, serve Argus and sync on a schedule. | -| `status` | Show where the local store lives and per-source counts. | +| `status` | Show where the local store lives, per-source counts and how far the [credential check](/sessions#credential-warnings) has got. | | `config` | Read or write settings (`config get`, `config set`). | | `secret` | Store API keys for the model providers Argus can use. | diff --git a/docs/how-it-works.md b/docs/how-it-works.md index f3049af5..c990290b 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -17,6 +17,13 @@ its next pass and [indexes](/terminology#index) it, reading the session once and pulling out the useful details (usage, cost, tools, skills and projects). This runs on its own, so your usage stays up to date without you thinking about it. +Indexing also checks each session's text for credentials pasted into it, like an API +key or a token, and warns you so you can rotate them. That check is local pattern +matching, with no model and no network. Sessions already in your +[index](/terminology#index) when you updated Argus get checked in the background as +well, so you don't have to re-index to see the warnings. See +[Credential warnings](/sessions#credential-warnings). + ## Your data lives in a local database Everything Argus indexes is stored in a database on your own computer. That local diff --git a/docs/mcp-server.md b/docs/mcp-server.md index 9e1ebd67..74802e8d 100644 --- a/docs/mcp-server.md +++ b/docs/mcp-server.md @@ -366,6 +366,10 @@ them sends that text into the model behind whichever agent asked. than failing. - `search_sessions` and `get_session` leave out your opening prompt, along with any search match that came from the conversation itself. +- Both also leave out a session's + [credential warnings](/sessions#credential-warnings). A warning holds no + credential, but Argus works it out from the text you chose not to share, so it + follows the same switch. Both switches apply the moment you flip them, with no restart. Turning **Let agents query Argus** off closes the endpoint entirely, and connected agents get a diff --git a/docs/metric-views.md b/docs/metric-views.md index 43f680d1..8abae19b 100644 --- a/docs/metric-views.md +++ b/docs/metric-views.md @@ -26,7 +26,9 @@ Below the totals: - **Recommendations** are things Argus noticed that may be worth acting on, like [plugins](/terminology#plugin) you've enabled but never use, or sessions where - context grew unusually fast. + context grew unusually fast. A + [credential warning](/terminology#credential-warning) leads the list when Argus + finds one, and links to the sessions it applies to. - **Trends** plot your tokens per day and cost per day across the range. - **Sources** breaks your usage down by agent, as charts and a table you can sort. diff --git a/docs/privacy.md b/docs/privacy.md index 5d9419f6..7f06cc58 100644 --- a/docs/privacy.md +++ b/docs/privacy.md @@ -23,6 +23,25 @@ the useful details and saves them to a local [index](/terminology#index), a database on your computer. It doesn't watch your screen or record anything as you work. Everything it needs is already on disk. +## Credential warnings + +As it indexes, Argus checks your session text for credentials you may have pasted +into a conversation, like an API key, a token or a private key. The check is pattern +matching on your own machine: no model reads it, and nothing is sent anywhere. + +What Argus keeps from a match is deliberately thin. It records the kind of +credential, where in the session it appeared and a few characters of the value, +enough to tell you which key it was and not enough to use it. The credential itself +is never copied into the [index](/terminology#index). + +Warnings stay on your computer. A [sync](/terminology#sync) uploads none of them. +What an [Argus Hub](/terminology#argus-hub) does receive is one yes or no on each +[task](/terminology#task), saying whether a warning landed in it, so whoever runs the +Hub can see that a piece of work touched a credential and ask you to rotate it. The +kind, the location and those few characters all stay local. Dismissing a warning in +your own Argus hides your banner and leaves that flag in place, since the flag +records that the work touched a credential rather than that you've read the warning. + ## Task interpretation and model providers [Task interpretation](/tasks) is the one part of Argus that uses a model to read @@ -90,4 +109,6 @@ see agent use across the team. Two things to know: - **What's sent stays minimal.** A sync carries your metrics and task data (usage totals, breakdowns, outcomes and the like), plus a few short text snippets: a session's opening prompt and the brief evidence behind a task's - judgment. The full text of your sessions is never uploaded. + judgment. The full text of your sessions is never uploaded, and neither are the + details of a [credential warning](#credential-warnings), only a flag on the tasks + one applies to. diff --git a/docs/sessions.md b/docs/sessions.md index 3a88b0b0..9bf84f77 100644 --- a/docs/sessions.md +++ b/docs/sessions.md @@ -97,6 +97,39 @@ session (interruptions, tool actions you declined, compactions and turn timings, Claude sessions), the full table of tools the session used and the files the agent read or changed. +## Credential warnings + +Argus checks your sessions for credentials pasted into a conversation, so you can +rotate anything real. The check runs on your own computer as part of indexing. It's +pattern matching against well-known credential shapes, with no +[model](/terminology#model) reading your text and nothing sent anywhere. + +A session that looks like it holds a credential opens with a warning above its +tabs. Each +line says which [interaction](/terminology#interaction) it turned up in, what kind +of credential it looks like (an AWS access key, a GitHub token, a private key and +so on), a few characters of the value and whether it sat in your prompt or the +agent's reply. Those few characters are all Argus keeps, enough to tell you which +key it was and not enough to use it. + +Click a line to jump to that interaction in the Timeline, where the turn carries the +same marker on the half it matched. A marker points at the first place a credential +appeared, so a key you pasted once and the agent repeated later shows up once. + +- **Dismiss** hides the warning once you've dealt with it, leaving a muted line with + **Show again**. It covers the findings you saw, so a later index that turns up + something different warns you again. The Timeline markers stay either way. +- **In the list**, a session with an undismissed warning carries a red count + alongside its token and task counts. +- **Flagged** narrows the list to those sessions, and arrives as a pill you can + remove. The credential recommendation on Activity links straight to it. It's the + one filter that includes sessions you've hidden, each marked with an eye icon on + the row. + +Treat a warning as a reason to look rather than proof of a leak. Argus favors +precision over reach, so it rarely flags something harmless, and it stays quiet +about credential shapes it doesn't recognize. + ## Refresh If a session has grown since Argus last indexed it, the **Refresh** button at the diff --git a/docs/settings-reference.md b/docs/settings-reference.md index 777d2b4c..59372dc0 100644 --- a/docs/settings-reference.md +++ b/docs/settings-reference.md @@ -86,7 +86,7 @@ provider value `claude` is still accepted as an alias for `claude-cli`. | Hub URL | Argus Hub server URL for [sync](/terminology#sync). | `hub.url` | `ARGUS_HUB_URL` | None | unset | | Hub key | Key used to authenticate to Argus Hub. | `hub.key` | `ARGUS_HUB_KEY` | None | unset | | Log level | How much detail Argus prints to the terminal. | `log.level` | `ARGUS_LOG_LEVEL` | `--log-level` | `info` | -| Retain session text | Whether Argus keeps prompt and response text in the local [index](/terminology#index) for interpretation. | `retainText` | `ARGUS_RETAIN_TEXT` | `index`, `index rebuild` and `index refresh`: `--retain-text true\|false` | `true` | +| Retain session text | Whether Argus keeps prompt and response text in the local [index](/terminology#index) for interpretation. New sessions are still checked for [exposed credentials](/sessions#credential-warnings) either way, but with this off, sessions already indexed can't be re-checked without `index refresh`. | `retainText` | `ARGUS_RETAIN_TEXT` | `index`, `index rebuild` and `index refresh`: `--retain-text true\|false` | `true` | | Agent access | Whether agents on this computer can query Argus over the local MCP endpoint (`/mcp`). See [Connect Your Agent](/connect-your-agent). | `agentAccess.enabled` | `ARGUS_AGENT_ACCESS_ENABLED` | None | `true` | | Agent transcript access | Whether agents can also read retained session transcript text through the MCP endpoint. | `agentAccess.includeTranscripts` | `ARGUS_AGENT_ACCESS_INCLUDE_TRANSCRIPTS` | None | `false` | | Welcome completed | Whether the first-run welcome screen has been dismissed. | `state.onboardingCompleted` | `ARGUS_STATE_ONBOARDING_COMPLETED` | None | `false` | diff --git a/docs/terminology.md b/docs/terminology.md index f0a0339c..630802ee 100644 --- a/docs/terminology.md +++ b/docs/terminology.md @@ -25,6 +25,14 @@ The estimated dollar cost of your agent use, worked out from how many tokens you used and each model's price. It's an estimate for understanding trends, not a bill. +## Credential warning + +A warning Argus raises when a [session](#session)'s text looks like it holds a +credential someone pasted in, such as an API key, a token or a private key. Argus +checks for these locally as it indexes, and records only the kind of credential, +which [interaction](#interaction) it showed up in and a few characters of the +value, never the value itself. See [Sessions](/sessions#credential-warnings). + ## Dashboard The org-wide view an [Argus Hub](#argus-hub) presents, pulling together usage from