A comprehensive educational repository documenting supply chain attack vectors targeting the Python ecosystem. This is a catalog of known attack techniques, defensive strategies, and proof-of-concept code for security research and education.

Author: Satria Ady Pradana
License: MIT (see LICENSE)

This repository is intended for authorized security research, defensive security training, and educational purposes only. All code and techniques are provided for understanding threats to better defend against them. See SECURITY.md for responsible disclosure guidelines and legal compliance information.

• Overview
• Quick Start
• Repository Structure
• Attack Vectors
• Use Cases
• References
• Contributing

Python's rich ecosystem and Package Index (PyPI) make it an attractive target for supply chain attacks. Threat actors commonly abuse Python distribution mechanisms to:

1. Gain Initial Foothold — Deliver malicious code to development environments
2. Establish Persistence — Maintain long-term access through multiple mechanisms
3. Lateral Movement — Compromise downstream dependencies and projects

This repository documents three primary backdoor insertion techniques:

# Browse malicious package techniques
ls -la codes/1.packages/

# Review malicious module examples
ls -la codes/2.modules/

# Study interpreter-level attacks
ls -la codes/3.interpreter/

# Review payload examples
ls -la payloads/

Each example includes:

• README.md — Detailed explanation of the attack vector
• Proof-of-concept Python code
• Build/deployment instructions
• Detection and mitigation guidance

• Python 3.7+
• pip, setuptools, and build tools
• Intended for isolated lab environments only

malpython/
├── README.md                   # This file
├── LICENSE                     # MIT License
├── SECURITY.md                 # Responsible disclosure & legal guidelines
├── CONTRIBUTING.md             # Contribution guidelines
│
├── codes/                      # Attack vector demonstrations
│   ├── 1.packages/             # Supply chain compromise via packages
│   │   ├── malpkg1/            # Malicious module injection
│   │   ├── malpkg2/            # Malicious setup.py execution
│   │   ├── malpkg3/            # Setup.py hook injection
│   │   ├── malpkg4/            # Build backend hooks (PEP 517)
│   │   └── malpkg5/            # Entry point manipulation
│   │
│   ├── 2.modules/              # Runtime code injection via modules
│   │   ├── malmod1/            # Direct module import hijacking
│   │   ├── malmod2/            # __init__.py manipulation
│   │   ├── malmod3-6/          # Advanced module persistence
│   │
│   └── 3.interpreter/          # Python interpreter compromise
│       ├── malinterp1/         # Custom interpreter compilation
│       ├── malinterp2/         # Bytecode injection
│       └── malinterp3/         # Extension module backdoors
│
├── payloads/                   # Real-world payload examples
│   └── cython/                 # Compiled extension examples
│       └── steal-aws-credentials/  # AWS credential harvesting POC
│
└── slides/                     # Presentation materials

Supply chain attacks via compromised or masqueraded packages on PyPI. Focus on executing code before, during, or after package installation.

Key Techniques:

• Direct Injection — Insert code into legitimate package modules
• Setup Hooks — Execute arbitrary code during installation via setup.py
• Build Backend Hooks — Leverage PEP 517/518 build system integration
• Entry Points — Register CLI commands or plugin entry points

Impact: When a user installs a package, malicious code executes with the user's privileges.

Learn More: codes/1.packages/README.md

Runtime code injection via transitive dependencies and module manipulation. Focus on executing code triggered by specific events or conditions

Key Techniques:

• Dependency Hijacking — Inject code into commonly-imported modules
• init.py Poisoning — Modify initialization files
• Module Shadowing — Create modules with names similar to popular libraries
• Namespace Pollution — Inject into shared package namespaces

Impact: Code executes every time the module is imported, affecting all downstream consumers.

Learn More: codes/2.modules/README.md

System-level compromise via Python interpreter manipulation. Focus on tampering Python interpreter to execute custom flow.

Key Techniques:

• Custom Compiler — Build modified Python interpreter from source
• Bytecode Injection — Inject malicious bytecode into standard library
• Extension Modules — Create backdoored C extensions
• Site-packages Hooks — Modify sitecustomize.py for initialization-time execution

Impact: Affects all Python code executed on the system. Extremely difficult to detect.

Learn More: codes/3.interpreter/README.md

Real-world attack scenarios demonstrating impact.

Examples:

• AWS Credential Theft — Extract and exfiltrate AWS credentials from environment
• Additional payloads showing data exfiltration and persistence mechanisms

Learn More: payloads/README.md

• Threat Intelligence — Understand attack techniques threat actors use
• Red Team Exercises — Authorized penetration testing and security assessments
• Incident Response — Identify signs of supply chain compromise
• Vulnerability Research — Discover new attack vectors and mitigations

• Blue Team Training — Build detection and response capabilities
• Policy Development — Create policies to mitigate supply chain risks
• Supply Chain Audits — Assess organizational Python dependencies
• Security Hardening — Implement controls to detect malicious code

• Academic Research — Study supply chain security in open source ecosystems
• Course Material — Teach Python security and threat modeling
• CTF Challenges — Use code as basis for capture-the-flag exercises
• Security Awareness — Demonstrate real-world risks of open source adoption

• PyCon APAC 2024

We welcome contributions from security researchers, defensive security professionals, and educators. Please see CONTRIBUTING.md for detailed guidelines on:

• Types of contributions welcome
• Code and documentation standards
• Submission process
• Legal and ethical considerations

This research is provided for educational and authorized security research purposes only. Users are responsible for ensuring compliance with all applicable laws and regulations in their jurisdiction. Unauthorized access to computer systems is illegal and unethical.

The authors make no warranty about the accuracy, completeness, or suitability of any code or information. Use at your own risk in authorized lab environments only.

Licensed under the MIT License — see LICENSE for details.

Attribution Required: If you use this work, please provide attribution to Satria Ady Pradana and reference this repository.

Questions or Feedback? Open an issue or review SECURITY.md for responsible disclosure guidelines.