AEGIS: Anonymous Encryption & Generative Image Shield

AEGIS is a production-grade, offline, high-performance image protection tool designed to shield personal portraits, illustrations, and digital artwork from unauthorized AI training, facial recognition indexing, and web scraping.

By combining PyTorch-based adversarial face cloaking with a custom compiled Rust DSP engine for invisible Y-channel watermarking, AEGIS acts as an imperceptible, cryptographically secure shield for your digital identity and intellectual property.

📌 Table of Contents

💡 AEGIS in a Nutshell
🚀 Key Features
📁 Repository Structure
🏗️ System Architecture
📖 Project Documentation
💻 System Requirements
📦 Installation Guide
🛡️ Commands & Usage Examples
🧪 Quality Assurance & Security Validation
⚖️ Ethics & Compliance
🔒 Security Policy & Threat Model
🔧 Troubleshooting
🤝 Contributing
📄 License & Trademarks
👥 Support & Feedback

💡 AEGIS in a Nutshell

Imagine you post a picture of your face or your artwork online. AI programs can automatically copy your image to train AI generators, and facial recognition systems can scan it to track you.

AEGIS is a tool that helps you protect your images from being used by these AI systems without your permission. It does this in two main ways:

A Confusing Trick for AI (Image Cloaking): AEGIS makes tiny, microscopic adjustments to your image. To a human, the image looks exactly the same. But to an AI, these tiny changes act like a visual optical illusion. When an AI tries to scan your face or copy your drawing style, it gets completely confused and sees only scrambled gibberish. This prevents AI models from learning from or copying your images.
An Invisible Ownership Stamp (Digital Watermark): AEGIS hides a unique digital signature deep inside the image. You cannot see this signature, but it is locked into the picture. Even if someone takes a screenshot, crops the image, or compresses it to post online, the signature remains. Using a matching digital key, you can always prove that you are the original owner of the image.

In short, AEGIS lets you post your photos and artwork online while making sure AI systems cannot read or steal them.

🚀 Key Features

Adversarial Face Cloaking: Leverages Projected Gradient Descent (PGD) optimization against deep learning models (MobileNet, ResNet) to disrupt facial feature extraction while keeping modifications visually imperceptible.
Production-Grade Asymmetric Cryptography (Ed25519): Replaced symmetric HMAC keys with Ed25519 asymmetric signatures. Owners sign watermarks with a private key, and external platforms/verifiers validate ownership integrity using the public key.
Copy-Attack Prevention (Perceptual aHash Binding): Binds the watermark payload to the cover image's structure using an Average Hash (aHash) fingerprint. Verifiers automatically detect and reject watermarks replayed or copied onto different images.
Mid-Frequency DSP Majority-Voting (Rust): Employs a compiled Rust core to perform Discrete Cosine Transform (DCT) block manipulations. Uses a secure ChaCha8 stream cipher for coordinate mapping and payload encryption, with block majority-voting for error-tolerant watermark extraction.
Ethical ID-Guard Compliance: Built-in multi-tiered forensic analysis scans for passports (MRZ fields), visual centroids, and US Driver's Licenses (PDF417 barcodes) to block tool abuse on government identity assets.

📁 Repository Structure

The repository has been structured to cleanly separate production source code from the validation/test databases to facilitate integration:

├── aegis_kernel/            # Rust DSP Core Kernel source code
├── src/                     # Python command-line entrypoints & forensic pipelines
│   ├── aegis_core/          # Core modules (analyzer.py, cloaking.py)
│   └── cli.py               # Main CLI orchestrator
├── testing/                 # Consolidation of all test-based frameworks
│   ├── test_scripts/        # 14 isolated validation suites
│   ├── logs/                # Audit results & code coverage JSON outputs
│   ├── aegis_testing_temp/  # Raw test dataset assets
│   ├── run_audit.py         # Complete system validator & compiler
│   └── audit_report_production.md  # Final system QA report
├── install_libraries.py     # Hardware-aware deep learning installer
├── requirements.txt         # Production package dependencies
├── REPORT.md                # Technical Report
├── README.md                # README file
├── LICENSE                  # License file
├── SECURITY.md              # Security Policy
├── USAGE_WARNINGS.md        # Usage Warnings & Best Practices
├── ETHICS.md                # Ethics & Compliance
└── HOW_TO_USE.md            # How to Use Guide

🏗️ System Architecture

AEGIS is built as a modular Python-Rust hybrid pipeline. High-level orchestrations, compliance gatekeeping (ID-Guard), and deep neural network cloaking (Projected Gradient Descent) are handled in Python to leverage the rich machine learning ecosystem (PyTorch). Computationally intensive pixel-level and block-level transformations, asymmetric watermarking, and randomized coordinate shuffling are offloaded to a native compiled Rust library (aegis_kernel) bound via PyO3.

