Skip to main content

ConcurrencyGuard (cguard)

PyPI version Python Version License: MIT GitHub

v2.3.0 — Enterprise-Grade Semantic SAST Platform & Headless Runtime Race Verifier for Python.

Natively securing FastAPI, Django ORM, SQLAlchemy, Celery, Redis, asyncio, and multi-threaded Python systems.

ConcurrencyGuard Demo


The Problem vs. The cguard Solution

Traditional code security tools are fundamentally blind to concurrency. Syntax linters only check stylistic conventions, while generic SAST tools search for string-based regex patterns. Large Language Model (LLM) reviewers are non-deterministic, suffer from token context fragmentation, fail to trace cross-file data flow, and cannot mathematically execute code.

concurrency-guard (cguard) is a zero-cost, deterministic, 100% offline Semantic SAST platform. It combines inter-procedural AST call-graph traversal and semantic data-flow taint analysis with an empirical runtime stress engine to catch, prove, and patch race conditions in milliseconds.

Vulnerability Vector Linters (Ruff, Flake8) AI / LLM Reviewers cguard Semantic SAST
SQLAlchemy Unlocked RMW (CG-001) ❌ Blind to DB semantics ⚠️ Hallucinates, misses context ✅ Deterministic AST detection
Django ORM Unlocked RMW (CG-016) ❌ Ignored ⚠️ Misses ORM transaction scope ✅ AST select_for_update audit
Missing Idempotency Headers (CG-002) ❌ Ignored ⚠️ High latency, non-deterministic ✅ Sub-millisecond AST verification
Async Loop N+1 Explode (CG-003) ❌ Unchecked ⚠️ Inconsistent pattern matching ✅ Local control-flow AST traversal
Check-Then-Act Uniqueness Races (CG-004) ❌ Ignored ⚠️ Frequently missed ✅ Catch-integrity validation
Celery Retry Duplication (CG-005) ❌ Ignored ⚠️ Misses task retry mechanics ✅ Decorator & kwarg audit
Async & Threaded State Mutation (CG-006, CG-007) ❌ Ignored ⚠️ Fails on non-local globals ✅ Context-manager lock analysis
File I/O & Tempfile Races (CG-009, CG-010) ❌ Ignored ⚠️ Ignores multi-worker I/O ✅ Filesystem concurrency analysis
Redis / Cache Check-Then-Act (CG-011, CG-012) ❌ Ignored ⚠️ Recommends fragile locks ✅ Atomic primitive audit (SET NX)
Lock-Order Deadlocks (CG-013) ❌ Ignored ❌ Incapable of graph analysis ✅ Bipartite lock hierarchy audit
Cross-File Inter-Procedural Races (CG-014) ❌ Single-file only ❌ Exceeds token context window ✅ Project-wide Call-Graph engine
Abstracted Tainted Shared State (CG-015) ❌ Ignored ⚠️ Hallucinates variable scope ✅ Semantic data-flow taint tracking
Empirical Exploit Verification ❌ None ❌ Cannot execute code ✅ Barrier stress engine (HTTP & Headless)
Deterministic Code Remediation ⚠️ Style fixes only ⚠️ Introduces syntax regressions ✅ Zero-regression LibCST patcher

Why cguard? The Architectural Difference

concurrency-guard does not use naive regexes or brittle token searches. It parses and analyzes Python code using enterprise-grade architectural pillars:

flowchart TD
    A["Source Codebase (.py)"] --> B["Incremental SQLite Cache / AST Scanner"]
    B --> C["Tokenized # cg:ignore Filter"]
    C --> D["Inter-Procedural Call Graph Engine"]
    C --> E["Semantic Data-Flow & Deep Alias Tracker"]
    D --> F["Deterministic Findings (CG-001 to CG-016)"]
    E --> F
    F --> G["Headless Runtime Verifier (Barrier Engine)"]
    F --> H["Non-Destructive In-Memory Diff (--diff)"]
    F --> I["Preflight Syntax-Validated Patcher (--write)"]
    G --> J["Empirical Exploit Proof"]
    H --> K["Lossless Patch Review"]
    I --> L["Safe Patched Source"]

1. Inter-Procedural Call Graph Analysis (CG-014)

Real-world concurrency bugs rarely live in a single 10-line function. A web route often delegates to a service layer, which delegates to a repository layer, which mutates a module-level dictionary or shared cache. cguard constructs a project-wide call graph, resolving imported aliases and module symbols across your entire repository. If an endpoint or async worker triggers an unguarded mutation anywhere down the call chain, cguard flags the exact path without executing a single line of application code.

2. Data-Flow Semantic Taint Tracking (CG-015)

When shared state (globals, class-level caches, Redis connections, or singleton pools) is passed across variable assignments, aliased through local dictionaries, or unpacked into parameters, simple AST pattern matchers lose track. cguard employs a forward data-flow taint tracker that labels mutable shared references at their origin and propagates taint through assignments, attribute lookups, and function calls. An issue is raised if a tainted reference reaches an unguarded mutation sink (AugAssign, .append(), .pop(), .set(), .update()).

3. Deep Alias & Context-Aware Lock Detection (CG-006, CG-016)

cguard dynamically tracks stateful variable aliases (wallet → w1 → w2) across local function scopes. Tainted database queries or shared objects maintain their vulnerability provenance across reassignments and immediately trigger findings on in-place mutations (w.balance -= 50). Context-aware lock tracking audits with and async with block lifecycles—suppressing false positives when shared collections are protected inside async with lock: and enforcing that Django row locks are actively held inside with transaction.atomic():.

4. Incremental SQLite Caching Engine (cguard scan --cache)

For enterprise monorepos and high-frequency CI pipelines, cguard provides an incremental scanning cache backed by a thread-safe SQLite database (.concurrency_guard_cache.db). Scan keys are computed via SHA-256 hashes of file contents, scanner engine version, and active rules configuration. Unchanged source files skip AST parsing entirely, accelerating repository-wide scans down to sub-millisecond execution.

5. Inline # cg:ignore Directive Engine

False positives and intentional low-level synchronization patterns can be suppressed directly in source code using Python's standard tokenize module. cguard accurately ignores directives inside comments without mistaking docstrings or string literals:

  • Line-level: wallet.balance -= 50 # cg:ignore[CG-016] rationale="Protected upstream"
  • Block-level: # cg:ignore-start[CG-006] ... # cg:ignore-end[CG-006]
  • File-level: # cg:ignore-file[CG-001, CG-002]

6. Non-Destructive In-Memory Diffs & Preflight AST Validation (cguard fix --diff)

Review automated security patches without touching files on disk. cguard fix --diff (or --dry-run) generates standard colorized unified diffs in memory using difflib. Before displaying or applying any patch, a preflight syntax validator parses the modified AST with ast.parse(); if a syntax error or code corruption is detected, the patch is safely aborted and discarded.

7. Headless Runtime Stress Verification (cguard verify --headless)

Static analysis identifies potential hazards; cguard's verification engine mathematically proves them. You no longer need a running web server or live database. cguard verify dynamically imports raw Python callables, initializes synchronized barriers (asyncio.Barrier for coroutines or threading.Barrier for OS threads), and releases up to 100 concurrent workers at the exact same microsecond. By comparing the observed post-execution state against mathematical expectations, it confirms race conditions (such as balance double-spends or lost updates) with zero false alarms.

8. Lossless LibCST Auto-Patching (cguard fix --write)

Fixing security bugs by hand introduces syntax errors and disrupts formatting. cguard uses Concrete Syntax Tree (libcst) manipulation to safely modify code in place. It injects required locks (.with_for_update(), Django select_for_update(), asyncio.Lock, threading.Lock, or filelock.FileLock), wraps vulnerable mutations in synchronization contexts, and adds error guards while 100% preserving your comments, docstrings, indentation, and formatting.


Installation

pip install concurrency-guard

Requires Python 3.10+ (analyzes and patches Python 3.9+ codebases).


Quick Start

1. Scan your codebase

Run deterministic static analysis across a single file or an entire multi-package repository in milliseconds:

# Scan a specific file
cguard scan app/routers/wallet.py

# Scan an entire repository (auto-excludes .venv, migrations, and build caches)
cguard scan src/

# Run with sub-millisecond SQLite incremental caching
cguard scan src/ --cache

# Output structured JSON for CI/CD pipelines
cguard scan src/ --format json

2. Suppress intentional designs with inline # cg:ignore

Silence false positives or intentional low-level synchronization cleanly in code:

# Line-level ignore
wallet.balance -= 50  # cg:ignore[CG-016] rationale="Locked upstream in orchestrator"

# Multi-rule block-level ignore
# cg:ignore-start[CG-006, CG-007]
shared_cache[key] = val
# cg:ignore-end[CG-006, CG-007]

# Entire file ignore (e.g. at top of tests or legacy modules)
# cg:ignore-file[CG-001]

3. Verify race conditions empirically

Prove vulnerabilities at runtime using synchronized barrier stress-testing.

Option A: FastAPI & SQLAlchemy Endpoint Verification

cguard verify examples/vulnerable_wallet.py --workers 20
❌ CONCURRENCY INVARIANT VIOLATED (RACE PROVEN)
Target Endpoint: POST /wallet/withdraw
Concurrent Barrier Workers: 20
Initial Balance: $50
Successful Withdrawals ($50 each): 20
Final Resulting Balance: $-950 (Double-spend exploit confirmed!)

Option B: Headless Function Verification (No HTTP / No Framework)

Stress-test any raw Python async function or thread target directly in memory:

cguard verify worker.py --headless --function update_shared_state --workers 50
❌ HEADLESS CONCURRENCY INVARIANT VIOLATED
Target Function: worker.py::update_shared_state
Synchronization Engine: asyncio.Barrier (50 workers)
Expected Increments: 50
Observed State Value: 14 (Lost 36 state updates due to unguarded RMW race!)

4. Review non-destructive diffs and auto-patch in-place

Preview colorized unified diffs safely in memory, then apply syntax-validated fixes:

# Preview the unified diff in memory without touching disk (dry-run)
cguard fix app/routers/wallet.py --diff

# Apply preflight syntax-validated fixes directly to files
cguard fix app/routers/wallet.py --write

Supported Vulnerability Rules

concurrency-guard comes out of the box with 16 enterprise-grade security rules covering web frameworks, ORMs, asynchronous concurrency, multi-threading, and distributed tasks:

Rule ID Vulnerability Vector Framework / Subsystem Trigger Condition Automated Remediation (LibCST)
CG-001 Unlocked Read-Modify-Write Race SQLAlchemy / FastAPI Route reads state (select, db.scalar, session.get), mutates an attribute, and commits without row locking. Appends .with_for_update() to query chain.
CG-002 Missing Idempotency Guard on POST FastAPI / Web APIs Mutating @app.post / @router.post performs DB writes without an Idempotency-Key header. Injects Idempotency-Key header parameter into route signature.
CG-003 Async Loop N+1 Query Explode SQLAlchemy 2.0 / AsyncIO Queries (.execute(), .scalar(), .get()) executed directly inside a for or async for loop body. Flags query explosion; suggests eager loading (selectinload).
CG-004 Check-Then-Act Uniqueness Race SQLAlchemy / Databases Query checks record existence, calls db.add(), and commits without handling IntegrityError. Wraps commit in try...except IntegrityError with rollback.
CG-005 Non-Idempotent Celery Retry Task Celery / Distributed Queues Retrying Celery task executes database commits or external POST calls without acks_late=True or deduplication lock. Recommends acks_late=True and distributed idempotency lock.
CG-006 Async Shared-State Mutation asyncio Standard Library Coroutine mutates module-level collection (list, dict, set) without an asyncio.Lock context. Injects asyncio.Lock() and wraps mutation in async with.
CG-007 Threaded Collection Mutation threading Standard Library Multi-threaded target modifies shared built-in state without a threading.Lock / RLock. Injects threading.Lock() and wraps mutation in with lock:.
CG-008 Generic Read-Modify-Write Race Core Python Memory Subscript or attribute read into local variable, transformed, and reassigned without synchronization. Recommends atomic operation or lock-guarded block.
CG-009 Concurrent File Write Race Filesystem / File I/O Concurrent writes via open() or aiofiles.open() in write/append mode without a file lock. Wraps file context in filelock.FileLock.
CG-010 Insecure Shared Tempfile Race Filesystem Security Hard-coded or predictable path used under /tmp across concurrent execution contexts. Recommends task-isolated tempfile.NamedTemporaryFile.
CG-011 Cache Check-Then-Act Race Redis / Memcached Cache key read (get()) followed by conditional write (set()) without atomic primitives. Recommends Redis SET key value NX or Lua scripting.
CG-012 Non-Atomic Cache Invalidation Distributed Caching Database write committed before or after cache deletion without transactional synchronization. Recommends two-phase cache invalidation or atomic write-through.
CG-013 Lock-Order Inversion Deadlock Concurrency Primitives Multiple locks acquired in opposing hierarchical order across functions or modules. Identifies cycle and establishes strict global acquisition order.
CG-014 Inter-Procedural Call-Chain Race Cross-Module Architecture Local route or worker calls an imported function whose transitive call-chain mutates shared state without a lock. Traces full cross-file call graph to the mutation sink.
CG-015 Tainted Shared-State Mutation Semantic Data Flow Mutable reference to global/singleton/cache state passes through aliases or args into an unguarded mutation. Traces taint propagation and isolates unprotected mutation sink.
CG-016 Django ORM Unlocked RMW Race Django ORM Django query (objects.get(), filter().first()) mutated and saved without select_for_update(). Injects .select_for_update() inside transaction.atomic().

Custom Rules (YAML DSL)

Define bespoke concurrency and state-management policies for proprietary internal clients, distributed caches, or company microservices without writing code.

Create a concurrency-rules.yml file:

rules:
  - id: ACME-001
    description: "Acme wallet balance updates must acquire the tenant lock"
    function: "acme_wallet.deduct"
    modifies: "wallet.balance"
    without_context: "tenant_lock"
    message: "Tenant balance mutation must be protected with `async with tenant_lock:`"
    fix: "Wrap balance deduction in `async with tenant_lock:`"

  - id: ACME-002
    description: "Internal Redis credit allocation must use Lua scripts"
    call: "redis_client.set"
    variable: "user_credits"
    without_lock: "redis_dist_lock"
    message: "Direct credit set detected. Use atomic Lua script or acquire `redis_dist_lock`."

Scan using your custom rules:

cguard scan src/ --rules concurrency-rules.yml

CI/CD Pipeline Integration

Enforce zero concurrency vulnerabilities on every pull request using the official GitHub Action or CLI reporter:

GitHub Actions (.github/workflows/cguard.yml)

name: Concurrency Security Scan

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  cguard-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: pip install concurrency-guard

      - name: Run ConcurrencyGuard Scan
        run: cguard scan src/

      - name: Generate PR Markdown Report
        if: failure()
        run: cguard report src/ >> $GITHUB_STEP_SUMMARY

Source and Releases

Source code, issue tracking, and roadmap are maintained at:
👉 github.com/AyushkhatiDev/concurrency-guard


License

Distributed under the MIT License. See LICENSE for details.

Metadata

Release files for concurrency-guard 2.3.0

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

Source distribution (sdist)

Source distribution for concurrency-guard 2.3.0
File Size Uploaded Provenance Actions
concurrency_guard-2.3.0.tar.gz 17.4 MB Without provenance Details for concurrency_guard-2.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for concurrency-guard 2.3.0
File Interpreter ABI Platform Actions
concurrency_guard-2.3.0-py3-none-any.whl Python 3 none any Details for concurrency_guard-2.3.0-py3-none-any.whl

Total release size: 17.5 MB

Release files / concurrency_guard-2.3.0.tar.gz

Download URL concurrency_guard-2.3.0.tar.gz
Size 17.4 MB
Tags Source
SHA-256 checksum
How to use checksums
4ee0bf8a74a575b4b0185ce8aef7df6b52128903bf5660ff2edff8a30a810a08
BLAKE2b-256 checksum
How to use checksums
381af42914cf08a7699c076e634157ad29ed27f807de6e48da3676d5a707d7d0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / concurrency_guard-2.3.0-py3-none-any.whl

Download URL concurrency_guard-2.3.0-py3-none-any.whl
Size 59.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4395d0aca1bc33731aff1953b34d3fe921bb0b24db58fdf381c822c7ed473c53
BLAKE2b-256 checksum
How to use checksums
a061bdda8515b91c251dcf329b146f59be98e3979bf2a5838d63e289f3494c1b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for concurrency-guard 2.3.0

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.

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