Django Chainsaw

Endpoints anyone can call that cost a great deal to answer. Two facts, each of which is somebody else's finding and neither of which is wrong alone: GET /orders has no authentication. GET /orders issues about 2852 queries per request. The first is right on a public catalogue. The second, behind a login, is a backlog item. Together they are one request, from anyone, that costs the database three thousand queries - and every one of them returns 200, so nothing in the logs looks like an attack. The other half is the unbounded list: public, unpaginated, and therefore the whole table in one request. That is not load, it is exfiltration. The tools that look for this are DAST scanners; they need the service running, reachable and holding enough rows for the cost to show. All of it is in the source. Works on Django (DRF views) and FastAPI. Args: search_path: directory to scan. Defaults to the configured project.

The shape every serializer currently promises its clients. Field names, types, whether each is read only, required, nullable, and what the nested ones expand to. Resolved from the class definitions, so nothing needs to run and no request needs to be sent. Capture this on the branch you already shipped, commit the result, and api_contract_check will tell a later branch what it broke. Args: max_depth: how far to expand nested serializers.

What this branch changes about the API, and who it breaks. Removing a serializer field is a one line diff that reads as tidying up. The client on a version nobody updated still reads that field. Every tool that catches this needs the app running: drf-api-checker records real responses during a test run, OpenAPI diffing needs the schema generated. Changes come back sorted by who they hurt. Breaking means an existing client stops working: a field it reads disappears, a field it omits becomes required, a type or a constraint narrows. Risky means it still parses but the values may surprise it. Additive means nobody notices. Args: snapshot_path: the committed contract to compare against. update: overwrite the snapshot with the current shape instead of comparing. Do this once you have decided a change is intended. max_depth: how far to expand nested serializers.

Synchronous calls that run on the event loop. FastAPI runs an `async def` endpoint on the loop itself and a `def` endpoint in a threadpool. So a blocking call inside `async def` does not slow one request, it stops every request in the process - invisible at one request a second, an outage at two hundred. ruff's ASYNC rules cover open, time.sleep and subprocess inside an async function. This adds the two that matter more: a synchronous database call, which is the common one, and a blocking call reached through another project function, where nothing at the call site looks blocking. The second comes back with the path that reaches it. Needs no Django. A `def` endpoint is never reported, because blocking in a threadpool is fine and telling somebody to make it async causes the outage. Args: search_path: directory to scan. Defaults to the configured project. follow_calls: also report blocking reached through a project function. max_depth: how many calls deep to follow.

Bulk writes that skip everything the model's save() chain promised. what_happens_on says saving an Order creates an Invoice. That is true for order.save() and false for Order.objects.bulk_create(), .bulk_update() and .update(): they go straight to SQL, so no save() override runs and no pre_save/post_save receiver fires. Django documents this in one sentence per method; nothing at the call site says it. The finding is not "bulk_create bypasses signals" but this call, on this model, skips these named effects - the receivers, the overridden save(), the models that would have been written, transitively. A cache that never gets invalidated and a search index that quietly drifts are both this. Only models whose chain does something are reported. QuerySet.delete() is not listed: Django sends delete signals per object, so that chain fires. Args: search_path: directory to scan. Defaults to the project root. model: restrict to one "app_label.ModelName".

Model instances handed to Celery tasks, and calls whose arity is wrong. order = Order.objects.get(pk=pk) send_confirmation.delay(order) The worker does not get that order. It gets whatever the serialiser made of it, rehydrated later on another machine: the row may have changed in between, the whole object crosses the broker, and under the JSON serialiser - the default since Celery 4 - it may not encode at all. Pass the primary key and let the task load it. Also reports a dispatch whose argument count cannot match the task. Celery's strict_typing catches that at call time, which for a nightly job or an error branch means in production, months later. flake8-pie has Celery lints for names, crontab arguments and expirations. None of them look at what is passed. A dispatch is only checked when the name resolves to a task this project defines, through the file's own imports - matching on the bare name reported unrelated objects of the same name against the task's signature. Args: search_path: directory to scan. Defaults to the configured project.

Run every analysis and return one severity-sorted list. The single call to reach for on an unfamiliar project. It runs the checks whose findings are defects, merges them, and sorts by severity, instead of making you know which of a dozen tools to ask for. A check that fails to run is listed in `checks_failed` rather than counted as clean. This is the one slow call here - a minute or more on a large project - and it reports progress as each check starts, so a client can name the check that is running instead of showing nothing for a minute. Args: tenant_root: the model that owns data, for the ownership check. only: run just these checks. skip: run everything except these.

Literals compared against a field whose `choices` will never match them. STATUS = [("canceled", "Canceled"), ...] Order.objects.filter(status="cancelled") Two Ls. Valid Python, valid SQL, zero rows, no exception, wrong forever. Nothing in Django objects: `choices` is checked by `full_clean()`, which a queryset never calls and `create()` never calls either - so the write side is worse, and puts a value in the column the application does not believe exists. No existing tool finds this: django-stubs types the field as `str` rather than a Literal union of its choices, so mypy is satisfied, and the DJ rules do not read the model registry. Only literals are checked - an enum member is the spelling that cannot go wrong - and only equality and `in`, because `iexact` can legitimately match a differently spelled value. `order.status == "..."` names no model, so it is reported only when the literal is wrong for every model with a field of that name. Args: search_path: directory to scan. Defaults to the configured project. include_tests: also scan test files.

URL names and template names that nothing will resolve. return redirect("order-detial") return render(request, "shop/order_detial.html", context) {% url 'shop:order-detial' order.pk %} Each of these is resolved while serving a request and checked by nothing before then. Rename a URL pattern or move a template and they keep importing, keep passing every test that does not walk that branch, and raise NoReverseMatch or TemplateDoesNotExist the first time a real person opens the page - on the path nobody was watching. Both sides use the project's own machinery: names come from every URLconf in the project walked through each include(), so namespaces are real and a second URLconf served by host is not mistaken for a missing one; templates go through get_template(), so the project's loaders decide. `by_name` groups the findings, because one missing name used in thirty-five places is one problem. Args: search_path: directory to scan. Defaults to the configured project. include_templates: also read `{% url %}`, `{% include %}` and `{% extends %}` out of the templates. include_tests: also scan test modules. Off by default: tests run under their own settings, so a name missing from these ones may be registered under theirs.

Naive datetimes in code, and ambiguous defaults on model fields. With USE_TZ on, code that builds its own datetimes with datetime.now() or from parts produces naive values, and mixing them with the aware ones the ORM returns either raises or compares against the wrong instant. It is invisible for ten months and shows up on the two nights the clock moves. Also reports model fields whose default is naive, whose default was evaluated once at import time, or that set auto_now and auto_now_add together. Args: search_path: directory to scan. Defaults to the project path.

Relations that were prefetched and then re-queried anyway. A prefetched related manager answers `.count()`, `.exists()`, `.all()` and a slice from its cache. Anything else goes back to the database, once per parent object, with the prefetch query already paid for on top: orders = Order.objects.prefetch_related("lines") for order in orders: for line in order.lines.filter(active=True): # one query per order That costs more than never prefetching at all, and it reads like an optimisation, which is why it survives review. Reported only where the prefetch and the accessor are provably the same object - bound in the same scope, or the loop variable iterating it. `nplusone` finds the neighbouring problem, an eager load nothing touches, at runtime; `unused_eager_loading` answers that one statically for DRF. Args: search_path: directory to scan. Defaults to the configured project. include_tests: also report inside test files.

Show what deleting one row of a model would take with it. Follows on_delete across the whole model graph: which models lose rows through CASCADE, which PROTECT relations would block the delete, and which fields get set to NULL. Reads the graph only, never the database. Args: model_label: "app_label.ModelName", e.g. "shop.Customer". max_depth: how far to follow chained cascades.

Is a pending destructive migration safe to deploy yet? A migration linter says RemoveField is backward incompatible, always. This answers the question that actually decides the deploy: has the code caught up? For every unapplied migration that removes or renames a field, model, index or constraint, the source tree is searched for code that still refers to it, and each one comes back either "blocking" with file and line numbers, or "clear". Args: search_path: directory to scan. Defaults to the configured project path. max_hits_per_symbol: stop after this many references per symbol.

How many queries one request to each endpoint will cost. Every tool that answers this runs the application and tells you afterwards: the debug toolbar, silk, assertNumQueries. The number is derivable before anything runs. One query for the page, plus one per object for every serializer field crossing a relation the view did not prefetch, plus that again per level of nesting. On the demo project the same serializer measured 2852 queries behind an unoptimised queryset and 2 behind an optimised one. The ratio is the reliable part; the absolute number is only as good as nested_fan_out. Args: page_size: objects a list response returns. nested_fan_out: assumed children per parent one level down. A property of your data that reading the code cannot reveal. list_only: skip views that only ever return a single object.

