pydecipher

https://pydecipher.readthedocs.io/en/latest/
Admin
A Python package to unpack, unfreeze, and deobfuscate frozen Python artifacts to recover the...
Tokens:12,443
Snippets:227
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Simple Use-Case Example

Source: https://pydecipher.readthedocs.io/en/latest/user_guide.html

A straightforward example of using pydecipher on an executable file.

```bash
$ pydecipher evil.exe

```

--------------------------------

### Advanced Use-Case Example

Source: https://pydecipher.readthedocs.io/en/latest/user_guide.html

An example demonstrating the --decompile-all and --output flags for processing a zip archive.

```bash
$ pydecipher --decompile-all --output ~/Desktop sample.zip

```

--------------------------------

### Install pre-commit

Source: https://pydecipher.readthedocs.io/en/latest/developers/dev_guide.html

Command to install the pre-commit hook for code formatting and style checks.

```bash
pre-commit install
```

--------------------------------

### Bump2version dry run example

Source: https://pydecipher.readthedocs.io/en/latest/developers/dev_guide.html

Example of using bump2version with --verbose and --dry-run flags.

```bash
bump2version --verbose --dry-run patch
['patch']
current_version=1.0.0
commit=True
tag=False
files=pydecipher/__init__.py
parse=(?P<major>\d+)\.(?P<minor>\d+)(\.(?P<patch>\d+))?(?P<release>[a-z]+)?
serialize=
{major}.{minor}.{patch}{release}
{major}.{minor}.{patch}
{major}.{minor}
new_version=1.0.1b
```

--------------------------------

### Basic Command Line Usage

Source: https://pydecipher.readthedocs.io/en/latest/user_guide.html

Example of running pydecipher on a Python artifact from the command line.

```bash
$ pydecipher my_artifact.exe

```

--------------------------------

### Bump2version release commands

Source: https://pydecipher.readthedocs.io/en/latest/developers/dev_guide.html

Examples of using bump2version to manage package versions.

```bash
bump2version release                          # 1.0.0b → 1.0.0
bump2version patch                            # 1.0.0 → 1.0.1b
bump2version minor                            # 1.0.1b → 1.1.0b
bump2version patch --new-version 1.1.0rc      # 1.1.0b → 1.1.0rc
bump2version patch --new-version 1.1.0        # 1.1.0rc → 1.1.0
bump2version major                            # 1.1.0 → 2.0.0b
```

--------------------------------

### Check installation

Source: https://pydecipher.readthedocs.io/en/latest/developers/dev_guide.html

Command to verify pydecipher installation and check its version.

```bash
pydecipher -V
pydecipher 1.0.0
```

--------------------------------

### Install package for development

Source: https://pydecipher.readthedocs.io/en/latest/developers/dev_guide.html

Command to install the pydecipher package in editable mode with development dependencies.

```bash
pip install -e .[dev]
```

--------------------------------

### Running pydecipher Docker Container

Source: https://pydecipher.readthedocs.io/en/latest/user_guide.html

Example of executing the pydecipher Docker container, mapping the current directory for output.

```bash
$ docker run -v $(pwd):/root/ pydecipher sample.exe

```

--------------------------------

### Changelog Entry Example

Source: https://pydecipher.readthedocs.io/en/latest/developers/dev_guide.html

Example of a reStructuredText file for towncrier, detailing a new feature for issue #1337.

```rst
Added capability to extract source code from FooBar-frozen Python binaries.

```

--------------------------------

### Running pydecipher from Python Code

Source: https://pydecipher.readthedocs.io/en/latest/user_guide.html

Demonstrates how to import and run the pydecipher main function from within a Python script.

```python
#! /usr/bin/env python3

import pydecipher.main

pydecipher.main.run([
    '--decompile-all',
    '--verbose',
    'example.exe'
])

```

--------------------------------

### Command Line Usage

Source: https://pydecipher.readthedocs.io/en/latest/api/remap.html

Example command to run the remap tool with an opcode file.

```bash
$ remap --opcode-file path/to/opcode.pyc

```

--------------------------------

### Example opcode map dictionary

