Skip to main content

An easy-to-use library for implementing and visualizing a control flow graph in python.

Project description

What is pythonCFG?

It is an easy-to-use library to implement control flow graph generation in your emulator.

All that is required is to wrap your instruction set around the two classes Instruction or Jump.

Downloading the library

If you wish to download the library and use it, you must install Graphviz and add it to your PATH at install.

https://graphviz.org/download/

After installing Graphviz, you can use pip to install the library for use in your own emulator.

pip install pythonCFG

Using the library

Assuming you have an emulator which contains some pseudocode such as... emulator.execute(instruction)

You will take this instruction and wrap it into a Instruction or Jump class. An instruction can optionally take an operand, but requires a name.

A jump requires a name and "success_address" (operand) for all types of JumpType. A failure address is needed in the case of a JCC.

Some psuedocode to simulate this is...

match instruction:
      case INC:
            return Instruction("INC")
            
      case JUMP:
            return Jump("JUMP", 0x30, JumpType.JMP) ## NOTE: A failure address is not needed as this is an absolute jump!
            ## NOTE: You will need to dynamically determine what your success_address and failure_address.
            
      case CONDITIONAL_JUMP:
            return Jump("COND", 0x30, """ JumpType.JCC_TAKEN or JumpType.JCC_NOT_TAKEN """, 0x20) ## NOTE: A failure address is needed as this is conditional.
            ## It is burden upon you to determine if the jump is taken or not as it is not feasible for this library and its goals.

After matching your instruction set into an Instruction or Jump, you will need to execute this instruction in the graph. Some pseudocode after you've matched your instruction set with its respective operands.

    class Emulator:
        def __init__(self):
              ## OTHER ARGUMENTS ARE IMPLEMENTATION SPECIFIC
              self.graph = pyCFG(0) ## Import this class and set your entry point address ( in this case 0 ).
              
        def execute(self, instruction):
              self.graph.execute( matched_instruction(instruction) ) 
              ## We are assuming you have correctly determined operands in matched_instruction.
              
        def output(self):
              self.graph.png("some_output.png") # Returns an image of the control flow graph.

Implementations?

There is an example implementation in the source code of pythonRSCdev.

https://github.com/Calastrophe/pythonRSC-dev/blob/master/src/pythonRSCdev/emulator.py#L41

Then the matched instruction is executed inside the start() function above it.

What does it look like?

A large execution graph will typically look something like this ( instructions in the block depend on your architecture ).

There a few things subject to change on how the control flow graph will look in coming versions in order to better analyze the graph.

image

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pythonCFG-1.2.0.tar.gz (17.9 kB view details)

Uploaded Source

Built Distribution

pythonCFG-1.2.0-py3-none-any.whl (18.1 kB view details)

Uploaded Python 3

File details

Details for the file pythonCFG-1.2.0.tar.gz.

File metadata

  • Download URL: pythonCFG-1.2.0.tar.gz
  • Upload date:
  • Size: 17.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.11.0

File hashes

Hashes for pythonCFG-1.2.0.tar.gz
Algorithm Hash digest
SHA256 e73e86b998e3d488888378568c0be1105153ca3a1146ec84d8232eaf2195b704
MD5 122e9bb376162106daabab84f78c040b
BLAKE2b-256 e90906c38ea581d6d15f9fa2ac7adfea26dee494f316febfb79d30554b373928

See more details on using hashes here.

File details

Details for the file pythonCFG-1.2.0-py3-none-any.whl.

File metadata

  • Download URL: pythonCFG-1.2.0-py3-none-any.whl
  • Upload date:
  • Size: 18.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.11.0

File hashes

Hashes for pythonCFG-1.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 66e33fe48aaec9663e7f3448e7b5d8417b7063d5d63857bef447ce437c2f588b
MD5 1397e632da69245f6d6c2caab52dcfc5
BLAKE2b-256 c5f84be55675f512d010aa8a68e3d22220184404e411cee4e576c29bf802918e

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page