🔍 VeriScan: Web Application for Digital Image Forensics

VeriScan: Aplicação Web e Inteligência Computacional Aplicada à Análise Forense de Imagens

📄 Table of Contents / Sumário

English
Português (Brasil)
Academic Context & Credits

🇺🇸 English

🎯 Overview & Purpose

VeriScan is a full-stack web application designed for digital image forensic analysis and visual comparison. Built under an academic research initiative, the application allows users to upload one or two images, run the official computational tests (comparacao, ela, and gradiente), and inspect the resulting heatmaps/outputs directly from an intuitive web interface.

The platform links a modern web stack (Next.js & Express) with a local Python environment equipped with deep learning models to support digital forensics and forgery analysis.

⚙️ Key Operations

VeriScan currently supports three primary forensic operations:

comparacao (Comparison): Compares the ELA and Gradient verdicts for a single uploaded image in one consolidated report.
ela (Error Level Analysis): Analyzes JPEG compression artifacts across different levels to highlight modified regions.
gradiente (Gradient): Evaluates image intensity gradients to identify structural edge anomalies and tampered areas.

🔬 System Architecture & Flow

The project consists of three core components:

frontend/: Next.js (TypeScript) interface offering drag-and-drop file uploads, image previews, operation selection, and interactive result rendering.
backend/: Node.js REST API using Express and Multer to handle temporary uploads, spawn child Python processes, serve output images, and clean up temporary storage.
python/: Python virtual environment (.venv) hosting trained model weights (cnndetection_model.pth) and the official execution scripts (pipeline_comparacao.py, pipeline_ela.py, and pipeline_gradiente.py).

[User] ──(Drag & Drop / Select 1 or 2 Images)──► [Next.js Frontend]
                                                  │
                                           (POST /api/upload)
                                                  ▼
                                        [Express Backend API] ──(Saves to backend/tmp/uploads)
                                                  │
                                           (POST /api/process)
                                                  ▼
                                      [Python Pipeline Process]
                     (Runs pipeline_comparacao.py / pipeline_ela.py / pipeline_gradiente.py)
                                                  │
                                     (Outputs to backend/tmp/results)
                                                  ▼
[User] ◄──(Displays Image & Summary)─── [Next.js Frontend]

Detailed Execution Workflow:

The user selects or drags one or two images into the web UI (frontend/src/app/_components/inicial.tsx).
The frontend sends the selected images to POST /api/upload.
The backend validates and temporarily stores the images in backend/tmp/uploads.
The user selects an operation (comparacao, ela, or gradiente) and triggers POST /api/process.
The Express backend spawns the corresponding official script via python/.venv/bin/python.
The resulting visual output is generated in backend/tmp/results and served back to the UI.

🖼️ Screenshots & Results

Home / Upload Interface

Example Result — Comparison ELA x Gradiente (`ela x gradiente`)

Example Result — Error Level Analysis (`ela`)

Example Result — Gradient (`gradiente`)

📁 Project Structure

VeriScan/
├── frontend/                     # Next.js Frontend Application
│   ├── src/
│   │   └── app/
│   │       ├── page.tsx          # Main entry route
│   │       ├── layout.tsx        # Root layout & app metadata
│   │       ├── globals.css       # Global styles & CSS variables
│   │       └── _components/
│   │           └── inicial.tsx   # Core UI (drag & drop, upload, test execution)
│   ├── next.config.ts            # Rewrites (/api/* -> http://localhost:3001)
│   └── package.json
│
├── backend/                      # Node.js/Express REST API
│   ├── src/
│   │   ├── index.js              # Express server setup
│   │   ├── routes.js             # API route definitions & child process logic
│   │   └── config/
│   │       └── multer.js         # Multer upload & image MIME validation
│   ├── tmp/                      # Temporary storage
│   │   ├── uploads/              # Uploaded input images
│   │   └── results/              # Processed output images
│   └── package.json
│
└── python/                       # Machine Learning & Forensic Execution
    ├── .venv/                    # Local Python virtual environment
    ├── cnndetection_model.pth    # PyTorch model weights artifact
    ├── pipeline_comparacao.py    # Official comparison pipeline
    ├── pipeline_ela.py           # Official ELA pipeline
    └── pipeline_gradiente.py     # Official gradient pipeline

