This server gives an AI agent read-only AWS security audit capabilities: it can inspect an AWS account and return normalized, severity-rated findings, posture scores, and evidence instead of just assertions.
Audit IAM: stale access keys, users without MFA, root account MFA/access keys
Audit S3: public buckets via ACLs, bucket policies, and public access block gaps
Audit EC2: security groups open to the world (0.0.0.0/0 or ::/0)
Audit CloudTrail: existence, logging status, multi-region coverage, log validation, encryption
Audit RDS: public accessibility, encryption, deletion protection
Audit EBS: unencrypted volumes and publicly shared snapshots
Audit Lambda: resource policies allowing broad or unconditional invocation
Get an account-level security summary: account ID, IAM summary counters, S3 public access block
Run a full aggregated audit: executes all checks and returns severity counts, weighted posture score, and letter grade
All tools are read-only and return a standard envelope: {check, ok, findings[], scanned} for trustable clean results
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@aws-audit-mcp Run a full security audit and summarize the findings."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Read-only AWS security audits, exposed as MCP tools. Point an AI agent at this server and it can answer "is this account in good shape?" with evidence instead of vibes: stale access keys, users without MFA, root account posture, public S3 buckets, world-open security groups, and CloudTrail coverage, each returned as normalized findings with severities an agent can reason about.
pip install "aws-audit-mcp[demo]"
curl -sO https://raw.githubusercontent.com/OmniNomadLLC/aws-audit-mcp/main/examples/demo.py
python demo.pyThe demo builds a deliberately misconfigured account in moto (an in-memory AWS emulator, nothing leaves your machine) and runs the aggregated audit against it: seven findings, a posture score, and a letter grade, exactly what an agent gets back.
Related MCP server: AWS SRA Verify MCP Server
This server never mutates anything. That claim is enforced in three layers, not asserted once in a docstring:
A single client factory. Every boto3 client in the codebase is created through aws_client() in common.py. Grep for aws_client( and you have every AWS touchpoint; there is nowhere else for a write call to hide.
MCP tool annotations. Every tool is registered with ToolAnnotations(read_only_hint=True, destructive_hint=False), so MCP clients see the read-only contract at the protocol level.
A CI eval. The test suite greps every tool module for mutating boto3 verbs (create, put, delete, update, attach, and friends) and fails the build if one appears.
Honesty requires one more sentence: the real security boundary is IAM, not this code. Run the server with the least-privilege policy in examples/iam-policy.json, which grants exactly the read actions the tools call and nothing else. The policy uses Resource: "*" because these are account-wide list and describe actions: auditing "all IAM users" or "all buckets" is inherently account-scoped, and constraining resources would silently blind the audit.
Install from PyPI (available after the first release):
pip install aws-audit-mcpOr install from git (or a local clone):
pip install git+https://github.com/OmniNomadLLC/aws-audit-mcp.gitAdd it to Claude Code:
claude mcp add aws-audit-mcp --env AWS_PROFILE=audit --env AWS_REGION=eu-west-1 -- aws-audit-mcpOr for any MCP client, the generic config:
{
"mcpServers": {
"aws-audit-mcp": {
"command": "aws-audit-mcp",
"env": {
"AWS_PROFILE": "audit",
"AWS_REGION": "eu-west-1"
}
}
}
}Credentials resolve through the standard boto3 chain (AWS_PROFILE, environment variables, instance roles), the same way every AWS tool works.
Tool | Audits | Key severities |
| active IAM keys older than the threshold | HIGH if the user has no MFA, else MEDIUM |
| console users without MFA | HIGH |
| root MFA and root access keys | CRITICAL for root keys, HIGH for missing MFA |
| bucket ACLs, wildcard-principal policies, missing or weakened public access block | HIGH / MEDIUM |
| ingress from 0.0.0.0/0 or ::/0 | HIGH on admin/db ports or all traffic, MEDIUM otherwise |
| trail exists, logging, multi-region, log validation, CMK | CRITICAL / MEDIUM / LOW |
| account id, IAM summary, account-level S3 public access block | HIGH / MEDIUM |
| publicly accessible, unencrypted, unprotected RDS instances | HIGH / MEDIUM / LOW |
| unencrypted EBS volumes and publicly shared snapshots | CRITICAL / MEDIUM |
| Lambda functions invocable by anyone or by unconditioned service principals | HIGH / MEDIUM |
| runs every audit above and returns severity counts, a weighted posture score and a letter grade | aggregate |
Every tool returns the same envelope: {check, ok, findings[], scanned}. Every finding has {check, severity, title, resource, detail} with severity one of LOW, MEDIUM, HIGH, CRITICAL. The scanned count exists so a clean result is trustworthy: scanned: 0, findings: [] and scanned: 200, findings: [] are very different answers.
{
"check": "iam.stale_access_keys",
"ok": false,
"findings": [
{
"check": "iam.stale_access_keys",
"severity": "HIGH",
"title": "Active access key is 412 days old and the user has no MFA",
"resource": "arn:aws:iam::111111111111:user/ci-deploy",
"detail": {
"access_key_id": "AKIAEXAMPLEEXAMPLE",
"age_days": 412,
"max_age_days": 90,
"user_has_mfa": false
}
}
],
"scanned": 14
}flowchart LR
A[MCP client / AI agent] -- stdio --> B[server.py\nautodiscovery]
B --> T1[tools/iam.py]
B --> T2[tools/s3.py]
B --> T3[tools/ec2.py]
B --> T4[tools/cloudtrail.py]
B --> T5[tools/rds.py, ebs.py,\nawslambda.py, account.py]
B --> F[tools/full.py\naggregated posture]
T1 & T2 & T3 & T4 & T5 --> C[common.py\nfinding / report / aws_client]
C -- read-only API calls --> AWS[(AWS account)]Six lines, because that is all there is:
server.py autodiscovers tool modules: anything in tools/ exposing register(mcp) is loaded.
One module per AWS surface: iam.py, s3.py, ec2.py, cloudtrail.py, account.py.
The shared contract lives in common.py: finding(), report(), and the aws_client() factory.
Adding a check means adding one module plus its tests; the server does not change.
Unit tests run against moto, so every check is exercised against simulated AWS accounts with no credentials required.
Contract evals assert that every tool is documented, typed, annotated read-only, and returns the standard envelope.
A bad-account scenario eval builds a deliberately misconfigured moto account and asserts the tools catch every planted issue.
CI runs all of it on every push.
This project is built AI-assisted, with the discipline that makes that safe: every change passes the unit tests, the contract evals, and the machine-checked read-only gate before it lands on main. Every claim in this README is verified by CI, not by the author's memory.
The event-driven sibling of this project is aws-secops-lab: that one detects changes in seconds, this one audits state on demand.
MIT, see LICENSE.
Cheap posture snapshot of the audited AWS account.
Collects:
the account id (sts.GetCallerIdentity); this identifies the audited account and is returned in the summary
iam.GetAccountSummary counters: Users, AccountMFAEnabled, AccountAccessKeysPresent
the account-level S3 public access block (s3control.GetPublicAccessBlock)
Findings:
HIGH when the root account has no MFA (AccountMFAEnabled != 1)
MEDIUM when the account-level S3 public access block is missing or any of its four flags is disabled
Returns:
Report envelope: {check, ok, findings[], scanned, summary}. scanned
is 1 (one account). summary holds the collected numbers and
account_id. Each finding has {check, severity, title, resource,
detail} with severity one of LOW/MEDIUM/HIGH/CRITICAL.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already declare the tool read-only and non-destructive, the description goes further by naming the underlying AWS API calls (sts.GetCallerIdentity, iam.GetAccountSummary, s3control.GetPublicAccessBlock), specifying exact finding thresholds, and detailing the return envelope. This gives an agent a precise model of what the tool will and won't do.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well organized into 'Collects', 'Findings', and 'Returns' sections, and every line carries useful information. The opening sentence is a compact summary, and the nested detail is front-loaded and easy to scan without being padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description fully compensates by explaining the return envelope structure, finding severities, and what each collected value contributes. It also covers edge cases like a missing S3 public access block. An agent has all the information needed to invoke and interpret this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters and the schema description coverage is 100%, so the schema already fully documents the input surface. The description adds no parameter semantics because none are needed; the baseline of 4 for zero-parameter tools applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Cheap posture snapshot') on a specific resource ('audited AWS account'), then enumerates exactly what data is collected and which findings are generated. This makes the tool's purpose concrete and distinguishes it from the more specialized audit_* sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'cheap posture snapshot' implies a lightweight, account-level overview rather than a deep audit, which provides some usage context. However, the description never explicitly states when to use this tool instead of alternatives like audit_full_posture or audit_root_account_posture, nor does it list exclusions. Usage guidance is implied, not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit EBS volumes and snapshots for exposure risks.
Scans every EBS volume in the region (AWS_REGION or us-east-1 when the region argument is omitted) and flags unencrypted volumes as MEDIUM. Scans every snapshot owned by the account and checks its createVolumePermission attribute; a snapshot shared with the "all" group is public and is flagged CRITICAL.
Returns a dict {check, ok, findings, scanned, volumes_scanned, snapshots_scanned} where ok is true only when no findings were produced, findings is a list of normalized finding dicts, and scanned is the total number of volumes plus snapshots examined.
| Name | Required | Description | Default |
|---|---|---|---|
| region | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description deeply explains behavior beyond the readOnlyHint and destructiveHint annotations: it scans all volumes, flags unencrypted volumes as MEDIUM, checks createVolumePermission for public snapshots, flags them CRITICAL, and describes the output dict semantics. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear one-sentence purpose, then provides dense but relevant operational details, and ends with a useful return-value summary. Every sentence contributes information the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only audit tool with one optional parameter and no output schema, the description is thorough: it covers scope, region fallback, severity mapping, and the return dict structure. An agent can confidently decide when to invoke it and what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema description coverage is 0%, the description fully explains the only parameter: region defaults to AWS_REGION or us-east-1 when omitted. This adds meaningful behavioral context that the schema alone does not provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Audit'), a precise resource ('EBS volumes and snapshots'), and the exact goal ('exposure risks'). It clearly differentiates this tool from sibling audit tools that target RDS, security groups, buckets, and other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on what the tool scans, how region selection works, and what criteria produce findings. It does not explicitly name alternatives or say 'use this instead of X,' but the resource-specific scope makes the appropriate use case obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run every registered audit check with default arguments and aggregate the results into a single account posture report.
Discovers all audit_*/account_* functions in the tool modules and runs each
one; a failing check is recorded in errors and never aborts the rest.
Returns the standard {check, ok, findings, scanned} envelope where findings
is the concatenation of every sub-report's findings and scanned is the
number of checks run, plus severity_counts (LOW/MEDIUM/HIGH/CRITICAL),
posture_score, grade, checks_run, and errors. The score is weighted:
each CRITICAL finding costs 10 points, HIGH 5, MEDIUM 2, LOW 1, and
posture_score = max(0, 100 - total weight). Grades: A >= 90, B >= 75,
C >= 60, D >= 40, else F.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior. The description adds substantial behavioral detail: failing checks are captured in errors without aborting, the exact response envelope is specified, and the scoring/weighting model is fully explained. This exceeds what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: the core behavior is front-loaded, followed by the run semantics, return envelope, and scoring rules. Every sentence adds necessary information for correct invocation and interpretation, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description fully covers invocation behavior, error handling, return structure, scoring weights, and grade thresholds. An agent has everything needed to call the tool and interpret its result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema covers 100% of them by having none. Per baseline, no parameter documentation is needed; the description correctly focuses on behavior and output rather than adding meaningless parameter detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Run every registered audit check') and a concrete deliverable (aggregated account posture report). It clearly distinguishes itself from the sibling tools by describing the aggregation of all audit/account functions rather than a single check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when a full account-wide posture report is needed, as opposed to a specific audit_* sibling) and details what coverage includes. It lacks explicit 'use this instead of X' phrasing but provides clear contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit Lambda function resource policies for overly broad invoke access.
Scans every Lambda function in the region (AWS_REGION or us-east-1 when the region argument is omitted) and inspects its resource policy, if any. An Allow statement with a wildcard principal ("" or {"AWS": ""}) and no SourceArn/SourceAccount condition is HIGH: anyone can invoke the function. A service principal (for example s3.amazonaws.com) without any source condition is MEDIUM: any account's use of that service can invoke it. Service principals scoped by a SourceArn or SourceAccount condition are normal and are not flagged.
Returns a dict {check, ok, findings, scanned} where ok is true only when no findings were produced, findings is a list of normalized finding dicts (detail includes the statement sid, the principal and whether a condition exists), and scanned is the number of functions examined.
| Name | Required | Description | Default |
|---|---|---|---|
| region | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and non-destructive annotations, the description details scanning scope, region defaulting to AWS_REGION or us-east-1, severity classification logic for wildcard and service principals, and the exact conditions under which findings are produced. This is far more than the annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is thorough yet economical. It front-loads the purpose, then provides scanning behavior, severity rules, and output format. No sentence is wasted, and the structure flows logically from purpose to invocation details to return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully explains the return shape: a dict with check, ok, findings, and scanned keys, including details about finding normalization. The single optional parameter is also clarified. The tool is complex, but nothing necessary for correct invocation and interpretation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines an optional region parameter with zero description coverage. The tool description compensates by explaining that the region argument defaults to AWS_REGION or us-east-1 when omitted, giving the agent the exact behavior needed to invoke it correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'Audit Lambda function resource policies for overly broad invoke access.' It clearly distinguishes this tool from its audit siblings by targeting Lambda resource policies and defining the exact scope of what is inspected.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the audit context clear and explains the scanning behavior, but it does not explicitly state when to prefer this tool over alternatives such as audit_full_posture or audit_world_open_security_groups. Usage is implied rather than directly contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit every S3 bucket in the account for public exposure.
For each bucket this checks: the Public Access Block configuration (missing or any of the four flags disabled yields a MEDIUM finding), the bucket policy (any Allow statement with principal "" or {"AWS": ""} yields a HIGH finding), and the bucket ACL (grants to the AllUsers or AuthenticatedUsers groups yield a HIGH finding).
Returns a dict {check, ok, findings, scanned} where ok is true only when no findings were produced, findings is a list of normalized finding dicts (check, severity, title, resource, detail), and scanned is the number of buckets examined. Buckets that raise an unexpected AWS error are skipped and reported under an extra "errors" key mapping bucket name to error code. Severity: HIGH means the bucket is likely publicly reachable right now; MEDIUM means a guardrail is missing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description goes far beyond them by detailing exactly what is checked, how findings are classified, what the returned structure is, severity semantics, and how errors are handled. This is unusually transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately structured: a one-sentence summary, a bulleted list of checks and severities, and a concise explanation of the return value and error behavior. Every sentence carries useful information for calling the tool correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with no output schema, the description completely covers invocation semantics, return shape, finding schema, severity interpretation, and error handling. No important behavioral detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds no parameter meaning because none exists, but it clearly identifies the account-wide scope of the operation, which is the only relevant input context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb and resource: 'Audit every S3 bucket in the account for public exposure.' It clearly differentiates the tool from sibling audit tools by naming the specific AWS service, the account-wide scope, and the security concern it addresses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the tool's context clear: it is a focused S3 public-exposure audit covering Public Access Block, bucket policies, and ACLs. It does not explicitly list alternatives or when not to use it, but the scope is specific enough that an agent can select it appropriately among the sibling audit tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit RDS instance posture: public accessibility, storage encryption, and deletion protection.
Scans every RDS DB instance in the region. A publicly accessible instance is a HIGH finding, unencrypted storage is MEDIUM, and disabled deletion protection is LOW. Returns the {check, ok, findings[], scanned} envelope where scanned is the number of DB instances examined; each finding carries the engine, the endpoint address when public, and the raw posture flags.
| Name | Required | Description | Default |
|---|---|---|---|
| region | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and non-destructive behavior, and the description adds substantial behavior beyond that: it scans every RDS instance, assigns HIGH/MEDIUM/LOW severities, and returns the {check, ok, findings[], scanned} envelope with per-finding fields. This gives the agent a clear model of what the tool will do and return.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into three dense, purposeful parts: a one-line purpose statement, a scope-and-severity explanation, and a return envelope description. Every sentence adds value and the most identifying information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Because there is no output schema, the description correctly documents the return shape including the envelope and finding fields. It is nearly complete for a read-only RDS audit, but the region parameter's default and format are left under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one optional region parameter with 0% description coverage. The prose mentions 'in the region,' implying the parameter scopes the scan, but it does not explain the null default, accepted region format, or behavior when omitted. The description partially compensates but leaves the parameter semantics implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Audit RDS instance posture' and immediately lists the three concrete dimensions checked: public accessibility, storage encryption, and deletion protection. This specific verb+resource+scope clearly distinguishes it from the sibling audit tools, which target accounts, lambdas, EBS volumes, security groups, and other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the usage context clear by stating that it scans every RDS DB instance in the region and reports posture findings. It does not explicitly name alternatives or state when not to use it, such as pointing to audit_full_posture for a broader audit, so it misses the full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit the root account for missing MFA and active root access keys.
Reads the IAM account summary. No root MFA is a HIGH finding; any root access key present is a CRITICAL finding. Returns {check, ok, findings[], scanned} with scanned=1 (the single root identity) and the raw summary values in each finding's detail.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description discloses that it reads the IAM account summary, defines finding severities (HIGH for missing MFA, CRITICAL for root access keys), and details the exact return shape {check, ok, findings[], scanned} including scanned=1 and raw summary values in findings. This is rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences lead with the tool's core purpose, then explain the data source and findings, then give the return contract. Every sentence adds value and there is no redundant or filler information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only audit tool with no output schema, the description is fully complete: it names the checks, the severity levels, the response structure, and what each finding's detail contains. An agent has everything needed to invoke the tool and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema already covers 100% of them, so the baseline is 4. The description confirms there is nothing to configure and instead focuses on what the tool returns, which is appropriate for a no-input audit tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Audit the root account') and a specific resource ('root account') with explicit checks: missing MFA and active root access keys. It clearly distinguishes this from sibling audit tools by scoping itself to the root identity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for auditing the root account only, which implies when to choose it over sibling tools like audit_users_without_mfa. It does not explicitly name alternatives or exclusion criteria, but the root-account scope is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit IAM users for active access keys older than max_age_days.
Scans every IAM user and flags each Active access key whose age exceeds max_age_days. Returns {check, ok, findings[], scanned} where scanned is the number of users examined. Severity is HIGH when the key's owner has no MFA device (a leaked key is the only factor), MEDIUM when the owner has MFA.
| Name | Required | Description | Default |
|---|---|---|---|
| max_age_days | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnly/destructive annotations by disclosing that it scans every IAM user, flags only Active keys over the threshold, returns a specific shape with findings and scanned, and computes severity based on MFA presence. This gives the agent a clear model of behavior and side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the core purpose, the second describes behavior and return value, and the third covers severity. Each sentence adds necessary information without redundancy or padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only audit tool with no output schema, the description is fully sufficient: it details what is scanned, what is returned, and how severity is assigned. The agent can invoke and interpret the result without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema provides no parameter descriptions for max_age_day, the description explicitly explains its role as the age threshold and default value, making the parameter's semantics clear. It does not detail edge cases like zero or negative values, but the basic meaning is sufficiently covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Audit'), a clear resource ('IAM users'), and a precise condition ('active access keys older than max_age_days'). It unambiguously distinguishes this tool from siblings like audit_users_without_mfa or audit_full_posture.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly identifies the intended scenario: auditing IAM users for stale active access keys, and explains the threshold and severity logic. It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit CloudTrail trail posture in the account.
Checks, per trail (shadow trails included, so multi-region trails homed in another region are still seen):
trail exists at all (zero trails is a CRITICAL finding on its own)
the trail is actively logging (GetTrailStatus.IsLogging), CRITICAL if not
IsMultiRegionTrail, MEDIUM if single-region
LogFileValidationEnabled, MEDIUM if disabled
KmsKeyId present, LOW if logs are not encrypted with a customer managed key
Args: region: AWS region to query (defaults to AWS_REGION or us-east-1).
Returns:
Report envelope: {check, ok, findings[], scanned}. scanned is the
number of trails inspected; ok is true only when no findings exist.
Each finding has {check, severity, title, resource, detail} with
severity one of LOW/MEDIUM/HIGH/CRITICAL and resource "trail/"
(or "account" for the zero-trails finding).
| Name | Required | Description | Default |
|---|---|---|---|
| region | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and destructiveHint=false. The description adds substantial behavioral detail beyond annotations: exact checks performed, the criticality of zero trails, how multi-region trails are handled, severties for each failing check, and the precise return envelope and finding shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with purpose, check list, args, and returns sectioned clearly. The bullets are content-dense and every line provides actionable information, with no redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema present, the description fully specifies the return envelope, the fields in each finding, severity values, and resource naming. It also explains the default region behavior and the critical zero-trail finding, making it complete for an agent to invoke and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by documenting the only parameter 'region', including its default resolution to AWS_REGION or us-east-1. No other parameter information is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Audit CloudTrail trail posture' and enumerates exact checks. The detailed check list makes it unambiguous and clearly distinguishes it from sibling tools targeting RDS, EBS, IAM, or security groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use case is clear: audit CloudTrail trail posture in the account. It provides helpful context about scope, including shadow trails, but does not explicitly route the agent away from alternatives such as audit_full_posture or account_security_summary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit IAM users that can log in to the console without MFA.
Scans every IAM user, checks which ones have a console login profile, and flags those with no MFA device as HIGH severity. Returns {check, ok, findings[], scanned} where scanned is the number of users examined; users without console access are counted but never flagged.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive, and the description adds substantial behavioral detail: it scans every IAM user, considers console login profiles, flags only those with no MFA, reports HIGH severity, and clarifies that non-console users are counted but not flagged. The return object shape is also disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-sentence purpose, then a second sentence detailing scan behavior, severity, return shape, and edge-case handling. Every phrase adds value and no irrelevant details are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, read-only audit tool with no output schema, the description fully covers purpose, exact behavior, severity, return fields, and the edge case of users without console access. Nothing essential for selecting and invoking the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%, so there are no parameter semantics to document. Per the rubric, a parameterless tool earns a baseline of 4 because no additional description is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource-criterion combo: auditing IAM users who can log in to the console without MFA. It differentiates its scope from sibling audit tools by focusing specifically on console login profiles and MFA devices, and includes a concrete severity label (HIGH).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: when auditing IAM console access without MFA. It does not explicitly name alternatives or provide when-not-to-use guidance, but the purpose is specific enough that an agent can select it appropriately among the audit_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit EC2 security groups for ingress rules open to the world.
Scans every security group in the region (AWS_REGION or us-east-1 when the region argument is omitted) and flags each ingress rule whose source is 0.0.0.0/0 or ::/0. Rules allowing all traffic (protocol -1) or covering a sensitive port (SSH 22, RDP 3389, MySQL 3306, PostgreSQL 5432, Redis 6379, Elasticsearch 9200, MongoDB 27017) are HIGH; any other world-open port (for example 80 or 443) is MEDIUM.
Returns a dict {check, ok, findings, scanned} where ok is true only when no findings were produced, findings is a list of normalized finding dicts (check, severity, title, resource, detail with protocol, from_port, to_port, cidrs, group_name), and scanned is the number of security groups examined.
| Name | Required | Description | Default |
|---|---|---|---|
| region | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations: it explains the default region resolution from AWS_REGION, the exact CIDRs considered world-open, the severity classification for sensitive ports, and the full return dict shape with each key's meaning. This provides rich operational context that annotations alone do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded and each sentence adds operational detail. The layout clearly separates scope, severity criteria, and return value. It is long but every part is necessary for correct invocation and interpretation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description fully documents the return value including the fields in each finding. It also covers region behavior, scanning scope, and severity rules. Nothing essential is missing for an agent to select and invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, region, has no schema description, but the description fully compensates: it explains that region defaults to null, falls back to AWS_REGION, and then to us-east-1. This is exactly the semantic detail an agent needs to call the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Audit'), a specific resource ('EC2 security groups'), and a precise criterion (ingress rules open to the world). This clearly distinguishes it from sibling audit tools like audit_public_buckets or audit_ebs_exposure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear when this tool is relevant: when you need to audit security groups for world-open ingress. It also explains region selection behavior. It does not explicitly name alternative tools or exclusions, but the purpose is so specific that an agent can infer appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0account_security_summaryaudit_ebs_exposureaudit_full_postureaudit_lambda_resource_policiesaudit_public_bucketsaudit_rds_postureaudit_root_account_postureaudit_stale_access_keysaudit_trail_postureaudit_users_without_mfaaudit_world_open_security_groupsScored across 11 tools
Each tool targets a distinct AWS resource or audit domain (RDS, Lambda, CloudTrail, EBS, security groups, IAM, S3, root account), and the descriptions clearly specify scope. Minor overlap exists between account_security_summary and audit_root_account_posture (both touch root MFA) and between account-level and per-bucket S3 public access block checks, but the boundaries are still understandable.
The overwhelming majority follow a consistent audit_<resource>_<topic> pattern, which is predictable and searchable. Exceptions include account_security_summary (missing the audit_ prefix) and audit_world_open_security_groups (more verbose than the posture-named checks), but these are minor deviations rather than a broken convention.
11 tools is well within the ideal range and each tool corresponds to a meaningful audit check or aggregation layer. audit_full_posture consolidates the others instead of adding redundant surface area.
The server covers a broad set of critical AWS audit areas: compute, storage, database, serverless, networking, identity, root account, CloudTrail, and account-level posture. It lacks some optional AWS audit angles such as EC2 instance IMDS or KMS key audits, but for a security audit MCP the core lifecycle is well represented and the aggregate tool ties everything together.
AWS cloud security scanners for AI agents — S3, IAM, EC2, EKS, RDS, CloudTrail, CloudWatch Logs
Threat modeling, code/cloud/pipeline scanning, shadow-AI discovery, compliance checks and fixes.
Pay-per-call cybersecurity for AI agents: vuln scans, threat intel, compliance, code security.
HIPAA compliance AI agent — scan, grade, SRA, and generate compliance docs.
