Security & Performance — Skills

Threat Modelling

Takes a system as it is built and produces the model of how it can be attacked — so the team responsible for it knows what it defends, with what, and what is still exposed.

Deliverable

One Markdown document, threat-model.md, in the structure set out under Output below. It is the input to Security Review of a Change, which checks new work against the boundaries this document draws.

Required inputs

The system's architecture — the components, data stores, network positions and the calls between them, from documentation, diagrams or the code itself.
What the system protects — the data and the capabilities that matter, named by someone who owns them.
Confirmation that the system is yours to defend — this skill models a system the reader is responsible for. Without that confirmation it does not run.

If any of the three is absent, stop and report what is missing. Never infer what a system protects from its schema: a table shows what is stored, not what the organisation would lose.

Optional inputs

Deployment topology, network segmentation, and the environments the system runs in
The authentication and authorisation design, including how sessions and tokens are issued
Existing security controls and the evidence that each one works
Data classifications, retention rules and regulatory obligations
Past incidents and test reports, with the remediation status of each finding
Third-party services the system depends on, and what each one is trusted with

Every optional input that is absent becomes an entry under Open questions. Any control that could not be checked is recorded as assumed rather than dropped.

Execution

1 — List the assets and what each is worth. For each asset: what it is, where it lives, who owns it, and what the organisation loses if it is disclosed, altered or unavailable. An asset with no named owner is recorded owner unknown, because an asset nobody owns is an asset nobody defends.

2 — Draw the trust boundaries. A boundary is any place where data or control passes between parties with different levels of trust — a network edge, a process edge, a tenant edge, a change of privilege. For each boundary: what crosses it, in which direction, and what is checked on the way through.

3 — Enumerate the entry points. Every route by which input reaches the system, including the ones that are rarely listed: administrative consoles, scheduled jobs that read shared storage, message queues, webhooks, file uploads, support tooling, and the build and deployment path. Tag each observed if it was found in the system, or reported if a person stated it.

4 — Derive the threats boundary by boundary. For each boundary work through the categories in turn — identity claimed falsely, data altered in transit or at rest, an action denied afterwards, information disclosed, capacity exhausted, privilege raised. A systematic pass finds the threat nobody remembered; a brainstorm finds the threat everybody already fears.

5 — Record the existing controls and how you know. For each threat, the control that currently addresses it, where that control lives, and whether it is verified — you exercised it or read the code that enforces it — or assumed — someone said it was there. A control marked assumed is not a mitigation; it is an open question with a reassuring name.

6 — State the residual risk and give it an owner. For each threat still standing after its controls: what remains, how it would be noticed if it happened, and who owns the decision to accept it or fund it. Residual risk with nobody against it is reported as unowned, never as accepted.

7 — Collect what could not be determined. Every asset, boundary or control the material did not settle, each with what it blocks and who can answer it.

Output

threat-model.md, in this order:

1. Scope and date — which system was modelled, from what material, by whom, and when
2. Assets — one line each: asset, location, owner, and what its loss would cost
3. Trust boundaries — one line each: boundary, what crosses it, direction, what is checked
4. Entry points — one line each: entry point, the boundary it crosses, observed or reported
5. Threats — per boundary: the threat, the category it came from, the entry point it uses, the asset it reaches
6. Controls — per threat: the control, where it lives, verified or assumed, and the evidence
7. Residual risk — what remains after controls, how it would be detected, the owner, and whether it is accepted
8. Assumptions — every statement taken on trust, and what would confirm it
9. Open questions — the question, what it blocks, who can answer it

Validation

The model is ready when all of these hold:

Every asset in section 2 names an owner or reads owner unknown
Every entry point in section 4 maps to a boundary in section 3
Every threat in section 5 names the boundary it crosses and the asset it reaches
Every control in section 6 is marked verified or assumed, with nothing left unmarked
Every residual risk in section 7 has an owner and a way it would be detected
No control is described as effective without the evidence that it is

Fail the run if a control appears with neither verified nor assumed against it, or if a threat is recorded as mitigated on the strength of an assumed control.

Failure handling

No architecture supplied — stop. Report that the model has no system to describe, and that inferring one from a single component produces a map of that component rather than of the system.
Nobody can say what the system protects — produce sections 3 and 4 from what is observable, leave section 2 empty and marked pending owner input, and state that a model without assets ranks nothing.
Architecture and code disagree — record both, name both sources, model the behaviour that is in the code, and raise the disagreement in section 9 as blocking. Do not resolve it by choosing.
No access to the running system — mark every entry point reported and every control assumed, and state plainly that nothing in the document was verified.
Partial material — model the parts the material supports, mark the rest INCOMPLETE — pending <question>, and deliver. A model honest about its edges is usable; one that guessed at them teaches the team to trust a boundary that may not exist.

