PortEx

Welcome to PortEx

PortEx is a Java library for static malware analysis of Portable Executable files. Its focus is on PE malformation robustness, and anomaly detection. PortEx is written in Java and Scala, and targeted at Java applications.

Features

• Reading header information from: MSDOS Header, COFF File Header, Optional Header, Section Table
• Reading PE structures: Imports, Resources, Exports, Debug Directory, Relocations, Delay Load Imports, Bound Imports
• Dumping of sections, resources, overlay, certificates, embedded ZIP, JAR or .class files
• Scanning for file format anomalies, including structural anomalies, deprecated, reserved, wrong or non-default values.
• Visualize PE file structure, local entropies and byteplot of the file with variable colors and sizes
• Calculate Shannon Entropy and Chi Squared for files and sections
• Calculate ImpHash and Rich and RichPV hash values for files and sections
• Parse RichHeader and verify checksum
• Parse Authenticode signatures (certificate table, PKCS#7, X.509 certificates, timestamps, nested signatures) and verify their integrity: image digest, message digest, signer and certificate signatures (no trust or revocation checks); malformed and manipulated signatures are reported as anomalies
• Calculate and verify Optional Header checksum
• Scan for packer, protector, cryptor, installer and file type signatures or your own signature database, with patterns tied to locations like the entry point, overlay, resources, sections or .NET streams (see Signatures), and import PEiD databases. The bundled signatures include rules converted from Detect It Easy
• Scan for Jar to EXE wrapper (e.g. exe4j, jsmooth, jar2exe, launch4j)
• Extract Unicode and ASCII strings contained in the file
• Extraction and conversion of .ICO files from icons in the resource section
• Extraction of version information and manifest from the file
• Reading .NET metadata and streams (Alpha)

For more information have a look at PortEx Wiki and the Documentation. The signature format is described in docs/SIGNATURES.md. Upgrading from PortEx 5? See docs/MIGRATION-6.md.

PortexAnalyzer CLI and GUI

PortexAnalyzer CLI is a command line tool that runs the library PortEx under the hood.

If you are looking for a readily compiled command line PE scanner to analyse files with it, you will find the newest version here PortexAnalyzer.jar

The long-term release version of the CLI tool is on the releases page.

The GUI version is available here: PortexAnalyzerGUI

Using PortEx

Including PortEx to a Maven Project

You can include PortEx to your project by adding the following Maven dependency:

<dependency>
   <groupId>io.github.struppigel</groupId>
   <artifactId>portex_2.12</artifactId>
   <version>6.0.0</version>
</dependency> 

To use a local build, add the library as follows:

<dependency>
   <groupId>io.github.struppigel</groupId>
   <artifactId>portex_2.12</artifactId>
   <version>6.0.0</version>
   <scope>system</scope>
   <systemPath>$PORTEXDIR/target/scala-2.12/portex_2.12-6.0.0.jar</systemPath>
</dependency> 

Including PortEx to an SBT project

Add the dependency as follows in your build.sbt

libraryDependencies += "io.github.struppigel" % "portex_2.12" % "6.0.0"

Building PortEx

Requirements

PortEx is build with sbt

Compile and Build With sbt

To simply compile the project invoke:

$ sbt compile

To create a jar:

$ sbt package

To compile a fat jar that can be used as command line tool, type:

$ sbt assembly

Create Eclipse Project

You can create an eclipse project by using the sbteclipse plugin. Add the following line to project/plugins.sbt:

addSbtPlugin("com.typesafe.sbteclipse" % "sbteclipse-plugin" % "2.4.0")

Generate the project files for Eclipse:

$ sbt eclipse

Import the project to Eclipse via the Import Wizard.

Donations

I develop PortEx and PortexAnalyzer as a hobby in my freetime. If you like it, please consider buying me a coffee: https://ko-fi.com/struppigel

Author

Karsten Hahn

Twitter/X: @Struppigel

Mastodon: [email protected]

Bluesky: https://bsky.app/profile/struppigel.bsky.social

Youtube: MalwareAnalysisForHedgehogs

License

Apache License, Version 2.0

The signature database die.sig is converted from the rules of Detect It Easy and is licensed under the MIT License, see THIRD-PARTY-NOTICES.md.