agentleFS
Pablo-Lozano-GilPablo-Lozano-Gil/battletested-agent-skills/python-security/SKILL.md

python-security

Skill3 starsChanged 8 months agoApache-2.0View on GitHub

Use when creating Python projects with Docker, handling environment variables, managing secrets, or setting up secure deployments. Trigger: when writing Dockerfiles, docker-compose files, .env files, or configuring database connections and API keys.

  • Reads credentials

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. jim60105/copilot-prompt★ 22same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository6 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Revoke old secret: after grace period

    line 412
  2. Very specific:

    UV lock file: - Commit uv.lock, use --frozen in CI

    line 539
  3. Distinctive:

    Mask in logs: - Never log raw secrets, passwords, tokens

    line 540

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Python Security Best Practices

Overview

Core Principle: Secrets NEVER go into git. Not in Dockerfile, not in docker-compose.yml, not in any committed file. Environment variables are for runtime, not build time.

This skill covers: environment variables (python-dotenv), UV package manager, Docker security, .gitignore, logging security, input validation, secrets rotation, and production secrets management.

Red Flags - STOP Immediately

  • Hardcoding passwords, API keys, or tokens in ANY file that goes to git
  • "It's just for development" excuses
  • Putting secrets in Dockerfile ENV or ARG
  • Passwords in docker-compose.yml under environment:
  • Logging sensitive data "for debugging"
  • "I'll fix it later" when it comes to secrets

All of these mean: STOP. Delete the secrets. Start over with proper patterns.

Quick Reference

CategoryDODON'T
Environment.env in .gitignore, load with python-dotenvCommit .env, hardcode in Python
DockerPass secrets at runtime via env varsPut secrets in Dockerfile ENV/ARG
Compose${VAR:-default} syntax, .env fileHardcode passwords in environment:
GitComprehensive .gitignoreAssume "I won't accidentally commit"
LoggingMask/omit secrets, use structured loggingLog raw os.environ, passwords, tokens
UVCommit uv.lock, use --frozen in CIIgnore lock file, floating versions
ProductionSecrets manager (Vault, AWS, etc.)Files on disk, environment in images

1. Environment Variables with python-dotenv

Basic Pattern

# config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str
    openai_api_key: str
    secret_key: str

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"

settings = Settings()

.env Files

# .env.example (commit to git - TEMPLATE ONLY with <placeholders>)
DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<database>
OPENAI_API_KEY=<your-openai-api-key>
SECRET_KEY=<your-secret-key-min-32-chars>

# .env (NEVER commit - actual secrets)
DATABASE_URL=postgresql://realuser:realpass@prod-db.example.com/proddb
OPENAI_API_KEY=sk-prod-abc123xyz789
SECRET_KEY=super-secret-production-key-42

Critical: .env.example shows STRUCTURE, not real values. Use obvious placeholders.


2. UV Best Practices

Project Setup

# Initialize project
uv init
uv add fastapi uvicorn pydantic-settings

# Generate/update lock file - RUN THIS after adding dependencies
uv lock

# uv.lock MUST be committed to git for reproducible builds
git add uv.lock

Docker with UV

FROM python:3.12-slim

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app

# Install dependencies FIRST (cached layer)
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project --no-dev

# Copy and install project
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-dev

# Non-root user
RUN useradd --create-home --shell /bin/bash app
USER app

ENV PATH="/app/.venv/bin:$PATH"
CMD ["uvicorn", "main:app", "--host", "0.0.0.0"]

CI/CD with UV

# In CI - fail if lock is outdated
uv sync --frozen

# Or with frozen flag
uv run --frozen python -m pytest

Key: --locked fails if uv.lock needs update. --frozen prevents network access. Use in CI.


3. Docker Without Secrets

The Rules

  1. NO secrets in Dockerfile - ENV API_KEY=xxx is forever in image layers
  2. NO secrets in build args - ARG PASSWORD is visible in docker history
  3. NO secrets in docker-compose environment hardcoded - That file goes to git

Correct Pattern: Runtime Injection

