Aegis MCP
Aegis MCP enables ten-step confidentiality hardening assessments, remediation planning/application/rollback, audit comparison, and report generation via MCP tools.
Retrieve the exact ten-step hardening guide and ISO references.
List registered target IDs and capabilities without connecting to targets.
Audit a target: collect read-only Linux evidence and save a local audit snapshot.
Create a sealed hardening plan with exact diffs, prerequisites, supported actions, and manual work (no target changes).
Apply a reviewed sealed plan with explicit local write opt-ins and root access, including backups, validation, and after evidence.
Rollback an applied plan, rejecting drift and collecting new evidence.
Compare evidence status changes between audits for the same target registration.
Get compact ten-step evidence, report director, and narrative schema for reporting.
Render offline HTML, Markdown, and JSON reports; narrative is escaped commentary and cannot override observed tables.
Allows auditing existing Docker containers for confidentiality readiness, gathering read-only system evidence and producing professional reports. Docker targets are audit-only; Aegis does not provision, restart, or rebuild containers.
Provides read-only audits and supported hardening for existing Linux systems (local, WSL, or SSH-accessible), including evidence collection, remediation plans, verification of changes, and report generation.
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., "@Aegis MCP Audit my registered wsl target and generate a confidentiality report."
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.
Aegis MCP
An AI-assisted, ten-step confidentiality hardening project for Linux and Windows architectures, with MCP integration and professional reporting.
The auditor uses OpenCode, another MCP-compatible AI host, or a custom SDK application. The host connects the chosen model to Aegis; Aegis collects evidence from operator-registered systems, evaluates it against an embedded best-practice guide, and renders a professional English report. The model explains findings and priorities while the server supplies the evidence tables, ISO references and visual design.
Project subject: Summary of a Ten-Step Best-Practice Guide to the Hardening Process of an Information System in Preparation for a Confidentiality Audit
The guide and every report preserve exactly ten steps. The operator provides an authorized existing architecture; this repository implements the MCP server and report workflow.
Implementation status: Linux, Linux inside WSL, Linux VPSs over SSH and existing Linux containers have implemented collectors. Native Windows uses a separate PowerShell collector in the extension design below; that collector and Windows-specific checks are planned. A WSL assessment records the Linux guest, while a native Windows assessment must record Windows settings.
Architecture · Audit workflow · Ten-step guide · ISO references · Setup · Report preview
Who uses it and why
User | Use | Deliverable |
Auditor or student | Assess an authorized system using the ten-step method | Traceable findings, missing evidence and an English audit dossier |
System administrator | Review a hardening plan and verify supported changes | Exact diffs, prerequisites and a before/after comparison |
Professor or technical reviewer | Follow the method from system observations to conclusions | Consistent ten-step structure, ISO mappings and independent review items |
Related MCP server: sec-ops-mcp
System architecture
flowchart TB
Auditor["Auditor / system owner"] --> Host["OpenCode / MCP host / custom SDK app"]
Host <-->|"Inference"| Model["Chosen language model"]
subgraph Aegis["Aegis MCP — this project"]
Server["Tools · resources · prompts"]
Registry["Operator target registry"] --> Server
Guide["Ten steps + ISO references"] --> Server
Server --> Collector["Bounded collectors + check engine"]
Collector --> Evidence["Private evidence snapshots"]
Server -->|"AI narrative"| Renderer["Report context + template engine"]
Evidence --> Renderer
end
Host <-->|"MCP: stdio / loopback HTTP"| Server
Collector <-->|"Registered access"| Linux["Linux / WSL / VPS / Docker"]
Collector -.-> Windows["Native Windows workstation / server<br/>PowerShell collector — planned"]
Renderer --> Reports["English HTML / Markdown / JSON"]
Reports --> Review["Auditor review · browser print-to-PDF"]
classDef planned stroke-dasharray: 5 5
class Windows plannedThe host coordinates; the model interprets; Aegis collects, evaluates and renders; the auditor reviews. Model credentials and inference belong to the host. Aegis uses the MCP protocol to expose capabilities to that host, as described in the official MCP architecture.
Layer | Implementation | Responsibility |
MCP interface |
| Expose nine tools, four resources and two prompts over stdio or loopback HTTP |
Method and references |
| Keep the exact subject, ten guide steps, ISO identifiers and AI workflow instructions |
Audit orchestration |
| Collect observations, evaluate checks, preserve review gaps and manage plans/comparisons |
Target access |
| Resolve registered IDs and run fixed, bounded Linux collection/remediation operations |
Evidence custody |
| Store SHA-256-addressed snapshots, HMAC-sealed plans and chained workflow events |
Report generation |
| Validate AI narrative and generate consistent offline reports from recorded evidence |
The operator configures addresses, access, container names and metadata paths locally. MCP calls use registered IDs such as wsl or vps; the model cannot supply an arbitrary destination or shell command through Aegis tools. An architecture with several registered nodes is assessed node by node, with a separate audit/report for each target. Dashed Windows elements show the planned extension. Technical data flow and trust boundaries.
From an audit request to a report
Phase | Interaction | Result |
Define the scope | Auditor registers owned/authorized targets; host connects Aegis to the selected model | Known target IDs and explicit access boundaries |
Load the method | Model calls | Exact subject, ten steps, ISO references and target capabilities |
Gather evidence |
| Timestamped observations, check statuses, review items and an |
Review treatment | If requested, | Supported actions, exact diffs, prerequisites and manual work |
Verify changes | When authorized and enabled, apply the plan and compare the returned after audit with the before audit | Recorded changes and observed status transitions |
Draft once |
| Model writes a short summary, priorities and optional step notes |
Render and review |
| HTML, Markdown and JSON paths for auditor review; PDF via browser printing |
The read-only audit-to-report path works without applying a plan. For example, an auditor can ask OpenCode to assess wsl, receive an audit ID, review gaps and produce a report using the same snapshot. Reassessing is useful after a change or when evidence has become stale.
The ten-step method
Step | Best-practice domain | Confidentiality purpose | Suggested ISO/IEC 27001 Annex A controls |
01 | Scope, inventory and classify | Know which assets and data need protection | A.5.9, A.5.12, A.5.13 |
02 | Maintain a patched baseline | Reduce exposure from vulnerable software | A.8.8, A.8.9 |
03 | Constrain identities and access | Permit access only to approved identities | A.5.15, A.5.16, A.5.18, A.8.2, A.8.5 |
04 | Separate network trust zones | Restrict unintended paths to sensitive services | A.8.20–A.8.22 |
05 | Protect cryptography and keys | Protect confidential data in transit and storage | A.8.24, A.5.17 |
06 | Reduce system attack surface | Reduce information leaks and excess privilege | A.8.9, A.8.19, A.8.27 |
07 | Minimize data exposure | Reduce permissive files and data disclosure | A.8.3, A.8.11, A.8.12, A.5.34 |
08 | Observe and investigate access | Produce usable access and incident evidence | A.8.15–A.8.17 |
09 | Secure backups and prove recovery | Protect copies and demonstrate recovery | A.8.13, A.5.30 |
10 | Validate and build the audit dossier | Preserve evidence, review gaps and verify changes | A.5.35, A.5.36, A.8.32 |
Each step supplies a risk, best practice, expected audit evidence and suggested standards mapping. Technical checks use pass, fail, unknown or not_applicable; organizational and application controls retain independent human review items. Missing evidence and inherited host controls never become passes. Read the complete embedded guide.
How ISO references guide the assessment
Reference | Role in the project | Auditor's use |
ISMS requirements and suggested clause/Annex A mappings | Establish scope, assess risks and validate control applicability | |
Guidance for information-security controls | Consult implementation guidance and identify the evidence needed for each domain | |
ISO/IEC 27001:2022/Amd 1:2024, linked from the official 27001 page | Amendment concerning organizational context | Include the amendment when reviewing the actual ISMS context |
The model obtains the project's original guidance and official reference links through get_hardening_guide, aegis://standards/mappings and get_report_context. Clause and control identifiers orient the assessment; they are suggested mappings for the auditor to validate against the organization and its Statement of Applicability (the record of applicable controls and their justification).
For the normative text, the auditor follows the official ISO links or uses institutional access under its permitted terms. The MCP supplies original guidance, identifiers and links; the full standards remain separately managed references. ISO's publication terms also govern permitted AI use of its text. Technical snapshots support audit preparation and require organizational evidence and independent review before any conformity conclusion.
Getting started
Requires Python 3.11+, uv and a Linux execution environment. Run the server in WSL when using a Windows machine. SSH targets and existing containers need Python 3.9+ inside the target; missing tools are recorded as missing evidence.
uv sync --frozen
cp --no-clobber targets.example.yaml targets.yaml
# Edit targets.yaml: keep only targets you own and intend to assess.
uv run aegis doctor
uv run aegis-mcpaegis-mcp waits for an AI client over stdio. It does not print a dashboard. Register the launch command in your MCP client using the connection examples.
You can verify setup before connecting an AI:
uv run aegis guide
uv run aegis targets
uv run aegis audit wsl
# Save the returned audit_id and use it in the following commands.
uv run aegis plan wsl --audit <audit_id>
uv run aegis report --audit <audit_id>The report command fills the existing template with deterministic summary prose. A connected AI can supply a richer narrative through get_report_context and render_report.
Connect OpenCode or another AI host
Integration | Connection | Model handling |
OpenCode | Merge examples/opencode.json; verify with | Select/configure the model in OpenCode |
Another MCP-compatible host | Use the matching stdio, VS Code or HTTP example | The host manages its model and tool-use policy |
Custom SDK application | Use an MCP SDK client plus a model SDK or local inference runtime | Your application forwards tool requests/results and controls the agent loop |
For OpenCode, follow the setup instructions. Look for aegis connected; tools appear with names such as aegis_audit_target. The configuration shape is an mcp mapping, documented in OpenCode's official MCP guide.
For clients using the common mcpServers configuration shape:
{
"mcpServers": {
"aegis": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/audit_mcp", "run", "--frozen", "aegis-mcp"],
"env": {
"AEGIS_TARGETS": "/absolute/path/to/audit_mcp/targets.yaml",
"AEGIS_WORKSPACE": "/absolute/path/to/audit_mcp/.runtime",
"AEGIS_ALLOW_APPLY": "0"
}
}
}
}Use absolute paths and make uv available to the client process. Client configuration shapes differ; see connection examples. Aegis works with MCP-compatible AI hosts. A model without an MCP host needs an adapter. Your chosen host handles model credentials and inference; Aegis does not call a paid model itself.
Suggested first request:
Use Aegis to summarize the ten-step hardening best-practice guide, audit my registered
wsltarget for confidentiality readiness, and produce a professional English report using the embedded template. Keep missing evidence and human review items visible. Do not apply target changes.
MCP interface
Tool | Result |
| Exact English subject, ten steps and ISO links |
| Locally registered IDs and capabilities |
| Read-only target observations and a SHA-256 audit ID |
| Sealed plan, exact diffs, prerequisites and manual work |
| Supported changes, target backup and after evidence |
| Restore managed settings and collect new evidence |
| Status transitions between snapshots |
| Compact ten-step evidence, writing brief and narrative schema |
| Offline HTML, Markdown and JSON files |
Resource | Supplies |
| Exact subject and ten-step best-practice guide |
| Suggested clause/control identifiers and official reference links |
| Instructions for concise, evidence-based AI narrative |
| Packaged report structure |
Two reusable prompts orient the model: confidentiality_audit(target_id) guides assessment, and professional_report(audit_id, before_audit_id?) supplies report context. Hosts that primarily support tools can follow the same workflow through the nine tools above.
Professional report, with little model effort
The design is built in: editorial cover, mint accents, clear typography, ten-step evidence sections, ISO control chips, status filters, search, a before/after comparison and a print-to-PDF layout. It requires no external fonts, analytics or network requests.
The AI receives compact facts and a strict narrative schema. It drafts the title, executive summary, priorities and optional step notes once. The server generates all tables and styling. Narrative cannot override collected counts or statuses. HTML is escaped and protected by a restrictive content-security policy.
Artifact | Contents | Use |
| Ten-step findings, review items, AI narrative, references and visual navigation | Present the assessment; print/save a PDF in a browser |
| The same assessment in readable Markdown | Review conclusions and share approved text |
| Compact assessed evidence, scope, ISO mappings and optional comparison | Inspect the data supporting the report |
render_report returns absolute paths under .runtime/reports/ for the selected audit. The template handles formatting and tables so the model can focus on concise, evidence-based interpretation.
Reports and system evidence stay in .runtime/, which is ignored by Git. Evidence may include operational hostnames, usernames and configured paths: review a report before sharing it externally.

