Anikk02/triansec-sdk
GitHub: Anikk02/triansec-sdk
一款为 FastAPI 应用提供基于行为分析的 API 安全防护 SDK，防御凭证填充、爬虫和自动化机器人攻击。
Stars: 0 | Forks: 0
# TriAnSec SDK
[](https://badge.fury.io/py/triansec)
[](https://pypi.org/project/triansec/)
[](https://opensource.org/licenses/MIT)
**TriAnSec SDK** 是一个轻量级的 Python SDK，用于将 TrianSec API 安全平台集成到您的 FastAPI/Starlette 应用程序中。它提供基于行为的 API 保护，且无需修改您现有的业务逻辑。
## ✨ 功能
- 🔒 **基于行为的保护** - 分析请求模式，而不仅仅是速率限制
- ⚡ **快速决策路径** - 安全决策延迟低于 15ms
- 🛡️ **自适应策略引擎** - 动态应用 ALLOW、BLOCK 或 THROTTLE 决策
- 🧠 **有状态的智能** - 为每个身份维护历史行为状态
- 📊 **可解释的决策** - 每个决策都包含人类可读的原因
- 🔌 **即插即用** - 只需一行代码即可完成最小化集成
- 🎯 **多租户隔离** - 每个客户端的安全态势相互独立
## 📦 安装
```
pip install triansec
```
支持 FastAPI（可选）：
```
pip install triansec[fastapi]
```
用于开发：
```
pip install triansec[dev]
```
## 🚀 快速开始
### 1. 获取您的 API Key
在 [TriAnSec](https://triansec.com) 注册并从仪表板生成您的 API key。
### 2. 添加 Middleware
```
from fastapi import FastAPI
from triansec import TriAnSec
app = FastAPI()
# 添加 security middleware
app.add_middleware(
TriAnSec,
api_key="ts_live_xxxxxxxxx",
timeout=5,
fallback_action="allow",
)
@app.get("/")
async def root():
return {"message": "Protected by TrianSec"}
```
## 📋 使用示例
### 选项 1：直接使用 Middleware（最简单）
```
from fastapi import FastAPI
from triansec import TriAnSec
app = FastAPI()
app.add_middleware(
TriAnSec,
api_key="ts_live_xxxxxxxxx",
timeout=10,
fallback_action="allow",
)
```
### 选项 2：使用类和 Install 方法
```
from fastapi import FastAPI
from triansec.security import TriAnSec
app = FastAPI()
security = TriAnSec(
api_key="ts_live_xxxxxxxxx",
timeout=10,
fallback_action="allow",
)
security.install(app)
```
### 选项 3：一行代码设置
```
from fastapi import FastAPI
from triansec.security import setup_security
app = FastAPI()
security = setup_security(
app,
api_key="ts_live_xxxxxxxxx",
timeout=10,
fallback_action="allow",
add_health=True,
add_shutdown=True,
)
```
### 使用配置对象
```
from fastapi import FastAPI
from triansec import TriAnSec, SecurityConfig
app = FastAPI()
config = SecurityConfig(
api_key="ts_live_xxxxxxxxx",
timeout=10,
fallback_action="block",
enable_cache=True,
cache_ttl=600,
)
app.add_middleware(TriAnSec, config=config)
```
## ⚙️ 配置选项
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `api_key` | `str` | **必填** | 您的 TrianSec API key |
| `engine_url` | `str` | 硬编码 | 安全引擎 URL（您无需设置此项） |
| `timeout` | `int` | `5` | 请求超时时间（秒） |
| `retry_count` | `int` | `3` | 重试次数 |
| `fallback_action` | `str` | `"allow"` | 引擎不可用时的操作（`"allow"` 或 `"block"`） |
| `enable_cache` | `bool` | `True` | 启用本地决策缓存 |
| `cache_ttl` | `int` | `300` | 缓存 TTL（秒） |
| `cache_maxsize` | `int` | `1000` | 最大缓存条目数 |
| `enable_debug` | `bool` | `False` | 启用调试模式 |
| `bypass_paths` | `List[str]` | 控制面路径 | 绕过安全检查的路径 |
## 🔧 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `TRIANSEC_API_KEY` | 您的 TrianSec API key | （必填） |
| `TRIANSEC_ENGINE_URL` | 安全引擎 URL | `https://api.triansec.com` |
| `TRIANSEC_TIMEOUT` | 请求超时时间（秒） | `5` |
| `TRIANSEC_RETRY_COUNT` | 重试次数 | `3` |
| `TRIANSEC_FALLBACK_ACTION` | 回退操作（`allow` 或 `block`） | `allow` |
| `TRIANSEC_CACHE_ENABLED` | 启用缓存（`true` 或 `false`） | `true` |
| `TRIANSEC_CACHE_TTL` | 缓存 TTL（秒） | `300` |
| `TRIANSEC_DEBUG` | 调试模式（`true` 或 `false`） | `false` |
## 🔒 工作原理
```
Incoming Request
│
▼
SDK Middleware
│
▼
Extract Request Data (IP, User-Agent, Headers, etc.)
│
▼
Check Local Cache
│
▼
Send to Security Engine (with API key from request)
│
▼
Security Engine validates API key, analyzes behavior
│
▼
Return Decision (ALLOW / BLOCK / THROTTLE)
│
▼
Apply Decision
│
▼
Your Application Logic
```
## 🛡️ 安全决策
| 决策 | 描述 |
|----------|-------------|
| **ALLOW** | 请求合法，放行至您的应用程序 |
| **THROTTLE** | 请求可疑，带限流 header 放行 |
| **BLOCK** | 请求恶意，返回 `429 Too Many Requests` |
## 🧪 开发
### 设置
```
git clone https://github.com/triansec/triansec-sdk.git
cd triansec-sdk
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e .[dev]
```
### 运行测试
```
pytest
```
### 运行测试并生成覆盖率报告
```
pytest --cov=triansec --cov-report=html
```
### 代码检查
```
ruff check .
black .
mypy triansec
```
## 📄 许可证
本项目基于 MIT 许可证授权 - 详情请参阅 [LICENSE](LICENSE) 文件。
## 📞 支持
- 文档：[https://docs.triansec.com](https://docs.triansec.com)
- 问题：[https://github.com/Anikk02/triansec-sdk/issues](https://github.com/triansec/triansec-sdk/issues)
- 邮箱：support@triansec.com
## 👥 作者
- **Aniket Paswan** - *后端架构、系统设计、策略引擎、安全 Middleware、前端开发*
- **Anjali Jha** - *认证架构、API Key 生成与管理、前端开发、UI/UX*
- **Anshika Pratap Singh** - *系统管理、前端开发、UI/UX、开发者仪表板*
## 🙏 鸣谢
- 基于 [FastAPI](https://fastapi.tiangolo.com/) 和 [Starlette](https://www.starlette.io/) 构建
- 由 [httpx](https://www.python-httpx.org/) 和 [Pydantic](https://docs.pydantic.dev/) 提供支持
标签：API安全, AppImage, AV绕过, FastAPI, JSON输出, Python, Web应用防火墙, 反爬虫, 无后门, 运行时操纵, 逆向工具