The comprehensive diagram below details the end-to-end execution flow of both the Protection Pipeline (cli.py protect) and the Verification/Extraction Pipeline (cli.py verify):

flowchart TB
    %% Core Styling
    classDef python fill:#3572A5,stroke:#fff,stroke-width:2px,color:#fff;
    classDef rust fill:#dea584,stroke:#fff,stroke-width:2px,color:#333;
    classDef file fill:#f5f5f5,stroke:#333,stroke-width:1px,color:#333;
    classDef decision fill:#fff2cc,stroke:#d6b656,stroke-width:2px,color:#333;

    subgraph UserInterface ["1. User CLI Entrypoint & Keys"]
        CLI["cli.py (Command Parser)"]:::python
        Keys["PEM Keypair (Ed25519)"]:::file
        Seed["SHA-256 Seed Generator"]:::python
        CLI -->|Loads Keys| Keys
        Keys -->|Parse Seed| Seed
    end

    subgraph Gatekeeper ["2. Forensic Compliance (ID-Guard)"]
        ImgIn["Source Image"]:::file
        Analyzer["ImageAnalyzer (analyzer.py)"]:::python
        OCR["Tesseract OCR Engine"]:::python
        MRZ["MRZ Regex Matcher"]:::python
        Barcode["PDF417 Barcode Decoder"]:::python
        FlagDecision{"ID Detected?"}:::decision

        ImgIn --> Analyzer
        Analyzer --> OCR
        Analyzer --> MRZ
        Analyzer --> Barcode
        OCR & MRZ & Barcode --> FlagDecision
        FlagDecision -->|Yes| Flagged["Block / Request Override"]:::decision
        FlagDecision -->|No| Clean["Proceed to Cloaking"]:::python
    end

    subgraph Cloaking ["3. Adversarial Cloaking Engine (PyTorch)"]
        Cloaker["PgdCloaker (cloaking.py)"]:::python
        Surrogate["Surrogate CNN Models (MobileNetV2 / ResNet18)"]:::python
        PGD["Projected Gradient Descent (PGD Loop, L-inf budget)"]:::python
        CloakedImg["Intermediate Cloaked Tensor"]:::python

        Clean --> Cloaker
        Cloaker --> Surrogate
        Cloaker --> PGD
        Surrogate --> PGD
        PGD --> CloakedImg
    end

    subgraph RustDSP ["4. High-Performance DSP Kernel (aegis_kernel)"]
        RGB2YCbCr["RGB to YCbCr Conversion"]:::python
        YChannel["Extract Y (Luminance) Channel"]:::python
        BlockSplit["8x8 Block Grid Segmentation"]:::rust
        ChaChaShuffle["Block Coordinate Shuffling (ChaCha8Rng Key-Seeded)"]:::rust
        DCT2D["2D Discrete Cosine Transform (DCT)"]:::rust
        
        subgraph Perturb ["Frequency Domain Manipulation"]
            QIM["Quantization Index Modulation (QIM Watermarking)"]:::rust
            FreqNoise["Mid-Frequency Noise Insertion"]:::rust
            PayloadSign["Ed25519 Payload Signer (JSON + aHash Signature)"]:::python
        end

        IDCT2D["2D Inverse DCT (IDCT)"]:::rust
        Unshuffle["Coordinate Unshuffling"]:::rust
        MergeCh["Merge Channels & YCbCr to RGB"]:::python

        CloakedImg --> RGB2YCbCr
        RGB2YCbCr --> YChannel
        YChannel --> BlockSplit
        BlockSplit --> ChaChaShuffle
        ChaChaShuffle --> DCT2D
        DCT2D --> QIM & FreqNoise
        PayloadSign -->|Wrapped Payload| QIM
        QIM & FreqNoise --> IDCT2D
        IDCT2D --> Unshuffle
        Unshuffle --> MergeCh
    end

    subgraph Verification ["5. Watermark Verification & Copy-Attack Detection"]
        ProtImg["Protected Image (.png)"]:::file
        DetectWM["aegis_kernel.detect_watermark_py"]:::rust
        JSONParse["Payload Parser & Verification"]:::python
        EdVerify["Ed25519 Signature Verifier"]:::python
        aHashVerify["Perceptual aHash Evaluator"]:::python
        HammingDist{"Hamming Distance > 10?"}:::decision
        
        ProtImg --> DetectWM
        DetectWM --> JSONParse
        JSONParse --> EdVerify
        JSONParse --> aHashVerify
        aHashVerify --> HammingDist
        
        HammingDist -->|Yes| CopyWarning["WARNING: Copy/Replay Attack!"]:::decision
        HammingDist -->|No| Success["Watermark Verified Successfully"]:::python
    end

    MergeCh -->|Saves Output| ProtImg

