DEV Community

Cover image for Aeglis Intelligence: Building an Open-Source API-First Security Analysis Backend
Shubham
Shubham

Posted on Originally published at github.com

Aeglis Intelligence: Building an Open-Source API-First Security Analysis Backend

#python #fastapi #cybersecurity #opensource

Aeglis Intelligence: Building an Open-Source API-First Security Analysis Backend

Modern threats rarely arrive in a single format. A phishing attempt may look like a shortened URL, a fake payment request, a malicious document, an infected archive, or an Android application that behaves differently from what it promises.

This is the problem I wanted to work on with Aeglis Intelligence: an open-source cybersecurity and risk-analysis backend that brings multiple detection workflows behind one Python and FastAPI-based service.

Repository: github.com/Shubhamorigin/Aeglis-Intelligence

What Is Aeglis Intelligence?

Aeglis Intelligence is built for applications, developers, and security-focused teams that need to inspect suspicious content and receive useful risk intelligence through APIs.

It can be used to analyze:

  • Suspicious URLs and phishing pages
  • Scam messages and risky text content
  • Office documents and PDFs
  • ZIP archives and scripts
  • JavaScript, SVG files and images
  • Malware patterns
  • Android APKs
  • Domain reputation and external threat signals

The goal is not only to return a binary safe-or-unsafe answer. Aeglis is designed to combine multiple signals and produce a practical verdict, risk score, and supporting explanation that can be used by a dashboard, consumer application, moderation system, or automated security workflow.

Why Multiple Signals Matter

A single security check is often not enough. A domain may be new but not malicious. A file may contain an unusual pattern without being harmful. A URL may look normal while redirecting users through a phishing flow.

Aeglis approaches analysis as a layered process. Depending on the input, it can combine:

  • Local security rules and heuristics
  • Text and input classification
  • Domain intelligence and RDAP checks
  • Static file inspection
  • Browser-based URL analysis
  • Reputation lookups through external services
  • AI-assisted risk classification

This layered approach makes it possible to use fast local checks where they are enough and bring in deeper analysis when the input deserves more investigation.

The Architecture

Aeglis is organized into separate modules so that API handling, detection engines, storage, authentication, and result delivery do not become one large block of application logic.

API Layer

The central application lives in main.py and is built with FastAPI. It coordinates public routes, authenticated consumer routes, developer APIs, billing workflows, support tickets, and webhook configuration.

The service includes rate limiting through SlowAPI, CORS middleware, JWT-based authentication for protected consumer actions, and API-key validation for developer endpoints.

Detection Layer

The detection responsibilities are split across specialized modules:

  • core_engine.py handles domain intelligence, whitelist checks, Redis access, and high-level risk assessment.
  • scanner_engine.py performs deep analysis of documents, archives, scripts, JavaScript, SVG, PDFs, APKs, and images.
  • scan_url.py handles browser-based URL detonation and phishing checks.
  • input_classifier.py classifies suspicious text and payment-related scam patterns.
  • security_engine.py generates API keys and stores hashes rather than relying on plain-text key storage.

This separation makes it easier to improve one analysis path without rewriting the rest of the backend.

Data and Storage Layer

Supabase provides the main persistence and authentication layer. The project uses it for:

  • User authentication and profiles
  • API keys and usage plans
  • Scan history and API logs
  • Support tickets
  • Billing records
  • Developer webhook configuration

Redis can be used as a cache for domain results and scan information. For one-off file processing, the application uses a local temp_uploads/ directory at runtime.

Integration Layer

Aeglis can connect to external services for additional signals and analysis, including:

  • VirusTotal for hash reputation
  • AlienVault for threat intelligence lookups
  • WebRisk for malicious URL checks
  • Groq for AI-assisted classification and verdict generation
  • Playwright for browser automation and URL analysis

External services are treated as supporting signals. The application also has local logic so that the system can continue using fallback paths when optional services such as Redis are unavailable.

Consumer and Developer Workflows

Aeglis supports two main types of users.

Consumer Applications

A consumer safety application can send text, URLs, downloaded content, or uploaded files for analysis. The response can then be shown as a warning, a risk score, or a more detailed explanation before a user opens a link or file.

The backend includes routes for signup, login, Google authentication flows, text scanning, deep file scanning, scan history, profile data, and history management.

Developer and B2B Integrations

Developers can use protected endpoints to add security analysis to their own products. The developer workflow is based on API keys, quotas, structured scan requests, and optional webhooks for asynchronous result delivery.

The current developer-oriented routes include:

  • POST /v3/api/scan
  • POST /v3/api/deep-scan
  • POST /v3/dashboard/generate-key
  • POST /v3/dashboard/webhook
  • GET /v3/dashboard/api-logs
  • GET /v3/dashboard/api-data
  • GET /v3/dashboard/reports

A developer API key is sent through the Authorization header:

Authorization: Bearer sk_live_xxx
Enter fullscreen mode Exit fullscreen mode

A text scan can be sent as JSON:

POST /v3/api/scan
Content-Type: application/json
Authorization: Bearer sk_live_xxx
Enter fullscreen mode Exit fullscreen mode 
{
  "input_text": "Check this suspicious link: https://example.com",
  "end_user_id": "customer-123"
}
Enter fullscreen mode Exit fullscreen mode

