Skip to content

Security: umpolungfish/purl_diver

Security

docs/SECURITY.md

Security Policy for purl_diver

Overview

purl_diver is a security analysis tool for extracting executable code from Portable Executable (PE) files. It is designed for legitimate security research and malware analysis purposes.

Threat Model

Intended Use

  • Security Research: Analyzing legitimate and malicious PE files for research purposes
  • Malware Analysis: Extracting shellcode for deeper inspection in safe environments
  • Incident Response: Analyzing suspect files during security incidents
  • Vulnerability Research: Studying PE file structures and executable code

Assumptions

  • The tool runs in a secure, isolated environment (sandbox/VM)
  • Users are trained security professionals aware of risks
  • Input files are handled with proper security precautions
  • All extracted shellcode is analyzed in contained environments

Potential Threats

  • Code Execution Risk: The tool extracts executable code that could be malicious
  • Environment Escape: Malformed PE files could potentially exploit vulnerabilities in the tool
  • Data Exfiltration: Processed files may contain sensitive data
  • Tool Misuse: The tool could be used for malicious purposes if in wrong hands

Safe Usage Practices

1. Isolated Environment

  • Always run the tool in an isolated environment (dedicated VM or sandbox)
  • Ensure the environment has no access to sensitive data or systems
  • Use network isolation to prevent potential data exfiltration

2. File Handling

  • Never execute extracted shellcode directly
  • Store processed files with appropriate security measures
  • Use proper access controls on input and output files
  • Consider hashing input files for tracking purposes

3. Input Validation

  • The tool has built-in validation, but verify inputs when possible
  • Process files one at a time to better track results
  • Validate the authenticity of PE files when possible

4. Output Management

  • Treat all extracted shellcode as potentially malicious
  • Implement proper access controls on output files
  • Securely delete temporary files after processing
  • Use antivirus tools on extracted outputs if appropriate

5. Regular Updates

  • Keep the tool updated with security patches
  • Monitor for security advisories related to PE parsing
  • Review and update security practices regularly

Security Features

Input Validation

  • File size limits (default 500MB) to prevent resource exhaustion
  • PE header validation to prevent malformed file processing
  • Section boundary checks to prevent buffer overflows
  • Integer overflow protection in size calculations

Memory Safety

  • Two-pass algorithm for precise memory allocation
  • Proper bounds checking during file processing
  • Secure memory cleanup after processing

Analysis Features

  • Entropy analysis to identify potentially packed/encrypted sections
  • Import analysis to identify external dependencies
  • Hash calculation for integrity and identification

Known Security Limitations

1. Parser Limitations

  • Complex PE structures with intentional obfuscation may not be fully handled
  • Heavily packed or encrypted files may yield limited useful information
  • Some malware techniques might evade detection

2. Environment Assumptions

  • The tool assumes execution in a secure environment
  • No built-in execution prevention for extracted code
  • Relies on external security controls for safety

There aren't any published security advisories