Progpilot

https://github.com/designsecurity/progpilot
Admin
Progpilot is a static application security testing (SAST) tool for PHP that performs taint analysis...
Tokens:147,823
Snippets:958
Trust Score:5.4
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Docker Usage Examples

Source: https://github.com/designsecurity/progpilot/blob/master/DOCKER.md

Practical examples of running progpilot in Docker: analyzing the current directory, using a custom configuration, analyzing specific files, and testing with the example file.

```bash
# Analyze current directory (mount current directory)
docker run -v $(pwd):/workspace progpilot /workspace/

# Analyze with custom configuration
docker run -v $(pwd):/workspace progpilot /workspace/ --configuration /workspace/progpilot.yml

# Analyze specific files in current directory
docker run -v $(pwd):/workspace progpilot /workspace/index.php /workspace/config.php

# Test with the example file
docker run -v $(pwd):/workspace progpilot /workspace/projects/example/source_code1.php
```

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

### Simplified output of the library example

Source: https://github.com/designsecurity/progpilot/blob/master/README.md

The output from the library example shows the detected vulnerability: source name $var4 at line 4, sink echo at line 5, and vulnerability type xss.

```php
array(1) {
  [0]=>
  array(11) {
    ["source_name"]=>
    array(1) {
      [0]=>
      string(5) "$var4"
    }
    ["source_line"]=>
    array(1) {
      [0]=>
      int(4)
    }
    ["sink_name"]=>
    string(4) "echo"
    ["sink_line"]=>
    int(5)
    ["vuln_name"]=>
    string(3) "xss"
  }
}
```

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

### Install PHAR release and make executable

Source: https://github.com/designsecurity/progpilot/blob/master/README.md

Download the latest PHAR archive from the releases page, place it in your path, and make it executable with chmod and mv commands.

```shell
chmod +x progpilot_vX.Y.Z.phar
sudo mv progpilot_vX.Y.Z.phar /usr/local/bin/progpilot
```

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

### CLI usage with and without configuration file

Source: https://github.com/designsecurity/progpilot/blob/master/README.md

Run progpilot from the command line, optionally specifying a configuration file with --configuration. If installed via Composer, the binary is at vendor/bin/progpilot.

```shell
# without config file
progpilot example1.php example2.php folder1/ folder2/
# with a config file
progpilot --configuration configuration.yml example1.php example2.php folder1/ folder2/
```

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

### Example vulnerable PHP code (source_code1.php)

Source: https://github.com/designsecurity/progpilot/blob/master/README.md

This is the content of source_code1.php used in the library example. It contains a tainted variable from $_GET that is echoed, leading to an XSS vulnerability.

```php
<?php
$var7 = $_GET["p"];
$var4 = $var7;
echo "$var4";
```

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

### Library usage to analyze a PHP file

Source: https://github.com/designsecurity/progpilot/blob/master/README.md

Use progpilot inside PHP code by requiring the autoloader, setting the input file, running the analyzer, and retrieving results. The example analyzes source_code1.php and outputs the results with var_dump.

```php
<?php
require_once './vendor/autoload.php';

$context = new \progpilot\Context;
$analyzer = new \progpilot\Analyzer;

$context->inputs->setFile("source_code1.php");

try {
  $analyzer->run($context);
} catch (Exception $e) {
   echo "Exception : ".$e->getMessage()."\n";
}  
  
$results = $context->outputs->getResults();

var_dump($results);
```

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

### Install progpilot with Composer

Source: https://github.com/designsecurity/progpilot/blob/master/README.md

Install the package as a dev dependency, typically when using progpilot as a library in a PHP project.

```shell
composer require --dev designsecurity/progpilot
```

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

### Build and run progpilot Docker container

Source: https://github.com/designsecurity/progpilot/blob/master/README.md

Build the Docker image and run the container, mounting the current directory to /workspace and passing the target PHP file path.

```shell
docker build -t progpilot .
docker run -v $(pwd):/workspace progpilot /workspace/path/to/your/file.php
```

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

### Display vulnerabilities when detected using setOnAddResult

Source: https://github.com/designsecurity/progpilot/blob/master/docs/EXAMPLES.md

Sets a callback via setOnAddResult to display each detected vulnerability. The commented-out line shows an alternative using var_dump directly. Requires the vendor autoload and a target file.

```php
<?php

require_once './vendor/autoload.php';

$context = new \progpilot\Context;
$analyzer = new \progpilot\Analyzer;

$context->inputs->setFile("./tests/oop/simple1.php");
//$context->outputs->setOnAddResult("var_dump");
$var = function($result) {
    var_dump($result);
};
$context->outputs->setOnAddResult($var);
$analyzer->run($context);

```

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

### Build PHAR archive from source code

Source: https://github.com/designsecurity/progpilot/blob/master/README.md

Clone the repository, change into the directory, and run the build script. Requires phar-composer.phar in a directory listed in $PATH. The resulting archive is placed in the builds folder.

```shell
git clone https://github.com/designsecurity/progpilot
cd progpilot
./build.sh
```

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

### Sink Configuration JSON Example

Source: https://github.com/designsecurity/progpilot/blob/master/docs/SPECIFY_ANALYSIS.md