Download .md

Security Review of a Change

Reviews a change for the exposure it adds — every finding traced to a path that is actually reachable, and every suspicion reported as a suspicion.

Deliverable

One Markdown document, security-review.md, in the structure set out under Output below. It takes the boundaries drawn by Threat Modelling and returns a decision the release can carry.

Required inputs

The change set — the diff, patch or branch under review, complete rather than summarised.
What the change touches — the components, data and interfaces it reaches, and which of them sit on a trust boundary.
The code the change lands in — enough of the surrounding system to trace a changed line to the path that reaches it.

If any is absent, report it as missing and review only what the supplied material supports. A diff read without the code around it shows what changed, not what the change exposes.

Optional inputs

The threat model, or any record of where the trust boundaries run
The authorisation design: the roles, the scopes, and where each is enforced
Logging, error-reporting and monitoring configuration
Infrastructure and configuration changes shipping alongside the code
The tests that cover the changed paths, and what they assert
The reason for the change, in the author's own words

Absent optional inputs narrow what can be concluded, never what is claimed. Where reachability cannot be established from the material supplied, the finding is filed under Needs verification.

Execution

1 — Establish what the change reaches. From the diff, list the files, entry points, data stores and outbound calls it touches. For each, the path that reaches it and whether that path crosses a trust boundary. A change that touches nothing on a boundary is still reviewed, and the review says that is what it found.

2 — Follow the input. For every value the change accepts from outside a boundary, trace it to where it is used: a query, a command, a path, a template, a redirect, a deserialiser, a response. Record where it is validated, where it is encoded for its destination, and where it is neither.

3 — Check authorisation on every path, not every route. For each operation the change adds or alters: who may call it, where that check is made, and whether every path into the operation passes through it. The common defect is not a missing check but a second path that reaches the same operation around the check that exists.

4 — Look for secrets and credentials. Keys, tokens, passwords, connection strings and private material in the diff, in configuration, in fixtures, in test data, and in anything the build embeds. Record each with its file, and whether it reaches a build artefact or the repository history.

5 — Read what the change writes out. Logs, error responses, stack traces, analytics events and support tooling. Record every field that leaves the system carrying user data, credentials, internal addresses, or the details of a failure that an outsider should not receive.

6 — Account for the new surface. What the change makes publicly reachable that was not, what permission it widens, what default it changes, and what dependency it adds. A dependency added here is named and handed to Dependency & Supply-Chain Audit rather than assessed in passing.

7 — Write each finding with its path and its fix. Per finding: the file, the condition under which the path is reached, what an attacker gains at that point, the severity and the reason for it, and the specific change that closes it. A finding that cannot be traced to a reachable path goes under Needs verification with the step that would settle it.

Output

security-review.md, in this order:

1. Change under review — what was reviewed, from which material, by whom, and when
2. Surface touched — the files, entry points and data the change reaches, and which cross a boundary
3. Findings — per finding: file, the condition that reaches it, impact, severity and its reason, and the fix
4. Needs verification — suspected issues with no traced path, each with the step that would settle it
5. Input handling — per external value: where it enters, where it is validated, where it is encoded
6. Authorisation — per added or altered operation: the check, its location, and every path that reaches it
7. Secrets and output — credentials found, and every field the change writes to logs or errors
8. New surface and dependencies — what became reachable, what widened, what was added
9. Not reviewed — what the supplied material did not cover, and what that leaves unknown

Validation

The review is ready when all of these hold:

Every finding in section 3 names a file and the condition that reaches it
Every finding in section 3 carries a fix a developer can apply, not a principle
Every suspicion without a traced path is in section 4 rather than section 3
Every operation the change adds appears in section 6 with its check or with no check found
Section 7 states that no credential was found where none was, rather than being left empty
Section 9 is either non-empty or states that the material covered the whole change

Fail the run if a finding is stated as exploitable without a reachable path, or if a severity is assigned without the impact that justifies it.

Failure handling

No change set supplied — stop. Report that there is nothing to review, and that reviewing the current state of a file is a different job under a different name.
No access to the surrounding code — review the diff alone, place every finding that depends on reachability in section 4, and state that no path was traced.
The change is too large to review as one unit — split it by surface, review each part, and report which parts were reviewed and which were not. Never sample a diff and present the result as coverage.
The author's account and the code disagree — review the code, record the stated intent beside it, and raise the difference as a finding about the change rather than about the author.
A finding cannot be reproduced — keep it in section 4 with what was observed and what is needed to confirm it. A suspicion recorded honestly gets investigated; one stated as fact gets argued about and then dropped.

