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., "@strands-sentinel Audit this repository for safety issues and secrets"
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.
Autonomous mission-critical systems and AST safety auditor built with the Strands Agents SDK and the Model Context Protocol (MCP). Built for the AWS "Agents for Humans Hackathon" ($40,000 prize pool, Devpost).
strands-sentinel wires a Strands Agent to five deterministic audit tools
(AST safety invariants, secret scanning, sandboxed test execution, and
remediation guidance) behind an InterventionHandler that requires human
confirmation before any remediation action runs. Every finding traces back
to a real AST node, regex match, or subprocess result -- nothing is
inferred by the model and reported as fact.
Live Interactive Demo (Hugging Face Spaces): https://huggingface.co/spaces/IP11/strands-sentinel
Demo Video Walkthrough (MP4): assets/strands_sentinel_demo.mp4 (Direct link: https://huggingface.co/spaces/IP11/strands-sentinel/resolve/main/strands_sentinel_demo.mp4)
flowchart TD
CLI["cli.py<br/>check / watch / mcp"] --> Agent
MCP["mcp_server.py<br/>MCPServer (mcp>=2.1.0)"] --> Tools
Agent["agent.py<br/>strands.Agent"] --> Router["Model Router<br/>Bedrock / Anthropic / OpenAI / Gemini / Ollama"]
Agent --> Tools
Agent --> Intervention["intervention.py<br/>SentinelInterventionHandler"]
Tools["Five @tool functions"] --> Invariants["invariants.py<br/>AST/tokenizer engine"]
Tools --> Secrets["secret_scanner.py<br/>regex + Shannon entropy"]
Tools --> TestRunner["test_runner.py<br/>bounded subprocess"]
Intervention -->|Proceed| Tools
Intervention -->|Confirm| Human["Human approval"]
Script["scripts/audit_safety_invariants.py"] -.self-audits.-> InvariantsRelated MCP server: sdlc-integrity-mcp
uv venv .venv --python python3.12
uv pip install --python .venv/bin/python3 -e ".[dev]"
# One-shot audit of a path, prints a Rich report, exits 1 on any CRITICAL finding
.venv/bin/strands-sentinel check src/strands_sentinel
# Re-audit on every .py file change (bounded via --max-iterations for CI/tests)
.venv/bin/strands-sentinel watch src/strands_sentinel --interval 2
# Run as an MCP server over stdio (Claude Code CLI, Antigravity, Bedrock AgentCore)
.venv/bin/strands-sentinel mcpModel provider is selected by STRANDS_SENTINEL_MODEL_PROVIDER, or
inferred from ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY /
OLLAMA_HOST, defaulting to Bedrock (the only provider whose client
library -- boto3 -- ships as a strands-agents transitive dependency and
is therefore the only one exercised end to end by this test suite; the
other four fail fast with an actionable install message when their client
library is missing, rather than shipping an untested code path).
AST safety invariants (invariants.py), a practical subset of
Gerard J. Holzmann's Power of 10 rules: function length (<=60 lines),
assertion density (>=2 assert per function), bounded loops (while True without a statically reachable break is CRITICAL, with a break is
WARNING since runtime boundedness still isn't provable), mutable default
arguments, and banned dynamic-execution/deserialization calls (eval,
exec, os.system, pickle.load(s), yaml.load). Python is handled by
full ast analysis; Rust/TypeScript/JavaScript/Go/C/C++ get a
brace-counting length heuristic.
Secrets (secret_scanner.py): deterministic regex matches (AWS
access keys, GitHub PATs, EVM private keys, 12/24-word mnemonic-shaped
phrases) reported at CRITICAL, plus a Shannon-entropy (H >= 3.8) catch-all
for everything else reported at WARNING. Findings are always redacted
(AKIA****...**OP) before leaving the scanner -- raw secret values are
never returned, printed, or logged.
Tests: test_runner.py auto-detects cargo test, pytest, or make test from repository markers and runs the resolved command as a bounded
subprocess (a real list[str] argv, never a shell string, so there is no
command-injection surface), extracting structured per-test failures. The
parsers are verified against real pytest -q and cargo test output
captured in this environment, not an assumed format.
SentinelInterventionHandler overrides before_tool_call: the four
read-only audit tools always Proceed(); generate_remediation_patch (or
any tool call made while a CRITICAL finding is outstanding) requires
Confirm(prompt=...) -- human approval before anything that could act on a
finding. Confirm takes a prompt field, not message; this is the one
place this build corrected a wrong field name that had been assumed rather
than verified against the installed SDK.
make lint # ruff check + mypy --strict, 0 errors
make audit-invariants # this repo's own scripts/audit_safety_invariants.py, 0 violations
make test # pytest, 100% pass rate
make demo # runs the CLI against this package's own src/Measured on this repository (macOS arm64, Python 3.12.13, in .venv):
Check | Result |
Tests | 85 passed; 0.87-5.20s wall clock across repeated runs (no fixed number quoted -- see below) |
| 0 errors, 0 warnings (note: ruff has no |
| 0 errors across 9 source files |
| 0 violations (src/ + scripts/, self-inclusive, 9 files) |
Invariant scan, | 13.6 ms, 0 violations |
Secret scan, same 8 files | 2.6 ms, 0 CRITICAL, 7 WARNING (long identifier names crossing the entropy threshold -- the documented false-positive surface of the entropy tier, not the deterministic one) |
Repeated pytest runs measured: 1.91s, 5.16s, 5.20s, 1.10s, 0.87s, 0.88s
(same machine, no code changes between runs) -- quoted as a range rather
than a single number since the variance itself is real and worth being
honest about.
src/strands_sentinel/
invariants.py AST/tokenizer Power of 10 engine
secret_scanner.py regex + entropy secret detection
test_runner.py bounded pytest/cargo/make executor
intervention.py SentinelInterventionHandler
agent.py tools + resilient model router + Agent factory
mcp_server.py MCPServer (mcp>=2.1.0) exposing the five tools
cli.py check / watch / mcp subcommands
scripts/audit_safety_invariants.py standalone self-audit entry point
tests/ 85 tests across 7 filesEvery function in src/ has <=60 lines and >=2 assert statements,
enforced by scripts/audit_safety_invariants.py against its own source.
No emojis anywhere in source, docstrings, CLI output, or commit history.
Commits are authored as Ishant5436 <ishant.p@somaiya.edu>.
Run the full sentinel sweep (AST invariants and secret scan) over a workspace path.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the behavioral disclosure, but it only says 'Run the full sentinel sweep.' It does not state whether the operation is read-only, whether it modifies files, what happens on failure, or whether it can be safely run repeatedly. The name 'audit' hints at non-mutating behavior, but that is not explicit.
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 a single, front-loaded sentence that states the action, the scope, and the included components without any filler. Every word contributes to understanding what the tool does.
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?
The tool is simple with one required parameter, and the presence of an output schema reduces the need to describe return values. The description covers the core action and scope well, though it omits side-effect and usage details that are captured as weaknesses in other dimensions.
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 input schema only provides 'path' with no description, so the phrase 'over a workspace path' adds meaningful context that the parameter should point to a workspace. However, it does not specify path format, whether it must be a directory, or absolute vs. relative paths, leaving some ambiguity.
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 ('Run') and a specific resource ('full sentinel sweep over a workspace path'), and explicitly names the two components (AST invariants and secret scan). This clearly distinguishes it from the sibling single-purpose tools sentinel_check_ast_invariants and sentinel_scan_for_secrets.
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 'full sentinel sweep' with the parenthetical listing its components makes it clear this tool is the combined option versus the individual sibling checks. However, it does not explicitly state when not to use it or mention alternatives beyond the implied distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan a file or directory for Power of 10 AST safety invariant violations.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden. 'Scan' and 'AST' imply a static, read-only analysis, which is useful, but the description never explicitly states that files are not modified or that no permissions beyond read access are needed. It does not contradict annotations because none exist.
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?
A single sentence with zero filler. It front-loads the action and target and wastes no words, making it easy for an agent to parse quickly.
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?
The tool is simple with one parameter and an output schema, so the description need not explain return values. What is missing is guidance on sibling tool selection and any explicit side-effect statement, which leaves the description adequate but not fully complete.
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%, so the description must compensate. It adds the key meaning that 'path' may be a file or directory, which is not present in the schema. However, it omits format details, recursion behavior for directories, and accepted file types, so compensation is only partial.
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 and resource: 'Scan a file or directory for Power of 10 AST safety invariant violations.' It clearly identifies the tool's object and differs from siblings like sentinel_scan_for_secrets or sentinel_audit_workspace by focusing on AST invariants. It loses a point because 'Power of 10' is unexplained jargon, but the core purpose is unmistakable.
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 no guidance on when to use this tool versus its siblings, no exclusions, and no alternatives. It implies 'use when checking invariants' but never contrasts with sentinel_audit_workspace or sentinel_scan_for_secrets. An agent is left to infer selection criteria from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return structured remediation guidance for a violation previously reported by an audit tool.
| Name | Required | Description | Default |
|---|---|---|---|
| violation_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It says the tool 'returns' guidance, which suggests a read-only operation, but it does not disclose whether any state changes occur, whether credentials are needed, or what happens for invalid or unknown violation IDs.
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 a single, focused sentence with no filler. It front-loads the action and object, and every word contributes to understanding the tool's purpose.
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 simple one-parameter tool with an output schema, the description is mostly sufficient to guide a call. The main gaps are explicit usage boundaries and behavioral side effects, but these are minor given the tool's low complexity.
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%, and there is only one parameter, violation_id. The description adds meaning by tying the parameter to a previously reported audit violation, but it does not clarify the expected format, origin, or how to obtain a valid violation ID.
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 ('Return'), a specific resource ('structured remediation guidance'), and a clear precondition ('a violation previously reported by an audit tool'). This clearly distinguishes it from sibling tools like sentinel_audit_workspace or sentinel_run_test_suite.
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 the tool should be used after an audit tool has reported a violation, which gives useful context. However, it does not explicitly state when not to use it or name alternative tools for related scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the test suite for a repository. Pass command="" to auto-detect pytest/cargo test/make test.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| command | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states that it runs the test suite and that an empty command auto-detects pytest/cargo test/make test. It does not mention whether the tool executes arbitrary commands, whether it modifies workspace state, what permissions are needed, or what happens on failure.
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?
Two short sentences with no wasted words. The main action is front-loaded, and the auto-detect tip is a valuable addition that earns its place.
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?
The presence of an output schema relieves the need to describe return values, and the command auto-detect behavior is explained. However, path semantics are omitted, and there are no behavioral caveats about executing tests in an environment. For a two-parameter tool, the description is adequate but leaves notable gaps.
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%, so the description must compensate. It usefully explains the command parameter's empty-string auto-detection behavior, but it gives no meaning for the path parameter beyond the vague 'for a repository'. Partial compensation for one of two parameters warrants a mid score.
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 the specific action 'Run' and the resource 'the test suite for a repository'. Sibling tools focus on auditing, invariants, secret scanning, and remediation patches, so the test-suite scope is distinct, but the description does not explicitly name a sibling or call out the distinction.
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 a how-to tip for the command parameter but gives no when-to-use guidance or alternatives. It doesn't explain when to prefer this over sibling tools like sentinel_check_ast_invariants or sentinel_scan_for_secrets, leaving usage context entirely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan a file or directory for hardcoded secrets using deterministic patterns and entropy.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the method ('deterministic patterns and entropy') but omits critical traits: whether the scan is read-only, whether it scans recursively, how it handles binary files, whether it requires network access, or what the output format looks like. This leaves the agent uncertain about side effects and expected results.
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 a single, front-loaded sentence with zero wasted words. It efficiently conveys the core action and scope. The structure is ideal for quick parsing by an agent, earning top marks for conciseness despite the other gaps.
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 scanning tool with a single parameter, the description is incomplete. It does not explain what triggers a 'secret' match, how deep the scan goes, whether it follows symlinks, or what the output schema contains (though an output schema exists, its details are not in the description). The agent lacks enough context to predict tool behavior 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?
The schema description coverage is 0%, so the description must compensate. It does clarify that 'path' can be a file or directory, which adds some meaning. However, it does not specify whether the path must be absolute, whether glob patterns are accepted, or what constitutes a valid path for the scan. This is minimal added value over the parameter name.
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 (scan), a concrete resource (file or directory), and the target (hardcoded secrets) with a method (deterministic patterns and entropy). It clearly differentiates from sibling tools like sentinel_audit_workspace or sentinel_run_test_suite, which target different concerns. The verb 'scan' plus the object 'hardcoded secrets' leaves no ambiguity about the tool's core function.
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?
There is no guidance on when to use this tool versus the siblings. The description does not mention prerequisites (e.g., requiring a git repo), conditions (e.g., before code review), or exclusions (e.g., not for detecting secrets at runtime). Without such context, an agent may misuse it or fail to know when it is the appropriate choice.
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.1.0sentinel_audit_workspacesentinel_check_ast_invariantssentinel_generate_remediation_patchsentinel_run_test_suitesentinel_scan_for_secretsScored across 5 tools
The tools are mostly distinct, but sentinel_audit_workspace overlaps with sentinel_check_ast_invariants and sentinel_scan_for_secrets since it runs both checks in one sweep. The descriptions clarify that the audit tool is a combined execution, but an agent might be unsure whether to call the aggregate or individual scanners.
All tool names follow the consistent pattern sentinel_<verb>_<noun> (audit_workspace, check_ast_invariants, scan_for_secrets, run_test_suite, generate_remediation_patch). The verbs are clear and snake_case is used uniformly.
Five tools is well-scoped for a security/quality sentinel server. Each tool covers a distinct operation without bloat, and the count feels appropriate for the stated purpose.
The surface covers auditing, AST invariant checks, secret scanning, test execution, and remediation guidance. A minor gap is the lack of a dedicated tool to list or query prior violations (though audit results presumably include them), and remediation only provides guidance rather than applying fixes.
Security reviews for coding agents: diffs checked against your org policy and live infrastructure.
Security & DLP proxy for MCP: tool-poisoning scans, PII redaction on tool args/results. Beta.
Threat modeling, code/cloud/pipeline scanning, shadow-AI discovery, compliance checks and fixes.
Zero-config MCP security scanner for AI-generated apps. 25K+ vulnerability patterns.
