ropoly

README

Current Status

polyverse/ropoly

Build Instructions

Run "./build.sh"

Run Instructions for Docker

The container must be run with --cap-add=SYS_PTRACE --security-opt seccomp=unconfined --privileged Port 8008 must be mapped to a port on the host with -p in order to view output.

Command Line Options

server

Runs as a server exposing the API described under "Ropoly API Endpoints." Use this option, "scan", or both.

scan

Runs as a daemon that repeatedly scans the server's file system and the libraries of its running processes to check for Polyverse signatures. Use this option, "server", or both.

log

Use only with "scan". Logs the results of scanning for signatures.

prometheus

Use only with "scan". Not yet implemented, and doesn't do anything useful.

ROPoly API Endpoints

/api/v1/pids

Return list of all visible process ids and information about each process.

/api/v1/pid/<pid>/libraries[?signatures=<[true]>]

Return list of loaded libraries for the given pid. If pid is 0, pid refers to the ROPoly process itself. If signature is true, list whether or not each library has a Polyverse signature.

/api/v1/pid/<pid>[?mode=<taints|gadgets|fingerprint>][&start=start][&end=end][&instructions=instructions][&octets=octets][&limit=limit][?access=<[R][W][X][F]|None>][?<string|regexp>=target]

Return information about the memory of the given pid according to the option provided in mode. taints by default.

/api/v1/files/<path>[?query=<taints|gadgets|fingerprint>][&start=start][&end=end][&instructions=instructions][&octets=octets][&limit=limit]

Return information about the files and directories in the given directory on the server according to the option provided in query. Default option is taints.

/api/v1/fingerprints

Return the list of fingerprints stored on the server.

/api/v1/fingerprints/{fingerprint}[?overwrite=true]

Return the contents of the fingerprint with the given name. Post fingerprint file to add fingerprint with the given name. Fails if fingerprint with given name already exists, unless overwrite is set to true, in which case it will overwrite the old fingerprint.

/api/v1/fingerprints/{fingerprint}/compare?second=fingerprint[&out=filepath]

Compares the first given fingerprint to the one provided in second. Outputs the generated fingerprint comparison if out is not set. If out is set, saves the fingerprint comparison under the name provided to out.

/api/v1/comparisons

Return the list fingerprint comparisons stored on the server.

/api/v1/comparisons/{comparison}[?overwrite=true]

Return the contents of the fingerprint comparison with the given name. Post comparison file to add fingerprint comparison with the given name. Fails if fingerprint with the given name already exists, unless overwrite is set to true, in which case it will overwrite the old comparison.

/api/v1/comparisons/{comparison}/eqi?func=<|monte-carlo|envisen-original|count-poly|count-exp|>

Calculate the EQI based on the given fingerprint comparison stored on the server, using the EQI function named in func. Additional arguments may be required depending on func.

/api/v1/compare?old=filepath&new=filepath

Recommended to use /api/v1/fingerprints/old/compare?second=new instead. Get fingerprint comparison information about the changes from the old/original binary to the new/modified binary.

/api/v1/eqi?comparison=filepath&calc=<|monte-carlo|envisen-original|count-poly|count-exp|>

Recommended to use /api/v1/comparisons/comparison/eqi instead. Calculate the EQI based on the given fingerprint comparison file, using the given calculation method. Additional arguments may be required depending on calc.

Query options for /api/v1/pid/<pid> and /api/v1/files/<path>

taints

For libraries in memory if looking at a PID or contained files if looking at a directory, check if each is signed by Polyverse.

gadgets

Find up to limit gadgets between start and end of up to instructions instructions and octets bytes.

fingerprint

Generate a fingerprint based on up to limit gadgets between start and end of up to instructions instructions and octets bytes. If out is set to a name, saves under that name. Otherwise, outputs to client. Will fail if fingerprint with the given name already exists, unless overwrite is set to true, in which case it will overwrite the old fingerprint.

EQI options

monte-carlo

Uses a Monte Carlo method to simulate fingerprints ROP attacks of length between min and max gadgets. EQI is the percentage of attacks with no common offset.

envisen-original

Uses the original formula described at https://github.com/polyverse/EnVisen/blob/master/docs/entropy-index.md as of October 25, 2018.

count-poly

Uses a sum-of-squares method based on the number of gadgets weakly surviving at each offset. Uses all offsets for each original gadget by default; set single to true to treat each gadget as having only a single offset. To use a polynomial order other than 2.0, set order to another number.

count-exp

Uses the sum of exponents of numbers of gadgets weakly surviving at each offset. Uses all offsets for each original gadget by default; set single to true to treat each gadget as having only a single offset. Default base is 2.0; set base to another value to use a different base.

shared-offsets

Calculates EQI by looking at each gadget individually and checking how many gadgets it shares an offset with. Handles the case of multiple offsets based on the argument passed to multiple-handling, with the default being worst-only.

worst-only

When calculating each gadget's contribution to EQI, considers only the offset with the most contribution to EQI (the offset shared with the most other gadgets). The gadget's other offsets are still considered when calculating other gadgets' contribution to EQI.

closest-only

When calculating each gadget's contribution to EQI, considers only the smallest offset. The gadget's other offsets are still considered when calculating other gadgets' contributions to EQI.

multiplicative

For each gadget, starts with a "quality" value of 1, and multiplies it by the complement of the penalty incurred by each offset (normalized to a number between 0 and 1). This causes EQI to decrease asymptotically as each gadget appears at a greater number of offsets.

additive

Adds the penalty for each gadget offset, so that for example a gadget with two offsets each shared with n other gadgets would incur twice the EQI penalty a gadget with a single offset shared with n other gadgets. The same as count-poly with the default order of 2.0 and single=false.

additive-with-ceiling

Adds the penalty for each gadget offset, but caps the contribution of each individual gadget to the EQI at 100 divided by the total number of gadgets.