AWS DevOps Agent

What it does

• Guard. Every hour Spellwarden reads the skills, AGENTS.md files, custom agents, the directives memory store and the MCP servers of the Agent Space, scans them with the same engine and rules as everything else in Spellwarden, and shows them in the dashboard with their findings. If you allow it, Spellwarden switches off a skill that fails.
• Deliver. If you allow it, owners and managers install vetted skills from the Spellwarden catalog into the Agent Space, pinned to the vetted version, and Spellwarden moves them to the next vetted version when your organisation accepts an update.
• Tool. The stack registers Spellwarden's MCP server in the Agent Space with 13 read-only tools, so the agent can look up your findings and scans. An optional weekly review adds a custom agent that reports on the Agent Space's own skills and servers once a week.

If you only want Spellwarden's tools in DevOps Agent, without Guard or Deliver, you can add Spellwarden from the DevOps Agent console instead (see Adding Spellwarden from the DevOps Agent console).

Before you start

• A Spellwarden organisation on any plan, the 14-day trial included. Sign up at dash.spellwarden.ai. An organisation that is read-only until billing is added cannot start a new connection.
• The Owner role in that organisation to connect and disconnect an Agent Space. Owners and managers see the connected Agent Spaces, sync them and remove skills Spellwarden installed.
• An Agent Space in one of the Regions below. Have its ID ready: the stack asks for it if you do not type it in Spellwarden.
• Rights in the Agent Space's AWS account to create a CloudFormation stack that creates IAM roles, one of them with a fixed name, a Secrets Manager secret, a Lambda function and DevOps Agent resources.
• An organisation can connect up to 10 Agent Spaces, with one stack each. Several stacks, one per Agent Space, can live side by side in one AWS account.

Regions

The stack works in the 15 Regions of AWS DevOps Agent: us-east-1, us-east-2, us-west-2, ca-central-1, sa-east-1, ap-south-1, ap-southeast-1, ap-southeast-2, ap-northeast-1, ap-northeast-2, eu-central-1, eu-west-1, eu-west-2, eu-west-3 and eu-north-1. Create it in the Agent Space's own Region. Spellwarden itself runs in eu-central-1 (Frankfurt), whichever Region the Agent Space is in.

Connect an Agent Space

1. In Spellwarden, open Settings, then AWS DevOps Agent, and select Connect an Agent Space.
2. Region: the Region of the Agent Space, such as eu-central-1. Agent Space ID: optional. When you type it, Spellwarden lists it with the other values; otherwise you type it in the stack.
3. Under What Spellwarden may do, choose the options (see The options). Only Add Spellwarden's tools to the Agent Space is on by default.
4. Select Create setup. Spellwarden shows Download template, Open CloudFormation, the values the stack needs and a ready-made command for the AWS CLI.
5. Select Download template. Spellwarden gives you the exact template file of this release.
6. Select Open CloudFormation. The console opens in the Agent Space's Region. Choose Create stack, With new resources, then Upload a template file, and pick the file you downloaded.
7. Enter the stack name and the parameters Spellwarden shows, including the external ID, the setup code and your options; each has a copy button. Acknowledge that the stack creates IAM resources with custom names, and create it.
8. The stack's registration function calls Spellwarden once. Spellwarden assumes the new role with your external ID, checks that it can read the Agent Space, and checks that the role refuses a wrong external ID. The connection then shows Active, usually within a minute, and the first sync starts.

The setup code works once and for one hour. Do not share it. On its own the code grants nothing: Spellwarden also has to be able to assume the role with this connection's external ID.

Until the stack registers, the connection shows Waiting for the stack. After one hour the setup code no longer works: create a new setup.

To deploy from a terminal instead, download the template, copy the command Spellwarden shows and run it in the same folder, in a terminal signed in to the Agent Space's AWS account. It has this shape, with the setup's values in place of the brackets:

aws cloudformation create-stack --region <Region> --stack-name spellwarden-devops-agent \
  --template-body file://spellwarden-devops-agent.yaml --capabilities CAPABILITY_NAMED_IAM \
  --parameters ParameterKey=AgentSpaceId,ParameterValue=<Agent Space ID> \
    ParameterKey=ExternalId,ParameterValue=<external ID> ParameterKey=SetupCode,ParameterValue=<setup code> \
    ParameterKey=AllowSwitchOff,ParameterValue=false ParameterKey=AllowInstall,ParameterValue=false \
    ParameterKey=ReadMemories,ParameterValue=false ParameterKey=ConnectSpellwardenTools,ParameterValue=true \
    ParameterKey=WeeklyReview,ParameterValue=false

The command holds the setup code too, so keep it to yourself. Download template gives the exact file of this release; it is template/spellwarden-devops-agent.yaml in the stack's repository.

The options

Each option is a parameter of the stack. The checkboxes in Spellwarden set them in the link, and you can still change them in the CloudFormation console before you create the stack.

What the stack creates, and its permissions

The stack holds only IAM, one secret, one small function and DevOps Agent resources:

