Code complexity analysis is the practice of measuring how difficult a piece of code is to understand and change, and it doubles as an early-warning system for where security defects concentrate. The link is not folklore: functions with high branching are harder to reason about, harder to test completely, and therefore more likely to hide the edge case that becomes a vulnerability. When you run code complexity analysis, you're not just chasing a maintainability score — you're producing a heat map of the places most likely to break under an attacker's edge cases.
Let's define the metrics, then turn them into action.
The metrics that matter
Several numbers travel under the banner of code complexity. The ones worth tracking:
Cyclomatic complexity counts the independent paths through a function — essentially the number of decisions (if, for, case, &&) plus one. A function with a cyclomatic complexity of 3 needs at least three test cases to exercise every path; one at 25 needs 25, which almost nobody writes. Unwritten paths are untested paths.
Cognitive complexity (popularized by SonarSource) tries to model how hard code is for a human to follow, penalizing nesting more heavily than a flat sequence of conditions. Two functions can share a cyclomatic score while one is far harder to read; cognitive complexity captures that.
Halstead metrics derive volume and difficulty from counts of operators and operands — more academic, occasionally useful for estimating effort.
Maintainability index rolls several signals into a single 0-to-100 figure. Convenient for dashboards, but too blunt to act on directly.
For security work, cyclomatic and cognitive complexity are the two to watch.
Why complexity predicts vulnerabilities
A high-complexity function is a place where three things compound. First, the developer who wrote it may not have held all its states in their head, so a validation branch gets missed. Second, test coverage is usually thinner there, because writing 25 test cases is tedious. Third, the next person to modify it — often under time pressure — is more likely to introduce a regression they can't foresee.
Put those together and you get the pattern researchers keep finding: defects cluster in the most complex, most-churned files. A parser, an auth middleware, or a permission check with deep nesting is exactly where an injection or authorization bypass tends to live. Complexity doesn't cause the vulnerability, but it reliably marks the neighborhood.
Measuring it in practice
The tooling is mature and mostly free.
For JavaScript and TypeScript, ESLint ships a complexity rule:
{ "rules": { "complexity": ["warn", 10] } }
For Python, radon reports cyclomatic complexity and the maintainability index:
pip install radon
radon cc ./src -a -nc
For multi-language projects, SonarQube and lizard both compute complexity across many languages and integrate with CI. Most SAST platforms also surface complexity alongside security findings, which is convenient because the two data sets reinforce each other.
The point isn't the absolute number. A threshold of 10 for cyclomatic complexity is a common convention, but a well-structured state machine might legitimately exceed it. What matters is the trend and the outliers.
Turning the numbers into decisions
Raw metrics gather dust unless you wire them into a workflow. Three moves that work:
- Gate on increases, not absolutes. Fail a pull request that pushes a function's complexity above a threshold it didn't previously cross. This stops the slow rot without demanding a rewrite of the legacy monolith on day one.
- Cross-reference complexity with churn. A file that is both complex and frequently changed is your highest-risk target. Prioritize refactoring and extra security review there.
- Feed it into security review scope. When triaging where to spend a limited threat-modeling budget, start with the most complex modules on the attack surface. That's where the DAST and manual review hours pay off most.
Refactoring for complexity is also a security control in itself: extracting a nested validation block into a small, single-purpose, fully tested function removes a hiding place. You're not gold-plating readability — you're shrinking the surface where a subtle logic flaw can survive.
Complexity and third-party code
Your own functions aren't the whole picture. The dependencies you pull in carry their own complexity, and you inherit their risk without their tests being your problem to write. You can't refactor a library you didn't author, but you can choose simpler, better-maintained ones and keep them patched. An SCA tool such as Safeguard flags known vulnerabilities in those dependencies, which is the practical counterpart to complexity analysis on code you can't change. The Academy has more on evaluating dependency health before you adopt it.
Making it a habit
Add a complexity check to CI this week with whatever your language already supports — ESLint, radon, or Sonar. Watch it for a sprint, find your worst offenders on the attack surface, and refactor one of them. Repeat. Code complexity analysis rewards steady attention far more than a one-time audit, and the security payoff is that your most dangerous code slowly stops being your most tangled.
FAQ
What is a good cyclomatic complexity score?
A common convention treats functions up to about 10 as manageable, 10 to 20 as worth watching, and above 20 as candidates for refactoring. These are guidelines, not laws — some inherently branchy logic is fine if it's well tested — so treat outliers and upward trends as the real signal.
Does code complexity actually correlate with security bugs?
Empirical studies repeatedly find that defects, including security defects, cluster in the most complex and most-changed files. Complexity doesn't directly cause vulnerabilities, but it marks code that is under-tested and hard to reason about, which is where flaws survive.
What tools measure code complexity?
ESLint's complexity rule for JavaScript and TypeScript, radon for Python, lizard for many languages, and SonarQube for cross-language projects with CI integration. Many SAST platforms also report complexity alongside their security findings.
How is cognitive complexity different from cyclomatic complexity?
Cyclomatic complexity counts independent execution paths. Cognitive complexity estimates how hard code is for a human to read, weighting nested structures more heavily. Two functions can share a cyclomatic score while differing sharply in cognitive complexity because one nests its conditions and the other keeps them flat.