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

> Contribute to the IPED project effortlessly. Follow our complete guide for developers: fork the repo, build with Maven, add features with JUnit tests, and submit your pull request for the advanced digital forensics suite.

- Repository: [Serviço de Perícias em Informática/IPED](https://github.com/sepinf-inc/IPED)
- Tags: how-to-guide
- Published: 2026-03-11

---

**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`](https://github.com/sepinf-inc/IPED/blob/main/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`](https://github.com/sepinf-inc/IPED/blob/main/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:

```bash
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`](https://github.com/sepinf-inc/IPED/blob/main/iped-parsers/config/sun_checks.xml)**, referenced in **[`iped-parsers/pom.xml`](https://github.com/sepinf-inc/IPED/blob/main/iped-parsers/pom.xml)** (lines 36‑44).

### Verifying Code Style

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

```bash
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`](https://github.com/sepinf-inc/IPED/blob/main/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
'''
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`](https://github.com/sepinf-inc/IPED/blob/main/MyCustomParser.py), register the new MIME type in **[`iped-app/src/main/resources/iped/app/parsers/mimetypes.txt`](https://github.com/sepinf-inc/IPED/blob/main/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`](https://github.com/sepinf-inc/IPED/blob/main/.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`](https://github.com/sepinf-inc/IPED/blob/main/pom.xml)** – Parent Maven POM defining modules and dependencies.
- **[`iped-parsers/pom.xml`](https://github.com/sepinf-inc/IPED/blob/main/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`](https://github.com/sepinf-inc/IPED/blob/main/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`](https://github.com/sepinf-inc/IPED/blob/main/.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`](https://github.com/sepinf-inc/IPED/blob/main/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.