• SpellwardenDevOpsAgent-<AgentSpaceId>: the IAM role Spellwarden assumes. It trusts only Spellwarden's role arn:aws:iam::359360911388:role/spellwarden-devops-agent, and only with this connection's external ID. A session lasts at most one hour.
• spellwarden-devops-agent/<AgentSpaceId>: a Secrets Manager secret that holds the connection token and, with the tools option, the read API key. Only the registration function writes it. Spellwarden keeps only hashes of both, so this secret holds the only copy.
• A registration function (AWS Lambda, Python 3.13, written inline in the template so you can read it) with its own role, which may only write its logs and read and write that secret. It calls Spellwarden when the stack is created, updated and deleted, and never calls DevOps Agent.
• With the tools option: the MCP server registration spellwarden-<AgentSpaceId> and its association with the Agent Space, which allows the 13 read-only tools.
• With the weekly review: the skill spellwarden-agent-supply-chain-review, the custom agent spellwarden-supply-chain-review and a trigger that runs it every 7 days.

IAM cannot limit UpdateAsset to the status field, or DeleteAsset to the assets Spellwarden created. Spellwarden's backend enforces both: it sends only the status field when it switches a skill off, and it changes and removes only skills it installed, and only while nobody has changed them.

IAM also cannot limit reads to some kinds of asset. AWS authorises ListAssets, GetAsset, GetAssetContent, ListAssetFiles and GetAssetFile only on the whole Agent Space, with no condition key for the asset type. So the Read policy lets the role read every asset of the Agent Space, memory stores included, whatever ReadMemories says. What Spellwarden reads, in the next section, is enforced by Spellwarden's backend, and a test there pins it.

You can check it yourself: every call the role makes is in your AWS CloudTrail, with a session name that starts with dag-. If an Agent Space holds material Spellwarden must not be able to read at all, do not connect that Agent Space.

What Spellwarden reads

• Spellwarden syncs every connected Agent Space once an hour. Owners and managers can also select Sync now on the connection's page, up to 6 times an hour.
• A sync starts a scan only for an item whose content changed, and at most 20 scans; the rest start at the next sync.
• When the scanner's rules change, a skill whose last scan is more than 7 days old is scanned again.
• A skill removed from the Agent Space stays in your Skills list with its scans and findings, marked Removed from the Agent Space on its date, and is no longer scanned.

The connection's page shows the Agent Space in four tables: its skills with their scan, findings and trust, its instruction files, its MCP servers and its remote agents. In the Skills and MCP servers lists, what came from an Agent Space carries an Agent Space label.

Switching off failing skills

Only with the AllowSwitchOff option, and only skills. Spellwarden switches a skill off when its latest complete scan leaves it quarantined or with an open critical finding, and for no other reason.

It sets the skill's status to INACTIVE and sends nothing but the status field. The organisation's owners and managers get an email, the audit log records it, and the connection's page shows the skill as Switched off by Spellwarden, with the reason.

Spellwarden never switches a skill back on. If a person switches it back on and its content has not changed, Spellwarden leaves it on and does not switch it off again for the same findings. When the content changes, the next scan decides again.

AGENTS.md files, custom agents and memory stores are never switched off: Spellwarden reports them only.

Installing vetted catalog skills

With the AllowInstall option, owners and managers can install skills from the Spellwarden catalog into the Agent Space.

1. In the dashboard, open Catalog and choose a skill or a plugin. Its page says whether DevOps Agent can hold it: a skill with a scripts folder, more than 100 files, more than 6 MB zipped, or a name or description DevOps Agent does not accept cannot go into an Agent Space.
2. Select Install, and under Also install into an Agent Space choose the Agent Space. The catalog install into your organisation happens either way.
3. Spellwarden installs the vetted version: the skill's own folder at the vetted commit, with the upstream licence and notice files under references/. A name already used in the Agent Space is refused. The next sync scans the copy.

When your organisation accepts a newer vetted version of the entry with Update, Spellwarden moves the copy in the Agent Space to it, content only. If a person changed the copy since Spellwarden wrote it, Spellwarden leaves it as it is.

To take a skill out, select Remove from Agent Space on the connection's page. Spellwarden removes only skills it installed, and only while nobody has changed them.

Spellwarden's tools and the weekly review

With the ConnectSpellwardenTools option, on by default, the stack registers Spellwarden's MCP server, https://dash.spellwarden.ai/api/v1/mcp, and allows these 13 read tools in the Agent Space: list_organisations, get_organisation, list_skills, get_skill, list_findings, get_trust_score, list_policy_packs, list_registry_entries, get_runtime_inventory, get_eval_run, get_migration_report, list_mcp_servers and list_agent_space_connections. The tools that start scans, add servers, start eval runs or export, and list_api_keys, are not allowed. The tools are described in the connector guide.

The agent reaches the server with a read API key that Spellwarden makes for this connection, named AWS DevOps Agent: <Agent Space name>. The key belongs to the organisation that made the setup and cannot change anything. It counts toward the organisation's 20 read or write keys and is listed under Settings, API keys. Spellwarden keeps only its hash; the copy the agent uses is in the stack's secret. Disconnecting revokes it.

The weekly review