The interactive report preview uses synthetic evidence to demonstrate the design. See the report structure and narrative contract.
Target scope and supported hardening
Target | Access adapter | Status | Assessment boundary |
Existing local Linux / WSL | Local Python collector | Implemented | Linux guest evidence; WSL findings do not establish Windows-host security |
Existing Linux VPS | Key-authenticated SSH with strict host-key checks | Implemented | Visible guest settings and operator-configured metadata paths |
Existing Linux Docker container |
| Implemented | Container evidence; audit-only, with host controls requiring separate assessment |
Native Windows workstation / server | Bounded PowerShell collector and Windows checks | Planned | Windows configuration evidence under the same ten-step method |
Linux is the implemented collection scope. Application IAM, cloud policies, hypervisors and organizational practices require separate evidence and human review. SSH/container targets need Python 3.9+; collection needs the permissions appropriate to each check. The collector is ephemeral and reads fixed system settings and configured file metadata.
The native Windows design retains the same MCP workflow and report structure, using Windows-specific evidence for updates, privileged accounts, firewall profiles, BitLocker status, service privileges, NTFS permissions, audit logging and backups. Its checks should use an operator-approved baseline, guided by Microsoft's Windows security baselines. See the Windows extension design; it requires implementation and operational validation before native Windows audits are available.
Audit collection is read-only on the target. Target changes require both AEGIS_ALLOW_APPLY=1 in the server environment and allow_apply: true for the target. The operator still controls conversational authorization through the AI host.
The current automatic catalogue is deliberately explicit:
Linux kernel information-disclosure and link-protection settings:
dmesg_restrict,kptr_restrict,protected_hardlinks,protected_symlinks.A managed login-shell
umask 027drop-in. Existing processes and service policies are unaffected.Key-only SSH and disabled direct root SSH login, after independent key access and configuration prerequisites are verified locally.
Patching, firewall changes, application IAM, volume encryption, MFA, logging custody, backup encryption and restore exercises are guided work requiring environment-specific review. Docker targets are audit-only; WSL kernel controls are inherited from its host. Aegis does not provision, restart or rebuild containers.
Read the exact prerequisites and rollback behavior before enabling target writes.
Development and verification
uv sync --frozen
uv run ruff check src tests scripts
uv run pytest -q
uv run python scripts/check_repository.py
uv run pip-audit --skip-editable
uv buildTests cover the real MCP protocol using synthetic target evidence, target/option injection, evidence tampering, local permission gates, stale plans, rollback, inherited-control handling, report escaping and content-security hashes. Adapter and operational test boundaries are documented in validation.
Repository layout
src/aegis_mcp/ MCP server, bounded collector, adapters, evidence and reporting
assets/prompts/ Ten-step workflow and one-pass report director
assets/templates/ Professional offline HTML/CSS/JS template
docs/ Setup, guide, architecture, hardening and template preview
examples/ MCP host configuration examples
tests/ Protocol, security and report regression tests
scripts/ Publication checks and synthetic template preview
targets.example.yaml Operator target configuration template
uv.lock Locked dependenciesISO mapping references: ISO/IEC 27001:2022, ISO/IEC 27002:2022. This repository contains original guidance and control identifiers, not copied ISO standard text. See SECURITY.md and MIT license.
Available Tools
9 toolsapply_hardening_planADestructive
Apply a reviewed, sealed plan to its registered target; requires explicit local write opt-ins and root access. Backs up, validates and collects after evidence.
Inputs: plan_id (required). Returns: object
audit_targetB
Collect read-only Linux evidence and save a local audit snapshot. No target configuration changes.
Inputs: target_id (required). Returns: object
compare_auditsBRead-only
Compare evidence status changes for the same target registration.
Inputs: after_audit_id (required), before_audit_id (required). Returns: object
create_hardening_planA
Build a sealed plan with exact diffs, supported actions, prerequisites and manual work. Does not modify the target.
Inputs: audit_id (required), target_id (required). Returns: object
get_hardening_guideBRead-only
Return the exact English subject and the ten-step confidentiality hardening guide.
Inputs: no named parameters. Returns: object
get_report_contextBRead-only
Get the compact ten-step evidence bundle, report director and narrative schema. The server handles design and tables; draft the narrative once.
Inputs: audit_id (required), before_audit_id. Returns: object
list_targetsARead-only
List operator-registered target IDs and capabilities. Does not connect to targets.
Inputs: no named parameters. Returns: object
render_reportB
Fill the supplied professional template and export offline HTML, Markdown and JSON. Narrative is escaped commentary; observed tables cannot be overridden.
Inputs: audit_id (required), narrative, before_audit_id. Returns: object
rollback_hardening_planADestructive
Restore the backed-up managed configuration for a successfully applied plan; rejects drift and collects after evidence.
Inputs: plan_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool maps to a distinct stage of the hardening workflow (guide, targets, audit, plan, apply, rollback, compare, report). The only mild overlap is between get_hardening_guide and get_report_context, both informational retrievals, but descriptions make their purposes clearly separable.
All nine tools follow a consistent snake_case verb_noun pattern (get_, list_, audit_, create_, apply_, rollback_, compare_, render_). No mixed conventions or stylistic deviations.
Nine tools are well-scoped for a focused Linux hardening and reporting workflow, with each tool earning its place at a distinct lifecycle stage. No redundant or trivially thin tools.
The surface covers a full lifecycle: guidance, target listing, audit, plan creation, apply, rollback, comparison, and reporting. The only apparent gap is a register/remove target operation, since targets are described as operator-registered out of band.
Maintenance
Related MCP Connectors
Compliance frameworks (SOC 2, ISO 27001, CMMC, NIST, more) delivered to AI agents as MCP tools.
Cited, standards-aware compliance overlay for AI assistants (ISO, NIST, FedRAMP, IRAP), over MCP.
Independent AI-governance measurement MCP. Free reads + x402 evidence. Measurement not cert.
AI agent security, MCP 2026 schema & graph audits, <250ms guardrails, and compliance dossiers
Related MCP Servers
- AlicenseAqualityDmaintenanceA secure, read-only MCP server for AI-powered system monitoring. It provides real-time OS metrics, config discovery, and safe log tailing to enable autonomous infrastructure audits without shell access risks.42ISC
- AlicenseNot gradedqualityCmaintenanceEnables LLMs and AI agents to perform defensive security posture assessments, privilege escalation surface audits, and post-quantum cryptography readiness checks through read-only diagnostic tools.MIT
- AlicenseNot gradedqualityCmaintenanceEnables enterprise MCP security auditing through 12 deterministic no-LLM tools for evidence-gated claims, skill/prompt supply-chain audits, token profiling, and server auth-mode checks.MIT
- AlicenseBqualityBmaintenanceEnables read-only inspection of local Windows and Linux systems for host, resource, network, service, software, identity, startup, certificate, SSH key metadata, and environment-variable name evidence through MCP tools. It normalizes platform outputs into stable schemas while avoiding arbitrary shell execution, credential reads, secret values, or remediation.23MIT