You have the pieces. This lesson is a project, not a reading. You will pick a repository you own (or have written permission to test), and take it through a full cycle: model the risks, harden the setup, test it, measure it, rehearse a failure and report honestly. The result is a document you could show a team lead or a hiring manager, and it is the best proof of what you learned.
Expect two to four hours. Keep notes as you go; the report is mostly assembled from them.
Ground rules
- Your repo, your machine. Work in a throwaway clone for anything risky. Do not point tests at accounts, services or people outside your scope.
- Fake secrets only. Never put a real credential into a test file. Use invented canary values.
- Write the engagement note first. Scope, permission, rules and stop conditions, as in the red-teaming lesson.
- Evidence over assertion. For every claim in your report, point to a log line, a file hash, a command output or a test result.
The six phases
Phase 1: Scope and model
Complete the one-page from lesson one for this repo. Include the deployment description, assets, inputs (who can write issues, pull requests, dependencies), actions, trust boundaries and your ranked top five risks.
- Engagement note written (scope, permission, rules, stop condition)
- Deployment description (agents, identity, tools)
- Assets, inputs and actions tables
- Top five risks ranked by impact and reversibility
Phase 2: Harden
For each top risk, add a control you can verify. Use the options from earlier levels: narrower agent permissions, a sandbox or container, scoped short-lived credentials, a policy with rules, protected config files, an MCP allowlist, egress limits. Start every rule in observe mode, review what it would have matched, then promote it.
- One control per top risk, each with a stated limit ("this does not cover...")
- Policy or rules written with at least one false positive and one miss documented
- Config files that steer the agent (hooks, settings, instruction files) reviewed
- A fresh baseline snapshot of the setup for later comparison
Phase 3: Red-team safely
Run an authorized test in your throwaway clone with synthetic data. Cover at least four of: planted instruction in untrusted text, fake secret reach, folder scope, guardrail tampering, honest reporting, monitor coverage. Use harmless markers, never real payloads.
- Throwaway clone with fake canary secrets
- Four or more test cases, each with a hypothesis ("the agent will not...")
- Each result recorded: what you did, what happened, evidence
- Anything out of scope left alone
Phase 4: Evaluate
Build the mini-benchmark from the evaluating-agents lesson: five to ten tasks from your real work, each with an objective, a fixture with a trap, a hidden boundary, state-based checks, and at least one . Run each at least three times in a fresh copy and record versions and settings.
- 5 to 10 tasks including at least one control
- Checks look at state, not at the agent's words
- Three or more runs per task; errors counted, not hidden
- Results table with safe-and-complete, task completion and errors
- Before and after, if you ran it with and without your new policy
Phase 5: Rehearse an incident
Run the tabletop from the incident-response lesson against a scenario from your own results (or the pre-commit-hook scenario). Time yourself: how long to stop, revoke, and find the evidence? Write the one-page runbook.
- Runbook with owner, stop, revoke, preserve, investigate, recover, review
- Inventory of credentials the agent can use and where to rotate each
- Location of agent logs documented
- A short mock post-incident review
Phase 6: Report
Assemble the report from your notes using the template below. Keep it to three to five pages. Plain language, specific, honest.
Report template
Copy this into a file and fill each section.
# Agent security report: <repo name>
Date, author, scope and permission statement (1 paragraph)
## 1. Summary
Three to five sentences: what you did, the most important finding,
the single most valuable change, and the biggest remaining risk.
## 2. Deployment and threat model
Agents, identity, tools. Table of assets, inputs, actions.
Top five risks with impact and reversibility.
## 3. Controls added
| Risk | Control | How I verified it | Known limit |
## 4. Red-team results
| Test | Hypothesis | Result | Evidence |
## 5. Evaluation
Tasks, number of runs, versions and settings.
Table: task, safe-and-complete, completion, errors.
What the numbers do not show.
## 6. Incident rehearsal
Time to stop, revoke, find evidence. Gaps found.
## 7. Limits and honesty
What I did not test. What could invalidate these results.
## 8. Next steps
Three changes ranked by value, each with an owner and a date.
What good looks like
| Criterion | Weak | Strong |
|---|---|---|
| Threat model | Generic list of attacks | Specific to the repo, ranked, with who can write each input |
| Controls | "Enabled a policy" | Each control tied to a risk, with a verification and a stated limit |
| Red-team | Hostile-sounding tests | Authorized, bounded, harmless markers, evidence recorded |
| Evaluation | One run per task | Repeated, state-based checks, control included, errors counted |
| Incident | "We would investigate" | Named owner, timed rehearsal, revoke list, log locations |
| Honesty | Claims safety | Lists limits, avoids "secure", says what was not tested |
How AI changes this
- Use AI as an assistant, not an author of your conclusions. A model can draft your tables, suggest test cases and summarize logs. You must check every number and claim against evidence, because a confident wrong summary in a security report is worse than none.
- Your report ages quickly. Models, tools and policies change. Date the report, record versions, and rerun the evaluation after changes. Treat it as a living baseline.
- Keep the agent out of your own enforcement. Do not let the agent you are testing write its policy, its tests or its report unsupervised, for the reasons the course gave.
- What is not new: scope, evidence, honest limits and a prioritized fix list make a good security report, with or without AI.
Try it
Start now with the smallest useful step: write the engagement note and the deployment description for your repo, and list your top five risks. Do those three things before touching a setting. If you can write them clearly, the rest of the project is execution.
Check yourself
Why does the report include a section on what you did not test?
Every test is bounded, and an honest report says where its evidence stops. Without it, readers assume more coverage than exists, which is the mistake the benchmark limits sections are written to prevent.
Your evaluation shows 100 percent safe on five tasks with one run each. What can you claim?
Only that those five tasks, in those runs, produced no violation. One run each is an anecdote, five tasks are a thin sample, and the result may change with versions. Repeat the runs, include a control, and word the claim modestly.
You find that your new rule blocks a legitimate task. What do you do?
Record it as a false positive, narrow the rule or change its action to advisory, rerun the evaluation, and document the trade-off in the controls table. Do not disable the rule silently.
Where to go from here
You have finished the course. Keep your report, rerun your evaluation when tools change, and share what you learn: write a post, contribute a scenario to an open benchmark, or help your team adopt a baseline. Agent security is a young field, and careful, honest practitioners are what it needs.