Metadata-Version: 2.4
Name: ulinzilogs
Version: 0.1.11
Summary: Security logging middleware for FastAPI, Flask, and Django
Author-email: PashyGeek <codyypashy@gmail.com>
Project-URL: Homepage, https://github.com/PashyGeek/ulinzilogs
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Provides-Extra: fastapi
Requires-Dist: starlette>=0.20.0; extra == "fastapi"
Provides-Extra: flask
Requires-Dist: flask>=2.0.0; extra == "flask"
Provides-Extra: django
Requires-Dist: django>=3.2; extra == "django"
Provides-Extra: all
Requires-Dist: starlette>=0.20.0; extra == "all"
Requires-Dist: flask>=2.0.0; extra == "all"
Requires-Dist: django>=3.2; extra == "all"

# Ulinzilogs 🛡️

> **Lightweight, non‑blocking security logging middleware for Python web apps**
> Built for developers who want **visibility without performance pain**.

---

## 🌍 What is Ulinzilogs?

**Ulinzilogs** is a security‑focused middleware that silently watches incoming HTTP requests in your Python web application, **redacts sensitive data**, and **ships sanitized logs** to the Ulinzi Security API for **AI‑powered threat analysis**.

Think of it as:

> 🔐 *A security camera for your API — always on, never in the way.*

---

## ✨ Key Features

* 🚀 **Non‑Blocking by Design** — Uses background threads so your request/response cycle stays fast.
* 🔒 **Automatic Data Redaction** — Sensitive fields are replaced with `[REDACTED]` before leaving your server.
* 🌐 **Multi‑Framework Support** — Works out of the box with FastAPI, Flask, and Django.
* 🧹 **Clean & Safe Headers** — Excludes `Authorization` and `Cookie` headers automatically.

---

## 📦 Installation

Install only what your stack needs:

```bash
# FastAPI / Starlette
pip install ulinzilogs[fastapi]

# Flask
pip install ulinzilogs[flask]

# Django
pip install ulinzilogs[django]

# All frameworks
pip install ulinzilogs[all]
```

---

## 🔑 Getting Your Project Key

After installing, run:

```bash
ulinzi-init
```

This generates a **unique Project Key** for your app and prints setup instructions.

> ⚠️ **Important:** This key is generated locally on your machine.
> To activate it, copy the key and register it at **[ulinzilogs.com](https://ulinzilogs.com)**.
> Once registered, your dashboard will start receiving logs from your app.

---

## ⚙️ Setup & Usage

### 🟢 FastAPI

```python
from fastapi import FastAPI
from ulinzilogs import UlinziFastAPIMiddleware

app = FastAPI()

app.add_middleware(
    UlinziFastAPIMiddleware,
    api_key="YOUR_ULINZI_KEY"
)

@app.get("/")
async def root():
    return {"message": "Protected by Ulinzi"}
```

---

### 🔵 Flask

```python
from flask import Flask
from ulinzilogs import UlinziFlaskMiddleware

app = Flask(__name__)
UlinziFlaskMiddleware(app, api_key="YOUR_ULINZI_KEY")

@app.route("/")
def hello():
    return "Protected by Ulinzi"
```

---

### 🟣 Django

In `settings.py`:

```python
MIDDLEWARE = [
    # ... other middleware
    'ulinzilogs.UlinziDjangoMiddleware',
]

ULINZI_API_KEY = "YOUR_ULINZI_KEY"
ULINZI_APP_NAME = "MyDjangoApp"   # optional label shown in dashboard
```

---

## 🧠 How Ulinzilogs Works
Client Request
│
▼
┌───────────────┐
│   Middleware  │
└──────┬────────┘
│
▼
┌────────────────────┐
│  Redact Sensitive  │
│  Fields & Headers  │
└──────┬─────────────┘
│
▼   (Background Thread)
┌────────────────────┐
│  Send to Ulinzi    │
│  Security API      │
└──────┬─────────────┘
│
▼
┌────────────────────┐
│ AI Threat Analysis │
│ (SQLi, XSS, etc.)  │
└────────────────────┘

1. **Intercept** — Captures request metadata (IP, URL, method, body).
2. **Redact** — Removes secrets before transmission.
3. **Dispatch** — Sends logs asynchronously in a background thread.
4. **Analyze** — Central AI scans for malicious patterns.

---

## 🔐 Sensitive Data Protection

The following keys are **automatically redacted**:

| Field | Redacted? |
|-------|-----------|
| `password` | ✅ Yes |
| `secret` | ✅ Yes |
| `token` | ✅ Yes |
| `key` | ✅ Yes |
| `cvv` | ✅ Yes |
| `api_key` | ✅ Yes |

Example:

```json
{
  "email": "user@mail.com",
  "password": "[REDACTED]"
}
```

Your users' secrets **never leave your server in plaintext**.

---

## ⚡ Performance Philosophy

* No request blocking
* No database writes on your server
* No logging delays

Ulinzilogs runs **beside** your app — not **inside** its critical path.

---

## 🧩 Package Structure
ulinzilogs/
├── init.py
├── middleware.py
├── utils.py
├── cli.py
├── pyproject.toml
└── README.md

---

## 📜 License

Copyright (c) 2026 PashyGeek. Licensed under the MIT License — see the LICENSE file for details.