# docker-compose.yml
services:
  app:
    build: .
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - SECRET_KEY=${SECRET_KEY}
    env_file:
      - .env  # Local dev only - .env should be in .gitignore

  db:
    image: postgres:15
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-postgres}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}  # NO default for passwords!
      POSTGRES_DB: ${POSTGRES_DB:-appdb}

.dockerignore

# .dockerignore - Prevent secrets from entering build context
.env
.env.*
*.pem
*.key
credentials.json
secrets.*
.git
.gitignore
__pycache__
.venv
*.pyc
.pytest_cache
.ruff_cache

4. Robust .gitignore

# Secrets - NEVER commit these
.env
.env.local
.env.*.local
*.pem
*.key
*.crt
credentials.json
secrets.*
secrets.yaml
secrets.yml
service-account.json
*.p12
*.pfx

# Python
__pycache__/
*.py[cod]
*$py.class
.venv/
venv/
*.so
.Python
build/
dist/
*.egg-info/

# IDE
.vscode/
.idea/
*.swp
*.swo

# Testing
.pytest_cache/
.coverage
htmlcov/
.tox/

# UV - IMPORTANT: uv.lock SHOULD be committed!
# Only ignore the cache
.uv/

# OS
.DS_Store
Thumbs.db

Note: uv.lock MUST be committed. It ensures reproducible builds.


5. Secure Logging

Wrong - Leaks Secrets

# BAD - Logs entire config including secrets
import logging
logging.info(f"Config: {settings.dict()}")

# BAD - Logs environment variables
import os
logging.info(f"Environment: {dict(os.environ)}")

# BAD - Logs database URL with password
logging.info(f"Connecting to: {settings.database_url}")

Correct - Masked Logging

import logging
from pydantic_settings import BaseSettings
from pydantic import field_validator

class Settings(BaseSettings):
    database_url: str
    openai_api_key: str
    secret_key: str

    @field_validator('database_url')
    @classmethod
    def mask_password(cls, v: str) -> str:
        # For logging only - mask password
        import re
        return re.sub(r'://([^:]+):([^@]+)@', r'://\1:****@', v)

    def safe_dict(self) -> dict:
        """Returns dict with secrets masked"""
        return {
            "database_url": self.mask_password(self.database_url),
            "openai_api_key": f"{self.openai_api_key[:8]}...",
            "secret_key": "***MASKED***"
        }

settings = Settings()
logging.info(f"Config loaded: {settings.safe_dict()}")

Structured Logging Pattern

import logging
import structlog

logger = structlog.get_logger()

# Good - explicit, intentional logging
logger.info("database_connected", host=db_host, port=db_port)
logger.info("api_request", endpoint="/users", method="GET")

# Never log: passwords, tokens, api keys, personal data

6. Input Validation

Basic Validation with Pydantic

from pydantic import BaseModel, field_validator, HttpUrl
import re

class UserInput(BaseModel):
    username: str
    email: str
    file_path: str | None = None

    @field_validator('username')
    @classmethod
    def validate_username(cls, v: str) -> str:
        if not re.match(r'^[a-zA-Z0-9_]{3,20}$', v):
            raise ValueError('Username must be 3-20 alphanumeric chars')
        return v

    @field_validator('email')
    @classmethod
    def validate_email(cls, v: str) -> str:
        if '@' not in v:
            raise ValueError('Invalid email format')
        return v.lower()

    @field_validator('file_path')
    @classmethod
    def prevent_path_traversal(cls, v: str | None) -> str | None:
        if v is None:
            return v
        if '..' in v or v.startswith('/'):
            raise ValueError('Path traversal detected')
        return v

SQL Injection Prevention

# BAD - SQL injection vulnerable
cursor.execute(f"SELECT * FROM users WHERE id = {user_input}")

# GOOD - Parameterized queries
cursor.execute("SELECT * FROM users WHERE id = %s", (user_input,))

# GOOD - With SQLAlchemy
from sqlalchemy import text
result = db.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_input})

Command Injection Prevention

import shlex
import subprocess

# BAD - Command injection vulnerable
subprocess.run(f"convert {filename} output.png", shell=True)

# GOOD - Use list args (no shell interpretation)
subprocess.run(["convert", filename, "output.png"], check=True)

# GOOD - If shell needed, use shlex.quote
subprocess.run(f"convert {shlex.quote(filename)} output.png", shell=True, check=True)

