How Octopii Works
Octopii is an open-source tool designed to detect Personally Identifiable Information (PII) in images and documents, addressing a critical gap in security solutions for organizations handling sensitive data. It combines Optical Character Recognition (OCR) with a Convolutional Neural Network (CNN) to identify and classify PII-containing documents such as government IDs, passports, driver’s licenses, debit cards, and other sensitive materials. The tool was developed by RedHunt Labs after evaluating existing solutions like Amazon Macie, which is limited to Amazon S3 buckets and proprietary services, and ManageEngine DataSecurity Plus, which lacks S3 support and requires a paid license. Octopii fills this gap by providing an extensible, open-source alternative that can scan local file systems, Amazon S3 buckets, and open directory listings for exposed PII.
The core functionality of Octopii relies on two primary components: image classification and OCR. For image classification, Octopii uses a MobileNet CNN model, a 53-layer deep neural network trained via Google’s Teachable Machine. This model assigns an index to classified images, which is cross-referenced with a manually specified labels file to determine the type of document. The training data for this model includes blurred PII samples and standard templates generated through research. The classification process is designed to handle challenges posed by manually captured images, such as poor orientation, lighting issues, cropping, or degraded text, by preprocessing images to improve readability.
Once an image is classified, Octopii employs Tesseract, an open-source OCR engine, to extract text from the image. Tesseract uses a neural network optimized for text recognition to identify strings within the image. Octopii then searches for predefined keywords or patterns specific to certain document types—for example, the word 'Passbook' in a banking document or 'License' in a driver’s license. This keyword-matching process can be enhanced using regular expressions to improve accuracy and automate the detection of potential identity theft risks. The combination of image classification and OCR allows Octopii to identify PII even in poorly formatted or low-quality images.
Octopii operates by recursively traversing directories or URLs to fetch images, using OpenCV and the Python Imaging Library (PIL) to process files. Supported image formats include JPEG, PNG, and GIF. The tool cleans and preprocesses images to mitigate issues caused by manual scanning, such as skewed orientations or unclear text. This preprocessing step ensures that the neural network receives optimized input for accurate classification. The entire workflow—from image acquisition to OCR and keyword matching—is automated, making it efficient for large-scale audits of file shares, buckets, or web directories.
For instance, users can extend the keyword lists or refine the neural network model by contributing additional training data. This extensibility is particularly valuable for supporting international documents, as the current model may not cover all regional variations. RedHunt Labs encourages community contributions to improve the model’s accuracy and broaden its applicability. The project also provides a dummy environment with sample PII images to facilitate testing and demonstration.
Octopii is implemented in Python and requires a properly configured environment with all necessary dependencies, which can be installed using the provided requirements.txt file. The tool is designed as a command-line interface, making it accessible for integration into automated security workflows. Its open-source nature ensures transparency and adaptability, allowing organizations to tailor it to their specific needs without vendor lock-in.
Use Cases
Octopii addresses several critical scenarios where PII exposure poses significant risks to organizations. One primary use case is auditing browsable directories within web applications to detect unintended leaks of sensitive information. Many security breaches occur due to misconfigured directories or poorly secured storage, and Octopii helps identify such vulnerabilities by scanning for exposed PII in HTML-based listings or unprotected file shares.
Another key application is monitoring Amazon S3 buckets for unauthorized or accidental exposure of PII. Research indicates that over half of recent data breaches involving PII have stemmed from misconfigured S3 buckets. Octopii provides a cost-effective and scalable solution for organizations to ensure compliance with data protection regulations by systematically scanning these buckets for sensitive documents.
Octopii is also valuable for organizations conducting internal audits of local file systems or shared drives. Many small businesses and enterprises inadvertently store PII in insecure environments, prioritizing accessibility over security. By scanning directories for images containing PII, Octopii helps organizations mitigate risks associated with unauthorized access or data leaks. This use case is especially relevant for compliance with frameworks like GDPR, CCPA, or industry-specific regulations that mandate the protection of personal data.
For example, it can process manually uploaded documents that may not conform to standard formats, such as passport photos, signatures, or ID scans. Octopii’s support for regular expressions further enhances its precision, allowing users to define custom patterns for detecting specific types of sensitive information.
Organizations using tools like RedHunt Labs’ NVADR, an attack surface management SaaS solution, can leverage Octopii to identify exposed PII as part of continuous monitoring efforts. NVADR helps discover untracked assets and external vulnerabilities, while Octopii provides granular insights into the specific types of sensitive data that may be at risk. This combination enables organizations to proactively address exposure risks before they escalate into breaches.
Key Features & Capabilities
One of its standout features is the use of a pre-trained MobileNet CNN model for image classification, which balances performance and efficiency. The model was trained using a combination of blurred PII samples and standard document templates, ensuring it can recognize a wide range of document types.
The integration of Tesseract for OCR adds a layer of robustness to Octopii’s functionality. Tesseract’s neural network subsystem is optimized for text recognition, allowing it to extract readable text from images even under challenging conditions. Octopii supplements this with a keyword-matching mechanism, where users can specify terms unique to certain document types. For example, a driver’s license might contain keywords like 'License Number' or 'Issuing Authority,' while a passport would include terms like 'Nationality' or 'Passport Number.' This approach reduces reliance on perfect OCR accuracy and improves detection rates for partially obscured or degraded text.
Octopii supports three primary scanning modes: local file system audits, Amazon S3 bucket inspections, and open directory listings via URLs. For instance, a company might use Octopii to scan internal shared drives for employee documents or to audit public-facing directories for inadvertently exposed customer data. The tool’s recursive directory traversal ensures comprehensive coverage, leaving no potential PII-containing image unexamined.
Images captured manually may suffer from issues such as poor lighting, incorrect orientation, or partial cropping. This step is critical for maintaining accuracy, as poorly formatted images could otherwise lead to misclassification or missed detections. The tool’s ability to process JPEG, PNG, and GIF formats further expands its applicability across different storage and sharing platforms.
Extensibility is a core principle of Octopii’s architecture. Users can customize the tool by adding new document types to the classification model or refining the keyword lists used for OCR-based detection. RedHunt Labs provides guidance on contributing to the project, including instructions for generating custom models using Google’s Teachable Machine or Keras. This community-driven approach ensures that Octopii remains adaptable to evolving threats and regional document standards. For example, organizations in jurisdictions with unique ID formats can train the model to recognize local documents, enhancing its global utility.
Octopii’s open-source nature fosters collaboration and innovation within the security community. By making the tool freely available, RedHunt Labs encourages developers and security professionals to improve its capabilities. This includes expanding the dataset for training the CNN model, optimizing preprocessing steps, or integrating additional OCR engines.
Another notable feature is Octopii’s support for regular expressions in keyword matching. This capability allows users to define complex patterns for identifying PII, such as credit card numbers, social security numbers, or other structured data formats. Regular expressions enable precise matching of partial or formatted text, reducing the risk of false positives or negatives.
Octopii’s compatibility with Python and its command-line interface make it easy to integrate into existing security workflows.
Limitations and Considerations
While Octopii offers significant advantages for PII detection, its effectiveness depends on several factors that users should consider. The accuracy of the image classification model is heavily influenced by the quality and diversity of the training dataset. Since PII is highly sensitive, obtaining large volumes of labeled data for training is challenging. Octopii’s current model may not cover all international document types, and users in regions with unique ID formats may need to contribute additional training samples to improve recognition rates.
While preprocessing steps mitigate some of these issues, extremely poor-quality images may still result in misclassification or missed detections. Users should test Octopii with representative samples of their data to assess its accuracy in their specific environment.
Octopii’s open-source nature also introduces considerations related to maintenance and support. While the tool is freely available, organizations may need to invest time in customizing it to meet their specific requirements. This includes updating the model, refining keyword lists, or troubleshooting integration issues. RedHunt Labs provides documentation and community resources, but users should be prepared to engage with the open-source ecosystem to maximize the tool’s benefits.
The tool is designed to identify PII but does not automatically redact or secure detected information. Organizations must implement additional measures, such as data masking or secure storage protocols, to protect identified PII.
Finally, Octopii’s focus on image-based PII detection means it may not cover all types of sensitive data. For example, the tool does not analyze text documents, spreadsheets, or databases for PII. Organizations should complement Octopii with other security tools to achieve comprehensive data protection. RedHunt Labs’ NVADR, for instance, provides broader attack surface management capabilities, including the discovery of untracked assets and external vulnerabilities.