With the WeeklyReview option, which needs the tools, the stack adds the skill spellwarden-agent-supply-chain-review, the custom agent spellwarden-supply-chain-review and a trigger that runs the agent every 7 days. The agent uses four of Spellwarden's tools, list_agent_space_connections, list_skills, list_mcp_servers and list_findings, and writes a short report under four headings: New findings, Quarantined or switched-off skills, Servers with no tool allowlist, and Not scanned. It changes nothing in the Agent Space and opens no investigation.

Each run is agent time on your AWS bill, at USD 0.0083 a second: a run of five minutes costs about USD 2.50, about USD 130 a year. The option is off by default.

Adding Spellwarden from the DevOps Agent console

For Spellwarden's tools alone, without Guard or Deliver, Spellwarden is preparing a connector for the connector gallery of the DevOps Agent console. It needs no stack and no role. AWS reviews and publishes the gallery, so until Spellwarden is listed in your console, use the stack, which adds the same tools.

Sign in (the default)

• Choose Sign in. Spellwarden asks which organisation the Agent Space may use and whether the connection is Read only or Read and write. Choose the organisation the Agent Space should see, and Read only.
• The connection then acts as you in that one organisation only, and the agent is told so when it connects and in the answer of list_organisations. Everyone who works in the Agent Space uses Spellwarden through this connection, which is why Read only is the safer choice.
• A connection lasts at most 365 days, and ends sooner if it goes unused for 30 days. You can disconnect it at any time in Spellwarden, under your account menu, then Connected apps (dash.spellwarden.ai/account/connected-apps).

Or an API key

In Spellwarden, open Settings, API keys, and create a key with Read access. In the console, paste it as the Spellwarden API key (read access). See API and keys.

Either way, allow only the 13 read tools listed above, and not the tools that start scans, add servers or start eval runs.

Changing options and updating the stack

The options come from the stack. To change one, update the stack in CloudFormation: choose Update, keep the current template and change the parameter. Spellwarden records the new options at the update, and the connection's page shows them.

Turning ConnectSpellwardenTools off revokes the stack's API key. Turning it on for a connection that has no key needs a new setup code, and the update fails with a message saying so: disconnect the Agent Space, then use Reconnect with the tools option on.

When a newer template is published, the connection's page says that it is available. Update the stack with the new template to get it.

Disconnect and remove

• Disconnect. An owner selects Disconnect on the connection's page. Spellwarden stops syncing and revokes the API key it made for the Agent Space. The scan history stays until the organisation deletes it.
• Remove. Delete the CloudFormation stack. That removes the role, the secret, the registration function and the DevOps Agent resources the stack created, and the function tells Spellwarden, which disconnects the Agent Space. Either order works, and Spellwarden being unreachable never blocks the deletion.
• Reconnect. On a connection that shows Disconnected or Access lost, an owner selects Reconnect. If the stack still exists, update it with the new setup code that Spellwarden shows, with the command or in the console; if you deleted the stack, create it again with the steps above.

Skills Spellwarden installed from the catalog are not resources of the stack, so they stay in the Agent Space when you delete it. Remove them first with Remove from Agent Space if you want them gone.

If Spellwarden is refused the role three times over at least 24 hours, for example because the stack was deleted while Spellwarden could not be told, the connection shows Access lost, its API key is revoked and the owners and managers get one email.

Troubleshooting

A sync that fails shows its reason on the Agent Space's row; a stack that cannot register fails in CloudFormation with Spellwarden's message. The messages, and what to do:

Plans and costs

• Guard and Spellwarden's tools: every plan and the 14-day trial.
• Switching off failing skills: every plan.
• Installing catalog skills into an Agent Space: wherever catalog installs are, which is the Team and Enterprise plans and the trial.

• Spellwarden charges nothing for the stack, and the stack starts no agent time. AWS bills its one Secrets Manager secret, about USD 0.40 a month. Idle Agent Spaces, skills and registrations cost nothing.
• AWS bills agent time at USD 0.0083 a second. A weekly review run of five minutes costs about USD 2.50, about USD 130 a year.

Your data

• Spellwarden assumes the role in your account with the external ID of the connection, for sessions of at most one hour. It stores no AWS credentials.
• It keeps what it reads as content your organisation submits: the files of each version it scans, with their findings, and the addresses, allowed tools and authentication types of the MCP server and remote agent registrations. It stores and processes them in the EU, in AWS eu-central-1 (Frankfurt).
• It never reads attachments, test profiles, feedback, chats, journals or investigations, and reads memory stores other than directives only with ReadMemories.
• Disconnecting or deleting the stack stops every read. What was already scanned stays until the organisation deletes it.
• Its calls to your account are in your CloudTrail, and what it changes there, a switch-off, an install, an update or a removal, is recorded in the organisation's audit log.

The full details are in the privacy policy, Connected AWS DevOps Agent spaces.

Support

Write to hello [at] spellwarden [dot] ai. To report a security problem in the stack, follow the security policy in its repository.

Related guides

• Spellwarden connector for Claude
• The Spellwarden catalog
• Check MCP servers and plan their migration
• API and keys