# Detections Source: https://docs.amplify.security/agents/detections Reusable rules that outlive any one conversation — OpenGrep patterns and natural-language policies. ## Why detections exist A finding describes one moment: this file, this commit, this vulnerability. A **detection** is the rule behind it, and it keeps checking forever. That is what makes the work compound. When an agent confirms a vulnerability, the durable value is the rule it leaves behind: one that catches the same mistake in every repository from then on, cheaply, with no agent needing to re-derive it. ## Detection types | Type | Format | What it's good at | | ----------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **OpenGrep rule** | YAML | Structural patterns with a known shape — a dangerous API, a missing flag, a taint path from source to sink. Fast and deterministic. | | **Policy** | Natural language | Intent that resists pattern matching — "every endpoint that mutates data must check authorization", "no service may log request bodies". Evaluated by an agent. | | **CodeQL query** | QL | Deep dataflow queries. See the limitation below. | **CodeQL detections can be authored but are not yet executed.** Only OpenGrep and policy detections have runtimes today; `detections-runner` stores other types and skips them with a note. The `codeql-rule-creator` skill and the editor's CodeQL support exist so the rules are ready when execution lands. ### OpenGrep rules OpenGrep rules support two modes: * **`search`** — match a pattern. Use `pattern`, `patterns`, `pattern-either`, or `pattern-regex`. * **`taint`** — track data flow. Declare `pattern-sources`, `pattern-sinks`, and optionally `pattern-sanitizers`; a match is a source reaching a sink with nothing neutralizing it in between. Taint mode is the one that matters most for security work: it encodes *reachability*, which is usually the question you actually care about. Rules carry a severity of `INFO`, `WARNING`, or `ERROR`, and OpenGrep filters by the rule's own `languages` field at run time — so an irrelevant rule exits cheaply rather than wasting a pass. ### Policy detections A policy is a security requirement written in plain language. At run time, `detections-runner` spawns a `policy-evaluator` per policy, bound to that detection so every finding links back to it. Policies are the right tool when the rule is about intent — business logic, authorization, data handling — where no pattern captures the requirement and a human reviewer would need to reason about the code. ## Fields that matter | Field | Values | What it does | | --------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- | | **Status** | `TEST`, `PRODUCTION` | Whether the detection is still being evaluated or is trusted. Promote once its results hold up. | | **Severity** | `critical`, `high`, `medium`, `low` | How serious a match is. | | **Disposition** | `flag`, `escalate` | What should happen on a match — record it, or escalate it. | | **Tags** | free-form | Grouping and filtering. | | **Project** | optional | Scopes the detection to one repository. Unset means it applies organization-wide. | ### The test-to-production lifecycle New detections start at `TEST`. Run them, review what they catch, tune the rule, and promote to `PRODUCTION` when the signal is trustworthy. This exists because a noisy detection is worse than no detection — it trains your team to ignore results. Keeping unproven rules visibly in `TEST` lets you build the library without eroding trust in it. ## Where detections come from | Source | Meaning | | --------------- | ------------------------------------------------ | | `manual` | Authored by a person, or by an agent on request. | | `risk-register` | Compiled from your organization's risk register. | | `threat-model` | Compiled from a threat model. | Compiled detections keep provenance back to the upstream document, so a rule can be traced to the requirement that motivated it. ## Authoring a detection **In the web console.** Open **Detections** and create one. The editor syntax-highlights by type — YAML for policies, Markdown with YAML frontmatter for rule types — and labels the language in the header. Customer types the UI doesn't recognize still render with a generic label rather than breaking. **With an agent.** Often the better path, because agents can validate as they go: * `opengrep-rule-creator` writes and checks an OpenGrep rule. * `policy-detection-creator` turns a requirement into a stored policy. * `detection-author` reads a scan's findings and authors a detection for each — the automated version of the same loop. Ask in [chat](/interactive/chat): *"Write an OpenGrep rule that catches this pattern and store it as a test detection."* ## Running detections Add [`detections-runner`](/agents/library#detections) as a workflow step. It lists every stored detection, triages which apply, and dispatches by type — OpenGrep rules directly, policies via one child evaluator each. Findings link back to the detection that produced them, so you can see which rules are earning their place. Its bias is deliberate: it dispatches when in doubt, because a detection that never ran is worse than a wasted pass. ## The compounding loop 1. An agent confirms a vulnerability in [chat](/interactive/chat) or a workflow run. 2. `detection-author` — or you — turns it into a detection, at `TEST`. 3. You review what it catches and promote it to `PRODUCTION`. 4. A `detections-runner` workflow applies it on every pull request from then on. Step 4 is cheap and repeatable. That's the payoff for the reasoning spent in step 1. ## Next steps Add `detections-runner` to a chain. What a detection produces when it matches. # How agents work Source: https://docs.amplify.security/agents/how-agents-work What an agent is, how it runs, and how agents delegate to each other. ## What an agent is An agent is a participant in the harness: a model, a set of tools it may call, a budget, and a body of instructions. Give it a task and it works until the task is done or the budget runs out. An agent decides what to do next based on what it just learned. It reads a file, notices a suspicious call, traces the caller, runs a command to check a hypothesis, and either confirms or discards it. That loop — reason, act, observe, reason again — suits security work, where the question is usually reachability: can an attacker actually get there? ## How a run proceeds 1. **The agent receives a task.** In chat that's your message; in a workflow it's the task Console composes for that step. 2. **It reasons and calls tools.** Each call returns a result it reads before deciding the next step. 3. **It may load a skill** with `activate_skill` when it hits a task a documented procedure covers. 4. **It may delegate** with `spawn_agent`, handing focused work to a child and waiting for the summary. 5. **It records durable results** — findings, patches, detections — rather than only replying in prose. 6. **It stops** when the task is done, the budget is exhausted, or it's cancelled. Everything an agent does in step 2 is bounded by the [tool surface](/agents/tool-reference). ## Budgets Two ceilings keep a run from going forever, both settable per agent: * **`maxIterations`** — how many reasoning↔tool cycles it may take. * **`timeout`** — wall-clock milliseconds for the whole execution. For an orchestrator, `timeout` covers every child it spawns, so it must exceed the worst-case sum of their durations. Leave both unset unless the agent is genuinely an outlier. ## Delegation and agent trees An agent can spawn sub-agents, and those can spawn their own, forming a tree. This exists for two reasons: * **Focus.** A child starts with a clean context scoped to one job, so a broad scan doesn't drown in detail from the first file it opened. * **Parallelism.** Independent work runs concurrently — one evaluator per detection, one patch generator per file. A child returns a **summary**, not its full transcript. The parent sees the conclusion and quotes it forward. This is why an agent's `description` and its final summary both matter so much: they're the interface between agents. You can watch the tree live — as a nested view in the CLI, and in the web console's chat while a turn runs. ## Where agents come from | Source | Description | | ----------------------- | -------------------------------------------------------------------- | | **Platform agents** | The library Console ships. See [the agent library](/agents/library). | | **Organization agents** | Agents your team writes, in the web console or the CLI. | Both appear together wherever agents are listed, and a workflow treats them identically. An organization agent whose `name` matches a platform agent **shadows** it — the supported way to customize built-in behavior. ## When to write your own Reach for a new agent when: * The task is a distinct job with its own output — "audit dependencies", "review IaC for public exposure". * You want different tool permissions, like a read-only reviewer that can't modify code. * You want a different model for cost or depth reasons. Prefer a [skill](/agents/skills) instead when you're capturing *how to do one thing well* and an existing agent could follow it. Skills are cheaper: no separate budget, no separate model, loaded only when relevant. ## Next steps The frontmatter reference. Sequence agents into a workflow. # The agent library Source: https://docs.amplify.security/agents/library The agents Console ships, what each is for, and which ones to put in a workflow. ## Using the library Console ships the agents below. They appear in the agent list and the [workflow agent picker](/workflows/create-a-workflow#agents) alongside anything your organization writes. They're also the best available examples of the format — if you're about to [write an agent](/agents/writing-an-agent), open one first and read how its frontmatter and instructions are put together. ## Scanning The vulnerability scanners share one approach: map the repository's security conventions, hunt for places the implementation diverges from that intent, then confirm candidates through analysis. They differ only in how broadly they hunt and how deeply they confirm. | Agent | Profile | Use when | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | | `vulnerability-scanner-basic` | Pursues the top 6 candidates, caps at 6 findings, generic analysis only. | You want a fast signal — a pull request check where latency matters. | | `vulnerability-scanner-standard` | Pursues the top 10 candidates, caps at 10 findings, uses the class-specific skill library plus confirmation. | The default choice for most workflows. | | `vulnerability-scanner-comprehensive` | Pursues the top 40 candidates, caps at 40 findings, uses the full skill library and a more capable model. | Auditing a repository in depth, where thoroughness matters more than speed. | The caps are deliberate. A scanner that returns everything it half-suspects is noise; these stop at a defined budget so the results stay reviewable. ## Detections | Agent | What it does | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `detections-runner` | Runs every [detection](/agents/detections) stored in your organization against the repository, dispatching by type — OpenGrep rules directly, policy detections via one child evaluator each. Findings are linked to the detection that produced them. | | `detection-author` | Reads findings from an earlier step and authors a reusable detection for each, choosing between an OpenGrep rule and a natural-language policy. | These two are the ends of a loop worth understanding: `detection-author` turns a one-time discovery into a permanent rule, and `detections-runner` is what applies every rule you've accumulated from then on. ## Patching | Agent | What it does | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `patch-generator` | Generates a verified patch for one detection's findings in one file: edits the file, re-runs the detection to confirm the fix, captures the diff, and records it. | Add it as its own step after any agent that produces findings — `detections-runner`, a vulnerability scanner, or one of your own. It [consumes findings grouped by detection and file](/agents/writing-an-agent#group-by) by default, so it runs once per (detection, file) pair rather than once per individual match. Patch generation used to be a setting on `detections-runner` itself. It's its own step now — if your workflow used the old setting, Console already added `patch-generator` as a step for you. ## Agents spawned by other agents These exist in the library but are normally driven by another agent rather than added directly as workflow steps: | Agent | Spawned by | Role | | --------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `policy-evaluator` | `detections-runner` | Evaluates one policy detection against the repository, bound to that detection so every finding links back to it. | | `policy-fix-verifier` | `patch-generator` | Independently judges whether a patched file still violates a policy. Deliberately read-only — it returns a verdict and cannot report findings or edit code. | You *can* name one as a workflow step, but they expect a briefing their usual parent provides, so they work best left to it. ## Common chains | Goal | Chain | | ---------------------------------------------------- | ----------------------------------------------------- | | Fastest signal | `vulnerability-scanner-basic` | | Balanced scan | `vulnerability-scanner-standard` | | Deepest audit | `vulnerability-scanner-comprehensive` | | Turn findings into permanent rules | `vulnerability-scanner-standard` → `detection-author` | | Apply everything you've already vetted | `detections-runner` | | Apply everything you've already vetted, and patch it | `detections-runner` → `patch-generator` | ## Next steps Extend or shadow any of these. Put a chain to work. # Agents & detections Source: https://docs.amplify.security/agents/overview Console supplies the agentic loop; you supply the domain logic as agents, skills, and detections. ## What you author Console runs an agentic loop: a model reasons, calls tools, reads the results, and reasons again, inside an isolated environment with access to your code. Building that loop — the orchestration, the tool implementations, the sandboxing, the sub-agent delegation, the event streaming — is Console's job. Deciding *what the loop should do* is yours. Console exposes three authorable primitives for that, and everything else in the product is built on top of them. | Primitive | What it is | Format | Authored in | | ------------------------------------ | --------------------------------------------------------- | ------------------------------------------- | ---------------- | | **[Agent](/agents/how-agents-work)** | A participant that reasons, calls tools, and can delegate | Markdown + YAML frontmatter | Web console, CLI | | **[Skill](/agents/skills)** | A procedure an agent loads on demand | Markdown + YAML frontmatter | CLI, API | | **[Detection](/agents/detections)** | A rule that can be run repeatedly against code | OpenGrep YAML, or a natural-language policy | Web console, CLI | Telling them apart is the most common early stumble: * An **agent** is *who* is working. It has its own model, tool permissions, and budget. * A **skill** is *how* to do one thing well. It has no budget of its own — an agent loads it when the task calls for it. * A **detection** is *what* to look for. It's the durable artifact: a finding describes one moment, a detection keeps checking forever. ## Yours are first-class Console ships a library of agents and skills to start from. Detections are yours to build up — nothing is prebuilt there. Anything you write sits alongside the built-ins with no second-class status — a workflow runs platform and organization agents identically, and both are picked from the same list by their stated `description`. An agent you write with the same name as a built-in one **shadows** it. That's the supported way to customize built-in behavior without breaking workflows that already reference that name. ## The tool surface is the ceiling An agent can only do what some tool lets it do. However you word its instructions, its real capabilities are the union of the tools it's allowed to call — reading and writing files, running commands, querying code structure, scanning, fetching a URL, reading your vendors' findings, recording results, and spawning sub-agents. This is the single most useful thing to internalize before writing an agent, because it tells you which tasks are achievable and which aren't. The full inventory is in the [tool reference](/agents/tool-reference). ## How the pieces run together A realistic chain uses all three primitives at once: 1. A **workflow** step spawns your **agent**. 2. The agent **activates a skill** for the vulnerability class it's investigating. 3. It runs stored **detections** against the repository. 4. It records **findings**, and optionally a patch. 5. A workflow **output** posts the result to the pull request. Each layer is replaceable independently. ## Next steps The frontmatter reference and the editor. Everything an agent can actually do. What ships with Console. Connect repositories and vendors. # Skills Source: https://docs.amplify.security/agents/skills Package a procedure an agent loads on demand — and when to write one instead of an agent. ## What a skill is A skill is a documented procedure an agent loads when it becomes relevant — a Markdown file with YAML frontmatter, same shape as an agent. A skill has no model and no budget of its own: an agent calls `activate_skill`, and the skill's instructions enter that agent's context and run on its budget. The reason skills exist is context economy. A comprehensive scanner might know how to analyze twenty vulnerability classes, but loading all twenty procedures up front would crowd out the code it's supposed to be reading. Instead it loads the SQL-injection procedure when it's looking at a query, and the SSRF procedure when it's looking at an outbound request. ## Skill or agent? | Write a **skill** when | Write an **agent** when | | ------------------------------------------------ | -------------------------------------------------------- | | You're capturing *how to do one thing well* | You're defining *a job with its own output* | | An existing agent could follow your instructions | You need different tool permissions or a different model | | The procedure is only relevant sometimes | The work deserves its own budget and can be delegated to | | You want it available to many agents | You want to name it as a workflow step | When in doubt, start with a skill. It's cheaper — nothing to budget, nothing to orchestrate — and you can promote it to an agent later if it grows its own output. ## Frontmatter reference | Key | Required | Type | What it does | | --------------- | -------- | ------------------ | ------------------------------------------------------------------------------ | | `name` | Yes | string | How the skill is activated and listed. | | `description` | Yes | string, ≤500 chars | When to use this skill. Agents read it to decide whether to activate. | | `allowed-tools` | No | string\[] | Tools the procedure expects. See the [tool reference](/agents/tool-reference). | | `license` | No | string | Optional license string. | | `compatibility` | No | object | `min-version` / `max-version` constraints. | | `metadata` | No | object | Free-form key/value data. | ```markdown theme={null} --- name: ssrf-analysis description: Confirms or rules out server-side request forgery where user input reaches an outbound HTTP call. Use when a request URL, host, or path is influenced by request data. allowed-tools: - shell - code_lineage - ripgrep_search --- # SSRF analysis ## Confirming 1. Identify the outbound call and the client library in use. 2. Trace the URL argument back to its source with `call_graph`. 3. Establish whether an attacker controls the scheme, host, or path — not merely the query string. 4. Check for an allow-list, a resolved-IP check, or a proxy that constrains the destination. ## Ruling out Discard the candidate when the host is a compile-time constant, or when the only attacker-controlled portion is a path segment appended to a fixed host with no traversal possible. ``` Like an agent's, the `description` is load-bearing: it's what an agent reads when deciding whether this skill applies. ## Built-in skills | Skill | What it does | | -------------------------- | --------------------------------------------------------------------------------------------------- | | `vulnerability-scan` | Uses natural-language policy descriptions to find vulnerabilities in application logic. | | `opengrep-rule-creator` | Authors OpenGrep rules for detecting a vulnerability or code pattern. | | `codeql-rule-creator` | Authors CodeQL queries for vulnerabilities, bug patterns, and code-quality issues. | | `policy-detection-creator` | Turns a security requirement into a stored natural-language [policy detection](/agents/detections). | The scanner agents also draw on an internal library of class-specific analysis skills, which is what distinguishes the `standard` and `comprehensive` [profiles](/agents/library#scanning) from `basic`. ## Where to author a skill Skills are authored in the **CLI** (as files) or through the API. Unlike agents and detections, there is no skill editor in the web console today. In the CLI, a skill is a file on disk: ``` ~/.amplify/skills//SKILL.md # available in every session ./skills//SKILL.md # project-local ``` Override those locations with `AMPLIFY_SKILLS_DIR`. Skills load at startup, so restart the CLI after adding one. A skill directory can hold supporting files — reference documents, example rules, helper scripts — next to `SKILL.md`, and the instructions can point the agent at them. ## Using skills in the CLI | Command | What it does | | --------------- | -------------------------------------------------- | | `/skills` | Lists available skills and marks which are active. | | `/skill ` | Toggles a skill on or off for the session. | Toggling a skill on makes it available immediately, which is the fastest way to test one you're writing: edit the file, restart, activate, and give the agent a task that should trigger it. Agents also activate skills on their own via `activate_skill` — manual toggling is for pinning a procedure you specifically want followed. ## Next steps Turn a procedure's results into a permanent rule. Where skills are authored and toggled. # Tool reference Source: https://docs.amplify.security/agents/tool-reference Every tool an agent can call — the real ceiling on what any agent you write can do. ## Why this page matters An agent's capabilities are exactly the tools it can call. Instructions describe intent; tools determine what's possible. Before writing an agent, check that the work you have in mind maps onto something here — otherwise the agent will try, fail, and narrate the failure. Use these names in an agent's [`allowed-tools`](/agents/writing-an-agent#frontmatter-reference). Omitting `allowed-tools` inherits the default set rather than granting everything. Availability differs slightly by surface. Tools that operate on a cloned target repository or on your organization's connections are available to cloud agents; the CLI runs against your working directory instead. ## Reading and searching code | Tool | What it does | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `shell` | Runs a shell command in the agent's environment. The general-purpose escape hatch — reading files, running builds, invoking any CLI. Output is truncated past a limit, and a blocked-pattern list rejects dangerous commands. | | `ripgrep_search` | Fast regex or literal search across the repository, returning file, line number, and matching text. `.gitignore`-aware. The right choice for plain search, and the fallback for languages without a tree-sitter grammar. | | `read_pdf` | Extracts text from a PDF — useful for threat models, policy documents, and vendor reports. | ## Understanding code structure `code_lineage` provides three structural operations backed by tree-sitter. Coverage is limited to languages with a grammar; on anything else, use `ripgrep_search`. | Operation | What it does | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `find_symbol` | Finds where a function, method, or class is defined and every place it's referenced. | | `call_graph` | Traces callers or callees of a symbol to a bounded depth (1–3). `direction='callers'` finds what invokes it; `callees` finds what it invokes. Computed on demand — no persistent index. | | `ast_query` | Runs a tree-sitter S-expression query against one file and returns captured nodes with line ranges. For precise structural search, like every call expression in a file. | This is how an agent traces taint: find the sink, walk callers back toward a source, and confirm nothing on the path neutralizes the input. ## Scanning | Tool | What it does | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `opengrep_scan` | Runs OpenGrep static rules over the repository for a fast first pass, returning matches for the agent to triage. Defaults to the broad `auto` ruleset. **Does not** record findings — it produces candidates. | | `run_opengrep_detection` | Runs one *stored* OpenGrep [detection](/agents/detections) and emits matches as findings linked to that detection. Refuses non-OpenGrep detections. | | `check_opengrep_rule` | Re-runs a stored detection's rule against a single file, read-only. Zero matches means a fix worked. This is the verification half of patch generation. | ## Confirming exploitability | Tool | What it does | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `generate_poc` | Produces a proof-of-concept for a candidate vulnerability. | | `execute_poc` | Runs a generated PoC against a configured running target to confirm the vulnerability. Passes a safety gate first, and only executes when a target URL is configured — otherwise it returns `executed=false` with a reason and the agent falls back to reasoning-only confirmation. Supports bash, Python, and JavaScript. | | `vuln_poc_evaluation` | Judges the PoC result to decide whether the vulnerability is confirmed. | PoC execution requires an explicitly configured target and clears a safety screen. Without a running target, agents confirm by reasoning — tracing the data flow end to end — rather than by executing an exploit. ## Reading the outside world | Tool | What it does | | ----------- | ----------------------------------------------------------------------------------- | | `web_fetch` | Fetches a URL and extracts its text. Accepts custom headers and an extraction mode. | `web_fetch` performs **reads only** — it takes a URL, headers, and an extraction mode, with no request method or body. There is no built-in tool for writing to a third-party API, so agents cannot create tickets or update external records through it. Console's outbound writes go through [workflow outputs](/workflows/outputs). ## Your vendors' data | Tool | What it does | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_leen_connections` | Lists the vendor connections configured for your organization, returning each connection's id and vendor. The discovery step before either query below. | | `get_leen_vulnerability_findings` | Queries normalized vulnerability findings from a connected vendor. Filters by severity, state, and whether a fix is available; paginates with a cursor. | | `get_leen_vulnerability_finding` | Fetches one vendor finding in full. | These three are the entire vendor-data surface today, and they are scoped to **vulnerability findings**. See [what agents can read](/data/what-agents-can-read) for what that covers and what it doesn't. ## Projects | Tool | What it does | | --------------- | ---------------------------------------------------------------------------------------------------- | | `list_projects` | Lists the repositories connected to your organization, with ids, `owner/repo` names, and clone URLs. | | `clone_project` | Clones a repository into the workspace so the agent can read and search it. | ## Recording results | Tool | What it does | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `report_finding` | Records a confirmed vulnerability, with evidence. This is what makes a result durable rather than conversational. | | `list_findings` | Lists findings already recorded. | | `report_patch` | Attaches a verified remediation patch (a unified diff) to the finding(s) it fixes. Call it only after editing the file **and** confirming the fix. It stores the patch; it does not verify. | | `emit_artifact` | Records a result of a kind your agent declares in [`produces:`](/agents/writing-an-agent#contracts-what-a-step-produces-and-consumes) — Console's own kinds or one you've defined yourself. Rejects `amplify:finding`: findings always go through `report_finding` instead. | | `list_artifacts` | Lists recorded artifacts, optionally filtered by kind. | | `get_artifact` | Fetches one artifact's full content by id. | ## Detections | Tool | What it does | | ------------------ | ------------------------------------------------------------- | | `create_detection` | Stores a new detection. | | `list_detections` | Lists stored detections with id, name, description, and type. | | `get_detection` | Fetches one detection, including its rule body. | | `delete_detection` | Removes a detection. | ## Coordination | Tool | What it does | | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `spawn_agent` | Spawns a sub-agent on a focused task and returns its summary. How a broad job fans out without one agent losing the thread. | | `spawn_multiple_agents` | Spawns several sub-agents. Used to run one child per item — a policy evaluator per detection, for instance. | | `activate_skill` | Loads a [skill](/agents/skills) into the agent's context on demand. | | `add_todo`, `start_todo`, `complete_todo`, `clear_todos` | Maintains the agent's plan as a visible todo list you can watch while it works. | ## Managing agents | Tool | What it does | | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `create_agent`, `get_agent`, `list_agents`, `update_agent`, `delete_agent` | Lets an agent read and write agent definitions — so an agent can help you author another one. | ## Next steps Put these names in `allowed-tools`. Package a procedure an agent can load on demand. # Writing an agent Source: https://docs.amplify.security/agents/writing-an-agent The AGENT.md format — YAML frontmatter plus a Markdown body — and every field it accepts. ## The format An agent is a Markdown document with two parts: 1. **YAML frontmatter** — the machine-readable declaration: name, model, tool permissions, budgets. 2. **A Markdown body** — the agent's instructions. This becomes its system prompt. ```markdown theme={null} --- name: dependency-auditor description: Audits third-party dependencies for known-vulnerable versions and unmaintained packages, and reports each one as a finding. model: anthropic/claude-sonnet-4-6 allowed-tools: - shell - ripgrep_search - web_fetch - report_finding --- You audit third-party dependencies. ## Workflow 1. Locate every manifest and lockfile in the repository. 2. For each direct dependency, determine the resolved version. 3. Flag versions with known advisories, and packages with no release in over two years. 4. Report each one with `report_finding`, citing the manifest path and the resolved version. ## Rules - Report the resolved version from the lockfile, never the range from the manifest. - Do not report transitive dependencies unless the advisory is critical. ``` That's the entire contract. No build step, no registration. ## Frontmatter reference | Key | Required | Type | What it does | | ------------------ | -------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `name` | Yes | string | How the agent is referenced — by workflow steps and by `spawn_agent`. Must be unique. | | `description` | Yes | string, ≤500 chars | What this agent does. **Load-bearing** — see below. | | `model` | No | string | Which model to run. Omit to inherit the default. | | `allowed-tools` | No | string\[] | Restricts the agent to these tools. Omit to inherit. | | `maxIterations` | No | positive int | Budget of reasoning↔tool cycles before the agent is stopped. | | `timeout` | No | positive int (ms) | Wall-clock limit for one execution. | | `produces` | No | list | The kinds of result this agent's step may record. See [contracts](#contracts-what-a-step-produces-and-consumes) below. | | `consumes` | No | list | The kinds this agent's step reads, and how. See [contracts](#contracts-what-a-step-produces-and-consumes) below. | | `mutates-worktree` | No | boolean | Declares that this agent edits files in the repository. See below. | ### Why the description matters Two audiences read `description`, and neither is your agent itself: * **You, choosing agents for a workflow** — the [workflow editor](/workflows/create-a-workflow#agents) and the [agent library](/agents/library) show it as the one-line summary of what an agent does. * **Other agents, deciding whether to delegate to it** — an agent choosing a sub-agent to spawn sees only its name and description, so those two lines are the entire interface it has to go on. Write it as an external, precise statement of the job and its output — not a note to yourself: ```yaml theme={null} # Good — states the job and the output description: Audits third-party dependencies for known-vulnerable versions and unmaintained packages, and reports each one as a finding. # Too vague to be useful to anyone deciding whether to use this agent description: Dependency helper. ``` ### `allowed-tools` restricts, it doesn't grant Listing a tool doesn't create capability that doesn't exist — it narrows the agent to a subset of what the harness already offers. See the [tool reference](/agents/tool-reference) for valid names. Restricting tools is a real design technique, not just hygiene. An agent that shouldn't modify code should not be given `shell`, and a verifier that must stay honest should not be given the ability to report findings. Console's own `policy-fix-verifier` works this way: it is deliberately read-only so its verdict can't be self-serving. ### Budgets: `maxIterations` and `timeout` Both are ceilings, not targets. Leave them unset unless the agent is an outlier. * Raise `maxIterations` for agents that legitimately need many tool calls — a broad scan across a large repository. * Raise `timeout` for **orchestrators**, whose wall clock includes every child they spawn. Set it above the worst-case sum of the children's durations. ## Contracts: what a step produces and consumes When you chain agents into a [workflow](/workflows/create-a-workflow), Console needs to know which step's output feeds which step's input, so it can run steps that don't depend on each other together, wait for the ones that do, and skip a step that has nothing to work on. You declare that with `produces` and `consumes`. ### `produces` The kinds of result this agent's step may record: ```yaml theme={null} produces: - kind: amplify:finding ``` `produces` is a *may*, never a promise — an agent that looked thoroughly and found nothing has still done its job, and nothing checks that a declared kind was actually emitted. A kind is either one of Console's own (prefixed `amplify:`, like `amplify:finding` or `amplify:patch`) or one you define yourself. See [defining your own kind](#defining-your-own-kind) below. ### `consumes` The kinds this agent's step reads, and how it wants them delivered: ```yaml theme={null} consumes: - kind: amplify:finding mode: each ``` | Field | Required | What it does | | ---------- | -------- | ----------------------------------- | | `kind` | Yes | The kind this step reads. | | `mode` | No | `each` or `all`. Defaults to `all`. | | `group-by` | No | Only with `mode: each`. See below. | **`mode: all`** (the default) runs your agent once, with everything matching that kind from earlier in the chain — including an empty set. Use this for a step whose job is to summarize or report on the whole run: "no issues found" is itself a result worth producing, so it needs to run even when there's nothing to say. **`mode: each`** runs a separate copy of your agent per item (or per group, if you set `group-by`). Zero items means the step doesn't run at all — it's recorded as [skipped](/workflows/running#run-statuses), not as having run and found nothing. Use this when your agent's job only makes sense one item at a time, like generating a fix for a single bug. A step can only consume a kind that an earlier step in the same workflow actually produces. Console checks this when you save the workflow, not when it runs. ### `group-by` For a `mode: each` step, `group-by` controls what counts as "one item." By default every result is its own item; naming fields under `group-by` batches results that share the same values into a single item instead. `patch-generator`, Console's built-in patching agent, is the canonical example — one patch should fix every match of the same underlying issue in the same file, not one patch per individual match: ```yaml theme={null} consumes: - kind: amplify:finding mode: each group-by: [detection_id, properties.filePath] ``` Names in `group-by` come from the kind you're consuming — never from anything about how Console stores it: * **A field the kind itself declares**, including one nested inside another declared field, like `properties.filePath` above. * **A documented attribute of that kind.** `amplify:finding` additionally exposes `detection_id` and `severity` this way. * **`id`** — every item is its own group, overriding any default grouping. `amplify:finding` already groups by detection and file when you set no `group-by` of your own, so write `group-by: [id]` explicitly if you want one child per finding instead. An empty `group-by: []` isn't allowed: grouping by nothing means everything is one group, which is what `mode: all` already means. Console rejects it and suggests `[id]` if that's what you meant. A result your grouping can't place — a finding with no detection behind it, say — is left out of that step, with the reason recorded on the step. It still reaches any other step consuming the same kind with `mode: all`. ### `mutates-worktree` Set this to `true` if your agent edits files in the repository: ```yaml theme={null} mutates-worktree: true ``` This states a fact, not a scheduling request. Console uses it to make sure two steps that both edit the checkout never run at the same time and clobber each other's changes. Leave it unset (the default) for an agent that only reads. ### Defining your own kind If `produces` names a kind that doesn't already exist in your organization, attach a `schema:` block and Console registers it the moment you save the agent — no separate setup step: ```yaml theme={null} produces: - kind: scan-report schema: fields: verdict: type: string enum: [clean, issues-found] total_findings: type: integer ``` Each field has a `type` (`string`, `number`, `integer`, `boolean`, `object`, or `array`) and can be marked `required`. A `string` field can restrict its values with `enum`; an `object` field declares its own nested `fields`; an `array` field declares the shape of its `items`. Saving the identical schema again is a no-op. Changing an already-registered kind's shape is not allowed — Console rejects the save rather than reinterpreting artifacts you've already recorded under the old shape. If a kind's shape needs to change, give it a new name. Names starting with `amplify:` are reserved for Console's own kinds. You can *consume* `amplify:finding` or `amplify:patch` in your own agents, but you can't register a `schema:` under that prefix. ## Writing one in the web console Open **Agents** and create an agent. The editor is a Markdown editor with: * **Frontmatter linting** — malformed YAML is flagged as you type. * **A model picker** — selecting a model rewrites the `model:` line in place, so what you see in the frontmatter is always what will run. * **Folders** — organize agents as the list grows. Your organization's agents appear in the [workflow agent picker](/workflows/create-a-workflow#agents) next to the built-in ones. ## Writing one in the CLI The CLI loads agent definitions from the filesystem, so an agent is just a file: ``` ~/.amplify/agents//AGENT.md # available in every session ./agents//AGENT.md # project-local ``` Override those locations with `AMPLIFY_AGENTS_DIR`. Definitions load at startup, so restart the CLI after adding one. ## Shadowing a built-in agent Give your agent the same `name` as one Console ships and yours takes precedence. This is the supported way to change built-in behavior — a workflow step referencing that name keeps working and picks up your version. Start by copying the built-in agent you want to change, editing the body, and keeping the name. You inherit a working structure and only change what you meant to. ## Next steps Valid `allowed-tools` values and what each does. Built-in agents worth reading as examples. # Connections Source: https://docs.amplify.security/data/connections Connect your source control provider and the security and IT vendors you already run. ## Two kinds of connection The **Connections** page handles two different jobs behind one interface: | Kind | What it enables | | --------------------- | ------------------------------------------------------------------------- | | **Source control** | Cloning repositories, pull request triggers, review comments, merge gates | | **Vendor connectors** | Reading signal from the security and IT tools you already run | Source control is what makes Console able to *act* on your code. Vendor connectors are what let it reason about findings your existing stack has already produced. ## Source control ### GitHub Install the Console GitHub App for your organization. You can grant access to every repository or pick a subset; the repositories you grant become [projects](/data/projects). The App is what powers: * Cloning repositories into sandboxes * [Pull request triggers](/workflows/triggers#pull-request-triggers) firing on open, reopen, and new commits * [Review comments](/workflows/outputs#comment-on-triggering-pull-request) * [Merge gates](/workflows/outputs#gate-merging-on-security-review) as required checks * Opening a pull request from a [finding's suggested fix](/data/findings#accepting-a-fix) See [Installation](/install-console#install-the-github-app) for the install flow. ### GitLab Connect a GitLab instance by providing its host URL, the project, and a personal access token. GitLab supports cloning and merge request comments. **Merge blocking is not supported yet** — a [merge gate](/workflows/outputs#gitlab) on a GitLab run is recorded as skipped. ## Vendor connectors Console connects to the security and IT tools you already run, so agents can reason about the findings already sitting in them. Open **Connections**, add a connection, and search the connector catalog. Connectors are grouped by category: | Category | Covers | | ---------- | ------------------------------------------------------ | | **EDR** | Endpoint detection and response | | **AppSec** | Application security scanners — SAST, SCA, and similar | | **VMS** | Vulnerability management | | **CSPM** | Cloud security posture management | | **IDP** | Identity providers | | **GRC** | Governance, risk, and compliance | | **TPRM** | Third-party risk management | | **ITSM** | IT service management and ticketing | The catalog is searchable by vendor name or slug, and a connector spanning more than one category appears under each — AWS Inspector shows up under both AppSec and VMS, for instance. Completing a connection walks you through that vendor's own authorization flow. Console stores the resulting connection and never handles the underlying vendor API key directly — requests are brokered server-side. Connecting a vendor and *reading from it* are two different things. A connection can be established for any connector in the catalog, but what an agent can query today is scoped to **vulnerability findings**. An agent can read your Snyk or Semgrep backlog; it cannot read Jira issues or Cloudflare configuration. Read [what agents can read](/data/what-agents-can-read) before designing a workflow around a connection. ## Which connections do you need? | If you want to | You need | | ---------------------------------------------------- | ---------------------------------------------- | | Ask an agent about your code | A source-control connection | | Run workflows on pull requests | GitHub | | Block merges on security review | GitHub | | Triage an existing scanner backlog against real code | An AppSec or VMS connector | | Just use the CLI on local code | Nothing — the CLI reads your working directory | ## Troubleshooting **A repository isn't available as a project.** The GitHub App installation probably doesn't include it. Adjust the installation's repository access. **An output shows Failed on a run.** Confirm the App is still installed for that repository and has permission to write checks and pull request comments. See [checking delivery](/workflows/outputs#checking-delivery). **The connector catalog is empty or won't load.** The catalog is fetched when you open the dialog, so a transient upstream failure shows there without affecting the rest of the page. Retry. ## Next steps The exact vendor-data surface today. Turn a connection into analyzable code. # Findings Source: https://docs.amplify.security/data/findings Confirmed issues with the agent’s reasoning, the affected code, and often a ready-to-merge fix. ## What a finding is A finding is a vulnerability an agent has confirmed and recorded. It's the durable output of agent work — what survives after the conversation or run is over. Every finding carries: * **Where** — the affected file, and the symbol it's anchored to * **What** — the vulnerability, its classification, and severity * **Why** — the agent's reasoning for believing it's genuinely exploitable * **The fix** — a suggested patch, when one was generated * **Provenance** — the run that produced it, and the [detection](/agents/detections) behind it if there was one The reasoning is the part worth reading: it lays out why the agent believes an attacker can reach the code, which is what makes the finding triageable. ## Where findings come from | Source | How | | ----------------- | ----------------------------------------------------------------------------- | | **Workflow runs** | A scanner or detections step confirms an issue and calls `report_finding` | | **Chat** | An agent investigating on your behalf records what it confirms | | **Detections** | A stored rule matches, and the finding links back to the rule | | **The CLI** | Local scans record findings, and sync to your organization when authenticated | ## Deduplication Findings are deduplicated per project by identity. The same issue rediscovered on a later run updates the existing finding rather than creating a second one, so a long-lived issue doesn't inflate your counts and run history stays readable. Findings are anchored to a **symbol** rather than only a line number, so a finding survives edits that shift line numbers around it. ## Closing the loop Two actions on a finding detail page turn a report into progress. ### Accepting a fix When a finding has a generated patch, the suggested fix section can open a pull request with that patch applied. You review it like any other pull request. Accepting a fix opens pull requests through the GitHub API, so it requires a GitHub-connected project. Other providers can't do this yet, and the action is unavailable when a project has no code host connected. Patches aren't guesses. The agent that generated one edited the file, re-ran the detection to confirm the match was gone, and captured the resulting diff — for policy detections, an independent read-only verifier judged the result. You're reviewing a change that has already been checked, not a proposal. ### Starting a chat **Start a chat** opens a session with the finding's context already loaded — the affected code, the agent's reasoning, and the generated patch if there is one. You type your question in the same step. Use it to ask the things a report can't anticipate: *is this actually reachable in production?*, *what else in this codebase has the same problem?*, *why is this the right fix?* The session is titled after the finding's file and line, so it's easy to find later. This also requires a project connected to a code host — the agent needs to load the code to answer. ## From finding to detection The highest-leverage move on a finding is turning it into a rule. A finding is one instance; a [detection](/agents/detections) catches the whole class from then on, in every repository, without an agent re-deriving it. Ask in chat, or add [`detection-author`](/agents/library#detections) as a workflow step to do it automatically for every finding a scan produces. ## Delivering findings automatically Findings don't have to be pulled — a workflow can push them where your team already works: * [Comment on the triggering pull request](/workflows/outputs#comment-on-triggering-pull-request), with links back to the full finding. * [Gate merging](/workflows/outputs#gate-merging-on-security-review) until review passes or a human approves. ## Next steps Catch the class, not the instance. Comments and merge gates. # Data & connections Source: https://docs.amplify.security/data/overview Agents are only as good as what they can see — your repositories, and the security tools you already run. ## Why this comes first An agent that can't see your environment is guessing. Console's agents don't answer from a static index or a model's memory of open-source code — they read your actual files, run commands against your actual repository, and query the findings your existing tools have already produced. That means the quality of everything downstream depends on what you've connected. ## Two kinds of data | Kind | What it gives the agent | Set up in | | ------------------------------------ | ------------------------------------------------------------------------------------------ | ----------- | | **[Projects](/data/projects)** | Your code. The repositories Console clones and reads. | Projects | | **[Connections](/data/connections)** | Your source control provider, and signal from the security and IT vendors you already run. | Connections | Projects are what an agent reads *from disk*. Connections are what it queries *over the network* — including the pull request events that let a workflow fire on its own. These are prerequisites, not optional extras. Chat can't analyze a repository that isn't connected, and a workflow has nothing to run against without at least one project. ## Two ways to direct it Once the data is connected, Console gives you two ways to put it to work — one interactive, one declarative: * **[Chat](/interactive/chat)** — point an agent at something and ask. Best when you don't yet know what you're looking for, or when the question is a one-off. * **[Workflows](/workflows/overview)** — declare the repositories, the agent chain, and where results go, then let it run unattended. Best when the task is worth repeating. The usual progression is to explore a question in chat, and once the approach works, promote it to a workflow. ## What accumulates As agents work, results collect in your organization rather than evaporating with the conversation: * **[Findings](/data/findings)** — confirmed issues, each with the agent's reasoning, the affected code, and often a suggested fix. * **[Detections](/agents/detections)** — the rules you've built up, which later runs apply automatically. Both become inputs in their own right. A finding can seed a new chat; detections turn a one-time discovery into a permanent check. ## Next steps Give agents code to read. Source control, plus the security stack you already run. Exactly what a connection exposes today. Where confirmed results land. # Projects Source: https://docs.amplify.security/data/projects Connect the repositories Console clones, reads, and analyzes. ## What a project is A project is a repository Console can reach. It carries a name in `owner/repo` form, a clone URL, and the source-control connection that authorizes access. Projects are the unit of targeting everywhere else in the product: * **Chat** clones a project on demand so an agent can read its code. * **Manual workflow runs** ask which projects to run against. * **Pull request triggers** watch a set of projects. * **Findings** are recorded against a project, and deduplicated within it. ## Connecting a repository Projects come from a source-control [connection](/data/connections). Install the Console GitHub App for your organization — granting access to all repositories or a chosen subset — or connect a GitLab instance, and the repositories become available as projects. See [Connections](/data/connections#source-control) for both flows. Access is inherited from the connection. If a repository isn't showing up, the usual cause is that the GitHub App installation doesn't include it — adjust the installation's repository access rather than looking for a per-project setting. ## How code reaches an agent Console never analyzes code in place. Each run gets an isolated sandbox and clones the repository into it, which is why an agent can run builds and execute commands without touching anything of yours. What gets cloned depends on how the run started: | Run type | Cloned | | ------------------- | -------------------------------------------------------------------------------------------------------------------- | | Chat | The project you're asking about | | Manual workflow run | Each selected project, at its default branch — or at a [git ref](/workflows/running#run-a-workflow-manually) you pin | | Pull request run | The pull request's **head** — the proposed code, not the base branch | Agents can also discover and clone projects themselves through `list_projects` and `clone_project`, which is how a chat session pulls in a repository mid-conversation. ## Local code and the CLI The CLI is the exception: it runs against **the directory you started it in**, with no project or clone involved. That makes it the right tool for code you're actively editing, including uncommitted changes that don't exist in any repository yet. Projects still matter to the CLI when it's authenticated, since detections and findings sync to your organization. See [The CLI](/interactive/cli). ## Findings are scoped per project Findings are deduplicated within a project by identity, so the same issue rediscovered on a later run updates the existing finding instead of creating a second one. Run history stays readable and a recurring issue doesn't inflate your counts. ## Next steps Set up source control and vendor connectors. Start a chat against a connected project. # What agents can read Source: https://docs.amplify.security/data/what-agents-can-read Exactly what a vendor connection exposes to an agent today — and what it does not. ## The short version Once a vendor is connected, an agent can do two things: **discover your connections**, and **query normalized vulnerability findings** from them. That's the whole surface today. It's genuinely useful — it's what lets an agent triage an existing scanner backlog against your real code — but it is narrower than the [connector catalog](/data/connections#vendor-connectors), so it is worth being precise before you design a workflow around it. ## What an agent can do | Capability | Tool | | --------------------------------------------------------------------------- | --------------------------------- | | List the connections configured for your organization | `list_leen_connections` | | Query vulnerability findings from a connection, with filters and pagination | `get_leen_vulnerability_findings` | | Fetch one vendor finding in full | `get_leen_vulnerability_finding` | An agent discovers connections first, then queries the one it wants — the same order you'd use by hand. ### What a vendor finding carries Findings are **normalized**, so the shape is the same whether they came from Snyk, Semgrep, or an EDR: | Field | Notes | | ------------------------- | ------------------------------------------- | | `title`, `description` | What the vendor reported | | `severity` | `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO` | | `state` | `OPEN`, `CLOSED`, `REOPENED`, `IGNORED` | | `type` | The finding's classification | | `has_fix` | Whether a fix is available | | `remediation` | The vendor's suggested remediation | | `first_seen`, `last_seen` | Timestamps | | `product` | The product the finding belongs to | | `vulnerabilities` | Associated CVE knowledge-base entries | Filter by severity and state, restrict to findings that do or don't have a fix, and page through large result sets with a cursor. Heavier vendor-specific payloads are deliberately dropped — they'd crowd an agent's context without improving its reasoning. ## What an agent cannot do The vendor surface is scoped to **vulnerability findings**. Connecting a vendor from another category makes the connection available, but does not give agents a way to read that vendor's other data. Concretely, today an agent **cannot**: * Read Jira or other ITSM issues, or create tickets in them * Read cloud or CSPM configuration state * Read identity provider users, groups, or policies * Read GRC controls or evidence * Write anything back to a vendor — update a finding's state, comment, or close it There is also no general-purpose outbound write tool. `web_fetch` performs reads only, with no request method or body, so an agent cannot use it to POST to a vendor API. Console's outbound writes go through [workflow outputs](/workflows/outputs), which today deliver to pull requests and GitHub checks. ## What this is good for The one thing this surface does well is worth building on, because nothing else in your stack does it: **deciding which of your existing findings actually matter.** A scanner tells you a vulnerable function exists in a dependency. It usually can't tell you whether your code ever calls it. An agent with both your vendor findings *and* your source can: ``` Pull the open CRITICAL and HIGH findings from our Snyk connection. For each one, trace whether the vulnerable code path is actually reachable from an entrypoint in this repository. Report the reachable ones as findings and tell me which are noise. ``` That turns a backlog of hundreds into a list of the few that are real — using the vendor for breadth and the harness for judgment. Other things this supports well: * **Cross-referencing tools.** Ask whether two scanners agree, and where they disagree and why. * **Explaining a finding in context.** Take a terse vendor finding and have an agent explain what it means in your codebase specifically. * **Prioritizing by real exposure** rather than by CVSS alone, by checking what's actually deployed and reachable. ## Using it in a workflow Because these are ordinary tools, an agent you write can use them in any workflow step. Grant the tools in [`allowed-tools`](/agents/writing-an-agent#allowed-tools-restricts-it-doesnt-grant) and describe the job: ```markdown theme={null} --- name: backlog-triage description: Triages open vendor vulnerability findings against this repository's code and reports which are genuinely reachable. allowed-tools: - shell - ripgrep_search - code_lineage - list_leen_connections - get_leen_vulnerability_findings - report_finding --- You triage an existing scanner backlog against real code. 1. Call `list_leen_connections` to find the available connections. 2. Query open findings at CRITICAL and HIGH severity. 3. For each, locate the affected package or symbol in this repository and use `call_graph` to determine whether it is reachable from an entrypoint. 4. Report only the reachable ones with `report_finding`, citing the call path. ``` ## Next steps Browse the connector catalog. Grant these tools and put them to work. # Installation Source: https://docs.amplify.security/install-console Install Console on Linux or macOS. ## Prerequisites * Linux or macOS (x86\_64 or arm64) * `curl` available in your `PATH` ## Install Open a terminal and run the following command to launch the installer: ```bash theme={null} curl -sSf https://get-console.amplify.security | bash ``` The installer will download the latest release of Console from GitHub, verify its integrity, install it under your current user at `~/.local/bin/console` (or under a separately configured XDG path), and update your `PATH` if necessary in your shell's rc file. To install a specific version, pass the version tag as an argument: `curl -sSf https://get-console.amplify.security | bash -s -- v1.2.3` After installation, open a new terminal session (or `source` your shell's rc file) so that the updated `PATH` takes effect. ## Configure API keys Console requires an Amplify API key, which you can obtain by going to [Profile > API keys](https://app.console.lab.amplify.security/console/profile/api-keys) from the web interface. Add the following to your `~/.bashrc` or `~/.zshrc`, then `source` the file or open a new terminal: ```bash theme={null} export AMPLIFY_API_KEY="" ``` ## Install the GitHub App Currently, in order to enable Console to access your organization's repositories on GitHub, you need to install the [Amplify Console GitHub App](https://github.com/apps/console-lab). To do so, visit the [install page](https://github.com/apps/console-lab/installations/select_target), select your organization, optionally select specific repositories to grant Console access to, and finally click Install. This should redirect you back to Console's web interface to complete setup. ## Start a session Once your environment is configured, change to a directory containing one of your projects and start Console: ```bash theme={null} cd ~/src/hello-world console ``` This opens an interactive chat session with the AI agent. Try asking it one of the following: * Find and resolve any vectors for XSRF/XSS attacks within this project. * Are there any exposed service endpoints in this project that shouldn't be? or anything else may be relevant for your project. # Chat Source: https://docs.amplify.security/interactive/chat Direct an agent by hand — and promote what works into a workflow. ## What chat is for Chat is the interactive way to use the harness. You give an agent a task, watch it work, and redirect it as it goes. It's the right mode when you don't yet know what you're looking for. The agent doesn't answer from an index — it investigates: reads files, runs commands, traces call paths, and follows the code until it can answer. In a session an agent can: * **Explore your codebase** — read, search, and trace how data flows through the application * **Run commands** in its sandbox to test its own hypotheses * **Load [skills](/agents/skills)** for specialized procedures * **Delegate to sub-agents**, so a broad question can fan out without losing the thread * **Track its plan** as a running todo list you can watch * **Record [findings](/data/findings)** and write patches for what it confirms Ask open-ended questions — *"are there any exposed endpoints in this service that shouldn't be?"* — or point it at something specific and ask it to dig in. ## Watching it work A session shows you what the agent is doing as it works: * **Tool calls** appear as they run, with a status dot and the command or arguments, so you can see the reasoning path. * **The todo list** shows the plan and what's done, and disappears once everything completes. * **The sub-agent tree** appears when the agent delegates, showing which children are running. * **The Tools panel** on the right lists every tool call in the session; click one to jump to it in the transcript. When an agent reaches a wrong conclusion, the tool trail usually shows exactly where it went sideways. ## Sessions Chats persist to your organization, so work doesn't evaporate when you close the tab. | Action | Notes | | ------------ | -------------------------------------------------- | | **New chat** | Starts a fresh session | | **Rename** | Sessions title themselves from your first message | | **Archive** | Keeps the session read-only; unarchive to continue | | **Delete** | Permanent, with a confirmation | A session survives a page reload mid-turn — reconnecting picks the running turn back up rather than losing it. ## Choosing a model The model picker in the header sets the model for the session, and you can switch **mid-conversation**. Switching carries your context forward: Console summarizes the conversation so far and hands that summary to the new model, marking the switch point in the transcript. If a turn is in flight, you'll be asked to confirm, since switching cancels it. Use a faster model to explore, then switch to a more capable one for the hard part. ## Cancelling a turn Press Escape while a turn is running. The agent stops and the transcript notes the interruption, so you can redirect without starting over. Anything already recorded — findings, patches — stays. ## Starting from a finding The fastest way into a productive session is from a [finding](/data/findings). **Start a chat** on any finding opens a session with the affected code, the agent's reasoning, and any generated patch already loaded, and you type your question in the same step. ## Promote it to a workflow Chat is exploratory by design. Once you've asked the same question a third time, it belongs in a [workflow](/workflows/overview): | In chat | As a workflow | | --------------------------------- | -------------------------------------------------------------- | | You pick the repository each time | The trigger names the repositories | | You type the task | The workflow's description and agent chain encode it | | You read the answer | [Outputs](/workflows/outputs) deliver it where your team works | | Runs when you remember | Runs whenever its trigger fires | The translation is usually direct: the prompt you refined becomes the workflow description, and the agents you found useful become the chain. ## Next steps Same agents, against your local working directory. Automate what worked in chat. # The CLI Source: https://docs.amplify.security/interactive/cli Run the same agents in your terminal, against the code you have checked out right now. ## Why use the CLI The CLI runs the same agents as the web console, with one important difference: it works on **the directory you started it in**, on your machine. That makes it the right tool for code you're actively editing. An agent can look at uncommitted changes, work-in-progress branches, and files that exist nowhere but your laptop — none of which a cloud sandbox can reach. See [Installation](/install-console) to get set up. ## Web console vs. CLI The agents' capabilities are the same. What differs is where they run and what they can reach. | | Web console | CLI | | ----------------------- | --------------------------------------------------- | --------------------------------------------------------------------- | | Runs in | An isolated cloud sandbox | Your own machine | | Code it analyzes | Clones connected projects on demand | The directory you started it in | | Uncommitted changes | Not visible | Visible | | Chat history | Saved to your organization; resume, rename, archive | Not persisted between sessions | | Choosing a model | Model picker | `/model` | | Slash commands | Not available | `/help`, `/model`, `/skills`, `/skill`, `/context`, `/clear`, `/quit` | | One-shot prompts | Not available | `console --prompt "..."` | | Authoring skills | Not available | Files on disk | | Starting from a finding | Yes | No | | Works offline | No | Yes | ## Starting a session ```bash theme={null} cd ~/src/hello-world console ``` Ask it something: * *Find and resolve any vectors for XSRF/XSS attacks within this project.* * *Are there any exposed service endpoints in this project that shouldn't be?* The footer shows whether you're connected to Amplify Cloud (and which organization) or running offline, plus the active model. ## One-shot prompts Run a single prompt and exit — useful in scripts, git hooks, and CI: ```bash theme={null} console --prompt "Scan this project for vulnerabilities" ``` It prints the agent's final answer and exits. Also `--version`. ## Slash commands | Command | Aliases | What it does | | ---------------- | ------------- | ------------------------------------------- | | `/help` | `/?` | Lists all commands | | `/model` | | Opens the model picker | | `/skills` | | Lists available skills and which are active | | `/skill ` | | Toggles a skill on or off | | `/context ` | | Switches organization | | `/clear` | | Clears the conversation | | `/quit` | `/q`, `/exit` | Exits | Type `/` to get an autocomplete dropdown rather than memorizing them. ### The model picker `/model` opens a tabbed picker: * **Popular** — a curated shortlist. Works even if the model catalog is unreachable. * **Browse** — grouped by provider; drill into one to see its models. * **Search** — substring match across the full catalog, with pricing and context length per model. Switching models mid-session carries your context forward via a summary, the same as the web console, and the transcript notes the switch. ## Authoring skills and agents The CLI is where [skills](/agents/skills) are authored, because it loads both skills and agents from the filesystem: ``` ~/.amplify/skills//SKILL.md # available in every session ~/.amplify/agents//AGENT.md ./skills//SKILL.md # project-local ./agents//AGENT.md ``` Override with `AMPLIFY_SKILLS_DIR` and `AMPLIFY_AGENTS_DIR`. Both load at startup, so restart after adding one. The loop is quick: write the file, restart, `/skill ` to activate, then give the agent a task that should trigger it. ## Offline mode Without an Amplify API key the CLI runs fully local: detections and findings go to a SQLite database under `~/.amplify` instead of your organization, and the footer shows a red **offline mode** indicator. Once authenticated, detections write through to your organization instead, so work done locally shows up for your team. ## Cancelling and exiting Ctrl+C cancels a running turn and leaves the session open so you can redirect. Pressing it again when nothing is running exits. ## What the CLI doesn't do * **No persistent chat history.** Sessions aren't saved; `/clear` is final and there's no resuming a past conversation. Findings and detections do persist. * **No input history recall.** Arrow keys don't walk previous messages. * **No workflows.** Workflows are a cloud feature — the CLI runs agents interactively, one session at a time. ## Next steps The CLI is where skills are authored. Setup and API keys. # Introduction Source: https://docs.amplify.security/introduction Amplify Console is an AI harness for security — you define the agents, give them context, and automate them as workflows. ## What is Console? Console is Amplify Security's AI harness for security work. It supplies the machinery — LLM orchestration, tool execution, isolated sandboxes, sub-agent delegation — and you supply the domain logic: the agents that reason, the skills they follow, and the detections they enforce. Teams get the most out of Console by writing their own agents and detections — encoding the security questions that matter for their codebase and their stack, then pointing those agents at them. Console is currently in alpha, undergoing rapid development. Contact [support@amplify.security](mailto:support@amplify.security) if you would like to try it out and work with us to help our project come to fruition! ## Three ideas Everything in Console fits into one of three layers, and they build on each other in this order. The agents, skills, and detections that do the work. All of them are yours to write. Repositories and vendor connections, so agents reason about your actual environment. Chain agents into automation that runs on every pull request and produces real artifacts. ### 1. Agents and detections An **agent** is a Markdown file with YAML frontmatter: the frontmatter declares its name, model, and which tools it may use, and the body is its instructions. That's the whole format — you write an agent in a text editor, and it runs. Agents delegate to sub-agents, load **skills** for specialized procedures, and run **detections** — reusable rules that outlive any single conversation. Console ships a library of agents and skills to start from; detections are yours to build up as you go. Anything you write sits alongside the built-ins as an equal. ### 2. Data and connections An agent with nothing to look at is just a chatbot. Console draws on two sources: * **Projects** — the repositories it clones and reads. * **Connections** — your source control provider, plus the security and IT vendors you already run, added from the [connector catalog](/data/connections#vendor-connectors). You put that to work two ways: interactively in **chat**, or declaratively in a **workflow**. ### 3. Workflows Workflows are where it comes together. A workflow chains agents into an ordered sequence, fires on the **triggers** you configure, and routes whatever it produces to the **outputs** you attach. Run one on demand, or let events in your connected systems start it for you. ## Two interfaces The same agents run in both places. What differs is where they run and what code they can reach. | | Web console | CLI | | ---------------- | ---------------------------------------- | ------------------------------------------------------------ | | Runs in | An isolated cloud sandbox | Your own machine | | Code it analyzes | Clones your connected projects on demand | The directory you started it in | | Best for | Team work, automation, anything shared | Code you're editing right now, including uncommitted changes | See [Chat](/interactive/chat) and [The CLI](/interactive/cli) for the differences in detail. ## Get started Connect a repository, ask an agent a question, and build your first workflow. Run Console in your terminal on Linux or macOS. # Enable Pull Request Comments Source: https://docs.amplify.security/legacy/guides/enable-comments A how-to for enabling Amplify comments on pull requests for projects currently running silent. ## Why am I not seeing comments on my Pull Requests? The Amplify platform allows for projects to run silently, meaning that while we are actively detecting vulnerabilities and generating code fixes for your project, we are not commenting on your Pull Requests. This is caused by not enabling commenting on the projects when they are added to the Amplify platform. Follow along with this guide to enable commenting for your projects. ## What comments can I expect Amplify to make on my Pull Requests? Amplify can be configured to make two different types of comments on your Pull Requests. The first type of comment is a notification that one or more vulnerabilities have been detected in the new code. The second type of comment is a notification that a code fix is available for a detected vulnerability. Amplify can also be configured to comment with "Approvals" on Pull Requests that have no detected vulnerabilities. ### Vulnerability notification Vulnerability notifications are made on Pull Requests when Amplify detects vulnerabilities in the new code. These notifications are enabled in the Amplify App by enabling `Merge Comments` for the project. Vulnerability Notification Vulnerability Notification ### Code fix notification Code fix notifications are made on Pull Requests when a Code Fix is available for a detected vulnerability. These notifications are enabled in the Amplify App by enabling `Merge Comments` for the project. Code Fix Notification Code Fix Notification ### Approval notification Approval notifications are made on Pull Requests when no vulnerabilities are detected in the new code. These notifications are enabled in the Amplify App by enabling `Merge Approvals` for the project. Approval Notification Approval Notification ## How to enable commenting To enable commenting, Sign in to the [Amplify App](https://app.amplify.security) and select `Projects` on the Navigation Bar. From the Projects page, you can enable commenting on your projects by selecting the appropriate options in the `Merge Comments` and `Merge Approvals` columns. Project Configuration Project Configuration Alternatively, Sign in to the [Amplify App](https://app.amplify.security), select `Projects` on the Navigation Bar, then select the `Settings` tab from the Project's page. From the Project's Settings you can enable commenting on your projects by selecting the appropriate options under **Integrations**. Project Settings Project Settings # Ignoring Vulnerabilities Source: https://docs.amplify.security/legacy/guides/ignoring-vulns A how-to for suppressing vulnerability notifications inline and by using an .amplifyignore file. There are times when you simply don't need to worry about a vulnerability. Testing code that only runs locally and never gets deployed and code which have potential vulnerabilities mitigated elsewhere, like in infrastructure, are two examples of these scenarios. Let's look at how to ignore these vulnerabilities on the Amplify platform. # What is an "Ignored" vulnerability? On the Amplify platform, and Ignored vulnerability is considered to be ***Acknowledged*** with ***Ignored*** given as the reason. Acknowledgement does not mean that the vulnerability is legitimate! Acknowledgement simply means that someone is aware that one or more security scanners flagged a particular piece of code as vulnerable but the vulnerability is not considered active or as truly positive. Acknowledged vulnerabilities do not trigger notifications and they do not display as prevented or merged vulnerabilities in Amplify's metrics. Acknowledged vulnerabilities, including those which have been ignored, may be viewed on the Vulnerabilities page under the **Acknowledged Vulns** tab. Acknowledged Vulns tab with two ignored vulnerabilities shown # How to Ignore a vulnerability There are two ways to ignore a vulnerability currently in the Amplify platform. The first is with a code comment on the vulnerable code line. The second is by using a `.amplifyignore` file. ## Ignoring with a code comment To ignore a vulnerability with a code comment, simply append a comment to the vulnerable line which contains the string `@amplify-ignore`. For example: ```tsx theme={null} models.sequelize.query(`SELECT * FROM Products WHERE ((name LIKE '%${criteria}%' OR description LIKE '%${criteria}%') AND deletedAt IS NULL) ORDER BY name`) // @amplify-ignore ``` The `@amplify-ignore` code comment must be made on the vulnerable line as reported by Amplify. Commenting on the lines above or below the vulnerable line will not currently ignore the vulnerability. ## Ignoring with a `.amplifyignore` file To use a `.amplifyignore` file to ignore vulnerabilities, first create a file in the root of your project directly named `.amplifyignore`. This file mostly follows the familiar syntax of the well-known `.gitignore` file, for which the specification can be found in the [Git documentation](https://git-scm.com/docs/gitignore). The below section, **Pattern Format**, is for the most part verbatim to the Git documentation, but has been updated to reflect the `.amplifyignore` filename and omit patterns which reference relative paths, as Amplify only supports a `.amplifyignore` file in the root of the project. ### Pattern Format * A blank line matches no files, so it can serve as a separator for readability. * A line starting with # serves as a comment. Put a backslash ("`\`") in front of the first hash for patterns that begin with a hash. * Trailing spaces are ignored unless they are quoted with backslash ("`\`"). * An optional prefix "`!`" which negates the pattern; any matching file excluded by a previous pattern will become included again. It is not possible to re-include a file if a parent directory of that file is excluded. Git doesn't list excluded directories for performance reasons, so any patterns on contained files have no effect, no matter where they are defined. Put a backslash ("`\`") in front of the first "`!`" for patterns that begin with a literal "`!`", for example, "`\!important!.txt`". * The slash "`/`" is used as the directory separator. Separators may occur at the beginning, middle or end of the `.amplifyignore` search pattern. * If there is a separator at the end of the pattern then the pattern will only match directories, otherwise the pattern can match both files and directories. * For example, a pattern `doc/frotz/` matches `doc/frotz` directory, but not `a/doc/frotz` directory; however `frotz/` matches `frotz` and `a/frotz` that is a directory (all paths are relative from the `.amplifyignore` file). * An asterisk "`*`" matches anything except a slash. The character "`?`" matches any one character except "`/`". The range notation, e.g. `[a-zA-Z]`, can be used to match one of the characters in a range. Two consecutive asterisks ("`**`") in patterns matched against full pathname may have special meaning: * A leading "`*`" followed by a slash means match in all directories. For example, "`*/foo`" matches file or directory "`foo`" anywhere, the same as pattern "`foo`". "`*/foo/bar`" matches file or directory "`bar`" anywhere that is directly under directory "`foo`". * A trailing "`/**`" matches everything inside. For example, "`abc/**`" matches all files inside directory "`abc`", relative to the location of the `.gitignore` file, with infinite depth. * A slash followed by two consecutive asterisks then a slash matches zero or more directories. For example, "`a/**/b`" matches "`a/b`", "`a/x/b`", "`a/x/y/b`" and so on. * Other consecutive asterisks are considered regular asterisks and will match according to the previous rules. # GitHub Source: https://docs.amplify.security/legacy/integrations/github Secure your GitHub repositories with Amplify. ## Overview The Amplify GitHub App integrates the Amplify Security Platform with GitHub to secure your GitHub repositories and provide actionable security code fixes directly to developers in Pull Requests. The Amplify Security GitHub integration is currently in beta. Documentation and functionality may change frequently. View the Amplify Security GitHub App on the GitHub Marketplace. View the Amplify Security GitHub Action on GitHub. ## Components ### GitHub App The Amplify GitHub App installs in your GitHub organization and allows Amplify to make Requests to the GitHub API on behalf of your organization. Amplify uses these privileges to receive notifications about Pull Requests and GitHub Actions Workflows, and to commit security code fixes directly to your repositories when approved by a user. Amplify also has the ability to open Pull Requests and comment on Pull Requests to provide security feedback through the GitHub App. ### GitHub Action The Amplify GitHub Action is an action that runs configured security tools on your GitHub repository and sends security findings to the Amplify Platform. The Amplify GitHub Action is installed into the GitHub repositories added to the Github App when you approve the installation Pull Requests created by the Amplify Platform. ### Amplify Workflow The Amplify GitHub Actions Workflow is the workflow installed in any GitHub repositories added to the Amplify Platform. This Workflow runs the Amplify GitHub Action on every Pull Request and on every push to the repository's `main` or `develop` branch. ```yaml .github/workflows/amplify.yml theme={null} --- name: Amplify Security on: pull_request: {} workflow_dispatch: {} push: branches: ["main", "develop"] permissions: contents: read id-token: write jobs: amplify-security-scan: name: Amplify Security Scan runs-on: ubuntu-latest if: (github.event_name != 'pull_request' || github.repository_id == github.event.pull_request.head.repo.id) && github.actor != 'dependabot[bot]' steps: - name: Checkout uses: actions/checkout@v5 - name: Amplify Runner uses: amplify-security/runner-action@main ``` The Amplify Platform currently relies on the name of the Workflow to track and display GitHub Workflows correctly. Do not change the name of the Workflow. This restriction will be lifted soon. ## Configuration ### Scanning branches other than `main` or `develop` By default, this Amplify workflow runs on all Pull Requests and on every push to the repository's `main` or `develop` branch. To run on any additional branches, add them to the list of branches in `.github/workflows/amplify.yml`. For example, we will modify the section below to also execute on the `staging` branch. Note that the change in syntax from the above YAML is simply for readability. ```yaml .github/workflows/amplify.yml theme={null} --- name: Amplify Security on: pull_request: {} workflow_dispatch: {} push: # this is equivalent to '["main", "develop", "staging"]' branches: - main - develop - staging ``` # Hosted GitLab Source: https://docs.amplify.security/legacy/integrations/gitlab Secure your GitLab projects with Amplify. ## Overview The Amplify Security Platform integrates with GitLab's CI/CD infrastructure to secure your GitLab projects and provide actionable security code fixes directly to developers within their merge requests. The Amplify Security GitLab integration is currently in beta. Documentation and functionality may change frequently. View the Amplify Security GitLab Component on GitLab. ## Components ### GitLab Component Amplify provides a GitLab component that must be installed in a GitLab Pipeline for any GitLab projects added to the Amplify Platform. The following example pipeline configuration runs Amplify's Runner component on every merge request. Using the `main` branch will ensure you're always using the latest stable version of the component. Pre-release or experimental versions will never be in `main`. ```yaml .gitlab-ci.yml theme={null} --- stages: [test] include: - component: gitlab.com/amplify-security/components/runner@main ``` #### Specifying a component version If you want to specify a particular Amplify component version, you can use our semantic version tags instead of `main`. For example: ```yaml .gitlab-ci.yml theme={null} --- stages: [test] include: - component: gitlab.com/amplify-security/components/runner@0.1.0 ``` To find the latest tagged version, please refer to the [list of tags on GitLab](https://gitlab.com/amplify-security/components/-/tags). # Introduction Source: https://docs.amplify.security/legacy/introduction New to Amplify Security? Start here. Secure Software ## What is Amplify Security? Amplify Security is a cloud-native security platform that integrates industry leading security tools into your development workflow and provides automatically generated code fixes for security vulnerabilities. Amplify Security is currently in beta. Documentation and application functionality may change frequently. ## How Amplify secures your code Amplify Security runs configured security tools on codebases that have been added to Amplify using our [GitHub Action](https://github.com/amplify-security/runner-action) or [GitLab Component](https://gitlab.com/amplify-security/components/). Amplify notifies developers of new vulnerabilities directly in their pull/merge requests and provides code fixes when available. Official documentation for running Amplify Security on Bitbucket is coming soon! Our dedication to securing your code doesn't stop at identifying new vulnerabilities. The Amplify platform continuously runs configured security tools on your codebase and generates new code fixes as they become available for existing vulnerabilities. Once you've reviewed the available code fixes, you can open a PR to apply the fix within the Amplify platform. ## Developer first security Amplify is designed and built by developers, for developers. We're tired of security products that both get in the way and don't actually improve security just as much as you are. Our engineering team will never stop thinking about what developers actually need to develop secure code with zero reduction to velocity and without security theater. ## Core components All of the core components that you need to secure your code with Amplify are open source and available for review. View the Amplify Security GitHub App on the GitHub Marketplace. View the Amplify Security GitHub Action on GitHub. View the Amplify Security GitHub Action on GitHub. The Amplify Runner is open source and available to view on GitHub. The Amplify Runner Docker image is available on Docker Hub. Have a suggestion to improve our documentation? Contribute changes with a pull request to our [Docs](https://github.com/amplify-security/docs) repository on GitHub. # Quickstart Source: https://docs.amplify.security/legacy/quickstart Onboard your projects to Amplify in under 5 minutes. ## Overview We're going to walk you through the steps to onboard your projects to Amplify. The onboarding process is designed to be fully guided, so if you'd rather just follow along in the Amplify App and skip this guide, you can do that too. ### What to expect During onboarding you will: 1. Install the Amplify GitHub App. 2. Select which projects you want to onboard. 3. Approve the Pull Requests that Amplify will open for you in selected projects. These Pull Requests add the Amplify Security GitHub Actions Workflow. You will need permission to install a GitHub App for the organization you wish to secure with Amplify in order to complete this Quickstart guide. ## Quickstart ### Sign Up To get started, navigate to the Amplify App at or by using the Sign In button in the top right corner of this page. Sign Up Sign Up Select *Sign Up* to continue. Sign Up Providers Sign Up Providers Select *Sign up with GitHub* to continue. Support for GitLab and Bitbucket is coming soon! ### Authenticate with the Amplify GitHub App You will be redirected to GitHub to authenticate using the Amplify GitHub App. GitHub OAuth GitHub OAuth Select *Authorize Amplify* to continue. ### Install the Amplify GitHub App Once authenticated, you must install the Amplify GitHub App in the GitHub organization you want to secure with Amplify. Install App Install App Select *Redirect to GitHub to allow access to your organization* to continue. You will be redirected to GitHub. Install the GitHub Amplify App in the organization you want to secure. After installation, you will be redirected back to Amplify to continue the onboarding process. ### Accept terms & conditions You must accept the terms and conditions of the beta agreement to continue. Terms and Conditions Terms and Conditions ### Select projects to secure After authenticating with the Amplify GitHub App, you will be redirected back to the Amplify App to choose which projects you want to secure with Amplify. Select Projects Select Projects Select all projects you would like to secure with Amplify and select *Next*. ### Select security tools to run You will now be prompted to choose which security tools Amplify will run when scanning your projects. Select Tools Select Tools Select *Open Installation PRs* to continue. ### Approve installation PRs Amplify will now open Pull Requests in the selected projects to add the Amplify Security GitHub Actions workflow. You will need to approve these PRs to enable Amplify scanning in your projects. Approve PRs Approve PRs The Amplify App will automatically reflect the status of the PRs as they are merged. Merged PRs Merged PRs Select *Finish* to complete the onboarding process. # Using the Sample Repository Source: https://docs.amplify.security/legacy/sample-project Try out Amplify using our example repository with pre-existing vulnerabilities. ## Overview During setup, you may not have a vulnerable project to test Amplify with. To help you get started and quickly test out Amplify, we provide an example repository with preexisting vulnerabilities that you can add to your GitHub account. An example project based on Juice Shop, a Javascript web application for security testing. ## Usage From GitHub, go to [the new repository creation page](https://github.com/new). Under *Owner*, select the organization or user you added to Amplify, give a name to your example project, e.g. `my-vulnerable-project`, and create the repository. You can also select *Private* if you wish to keep it hidden. **For GitHub CLI users** To quickly perform this step, you can run the following command, replacing `ORGNAME`/`REPONAME` as needed: `gh repo create --private ORGNAME/REPONAME` Copy the example project and all its branches to your local machine. If using the command line, the following should suffice: ```bash theme={null} git clone --mirror https://github.com/amplify-security/amplify-example-project.git my-vulnerable-project ``` You'll now need to update your local copy of the example project to point to your own repository, and then sync your local copy to it. Using the command line, this can be done with the following commands: ```bash theme={null} cd my-vulnerable-project git remote set-url origin git@github.com:USERNAME/my-vulnerable-project.git git push --mirror origin ``` If you picked "Only select repositories" when installing the Amplify GitHub App, be sure to update the list of allowed repositories to include the new repository. [Click here for settings under your user account](https://github.com/settings/installations), otherwise go to `https://github.com/organizations/ORGNAME/settings/installations` for settings under an organization, replacing `ORGNAME` with your organization name. You can skip this if you selected "All repositories" during installation. If you're in the middle of setup, the repo should automatically show up in the list of projects to add. Otherwise, go to the *Projects* page and click *Add Project* to start the process. Visit your repository on GitHub and create a pull request or two from the example branches, such as `vulns/sql-injection`. Amplify will automatically scan the contents of your pull requests, report any vulnerabilities it finds, and provide code fixes when available. ## GitLab and Other Users If you're using GitLab or another platform, you can for the most part follow the above steps, substituting those using GitHub's web interface with the equivalent on your VCS platform. For succinctness, the following is a demonstration for GitLab, provided you've set up a new project on GitLab: ```bash theme={null} git clone --mirror https://github.com/amplify-security/amplify-example-project.git my-example-project cd my-example-project git remote set-url origin git@gitlab.com:USERNAME/my-example-project.git git push --mirror origin ``` # Quickstart Source: https://docs.amplify.security/quickstart Connect a repository, ask an agent a question, and turn the answer into automation. This walks through all three layers of Console in one pass: connect your **data**, use an **agent** interactively, then automate it as a **workflow**. Budget about twenty minutes. ## 1. Connect a repository Sign in to the web console and open **Connections**. Install the Console GitHub App for your organization, granting access to at least one repository you're comfortable experimenting on. The repositories you grant appear under **Projects** — the code agents can read. Pick a real repository rather than an empty one. Agents reason about actual code, so a repository with real application logic gives you a far better sense of what Console does. ## 2. Ask an agent something Open **Console** in the sidebar and start a new chat. Ask a question about the repository you just connected: > Look at this repository and tell me where user input reaches a database query without parameterization. Watch what happens. The agent clones the repository, reads files, searches, and traces call paths — and you see each tool call as it runs. It decides what to look at next based on what it just found. Try following up. *Is that actually reachable from an HTTP handler?* The agent goes back to the code to answer. If it confirms something, it records a [finding](/data/findings) — durable, with its reasoning attached. ## 3. Write an agent The built-in library covers a lot, but Console is most useful when the agents are yours. Open **Agents** and create one: ```markdown theme={null} --- name: secrets-auditor description: Finds credentials, API keys, and tokens committed to the repository, and reports each one as a finding with the file and line. model: anthropic/claude-sonnet-4-6 allowed-tools: - shell - ripgrep_search - report_finding --- You audit a repository for committed secrets. 1. Search for common credential patterns — API keys, private keys, connection strings, bearer tokens. 2. For each candidate, read the surrounding code to judge whether it's a real credential or a placeholder, test fixture, or example. 3. Report only real credentials with `report_finding`, citing file and line. Do not report obvious placeholders (`xxx`, `changeme`, `example.com`), values clearly loaded from the environment, or anything under a fixtures directory. ``` Save it. That's a working agent — YAML frontmatter declaring its name, model, and tools, plus instructions as the body. See [writing an agent](/agents/writing-an-agent) for every field. ## 4. Automate it Open **Workflows** and click **New workflow**. | Field | What to enter | | --------------- | ------------------------------------------------------------------------------ | | **Name** | `Secrets check` | | **Description** | `Audit pull requests for committed credentials and comment on anything found.` | | **Triggers** | Add **On pull requests**, and select your repository | | **Agents** | Add `secrets-auditor` | | **Output** | Add **Comment on triggering pull request** | Click **Save**. The description is just a summary for your own reference — the agent you wrote in step 3 already carries its own instructions, and those are what actually run. See [create a workflow](/workflows/create-a-workflow#description). ## 5. Run it Click **Run workflow**, select your repository, and leave the git ref empty to use the default branch. Console provisions a sandbox, clones the repository, and runs your agent. Click **View runs** to watch the chain: each step shows status and duration as it completes, and the run page lists findings and output deliveries when it's done. Your pull request trigger is live too — open a pull request in that repository and the workflow fires on its own, against the pull request's head. The **Comment on triggering pull request** output only acts on pull-request runs, so it's skipped on the manual run you just did. Open a pull request to see it deliver. ## What you just built * **Data** — a connected repository agents can read * **An agent** — your own, defined in YAML frontmatter and Markdown * **Workflow** — that agent running automatically on every pull request, reporting to your team Each layer is replaceable independently. Swap the agent, add a step, change where results go — the rest keeps working. ## Where to go next Skills, detections, and the full tool surface. Connect a scanner and find what's actually reachable. Block merging until security review passes. Run the same agents on local, uncommitted code. # The agent chain Source: https://docs.amplify.security/workflows/agent-chain How workflow steps depend on each other, pass results forward, and how to order them. ## How the chain runs The agents you add to a workflow form a chain, and what each one **[produces and consumes](/agents/writing-an-agent#contracts-what-a-step-produces-and-consumes)** decides how it actually runs: 1. A step becomes eligible to run once every step it depends on has **settled** — either finished normally or been legitimately [skipped](/workflows/running#run-statuses). A step with nothing it depends on is eligible immediately. 2. **Steps with no dependency between them may run at the same time.** The order you drag them into sets which *earlier* steps a later one is allowed to draw on — a step can only consume a kind an earlier step in the list produces — but it doesn't by itself force one step to wait for another that it doesn't actually need. 3. **Two steps that both edit the repository never run at the same time**, whether or not they depend on each other — they'd be racing on the same checkout. This is `mutates-worktree` on the agent, not something you configure per workflow. 4. Each step is told what triggered the run (for a pull-request run: the PR number, head and base commits, the diff) and reads the actual results earlier steps recorded of the kinds it consumes — not a text summary of what an earlier step said it did. 5. **If a step fails, nothing that depends on it runs, and the run ends in error.** Workflow steps do not retry by default. A step whose input turns out to be empty runs **zero times** and is recorded as **skipped** — a distinct outcome from *failed* and from *ran and found nothing*. See [run statuses](/workflows/running#run-statuses). ## Passing results between steps You don't wire inputs and outputs together by hand. What flows from one step to the next is exactly what the consuming agent's `consumes` names — the actual results (findings, patches, or a kind of your own) that an earlier step's `produces` recorded, not a prose account of what happened. What this does **not** do is let you transform or filter results between steps. If you need different handling, that belongs inside an agent, not between them. ## Choosing agents Any agent can be a step — Console's or your own. Your organization's agents appear in the picker alongside the built-in ones, and Console treats them identically. * For what ships with Console and what each is for, see [the agent library](/agents/library). * To write your own, see [writing an agent](/agents/writing-an-agent). A few agents in the library are designed to be spawned *by* other agents rather than used as steps directly — [noted here](/agents/library#agents-spawned-by-other-agents). ## Ordering The rules of thumb: * **Broad before narrow.** Discover first, then act on what was discovered. * **Declare what a step actually needs.** Two steps that don't consume each other's output can run concurrently; a step only waits on the steps its `consumes` names. * **Expensive before dependent.** If a step fails, nothing depending on it runs — so put the step most likely to fail where it costs least. * **One step is a valid chain.** A single scanner plus an [output](/workflows/outputs) is a complete, useful workflow. Don't add steps for symmetry. ## Common chains | Goal | Chain | | ---------------------------------------------------- | ----------------------------------------------------- | | Fastest signal | `vulnerability-scanner-basic` | | Balanced scan | `vulnerability-scanner-standard` | | Deepest audit | `vulnerability-scanner-comprehensive` | | Turn findings into permanent rules | `vulnerability-scanner-standard` → `detection-author` | | Apply everything you've already vetted | `detections-runner` | | Apply everything you've already vetted, and patch it | `detections-runner` → `patch-generator` | ## Editing a chain In the workflow editor the chain is drawn left to right as pills with arrows: * **Add** with the **+** button, which searches the agent library. * **Reorder** by dragging a pill. * **Remove** via the grip icon on a pill. Between 1 and 20 steps. ## Next steps What's available to chain. Deliver what the chain produces. # What a run produces Source: https://docs.amplify.security/workflows/artifacts Findings, patches, and the artifact model behind them. ## Two kinds of result A workflow run produces results in two places, and it's worth keeping them straight: | Result | Where it lives | Durable? | | ------------------------ | ------------------------------------------------------ | --------------------------------------------- | | **Findings and patches** | Your organization, attached to the project and the run | Yes — they outlive the run | | **Output deliveries** | The pull request, as comments or a check | Yes, but they're a *copy* delivered elsewhere | The run itself is a record — status, per-step timings, which agents ran. The *results* are what the agents recorded while running. ## Findings The primary output. When an agent confirms a vulnerability it records a [finding](/data/findings) with the affected file and symbol, its reasoning, and provenance back to the run and the detection that produced it. Findings are deduplicated per project, so a recurring issue updates in place rather than accumulating duplicates across runs. ## Patches When patch generation is part of the chain, an agent that fixes a finding records the resulting diff against that finding. Patches are verified before they're recorded, not proposed speculatively: the agent edits the file, re-runs the detection to confirm the match is gone — for policy detections, an independent read-only verifier judges the result — and only then captures the diff. That's why a finding's suggested fix can [open a pull request](/data/findings#accepting-a-fix) directly. ## The artifact model Underneath findings and patches, Console stores results as **artifacts**. An artifact has: * A **kind** — what type of thing it is * A **summary** — a short description * **Files** — one or more, each with a path, a content type, and its contents * **Subjects** — optionally, the findings the artifact addresses This model is deliberately open-ended: an artifact is *a set of files an agent produced, with provenance and optional linkage to the findings it relates to*. Nothing about it is specific to security. A risk assessment, a compliance report, a threat model, a generated test suite are all describable in the same shape. Console ships several kinds of its own — findings and patches among them — but your own agents can define and record their own, with no setup outside the agent's own definition. See [defining your own kind](/agents/writing-an-agent#defining-your-own-kind) for how to declare one. A kind's shape is fixed once it's registered. Saving the identical shape again is a no-op; changing it is rejected outright, so a kind never silently reinterprets artifacts you've already recorded under the old shape. If a kind's shape needs to change, give it a new name. ## Getting results out Recording a result and delivering it are different steps. A run's results sit in Console until an [output](/workflows/outputs) pushes them somewhere: | Output | Delivers | | ---------------------------------- | ---------------------------------------------------------------- | | Comment on triggering pull request | Findings as review comments, with links back to the full finding | | Gate merging on security review | A required check reflecting the run's verdict | Both act on the pull request that triggered the run, so they're skipped on manual runs. These two destinations are the whole set today. There's no built-in delivery to ticketing systems, chat tools, or arbitrary webhooks, and no general outbound-write tool — `web_fetch` performs reads only. If you need results elsewhere, read them from Console rather than expecting a workflow to push them. ## Inspecting a run's results Open the run from **Runs** or from **View runs** on the workflow. You'll see the step chain with per-step status and duration, the findings the run produced, and each output with its delivery status. See [running a workflow](/workflows/running#follow-a-run). ## Next steps Review results and accept fixes. Deliver results to pull requests. # Create a workflow Source: https://docs.amplify.security/workflows/create-a-workflow Build a workflow section by section, and what each part of the editor is for. ## Before you start You need at least one **connected repository**. Workflows run against the projects Console has access to through your source control provider — if the Projects page is empty, connect a repository first. You do not need to create any agents. Console ships a library of agents that covers scanning, detection authoring, patching, and review. See [the agent library](/agents/library) for the catalog. ## Create it From **Workflows**, click **New workflow**. You land in the editor with an empty draft and four sections to fill in, top to bottom. Nothing is saved until you click **Save**. Click **Save** at any point to see what's still missing — incomplete fields highlight in red with a message explaining what's required. Nothing is submitted until the draft is valid. ## Name The field at the top of the editor. It identifies the workflow in lists, run history, and — if you add a [merge gate](/workflows/outputs#gate-merging-on-security-review) — in the GitHub check that appears on pull requests. * Required, and must be unique within your organization. * Choose something durable. Once a workflow has a **merge gate** output, its name is locked, because the check name customers pin in branch protection is derived from it. Renaming would silently stop the check from reporting and leave pull requests waiting forever. To rename, remove the merge gate output, save, then rename. ## Description A short statement of what the whole workflow is for — shown in the workflow list and in run history so your team can tell workflows apart at a glance. It doesn't shape what any step does. Each agent in the chain already carries its own instructions, and runs the same way whether it's the only step or one of many — write the description for the humans who'll read the workflow list, not as an instruction to the chain: **Good:** > Scans pull requests for injection and access-control vulnerabilities, patches anything confirmed > exploitable, and posts the result as a review comment. **Too vague to tell apart from your other workflows:** > Security workflow. If you want a step to behave differently, change that agent or its own `description` — see [writing an agent](/agents/writing-an-agent). The workflow description is documentation, not an instruction. ## Triggers *Optional.* When the workflow should fire on its own. You can save a workflow with no triggers at all and still run it by hand whenever you like — every workflow supports manual runs. Add a trigger only when you want it to fire automatically. Click **Add trigger** and pick a type. Today that means **on pull requests**, where you choose which repositories to watch and, optionally, restrict it to specific base branches. If you add a trigger, it must name at least one repository, or the workflow won't save. See [Triggers](/workflows/triggers) for the full details. ## Agents *Required.* The ordered chain of agents that does the actual work. Click the **+** button to search the agent library and add an agent. Each one becomes a step, drawn as a pill with an arrow to the next — the chain reads left to right. * **At least one** agent, **at most twenty**. * **Reorder** by dragging a pill. * **Remove** a step by clicking the grip icon on its pill and choosing *Remove from chain*. The order you drag steps into sets which *earlier* steps a later one can draw on — see [the agent chain](/workflows/agent-chain) for how that actually determines when each step runs. If any step fails, nothing depending on it runs and the run ends in error. See [the agent library](/agents/library) for which agents to use. ## Output *Optional.* Where the results go when a run completes. Click **Add output** and choose a destination: * **Comment on triggering pull request** — posts review comments on the pull or merge request that fired the run. * **Gate merging on security review** — adds a required check that blocks merging until the agent's verdict passes or a human approves the pull request. You can add one of each, but not two of the same type — an already-added destination shows as *Already added* in the picker. Both destinations describe a *triggering pull request*, so they only do something on runs that a pull request started. On a manual run they're skipped. See [Outputs](/workflows/outputs). ## Save Click **Save**. Console creates the workflow, then applies your triggers and outputs. If a trigger or output can't be applied, the workflow is still created — you'll land on its detail page with a banner explaining what didn't stick, and you can finish wiring it up there. Clicking **Cancel** with unsaved changes asks you to confirm before discarding. ## Edit or delete later Open a workflow from the **Workflows** list to see it in read-only form, then click **Edit**. The same four sections become editable, with **Save**, **Cancel**, and **Delete** in the header. Editing a workflow does not affect runs already in flight — each run uses the definition as it was when it fired. ## Requirements at a glance | Field | Rule | | ----------- | --------------------------------------------------------------------- | | Name | Required, unique, non-blank. Locked while a merge gate output exists. | | Description | Required, non-blank. | | Agents | At least 1, at most 20. | | Triggers | Optional. Any trigger you add must name at least one repository. | | Outputs | Optional. One per destination type. | ## Next steps Fire it manually and watch the run. The agent catalog and common chains. # Outputs Source: https://docs.amplify.security/workflows/outputs Post workflow results back to a pull request, and block merging until security review passes. ## What an output does An output is a destination for a run's results. When a run completes, Console dispatches every output you've configured. Outputs are optional — without one, a run still records its findings in Console; it just doesn't push them anywhere. Add them from the **Output** section of the workflow editor. You can add one of each destination type, but not two of the same kind. Both destinations act on *the pull request that triggered the run*, so they only do something for runs a pull request started. On a manual run they're recorded as skipped. ## Comment on triggering pull request Posts the run's findings as review comments on the pull or merge request that fired the workflow, with links back to the full finding in Console. This works for both GitHub pull requests and GitLab merge requests. Use it when you want the agent's results to show up where reviewers already are, without changing whether the pull request can merge. ## Gate merging on security review Adds a **required check** to the pull request that blocks merging until the security review passes or a human signs off. This is the output to use when you want the workflow to have teeth. ### The check The check is named: ``` Console / ``` Its details link points at the run in Console, so anyone looking at a blocked pull request can click through to what the agent actually found. Because the check name is derived from the workflow name, Console **locks the workflow name** while a merge gate output exists. If you rename it, the check reports under a new name, and any branch protection rule pinned to the old name waits forever for a check that will never arrive. To rename: remove the merge gate output, save, rename, then add the gate back. ### How the gate decides | Outcome | Check result | What it means | | ------------------------------- | --------------- | ------------------------------------------------------------------------- | | Agent's verdict is **pass** | Passing | Security review passed. Merging is unblocked. | | Agent's verdict is **fail** | Failing | Review failed. Push a commit addressing the findings. | | Agent asks for **human review** | Action required | The agent isn't confident enough to decide. A human approval releases it. | | **No verdict recorded** | Action required | The gate fails safe. A human approval releases it. | | The run **errored** | Failing | Merging stays blocked — a broken run is never treated as a pass. | The gate fails closed by design. A workflow whose agents don't report a gate verdict will block every pull request pending human review, rather than waving them through. For the gate to pass on its own, your chain needs an agent that records a gate verdict. If none does, the gate still works — it just always routes to human approval instead of ever passing automatically. ### Human approval Approving the pull request releases a gate that's waiting on human review, and the check flips to passing. This also works retroactively: if someone approved the pull request before the gate finished posting, Console resolves the gate as approved rather than leaving an already-approved pull request stuck. By default, later requesting changes on a pull request whose gate was already approved does not re-block it. ### Requiring the check in GitHub Adding the output makes the check *report*. It doesn't make it *required* — that's a GitHub branch protection setting you control: 1. In GitHub, go to **Settings → Branches** (or **Rules → Rulesets**) for the repository. 2. Edit the rule protecting your target branch, e.g. `main`. 3. Enable **Require status checks to pass before merging**. 4. Search for `Console / ` and add it. Let the workflow run on one pull request first. GitHub only offers a check in that search box once it has seen it report at least once. Until you complete this step the check appears on pull requests as information only, and merging isn't actually blocked. ### GitLab Merge blocking isn't supported for GitLab merge requests yet. A merge gate on a GitLab run is recorded as skipped. Use **Comment on triggering pull request** for GitLab in the meantime. ## Checking delivery Every run's detail page lists the outputs it dispatched and whether each was delivered: | Status | Meaning | | ----------- | ----------------------------------------------------------------------------------- | | **Sent** | Delivered successfully. | | **Failed** | Delivery failed — for example, Console lacks permission on the repository. | | **Skipped** | Not applicable to this run, such as a pull request comment on a manually-fired run. | | **Pending** | Delivery hasn't completed yet. | If an output shows **Failed**, check that the Console GitHub App is still installed for the repository and has permission to write checks and pull request comments. ## Next steps Fire a run and confirm your outputs delivered. Outputs need a pull-request run to act on. # Workflows Source: https://docs.amplify.security/workflows/overview Chain agents into repeatable automation that fires on a trigger and routes its results wherever you need them. ## What is a workflow? A workflow is a saved sequence of agents that Console runs against your repositories. Where chat is a conversation you drive turn by turn, a workflow is the same agents running unattended: you define the sequence once, and Console executes it whenever a trigger fires or you run it by hand. Workflows are where the other two layers pay off. [Agents, skills, and detections](/agents/overview) do the work; [your repositories and connections](/data/overview) give them something real to reason about. A workflow puts those to work on a schedule, with no one in the loop, and delivers the result to where your team already works. A typical workflow scans a repository for vulnerabilities, hands what it found to a second agent that authors reusable detections or generates patches, and routes the result to whichever outputs you have attached. ## Anatomy of a workflow Every workflow is made of four parts. Only the first two are required. | Part | Required | What it does | | --------------- | -------- | ------------------------------------------------------------------------------------------ | | **Name** | Yes | Identifies the workflow. Must be unique in your organization. | | **Description** | Yes | A short summary of the workflow's purpose, shown in the workflow list and run history. | | **Agents** | Yes | The ordered chain of agents to run. At least one, at most twenty. | | **Triggers** | No | When the workflow fires automatically. Manual runs are always available without a trigger. | | **Outputs** | No | Where the results go when the run finishes. Attach as many destinations as you need. | The description documents the workflow for your team — it doesn't shape what any step does. Each agent already carries its own instructions, which is what actually runs. See [Create a workflow](/workflows/create-a-workflow#description). ## What happens during a run When a workflow fires, Console does the following for **each** repository you targeted: 1. **Creates a run.** Every run gets its own record, visible under [Runs](/workflows/running). 2. **Snapshots the definition.** The run captures the workflow's name, description, and steps as they are at that moment. Editing the workflow later never changes a run that is already in flight. 3. **Provisions an isolated sandbox** and clones the repository into it. For pull-request runs, it clones the pull request's head — not the default branch. 4. **Runs the chain.** Each step runs once the steps it actually depends on have finished (or been legitimately skipped) — independent steps can run at the same time; see [the agent chain](/workflows/agent-chain) for exactly how steps depend on each other. 5. **Stops on failure.** If a step fails, nothing depending on it runs, and the run ends in error. 6. **Records findings** from the run, and **dispatches your outputs** once the run completes. Targeting three repositories produces three independent runs — one per repository — not one run that loops. Each gets its own sandbox, and one failing does not stop the others. ## Where workflows live * **Workflows** — the list of workflows in your organization, with a run count for the last 7, 30, or 90 days. This is where you create, edit, and manually fire them. * **Runs** — the execution history for every workflow, including per-step status, findings, and whether each output was delivered. ## Next steps Walk through the editor section by section. How steps depend on each other and how to order them. Decide what starts a run, and when. Route results to where your team works. Fire a workflow and read its run history. # Running a workflow Source: https://docs.amplify.security/workflows/running Fire a workflow manually, then follow the run through to its results. ## Run a workflow manually Open the workflow from the **Workflows** list and click **Run workflow**. In the dialog: 1. **Repositories** — select one or more connected repositories to run against. The button stays disabled until you pick at least one. 2. **Git ref** *(optional)* — a branch, tag, or commit. It's applied to **every** selected repository, so leave it empty unless they share the ref you want. Empty means each repository's own default branch. 3. Click **Run workflow**. Console fires immediately and starts one run per repository. Firing a workflow manually cancels any earlier **manual** runs of that workflow still pending or running. It does not touch runs started by a pull request. See [superseding in-flight runs](/workflows/triggers#superseding-in-flight-runs). ## Run it automatically Add a [pull request trigger](/workflows/triggers#pull-request-triggers) and Console fires the workflow whenever a pull request in the selected repositories is opened, reopened, or updated with new commits. Automatic runs always use the pull request's head commit. ## Follow a run From a workflow, click **View runs**. From anywhere, the **Runs** page lists every run in your organization; filter it by **status** or by **workflow name**. Open a run to see: * **The chain** — each step drawn in order with its agent name, how long it took, and its status icon. Steps light up as they complete, so you can watch progress on a running workflow. A step that fanned out into more than one agent run shows the count (`×3`); hover a **Skipped** step to see why, in the run's own words — for example, no findings had been produced yet, or none matched what that step groups by. * **Findings** — what the run confirmed, linked through to the full finding. * **Outputs** — each configured destination and whether it was delivered. See [checking delivery](/workflows/outputs#checking-delivery). * **Go to workflow** — jump back to the definition that produced this run. A run page refreshes itself while the run is active, so you can leave it open. ## Run statuses | Status | Meaning | | ------------- | -------------------------------------------------------------------------------- | | **Pending** | Queued. Console is provisioning a sandbox and cloning the repository. | | **Running** | The agent chain is executing. | | **Completed** | Every step finished — or was legitimately skipped — and outputs were dispatched. | | **Error** | A step failed. Nothing depending on it ran. | | **Cancelled** | Cancelled by you, or superseded by a newer run from the same trigger. | An individual step can also show **Skipped** — its input was empty, or nothing in it matched what the step [groups by](/agents/writing-an-agent#group-by). A skipped step is not a failure: the run around it still completes normally. It's a separate, distinct outcome from a step that ran and simply found nothing to report. ## Cancel a run Open the run and click **Cancel**. Console stops the agent chain and tears down the sandbox. Cancelling doesn't undo anything already done — findings recorded before the cancellation stay, and any output already delivered stays delivered. If a [merge gate](/workflows/outputs#gate-merging-on-security-review) was posted, a cancelled run leaves it blocking rather than passing. ## Reading a failed run A run ending in **Error** has a step with the error icon — that's where something failed. Any step that depended on it never ran at all; an independent step elsewhere in the chain may have already finished before the failure landed, and keeps its own result. Common causes: * **The repository couldn't be cloned.** Usually a permissions problem — confirm the Console GitHub App is still installed for that repository, or that a `Git ref` you pinned actually exists. * **A step exceeded its time budget.** Long chains against large repositories can run out of budget. Splitting a broad scan into a narrower profile (see [scanning agents](/agents/library#scanning)) usually resolves it. * **A step named an agent that no longer exists.** If you deleted an agent your workflow references, edit the workflow and repair the chain. Because Console snapshots the workflow definition when a run fires, fixing the workflow doesn't repair an existing failed run — edit the workflow, then fire it again. ## Run history at a glance The **Workflows** list shows a run count per workflow, and you can switch the window between **7d**, **30d**, and **90d** to see how often each one has been firing. ## Next steps Push results to pull requests automatically. Adjust scan depth and sequencing. # Triggers Source: https://docs.amplify.security/workflows/triggers Fire a workflow on demand, or automatically when a pull request opens. ## What a trigger does A trigger decides **when** a workflow fires and **which repositories** it fires against. Triggers are optional: every workflow can always be run by hand, so add a trigger only when you want Console to fire it without you. Manage triggers in the **Triggers** section of the workflow editor. Click **Add trigger**, pick a type, and choose its repositories. ## Manual runs Every workflow supports manual runs. There's nothing to configure and nothing appears in the Triggers section — it's always available. With a manual run you choose the repositories at the moment you fire it, and you can optionally pin a specific branch, tag, or commit. See [Running a workflow](/workflows/running). ## Pull request triggers Select **On pull requests** to fire the workflow automatically against pull and merge requests. ### When it fires Despite the name, this trigger fires on more than just opening a pull request. It fires when a pull request is: * **Opened** * **Reopened** * **Updated with new commits** An update supersedes the earlier run — Console cancels the in-flight run and starts a fresh one at the new head commit, so a [merge gate](/workflows/outputs#gate-merging-on-security-review) re-evaluates against the code that's actually there now, instead of staying stuck on a verdict for a commit nobody is merging. ### Repositories Choose one or more connected repositories to watch. A trigger with no repositories won't save. Pull-request runs always clone **the pull request's head** — the proposed code, not the base branch. You cannot pin a branch or commit on a pull request trigger, because the head is what's under review. ### Base branch filter By default the workflow fires on pull requests targeting **any** branch. Add one or more base branches to narrow it to pull requests aimed at those branches specifically — a common choice is to gate only what's merging into `main`. Matching is exact. A pull request whose base branch isn't in your list is skipped before Console provisions anything, so filtered-out pull requests cost you nothing. ### Draft pull requests Draft pull requests are always skipped. Work in progress doesn't warrant a run, and the workflow will fire once the pull request is marked ready. ### Requirements Pull request triggers depend on Console receiving events from your source control provider, which means the repository must be connected and the Console GitHub App installed for it. See [Installation](/install-console#install-the-github-app). ## One run per repository A trigger that names three repositories produces **three runs** when it fires — one per repository, each in its own sandbox. Runs from the same firing are grouped, so you can see them together in the run history, but they succeed or fail independently. ## Superseding in-flight runs When a workflow fires again from the same trigger, Console cancels any of that trigger's runs that are still pending or running before starting the new ones. This keeps a rapidly-updated pull request from stacking up parallel sandboxes for commits that are already stale, and it means the verdict on a pull request always reflects its latest commit. It applies to manual runs too: firing a workflow manually while an earlier manual run is still going replaces it. Cancellation is scoped to the trigger. A manual run does not cancel a pull-request run of the same workflow, and vice versa. ## Scheduled triggers Scheduled triggers aren't available to create yet. If your organization has any from an earlier configuration, the editor displays them read-only. ## Next steps Decide what a triggered run posts back. Fire a run and follow it through.