JSON file defining sinks for Progpilot. Mandatory properties are name, language, and attack; optional properties include instanceof, prevent, and parameters. The example lists common PHP sinks with their attack types and CWE identifiers.

```javascript
{
    "sinks": [
        {"name": "echo", "language": "php", "attack": "xss", "cwe": "CWE_79"},
        {"name": "print", "language": "php", "attack": "xss", "cwe": "CWE_79"},
        {"name": "printf", "language": "php", "attack": "xss", "cwe": "CWE_79"},
        {"name": "include", "language": "php", "attack": "file_inclusion", "cwe": "CWE_98"},
        {"name": "eval", "language": "php", "attack": "code_injection", "cwe": "CWE_95"},
        {"name": "system", "language": "php", "attack": "command_injection", "cwe": "CWE_78"},        
        {"name": "ldap_search", "parameters": [{"id": 3}], "language": "php", "attack": "ldap_injection", "cwe": "CWE_90"},
        {"name": "mysql_query", "language": "php", "attack": "sql_injection", "cwe": "CWE_89"},
        {"name": "prepare", "instanceof": "mysql_connect", "language": "php", "attack": "sql_injection", "cwe": "CWE_89"}
        ]
}
```

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

### Sanitizer Configuration JSON Example

Source: https://github.com/designsecurity/progpilot/blob/master/docs/SPECIFY_ANALYSIS.md

JSON file defining sanitizers for Progpilot. Mandatory properties are name and language; optional properties include instanceof, prevent, and parameters. The example shows a filter_var sanitizer with parameter conditions and prevent lists, and an addslashes sanitizer.

```javascript
{
    "sanitizers": [
        {"name": "filter_var",  "language": "php", "parameters": 
            [
                {"id": 2, "conditions": "equals", "values": 
                    [
                        {"value" : "FILTER_SANITIZE_ENCODED", "prevent" : ["xss"]},
                        {"value" : "FILTER_SANITIZE_MAGIC_QUOTES", "prevent" : ["command_injection", "sql_injection"]},
                        {"value" : "FILTER_SANITIZE_SPECIAL_CHARS", "prevent" : ["xss"]},
                        {"value" : "FILTER_SANITIZE_FULL_SPECIAL_CHARS", "prevent" : ["xss"]},
                        {"value" : "FILTER_SANITIZE_STRING", "prevent" : ["xss"]},
                        {"value" : "FILTER_SANITIZE_STRIPPED", "prevent" : ["xss"]}
                    ]}
            ]
        },
        {"name": "addslashes", "language": "php", "prevent": ["sql_injection", "command_injection"]}
        ]
}
```

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

### Example sources JSON file

Source: https://github.com/designsecurity/progpilot/blob/master/docs/SPECIFY_ANALYSIS.md

Defines sources with mandatory name and language properties, plus optional properties like is_array, is_function, and parameters. The 'exec' source specifies a parameter with id 2 and array_index 0.

```json
{
    "sources": [
        {"name": "_GET", "is_array": true, "language": "php"},
        {"name": "_POST", "is_array": true, "language": "php"},
        {"name": "_COOKIE", "is_array": true, "language": "php"},
        {"name": "shell_exec", "is_function": true, "language": "php"},
        {"name": "vardev", "is_array": true, "array_index": "tainted", "language": "php", "type": "for dev purposes"},
        {"name": "exec", "is_function": true, "parameters": [{"id": 2, "is_array": true, "array_index": 0}], "language": "php"}
        ]
}
```

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

### Custom taint analysis configuration (JSON)

Source: https://github.com/designsecurity/progpilot/blob/master/README.md

Define custom sources for the taint analysis. This example marks superglobals _GET, _POST, _COOKIE as untrusted arrays and the return of shell_exec() as untrusted function.

```json
{
    "sources": [
        {"name": "_GET", "is_array": true, "language": "php"},
        {"name": "_POST", "is_array": true, "language": "php"},
        {"name": "_COOKIE", "is_array": true, "language": "php"},
        {"name": "shell_exec", "is_function": true, "language": "php"}
    ]
}
```

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

### Customize analysis with custom rules and data files

Source: https://github.com/designsecurity/progpilot/blob/master/docs/EXAMPLES.md

Configures Progpilot with custom sources, sinks, sanitizers, validators, and rules, then runs the analyzer on a file and dumps results. Requires the vendor autoload and the specified data files in the package/src/uptodate_data folder.

```php
<?php

require_once './vendor/autoload.php';

$file = "example1.php";
$context = new \progpilot\Context;
$analyzer = new \progpilot\Analyzer;

$context->inputs->setSources("../../package/src/uptodate_data/php/sources.json");
$context->inputs->setSinks("../../package/src/uptodate_data/php/sinks.json");
$context->inputs->setSanitizers("../../package/src/uptodate_data/php/sanitizers.json");
$context->inputs->setValidators("../../package/src/uptodate_data/php/validators.json");
$context->inputs->setCustomRules("../../package/src/uptodate_data/php/rules.json");
$context->inputs->setFile($file);

$analyzer->run($context);
$results = $context->outputs->getResults();

var_dump($results);

```

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

### Validators JSON file example