Calls inside a transaction whose effect cannot be rolled back. A transaction can be rolled back. An email cannot, and neither can a webhook or a task a worker has already picked up. with transaction.atomic(): order = Order.objects.create(...) send_confirmation.delay(order.pk) Two defects, and only one is famous. The race: the broker has the task immediately, a worker can start before the commit, and it queries for a row that is not there. It passes every test, because tests run in a transaction that never commits with a worker that runs eagerly, and it fails under load. The quieter one: if anything after that line raises, the order is gone and the customer has the email. The fix is transaction.on_commit, and calls already deferred that way are not reported. The ecosystem's answer to this is runtime wrappers; ruff and flake8-django do not look at it. Args: search_path: directory to scan. Defaults to the project root. include_low_confidence: also report calls like `.send()` that are guessed from the name, since it is also Signal.send and socket.send.

Everything known about one model, and the risks only visible combined. Start here when meeting a model for the first time. It runs the structural, ownership, deletion, signal, exposure, index and datetime checks and returns one picture instead of seven reports. The part worth reading is `correlated_risks`. Some defects exist only in the overlap and no single analyser can see them: a model that is owned, read without scoping, and serialised with fields = "__all__" is a complete path from a URL to another customer's row, while each of those three alone is just a warning. Args: model_label: "app_label.ModelName". tenant_root: the model that owns data, for the ownership half. include_raw: attach the full report from each analyser as well.

FastAPI endpoints that serialise more than they declare. @app.get("/users/{pk}") async def get_user(pk: int): return session.get(User, pk) No response_model and no return annotation, so FastAPI serialises whatever it is handed - the whole ORM object, every column, including the ones added to the model next month. The absence of one line is the entire bug, so there is nothing in the file to read or review. Every FastAPI guide says to set response_model and several say a CI rule should enforce it. No linter ships one. An endpoint returning a dict or a literal is not reported: the author decided what goes in it. Unauthenticated is critical, behind a dependency is high - it still leaks to everyone who can log in. Nothing here imports the project, because a FastAPI app usually wants a database URL and a secret before it will import at all, and none of that is needed to read a decorator. Needs no Django. Args: search_path: directory to scan. Defaults to the configured project.

Find relation traversals in a template that each cost a query. Resolves attribute chains against the real model graph and flags the ones that cross a relation inside a loop, which is where N+1 queries come from. Reports candidates: whether a crossing really costs a query depends on the queryset in the view, which this does not read. Args: template_path: path to the template file. root_models: context variable to model label, e.g. {"orders": "shop.Order"}. Loop variables inherit from these.

Find querysets that read tenant-scoped data without scoping the query. This is the shape behind most IDOR reports: a view loads an object by primary key and never checks who owns it. Generic analysers struggle because the defect is the absence of a filter, and absence has no syntax. The model graph makes it tractable: it knows Order reaches the tenant root through 'customer', so it can tell that filtering on pk alone is not enough. Candidates, not verdicts. A filter in a base class, a mixin, a custom manager or a get_queryset() override is invisible from here. Args: tenant_root: the model that owns data, e.g. "auth.User" or "shop.Customer". search_path: directory to scan. Defaults to the project path. max_depth: how many relation hops still count as owned. include_exempt: also scan admin, management commands and tests.

List the project's models with their fields and relations. Args: app_label: Restrict to one app, e.g. "shop". Omit for all apps. include_fields: Set False for a short overview without field details.

Rate migrations by what they do to a live database. Flags operations that block writes, rewrite a table, or break the code that is still running during a rolling deploy. Args: include_applied: also classify migrations that already ran.

Fields the code filters or sorts on that carry no index. Runtime tools answer this by watching real traffic, which only ever covers the paths traffic reached. Reading the source covers every path in the repository, works with no database and no traffic, and can run on a branch before it ships. The trade is that it cannot weigh anything: a filter on a forty row table looks like one on a forty million row table. It reports where an index is missing and how often the code asks for it, and leaves the decision to somebody who knows the row counts. Args: search_path: directory to scan. Defaults to the project path. min_occurrences: only report a field asked for at least this often.

Places where a decimal amount stops being exact. A DecimalField exists so that money is exact. Four things give that up, and they are not equally bad: Decimal(0.1) wrong from birth - 0.1 has no exact binary form, so this is 0.1000000000000000055... float(invoice.amount) a one-way door; everything after is approximate round(amount, 2) exact, but banker's rounding: 0.125 becomes 0.12 where an invoice expects 0.13 FloatField("price") the column itself cannot hold money Decimal(0.5) is NOT reported as a defect: that float is exactly representable and nothing is lost. The check computes the round trip, so on a real project 41 of 50 Decimal(<float>) calls came back harmless and 11 were genuinely wrong. Nothing in the linter ecosystem looks at this; the usual advice stops at the model definition and every one of these happens somewhere else. Args: search_path: directory to scan. Defaults to the project root.

Aggregates whose numbers are wrong because a join multiplied the rows. Order.objects.annotate(lines=Count("lines"), shipments=Count("shipments")) Joining two multi-valued relations gives the cartesian product of them: an order with 3 lines and 2 shipments produces 6 rows, and both counts come back as 6. Nothing raises. Two plausible numbers, both the product of the two, usually on a dashboard nobody can check by hand. Only Count and Sum are reported. A join repeats rows uniformly within each group, so Min and Max return the value they would anyway and Avg divides a multiplied total by a multiplied count - including them reported a correct query as a defect on the first real project this saw. Count(distinct=True) is treated as correct. Sum has no equivalent and needs a Subquery, so a query is still reported when every Count in it is distinct but a Sum crosses a second relation. Django's own documentation warns about this and no linter checks it. Args: search_path: directory to scan. Defaults to the configured project.

Endpoints anyone can call, crossed with what their serializer exposes. serializer_exposure knows CustomerExportSerializer leaks a password reset token; a Semgrep rule knows a view has AllowAny. Each alone is a judgement call - maybe the serializer only feeds an admin export, maybe the view serves a catalogue. Together there is nothing left to judge, and neither check can make the connection alone. DRF's own default permission is AllowAny. A project that never configured DEFAULT_PERMISSION_CLASSES has every view without explicit permission_classes open, and none of them say so; that is volunteered first. Views overriding get_permissions() are listed, not judged. Args: include_unbounded: also report open endpoints whose serializer uses fields="__all__" or exclude, even with nothing sensitive on the model today. The next migration decides what leaks.

Check that the target Django project loads, and report what it is. Run this first when something is not working. It is the smallest call that proves both halves of the setup: the MCP transport and the Django boot.

What this project is built on, without needing Django to boot. Frameworks are counted by how many of the project's own files import them, not by what is installed: a package sitting in the virtualenv that nothing imports is a fact about the environment, not the code. A project can be Django and FastAPI at once and both are reported. Use it to find out which checks can say anything here. Args: search_path: directory to scan. Defaults to the configured project.

Database work written inside a loop, split by what the fix is. The template and serializer checks here find the N+1 a framework causes. This finds the one somebody wrote by hand, which is where it lives in a codebase whose views build their responses themselves. Three shapes share one appearance and need three different fixes: Customer.objects.get(pk=order.customer_id) uses the loop variable: once per row, needs a bulk fetch or a prefetch Config.objects.get(key="vat") does not: the same question N times for the same answer, move it above the loop order.save() N round trips; bulk_update fixes it and skips signals django-check does static N+1 for relation access in a loop and is the closest existing tool; nplusone and the debug toolbar find it at runtime. The separation is what is added here. Args: search_path: directory to scan. Defaults to the configured project. include_writes: also report save()/delete() inside a loop.

Read-modify-save races, and row locks taken outside any transaction. product = Product.objects.get(pk=pk) product.stock -= quantity product.save() Two requests read 10, both subtract 3, both write 7; one sale is gone. A transaction does not help, since neither sees the other's uncommitted write. The fix is F("stock") - quantity so the database does the maths, or select_for_update() inside atomic() to hold the row - and both of those are silent here. Counters, balances, stock, retry counts: the fields where off-by-one costs money. Also: get_or_create() on a lookup no unique field, unique_together or UniqueConstraint covers - two requests miss the get together, both create, and the next call raises MultipleObjectsReturned. And select_for_update() with no atomic() around it, which is not a race but a TransactionManagementError the first time the line is reached. Whether a transaction is open is judged with the call graph, so a caller's atomic(), a decorator and ATOMIC_REQUESTS on a view all count. Args: search_path: directory to scan. Defaults to the project root. include_parameters: also report mutations of an instance passed in as a parameter, at medium confidence (the caller may hold a lock).

Every finding, grouped by the entry points that actually reach it. The other checks answer "where is this defect". A few hundred correct entries sorted by severity still does not say where to start, because risk is severity times how often the code runs and nothing in the list says whether a line is on the path of an endpoint served ten thousand times an hour or of a command last run in 2023. This runs the checks, maps each finding to the function containing it, and walks the call graph backwards to the HTTP routes, Celery tasks, signal receivers and management commands that reach it. Each finding carries the path taken to it. `unattributed` means no entry point this can see reaches the finding. It does not mean unreachable and it does not mean safe - a plain Django function view carries no decorator and belongs to no view class. Args: search_path: directory to scan. Defaults to the configured project. max_depth: how many callers to walk back through. tenant_root: passed to the ownership check when this runs the checks.

Run the N+1 analysis over every template in a directory. find_n_plus_one needs a context map per template. This resolves it instead from class-based views that declare template_name together with model or queryset, so a whole project can be scanned without typing anything. Args: template_root: template directory. Defaults to the project path. project_root: where to look for views. Defaults to the project path. root_models: context applied to every template, for names no view supplies.

What each DRF ModelSerializer exposes, and what looks unintended. `fields = "__all__"` is a decision made once and then re-made silently by every migration after it. Add a token column to the model and the API starts returning it, with no diff on the serializer for anyone to review. Args: include_safe: also list serializers with an explicit, clean field list.

N+1 queries in DRF serializers, with the queryset fix for each. find_n_plus_one answers this for templates. Most Django written today renders JSON, and there the N+1 comes from a nested serializer field: a list of a hundred orders runs a hundred extra queries per nested relation. Follows nested serializers, so the lookup it suggests is the full path. Args: max_depth: how far to follow nested serializers.

Relationships SQLAlchemy will load one row at a time. orders = db.query(Order).all() for order in orders: print(order.customer.name) # one query per order And the quieter FastAPI shape, where there is no loop to see: @app.get("/orders", response_model=list[OrderOut]) def list_orders(db=Depends(get_db)): return db.query(Order).all() OrderOut declares `items`, so serialisation walks the relationship once per row - after the endpoint has returned, which is why nothing in the function body mentions it. nplusone finds this at runtime by watching lazy loads happen, and lazy="raise" turns it into an exception; both need the code path to run. A relationship declared lazy="selectin", "joined" or "raise" is never reported here, since the first two are already eager and the third is the recommended fix. Nothing is imported. Needs no Django. Args: search_path: directory to scan. Defaults to the configured project.

Findings turned into code, grouped by how safe each one is to apply. Three classes, and the distinction is the point: - **mechanical**: one correct answer derivable from the code alone, such as datetime.now() becoming timezone.now(). No judgement in it. - **generated**: a machine can write the artefact, a human decides whether it should exist. An index migration is exactly right as text and entirely wrong if that table is write-heavy. - **advisory**: real code with the right names resolved, but the decision belongs to somebody who knows the domain. Which user owns a row is not a question the AST can answer. Nothing is applied. The CLI `fix --write` applies the mechanical class only. Args: tenant_root: the model that owns data, for the ownership suggestions.

select_related and prefetch_related the serializer never reads. Every tool in this space looks the other way: a relation the serializer touches that the queryset did not prefetch, which is the N+1. This is the opposite, and it costs on every request. An unused select_related is a JOIN on every row; an unused prefetch_related is a whole extra query plus the objects it returns. It is invisible because it looks like an optimisation, and it usually was one - the field it was added for was removed and nobody takes the line out, because removing one feels riskier than leaving it in. nplusone finds this at runtime by watching which loaded objects go untouched, so it covers the paths the tests exercise. Both halves are in the source: the queryset says what it loads, the serializer what it reads. Args: include_low_confidence: also report views whose serializer has a SerializerMethodField or which override list/retrieve/ to_representation, where the relation may be read out of sight.

Follow the signal chain a save or delete actually triggers. Nothing at an `order.save()` call site hints that it also writes an Invoice, clears a cache and queues a task, because the receivers live elsewhere and were connected in AppConfig.ready(). Tools that list registered receivers exist; this follows the chain, because the second hop is where the surprise lives. It is also the other half of delete_impact, which deliberately ignores signals and says so. Args: model_label: "app_label.ModelName". event: "save" or "delete". max_depth: how far to follow writes into further signals.