torusguard 1.0.0 → 1.3.1

package/.torusguard/rules/agent/TG-AGENT-003-broad-mcp-tool-scoping.md

@@ -0,0 +1,53 @@
+# TG-AGENT-003: Overly Broad MCP Tool Scoping & Credential Access
+
+## Severity
+High. Granting Model Context Protocol (MCP) servers or autonomous agents unbounded filesystem or database access violates the principle of least privilege.
+
+## Applies To
+- Model Context Protocol (MCP) Configurations (`mcp_config.json`, `.agent/mcp.json`)
+- AI Coding Agent Plugins & Tool Connectors
+
+## Why It Matters
+MCP servers bridge LLMs to local filesystems, git repositories, and external APIs. When MCP configurations grant broad root filesystem access (`/`) or pass unrestricted service-role database keys:
+1. A compromised or hallucinating agent can read SSH keys, browser cookies, and bash histories.
+2. Destructive SQL operations (`DROP TABLE`, `DELETE FROM`) can be triggered through tool calls without human confirmation.
+
+## What TorusGuard Looks For
+1. MCP server configurations mounting root directories (`/`, `C:\`, `~`) instead of project-specific subdirectories.
+2. Unrestricted write and delete permissions on production databases passed to agent tools.
+3. Lack of Human-in-the-Loop confirmation gates for destructive actions.
+
+## Unsafe Example
+```json
+// UNSAFE: MCP configuration granting full user home directory access
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
+    }
+  }
+}
+```
+
+## Safe Example
+```json
+// SAFE: Least privilege directory scoping restricted to active project workspace
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src", "./docs"]
+    }
+  }
+}
+```
+
+## Remediation
+1. **Scope to Project Root:** Restrict filesystem MCP servers to explicit project workspaces. Never mount user home directories or sensitive system paths.
+2. **Read-Only by Default:** Configure tools with read-only modes unless write access is explicitly justified.
+3. **Human Gate for Destructive Actions:** Require explicit user approval before executing file deletions or destructive database queries.
+
+## Related Rules
+- `TG-AGENT-002`: Unsafe Tool Dispatch & Shell Execution without Sandboxing
+- `TG-SEC-001`: Hardcoded Secrets

package/.torusguard/rules/agent/TG-AGENT-004-persistent-memory-cross-session-leakage.md

@@ -0,0 +1,67 @@
+# TG-AGENT-004: Persistent Memory & Cross-Session Information Leakage
+
+## Severity
+High. Storing unredacted sensitive session data, tokens, or personal information in long-term vector memory stores causes cross-session data leakage.
+
+## Applies To
+- Agent Long-Term Memory, RAG Vector Stores, ChromaDB, Pinecone, LangChain Memory
+- Multi-Tenant AI Assistants & Support Bots
+
+## Why It Matters
+Autonomous agents increasingly use vector embeddings and episodic memory databases to remember user preferences across sessions. If multi-tenant agents store memories without tenant isolation:
+1. User A's API tokens, medical history, or confidential notes can be indexed into vector search.
+2. When User B queries the agent, vector similarity search can retrieve User A's private context and inject it into the prompt.
+
+## What TorusGuard Looks For
+1. Ingesting raw user messages containing credentials, tokens, or PII into persistent vector databases without automated secret scrubbing.
+2. Vector database queries lacking mandatory `tenant_id` metadata filtering.
+3. Cross-user shared memory caches in multi-user AI services.
+
+## Unsafe Example
+```python
+# UNSAFE: Storing raw user messages in shared vector memory without tenant isolation
+def save_agent_memory(vector_store, user_id: str, message: str):
+    # Missing credential scrub & missing tenant namespace
+    vector_store.add_texts(
+        texts=[message],
+        metadatas=[{"source": "chat"}] # Danger: Searchable across all users!
+    )
+```
+
+## Safe Example
+```python
+# SAFE: Secret redaction and mandatory tenant metadata isolation
+from core.runtime_evidence import mask_sensitive_data
+
+def save_agent_memory(vector_store, tenant_id: str, user_id: str, message: str):
+    # 1. Scrub credentials and tokens prior to indexing
+    clean_message = mask_sensitive_data(message)
+    
+    # 2. Store with strict tenant metadata
+    vector_store.add_texts(
+        texts=[clean_message],
+        metadatas=[{
+            "tenant_id": tenant_id,
+            "user_id": user_id,
+            "source": "chat"
+        }]
+    )
+
+def query_agent_memory(vector_store, tenant_id: str, query: str):
+    # Mandatory tenant filter prevents cross-tenant memory leakage
+    return vector_store.similarity_search(
+        query,
+        k=4,
+        filter={"tenant_id": tenant_id}
+    )
+```
+
+## Remediation
+1. **Always Sanitize Before Storing:** Run credential masking over all text before saving to memory databases.
+2. **Strict Tenant Filtering:** Enforce hard metadata filters (`filter={"tenant_id": ...}`) on every vector search query.
+3. **Session Cleansing:** Provide users with clear commands to clear and audit persistent memory.
+
+## Related Rules
+- `TG-AGENT-001`: Prompt Injection in System Context Files
+- `TG-DB-004`: Missing Tenant Query Isolation
+- `TG-SEC-004`: Sensitive Logging

package/.torusguard/rules/authorization/TG-AUTH-006-mass-assignment.md

@@ -0,0 +1,70 @@
+# TG-AUTH-006: Mass Assignment & Privilege Escalation via Payloads
+
+## Severity
+High by default. Raise to Critical when client payloads can alter administrative roles (`is_staff`, `is_superuser`, `role`), account status, or billing tiers.
+
+## Applies To
+- Form handlers, model binders, ORM update operations, DRF serializers, and FastAPI/Pydantic ingestion schemas.
+
+## Why It Matters
+When server code automatically binds arbitrary client JSON/form keys to internal database models without field-level allowlists, clients can inject sensitive attributes (e.g. `{"role": "admin", "is_verified": true}`) to elevate their privileges.
+
+## What TorusGuard Looks For
+- Django `ModelForm` classes declaring `fields = '__all__'`.
+- DRF serializers without `read_only_fields` on privilege or system columns.
+- FastAPI/Pydantic schemas omitting `extra="forbid"` or binding directly to ORM models.
+- SQLAlchemy `.update(request_data)` executing raw untrusted dictionaries.
+
+## Evidence & Classification Standards
+- **`Confirmed`:** `fields = '__all__'` in Django ModelForms or raw `.update(payload)` without allowlists on models containing privilege fields.
+- **`Safe`:** Serializers using explicit `read_only_fields = ['role', 'is_staff']` or Pydantic models using `ConfigDict(extra="forbid")`.
+
+## Unsafe Examples
+
+### Django ModelForm
+```python
+# VULNERABLE: Binds all model fields to form
+class UserProfileForm(forms.ModelForm):
+    class Meta:
+        model = User
+        fields = '__all__'  # ❌ Allows user to submit is_staff=True
+```
+
+### DRF Serializer
+```python
+# VULNERABLE: Missing read_only_fields
+class UserSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = ['id', 'username', 'email', 'role', 'is_staff']  # ❌ role & is_staff are writable
+```
+
+## Safe Examples
+
+### Django ModelForm
+```python
+# SAFE: Explicit editable fields whitelist
+class UserProfileForm(forms.ModelForm):
+    class Meta:
+        model = User
+        fields = ['display_name', 'bio', 'avatar_url']  # ✅ Only safe fields exposed
+```
+
+### DRF Serializer
+```python
+# SAFE: Explicit read_only_fields
+class UserSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = ['id', 'username', 'email', 'role', 'is_staff']
+        read_only_fields = ['id', 'role', 'is_staff']  # ✅ System fields protected
+```
+
+## Remediation
+1. Use explicit field allowlists rather than wildcard binds.
+2. In DRF serializers, declare `read_only_fields` for all privilege, status, and financial properties.
+3. In Pydantic v2 schemas, configure `model_config = ConfigDict(extra="forbid")`.
+
+## Related Rules
+- `TG-AUTH-007`: Missing Property-Level Authorization
+- `TG-INPUT-001`: Unvalidated Client Input

package/.torusguard/rules/authorization/TG-AUTH-007-missing-property-level-authorization.md

@@ -0,0 +1,71 @@
+# TG-AUTH-007: Missing Object-Level and Property-Level Authorization (IDOR)
+
+## Severity
+High by default. Raise to Critical when financial, healthcare, or administrative records are exposed without tenant boundaries.
+
+## Applies To
+- Database query handlers, REST API endpoints, GraphQL resolvers, RPC methods, and service layers across Node.js, Express, Django, DRF, FastAPI, Flask, and SQLAlchemy.
+
+## Why It Matters
+When an application retrieves, modifies, or deletes an object using a client-supplied identifier (`id`, `order_id`, `invoice_id`) without verifying that the requesting user owns or has legitimate access to that specific object, attackers can perform Insecure Direct Object References (IDOR) to access records belonging to other tenants.
+
+## What TorusGuard Looks For
+- Query lookups using solely URL parameters or payload primary keys (e.g. `Model.objects.get(id=pk)`, `session.query(Order).filter(Order.id == order_id)`) without tenant/user ownership criteria.
+- Serializers and API endpoints that expose or mutate private sub-resources without validating the parent-child tenant relationship.
+
+## Evidence & Classification Standards
+- **`Confirmed`:** The query or view directly executes database lookups using an unsanitized client identifier with zero user/tenant filter criteria in the same module.
+- **`Manual Review`:** The view delegates fetching to a separate domain or service layer (e.g. `InvoiceService.get_invoice(id, request.user)`). The reviewer must inspect the service layer to confirm tenant enforcement.
+- **`Informational`:** Read-only queries against intentionally public or catalog records.
+
+## Unsafe Examples
+
+### Python (Django / DRF)
+```python
+# VULNERABLE: Direct lookup without owner filter
+class InvoiceViewSet(viewsets.ModelViewSet):
+    queryset = Invoice.objects.all()  # ❌ Exposes all invoices to any user
+    serializer_class = InvoiceSerializer
+```
+
+### Python (SQLAlchemy)
+```python
+# VULNERABLE: Direct primary key filter
+def get_order(session, order_id: int):
+    return session.query(Order).filter(Order.id == order_id).first()  # ❌ Missing user_id
+```
+
+## Safe Examples
+
+### Python (Django / DRF)
+```python
+# SAFE: Scope queryset to authenticated user
+class InvoiceViewSet(viewsets.ModelViewSet):
+    serializer_class = InvoiceSerializer
+    permission_classes = [permissions.IsAuthenticated]
+
+    def get_queryset(self):
+        return Invoice.objects.filter(owner=self.request.user)  # ✅ Scoped
+```
+
+### Python (SQLAlchemy)
+```python
+# SAFE: Scoped query
+def get_order(session, order_id: int, current_user_id: int):
+    return session.query(Order).filter(
+        Order.id == order_id, 
+        Order.user_id == current_user_id
+    ).first()  # ✅ Scoped to user
+```
+
+## Remediation
+1. Ensure all object lookups include the current user/tenant ID in the database query (`filter(user_id=request.user.id)`).
+2. For DRF ViewSets, override `get_queryset()` to filter by `self.request.user`.
+3. In service-layer architectures, pass the authenticated user identity explicitly into domain methods.
+
+## Verification
+- Run authenticated test requests using User A's credentials against User B's resource IDs and assert `404 Not Found` or `403 Forbidden`.
+
+## Related Rules
+- `TG-AUTH-006`: Mass Assignment
+- `TG-AUTH-001`: Unauthenticated Endpoints

package/.torusguard/rules/authorization/TG-AUTH-008-untrusted-role-header-injection.md

@@ -0,0 +1,112 @@
+---
+id: TG-AUTH-008
+title: Untrusted Role or Tenant Header Injection
+category: authentication-authorization
+severity: Critical
+confidence: Confirmed
+frameworks:
+  - django
+  - drf
+  - fastapi
+  - flask
+  - express
+  - nextjs
+cwe: CWE-284
+asvs_v4: V4.1.1
+nist_ssdf: PW.5.1
+---
+
+# TG-AUTH-008: Untrusted Role or Tenant Header Injection
+
+## 🚨 Problem Statement
+Applications that extract user roles, permissions, or tenant identifiers directly from client-supplied HTTP request headers (e.g. `X-User-Role`, `X-Tenant-ID`, `X-Is-Admin`, `X-Authenticated-User`) without cryptographic verification or a trusted API gateway boundary allow attackers to elevate privileges or access arbitrary tenant data simply by injecting custom header values.
+
+> **Tuning Guardrails (v0.5.6):**
+> - **DO NOT flag** a header merely because it is read (e.g., for logging or non-authoritative metadata).
+> - **ESCALATE** only if client-controlled role/tenant data influences authorization, identity, tenant selection, or privileged database scope without verified server-side binding.
+> - **DOWNGRADE** to `Needs Review` if authorization context is resolved elsewhere (e.g., API gateway, mTLS, service mesh) and cannot be proven vulnerable from local source alone.
+
+---
+
+## 💥 Adversarial Threat & Exploitation
+An attacker sends a request with crafted HTTP headers:
+```http
+GET /api/v1/admin/users HTTP/1.1
+Host: api.example.com
+X-User-Role: superadmin
+X-Tenant-ID: victim-tenant-uuid
+```
+If the backend application assigns permissions based on `request.headers.get("X-User-Role")` without verifying that the request originated from an internal gateway with a signed cryptographic token (or mTLS), the attacker completely bypasses authorization checks.
+
+---
+
+## 🛠️ Framework-Native Remediations
+
+### 🐍 FastAPI (Dependency Injection & Signed JWT Extraction)
+
+#### ❌ Unsafe Pattern
+```python
+# Unsafe: Trusting client-supplied header directly
+@app.get("/admin/metrics")
+async def get_metrics(x_user_role: str = Header(None)):
+    if x_user_role != "admin":
+        raise HTTPException(status_code=403, detail="Forbidden")
+    return {"metrics": "sensitive_admin_data"}
+```
+
+#### ✅ Safe Remediation
+```python
+# Safe: Extracting authenticated user and roles from cryptographically verified token
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+import jwt
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
+
+async def get_current_user_roles(token: str = Depends(oauth2_scheme)) -> list[str]:
+    try:
+        payload = jwt.decode(token, settings.JWT_SECRET_KEY, algorithms=["HS256"])
+        return payload.get("roles", [])
+    except jwt.PyJWTError:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")
+
+@app.get("/admin/metrics")
+async def get_metrics(roles: list[str] = Depends(get_current_user_roles)):
+    if "admin" not in roles:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Forbidden")
+    return {"metrics": "sensitive_admin_data"}
+```
+
+---
+
+### 🐍 Django / DRF (Session & Verified Token Authorization)
+
+#### ❌ Unsafe Pattern
+```python
+# Unsafe: Using request header in ViewSet or middleware for tenant scoping
+class DocumentViewSet(viewsets.ModelViewSet):
+    def get_queryset(self):
+        tenant_id = self.request.headers.get("X-Tenant-ID")
+        return Document.objects.filter(tenant_id=tenant_id)
+```
+
+#### ✅ Safe Remediation
+```python
+# Safe: Deriving tenant isolation from authenticated user session or token claim
+class DocumentViewSet(viewsets.ModelViewSet):
+    permission_classes = [permissions.IsAuthenticated]
+
+    def get_queryset(self):
+        # Derive tenant strictly from the server-authenticated user profile
+        user_tenant = self.request.user.profile.tenant
+        return Document.objects.filter(tenant=user_tenant)
+```
+
+---
+
+## 🧪 Verification & Reproduction
+1. Execute request with header override:
+   ```bash
+   curl -H "X-User-Role: admin" -H "X-Tenant-ID: victim-tenant" http://localhost:8000/api/admin/metrics
+   ```
+2. **Assertion:** Unauthenticated request must return `401 Unauthorized` or `403 Forbidden`, ignoring unverified header overrides.

package/.torusguard/rules/business-logic/TG-BIZ-001-client-controlled-sensitive-business-value.md

@@ -0,0 +1,37 @@
+# TG-BIZ-001: Client-Controlled Sensitive Business Value
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001

package/.torusguard/rules/business-logic/TG-BIZ-002-replayable-one-time-operation.md

@@ -0,0 +1,37 @@
+# TG-BIZ-002: Replayable One-Time Operation
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001

package/.torusguard/rules/business-logic/TG-BIZ-003-missing-workflow-state-validation.md

@@ -0,0 +1,37 @@
+# TG-BIZ-003: Missing Workflow-State Validation
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001

package/.torusguard/rules/business-logic/TG-BIZ-004-unrestricted-sensitive-business-flow.md

@@ -0,0 +1,37 @@
+# TG-BIZ-004: Unrestricted Sensitive Business Flow
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001

package/.torusguard/rules/cache/TG-CACHE-001-sensitive-response-publicly-cacheable.md

@@ -0,0 +1,37 @@
+# TG-CACHE-001: Sensitive Response Publicly Cacheable
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001

package/.torusguard/rules/cache/TG-CACHE-002-missing-user-cache-isolation.md

@@ -0,0 +1,37 @@
+# TG-CACHE-002: Missing User Cache Isolation
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001

package/.torusguard/rules/cache/TG-CACHE-003-sensitive-data-in-url.md

@@ -0,0 +1,37 @@
+# TG-CACHE-003: Sensitive Data in URL
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001

package/.torusguard/rules/csrf/TG-CSRF-001-missing-csrf-protection.md

@@ -0,0 +1,37 @@
+# TG-CSRF-001: Missing CSRF Protection
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001