Source: https://github.com/designsecurity/progpilot/blob/master/docs/SPECIFY_ANALYSIS.md

Example JSON file defining validators with name, language, and optional parameters. Each validator specifies conditions for parameter IDs, including predefined filter_var values.

```json
{
    "validators": [
        {"name": "in_array", "language": "php", "parameters": 
            [
                {"id": 1, "conditions": "valid"},
                {"id": 2, "conditions": "array_not_tainted"}
            ]
        },
        {"name": "isValidNumber", "instanceof": "ESAPI->validator", "language": "php", "parameters": 
            [
                {"id": 2, "conditions": "valid"}
            ]
        },
        {"name": "filter_var",  "language": "php", "parameters": 
            [
                {"id": 1, "conditions": "valid"},
                {"id": 2, "conditions": "equals", "values": 
                    [
                        {"value" : "FILTER_VALIDATE_BOOLEAN"},
                        {"value" : "FILTER_VALIDATE_FLOAT"},
                        {"value" : "FILTER_VALIDATE_INT"},
                        {"value" : "FILTER_VALIDATE_IP"},
                        {"value" : "FILTER_VALIDATE_MAC"},
                        {"value" : "FILTER_VALIDATE_URL"}
                    ]}
            ]
        }
        ]
}
```

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

### Static include example

Source: https://github.com/designsecurity/progpilot/blob/master/docs/INCLUDES.md

Progpilot successfully resolves this static include of myfile.php.

```php
include("myfile.php");
```

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

### Dynamic include example that fails

Source: https://github.com/designsecurity/progpilot/blob/master/docs/INCLUDES.md

Progpilot fails to resolve this complex dynamic include because the file path is built at runtime.

```php
$dir = "/files/";
$suf = 2+2;
include($dir."myfile$suf.php");
```

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

### resolved_includes.json example

Source: https://github.com/designsecurity/progpilot/blob/master/docs/INCLUDES.md

Create this file with the correct value for each include function call, then pass it to $context->inputs->setResolvedIncludes("resolved_includes.json") so Progpilot can analyze the resolved file.

```javascript
{
    "includes":
        [
            {
                "line":11,
                "column":11,
                "source_file":"/home/dev/projects/tests/includes/simple5.php",
                "value":"/home/dev/projects/tests/includes/simple5_include.php"
            }
        ]
}
```

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

### in_array validation example

Source: https://github.com/designsecurity/progpilot/blob/master/docs/SPECIFY_ANALYSIS.md

Shows a PHP example where a tainted variable is validated using in_array with a legal table. The first parameter is the variable to validate, the second is an array that must not contain tainted values, making the variable safe inside the if block.

```php
$tainted = $_GET["p"];

$legal_table = array("safe1", "safe2");
if (in_array($tainted, $legal_table, true)) 
{
    echo $tainted;
} 
```

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

### Include failure output example

Source: https://github.com/designsecurity/progpilot/blob/master/docs/INCLUDES.md

When include failure reporting is enabled, each unresolved include is printed in the specified file with its location (file, line, column).

```javascript
{"include_failures":[["/home/dev/projects/tests/includes/simple5.php",11,11]]}
```

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

### instanceof with parent class and inheritance example

Source: https://github.com/designsecurity/progpilot/blob/master/docs/SPECIFY_ANALYSIS.md

Shows that instanceof works with object heritage: defining a sink on a parent class also applies to child classes. The PHP code demonstrates a child class extending the parent and calling the sink method.

```json
{"name": "query", "instanceof": "SomeClass1", "language": "php"}
```

```php
<?php
class SomeClass1
{
}

class SomeClass2 extends SomeClass1
{
    public function query($tata)
    {
    }
}

$a = new SomeClass2;
$a->query($_GET["p"]);
```

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

### Simple variable dataflow with defaultState

Source: https://github.com/designsecurity/progpilot/blob/master/docs/dev/STATES.md

Shows how a simple variable's defaultState is used for dataflow. The variable $foo is tainted from $_GET, and $bar gets tainted or empty depending on the branch. At block 4, the states from both branches are merged for the echo.

```php
// block 1
// foo defined in blockid 1 (defaultState = 1)
// state 1 of foo tainted
$foo = $_GET["p"]; 

if(rand()) {
    // block 2
    // bar defined in blockid 2 (defaultState = 2)
    // state 2 of foo bar (get value of foo->currentState()) tainted
    $bar = $foo;
}
else {
    // block 3
    // bar defined in blockid 3 (defaultState = 3)
    // state 3 of foo bar empty
    $bar = null;
}

// block 4
// bar search def:
//    * block2 $bar->getCurrentState()
//    * block3 $bar->getCurrentState()
// merge states on block 4 of echo_arg0
echo $bar;
```

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

### Call graph checking rule with MUST_VERIFY_CALL_FLOW

Source: https://github.com/designsecurity/progpilot/blob/master/docs/CUSTOM_ANALYSIS.md

Defines a custom rule that traverses the call graph from the main function to verify a sequence of function calls. In this example, it checks that dev_iam_authenticated, dev_iam_rights, and dev_retrieve_secret are called in order before retrieving a secret. The rule is raised if any path does not verify the sequence.

