How to Contribute to the IPED Project: A Complete Guide for Digital Forensics Developers

Fork the sepinf-inc/IPED repository, install JDK 11 with JavaFX and Maven 3.x, run mvn clean install to build the multi-module forensic suite, add your feature with JUnit 4 unit tests, verify Checkstyle compliance, and submit a pull request targeting the master branch.

IPED (Integrated Platform for Evidence Discovery) is an open-source, Java-based digital forensics suite maintained by the Brazilian Federal Police. Contributing to the IPED project requires navigating its Maven multi-module architecture and forensic-specific build pipeline. This guide walks through the exact file paths, commands, and quality gates defined in the source code to ensure your contribution merges successfully.

IPED Repository Structure and Modules

The project uses a standard Maven multi-module layout defined in the parent pom.xml (lines 9‑17). Understanding these modules helps you locate where to add new functionality:

• iped-api – Core data structures and search interfaces.
• iped-utils – Common utilities for file I/O, hashing, and UI helpers.
• iped-parsers – File format parsers written in Java and Python.
• iped-viewers – Visualizers for images, videos, and maps.
• iped-carvers – File-carving engines for deleted data recovery.
• iped-geo – Geolocation processing and map rendering.
• iped-engine – Processing engine, web API, and indexing logic.
• iped-app – Desktop GUI application and script resources.

Every module inherits build conventions from the parent POM, ensuring consistent dependency management across the forensic toolkit.

Setting Up the Build Environment

Before compiling, verify your workstation meets the toolchain requirements specified in the repository README.md (lines 21‑28).

Prerequisites

1. Java Development Kit 11 with JavaFX support (e.g., Liberica OpenJDK 11 Full).
2. Apache Maven 3.x.
3. Optional external forensic tools (Sleuth Kit, Tesseract, etc.) referenced in the CI configuration for full integration testing.

Install these dependencies, then clone your fork locally. The build strictly requires JDK 11; newer versions may compile but are not guaranteed to produce compatible bytecode for the JavaFX desktop components.

Building the Project Locally

Navigate to the repository root and execute the standard Maven lifecycle:

mvn clean install

This command compiles all eight modules, executes unit tests, and assembles a self-contained forensic distribution in target/release/iped-<version>. You can launch the desktop GUI directly from this directory using the bundled Java runtime or your local JDK 11 installation.

Successful compilation is the first quality gate; the build must pass before you modify any source files.

Coding Standards and Style Enforcement

IPED enforces consistent formatting through Checkstyle. The configuration file resides at iped-parsers/config/sun_checks.xml, referenced in iped-parsers/pom.xml (lines 36‑44).

Verifying Code Style

Run the following command before committing to ensure your changes meet project standards:

mvn checkstyle:check

This validation step is identical to the linting performed during continuous integration. Address any warnings regarding indentation, naming conventions, or import order to prevent CI failures.

Writing Unit Tests

Every code contribution must include JUnit 4 test coverage. Place test classes under the corresponding module’s src/test/java directory, mirroring the package structure of the main source.

For reference, examine iped-parsers/iped-parsers-impl/src/test/java/iped/parsers/browsers/firefox/FirefoxSqliteParserTest.java (line 52), which demonstrates how to instantiate parsers and assert against forensic artifacts. Your tests should validate both successful parsing and error handling for malformed evidence files.

Contributing Python Parsers via JEP

IPED supports extensible parsers written in Python through the JEP (Java Embedded Python) bridge. This allows forensic developers to leverage Python libraries while maintaining Java’s threading model.

Creating a Custom Parser

Save your Python class to iped-app/resources/scripts/parsers/. The following minimal example demonstrates the required interface:

'''
Python parser example.
To use python parsers, first you must install JEP:
https://github.com/sepinf-inc/IPED/wiki/User-Manual#python-modules
'''

from org.apache.tika.sax import XHTMLContentHandler
from org.apache.tika.io import TemporaryResources