🔌 API Endpoints

Method	Endpoint	Description
`POST`	`/api/upload`	Uploads one or two target images (`jpeg`, `png`, `webp`, `bmp`, `tiff`).
`POST`	`/api/process`	Executes the forensic pipeline (`fileNames` array & `operation`).
`GET`	`/api/uploads/:filename`	Serves an uploaded input image.
`GET`	`/api/results/:filename`	Serves a processed result/heatmap image.
`DELETE`	`/api/cleanup`	Removes temporary files from `backend/tmp/uploads` and `backend/tmp/results`.

🚀 How to Run

Prerequisites

Node.js: v18.0.0 or higher
npm: Node package manager
Python: v3.10 or higher (for local pipeline execution)

1. Start the Backend API

cd backend
npm install
npm run dev

The Express server will launch on http://localhost:3001.

2. Configure the Python Environment

Ensure your virtual environment and dependencies are set up inside python/:

cd python
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install torch torchvision opencv-python pillow numpy matplotlib

Note: The backend executes one of python/pipeline_comparacao.py, python/pipeline_ela.py, or python/pipeline_gradiente.py using --input and --output-dir.

3. Start the Frontend Application

cd frontend
npm install
npm run dev

Open http://localhost:3000 in your browser. Next.js automatically rewrites /api/* to http://localhost:3001.

🇧🇷 Português (Brasil)

🎯 Visão Geral e Propósito

O VeriScan é uma aplicação web full-stack desenvolvida para análise forense digital e comparação de imagens. Construído em contexto de pesquisa acadêmica, o sistema permite que o usuário envie uma ou duas imagens, execute as pipelines oficiais (comparacao, ela e gradiente) e visualize os mapas de calor e resultados processados diretamente na interface web.

A plataforma integra uma stack moderna (Next.js e Express) a um ambiente local em Python equipado com modelos de aprendizado profundo para apoiar a investigação de fraudes e manipulações visuais.

⚙️ Operações Suportadas

Atualmente, o VeriScan suporta três operações principais de análise:

comparacao: Consolida os vereditos de ELA e Gradiente sobre uma imagem em um único relatório.
ela (Error Level Analysis): Analisa as diferenças nos níveis de compressão JPEG para identificar áreas modificadas.
gradiente: Avalia variações na intensidade da imagem para identificar anomalias nas bordas e estruturas da cena.

🔬 Arquitetura do Sistema e Fluxo

O projeto está dividido em três módulos principais:

frontend/: Interface em Next.js (TypeScript) com drag-and-drop, preview de imagens, seleção de exames e exibição interativa de resultados.
backend/: API REST em Node.js com Express e Multer. Recebe os uploads, gerencia os arquivos temporários, dispara o processo Python e entrega os arquivos processados.
python/: Ambiente virtual Python (.venv) contendo os pesos do modelo pré-treinado (cnndetection_model.pth) e os scripts oficiais (pipeline_comparacao.py, pipeline_ela.py e pipeline_gradiente.py).

[Usuário] ──(Arrasta / Seleciona 1 ou 2 Imagens)──► [Frontend Next.js]
                                                      │
                                               (POST /api/upload)
                                                      ▼
                                            [Backend Express API] ──(Salva em backend/tmp/uploads)
                                                      │
                                               (POST /api/process)
                                                      ▼
                                           [Execução do Pipeline Python]
                    (Roda pipeline_comparacao.py / pipeline_ela.py / pipeline_gradiente.py)
                                                      │
                                         (Salva em backend/tmp/results)
                                                      ▼
[Usuário] ◄──(Exibe Imagem & Resumo)────── [Frontend Next.js]

Fluxo Detalhado do Código:

O usuário seleciona ou arrasta uma ou duas imagens na interface (frontend/src/app/_components/inicial.tsx).
O frontend envia os arquivos para POST /api/upload.
O backend armazena as imagens temporariamente na pasta backend/tmp/uploads.
O usuário escolhe a operação desejada (comparacao, ela ou gradiente) e aciona a requisição POST /api/process.
O Express dispara o script oficial correspondente utilizando o executável python/.venv/bin/python.
A imagem resultante é salva em backend/tmp/results e enviada para exibição na tela do usuário.

🖼️ Captura de Tela & Resultados

Inicial / Upload Interface