```javascript
{
    "custom_rules": [
        {
            "sequence":
            [
                {"function_name": "dev_iam_authenticated", "language": "php"},
                {"function_name": "dev_iam_rights", "language": "php"},
                {"function_name": "dev_retrieve_secret", "language": "php"}
            ],
            "description": "rule #1 not verified",
            "action": "MUST_VERIFY_CALL_FLOW"
        }]
}
```

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

### Basic Docker Usage

Source: https://github.com/designsecurity/progpilot/blob/master/DOCKER.md

Shows how to run progpilot in Docker to analyze a single file, multiple files, a directory, or with a configuration file. Mounts the current directory to /workspace and uses container paths.

```bash
# 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 configuration file
docker run -v $(pwd):/workspace progpilot /workspace/file.php --configuration /workspace/config.yml
```

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

### Inputs: addSources

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Adds source files to the analysis.

```APIDOC
## [ADD] addSources

### Description
Adds source files to the analysis.

### Method
addSources

### Parameters
- **$files_sources** (array) - Required - List of source files.

### Request Example
```php
$obj_context->inputs->addSources($files_sources);
```

### Response
No return value.
```

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

### Inputs: setSources

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the source files for the analysis.

```APIDOC
## [SET] setSources

### Description
Sets the source files for the analysis.

### Method
setSources

### Parameters
- **$files_sources** (array) - Required - List of source files.

### Request Example
```php
$obj_context->inputs->setSources($files_sources);
```

### Response
No return value.
```

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

### Inputs: getSources

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Retrieves the source files set for the analysis.

```APIDOC
## [GET] getSources

### Description
Retrieves the source files set for the analysis.

### Method
getSources

### Parameters
None.

### Request Example
```php
$sources = $obj_context->inputs->getSources();
```

### Response
- **$sources** (array) - List of source files.
```

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

### PHP code violating Twig autoescaping rule

Source: https://github.com/designsecurity/progpilot/blob/master/docs/CUSTOM_ANALYSIS.md

Example PHP code that does not satisfy the custom rule set on the Twig_Environment function call. It creates a Twig_Environment with 'autoescape' set to false, which triggers the MUST_NOT_VERIFY_DEFINITION rule.

```php
<?php

$a = new Twig_Environment($loader, array("autoescape" => false));

```

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

### Copy remote file locally and analyze with getID3()

Source: https://github.com/designsecurity/progpilot/blob/master/projects/tests/tests/performance/ID3/readme.txt

Use this PHP snippet to analyze remote files over HTTP or FTP by first copying the file locally. It downloads the remote file to a temporary location, passes the original filesize and filename to $getID3->analyze(), then deletes the temporary file. Since v1.9.9-20150212, the second and third parameters to analyze() allow accurate playtime estimates when only a portion of a large remote file is downloaded.

```PHP
// Copy remote file locally to scan with getID3()
$remotefilename = 'http://www.example.com/filename.mp3';
if ($fp_remote = fopen($remotefilename, 'rb')) {
	$localtempfilename = tempnam('/tmp', 'getID3');
	if ($fp_local = fopen($localtempfilename, 'wb')) {
		while ($buffer = fread($fp_remote, 32768)) {
			fwrite($fp_local, $buffer);
		}
		fclose($fp_local);

		$remote_headers = array_change_key_case(get_headers($remotefilename, 1), CASE_LOWER);
		$remote_filesize = (isset($remote_headers['content-length']) ? (is_array($remote_headers['content-length']) ? $remote_headers['content-length'][count($remote_headers['content-length']) - 1] : $remote_headers['content-length']) : null);

		// Initialize getID3 engine
		$getID3 = new getID3;

		$ThisFileInfo = $getID3->analyze($localtempfilename, $remote_filesize, basename($remotefilename));

		// Delete temporary file
		unlink($localtempfilename);
	}
	fclose($fp_remote);
}
```

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

### Inputs: setFile

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the file to analyze. The analysis will prioritize the file over code if both are set.

```APIDOC
## [SET] setFile

### Description
Sets the file to analyze. The analysis will prioritize the file over code if both are set.

### Method
setFile

### Parameters
- **$file** (string) - Required - Path to the file to analyze, e.g., './myfile.php'.

### Request Example
```php
$obj_context->inputs->setFile($file);
```

### Response
No return value.
```

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

### Outputs: getAst

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Retrieves the Abstract Syntax Tree (AST) from the analysis.

```APIDOC
## [GET] getAst

### Description
Retrieves the Abstract Syntax Tree (AST) from the analysis.

### Method
getAst

### Parameters
None.

### Request Example
```php
$ast = $obj_context->outputs->getAst();
```

### Response
- **$ast** (mixed) - The AST data.
```

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

### Inputs: getCustomRules

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Retrieves the custom rule files set for the analysis.

```APIDOC
## [GET] getCustomRules

### Description
Retrieves the custom rule files set for the analysis.

### Method
getCustomRules

### Parameters
None.

### Request Example
```php
$customRules = $obj_context->inputs->getCustomRules();
```

### Response
- **$customRules** (array) - List of custom rule files.
```

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

### Build Docker Image

Source: https://github.com/designsecurity/progpilot/blob/master/DOCKER.md

Builds the progpilot Docker image with the tag 'progpilot'.

```bash
docker build -t progpilot .
```

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

### Options: setConfiguration

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the configuration for the analysis using a YAML file.

```APIDOC
## [SET] setConfiguration

### Description
Sets the configuration for the analysis using a YAML file.

### Method
setConfiguration

### Parameters
- **$config** (string) - Required - Path to the YAML configuration file.

### Request Example
```php
$obj_context->setConfiguration($config);
```

### Response
No return value.
```

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

### Inputs: getFile

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Retrieves the value of the file set for analysis.

```APIDOC
## [GET] getFile

### Description
Retrieves the value of the file set for analysis.

### Method
getFile

### Parameters
None.

### Request Example
```php
$file = $obj_context->inputs->getFile();
```

### Response
- **$file** (string) - The path to the file.
```

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

### Property dataflow with multiple states

Source: https://github.com/designsecurity/progpilot/blob/master/docs/dev/STATES.md

Shows how properties require different states. The instance is defined once, but its property $prop gets tainted or set to "null" in different branches. At block 4, the states from branches 2 and 3 are merged for the final echo.

```php
// block 1
// instance defined in blockid 1 (defaultState = 1)
$instance = new Object;

if(rand()) {
    // block 2
    // instance defined in blockid 1 (defaultState = 1)
    // state 2 of instance prop tainted
    $instance->prop = $_GET["p"]; 
    echo $instance->prop;
}
else {
    // block 3
    // instance defined in blockid 1 (defaultState = 1)
    // state 3 of instance prop "null"
    $instance->prop = "null";
    echo $instance->prop;
}

// block 4
// we launch dataflow analysis for properties
// parent of 4 = block 2, 3
// state 4 = merge(state 2,3)
echo $instance->prop;
```

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

### PHP code with call graph path that violates rule #1

Source: https://github.com/designsecurity/progpilot/blob/master/docs/CUSTOM_ANALYSIS.md

Example PHP code whose call graph has a path that does not verify the custom rule #1 (MUST_VERIFY_CALL_FLOW). The conditional call to dev_iam_rights() means one path skips it, causing the rule to be raised.

```php
<?php

function secret()
{
    dev_iam_authenticated();
    
    if(1 == rand())
    {
        dev_iam_rights();
    }
    else
    {
        nada();
    }
    
    var_dump(dev_retrieve_secret());
}

secret();

```

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

### Configure sources with setSources, addSources, getSources

Source: https://github.com/designsecurity/progpilot/blob/master/docs/SPECIFY_ANALYSIS.md

Use these methods on the inputs object to set, add, or retrieve source configuration files. The $files_sources parameter is a JSON file or an array of JSON files.

```php
$obj_context->inputs->setSources($files_sources);
```

```php
$obj_context->inputs->addSources($files_sources);
```

```php
$obj_context->inputs->getSources();
```

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

### Inputs: getFolder

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Retrieves the value of the folder set for analysis.

```APIDOC
## [GET] getFolder

### Description
Retrieves the value of the folder set for analysis.

### Method
getFolder

### Parameters
None.

### Request Example
```php
$folder = $obj_context->inputs->getFolder();
```

### Response
- **$folder** (string) - The path to the folder.
```

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

### Inputs: setSinks

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the sink files for the analysis.

```APIDOC
## [SET] setSinks

### Description
Sets the sink files for the analysis.

### Method
setSinks

### Parameters
- **$files_sinks** (array) - Required - List of sink files.

### Request Example
```php
$obj_context->inputs->setSinks($files_sinks);
```

### Response
No return value.
```

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

### Inputs: setCustomRules

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the custom rule files for the analysis.

```APIDOC
## [SET] setCustomRules

### Description
Sets the custom rule files for the analysis.

### Method
setCustomRules

### Parameters
- **$files_custom** (array) - Required - List of custom rule files.

### Request Example
```php
$obj_context->inputs->setCustomRules($files_custom);
```

### Response
No return value.
```

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

### Inputs: setFolder

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the folder to analyze. The analysis will prioritize the folder if both file and code are also set.

```APIDOC
## [SET] setFolder

### Description
Sets the folder to analyze. The analysis will prioritize the folder if both file and code are also set.

### Method
setFolder

### Parameters
- **$folder** (string) - Required - Path to the folder to analyze.

### Request Example
```php
$obj_context->inputs->setFolder($folder);
```

### Response
No return value.
```

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

### Inputs: addCustomRules

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Adds custom rule files to the analysis.

```APIDOC
## [ADD] addCustomRules

### Description
Adds custom rule files to the analysis.

### Method
addCustomRules

### Parameters
- **$files_custom** (array) - Required - List of custom rule files.

### Request Example
```php
$obj_context->inputs->addCustomRules($files_custom);
```

### Response
No return value.
```

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

### Inputs: addSinks

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Adds sink files to the analysis.

```APIDOC
## [ADD] addSinks

### Description
Adds sink files to the analysis.

### Method
addSinks

### Parameters
- **$files_sinks** (array) - Required - List of sink files.

### Request Example
```php
$obj_context->inputs->addSinks($files_sinks);
```

### Response
No return value.
```

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

### Inputs: getValidators

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Retrieves the validator files set for the analysis.

```APIDOC
## [GET] getValidators

### Description
Retrieves the validator files set for the analysis.

### Method
getValidators

### Parameters
None.

### Request Example
```php
$validators = $obj_context->inputs->getValidators();
```

### Response
- **$validators** (array) - List of validator files.
```

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

### Inputs: setFalsePositives

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the false positives handling for the analysis.

```APIDOC
## [SET] setFalsePositives

### Description
Sets the false positives handling for the analysis.

### Method
setFalsePositives

### Parameters
- **$mixed** (mixed) - Required - The false positives value.

### Request Example
```php
$obj_context->inputs->setFalsePositives($mixed);
```

### Response
No return value.
```

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

### Inputs: getSanitizers

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Retrieves the sanitizer files set for the analysis.

```APIDOC
## [GET] getSanitizers

### Description
Retrieves the sanitizer files set for the analysis.

### Method
getSanitizers

### Parameters
None.

### Request Example
```php
$sanitizers = $obj_context->inputs->getSanitizers();
```

### Response
- **$sanitizers** (array) - List of sanitizer files.
```

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

### Inputs: getSinks

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Retrieves the sink files set for the analysis.

```APIDOC
## [GET] getSinks

### Description
Retrieves the sink files set for the analysis.

### Method
getSinks

### Parameters
None.

### Request Example
```php
$sinks = $obj_context->inputs->getSinks();
```

### Response
- **$sinks** (array) - List of sink files.
```

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

### JSON File with False Positives

Source: https://github.com/designsecurity/progpilot/blob/master/docs/FALSE_POSITIVES.md

Create a JSON file containing all false positives with the hash as the value of the vuln_id property.

```json
{
    "false_positives":
        [
            {"vuln_id":"e64d474f7d71f783ca18431b280095644599c6b789005c7748587891a0cd8a94"}
        ]
}
```

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

### Outputs: setOnAddResult

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets a callback function to be called for each vulnerability found.

```APIDOC
## [SET] setOnAddResult

### Description
Sets a callback function to be called for each vulnerability found.

### Method
setOnAddResult

### Parameters
- **$func** (callable) - Required - The callback function that receives the vulnerability as argument.

### Request Example
```php
$obj_context->outputs->setOnAddResult($func);
```

### Response
No return value.
```

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

### Inputs: getCode

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Retrieves the value of the code set for analysis.

```APIDOC
## [GET] getCode

### Description
Retrieves the value of the code set for analysis.

### Method
getCode

### Parameters
None.

### Request Example
```php
$code = $obj_context->inputs->getCode();
```

### Response
- **$code** (string) - The code contents.
```

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

### Inputs: setInclusions

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the inclusions for the analysis.

```APIDOC
## [SET] setInclusions

### Description
Sets the inclusions for the analysis.

### Method
setInclusions

### Parameters
- **$mixed** (mixed) - Required - The inclusions value.

### Request Example
```php
$obj_context->inputs->setInclusions($mixed);
```

### Response
No return value.
```

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

### Add expected output for a test in projects/tests/ooptest.php

Source: https://github.com/designsecurity/progpilot/blob/master/docs/CONTRIBUTING.md

When implementing a new test, edit projects/tests/ooptest.php and add an array entry with the test file name and expected vulnerabilities. Each vulnerability is an array containing the source name, source line number, and attack type. For multiple sources, use nested arrays for names and line numbers.

```php
    [
        "./tests/oop/simple27.php",
        [["\$_GET[\"p\"]", "8", "xss"],
        ["\$_GET[\"t\"]", "17", "xss"]]
    ]
```

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

### Inputs: setCode

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the code to analyze. The analysis will prioritize the file or folder if also set.

```APIDOC
## [SET] setCode

### Description
Sets the code to analyze. The analysis will prioritize the file or folder if also set.

### Method
setCode

### Parameters
- **$code** (string) - Required - The contents/code of a file, e.g., `$code = file_get_contents("./myfile.php");`.

### Request Example
```php
$obj_context->inputs->setCode($code);
```

### Response
No return value.
```

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

### Inputs: addValidators

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Adds validator files to the analysis.

```APIDOC
## [ADD] addValidators

### Description
Adds validator files to the analysis.

### Method
addValidators

### Parameters
- **$files_validators** (array) - Required - List of validator files.

### Request Example
```php
$obj_context->inputs->addValidators($files_validators);
```

### Response
No return value.
```

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

### PHP Array with False Positives

Source: https://github.com/designsecurity/progpilot/blob/master/docs/FALSE_POSITIVES.md

Use a PHP array that contains the false positives, with each entry having a vuln_id key.

```php
$arr = [
        array("vuln_id" => "f31cec392303e924f666116fd67d897c92e8a59a5e8ca93a65091701ca9db558")
    ];
```

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

### Inputs: setExclusions

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the exclusions for the analysis.

```APIDOC
## [SET] setExclusions

### Description
Sets the exclusions for the analysis.

### Method
setExclusions

### Parameters
- **$mixed** (mixed) - Required - The exclusions value.

### Request Example
```php
$obj_context->inputs->setExclusions($mixed);
```

### Response
No return value.
```

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

### Inputs: setValidators

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the validator files for the analysis.

```APIDOC
## [SET] setValidators

### Description
Sets the validator files for the analysis.

### Method
setValidators

### Parameters
- **$files_validators** (array) - Required - List of validator files.

### Request Example
```php
$obj_context->inputs->setValidators($files_validators);
```

### Response
No return value.
```

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

### Inputs: setSanitizers

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the sanitizer files for the analysis.

```APIDOC
## [SET] setSanitizers

### Description
Sets the sanitizer files for the analysis.

### Method
setSanitizers

### Parameters
- **$files_sanitizers** (array) - Required - List of sanitizer files.

### Request Example
```php
$obj_context->inputs->setSanitizers($files_sanitizers);
```

### Response
No return value.
```

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

### Inputs: addSanitizers

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Adds sanitizer files to the analysis.

```APIDOC
## [ADD] addSanitizers

### Description
Adds sanitizer files to the analysis.

### Method
addSanitizers

### Parameters
- **$files_sanitizers** (array) - Required - List of sanitizer files.

### Request Example
```php
$obj_context->inputs->addSanitizers($files_sanitizers);
```

### Response
No return value.
```

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

### Chained calls with multiple instances

Source: https://github.com/designsecurity/progpilot/blob/master/docs/dev/STATES.md

Shows chained method calls on instances. Each instance is defined in its own block with its own defaultState. The chain $instance1->func1()->func2()->func3() is executed, but the functions are commented out.

```php
// block 1
// instance1 defined in blockid 1 (defaultState = 1)
$instance1 = new Object1;

/*
function func1() {
    // block 2
    // instance2 defined in blockid 2 (defaultState = 2)
    $instance2 = new Object2;
    return $instance2;
}

function func2() {
    // block 3
    // instance3 defined in blockid 3 (defaultState = 3)
    $instance3 = new Object3;
    return $instance3;
}

function func3() {
    echo $this->prop;
}
*/

$instance1->func1()->func2()->func3();
```

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

### Options: setMaxDefinitions

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the maximum number of definitions per file to prevent memory exhaustion.

```APIDOC
## [SET] setMaxDefinitions

### Description
Sets the maximum number of definitions per file to prevent memory exhaustion.

### Method
setMaxDefinitions

### Parameters
- **$nb** (integer) - Required - The maximum number of definitions. Default is 3000.

### Request Example
```php
$obj_context->setMaxDefinitions($nb);
```

### Response
No return value.
```

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

### Pass False Positives to Analyzer

Source: https://github.com/designsecurity/progpilot/blob/master/docs/FALSE_POSITIVES.md

Pass the JSON file or PHP array to the setFalsePositives function to make the analyzer ignore vulnerabilities with these hashes.

```php
$context->inputs->setFalsePositives($arr_or_file);
```

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

### Configure validators with addValidators/setValidators/getValidators

Source: https://github.com/designsecurity/progpilot/blob/master/docs/SPECIFY_ANALYSIS.md

Shows the three methods to add, set, or retrieve validators on the inputs context. The $file_validators argument is a JSON file or an array of JSON files.

```php
$obj_context->inputs->addValidators($file_validators);
```

```php
$obj_context->inputs->setValidators($file_validators);
```

```php
$obj_context->inputs->getValidators();
```

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

### Options: setDebugMode

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets whether to output warnings during the analysis.

```APIDOC
## [SET] setDebugMode

### Description
Sets whether to output warnings during the analysis.

### Method
setDebugMode

### Parameters
- **$bool** (boolean) - Required - True to output warnings, false otherwise. Default is false.

### Request Example
```php
$obj_context->setDebugMode($bool);
```

### Response
No return value.
```

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

### Inputs: setResolvedIncludes

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the resolved includes for the analysis.

```APIDOC
## [SET] setResolvedIncludes

### Description
Sets the resolved includes for the analysis.

### Method
setResolvedIncludes

### Parameters
- **$mixed** (mixed) - Required - The resolved includes value.

### Request Example
```php
$obj_context->inputs->setResolvedIncludes($mixed);
```

### Response
No return value.
```

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

### Vulnerability Identifier Hash Output

Source: https://github.com/designsecurity/progpilot/blob/master/docs/FALSE_POSITIVES.md

Shows the hash output for a vulnerability identifier, which is independent of code indentation and can be used to handle false positives.

```javascript
    ["vuln_id"]=>
    string(64) "e64d474f7d71f783ca18431b280095644599c6b789005c7748587891a0cd8a94"
```

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

### Options: setPrettyPrint

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets whether to pretty print the JSON output of the standalone progpilot application.

```APIDOC
## [SET] setPrettyPrint

### Description
Sets whether to pretty print the JSON output of the standalone progpilot application.

### Method
setPrettyPrint

### Parameters
- **$bool** (boolean) - Required - True to pretty print, false otherwise. Default is true.

### Request Example
```php
$obj_context->setPrettyPrint($bool);
```

### Response
No return value.
```

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

### Outputs: getCfg

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Retrieves the Control Flow Graph (CFG) from the analysis.

```APIDOC
## [GET] getCfg

### Description
Retrieves the Control Flow Graph (CFG) from the analysis.

### Method
getCfg

### Parameters
None.

### Request Example
```php
$cfg = $obj_context->outputs->getCfg();
```

### Response
- **$cfg** (mixed) - The CFG data.
```

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

### getSinks

Source: https://github.com/designsecurity/progpilot/blob/master/docs/SPECIFY_ANALYSIS.md

Retrieves the current sinks configuration.

```APIDOC
## getSinks

### Description
Retrieves the current sinks configuration.

### Method
getSinks

### Parameters
None documented.

### Response
No response body is documented.
```

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

### instanceof with undefined class

Source: https://github.com/designsecurity/progpilot/blob/master/docs/SPECIFY_ANALYSIS.md

Shows that instanceof continues to work even when the class is not defined in the analyzed code. The PHP code instantiates the undefined class and calls the sink method.

```json
{"name": "query", "instanceof": "VulnerableClass", "language": "php"}
```

```php
<?php

$a = new VulnerableClass;
$a->query($_GET["p"]);
```

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

### Options: setAnalyzeIncludes

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets whether to analyze included files.

```APIDOC
## [SET] setAnalyzeIncludes

### Description
Sets whether to analyze included files.

### Method
setAnalyzeIncludes

### Parameters
- **$bool** (boolean) - Required - True to analyze included files, false otherwise. Default is true.

### Request Example
```php
$obj_context->setAnalyzeIncludes($bool);
```

### Response
No return value.
```

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

### Options: setMaxFileSize

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the maximum file size to analyze.

```APIDOC
## [SET] setMaxFileSize

### Description
Sets the maximum file size to analyze.

### Method
setMaxFileSize

### Parameters
- **$size_bytes** (integer) - Required - The maximum file size in bytes. Default is 500000 bytes.

### Request Example
```php
$obj_context->setMaxFileSize($size_bytes);
```

### Response
No return value.
```

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

### getSanitizers

Source: https://github.com/designsecurity/progpilot/blob/master/docs/SPECIFY_ANALYSIS.md

Retrieves the current sanitizers configuration.

```APIDOC
## getSanitizers

### Description
Retrieves the current sanitizers configuration.

### Method
getSanitizers

### Parameters
None documented.

### Response
No response body is documented.
```

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

### Outputs: setIncludeFailuresFile

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the file to write include failures to.

```APIDOC
## [SET] setIncludeFailuresFile

### Description
Sets the file to write include failures to.

### Method
setIncludeFailuresFile

### Parameters
- **$file** (string) - Required - Path to the file.

### Request Example
```php
$obj_context->outputs->setIncludeFailuresFile($file);
```

### Response
No return value.
```

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

### Outputs: getCallGraph

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Retrieves the call graph from the analysis.

```APIDOC
## [GET] getCallGraph

### Description
Retrieves the call graph from the analysis.

### Method
getCallGraph

### Parameters
None.

### Request Example
```php
$callGraph = $obj_context->outputs->getCallGraph();
```

### Response
- **$callGraph** (mixed) - The call graph data.
```

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

### addSanitizers

Source: https://github.com/designsecurity/progpilot/blob/master/docs/SPECIFY_ANALYSIS.md

Adds sanitizers to the existing configuration. Accepts a JSON file or an array of JSON files defining sanitizer rules.

```APIDOC
## addSanitizers

### Description
Adds sanitizers to the existing configuration. Accepts a JSON file or an array of JSON files defining sanitizer rules.

### Method
addSanitizers

### Parameters
- **$file_sanitizers** (JSON file or array of JSON files) - Required - The sanitizer configuration file(s).

### Request Example
```javascript
{
    "sanitizers": [
        {"name": "filter_var",  "language": "php", "parameters": 
            [
                {"id": 2, "conditions": "equals", "values": 
                    [
                        {"value" : "FILTER_SANITIZE_ENCODED", "prevent" : ["xss"]},
                        {"value" : "FILTER_SANITIZE_MAGIC_QUOTES", "prevent" : ["command_injection", "sql_injection"]},
                        {"value" : "FILTER_SANITIZE_SPECIAL_CHARS", "prevent" : ["xss"]},
                        {"value" : "FILTER_SANITIZE_FULL_SPECIAL_CHARS", "prevent" : ["xss"]},
                        {"value" : "FILTER_SANITIZE_STRING", "prevent" : ["xss"]},
                        {"value" : "FILTER_SANITIZE_STRIPPED", "prevent" : ["xss"]}
                    ]}
            ]
        },
        {"name": "addslashes", "language": "php", "prevent": ["sql_injection", "command_injection"]}
        ]
}
```

### Response
No response body is documented.
```

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

### Options: setMaxFileAnalysisDuration

Source: https://github.com/designsecurity/progpilot/blob/master/docs/API.md

Sets the maximum execution time per file for some analysis steps.

```APIDOC
## [SET] setMaxFileAnalysisDuration

### Description
Sets the maximum execution time per file for some analysis steps.

### Method
setMaxFileAnalysisDuration

### Parameters
- **$time_sec** (integer) - Required - The maximum time in seconds. Default is 10 seconds.

### Request Example
```php
$obj_context->setMaxFileAnalysisDuration($time_sec);
```

### Response
No return value.
```
Tokens:
Raw