📖 Project Documentation

To help you navigate the AEGIS project and understand all aspects of deployment, security, ethics, and testing, the following dedicated documentation guides are available:

REPORT.md (Technical & Audit Report): Contains detailed information about the system architecture, mathematical & cryptographic foundations (such as QIM watermarking and aHash binding), branch coverage validation, and performance benchmarks.
HOW_TO_USE.md (Operations & User Guide): A comprehensive, step-by-step walkthrough of installing AEGIS, setting up the hardware-optimized Python environment, building the Rust kernel, and using all CLI features (keygen, protect, verify, and audit).
USAGE_WARNINGS.md (Usage Warnings & Best Practices): Crucial guide explaining the physical limits of cloaking and watermarking, recommendations for preserving watermark integrity (avoiding double-compression, scaling recommendations), and how to maximize protection.
ETHICS.md (Ethics & Compliance): Outlines the Acceptable Use Policy, legal mandates, and technical implementations of the automated ID-Guard scanner designed to prevent abuse.
SECURITY.md (Security Policy & Threat Model): Details the cryptographic boundaries of AEGIS, active threat models, security audits, key management practices, and instructions for reporting vulnerabilities.

💻 System Requirements

Because AEGIS utilizes PyTorch for adversarial face cloaking and running visual classifiers, the recommended system configurations are:

Operating System: Linux (tested on Ubuntu, Fedora, Arch), macOS (Intel & Apple Silicon), or Windows 10/11.
Python Version: Python 3.10, 3.11, or 3.12 (highly recommended for stability).
Rust Toolchain: Cargo/Rustc 1.70+ (required to compile the high-performance DSP engine aegis_kernel).
Hardware Acceleration (Highly Recommended):
- NVIDIA GPU: CUDA 11.8+ compatibility (drastically speeds up cloaking operations).
- Apple Silicon (M1/M2/M3/M4): Native Metal Performance Shaders (MPS) acceleration.
- CPU Mode: Supported, but processing time will be significantly longer.

📦 Installation Guide

Prerequisites

Python 3.10+ (Try to use Python 3.10, 3.11 & 3.12 as they are most stable in these versions)
Rust toolchain (cargo, rustc)

1. Setup Virtual Environment

git clone https://github.com/MSpider3/AEGIS.git
cd AEGIS
python3 -m venv venv
# Windows
source venv/Scripts/activate
# Linux/macOS
source venv/bin/activate

2. Run the Smart Installer

AEGIS detects your hardware (NVIDIA CUDA, Apple Silicon Metal, or CPU) to configure the optimal PyTorch stack:

venv/bin/python install_libraries.py

3. Compile the Rust DSP Kernel

Install Maturin and compile the high-performance bindings:

VIRTUAL_ENV=venv venv/bin/pip install maturin
VIRTUAL_ENV=venv venv/bin/maturin develop --manifest-path aegis_kernel/Cargo.toml --features python

4. Alternative: Run via Podman (Containerized)

If you prefer to run AEGIS in an isolated environment without installing Python, Rust, or system libraries (like Tesseract) on your host, you can build and run it using Podman:

# Build the container image
podman build -t aegis:latest .

# Run the validation/audit suite to verify the installation
podman run --rm -it --entrypoint python aegis:latest testing/run_audit.py

For detailed instructions on generating keys and protecting/verifying images using volume mounts, see HOW_TO_USE.md.

🛡️ Commands & Usage Examples

Run all commands within the activated virtual environment. Use PYTHONPATH=src venv/bin/python src/cli.py --help for full flags.

1. Generating a Keypair (`keygen`)

Generate an Ed25519 PEM private/public keypair:

PYTHONPATH=src venv/bin/python src/cli.py keygen -o keys/

Generates keys/aegis_private.pem (private signing key) and keys/aegis_public.pem (public verification key).

2. Protecting an Image (`protect`)

Apply protection modes. Always output to .png to avoid compression degradation:

PYTHONPATH=src venv/bin/python src/cli.py protect \
  -i input.jpg \
  -o protected.png \
  -m hybrid \
  -k keys/aegis_private.pem \
  -w '{"author": "Jane Doe", "license": "CC-BY-NC"}' \
  --watermark-engine qim-frequency \
  --block-size 16 \
  --robustness-level aggressive \
  --accept-ethics