Source: https://pydecipher.readthedocs.io/en/latest/api/bytecode.html

An example of the dictionary returned by create_opmap_from_file, mapping opcode names to their integer values.

```python
{
    'POP_TOP': 5,
    'ROT_TWO': 4,
    ...
}
```

--------------------------------

### Remapping with a custom megafile

Source: https://pydecipher.readthedocs.io/en/latest/api/remap.html

Example of how to use the remap command with a custom megafile.

```bash
$ remap -m remapped_megafile.pyc standard_megafile.pyc

```

--------------------------------

### Install pydecipher using pip

Source: https://pydecipher.readthedocs.io/en/latest/installing.html

This command installs pydecipher as a user package using pip.

```bash
$ pip install git+https://github.com/mitre/pydecipher.git#egg=pydecipher

```

--------------------------------

### Example Python Code

Source: https://pydecipher.readthedocs.io/en/latest/api/remap.html

This example demonstrates how literals are added to the co_consts attribute in the order they appear in the Code object.

```python
# /usr/bin/env python
def main():
    print("hello")
    print(1)
    print(2)
    print("world")
    return 3

if __name__ == "__main__":
    main()

```

--------------------------------

### Example Python Code

Source: https://pydecipher.readthedocs.io/en/latest/api/remap.html

A simple Python code snippet to demonstrate bytecode differences.

```python
print("Hello, World!")

```

--------------------------------

### Build Docker container

Source: https://pydecipher.readthedocs.io/en/latest/developers/dev_guide.html

Command to build the pydecipher Docker image.

```bash
docker build -t pydecipher .
```

--------------------------------

### Clone the repository

Source: https://pydecipher.readthedocs.io/en/latest/developers/dev_guide.html

Command to clone the pydecipher repository.

```bash
git clone <pydecipher-url>
```

--------------------------------

### Cloning the Repository and Creating a Branch

Source: https://pydecipher.readthedocs.io/en/latest/developers/dev_guide.html

Steps to clone the PyDecipher repository and create a new feature branch for development.

```bash
git clone <pydecipher_repo_url>
cd pydecipher

$ git checkout -b feature/my-new-feature
```

--------------------------------

### Using a predefined megafile for Python 2.7

Source: https://pydecipher.readthedocs.io/en/latest/api/remap.html

Example of how to use the remap command with a predefined megafile for Python 2.7.

```bash
$ remap --version 2.7 -m remapped_megafile.pyc

```

--------------------------------

### Pushing Changes to Fork

Source: https://pydecipher.readthedocs.io/en/latest/developers/dev_guide.html

Command to push your local branch changes to your forked repository.

```bash
git push
```

--------------------------------

### Example co_consts Attribute

Source: https://pydecipher.readthedocs.io/en/latest/api/remap.html

The co_consts attribute for the above code's Code object.

```python
(
    None
    'hello'
    1
    2
    'world'
    3
)

```

--------------------------------

### Rebasing Changes on Development Head

Source: https://pydecipher.readthedocs.io/en/latest/developers/dev_guide.html

Instructions for rebasing your feature branch onto the latest development branch to integrate changes.

```bash
git remote add upstream <pydecipher_repo_url>
git checkout feature/my-new-feature
git pull --rebase upstream develop
```

--------------------------------

### Set local pyenv virtual environment

Source: https://pydecipher.readthedocs.io/en/latest/developers/dev_guide.html

Command to set the local pyenv virtual environment for pydecipher development.

```bash
pyenv local pydecipher
```

--------------------------------

### Running Integration Tests

Source: https://pydecipher.readthedocs.io/en/latest/developers/dev_guide.html

Command to run pytest in the tests/ directory to ensure all integration tests pass before merging new code.

```bash
pytest tests/
```

--------------------------------

### Command Line Usage

Source: https://pydecipher.readthedocs.io/en/latest/index.html

Example of running pydecipher on the command line to unpack a PE file and its contents.

```bash
$ pydecipher example.exe
[*] Unpacking /home/user/example.exe
[+] Dumped this PE's overlay data to pydecipher_output_example/overlay_data
[*] Unpacking /home/user/pydecipher_output_example/overlay_data
[!] Potential entrypoint found at script example_main.py
[*] Unpacking /home/user/pydecipher_output_example/overlay_data_output/PYZ-00.pyz
[+] Successfully extracted 133 files from this ZlibArchive.
[+] Successfully extracted 7 files from this CArchive.
[+] Decompiled 6 .pyc files.

```

--------------------------------

### Output Directory Structure

Source: https://pydecipher.readthedocs.io/en/latest/index.html

Example of the directory structure created by pydecipher after unpacking an artifact.

```bash
$ tree pydecipher_output_example/ -L 2
pydecipher_output_example/
├── log_18_18_33_Dec_04_2019.txt
├── overlay_data
└── overlay_data_output
    ├── PYZ-00.pyz
    ├── pyiboot01_bootstrap.py
    ├── pyiboot01_bootstrap.pyc
    ├── pyimod01_os_path.py
    ├── pyimod01_os_path.pyc
    ├── pyimod02_archive.py
    ├── pyimod02_archive.pyc
    ├── pyimod03_importers.py
    ├── pyimod03_importers.pyc
    ├── pyz-00_output
    ├── struct.py
    ├── struct.pyc
    ├── example_main.py
    └── example_main.pyc
2 directories, 15 files

```

--------------------------------

### Merging Development Head into Changes

Source: https://pydecipher.readthedocs.io/en/latest/developers/dev_guide.html

Alternative method to integrate changes by merging the development branch into your feature branch.

```bash
git remote add upstream <pydecipher_repo_url>
git fetch upstream develop
git checkout feature/my-new-feature
git merge upstream/develop
```

--------------------------------

### Standard Bytecode Instructions

Source: https://pydecipher.readthedocs.io/en/latest/api/remap.html

Bytecode instructions for 'Hello, World!' compiled with a standard Python 2.7 interpreter.

```text
opcode | argument | opname
-------+----------+-------
0x64   |   0000   | LOAD_CONST ('Hello, World!')
0x47   |          | PRINT_ITEM
0x48   |          | PRINT_NEWLINE
0x64   |   0001   | LOAD_CONST (None)
0x53   |          | RETURN_VALUE

```

--------------------------------

### get_logging_options

Source: https://pydecipher.readthedocs.io/en/latest/api/init.html

Retrieves the library-wide logging settings.

```python
pydecipher.__init__.get_logging_options() -> Dict[str, bool | Path]
```

--------------------------------

### set_logging_options

Source: https://pydecipher.readthedocs.io/en/latest/api/init.html

Sets the library-wide logging settings.

```python
pydecipher.__init__.set_logging_options(_** kwargs_)
```

--------------------------------

### Run remap with Standard Bytecode

Source: https://pydecipher.readthedocs.io/en/latest/api/remap.html

Command to run the 'remap' tool using a reference set of standard library bytecode.

```bash
$ remap --standard-bytecode-path ./2.7.15 ./path/to/custom_interpreter/bytecode/

```

--------------------------------

### Modified Bytecode Instructions

Source: https://pydecipher.readthedocs.io/en/latest/api/remap.html

Bytecode instructions for the same 'Hello, World!' statement compiled with a modified Python interpreter.

```text
opcode | argument
-------+---------
0x84   |   0000
0x67   |
0x68   |
0x84   |   0001
0x73   |

```

--------------------------------

### Generate Standard Library Bytecode

Source: https://pydecipher.readthedocs.io/en/latest/api/remap.html

Docker command to generate a reference set of Python standard library .pyc files.

```bash
$ docker run --volume "$(pwd):/bc" pydecipher/sbg 2.7.15

```

--------------------------------

### Run pydecipher

Source: https://pydecipher.readthedocs.io/en/latest/api/main.html

Orchestrates the flow of the pydecipher command, including parsing arguments, checking file readability/writability, unpacking artifacts, and decompiling bytecode.

```python
pydecipher.main.run(_args_in : List[str] | None = None_) → None
    
Orchestrate the flow of the pydecipher command.
This function is the entry-point of the pydecipher command. It calls out to other routines and generally attempts to follow this high-level flow:
>   1. Parse program arguments.
>   2. Check that input files are readable and output locations are writeable, including that the the program is running in a sufficiently new Python environment (3.6+).
>   3. Recursively call unpack on the artifact until all items of interest are extracted.
>   4. Decompile any Python bytecode found through the unpacking process.
> 

Parameters:
    
**args_in** (_List_ _[__str_ _]_) – If this function is being called from other Python code, pydecipher flags and other command-line options can be passed in as a list.
```

--------------------------------

### Parse Arguments

Source: https://pydecipher.readthedocs.io/en/latest/api/main.html

Parses pydecipher's arguments and sets run-time options. Arguments can be passed as a list if calling from code.

```python
pydecipher.main._parse_args(_args : List | None = None_) → Namespace
    
Parse pydecipher’s arguments and accordingly set run-time options.
Usually these arguments will come from the command line, however if pydecipher is being called from code, _args may be passed in as a list. 

Parameters:
    
**args** (_List_ _,__optional_) – A list of arguments/flags. If you are calling pydecipher from code, you need to pass in your command line as a space-delimited list. i.e. for `pydecipher -v example.exe`, args would be [‘-v’, ‘example.exe’]. 

Returns:
    
The populated namespace of options for pydecipher’s runtime. 

Return type:
    
argparse.Namespace
```

--------------------------------

### register decorator

Source: https://pydecipher.readthedocs.io/en/latest/api/init.html

Decorator to register artifact classes for unpacking.

```python
pydecipher.__init__.register(_artifact_class : type_) -> type
```

--------------------------------

### Unpack Artifact

Source: https://pydecipher.readthedocs.io/en/latest/api/main.html

Recursively extracts interesting resources from a Python artifact, cycling through registered ARTIFACT_TYPES. It handles artifact parsing and can specify an output directory.

```python
pydecipher.main.unpack(_python_artifact : PathLike_, _output_dir : str | None = None_, _** kwargs_) → None
    
Recursively extract interesting resources from the Python artifact.
This function will cycle through all the registered ARTIFACT_TYPES. See usages of `pydecipher.__init__.register()` for the creation of this list.
ARTIFACT_TYPES consists of the different ‘unpackable’, registered (via decorator) Python artifact classes in a dictionary of the format <Artifact_Name : Class Instance of Artifact_Name>. A class’s constructor should raise a TypeError if is being instantiated with something that isn’t the correct type (i.e. Py2Exe resource being passed to a PyInstaller archive constructor). 

Parameters:
    
  * **python_artifact** (_pathlib.Path_ _or_ _io.IOBase_ _(__file-like object_ _)_) – The path to the Python artifact
  * **output_dir** (_str_ _,__optional_) – Where to dump the extracted output of artifact parsers. If no directory is specified, a directory will be created in the current working directory.
  * ****kwargs** – 
Arbitrary keyword arguments. Including, but not limited to:
> 

version_hint: str
    
> The (potential) Python version of the artifact. If you know the version, you should pass it in. Otherwise, pydecipher will try to automatically figure out what version was used through string-analysis (and possibly brute-force decompilation). If
```

--------------------------------

### Remap Output JSON Format

Source: https://pydecipher.readthedocs.io/en/latest/api/remap.html

The JSON format of the remapping file produced by the remap tool.

```json
{
    "python_version": "<version_str>",
    "method": "<method_name>",
    "command line": "<command_line>"
    "remapped_opcodes": [
        {
            "opcode": "<original_opcode_value>",
            "opname": "<operation_name>",
            "remapped_value": "<new_opcode_value>",
            "guess": "<bool>"
        },
        ...
    ]
}

```

--------------------------------

### unpack() Method

Source: https://pydecipher.readthedocs.io/en/latest/api/artifact_types/zip.html

The unpack method recursively searches the artifact for frozen Python artifacts.

```python
unpack() -> None
```

--------------------------------

### JSON file format for opmap remapping

Source: https://pydecipher.readthedocs.io/en/latest/api/bytecode.html

The required format for a JSON file used to remap opcodes when creating an opcode map from a file.

