secure-mcp-server

An MCP server for Kali Linux that deliberately has no shell access. Read-only, allowlisted tools behind OAuth 2.0 + PKCE, TLS, rate limiting, and audit logging.

Current release: v1.0.0

Why this project exists

Many MCP servers give an AI client a generic shell or exec endpoint. That makes a single prompt-injection or a leaked token potentially equivalent to broad control of the host.

secure-mcp-server takes the opposite approach: the client can only call a small set of explicitly registered, read-oriented tools. There is no shell, no command execution endpoint, and no arbitrary code execution interface.

Access is authenticated with OAuth 2.0 + PKCE and scoped to mcp:read.

Related MCP server: Kali Factory MCP Server

Features

• OAuth 2.0 Authorization Code and Refresh Token flows with PKCE (S256)

• Single MCP scope: mcp:read

• Dynamic public-client registration

• Token revocation

• SQLite-backed OAuth state

• Interactive consent step

• JWT signing with EdDSA (Ed25519)

• HTTPS with minimum TLS 1.2

• ECDSA P-256 certificate generation and validation

• DNS rebinding protection and explicit host allowlisting

• Rate limiting on /register, /authorize, /token, /revoke, and /mcp

• Audit logging with recursive redaction of sensitive arguments

• Refuses to run as root

• Read-only, explicitly registered MCP tools

• Test coverage for OAuth, transport security, TLS, rate limiting, validation, and tools

Architecture

MCP Client (e.g. Termux)
        |
        | HTTPS + OAuth 2.0 + PKCE
        v
Kali Linux MCP Server
        |
        +-- Streamable HTTP
        +-- Host validation
        +-- Rate limiting
        +-- OAuth authorization
        +-- Audit logging
        |
        v
Allowlisted read-only MCP tools

The client connects over the local network to:

https://<MCP_PUBLIC_HOST>:<MCP_PORT>/mcp

Available Tools

read_text_file restrictions

read_text_file is deliberately restricted:

• Files must remain within the project workspace.

• Absolute paths are rejected.

• Path traversal is rejected.

• Symlink escapes outside the permitted workspace are rejected.

• Maximum readable file size is 1 MiB.

New capabilities should be added as dedicated tools. Do not add generic command execution.

Security Model

Authentication and authorization

• OAuth 2.0 Authorization Code flow

• Refresh Token flow

• Public-client registration

• PKCE with S256

• Single supported MCP scope: mcp:read

• Resource validation

• Short-lived authorization requests and authorization codes

• Authorization codes are single-use

• Refresh tokens are stored hashed

• Token revocation is enabled

• Dynamic registration is limited to the supported scope

PKCE

PKCE protects the authorization-code exchange for the public-client model used by this project.

The integration test verifies the S256 flow, including rejection of an incorrect code verifier.

Token lifetimes

Transport security

• HTTPS only

• Minimum TLS 1.2

• Restricted ECDSA cipher suites

• DNS rebinding protection

• Explicit host allowlisting

• ECDSA P-256 certificates

• Certificate SAN validation

• Certificate/private-key matching checks

Rate limiting

Rate limiting is applied to:

/register
/authorize
/token
/revoke
/mcp

Default:

10 requests / 60 seconds

Both values are configurable.

Audit logging

Audit records are written to:

logs/audit.log

Records include:

• Timestamp

• Tool name

• Sanitized arguments

• Execution status

• Result or error information

Sensitive keys are recursively redacted, including:

api_key
authorization
client_secret
password
refresh_token
secret
token

The sanitizer handles nested dictionaries and sequences without modifying the original input.

Threat Model and Limitations

This project reduces the blast radius of giving an AI client access to a Kali host. It does not make the host safe to expose to the public internet.

Designed to protect against

• Arbitrary command execution through the MCP interface

• Unauthenticated access to protected tools

• Authorization-code interception risks addressed by PKCE

• DNS rebinding against the local server

• Brute-force and flooding of protected endpoints through rate limiting

• Sensitive values leaking into audit logs

Not covered / known limitations

• Intended for use on a trusted local network

• Public internet exposure is not a supported deployment scenario

• The project has not been independently audited