Exemplo de Resultado — Comparação ELA x Gradiente (`comparacao ela x gradiente`)

Exemplo de Resultado — Error Level Analysis (`ela`)

Exemplo de Resultado — Gradiente (`gradiente`)

📁 Estrutura do Projeto

VeriScan/
├── frontend/                     # Aplicação Web Next.js
│   ├── src/
│   │   └── app/
│   │       ├── page.tsx          # Rota principal
│   │       ├── layout.tsx        # Layout raiz e metadados
│   │       ├── globals.css       # Estilos globais e variáveis de tema
│   │       └── _components/
│   │           └── inicial.tsx   # Componente da interface (upload, testes e preview)
│   ├── next.config.ts            # Redirecionamento de rotas (/api/* -> localhost:3001)
│   └── package.json
│
├── backend/                      # API REST em Node.js / Express
│   ├── src/
│   │   ├── index.js              # Inicialização do servidor Express
│   │   ├── routes.js             # Rotas e chamadas do processo Python
│   │   └── config/
│   │       └── multer.js         # Validação de tipos MIME e salvamento de uploads
│   ├── tmp/                      # Diretório de armazenamento temporário
│   │   ├── uploads/              # Imagens enviadas pelo usuário
│   │   └── results/              # Resultados gerados pela análise
│   └── package.json
│
└── python/                       # Pipeline Forense em Python
    ├── .venv/                    # Ambiente virtual Python local
    ├── cnndetection_model.pth    # Pesos do modelo de aprendizado profundo
    ├── pipeline_comparacao.py    # Pipeline oficial de comparação
    ├── pipeline_ela.py           # Pipeline oficial ELA
    └── pipeline_gradiente.py     # Pipeline oficial de gradiente

🔌 Endpoints da API

Método	Endpoint	Descrição
`POST`	`/api/upload`	Recebe uma ou duas imagens (`jpeg`, `png`, `webp`, `bmp`, `tiff`).
`POST`	`/api/process`	Executa o pipeline de análise recebendo o array `fileNames` e a `operation`.
`GET`	`/api/uploads/:filename`	Entrega uma imagem original enviada.
`GET`	`/api/results/:filename`	Entrega o arquivo de resultado/mapa de calor gerado.
`DELETE`	`/api/cleanup`	Remove os arquivos temporários de `backend/tmp/uploads` e `backend/tmp/results`.

🚀 Como Rodar o Projeto

Pré-requisitos

Node.js: Versão 18.0 ou superior
npm: Gerenciador de pacotes do Node
Python: Versão 3.10 ou superior

1. Configurando e Rodando o Backend

cd backend
npm install
npm run dev

O servidor Express estará ativo em http://localhost:3001.

2. Configurando o Ambiente Python

Certifique-se de configurar o ambiente virtual e instalar as dependências na pasta python/:

cd python
python3 -m venv .venv
source .venv/bin/activate  # No Windows: .venv\Scripts\activate
pip install torch torchvision opencv-python pillow numpy matplotlib

Aviso: O backend invoca python/pipeline_comparacao.py, python/pipeline_ela.py ou python/pipeline_gradiente.py com os argumentos --input e --output-dir.

3. Configurando e Rodando o Frontend

cd frontend
npm install
npm run dev

Acesse http://localhost:3000 no seu navegador. O Next.js utiliza o rewrite configurado em next.config.ts para redirecionar /api/* automaticamente para a porta 3001.

💡 Observações Importantes

Limpeza de Temporários: Ao fechar ou sair da página no frontend, o sistema envia uma requisição automática para DELETE /api/cleanup, mantendo o servidor limpo.
Formatos de Arquivo: O Multer aceita exclusivamente os tipos image/jpeg, image/png, image/webp, image/bmp e image/tiff.

🏛 Academic Context & Credits

Institution: Instituto Federal do Espírito Santo (Ifes) - Campus Serra
Program: Programa de Iniciação Científica, Tecnológica e de Inovação (PICTI)
Research Group: NERA (Núcleo de Estudos em Robótica e Automação)
Project Title: VeriScan: Inteligência Computacional Aplicada à Detecção de Imagens Manipuladas

Name		Name	Last commit message	Last commit date
backend		backend
docs/images		docs/images
frontend		frontend
python		python
.gitignore		.gitignore
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation