mirror of
https://github.com/Rarebuffalo/securelens-backend.git
synced 2026-06-19 07:00:30 +00:00
updated the details
This commit is contained in:
rarebuffalo
203
README.md
203
README.md
@@ -16,6 +16,10 @@ It:
|
|||||||
- Assigns a **security score**
|
- Assigns a **security score**
|
||||||
- Categorizes risks into layers
|
- Categorizes risks into layers
|
||||||
- Generates **human-readable fix suggestions**
|
- 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**.
|
This backend is designed to evolve into an **AI-driven autonomous remediation agent**.
|
||||||
|
|
||||||
@@ -23,72 +27,215 @@ This backend is designed to evolve into an **AI-driven autonomous remediation ag
|
|||||||
|
|
||||||
## 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 |
|
| Layer | Checks | Purpose |
|
||||||
| ------------------- | --------------------------------- |
|
| ------------------- | ------ | ---------------------------------------------- |
|
||||||
| Transport Layer | HTTPS, HSTS, secure communication |
|
| Transport Layer | 6 | HTTPS, HSTS analysis, mixed content prevention |
|
||||||
| Server Config Layer | Security headers, CORS, policies |
|
| SSL/TLS Layer | 5 | Certificate expiry, TLS version, chain issues |
|
||||||
| Exposure Layer | Sensitive endpoints, leaked paths |
|
| 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**
|
- **Python 3.12+**
|
||||||
- **FastAPI**
|
- **FastAPI** — async web framework
|
||||||
- **HTTP analysis via Requests**
|
- **httpx** — async HTTP client
|
||||||
- JSON-based API output
|
- **SQLAlchemy 2.0** — async ORM (SQLite dev / PostgreSQL production)
|
||||||
- Designed for future AI integration
|
- **Pydantic v2** — data validation & settings
|
||||||
|
- **python-jose** — JWT authentication
|
||||||
|
- **passlib + bcrypt** — password hashing
|
||||||
|
- **SlowAPI** — rate limiting
|
||||||
|
- **Docker** — containerized deployment
|
||||||
|
- **pytest** — testing
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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
|
## Installation
|
||||||
|
|
||||||
|
### Local Development (SQLite)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/Rarebuffalo/securelens-backend
|
git clone https://github.com/Rarebuffalo/securelens-backend
|
||||||
cd securelens-backend
|
cd securelens-backend
|
||||||
python -m venv venv
|
python -m venv venv
|
||||||
source venv/bin/activate
|
source venv/bin/activate
|
||||||
pip install -r requirements.txt
|
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
|
## API Endpoints
|
||||||
{
|
|
||||||
"url": "https://example.com"
|
### 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
|
```bash
|
||||||
curl -X POST "http://127.0.0.1:8000/scan" \
|
curl -X POST http://127.0.0.1:8000/scan \
|
||||||
-H "Content-Type: application/json" \
|
-H "Content-Type: application/json" \
|
||||||
|
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||||
-d '{"url": "https://google.com"}'
|
-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
|
||||||
|
pytest tests/ -v
|
||||||
|
```
|
||||||
|
|
||||||
|
Tests use an in-memory SQLite database — no external DB needed.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Future Roadmap
|
## Future Roadmap
|
||||||
|
|
||||||
- AI agent for auto-remediation
|
- AI agent for auto-remediation
|
||||||
- Codebase & deployment scanning
|
- PDF report generation
|
||||||
- Mobile app security checks
|
|
||||||
- CI/CD pipeline integration
|
- 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! 🛡️
|
||||||
|
|||||||
Reference in New Issue
Block a user