From 5c2da5e187a44abf78dbd82c59249b0c7d01d337 Mon Sep 17 00:00:00 2001 From: Zeecka <24873615+Zeecka@users.noreply.github.com> Date: Wed, 10 Dec 2025 23:46:11 +0100 Subject: [PATCH 01/19] Revise README for clarity and structure Updated README.md to enhance formatting, improve descriptions, and add sections. --- README.md | 224 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 159 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 1628e41..6f7f2eb 100644 --- a/README.md +++ b/README.md @@ -6,101 +6,195 @@ [![Website](https://img.shields.io/website?url=https%3A%2F%2Faperisolve.com)](https://aperisolve.com/) [![Rawsec's CyberSecurity Inventory](https://inventory.raw.pm/img/badges/Rawsec-inventoried-FF5050_flat.svg)](https://inventory.raw.pm/tools.html#Aperi'Solve) -

+

+ + Aperi'Solve screenshot + +

-Try it now: https://www.aperisolve.com +Try it now: **https://www.aperisolve.com** - Support Aperi'Solve: +Support Aperi'Solve: -## What is Aperi'Solve? -Aperi'Solve is a platform which performs steganalysis on images.
+--- -The platform uses *layer analysis*, "*zsteg*", "*steghide*", "*outguess*", "*exiftool*", "*binwalk*", "*foremost*" and "*strings*" for deeper steganography analysis. +Aperi'Solve is an open-source steganalysis web platform that performs automated analysis on images to detect and extract hidden data using common steganography tools and techniques. -

- -### Why Aperi'Solve? +Table of contents +- [Key features](#key-features) +- [Quick start (Docker)](#quick-start-docker) +- [Development](#development) +- [Adding a new analyzer](#adding-a-new-analyzer) +- [Configuration & environment variables](#configuration--environment-variables) +- [Architecture](#architecture) +- [Troubleshooting & tips](#troubleshooting--tips) +- [Roadmap](#roadmap) +- [Contributing](#contributing) -Aperi'Solve has been created in order to have an "easy to use" platform which performs common steganalysis tests such as LSB or `steghide`. The platform is also a quick alternative for people who were note able to install tools like `zsteg` (ruby gem) properly. +## Key features -### Features +- Visualize each bit layer (LSB and other layers) per image channel (R/G/B/Alpha). +- Browse and download each bit-layer image. +- Integrates and displays outputs from: + - zsteg (LSB text/data extraction) + - steghide (extraction with password) + - outguess (extraction with password) + - exiftool (metadata and geolocation) + - binwalk (embedded archives) + - foremost (carved files) + - pngcheck + - strings +- Worker queue architecture for offloading heavy/slow analyzers (Redis + background workers). +- Results stored for later browsing and download. -Aperi'Solve is based on Python3 with Flask and PIL module, the platform supports the most common image formats like`.png`, `.jpg`, `.gif`, `.bmp`, `.jpeg`, `.jfif`, `.jpe`, `.tiff`... +## Quick start (Docker) -The platform allows you to: -- **Visualize each bit layer** of each channel for a given image (ie. LSB of Red channel). -- **Browse** and **Download each bit layer image**. -- **Visualise `zsteg` information** such as text encoded on LSB -- **Download `steghide` files** using a defined password -- **Download `outguess` files** using a defined password -- **Visualise `exiftool` information** such as geolocation or author -- **Visualise `binwalk` information** -- **Download `binwalk` files** such as ZIP file in PNG headers -- **Download `foremost` files** such as ZIP file in PNG headers -- **Visualise `pngcheck` output** -- **Visualise `strings` output** +In case you want to host your own version of https://www.aperisolve.com/. -## Installation - -Even if Aperi'Solve is available at the URL https://www.aperisolve.com/, you can set up your own instance with the following command: +Recommended: Docker + Docker Compose. +Clone and start the full stack (production-like): ```bash git clone https://github.com/Zeecka/AperiSolve.git -cd aperisolve +cd AperiSolve docker compose up -d ``` -> Default will run on http://localhost:5000/ +Default: http://localhost:5000/ ## Development - -Aperi'Solve platform is a *Flask* web service (python 3.11+) with python workers performing analysis. -Jobs are stacked in a redis-queue, and image information is stored in a postgresql database. -All services run inside Docker containers. - -### Adding new analyzer - -Adding new analyzer is easy. - -1. Copy and adapt the [template_analyzer.py](aperisolve/analyzers/template_analyzer.py) file with your name, ie. "myanalyzer.py". -2. Add this analyzer to [workers.py](aperisolve/workers.py). - - Import your function `from .analyzers.analyzer import analyze_myanalyzer` - - Add the function to the `analyzers` variable, like other analyzers. -3. Add your analyzer name to `TOOL_ORDER` in [aperisolve.js](aperisolve/static/js/aperisolve.js). - -### Tips - -Here is a batch of useful commands. - +Development compose: ```bash -docker compose down -v # Remove the volume containings results -docker compose -f compose.dev.yml up # Start application in developpement mode -rm -rf aperisolve/results # Remove results from development mode -docker exec -it postgres psql -U aperiuser -d aperisolve # Get postgresql shell -docker exec -it aperisolve-web bash # Get a shell inside the running web app +# development environment (hot reload and local volumes) +docker compose -f compose.dev.yml up --build ``` -> Note, if you used [compose.dev.yml](compose.dev.yml), you must remove "results" when switching to [production Docker](compose.yml) setup. +Useful commands: +```bash +# Stop and remove containers, networks and volumes (results are stored in a volume) +docker compose down -v -### Code quality +# Enter web container shell +docker exec -it aperisolve-web bash -Python code follows the following linters: +# Enter Postgres shell (from host) +docker exec -it postgres psql -U aperiuser -d aperisolve +``` -- Black -- Flake8 (ignoring E203,E501,W503) -- Pylint (ignoring W0718,R0903,R0801) -- Mypy (ignoring unused-awaitable) +Note: If switching between dev and production compose files, remove the `results` directory or mounted volume to avoid conflicts: +```bash +rm -rf aperisolve/results +``` +### Adding a new analyzer -GitHub CI will alert in case of failure. +Adding a custom analyzer is straightforward: + +1. Create your analyzer file: + - Copy `aperisolve/analyzers/template_analyzer.py` -> `aperisolve/analyzers/myanalyzer.py` + - Implement function signature similar to: + ```python + # aperisolve/analyzers/myanalyzer.py + def analyze_myanalyzer(image_path: str, results_dir: str) -> dict: + """ + Perform analysis on image located at image_path. + Produce outputs in results_dir and return a result dict (json-serializable). + """ + # your analysis logic here + return {"name": "myanalyzer", "status": "ok", "outputs": [...]} + ``` + +2. Register the analyzer in the worker pipeline: + - Edit `aperisolve/workers.py`: + ```python + # import + from .analyzers.myanalyzer import analyze_myanalyzer + + # add to analyzers list (preserve the order) + analyzers = [ + analyze_zsteg, + analyze_steghide, + # ... + analyze_myanalyzer, + ] + ``` + +3. Add your analyzer to the UI order: + - Edit `aperisolve/static/js/aperisolve.js` and append `myanalyzer` to `TOOL_ORDER` so it appears in the frontend. + +4. Test locally: run the worker and submit jobs to ensure outputs are produced and displayed. + +Tips: +- Keep analyzers idempotent and write outputs to the provided `results_dir`. +- Return structured JSON so the frontend can render links/downloads automatically. + +## Configuration & environment variables + +Typical services: +- Web app (Flask) +- Workers (Python) +- Redis (RQ) +- PostgreSQL + +Main environment variables (examples): +- DATABASE_URL=postgresql://aperiuser:password@postgres:5432/aperisolve +- REDIS_URL=redis://redis:6379/0 +- SECRET_KEY=change_me +- FLASK_ENV=production/development + +If using Docker Compose, defaults are set in the compose files. For production deployments, set secure secrets via your orchestrator or environment. + +## Architecture + +- Flask web framework +- Background workers that run analyzers (queue via Redis) +- PostgreSQL stores image metadata and job statuses +- Docker-based deployment for isolation of analyzers and services + +This separation keeps heavy tools (binwalk, foremost, zsteg, etc.) isolated and avoids blocking the web worker. + +## Troubleshooting & tips + +- If analyzers don't produce output, check worker logs: + ```bash + docker compose logs -f aperisolve-worker + ``` +- To force re-analysis, remove results for the image (both file and in database) and re-submit the job. +- Ensure system packages needed by native tools (binwalk, foremost) are available in the analyzer containers or host image. ## Roadmap -- [ ] Zsteg extract / --all --> **Download `zsteg` files** such as mp3 encoded on LSB -- [ ] Test on mobile -- [ ] i18n -- [ ] Rootless analyzers ? +- [ ] zsteg: full extraction (--all) and download of discovered files (mp3, etc.) +- [ ] Mobile-friendly UI / test on mobile +- [ ] i18n (internationalization) +- [ ] Rootless / unprivileged analyzers +- [ ] Improve analyzer sandboxing (e.g., per-analyzer containers) + +## Contributing + +Contributions are welcome! Please: +1. Fork the repository +2. Create a feature branch +3. Open a pull request describing your change + +Please follow the code style and run linters before submitting. +The project adheres to: +- Black +- Flake8 (ignoring E203, E501, W503) +- Pylint (ignoring W0718, R0903, R0801) +- Mypy (ignoring unused-awaitable) + +CI will run these checks on each PR. + +## Security + +- If you discover a security issue, please report it privately to the repository owner instead of opening a public issue. + +## Credits + +Acknowledgements: +- Thanks to contributors and the open-source community for the tools integrated (zsteg, steghide, binwalk, foremost, exiftool). From a0ed892b60b7f71bb4cf9f053b97330b359bb55e Mon Sep 17 00:00:00 2001 From: Zeecka Date: Wed, 10 Dec 2025 23:47:10 +0100 Subject: [PATCH 02/19] Bump JS, add coffee link --- aperisolve/static/css/aperisolve.css | 10 ++++++++-- aperisolve/templates/base.html | 4 ++-- aperisolve/templates/footer.html | 5 +++++ 3 files changed, 15 insertions(+), 4 deletions(-) diff --git a/aperisolve/static/css/aperisolve.css b/aperisolve/static/css/aperisolve.css index 1d4c7be..4279412 100644 --- a/aperisolve/static/css/aperisolve.css +++ b/aperisolve/static/css/aperisolve.css @@ -330,7 +330,7 @@ td { #cheatsheet li::before { content: "\f054"; - font-family: "Font Awesome 6 Free"; + font-family: "Font Awesome 7 Free"; font-weight: 900; position: absolute; left: 0; @@ -397,11 +397,17 @@ footer { } } - footer a i { font-size: 32px; } +#coffee { + height: 32px; + display: inline-block; + vertical-align: middle; + width: auto; +} + /* ======== Utility ======== */ .glow-border { diff --git a/aperisolve/templates/base.html b/aperisolve/templates/base.html index 5ec42eb..292879c 100644 --- a/aperisolve/templates/base.html +++ b/aperisolve/templates/base.html @@ -6,8 +6,8 @@ Aperi'Solve - - + + diff --git a/aperisolve/templates/footer.html b/aperisolve/templates/footer.html index 0dad7a3..27bd7b4 100644 --- a/aperisolve/templates/footer.html +++ b/aperisolve/templates/footer.html @@ -1,4 +1,9 @@