class MyCustomParser:
    """
    Simple thread‑safe parser that extracts text from a proprietary
    ``application/x‑myformat`` file.
    """

    def getSupportedTypes(self, context):
        # Declare the MIME type(s) this parser handles

        return ["application/x-myformat"]

    def parse(self, stream, handler, metadata, context):
        """
        Parse the input stream and emit XHTML via the Tika handler.
        """
        xhtml = XHTMLContentHandler(handler, metadata)
        xhtml.startDocument()
        # Example: read the whole stream (only for tiny files!)

        # raw = stream.read()

        # parsed_text = some_custom_logic(raw)

        xhtml.startElement("p")
        xhtml.characters("parsed content goes here")
        xhtml.endElement("p")
        # Store a custom property for later display in the UI

        metadata.add("myProp", "myValue")
        xhtml.endDocument()

After saving as MyCustomParser.py, register the new MIME type in iped-app/src/main/resources/iped/app/parsers/mimetypes.txt if it does not exist. Run mvn clean install to bundle the script into the release snapshot.

Continuous Integration and Pull Request Workflow

The project uses GitHub Actions defined in .github/workflows/maven.yml. This workflow builds the project on both Java 11 and Java 14, installs external forensic dependencies, and packages a snapshot release.

Submitting Your Contribution

1. Push your feature branch to your fork.
2. Verify the Java CI workflow completes without errors.
3. Open a pull request against the upstream master branch.
4. Complete the PR template, linking to any related issue.
5. Respond to reviewer feedback and update code/tests as requested.

Maintainers require green CI builds and adherence to the checklist before merging. If you plan a long-running feature, open an issue first to coordinate with the core team and avoid duplicate effort.

Key Source Files for Contributors

Navigate these specific paths to understand the architecture and extension points:

• pom.xml – Parent Maven POM defining modules and dependencies.
• iped-parsers/pom.xml – Parser-specific build logic and Checkstyle integration.
• iped-engine/src/main/java/iped/engine/webapi/ – REST API endpoints for search and thumbnails.
• iped-utils/src/main/java/iped/utils/ – Core utility classes for forensic I/O operations.

These files provide authoritative examples of how the processing engine handles evidence discovery and indexing.

Summary

• IPED is a Maven multi-module Java forensic suite; build it with mvn clean install after installing JDK 11 with JavaFX.
• Code style is enforced via Checkstyle configuration in iped-parsers/config/sun_checks.xml; always run mvn checkstyle:check locally.
• Unit tests using JUnit 4 are mandatory; place them in the corresponding module’s src/test/java directory.
• Python parsers integrate via JEP and belong in iped-app/resources/scripts/parsers/.
• All pull requests must pass the GitHub Actions CI pipeline defined in .github/workflows/maven.yml before merging.

Frequently Asked Questions

What Java version is required to build IPED?

You must use Java JDK 11 with JavaFX support (such as Liberica OpenJDK 11 Full). The build system explicitly targets this version in the parent POM, and the desktop GUI components require JavaFX libraries that are not included in standard OpenJDK distributions.

Where should I place new unit tests for a parser?

Place JUnit 4 test classes in the src/test/java folder of the same module containing your parser implementation. For example, Firefox parser tests reside in iped-parsers/iped-parsers-impl/src/test/java/iped/parsers/browsers/firefox/. This co-location ensures Maven executes them during the standard build lifecycle.

How do I add support for a new file format using Python?

Implement a Python class with getSupportedTypes() and parse() methods, save it to iped-app/resources/scripts/parsers/, and register the MIME type in iped-app/src/main/resources/iped/app/parsers/mimetypes.txt. The class must use the JEP bridge to interact with Apache Tika’s XHTMLContentHandler for emitting extracted text.

Why did my pull request fail the continuous integration checks?

CI failures typically result from Checkstyle violations, compilation errors on Java 11 or 14, or missing unit tests. Review the build logs in the GitHub Actions tab; ensure mvn clean install and mvn checkstyle:check both pass locally on your feature branch before submitting.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}