Skip to main content

secfn Python SDK

Comprehensive self-hosted security platform for Python developers

Python implementation of secfn providing secrets management, access control, rate limiting, security monitoring, and secret scanning.

Overview

secfn is a comprehensive security toolkit that provides:

  • Secrets Vault: Encrypted secret storage with AES-256-GCM, rotation, and access logging
  • Access Control (RBAC): Role-based permissions with wildcard matching and caching
  • Rate Limiting: Token bucket algorithm with per-user, per-IP, and per-endpoint limits
  • Security Monitoring: Event logging, metrics, and anomaly detection
  • Secret Scanning: Detect hardcoded secrets in code with pattern matching

Installation

pip install secfn

Quick Start

1. Create SecFn Instance

from secfn import create_secfn, SecFnConfig

secfn = create_secfn(
    SecFnConfig(
        master_key="your-secure-master-key",
        storage_path=".secfn",
    )
)

2. Secrets Vault

# Create vault
vault = secfn.create_secrets_vault()

# Store a secret
await vault.set("stripe_api_key", "sk_live_...", options={
    "tags": ["payment", "production"],
    "environment": "production",
    "rotateEvery": 90 * 24 * 60 * 60 * 1000,  # 90 days
})

# Retrieve secret
api_key = await vault.get("stripe_api_key")

# List secrets (without values)
secrets = await vault.list(filter={"environment": "production"})

# Rotate secret
await vault.rotate("stripe_api_key", "sk_live_new...")

# Get access log
log = await vault.get_access_log("stripe_api_key", limit=100)

3. Access Control (RBAC)

# Create access control
access = secfn.create_access_control()

# Create roles
admin_role_id = await access.create_role(
    name="admin",
    permissions=["*:*"],
    description="Full system access"
)

editor_role_id = await access.create_role(
    name="editor",
    permissions=["project:read", "project:write", "file:read", "file:write"],
    description="Can edit projects and files"
)

# Assign role to user
await access.assign_role(
    user_id="user_123",
    role_id=editor_role_id,
    resource_ids=["project_abc", "project_def"]
)

# Check permission
from secfn import AccessRequest

allowed = await access.check(AccessRequest(
    userId="user_123",
    action="project:write",
    resourceId="project_abc"
))

if allowed:
    print("Access granted!")

4. Rate Limiting

from secfn import RateLimitRule

# Create rate limiter
limiter = secfn.create_rate_limiter(
    rules={
        "global": RateLimitRule(requests=1000, window=60000),
        "perUser": RateLimitRule(requests=100, window=60000),
        "perIP": RateLimitRule(
            requests=50,
            window=60000,
            blockDuration=300000  # Block for 5 minutes
        ),
    }
)

# Check rate limit
try:
    result = await limiter.check(
        user_id="user_123",
        ip="192.168.1.1",
        endpoint="/api/search"
    )
    print(f"Allowed! Remaining: {result.remaining}")
except RateLimitExceededError as e:
    print(f"Rate limit exceeded: {e}")

5. Security Monitoring

from secfn import SecurityEventType, Severity

# Create monitor
monitor = secfn.create_monitoring()

# Log security event
event_id = await monitor.log_event(
    type=SecurityEventType.AUTH_FAILURE,
    severity=Severity.MEDIUM,
    ip="192.168.1.1",
    user_id="user_123",
    resource="/api/login",
    metadata={"reason": "invalid_password"}
)

# Query events
from secfn import EventQuery

events = await monitor.query_events(EventQuery(
    type=SecurityEventType.AUTH_FAILURE,
    severity=[Severity.HIGH, Severity.CRITICAL],
    startDate=int(time.time() * 1000) - 24 * 60 * 60 * 1000,
))

# Get metrics
import time
metrics = await monitor.get_metrics(
    start=int(time.time() * 1000) - 7 * 24 * 60 * 60 * 1000,
    end=int(time.time() * 1000)
)
print(f"Total events: {metrics.total_events}")
print(f"Events by type: {metrics.events_by_type}")

6. Secret Scanning

# Create scanner
scanner = secfn.create_secret_scanner(
    exclude_paths=["node_modules/**", "*.test.py"]
)

# Scan a file
results = await scanner.scan_file("./config.py")
for result in results:
    print(f"Found {result.pattern} at {result.file}:{result.line}")
    print(f"  Severity: {result.severity}")
    print(f"  Match: {result.redacted_match}")

