API Overview

Comprehensive guide to IPED’s programmatic APIs for digital forensics automation

IPED provides two main APIs for programmatic access to digital forensics capabilities:

• Core Java API: Direct access to IPED’s processing engine and data structures
• Web API: RESTful HTTP endpoints for remote case access and search

Core Java API

The Core Java API enables developers to build custom forensic tools and automated workflows using IPED’s processing capabilities.

Key Components

Item API

Access and manipulate evidence items with IItemReader and IItem interfaces

Search API

Query and filter evidence using Lucene-based search with IPEDSearcher

Task API

Extend IPED with custom processing tasks using AbstractTask

Web API

REST endpoints for remote case access and automation

Getting Started

Maven Dependencies

Add IPED dependencies to your pom.xml:

<dependency>
    <groupId>io.github.sepinf-inc</groupId>
    <artifactId>iped-api</artifactId>
    <version>4.1.0</version>
</dependency>

<dependency>
    <groupId>io.github.sepinf-inc</groupId>
    <artifactId>iped-engine</artifactId>
    <version>4.1.0</version>
</dependency>

Quick Example

Access an IPED case and search for items:

import iped.engine.data.IPEDSource;
import iped.engine.search.IPEDSearcher;
import iped.data.IItem;
import iped.search.SearchResult;

public class IPEDExample {
    public static void main(String[] args) throws Exception {
        // Open case
        File caseDir = new File("/path/to/case");
        IPEDSource source = new IPEDSource(caseDir);
        
        // Search for documents
        IPEDSearcher searcher = new IPEDSearcher(source, "type:pdf");
        SearchResult result = searcher.search();
        
        // Process results
        for (int id : result.getIds()) {
            IItem item = source.getItemByID(id);
            System.out.println(item.getName() + ": " + item.getLength());
        }
        
        source.close();
    }
}

Architecture

Data Flow

Core Interfaces

Interface	Purpose	Package
IIPEDSource	Case/index access	iped.data
IItemReader	Read-only item access	iped.data
IItem	Full item manipulation	iped.data
IIPEDSearcher	Search interface	iped.search
AbstractTask	Custom processing	iped.engine.task

Use Cases

Automated Analysis

Build custom analysis workflows:

// Find and export all images
IPEDSearcher searcher = new IPEDSearcher(source, "category:images");
SearchResult result = searcher.search();

for (int id : result.getIds()) {
    IItem item = source.getItemByID(id);
    Files.copy(
        item.getBufferedInputStream(), 
        Paths.get("/export/" + item.getName())
    );
}

Custom Processing Tasks

Extend IPED’s processing pipeline:

public class CustomHashTask extends AbstractTask {
    @Override
    protected void process(IItem item) throws Exception {
        byte[] content = IOUtils.toByteArray(item.getBufferedInputStream());
        String hash = computeCustomHash(content);
        item.setExtraAttribute("customHash", hash);
    }
}

Remote Access

Query cases via REST API:

# Search for items
curl "http://localhost:8080/search?q=pdf"

# Get item metadata
curl "http://localhost:8080/sources/case1/docs/12345"

# Download content
curl "http://localhost:8080/sources/case1/docs/12345/content" -o file.pdf

Performance Considerations

Large Result Sets: When searching returns more than 1 million items, scoring is automatically disabled. Use setNoScoring(true) for better performance on large searches.

Streaming Content: Always use getBufferedInputStream() or getSeekableInputStream() instead of getTempFile() to avoid spooling large files to disk.

Thread Safety

IPEDSource and IPEDSearcher are thread-safe for read operations. For processing tasks, each worker thread maintains its own task instances.

Error Handling

try {
    SearchResult result = searcher.search();
} catch (ParseException e) {
    // Invalid query syntax
} catch (IOException e) {
    // Index access error
}

Next Steps

Item API Reference

Learn about accessing item properties and content

Search API Reference

Master query syntax and search operations

Web API Reference

Explore REST endpoints for remote access

Task Development

Create custom processing modules