Skip to main content
The Python tool provides persistent Python interpreter sessions with IPython magic commands, perfect for security script development, data analysis, and HTTP proxy interaction.

​
Key Features

  • Persistent Sessions: Variables and imports persist across executions
  • Multiple Sessions: Run concurrent Python sessions
  • IPython Magic: Full support for magic commands (%pip, %time, %%writefile, etc.)
  • Proxy Integration: All proxy functions pre-imported in every session
  • Security Focus: Ideal for exploit development and pentesting workflows

​
Common Use Cases

  • Security script development and testing (payload generation, exploit scripts)
  • Data analysis of security logs, network traffic, or vulnerability scans
  • Cryptographic operations and security tool automation
  • Interactive penetration testing workflows and proof-of-concept development
  • Processing security data formats (JSON, XML, CSV from security tools)
  • HTTP proxy interaction for web security testing (all proxy functions are pre-imported)

​
Parameters

​
action
string
required
The Python action to perform:
  • new_session: Create a new Python interpreter session (MUST be first action)
  • execute: Execute Python code in the specified session
  • close: Close the specified session instance
  • list_sessions: List all active Python sessions
​
code
string
Required for new_session (as initial code) and execute actions. The Python code to execute.
​
timeout
integer
default:"30"
Maximum execution time in seconds for code execution. Applies to both new_session and execute actions.
​
session_id
string
Unique identifier for the Python session. If not provided, uses the default session ID.

​
Response

​
session_id
string
The ID of the session that was operated on
​
stdout
string
Captured standard output from code execution
​
stderr
string
Any error message if execution failed
​
result
string
String representation of the last expression result
​
execution_time
number
Time taken to execute the code in seconds
​
message
string
Status message about the action performed

​
Examples

​
Basic Session Management

# Create new session for security analysis
python_action(
    action="new_session",
    code="""
import hashlib
import base64
import json
print("Security analysis session started")
"""
)

# Execute code in session
python_action(
    action="execute",
    code="""
import requests
url = "https://example.com"
resp = requests.get(url, timeout=10)
print(resp.status_code)
"""
)

# Variables persist between executions
python_action(
    action="execute",
    code="""
vulnerability_data = {"cve": "CVE-2024-1234", "severity": "high"}
encoded_payload = base64.b64encode(json.dumps(vulnerability_data).encode())
print(f"Encoded: {encoded_payload.decode()}")
"""
)

​
IPython Magic Commands

# Use IPython magic for package management and profiling
python_action(
    action="execute",
    code="""
%pip install requests
%time response = requests.get('https://httpbin.org/json')
%whos
"""
)

# Write file with cell magic
python_action(
    action="execute",
    code="""
%%writefile exploit.py
import requests

def exploit(target):
    payload = "' OR '1'='1"
    return requests.post(target, data={'user': payload})
"""
)

​
HTTP Proxy Integration

# Analyze requests for potential vulnerabilities
# All proxy functions are pre-imported!
python_action(
    action="execute",
    code="""
# Filter for POST requests that might contain sensitive data
post_requests = list_requests(
    httpql_filter="req.method.eq:POST",
    page_size=20
)

# Analyze each POST request for potential issues
for req in post_requests.get('requests', []):
    request_id = req['id']
    # View the request details
    request_details = view_request(request_id, part="request")

    # Check for potential SQL injection points
    body = request_details.get('body', '')
    if any(keyword in body.lower() for keyword in ['select', 'union', 'insert', 'update']):
        print(f"Potential SQL injection in request {request_id}")

        # Repeat the request with a test payload
        test_payload = repeat_request(request_id, {
            'body': body + "' OR '1'='1"
        })
        print(f"Test response status: {test_payload.get('status_code')}")

print("Security analysis complete!")
"""
)

​
Long-Running Security Scans

# Long running security scan with custom timeout
python_action(
    action="execute",
    code="""
import time
# Simulate long-running vulnerability scan
time.sleep(45)
print('Security scan completed!')
""",
    timeout=50
)

​
Multiple Sessions

# Create separate session for exploit development
python_action(
    action="new_session",
    session_id="exploit_dev",
    code="""
import socket
import struct
print("Exploit development session")
"""
)

# Work in exploit session
python_action(
    action="execute",
    session_id="exploit_dev",
    code="""
def create_payload(command):
    # Buffer overflow payload generation
    padding = b"A" * 264
    return padding + struct.pack("<I", 0xdeadbeef)

test_payload = create_payload("whoami")
print(f"Payload size: {len(test_payload)}")
"""
)

# List all active sessions
python_action(action="list_sessions")

# Close session when done
python_action(
    action="close",
    session_id="exploit_dev"
)

​
Pre-Imported Proxy Functions

All proxy action functions are automatically imported into every Python session:
  • list_requests() - List and filter captured HTTP requests
  • view_request() - View request/response details
  • send_request() - Send new HTTP request through proxy
  • repeat_request() - Repeat and modify existing requests
  • scope_rules() - Manage proxy scope patterns
  • list_sitemap() - View discovered endpoints
  • view_sitemap_entry() - Get sitemap entry details
This enables seamless integration between Python analysis and HTTP traffic testing.

​
Important Notes

Multiline Code: Put real line breaks in your code. Do NOT emit literal “\n” sequences — use actual newlines.
Persistence: Session instances remain active and maintain their state (variables, imports, function definitions) until explicitly closed with the ‘close’ action.

​
Code Execution

  • Both expressions and statements are supported
  • Expressions automatically return their result
  • Print statements and stdout are captured
  • Variables persist between executions in the same session
  • Imports and function definitions persist in the session

​
Session Management

  • Session interaction MUST begin with new_session action
  • Only one action can be performed per call
  • Each session has its own isolated namespace
  • Variables in one session don’t affect others
  • Python sessions can operate concurrently with other tools

​
IPython Features

  • Line magics: %pip, %time, %whos, %pwd, etc.
  • Cell magics: %%writefile, %%timeit, %%bash, etc.
  • Shell commands: !ls, !cat file.txt, etc.
  • All standard IPython functionality is available
Use %pip install <package> to install packages during session without leaving Python context.

Build docs developers (and LLMs) love

Get started for freeTalk to us