Modes (-m): hybrid (cloaking + watermark + noise), face (cloaking only), art (noise only).
Watermark Options:
- --watermark-engine: Engine type (legacy or qim-frequency, default: qim-frequency).
- --block-size: Shuffling grid block size (8, 16, 32, 64, default: 8).
- --robustness-level: Dynamic delta scaling profile (standard or aggressive, default: standard).

3. Verifying and Detecting Copy-Attacks (`verify`)

Extract watermark ownership and verify perceptual bindings:

PYTHONPATH=src venv/bin/python src/cli.py verify \
  -i protected.png \
  -k keys/aegis_public.pem \
  --watermark-engine qim-frequency \
  --block-size 16 \
  --robustness-level aggressive

🧪 Quality Assurance & Security Validation

A suite of 14 validation files checks for crash recovery, fuzzing, dataset poisoning, and performance:

# Run the complete test suite and generate the validation report
PYTHONPATH=src venv/bin/python testing/run_audit.py

Upon successful completion, the test suite generates an executive audit summary containing detailed metrics under testing/audit_report_production.md.

🔧 Troubleshooting

"ModuleNotFoundError: No module named 'aegis_kernel'"

Fix: Ensure your virtual environment is active and run the following command:

VIRTUAL_ENV=venv venv/bin/maturin develop --manifest-path aegis_kernel/Cargo.toml --features python

"Error: Rust toolchain not found"

Fix: Ensure Rust is installed on your system. Refer to the Rust Installation Guide for instructions.

"Error: No such file or directory: 'keys/aegis_private.pem'"

Fix: Generate a keypair using the keygen command:

PYTHONPATH=src venv/bin/python src/cli.py keygen -o keys/

"TypeError: can only concatenate str (not "NoneType") to str"

Fix: Run the install_libraries.py script to ensure all required libraries are installed:
```
venv/bin/python install_libraries.py
```

"Error: No such file or directory: 'protected.png'"

Fix: Ensure that you are running the command from the root directory of the AEGIS repository:

cd AEGIS
PYTHONPATH=src venv/bin/python src/cli.py verify \
  -i protected.png \
  -k keys/aegis_public.pem

"Error: ID-Guard activated: Passport detected!" when running protect command

Fix: Use the --accept-ethics flag to explicitly consent to the terms of service. This bypasses the ID-Guard check for testing purposes:

PYTHONPATH=src venv/bin/python src/cli.py protect \
  -i input.jpg \
  -o protected.png \
  -m hybrid \
  -k keys/aegis_private.pem \
  -w '{"author": "Jane Doe", "license": "CC-BY-NC"}' \
  --accept-ethics

⚖️ Ethics & Compliance

AEGIS is built to protect personal privacy and individual content rights. To prevent misuse, the engine contains ID-Guard, an automated compliance checking system that flags and blocks processing of government identification documents (such as passports and driver's licenses).

Before using AEGIS, please review our full guidelines in ETHICS.md.

🔒 Security Policy & Threat Model

AEGIS uses Ed25519 asymmetric cryptography to sign watermarks and ChaCha8 stream encryption to secure payload metadata. Structural image binding (aHash) is used to detect copy-and-paste forgery/replay attacks.

For security reports, vulnerability disclosure procedures, and key security practices, please read SECURITY.md and Usage Warnings & Best Practices (USAGE_WARNINGS.md).

🤝 Contributing

We welcome contributions from developers, security researchers, and artists! To contribute:

Check the Troubleshooting section for common issues.
Fork the repository and create your feature branch.
Run the validation suite (python testing/run_audit.py) to verify all checks pass.
Open a Pull Request with a clear description of your changes.

📄 License & Trademarks

License

This project is open-source and licensed under the GNU General Public License v3.0 (GPLv3).

Trademark Policy

The name AEGIS, its logos, branding, and assets are protected trade names and trademarks of this project.

While you are free to fork the codebase, modify it, and distribute it under the terms of the GPLv3, you cannot use the name "AEGIS" or the official project logos for any commercial forks, redistributed versions, or hosted services without explicit prior written permission.
Any redistributed version or commercial fork must be renamed to a distinct, non-confusing name, and all references/logos associated with "AEGIS" as a brand must be removed.

👥 Support & Feedback

For reporting issues, suggestions, or feature requests, please open an issue on the GitHub repository.

Name		Name	Last commit message	Last commit date
aegis_kernel		aegis_kernel
src		src
testing		testing
.gitignore		.gitignore
Containerfile		Containerfile
ETHICS.md		ETHICS.md
HOW_TO_USE.md		HOW_TO_USE.md
LICENSE		LICENSE
README.md		README.md
REPORT.md		REPORT.md
SECURITY.md		SECURITY.md
USAGE_WARNINGS.md		USAGE_WARNINGS.md
install_libraries.py		install_libraries.py
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation