Security

Security features and best practices

FileGuard is designed with security-first principles for storing sensitive documents.

Multi-Tenant Isolation

Data Isolation

Each tenant’s files are completely isolated. API keys from one tenant cannot access another tenant’s files.

Separate Storage

Files are stored in tenant-specific S3 paths, preventing cross-tenant access.

API Key Security

Key Hashing

API keys are hashed with SHA-256 before storage. The original key value is never stored.

Stored: SHA-256 hash
Returned: Only first 6 characters (prefix) for identification

Scope-Based Access Control

Scope	Permissions
upload	Upload files only
download	Get download URLs only
metadata	Read file/context info only
delete	Delete files only
admin	Full access

Follow least privilege: only grant scopes your application needs.

Key Status Management

Action	Use Case
Disable	Temporarily suspend (can re-enable)
Revoke	Permanently invalidate
Expire	Automatic expiration after set days

Pre-Signed URLs

Files are downloaded via pre-signed S3 URLs:

1. Request

   Client calls FileGuard API with API key

2. Authorization

   FileGuard validates API key and permissions

3. URL Generation

   FileGuard generates time-limited pre-signed URL

4. Download

   Client downloads directly from S3 (no credentials exposed)

Benefits:

• API keys never sent to S3
• URLs expire automatically (default: 5 minutes)
• Bandwidth offloaded to S3

File Validation

Multiple layers of validation before storage:

1. Extension whitelist - Only allowed file types
2. Size limits - Prevent oversized uploads
3. Blank detection - Reject empty/meaningless files
4. Corrupt detection - Reject malformed files
5. Virus scanning - ClamAV malware detection

Audit Logging

All sensitive operations are logged:

Logged Data	Purpose
Who (performer ID, name, email)	Accountability
What (entity, action)	Tracking
When (timestamp)	Timeline
Where (IP address, user agent)	Forensics
Details (before/after values)	Change tracking

Performer details are snapshotted at action time for compliance - they won’t change even if the user’s info is updated later.

Rate Limiting

Protect against abuse with configurable rate limits:

• Tenant-level: Global limit for all uploads
• Context-level: Per-context limits

When exceeded:

• HTTP 429 response
• Retry-After header
• Rate limit headers

Storage Quotas

Control storage usage:

• Tenant quota: Total storage across all contexts
• Context quota: Per-context storage limits

Prevents runaway storage costs and ensures fair usage.

Best Practices

Use environment variables for API keys

Never hardcode API keys in source code:

API_KEY = os.environ.get("FILEGUARD_API_KEY")

Rotate keys regularly

Create new keys and revoke old ones periodically. Use last_used_at to identify unused keys.

Use separate keys per environment

Different keys for development, staging, and production.

Enable all validation

Keep reject_blank_files, reject_corrupt_files, and scan_for_viruses enabled unless you have a specific reason.

Set short URL expiration

Use the minimum expires_in time needed for your use case.

Monitor audit logs

Regularly review audit logs for suspicious activity.

Compliance

FileGuard’s features support various compliance requirements:

Requirement	Feature
Data integrity	SHA-256 checksums for all files
Access control	Scoped API keys, tenant isolation
Audit trail	Comprehensive audit logging
Data retention	Soft delete, configurable retention
Malware protection	ClamAV virus scanning