7. Secrets Rotation Strategy

Design for Rotation

class Settings(BaseSettings):
    # Support multiple API keys for rotation
    openai_api_key: str
    openai_api_key_backup: str | None = None

    def get_api_key(self) -> str:
        """Returns active key, supports rotation"""
        return self.openai_api_key

    def rotate_key(self, new_key: str) -> None:
        """Rotate API key without downtime"""
        self.openai_api_key_backup = self.openai_api_key
        self.openai_api_key = new_key

# In production, use a secrets manager that supports rotation

Rotation Checklist

  1. Generate new secret in secrets manager
  2. Deploy with new secret (old still valid)
  3. Verify new secret works
  4. Revoke old secret after grace period
  5. Monitor for failures - catch services still using old secret

Database Password Rotation

# Support read-only connection during rotation
database_url: postgresql://app:password@db/app
database_url_readonly: postgresql://app_ro:ro_password@db/app

8. Production Secrets Management

Never Use .env in Production

# BAD - .env files in production
from dotenv import load_dotenv
load_dotenv()  # Never do this in production

# GOOD - Load from environment (set by orchestrator)
import os
api_key = os.environ.get("OPENAI_API_KEY")

# BETTER - Use secrets manager SDK

AWS Secrets Manager

import boto3
import json

def get_secret(secret_name: str, region: str = "us-east-1") -> dict:
    client = boto3.client("secretsmanager", region_name=region)
    response = client.get_secret_value(SecretId=secret_name)
    return json.loads(response["SecretString"])

# Usage
secrets = get_secret("prod/myapp/database")
database_url = secrets["database_url"]

HashiCorp Vault

import hvac

client = hvac.Client(url="https://vault.example.com")
client.auth.approle.login(
    role_id=os.environ["VAULT_ROLE_ID"],
    secret_id=os.environ["VAULT_SECRET_ID"]
)

secret = client.secrets.kv.v2.read_secret_version(path="myapp/database")
database_url = secret["data"]["data"]["database_url"]

Environment Variable Pattern (Kubernetes/GitLab CI/etc.)

# Kubernetes Secret
apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
type: Opaque
stringData:
  DATABASE_URL: "postgresql://..."
  OPENAI_API_KEY: "sk-..."
---
# Deployment
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: app
          envFrom:
            - secretRef:
                name: app-secrets

Common Rationalizations (And Why They're Wrong)

ExcuseReality
"It's just a demo"Demos become prototypes become production. Start right.
"I'll fix it later"Later never comes. The commit with the password is forever.
"It's only in docker-compose"docker-compose.yml goes to git. Password is in history forever.
"The repo is private"Private repos get cloned, leaked, sold. Treat all repos as public.
"It's for local dev only"Dev environments have real data. Local databases get production dumps.
"The password is in .env"Great! But you also put it in docker-compose environment section.
"I'll use .env.example".env.example with real password patterns teaches bad habits.
"It's just a test API key"Test keys become prod keys. Habits compound.

Checklist Before Any Commit

# 1. Check for secrets accidentally staged
git diff --cached | grep -i -E "(password|secret|api_key|token)"

# 2. Verify .gitignore is working
git status --porcelain | grep -E "\.env|\.pem|\.key|credentials"

# 3. Check docker-compose for hardcoded secrets
grep -E "POSTGRES_PASSWORD|MYSQL_ROOT_PASSWORD|API_KEY" docker-compose.yml

# 4. Verify no secrets in Dockerfile
grep -E "ENV.*=.*[" dockerfile | grep -v "ENV PATH\|ENV PYTHON"

# 5. If any match found, STOP and fix before commit

TL;DR

  1. Never commit secrets - .env in .gitignore, templates in .env.example
  2. Runtime injection only - Docker gets secrets from env vars, not from files
  3. UV lock file - Commit uv.lock, use --frozen in CI
  4. Mask in logs - Never log raw secrets, passwords, tokens
  5. Validate all inputs - Pydantic, parameterized queries, no shell=True
  6. Design for rotation - Support multiple keys, grace periods
  7. Production: secrets manager - AWS, Vault, Kubernetes secrets - not files

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.