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**
|
||||
- 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**.
|
||||
|
||||
@@ -23,72 +27,215 @@ This backend is designed to evolve into an **AI-driven autonomous remediation ag
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
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" \
|
||||
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
|
||||
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
|
||||
|
||||
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