Endevor

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 (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 — [email protected]

License

GNU General Public License v3.0 — see 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 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

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 for VS Code and advanced configurations.

3. Configure credentials

Edit .cursor/mcp.json with your Endevor instance details:

{
  "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 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.

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