Content
# Endevor-MCP v1.0.0
A Model Context Protocol (MCP) server providing 43 tools for complete Broadcom Endevor SCM interaction via the REST API v2. Built for AI-driven mainframe operations — inventory browsing, element lifecycle management, package workflows, and security-focused source code review.
## Endevor-MCP + hack3270: Source-Informed Mainframe Penetration Testing
**Endevor-MCP becomes exceptionally powerful when paired with [hack3270](https://github.com/gglessner/hack3270)** (52 MCP tools for TN3270 data stream manipulation). Together they give a single AI agent 95 tools — the ability to read every line of source code behind a mainframe application *and* operate the live application simultaneously. This is a fundamentally different class of testing capability.
### Why This Matters
Mainframe CICS applications were architected in the 1980s-2000s around a trust model that no longer holds: **the 3270 terminal was the security boundary.** Field protection, numeric-only restrictions, field length limits, hidden fields, and screen flow control were all enforced by the terminal hardware — not the server. The COBOL programs behind these screens routinely accept MAP input and use it directly in arithmetic, SQL queries, file access, and transaction routing without any server-side validation.
hack3270 breaks this trust model. It intercepts the TN3270 data stream and lets you modify protected fields, send non-numeric data to numeric fields, overwrite hidden fields, bypass screen flow, and send arbitrary AID keys — none of which a real 3270 terminal would allow.
**But without source code, hack3270 testing is blind.** You can fuzz fields and watch for crashes, but you don't know *why* a field is vulnerable, *what* the server does with your input, or *where* the real attack surface is. You're guessing.
**Endevor-MCP eliminates the guessing.** With access to the Endevor source code repository, the AI agent can:
- **Read the BMS map** to know every field on every screen — including hidden dark fields, protected fields, and their expected data formats — before touching the live application
- **Read the COBOL program** to see exactly what happens after `EXEC CICS RECEIVE MAP`: which fields are validated, which are trusted blindly, which go directly into `EXEC SQL` statements, which control transaction routing
- **Read the copybooks** to know the `PIC` clause of every field — the difference between `PIC X(10)` (alphanumeric) and `PIC S9(7)V99 COMP-3` (packed decimal that will SOC7 abend on invalid data)
- **Read the JCL** to understand batch job structures, dataset naming conventions, STEPLIB concatenations, and find hardcoded credentials — intelligence that becomes immediately actionable if TSO escape is achieved
- **Trace program flow** through `EXEC CICS LINK` and `EXEC CICS XCTL` chains to find authorization bypasses where a sensitive program can be invoked directly, skipping the security check in the calling program
- **Review change history** to prioritize testing on recently modified code — new code has new bugs
The result: instead of blind fuzzing with hack3270, the AI agent performs **surgical, source-informed exploitation**. It reads the COBOL source, identifies that `ORDQTYI` goes directly into a `COMPUTE` with no `IS NUMERIC` check, then uses hack3270's `send_field_data()` to send alphabetic characters to that field and trigger the SOC7 abend. It reads the `EVALUATE EIBAID` block, discovers PA1 invokes an undocumented admin menu, then uses hack3270's `send_aid_key()` to access it. Every finding from source code can be proven live, and every live anomaly can be traced back to its root cause in the code.
This transforms mainframe application penetration testing from a slow, uncertain process into a systematic, comprehensive assessment covering 19 distinct vulnerability classes across COBOL, BMS, copybooks, JCL, DB2, VSAM, CICS, and batch processing.
## Author
Garland Glessner — [gglessner@gmail.com](mailto:gglessner@gmail.com)
## License
GNU General Public License v3.0 — see [LICENSE](LICENSE)
## Features
- **43 MCP tools** covering the complete Endevor REST API v2
- **Full inventory browsing**: Datasources, environments, stages, systems, subsystems, types, elements, members
- **Element lifecycle management**:
- Add, Update, Retrieve, Print, Generate, Move, Delete
- Sign-in / Sign-out for element locking
- Transfer across inventory locations
- Component dependency analysis (ACM)
- **Package workflow management**:
- Create, Update, Cast, Approve, Deny, Execute, Submit
- Commit, Reset, Backout, Backin, Delete
- **Async task management**: List, check status, and retrieve results of long-running operations
- **SCL submission**: Execute arbitrary Software Control Language statements
- **Fingerprint validation**: Optimistic concurrency control
- **Auto-connect via environment variables**: Configure `ENDEVOR_*` env vars in `mcp.json` — the server connects with Basic Auth, obtains a JWT, and is ready immediately (no manual `endevor_connect` needed)
- **Authentication support**:
- Auto-auth via env vars (Basic Auth -> JWT on startup)
- HTTP Basic Auth (username/password)
- Bearer Token (JWT)
- JWT acquisition via Endevor /auth endpoint
- Mutual TLS (mTLS) with client certificates
- **TLS/SSL support**: Custom CA certs, client certs, verification bypass for test environments
- **Security assessment ready**: Purpose-built workflows for mainframe source code review and vulnerability analysis
- **Secret redaction (MCP Armor)**: Every tool response is filtered through the vendored [`mcp_armor`](endevor_mcp/libs/mcp_armor/) library before it reaches the AI model. JCL `PASSWORD=`, RACF/ACF2/TSS password operands, IDCAMS VSAM passwords, DB2 `CONNECT … USING`, FTP-script credentials, and the standard cloud/API-key set are replaced with `[REDACTED]`. Unredacted hits are logged to `endevor_mcp/logs/endevor_mcp_armor_<timestamp>.log` for tester review. Patterns are configurable in `endevor_mcp/libs/mcp_armor/patterns.yaml`.
## Quick Start
### 1. Clone and install
```shell
git clone https://github.com/gglessner/Endevor-MCP.git
cd Endevor-MCP
pip install -r requirements.txt
```
### 2. Open in Cursor
Open the `Endevor-MCP` directory as your project in Cursor. Everything is pre-configured:
- `.cursor/mcp.json` — auto-registers the MCP server (43 tools)
- `.cursor/skills/endevor-mcp/SKILL.md` — teaches the AI assistant all tools and workflows
No manual setup needed. See [MCP_SETUP.md](MCP_SETUP.md) for VS Code and advanced configurations.
### 3. Configure credentials
Edit `.cursor/mcp.json` with your Endevor instance details:
```json
{
"mcpServers": {
"endevor-mcp": {
"command": "python",
"args": ["run_endevor_mcp.py"],
"cwd": "${workspaceFolder}",
"env": {
"ENDEVOR_HOST": "mainframe.example.com",
"ENDEVOR_PORT": "443",
"ENDEVOR_DATASOURCE": "ENDVCONF",
"ENDEVOR_USERNAME": "USER01",
"ENDEVOR_PASSWORD": "secret"
}
}
}
}
```
The server auto-connects with Basic Auth, obtains a JWT bearer token, and all 43 tools are immediately ready using `conn_id="auto"`.
**Manual connect** (alternative — if env vars are not configured):
```
endevor_connect(host="mainframe.example.com", port=443,
datasource="ENDVCONF",
username="USER01", password="secret")
```
## Tool Reference (43 tools)
### Connection Management (3 tools)
| Tool | Description |
|------|-------------|
| `endevor_connect` | Connect to Endevor REST API with full auth support |
| `endevor_disconnect` | Close a connection |
| `endevor_connections` | List all active connections |
### Authentication & Health (3 tools)
| Tool | Description |
|------|-------------|
| `endevor_authenticate` | Get JWT token from /auth endpoint |
| `endevor_healthcheck` | Run datasource health check |
| `endevor_get_report` | Get report from a previous request |
### Async Task Management (3 tools)
| Tool | Description |
|------|-------------|
| `endevor_list_tasks` | List async tasks (in-progress/finished) |
| `endevor_get_task_status` | Get status of an async task |
| `endevor_get_task_result` | Get result of a finished async task |
### Inventory / List Tools (8 tools)
| Tool | Description |
|------|-------------|
| `endevor_list_datasources` | List all datasource configurations |
| `endevor_list_environments` | List environments |
| `endevor_list_stages` | List stage numbers |
| `endevor_list_systems` | List systems |
| `endevor_list_subsystems` | List subsystems |
| `endevor_list_types` | List element types |
| `endevor_list_elements` | List elements with wildcard and CCID filtering |
| `endevor_list_members` | List members for an element type |
### Element Actions (11 tools)
| Tool | Description |
|------|-------------|
| `endevor_add_element` | Add (create) a new element |
| `endevor_update_element` | Update existing element source with sync support |
| `endevor_retrieve_element` | Retrieve (download) element source content |
| `endevor_print_element` | Print element info (browse/changes/history/summary/master/listing) |
| `endevor_print_element_components` | Print element component info (requires ACM) |
| `endevor_generate_element` | Generate (compile/process) an element |
| `endevor_move_element` | Move element up the map |
| `endevor_delete_element` | Delete an element |
| `endevor_signin_element` | Sign in (release lock on) an element |
| `endevor_signout_element` | Sign out (lock) an element |
| `endevor_transfer_element` | Transfer element to a different inventory location |
### Package Actions (13 tools)
| Tool | Description |
|------|-------------|
| `endevor_list_packages` | List packages with status/type/detail filtering |
| `endevor_create_package` | Create a new package with SCL |
| `endevor_update_package` | Update an existing package |
| `endevor_cast_package` | Cast (freeze) a package for review |
| `endevor_approve_package` | Approve a package |
| `endevor_deny_package` | Deny a package |
| `endevor_execute_package` | Execute a package |
| `endevor_submit_package` | Submit a package for batch execution |
| `endevor_commit_package` | Commit an executed package |
| `endevor_reset_package` | Reset a package to INEDIT status |
| `endevor_backout_package` | Back out an executed package |
| `endevor_backin_package` | Reverse a backout |
| `endevor_delete_package` | Delete a package |
### SCL & Fingerprint (2 tools)
| Tool | Description |
|------|-------------|
| `endevor_submit_scl` | Submit SCL statements for execution |
| `endevor_validate_fingerprint` | Validate element fingerprints for concurrency |
## Endevor Inventory Hierarchy
```
Datasource (configuration — points to an Endevor instance)
└── Environment (DEV, QA, PROD, ...)
└── Stage Number (1, 2, ...)
└── System (FINANCE, HR, PAYMENTS, ...)
├── Subsystem (ACCTS, PAYROLL, CLAIMS, ...)
│ └── Element (PAYCALC, EMPRPT, CUSTMNT, ...)
└── Type (COBOL, COPYBOOK, JCL, ASMPGM, PLI, BMS, ...)
```
## Common Element Types
| Type | Description | Security Relevance |
|------|-------------|-------------------|
| `COBOL` | COBOL source programs | Application logic, SQL queries, CICS calls, auth checks |
| `COPYBOOK` / `COPY` | COBOL copybooks (included headers) | Data structures, record layouts, field definitions |
| `JCL` | Job Control Language | Batch jobs, STEPLIB/PROCLIB, dataset references |
| `ASMPGM` / `ASM` | Assembler programs | Low-level system calls, SVC routines, authorized programs |
| `PLI` / `PL1` | PL/I programs | Application logic (less common than COBOL) |
| `BMS` | BMS mapsets (screen definitions) | TN3270 screen layouts, hidden fields, field attributes |
| `CLIST` / `REXX` | TSO command procedures | Automation scripts, may contain credentials |
| `PROC` | JCL procedures | Reusable JCL, compile/link steps |
| `LMOD` / `LOAD` | Load modules (compiled output) | Executable binaries |
| `DBRM` | DB2 Database Request Modules | SQL access paths, DB2 plan bindings |
Type names vary by installation. Use `endevor_list_types` to discover what's configured.
## Architecture
```
Endevor-MCP/
├── .cursor/
│ ├── mcp.json # Auto-registers MCP server with env var auth
│ └── skills/
│ └── endevor-mcp/
│ ├── SKILL.md # Core skill — 43 tools, auth, workflows
│ ├── mainframe-security.md # 19 vulnerability classes with COBOL patterns
│ └── security-checklist.md # Review checklist + hack3270 cross-reference
├── endevor_mcp/
│ ├── __init__.py # Package metadata
│ ├── client.py # HTTP REST client & connection manager
│ ├── server.py # FastMCP server with 43 tools + auto-connect
│ └── libs/mcp_armor/ # Vendored secret-redaction library (patterns.yaml)
├── run_endevor_mcp.py # Entry point
├── requirements.txt # Dependencies
├── MCP_SETUP.md # Setup guide for Cursor & VS Code
├── README.md # This file
└── LICENSE # GPL v3
```
### HTTP REST Client (client.py)
Thread-safe persistent HTTP session management:
- `requests`-based HTTP client with connection pooling
- Basic Auth and Bearer Token authentication
- Full TLS configuration (custom CA, mTLS, verification bypass)
- Automatic datasource path prefixing
- JWT token acquisition via Endevor /auth endpoint
### MCP Server (server.py)
FastMCP server with 43 registered tools organized by category:
- Connection management and authentication
- Async task management for long-running operations
- Inventory browsing with wildcard support
- Element lifecycle operations (multipart/form-data for content upload)
- Package workflow management (JSON body)
- SCL submission and fingerprint validation
- Intelligent response parsing with structured output
### Secret Redaction (libs/mcp_armor)
`server.py` wraps `mcp.tool` so that every tool's return value (and any
exception message) passes through `mcp_armor.ContentFilter` before leaving the
server. The filter is regex-driven from
`endevor_mcp/libs/mcp_armor/patterns.yaml`, which ships with both the upstream
cloud/API-key patterns and a **z/OS-specific block** covering JCL, RACF, ACF2,
Top Secret, IDCAMS, DB2, FTP, MQ, and COBOL `MOVE … TO …-PASSWORD` literals.
If `libs/mcp_armor/` is removed, the server runs unfiltered — the wrap is
best-effort and degrades gracefully.
## Authentication Quick Reference
| Method | Parameters |
|--------|-----------|
| Basic Auth | `username`, `password` |
| Bearer Token | `bearer_token` |
| JWT via API | Connect with Basic Auth, then `endevor_authenticate` |
| mTLS | `ssl_certfile`, `ssl_keyfile` |
| No verify | `ssl_no_verify=True` |
| Custom CA | `ssl_cafile` |
## Package Lifecycle
```
INEDIT → (cast) → INAPPROVAL → (approve) → APPROVED → (execute) → EXECUTED → (commit) → COMMITTED
↓ ↓ ↓
(deny) (reset) (backout)
↓ ↓ ↓
DENIED INEDIT EXECUTED
(backin)
```
## Security Assessment Details
### 19 Vulnerability Classes
The skill documentation covers 19 vulnerability classes applicable to the full field of mainframe application security (see [mainframe-security.md](.cursor/skills/endevor-mcp/mainframe-security.md) for complete details with COBOL source code patterns):
| # | Vulnerability Class | Source Type |
|---|-------------------|------------|
| 1 | Reconnaissance / application mapping | All |
| 2 | BMS map analysis (hidden/protected fields) | BMS |
| 3 | Missing input validation | COBOL |
| 4 | SQL injection (COBOL-DB2) | COBOL |
| 5 | Hardcoded credentials | COBOL, JCL, REXX |
| 6 | Missing authorization (RACF bypass) | COBOL |
| 7 | COMMAREA / channel data leakage | COBOL |
| 8 | Temporary storage queue exposure | COBOL |
| 9 | Pseudo-conversational state tampering | COBOL |
| 10 | Transaction routing / application escape | COBOL |
| 11 | Hidden AID key functionality | COBOL |
| 12 | Numeric data exceptions (SOC7/S0C7) | COBOL, Copybook |
| 13 | VSAM file access (IDOR) | COBOL |
| 14 | CICS ASSIGN information disclosure | COBOL |
| 15 | Error handling information disclosure | COBOL |
| 16 | REDEFINES type confusion | Copybook |
| 17 | Batch JCL security | JCL |
| 18 | Program flow / authorization bypass | COBOL |
| 19 | Change intelligence (prioritized testing) | All |
Plus a comprehensive 10-category source code review checklist and a 21-row hack3270 + Endevor-MCP cross-reference table in [security-checklist.md](.cursor/skills/endevor-mcp/security-checklist.md).
## Parameter Reference
### Common Parameters
| Parameter | Description |
|-----------|-------------|
| `conn_id` | Connection ID from `endevor_connect` |
| `environment` | Endevor environment name (DEV, QA, PROD) |
| `stage` | Stage number (1, 2) |
| `system` | System name (application group) |
| `subsystem` | Subsystem name (application subdivision) |
| `type_name` | Element type (COBOL, COPYBOOK, JCL, etc.) |
| `element` | Element name (program name) |
### Change Control Parameters
| Parameter | Description |
|-----------|-------------|
| `ccid` | Change Control ID (1-12 chars) |
| `comment` | Comment text (1-40 chars) |
| `override_signout` | Override another user's signout (yes/no) |
| `fingerprint` | 16-digit hex for optimistic concurrency |
### Search & Filter Parameters
| Parameter | Description |
|-----------|-------------|
| `search` | Search up the Endevor map (yes/no) |
| `path` | Mapping path: LOG (logical) or PHY (physical) |
| `return_opt` | Return option: FIR (first found) or ALL |
| `where_ccid_current` | Filter by CCID in Master Control File |
| `where_ccid_all` | Filter by CCID in MCF and deltas |
| `where_ccid_retrieve` | Filter by retrieve CCID |
| `where_proc_group` | Filter by processor group |
| `limit` | Max results (0 = no limit) |
### Print Options
| Value | Description |
|-------|-------------|
| `browse` | Current source with level annotations (default) |
| `changes` | Inserts/deletes at a specific level |
| `history` | All lines ever in the source across all levels |
| `summary` | One-line summary per level |
| `master` | Master Control File data |
| `listing` | Output listing from last generate |
### Package Statuses
| Status | Description |
|--------|-------------|
| `INEDIT` | Being edited, SCL modifiable |
| `INAPPROVAL` | Cast, awaiting approval |
| `APPROVED` | Ready for execution |
| `INEXECUTION` | Currently executing |
| `EXECUTED` | Successfully executed |
| `EXECFAILED` | Execution failed |
| `COMMITTED` | Committed, no backout possible |
| `DENIED` | Approval denied |
## SCL Quick Reference
SCL (Software Control Language) is Endevor's native scripting language, submitted via `endevor_submit_scl`:
```
LIST ELEMENT '*'
FROM ENVIRONMENT 'DEV' SYSTEM 'FINANCE' SUBSYSTEM '*'
TYPE 'COBOL' STAGE NUMBER 1
OPTIONS SEARCH .
RETRIEVE ELEMENT 'PAYCALC'
FROM ENVIRONMENT 'DEV' SYSTEM 'FINANCE' SUBSYSTEM 'ACCTS'
TYPE 'COBOL' STAGE NUMBER 1
TO DSN 'USER01.REVIEW.COBOL' MEMBER 'PAYCALC'
OPTIONS CCID 'REVIEW01' COMMENT 'Security review' .
MOVE ELEMENT 'PAYCALC'
FROM ENVIRONMENT 'DEV' SYSTEM 'FINANCE' SUBSYSTEM 'ACCTS'
TYPE 'COBOL' STAGE NUMBER 1
OPTIONS CCID 'REL21' COMMENT 'Release 2.1' .
```
## Requirements
- Python 3.9+
- `mcp[cli]` >= 1.0.0 (MCP framework)
- `requests` >= 2.31.0 (HTTP client)
- `urllib3` >= 2.0.0
## Target API
- Endevor REST API v2 (version 2.26)
- Compatible with Endevor 18.0, 18.1, and 19.0
