External/securelens-backend
1
0
Fork 0
mirror of https://github.com/Rarebuffalo/securelens-backend.git synced 2026-06-19 07:00:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

updated the details

Browse Source
This commit is contained in:
rarebuffalo
2026-04-07 18:09:09 +05:30
parent 45c3647517
commit 087d8ffaee
1 changed files with 181 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

215
README.md
View File

@@ -1,10 +1,10 @@
# SecureLens AI — Backend
# SecureLens AI — Backend
SecureLens AI Backend is the core security engine that powers the SecureLens AI agent. It performs live security analysis of applications and generates structured risk insights, issue explanations, and remediation guidance.
---
## What This Backend Does
## What This Backend Does
The SecureLens backend acts as the **security brain** of the system.
@@ -16,34 +16,103 @@ It:
- Assigns a **security score**
- Categorizes risks into layers
- Generates **human-readable fix suggestions**
- Validates URLs and prevents SSRF attacks
- Rate limits API requests
- **User authentication** with JWT tokens
- **Scan history** — saves and retrieves past scan results
This backend is designed to evolve into an **AI-driven autonomous remediation agent**.
---
## Security Layers Modeled
## Security Layers Modeled
SecureLens structures vulnerabilities into logical layers:
SecureLens structures vulnerabilities into 5 logical layers with **30+ security checks**:
| Layer | Purpose |
| ------------------- | --------------------------------- |
| Transport Layer | HTTPS, HSTS, secure communication |
| Server Config Layer | Security headers, CORS, policies |
| Exposure Layer | Sensitive endpoints, leaked paths |
| Layer | Checks | Purpose |
| ------------------- | ------ | ---------------------------------------------- |
| Transport Layer | 6 | HTTPS, HSTS analysis, mixed content prevention |
| SSL/TLS Layer | 5 | Certificate expiry, TLS version, chain issues |
| Server Config Layer | 14 | Security headers, CSP analysis, info disclosure|
| Cookie Security | 4 | HttpOnly, Secure, SameSite flags |
| Exposure Layer | 25+ | Sensitive paths, robots.txt, directory listing |
---
## 🛠 Tech Stack
## Tech Stack
- **Python**
- **FastAPI**
- **HTTP analysis via Requests**
- JSON-based API output
- Designed for future AI integration
- **Python 3.12+**
- **FastAPI** — async web framework
- **httpx** — async HTTP client
- **SQLAlchemy 2.0** — async ORM (SQLite dev / PostgreSQL production)
- **Pydantic v2** — data validation & settings
- **python-jose** — JWT authentication
- **passlib + bcrypt** — password hashing
- **SlowAPI** — rate limiting
- **Docker** — containerized deployment
- **pytest** — testing
---
## Installation
## Project Structure
```
securelens-backend/
├── app/
│ ├── main.py # FastAPI app + middleware + lifespan
│ ├── config.py # Pydantic settings (.env)
│ ├── database.py # Async SQLAlchemy engine & session
│ ├── models/
│ │ ├── user.py # User ORM model
│ │ └── scan.py # ScanResult ORM model
│ ├── schemas/
│ │ ├── auth.py # Auth request/response models
│ │ └── scan.py # Scan request/response models
│ ├── routers/
│ │ ├── auth.py # Register, login, me
│ │ ├── health.py # Health check endpoints
│ │ ├── scan.py # Scan endpoint
│ │ └── history.py # Scan history endpoints
│ ├── services/
│ │ ├── scoring.py # Scoring engine
│ │ └── scanner/
│ │ ├── base.py # Abstract scanner interface
│ │ ├── transport.py # Transport & HSTS checks
│ │ ├── ssl_checker.py # SSL/TLS certificate analysis
│ │ ├── headers.py # Header security checks
│ │ ├── cookies.py # Cookie security checks
│ │ └── exposure.py # Sensitive path detection
│ ├── middleware/
│ │ ├── auth.py # JWT auth dependencies
│ │ └── rate_limiter.py # SlowAPI rate limiting
│ └── utils/
│ ├── auth.py # JWT & password utilities
│ └── validators.py # URL validation & SSRF prevention
├── tests/
│ ├── conftest.py # Test fixtures (in-memory DB)
│ ├── test_auth.py
│ ├── test_health.py
│ ├── test_scan.py
│ ├── test_history.py
│ ├── test_validators.py
│ ├── test_transport.py
│ ├── test_headers.py
│ ├── test_ssl_checker.py
│ ├── test_cookies.py
│ └── test_scoring.py
├── main.py # Root entry point (backward compat)
├── .env.example
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── README.md
```
---
## Installation
### Local Development (SQLite)
```bash
git clone https://github.com/Rarebuffalo/securelens-backend
@@ -51,44 +120,122 @@ cd securelens-backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload
cp .env.example .env
uvicorn app.main:app --reload
```
The database is auto-created as `securelens.db` on first run.
### Docker (with PostgreSQL)
```bash
cp .env.example .env
docker compose up --build
```
---
## API Endpoint
## Configuration
### POST `/scan`
Copy `.env.example` to `.env` and customize:
Scans an application URL.
| Variable | Default | Description |
| --------------------- | ------------------------------------------ | --------------------------------- |
| `APP_NAME` | SecureLens AI | Application name |
| `APP_VERSION` | 1.0.0 | Application version |
| `DEBUG` | true | Enable debug mode & docs |
| `HOST` | 0.0.0.0 | Server host |
| `PORT` | 8000 | Server port |
| `CORS_ORIGINS` | http://localhost:3000,http://localhost:5173 | Allowed CORS origins |
| `RATE_LIMIT` | 30/minute | API rate limit |
| `SCAN_TIMEOUT` | 5 | HTTP request timeout (seconds) |
| `PATH_CHECK_TIMEOUT` | 3 | Sensitive path check timeout (s) |
| `DATABASE_URL` | sqlite+aiosqlite:///./securelens.db | Database connection string |
| `JWT_SECRET` | (change in production!) | Secret key for JWT signing |
| `JWT_ALGORITHM` | HS256 | JWT signing algorithm |
| `JWT_EXPIRY_MINUTES` | 1440 | Token expiry (default: 24h) |
**Request Body:**
---
```json
{
"url": "https://example.com"
}
## API Endpoints
### Health
| Method | Endpoint | Description |
| ------ | ---------- | ---------------- |
| GET | `/` | Welcome message |
| GET | `/health` | App status |
### Authentication
| Method | Endpoint | Description | Auth |
| ------ | ----------------- | ------------------------- | ---- |
| POST | `/auth/register` | Create account + get token| No |
| POST | `/auth/login` | Login + get token | No |
| GET | `/auth/me` | Get current user info | Yes |
### Scanning
| Method | Endpoint | Description | Auth |
| ------ | ---------------- | ------------------------------------ | -------- |
| POST | `/scan` | Scan a URL (saves if authenticated) | Optional |
### Scan History
| Method | Endpoint | Description | Auth |
| ------ | ----------------- | ------------------------- | ---- |
| GET | `/scans` | List your scan history | Yes |
| GET | `/scans/{id}` | Get scan details by ID | Yes |
| DELETE | `/scans/{id}` | Delete a scan | Yes |
### Example Usage
**Register:**
```bash
curl -X POST http://127.0.0.1:8000/auth/register \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "username": "myuser", "password": "securepass123"}'
```
**Example Usage:**
**Scan (authenticated):**
```bash
curl -X POST http://127.0.0.1:8000/scan \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{"url": "https://google.com"}'
```
**View scan history:**
```bash
curl http://127.0.0.1:8000/scans \
-H "Authorization: Bearer YOUR_TOKEN"
```
---
## Running Tests
```bash
curl -X POST "http://127.0.0.1:8000/scan" \
-H "Content-Type: application/json" \
-d '{"url": "https://google.com"}'
pytest tests/ -v
```
Tests use an in-memory SQLite database — no external DB needed.
---
## Future Roadmap
- AI agent for auto-remediation
- Codebase & deployment scanning
- Mobile app security checks
- PDF report generation
- CI/CD pipeline integration
- DNS security checks (SPF, DKIM, DMARC)
- Technology fingerprinting
- JavaScript library CVE detection
---
## License
## License
This project is open-source and available under the **MIT License**. You are free to commit, contribute, and fork this repository.
This project is open-source and available under the **MIT License**.
Happy Hacking!
Happy Hacking! 🛡️