This structure allows an integrating product to associate scans with its own end users without exposing the internal authentication model of Aeglis.

Webhooks for Automation

Polling for every scan result is not always the best integration pattern. Aeglis includes webhook configuration and dispatch support so that developer systems can receive results after a scan is completed.

A typical workflow looks like this:

  1. A developer creates an API key.
  2. The application sends text or a file for analysis.
  3. Aeglis processes the input through the relevant detection engines.
  4. The result is stored and returned through the API or delivered to a configured webhook.
  5. The integrating application uses the verdict and risk context in its own workflow.

This can be useful for moderation queues, security dashboards, customer support tooling, download protection, or automated incident workflows.

Database Setup

The repository includes a complete Supabase schema in database.sql.

The schema supports the tables and database objects required by the backend, including profiles, API keys, API logs, scans, support tickets, and billing records. To set up a development environment:

  1. Create a Supabase project.
  2. Open the Supabase SQL Editor.
  3. Copy the contents of database.sql into the editor.
  4. Run the script.
  5. Add the project URL and keys to the local environment file.

The application also references a storage bucket named cold-storage for exported reports and archival files.

Running the Project Locally

Clone the repository and move into the project directory:

git clone https://github.com/Shubhamorigin/Aeglis-Intelligence.git
cd Aeglis-Intelligence
Enter fullscreen mode Exit fullscreen mode

Create a virtual environment if you want to isolate the project dependencies:

python -m venv .venv
Enter fullscreen mode Exit fullscreen mode

Activate it on Windows:

.venv\Scripts\Activate.ps1
Enter fullscreen mode Exit fullscreen mode

On macOS or Linux:

source .venv/bin/activate
Enter fullscreen mode Exit fullscreen mode

Install the dependencies:

pip install -r requirements.txt
Enter fullscreen mode Exit fullscreen mode

For browser-based URL analysis, install the Playwright browsers:

python -m playwright install
Enter fullscreen mode Exit fullscreen mode

Start the application with either command:

python main.py
Enter fullscreen mode Exit fullscreen mode

or:

uvicorn main:app --host 0.0.0.0 --port 8000 --reload
Enter fullscreen mode Exit fullscreen mode

Environment Variables

Create a .env file in the project root. The required integrations use variables similar to these:

ALIENVAULT_API_KEY=your_alienvault_api_key
GROQ_API_KEY=your_groq_api_key
SB_ANON_KEY=your_supabase_anon_key
SB_API_URL=your_supabase_api_url
SB_SECRET_KEY=your_supabase_secret_key
VIRUSTOTAL_API_KEY=your_virustotal_api_key
WEB_RISK_API_KEY=your_web_risk_api_key
REDIS_URL=your_redis_url
Enter fullscreen mode Exit fullscreen mode

Some integrations are optional during local development. Redis can fall back to local or Supabase-backed paths when it is not available, but a properly configured Redis instance is recommended for better performance.

Never commit real API keys, service-role keys, or database credentials to the repository. Keep .env outside source control and use a secret manager for production deployments.

Security Considerations

A security-analysis service must protect both the service itself and the data it processes. Aeglis includes several controls that help establish that boundary:

  • Rate limits for public and authenticated routes
  • JWT validation for protected consumer actions
  • API-key validation for developer endpoints
  • Hashing for stored API keys
  • CORS and origin validation
  • File upload size limits, including a 50 MB application limit
  • Temporary file handling for uploaded content
  • Webhook configuration and secret support

Production deployments should still restrict CORS origins, enforce HTTPS, protect Redis and Supabase networking, validate every uploaded file, and keep all third-party credentials in a secure secret manager.

What Makes the Project Useful

Aeglis is intentionally more than a collection of scanners. It provides the surrounding platform pieces needed to turn detection logic into a product capability:

  • A single API surface for multiple input types
  • Consumer authentication and scan history
  • Developer API keys and quotas
  • Webhook delivery for integrations
  • Persistence for logs, profiles, support, and billing workflows
  • A ready-to-run Supabase schema
  • Local fallbacks for some optional infrastructure
  • Modular engines that can evolve independently

This makes it suitable as a foundation for consumer safety tools, security dashboards, content moderation systems, developer products, and internal security automation.

Open Source and Contributions

Aeglis Intelligence is released under the MIT License and is available on GitHub:

github.com/Shubhamorigin/Aeglis-Intelligence

The most useful contributions will likely be improvements to detection quality, better test coverage, safer integration defaults, new file-format support, clearer result explanations, and documentation for deployment scenarios.

When contributing, keep secrets out of commits, test changes against representative inputs, and document any new environment variables or external service requirements.

Final Thoughts

Threat detection becomes more useful when it is available where decisions are made: inside an application, a download flow, a moderation queue, or a developer workflow.

Aeglis Intelligence is an attempt to make that integration practical by combining local analysis, external intelligence, AI-assisted reasoning, persistence, authentication, and delivery mechanisms in one open-source backend.

Explore the repository, run the database schema, try the API locally, and adapt the detection layer to the needs of your own application.

Repository: github.com/Shubhamorigin/Aeglis-Intelligence

Built by: Shubham

Top comments (0)