```json
{
    "python_version": "<major>.<minor>(.<patch>)",
    "remapped_opcodes": [
        {
            "opcode": 1,
            "opname": "POP_TOP",
            "remapped_value": 5
        },
        {
            "opcode": 2,
            "opname": "ROT_TWO",
            "remapped_value": 4
        },
        ...

```
```

--------------------------------

### Segment of opcode.py from Python 2.7

Source: https://pydecipher.readthedocs.io/en/latest/api/remap.html

A segment of the opcode.py file from Python 2.7, showing def_op calls.

```python
57def_op('STOP_CODE', 0)
58def_op('POP_TOP', 1)
59def_op('ROT_TWO', 2)
60def_op('ROT_THREE', 3)
61def_op('DUP_TOP', 4)
62def_op('ROT_FOUR', 5)

```

--------------------------------

### Unpack Method

Source: https://pydecipher.readthedocs.io/en/latest/api/artifact_types/pyc.html

Validates a compiled Python file and writes a new, corrected file to disk if obfuscations are detected. Does not overwrite the original file.

```python
unpack()
```

--------------------------------

### Is Headerless Static Method

Source: https://pydecipher.readthedocs.io/en/latest/api/artifact_types/pyc.html

A static method to check whether the given bytes match the beginning of a Code object, indicating if a pyc file lacks a proper header.

```python
static _is_headerless(_first_eight_bytes : bytes_)
```

--------------------------------

### Pyc Class Constructor

Source: https://pydecipher.readthedocs.io/en/latest/api/artifact_types/pyc.html

The constructor for the Pyc artifact class, accepting a file path or bytes, an optional output directory, and keyword arguments.

```python
class pydecipher.artifact_types.pyc.Pyc(_file_path_or_bytes : str | Path | BinaryIO_, _output_dir : Path | None = None_, _** kwargs_)
```

--------------------------------

### Check and Fix Pyc Static Method

Source: https://pydecipher.readthedocs.io/en/latest/api/artifact_types/pyc.html

A static method to fix a given pyc file so it can be properly disassembled by xdis. This combats common obfuscations like missing headers, magic bytes, or incorrect version information.

```python
static _check_and_fix_pyc(_pyc_file : Path_, _provided_version : str | None = None_) -> None | NamedTemporaryFile
```

--------------------------------

### Remapped Opcodes

Source: https://pydecipher.readthedocs.io/en/latest/api/remap.html

Comparison of original and remapped opcode values.

```text
opname    | old value | new value
--------------+-----------+----------
LOAD_CONST    |    0x64   |   0x84
PRINT_ITEM    |    0x47   |   0x67
PRINT_NEWLINE |    0x48   |   0x68
RETURN_VALUE  |    0x53   |   0x73

```

--------------------------------

### ZipFile Class Signature

Source: https://pydecipher.readthedocs.io/en/latest/api/artifact_types/zip.html

The signature for the ZipFile class, including its parameters and their types.

```python
class ZipFile(_zip_path_or_bytes : str | Path | BinaryIO_, _output_dir : Path | None = None_, _** kwargs_)
```

--------------------------------

### Validate Pyc File Method

Source: https://pydecipher.readthedocs.io/en/latest/api/artifact_types/pyc.html

Checks if the contents of the class object is a valid zip archive.

```python
validate_pyc_file() -> bool
```

--------------------------------

### Segment of opcode.py's co_consts attribute

Source: https://pydecipher.readthedocs.io/en/latest/api/remap.html

The segment of opcode.py's co_consts attribute that corresponds to the def_op calls.

```python
  ...
  'STOP_CODE'
  0
  'POP_TOP'
  1
  'ROT_TWO'
  2
  'ROT_THREE'
  3
  'DUP_TOP'
  4
  'ROT_FOUR'
  5
  'NOP'
  9
  'UNARY_POSITIVE'
  10
  ...

```

--------------------------------

### validate_zip_archive() Method

Source: https://pydecipher.readthedocs.io/en/latest/api/artifact_types/zip.html

The validate_zip_archive method checks if the contents of the class object is a valid zip archive.

```python
validate_zip_archive() -> bool
```
Tokens:
Raw