Progpilot Documentation

Progpilot currently supports analysis for the following frameworks:

• suiteCRM
• codeIgniter

Progpilot tracks states through chained method calls by following the return values of functions. Each function call in a chain can introduce a new instance with its own definition block and state, which then flows into the next call in the chain.

$instance1 = new Object1;

// Progpilot tracks the flow through the chain:
// instance1 -> func1() (returns instance2) -> func2() (returns instance3) -> func3()
$instance1->func1()->func2()->func3();

To programmatically differentiate between the types of vulnerabilities found by Progpilot, check the vuln_type field in the output object. It will contain one of two values:

1. taint-style: Indicates a data-flow vulnerability (source to sink).
2. custom: Indicates a violation of a specific rule defined in rules.json.

When dealing with object instances and their properties, Progpilot tracks states for the properties themselves rather than just the instance variable.

When a property is assigned a value in different execution paths, Progpilot launches a dataflow analysis for those properties. The state at a subsequent block is calculated as the merge of the states from the preceding branches. For example, if a property is tainted in one branch and set to a string in another, the resulting state at the merge point reflects the combination of those states.

$instance = new Object;

if(rand()) {
    // block 2: instance->prop is tainted
    $instance->prop = $_GET["p"]; 
}
else {
    // block 3: instance->prop is "null"
    $instance->prop = "null";
}

// block 4: state of instance->prop is merge(state 2, state 3)
echo $instance->prop;

The instanceof property allows you to target specific object types or method chains.

1. Direct Class Name: Use the exact class name if known. {"name": "prepare", "instanceof": "mysql_connect", ...}

2. Property Path: If the exact class is unknown, use the property name within an object. {"name": "isValidNumber", "instanceof": "ESAPI->validator", ...}

3. Object Heritage: instanceof respects inheritance. If you define a parent class as an instance of a sink, all child classes will also be treated as sinks for that method.

4. Undefined Classes: It works even if the class is not explicitly defined in the analysis scope (e.g., using a placeholder like VulnerableClass).

// Example of targeting a method on a specific class hierarchy
{"name": "query", "instanceof": "SomeClass1", "language": "php"}

Progpilot uses a state-based model to track dataflow, specifically focusing on attributes like isTainted. Each definition (variable or object) maintains multiple states corresponding to different execution blocks.

For simple variables, Progpilot uses a defaultState for the variable and tracks how its state changes across different code blocks (e.g., inside if/else branches). The visitorDataFlow mechanism is responsible for performing the actual dataflow analysis by merging these states at join points (like the end of an if/else block).

// Example of state tracking for simple variables
$foo = $_GET["p"]; // block 1: foo state is tainted

if(rand()) {
    // block 2: bar state is tainted (inherits from foo)
    $bar = $foo;
}
else {
    // block 3: bar state is empty
    $bar = null;
}

// block 4: bar state is the merge of block 2 and block 3
echo $bar;

Because the container is isolated, it cannot see your local filesystem unless you explicitly mount it.

• Mounting: Use -v $(pwd):/workspace to map your current directory to /workspace inside the container.
• Pathing: All arguments passed to the docker run command are forwarded to the progpilot command. Therefore, you must use the container-internal paths (e.g., /workspace/...) for all target files, directories, and configuration files.
• Runtime: The container uses PHP 8.1 (compatible with project requirements of >=8.3).

To use Progpilot in a container, you must mount your local files into the container using a volume so the tool can access your PHP code. The recommended pattern is to mount your current working directory to /workspace inside the container.

Important: When specifying files or directories to analyze, you must use the absolute path as it exists inside the container (e.g., starting with /workspace/).

# Analyze a single PHP file
docker run -v $(pwd):/workspace progpilot /workspace/path/to/your/file.php

# Analyze multiple files
docker run -v $(pwd):/workspace progpilot /workspace/file1.php /workspace/file2.php /workspace/file3.php

# Analyze a directory
docker run -v $(pwd):/workspace progpilot /workspace/path/to/your/php/project/

# Use with a configuration file
docker run -v $(pwd):/workspace progpilot /workspace/file.php --configuration /workspace/config.yml

To build a local Docker image named progpilot from the source code, run the following command in the repository root. This process builds the Progpilot PHAR file inside the container.

docker build -t progpilot .