npm package: @modular-intelligence/linpeas-winpeas
Description: MCP server wrapping LinPEAS and WinPEAS for privilege escalation enumeration
Latest version: 1.0.2

# LinPEAS/WinPEAS MCP Server

MCP server that wraps [LinPEAS](https://github.com/carlospolop/PEASS-ng/tree/master/linPEAS) and [WinPEAS](https://github.com/carlospolop/PEASS-ng/tree/master/winPEAS) for privilege escalation enumeration through the Model Context Protocol.

## Overview

This MCP server provides safe, controlled access to LinPEAS and WinPEAS privilege escalation enumeration tools. It enables automated security assessments while enforcing authorization controls and providing structured output for analysis.

## Features

- **Full System Scans**: Complete privilege escalation enumeration with LinPEAS/WinPEAS
- **Targeted Section Scans**: Run specific enumeration modules for focused analysis
- **SUID Audit**: Comprehensive SUID binary audit with GTFOBins cross-reference
- **Privilege Escalation Checklists**: Reference checklists for Linux and Windows
- **Authorization Controls**: Mandatory authorization confirmation for all scans
- **Structured Output**: JSON-formatted results for easy parsing and analysis
- **Timeout Protection**: Configurable timeouts prevent runaway scans
- **Sensitive Data Warnings**: Clear warnings on all output containing sensitive information

## Prerequisites

### Required Tools

1. **LinPEAS** (for Linux scans)
   - Download: https://github.com/carlospolop/PEASS-ng/releases/latest/download/linpeas.sh
   - Make executable: `chmod +x linpeas.sh`

2. **WinPEAS** (for Windows scans)
   - Download: https://github.com/carlospolop/PEASS-ng/releases/latest/download/winPEASany.exe
   - Or use winPEASx64.exe / winPEASx86.exe for specific architectures

### Environment Variables

Configure paths to the scripts (optional):

```bash
export LINPEAS_PATH="/path/to/linpeas.sh"
export WINPEAS_PATH="/path/to/winPEASany.exe"
```

If not set, the server will look for `linpeas.sh` and `winPEASany.exe` in the PATH.

## Installation

```bash
cd linpeas-winpeas
bun install
bun run build
```

## Usage

### Starting the Server

```bash
bun run start
```

Or use the built version:

```bash
node dist/index.js
```

### MCP Configuration

Add to your MCP settings file (e.g., Claude Desktop config):

```json
{
  "mcpServers": {
    "linpeas-winpeas": {
      "command": "node",
      "args": ["/absolute/path/to/linpeas-winpeas/dist/index.js"],
      "env": {
        "LINPEAS_PATH": "/path/to/linpeas.sh",
        "WINPEAS_PATH": "/path/to/winPEASany.exe"
      }
    }
  }
}
```

## Available Tools

### 1. linpeas_scan

Run a full LinPEAS privilege escalation enumeration scan on a Linux system.

**Parameters:**
- `authorized` (boolean, required): Confirm authorization to run enumeration
- `intensity` (enum, optional): Scan intensity - "quiet", "normal" (default), or "full"
- `timeout` (number, optional): Maximum scan duration in seconds (default: 300, min: 30, max: 600)

**Output:**
- System information summary
- Network configuration
- User information
- SUID binaries (up to 50)
- Capabilities (up to 50)
- Writable paths (up to 50)
- Interesting files (up to 50)
- Potential vulnerabilities with severity levels
- Executive summary

**Example:**
```json
{
  "authorized": true,
  "intensity": "normal",
  "timeout": 300
}
```

### 2. linpeas_section

Run a specific LinPEAS section scan for focused enumeration.

**Parameters:**
- `authorized` (boolean, required): Confirm authorization to run enumeration
- `section` (enum, required): Section to scan
  - `system_information`
  - `container`
  - `network_information`
  - `users_information`
  - `software_information`
  - `interesting_files`
  - `api_keys_regex`
  - `processes_cron_timers_services`
  - `suid`
  - `capabilities`
  - `writable_files`
  - `passwords`
- `timeout` (number, optional): Maximum scan duration in seconds (default: 300)

**Output:**
- Section name
- Findings with severity levels (up to 100)

**Example:**
```json
{
  "authorized": true,
  "section": "suid",
  "timeout": 180
}
```

### 3. winpeas_scan

Run a full WinPEAS privilege escalation enumeration scan on a Windows system.

**Parameters:**
- `authorized` (boolean, required): Confirm authorization to run enumeration
- `intensity` (enum, optional): Scan intensity - "quiet", "normal" (default), or "full"
- `timeout` (number, optional): Maximum scan duration in seconds (default: 300)

**Output:**
- System information summary
- User information
- Services (up to 50)
- Scheduled tasks (up to 50)
- Interesting files (up to 50)
- Credentials (up to 20)
- Potential vulnerabilities with severity levels
- Executive summary

**Example:**
```json
{
  "authorized": true,
  "intensity": "full",
  "timeout": 400
}
```

### 4. winpeas_section

Run a specific WinPEAS section scan for focused enumeration.

**Parameters:**
- `authorized` (boolean, required): Confirm authorization to run enumeration
- `section` (enum, required): Section to scan
  - `system_information`
  - `logged_users`
  - `network`
  - `process_information`
  - `services`
  - `applications`
  - `interesting_files`
  - `credentials`
  - `browser_info`
- `timeout` (number, optional): Maximum scan duration in seconds (default: 300)

**Output:**
- Section name
- Findings with severity levels (up to 100)

**Example:**
```json
{
  "authorized": true,
  "section": "services",
  "timeout": 200
}
```

### 5. privesc_checklist

Get a comprehensive privilege escalation enumeration checklist (reference only, no execution).

**Parameters:**
- `os` (enum, required): Target operating system - "linux" or "windows"
- `authorized` (boolean, required): Confirm authorization

**Output:**
- Operating system
- Categories of checks (e.g., System Information, Users, SUID, Services, etc.)
- For each check:
  - Unique ID
  - Description
  - Command to run
  - Risk level
  - References and resources

**Example:**
```json
{
  "os": "linux",
  "authorized": true
}
```

### 6. suid_audit

Perform comprehensive SUID binary audit with GTFOBins cross-reference.

**Parameters:**
- `authorized` (boolean, required): Confirm authorization to run enumeration
- `timeout` (number, optional): Maximum scan duration in seconds (default: 300)

**Output:**
- List of all SUID binaries with:
  - Full path
  - Owner
  - Permissions
  - GTFOBins exploitation status
  - Detailed exploitation method (if exploitable)
- Total count
- Exploitable count

**Example:**
```json
{
  "authorized": true,
  "timeout": 240
}
```

## Security Considerations

### Authorization Required

All tools require explicit authorization confirmation. This is a security control to prevent unauthorized scanning. You must set `authorized: true` in every request.

### Local Execution Only

This server executes LinPEAS and WinPEAS locally on the host system. It is designed for:
- Authorized penetration testing
- Security assessments
- Red team exercises
- Vulnerability research
- CTF competitions

**Never run these tools on systems you do not own or have explicit permission to test.**

### Sensitive Output Warnings

All scan results include the warning:

```
⚠️ SENSITIVE OUTPUT: This scan reveals system configuration details, potential
vulnerabilities, and credential locations. Handle with care and restrict access
to authorized personnel only.
```

Treat all output as confidential and sensitive.

### Read-Only Enumeration

LinPEAS and WinPEAS are enumeration tools only. They:
- **DO**: Read system information, file permissions, configurations
- **DO NOT**: Modify system files, exploit vulnerabilities, escalate privileges

However, the act of enumeration itself may be logged and detected by security monitoring systems.

### Timeout Protection

All scans have configurable timeouts (30-600 seconds) to prevent resource exhaustion. Long-running scans will be terminated automatically.

## GTFOBins Database

The SUID audit tool includes a comprehensive GTFOBins database covering 100+ exploitable binaries including:

- **Shells**: bash, sh, zsh, csh, ksh, dash, etc.
- **Interpreters**: python, perl, ruby, php, node, lua, etc.
- **Editors**: vim, vi, nano, emacs, ed, etc.
- **File Operations**: cp, mv, dd, tar, rsync, wget, curl, etc.
- **System Tools**: find, docker, systemctl, mount, etc.

Each entry includes specific exploitation commands and techniques.

## Architecture

```
linpeas-winpeas/
├── src/
│   ├── index.ts              # MCP server main entry point
│   ├── cli-executor.ts       # Command execution wrapper
│   ├── security.ts           # Authorization and validation
│   ├── schemas.ts            # Zod schemas for all inputs
│   └── tools/
│       ├── linpeas-scan.ts      # Full LinPEAS scan
│       ├── linpeas-section.ts   # Targeted LinPEAS section
│       ├── winpeas-scan.ts      # Full WinPEAS scan
│       ├── winpeas-section.ts   # Targeted WinPEAS section
│       ├── privesc-checklist.ts # Reference checklists
│       └── suid-audit.ts        # SUID binary audit
├── package.json
├── tsconfig.json
└── README.md
```

## Error Handling

The server provides detailed error messages for:
- Missing authorization
- Invalid parameters
- Script execution failures
- Timeout conditions
- Invalid sections
- Missing scripts

All errors are returned in structured JSON format.

## Performance

- **Scan Duration**: Typically 30-300 seconds depending on system size and intensity
- **Output Size**: Up to 50MB (configurable buffer)
- **Memory Usage**: Minimal, streaming output processing
- **Timeout Protection**: Automatic termination after configured duration

## Troubleshooting

### Script Not Found

```
Error: LinPEAS execution failed: ENOENT
```

**Solution**: Set `LINPEAS_PATH` or ensure `linpeas.sh` is in PATH and executable.

### Permission Denied

```
Error: LinPEAS execution failed: EACCES
```

**Solution**: Make the script executable with `chmod +x linpeas.sh`.

### Timeout Errors

```
Error: Script timed out after 300 seconds
```

**Solution**: Increase the timeout parameter or use section scans instead of full scans.

### Authorization Errors

```
Error: Authorization required: You must explicitly confirm authorization...
```

**Solution**: Set `authorized: true` in your request.

## Best Practices

1. **Start with Checklists**: Use `privesc_checklist` to understand what to look for
2. **Use Section Scans**: Run targeted sections instead of full scans when possible
3. **Review SUID First**: `suid_audit` is fast and often reveals quick wins
4. **Increase Timeout for Full Scans**: Full scans may need 400-600 seconds on large systems
5. **Parse Results Programmatically**: All output is JSON for easy automation
6. **Verify Findings Manually**: Automated scans may have false positives
7. **Document Findings**: Keep records of discovered vulnerabilities
8. **Secure Output**: Treat all scan results as confidential

## References

- **PEASS-ng Project**: https://github.com/carlospolop/PEASS-ng
- **GTFOBins**: https://gtfobins.github.io/
- **HackTricks**: https://book.hacktricks.xyz/
- **MCP Documentation**: https://modelcontextprotocol.io/

## License

This MCP server wrapper is provided for authorized security testing only. LinPEAS and WinPEAS are part of the PEASS-ng project and have their own licenses.

## Disclaimer

This tool is provided for educational and authorized security testing purposes only. Unauthorized access to computer systems is illegal. Always obtain proper authorization before conducting security assessments.