# Scan directory
results = await scanner.scan_directory("./src", recursive=True)
critical = [r for r in results if r.severity == Severity.CRITICAL]
print(f"Found {len(critical)} critical secrets!")

Complete Example

import asyncio
from secfn import create_secfn, SecFnConfig, Severity, SecurityEventType

async def main():
    # Initialize secfn
    secfn = create_secfn(SecFnConfig(
        master_key="my-secure-master-key",
        storage_path=".secfn"
    ))

    # Create modules
    vault = secfn.create_secrets_vault()
    access = secfn.create_access_control()
    monitor = secfn.create_monitoring()

    # Store a secret
    await vault.set("database_url", "postgresql://user:pass@localhost/db")

    # Create admin role
    admin_role = await access.create_role(
        name="admin",
        permissions=["*:*"],
        description="Administrator"
    )

    # Assign role
    await access.assign_role("user_1", admin_role)

    # Log an event
    await monitor.log_event(
        type=SecurityEventType.SECRET_ACCESSED,
        severity=Severity.INFO,
        ip="127.0.0.1",
        user_id="user_1",
        resource="database_url"
    )

    print("✓ Secrets vault, access control, and monitoring configured!")

if __name__ == "__main__":
    asyncio.run(main())

API Reference

create_secfn(config: SecFnConfig) -> SecFn

Create a SecFn instance.

SecFn

Main class with factory methods:

  • create_secrets_vault() - Create encrypted secrets vault
  • create_access_control() - Create RBAC access control
  • create_rate_limiter(rules) - Create rate limiter
  • create_monitoring() - Create security monitor
  • create_secret_scanner() - Create secret scanner

SecretsVault

  • async set(key, value, options) - Store encrypted secret
  • async get(key, user_id) - Retrieve secret
  • async list(filter) - List secrets (without values)
  • async rotate(key, new_value, user_id) - Rotate secret
  • async delete(key, user_id) - Delete secret
  • async get_access_log(key, limit) - Get access log

AccessControl

  • async create_role(name, permissions, description) - Create role
  • async assign_role(user_id, role_id, resource_ids) - Assign role
  • async check(request) - Check permission
  • async get_user_permissions(user_id) - Get user permissions
  • async get_user_roles(user_id) - Get user roles

RateLimiter

  • async check(user_id, ip, endpoint) - Check rate limit

SecurityMonitor

  • async log_event(type, severity, ip, ...) - Log event
  • async query_events(query) - Query events
  • async get_metrics(start, end) - Get metrics
  • async resolve_event(event_id, resolved_by, notes) - Resolve event

SecretScanner

  • async scan_file(file_path) - Scan file
  • async scan_directory(directory, recursive) - Scan directory

Development

# Install dependencies
make install-dev

# Run tests
make test

# Type checking
make typecheck

# Linting
make lint

# Format code
make format

License

MIT

Repository

https://github.com/21nCo/super-functions

Metadata

Release files for secfn 0.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for secfn 0.0.1
File Size Uploaded Provenance Actions
secfn-0.0.1.tar.gz 26.1 kB Without provenance Details for secfn-0.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for secfn 0.0.1
File Interpreter ABI Platform Actions
secfn-0.0.1-py3-none-any.whl Python 3 none any Details for secfn-0.0.1-py3-none-any.whl

Total release size: 53.7 kB

Release files / secfn-0.0.1.tar.gz

Download URL secfn-0.0.1.tar.gz
Size 26.1 kB
Tags Source
SHA-256 checksum
How to use checksums
58dd87aaa7de0caa90d709fc6167d6910b6e9ef88fc4dbce303791274428adbe
BLAKE2b-256 checksum
How to use checksums
654968001455f45a3c792d61cb2435c029e0e2ba5bdf79c4006fe30e143637c4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Release files / secfn-0.0.1-py3-none-any.whl

Download URL secfn-0.0.1-py3-none-any.whl
Size 27.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b663ed543d7fdab9d5e364eb5f9f021ac9881679684d5cc3c969599e9a70001a
BLAKE2b-256 checksum
How to use checksums
05564c62143ece3e9a5c136bf7b36d188fcaec99605897bcc4445ca88d111cc6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Security for secfn 0.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page