Download .md

Dependency & Supply-Chain Audit

Reports what a project actually depends on, what of that its code actually reaches, and which findings therefore matter first.

Deliverable

One Markdown document, dependency-risk-report.md, in the structure set out under Output below. It receives the dependencies named by Security Review of a Change and returns the risk each one carries.

Required inputs

The dependency manifest and its lockfile — both. A manifest states intent; the lockfile states what is installed.
The application code — so a dependency can be traced to the paths that reach it, or shown to be reached by none.
The advisory source you may consult, and the date of its data. This skill copies advisories from a source; it never recalls them.

If any is absent, report it as missing before auditing. Never state an advisory identifier, an affected range or a version from memory — an advisory quoted from recollection is indistinguishable from an invented one.

Optional inputs

The build and deployment configuration, including whatever runs at install time
The licence policy the project has to satisfy
Previous audits, and the decisions taken on what they found
Which dependencies are pinned by policy and which are allowed to float
Registry and mirror configuration, and whether artefacts are verified on download
The list of dependencies added by the change currently under review

Where an optional input is absent, the section that depends on it reports not assessed with the reason. It never reports clean.

Execution

1 — Resolve the real tree. From the lockfile, list the direct dependencies and everything they pull in, with the resolved version of each. Record the depth of each transitive dependency and the path by which it arrived. A tree read from the manifest instead of the lockfile is a different tree, and the report states which one it read.

2 — Separate reachable from merely installed. For each dependency, establish whether any path in the application reaches it, and record reached, not reached or undetermined with how that was established. Most of a tree is usually not reached; treating all of it as live buries the part that runs.

3 — Check each dependency against the advisory source you were given. Record the source and the date of its data. Copy every identifier and affected range from it, and compare against the installed version. A dependency the source does not cover is recorded not covered, which is not the same as safe.

4 — Read the maintenance signals. Per direct dependency: when it last changed, how many people can publish a release, whether the published artefact corresponds to a public source tree, and whether it is archived or deprecated. Record each signal with where it was read and when.

5 — Record the licence obligations. Per dependency: the declared licence, whether the way this project distributes its software triggers an obligation, and any dependency whose licence could not be determined. A licence taken from package metadata rather than from the licence file is marked as such.

6 — Find what executes at install and build time. Install hooks, post-install scripts, code generation, binaries fetched while building, and anything that reaches the network during packaging. This code runs on developer machines and build agents with their privileges, so it is audited as running code rather than as metadata.

7 — Order the findings by reachability. Group them into reached code, build-time only, and not reached, and state which group each finding is in. Within a group, order by impact. The report never presents an advisory against code no path reaches as equivalent to one on a path that runs on every request.

Output

dependency-risk-report.md, in this order:

1. Scope and date — which manifest and lockfile were read, which advisory source and the date of its data, and when
2. Dependency tree — direct dependencies with resolved versions, and the transitive count and depth behind each
3. Reachability — per dependency: reached, not reached or undetermined, and how that was established
4. Advisory findings — per finding: the dependency, the identifier as the source gives it, the affected range, the installed version, the reachability group
5. Maintenance signals — per direct dependency: last change, who can publish, source correspondence, status
6. Licences — per dependency: the declared licence, the obligation it triggers, or undetermined
7. Install-time and build-time execution — what runs, from which package, and with what access
8. Pinning and verification — what is pinned, what floats, and whether artefacts are verified on install
9. Not determined — what could not be established, why, and what would establish it

Validation

The report is ready when all of these hold:

Every direct dependency in section 2 appears in sections 3, 5 and 6
Every finding in section 4 names the source it was copied from and its reachability group
No identifier, affected range or version appears that did not come from the supplied source
Every dependency in section 3 carries one of the three reachability values, with none left blank
Sections 5 and 6 read undetermined where the material did not settle them, never none
Section 9 is either non-empty or states that everything in scope was determined

Fail the run if an advisory identifier or a version appears without the source it was read from, or if a dependency is reported as safe on the grounds that nothing was found.

Failure handling

No lockfile — audit the manifest, mark every version as declared, not as installed, and report that the reachability and advisory results describe a tree that may not be the deployed one.
No advisory source available — produce every other section and mark section 4 not assessed — no advisory source supplied. Never fill it from memory.
Reachability cannot be determined — mark the dependency undetermined, order it as though it were reached, and state in section 9 which findings that affects.
The manifest and the lockfile disagree — record both, audit the lockfile, and raise the disagreement in section 9 as blocking. A project that installs something other than what it declares has a second problem behind the first.
Several ecosystems in one project — audit each manifest separately and report them separately, listing any directory not covered in section 9. A single merged list hides which package manager installs what.

Download .md

Performance Budget Definition

Turns what a system must feel like into thresholds a pipeline can enforce — and refuses to supply a number that nobody has agreed to.

Deliverable

One Markdown document, performance-budget.md, in the structure set out under Output below. It is the standard Performance Investigation measures against, and the condition the release pipeline checks.

Required inputs

What the system must feel like to its users — which interactions matter, stated by whoever owns the experience.
The threshold for each one, from the requester — the number the interaction must stay under. This skill records thresholds; it does not choose them.
The conditions the users are in — the devices, the networks and the data volumes the budget has to hold under.

If the thresholds are absent, produce the document with every threshold written unknown — required from <owner>, and report that the budget cannot be enforced until they are supplied. Never substitute a number of your own.

Optional inputs

Existing measurements of the interactions in scope, with where and how they were taken
The measurement tooling available, and what it can observe in each environment
The pipeline stages that could enforce a budget, and what they are allowed to block
Contractual or regulatory commitments about responsiveness or availability
The traffic pattern the budget must hold across, including its peaks
Previous budgets, and the reason any of them was changed

An absent optional input never softens a budget. Each one becomes an entry under Open questions, and any budget whose measurement point is unknown is recorded as unenforceable.

Execution

1 — List the interactions that have to be fast. One line per interaction, each of them something a user actually waits for, named from the user's side rather than from the call graph. An interaction nobody waits for does not get a budget.

2 — Attach the supplied threshold to each one. Record the number as it was given, the unit as it was given, and the person who gave it. Where none was given, write unknown — required from <owner> and carry the interaction forward unbudgeted. A threshold invented at this step becomes the system's real target by accident.

3 — Fix the percentile. State the percentile each threshold is measured at, supplied by the same owner who supplied the threshold. A budget held to an average passes while a share of users sits outside it, and the document can only name that share once the percentile is stated.

4 — Fix the conditions. Per budget: the device class, the network conditions, the data volume and the cache state under which it must hold. A budget that holds only on the fastest case is recorded as holding only on that case, in the same line as the threshold.

5 — Name the measurement point. Where the number is read: which environment, which instrument, which event opens the interval and which closes it, and how often it is sampled. A budget with no measurement point is recorded unenforceable, because nothing can ever fail it.

6 — Decide what exceeding it does. Per budget: which pipeline stage checks it, whether a breach warns or blocks, who is notified, and the documented route for shipping past it anyway. A budget that cannot fail anything is a preference with a number attached.

7 — Give each budget an owner and a review point. The person who answers when the budget is breached and who may change it, and the milestone at which the budget is reconsidered. A budget nobody owns is quietly raised the first time it is inconvenient.

Output

performance-budget.md, in this order:

1. Scope and date — which system, whose requirements, gathered by whom, and when
2. Interactions — one line each: the interaction, who waits for it, and why it matters
3. Budgets — per interaction: the metric, the threshold as supplied, the unit, the percentile, and who supplied them
4. Conditions — per budget: device class, network, data volume, cache state
5. Measurement — per budget: environment, instrument, the events that open and close the interval, sampling frequency
6. Enforcement — per budget: the pipeline stage, warn or block, who is notified, the documented route past it
7. Owners and review — per budget: the owner, and the point at which it is reconsidered
8. Unbudgeted interactions — those carried forward with no threshold, and who must supply one
9. Open questions — the question, what it blocks, who can answer it

Validation

The budget is ready when all of these hold:

Every interaction in section 2 appears in section 3 or section 8, and in exactly one of them
Every threshold in section 3 names the person who supplied it
Every budget in section 3 states a unit and a percentile
Every budget has a measurement point in section 5 or is marked unenforceable
Every budget names an owner in section 7
No threshold appears in the document that was not supplied by the requester

Fail the run if a threshold, a unit or a percentile appears without the person who supplied it, or if any number in the document originated with this skill.

Failure handling

No thresholds supplied — produce every section, list all interactions in section 8, mark the document NOT ENFORCEABLE, and name who must supply the numbers.
Nothing can be measured in the environment that matters — record the budget with its measurement point unknown, mark it unenforceable, and state what instrumentation would make it enforceable.
The thresholds contradict the stated conditions — record both, name both sources, and raise the conflict as a decision the owner must make. Do not relax one of them to fit the other.
The pipeline cannot block — record the enforcement as warn only, name who receives the warning, and state that a warning nobody owns is a budget in name only.
Partial material — budget the interactions the material supports, list the rest in section 8, and deliver. A short budget that is enforced is worth more than a complete one that is aspirational.

Download .md

Performance Investigation

Finds where the time actually goes, changes one thing, and proves the change with the same measurement that found the problem.

Deliverable

One Markdown document, performance-investigation.md, in the structure set out under Output below. It measures against the thresholds set by Performance Budget Definition, and returns the evidence that the system is inside them again.

Required inputs

The complaint as it was reported — what is slow, for whom, doing what, and since when if that is known.
A way to reproduce it — an environment, an account, a data set or a trace that shows the behaviour.
Access to measurement — the profiler, the timing instrumentation or the traces the system exposes.

If any is absent, report it as missing and go no further than the step it blocks. Never proceed to a fix on the strength of a plausible explanation: the plausible cause and the actual cause agree far less often than anyone expects.

Optional inputs

The budget the interaction is supposed to meet, and who owns it
Historical measurements from before the behaviour changed
The change history covering the period the complaint describes
The traffic shape and data volumes in production, as against those in the test environment
The infrastructure the system runs on, and what it shares with other workloads
Earlier attempts at the same problem, and what each of them measured

Where an optional input is absent, the report states what that leaves unconfirmed. It does not fill the gap with a hypothesis.

Execution

1 — Reproduce before changing anything. Establish the conditions under which the behaviour appears: the input, the data volume, the environment, the concurrency, the cache state. An investigation that cannot reproduce the problem stops at this step and reports what is needed to reproduce it.

2 — Take a baseline. Measure the reproduced case as it stands, record the instrument, the conditions and the percentile, and repeat the measurement enough times to show its spread. Without a baseline there is nothing to compare a fix against, and every later claim about the fix is an opinion.

3 — Measure where the time goes. Use the profiler, the traces or the timing instrumentation to attribute the interval to its parts, and record the attribution as measured. A component nobody measured is not a suspect; it is unmeasured, and the report says which components those are.

4 — Find the bottleneck rather than the suspicion. Follow the measurement to the largest attributable cost and confirm it: remove it, bypass it, or vary its input and watch the measurement move. The bottleneck is the part whose change moves the number, and the proof is the measurement that moved.

5 — Change one thing. Make the smallest change that addresses the confirmed bottleneck, and only that. Two changes at once produce a result that cannot be attributed, and a result that cannot be attributed can be neither defended nor reverted with confidence.

6 — Measure again under the baseline conditions. The same instrument, the same conditions, the same percentile, the same repetition. Record the new figure beside the old one. If the number did not move, record that it did not, revert the change, and return to step 3 — a change kept because it ought to have helped is technical debt with a good story attached.

7 — Lock it in. Add the test or the check that fails if the behaviour returns, at the measurement point the budget names. A fix with no regression test is a fix with an expiry date on it.

Output

performance-investigation.md, in this order:

1. Complaint and date — what was reported, by whom, and when
2. Reproduction — the conditions under which the behaviour appears, and what was needed to produce them
3. Baseline — the measurement before any change: instrument, conditions, percentile, spread
4. Attribution — where the time went, as measured, and what was left unmeasured
5. Bottleneck — what it is, and the measurement that confirmed it
6. Change — what was changed, and why that change addresses the confirmed bottleneck
7. Result — the measurement after the change, under the baseline conditions, beside the baseline
8. Regression test — what now fails if the behaviour returns, and where it runs
9. Not established — the hypotheses that were not confirmed, and what would settle each

Validation

The report is ready when all of these hold:

Section 3 records a baseline taken before any change was made
Section 5 names a measurement, not an inspection, as its confirmation
Section 6 describes one change; a second change is a second investigation
Section 7 reports the measurement after under the same conditions as section 3
Section 8 names a test that fails when the behaviour returns
Every cause stated in the document traces to a measurement in section 4

Fail the run if a cause is reported without a measurement behind it, or if the measurement after was taken under conditions other than the baseline's.

Failure handling

The problem cannot be reproduced — stop at section 2, report the conditions that were tried, and name what is needed: an environment, a data set, a trace from an affected user, or instrumentation in production.
No profiler or instrumentation available — report the reproduction, and the baseline if the interaction can be timed end to end. State that attribution is impossible without instrumentation, and name what must be added.
The complaint and the measurement disagree — measure at the point the user experiences, record both results with their conditions, and report the difference. Do not resolve it by choosing the measurement that is easier to take.
Several changes shipped together — report the combined result and state that no single change can be credited. Re-run the investigation one change at a time before recording a cause.
Partial access — measure what is reachable, list the components that could not be observed in section 9, and deliver. An investigation that names what it could not see is usable; one that omits it points at whatever it happened to measure.

Download .md