IPED provides two main APIs for programmatic access to digital forensics capabilities:
Core Java API : Direct access to IPED’s processing engine and data structuresWeb 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 IIPEDSourceCase/index access iped.dataIItemReaderRead-only item access iped.dataIItemFull item manipulation iped.dataIIPEDSearcherSearch interface iped.searchAbstractTaskCustom 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
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