• Dynamic client registration is available to clients that can reach the server; authorization still requires the configured consent flow

• The default certificate is self-signed

• Anything an authorized read-oriented tool can return can be viewed by the authorized client

• The rate limiter is process-local and does not provide distributed/shared rate-limit state

Review every tool before adding it to the allowlist.

Configuration Reference

Configuration is controlled through environment variables defined in config.py.

Keep private keys, OAuth state, and audit logs out of version control.

Quick Start

Prerequisites

• Kali Linux or another Linux host with Python 3 and openssl

• A non-root user

• A client that supports MCP over Streamable HTTP with OAuth

1. Install

git clone https://github.com/Zer-security/secure-mcp-server.git
cd secure-mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
mkdir -p logs data secrets/tls

2. Generate JWT signing keys

openssl genpkey -algorithm ED25519 -out secrets/jwt-ed25519-private.pem
openssl pkey -in secrets/jwt-ed25519-private.pem -pubout -out secrets/jwt-ed25519-public.pem
chmod 600 secrets/jwt-ed25519-private.pem

3. Generate the TLS certificate

PYTHONPATH=. python scripts/generate_tls.py

The generated certificate uses ECDSA P-256. Certificate handling includes certificate/key compatibility checks, SAN validation, backup, and rollback on promotion failure.

The default certificate is self-signed, so an MCP client must be configured to trust it.

4. Configure

Set the server's LAN address:

export MCP_PUBLIC_HOST=192.168.x.x
export MCP_PORT=8000

The server uses explicit host validation based on the configured public host and port.

5. Run

PYTHONPATH=. python server.py

The MCP endpoint is:

https://<MCP_PUBLIC_HOST>:8000/mcp

The server refuses to run as root.

6. Connect a client

Point an MCP-compatible client at the MCP endpoint.

The authorization flow uses dynamic public-client registration, an interactive consent step, OAuth 2.0 Authorization Code flow, and PKCE S256.

Testing

The release v1.0.0 was verified with:

124 passed

Historical full-suite command used for v1.0.0:

PYTHONPATH=. ./venv/bin/pytest -q

Current CI command:

PYTHONPATH=. pytest -q --ignore=tests/test_integration.py

Current CI verification: 123 passed.

The suite covers:

• OAuth provider and integration flow

• Authentication

• Transport security

• TLS

• Rate limiting

• SSRF/network security

• Input validation

• File tools

• MCP tools

• Audit logging and sanitization

• Configuration

The release commit is:

f642badaa27315e6b446e1b4370cf113fdc652e1

Project Structure

secure-mcp-server/
├── core/
│   ├── audit_extension.py
│   ├── audit_sanitizer.py
│   ├── oauth_provider.py
│   ├── oauth_routes.py
│   ├── rate_limit.py
│   ├── security.py
│   ├── ssrf.py
│   └── validation.py
├── scripts/
│   └── generate_tls.py
├── tools/
│   ├── file_tools.py
│   ├── info_tools.py
│   ├── network_tools.py
│   └── system_tools.py
├── tests/
├── config.py
├── server.py
├── test_client.py
├── requirements.txt
├── LICENSE
└── README.md

Development Principles

• Least privilege and explicit allowlisting

• Secure defaults

• No generic shell or command execution

• No hardcoded secrets

• Input validation

• Authentication before protected operations

• Auditability

• Fail-safe behavior

• Reproducible testing

• Evidence-based security claims

Workflow:

Implement
   ↓
Test
   ↓
Verify
   ↓
Document

A feature should not be described as secure merely because it exists in source code. The implementation and relevant tests should be verified first.

Roadmap

• GitHub Actions CI with automated tests

• Dependency/update automation

• Additional read-only tools reviewed against the least-privilege model

• Documented MCP client setup guides

• Additional security hardening based on verified requirements

Responsible Use

Use this software only on systems you own or are explicitly authorized to administer or test.

The project is intended for controlled, authorized environments and should not be treated as a general-purpose remote administration interface.

Security Policy

If you discover a security vulnerability, avoid publishing sensitive details in a public issue.

Use the repository's GitHub Security Advisory mechanism for private vulnerability reporting.

License

Licensed under the Apache License 2.0.