Chapter 1 — Computing and service architecture
Lesson map
Lesson 01 published. Map, example, EX001.
flowchart TD
N0["Learning outcomes"]
N1["1.1 Components"]
N2["1.2 Following a request"]
N3["1.3 Data and secrets"]
N4["1.4 Controls technicians configure"]
N5["Synthesis"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5
N5 --> EX["Worked example"]
EX --> Q["Exercise EX001"]
Logical drawing
flowchart LR
N0["Learning outcomes"]
N1["1.1 Components"]
N2["1.2 Following a request"]
N3["1.3 Data and secrets"]
N4["1.4 Controls technicians configure"]
N5["Synthesis"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> Q["EX001"]
[Learning outcomes]
|
v
[1.1 Components]
|
v
[1.2 Following a request]
|
v
[1.3 Data and secrets]
|
v
[1.4 Controls technicians configure]
|
v
[Synthesis]
|
v
[Worked example] --> [Exercise EX001]
Learning outcomes
You will (1) name the components of an AI-enabled service; (2) follow a request through them; (3) identify where data and secrets are held; (4) locate the controls a technician configures.
1.1 Components
An AI-enabled support service has: a customer front end (web chat, app); an application server; an orchestrator that builds prompts and calls the model; a model, usually reached through a vendor API; a retrieval service with an index of help articles; tool services (ticketing, router management); databases; logging; and monitoring. Each runs on servers or containers that technicians install, patch and configure.
Ana's HelpBot inventory counted eleven such components, and the count matters for patching. The front end, the gateway, the orchestrator, the retrieval service with its index, the ticketing tool, the router-management service, the account database, the secrets store, logging, monitoring and the vendor model API each have a different owner and update cycle. Only the last one is patched by someone outside Kestrel, which is why the vendor's model version later had to be added to the bill of materials by hand.
1.2 Following a request
A customer writes "my internet is down". The app authenticates the customer, the orchestrator retrieves relevant help articles, builds a prompt (system instructions + articles + message), sends it to the model, receives a reply that may request a tool ("restart_router"), checks the request, calls the router-management service, and returns an answer. Each step writes logs.
Each hop in that trace is a place where a check can sit. When Ana followed the request through the logs, the authenticated customer ID appeared at the app and again at the tool service, but the orchestrator's call to the router-management service carried only a service account. That gap is what let a restart reach a router the customer did not own, and it is why the later fix made the tool service read the customer identity from the call rather than trust the router ID in the model's request.
1.3 Data and secrets
Customer account data, conversation text and tool results all pass through memory, logs and sometimes caches. Secrets — the vendor API key, the router-management credentials — live in a secrets store and are read by services at start-up. A technician must know where each is, who can read it and how long it is kept.
At Kestrel the answer to "who can read it" was the problem: the router-management credential sat in the orchestrator's configuration file, so every engineer with server access could read it, and so could any backup of that server. Moving it to the secrets store limited readers to the tool service account. A technician should also ask how long conversation text stays in caches and logs, because a customer's address typed into the chat ends up in the same log files as the tool calls.
1.4 Controls technicians configure
Authentication settings, rate limits, retrieval sources, tool permissions, log retention and redaction, alert thresholds, container settings and patching. Most AI-security failures come from configuration, not from exotic attacks.
Every Kestrel incident in this book was fixed by one of these settings rather than by changing the model. The doubled vendor bill was fixed with a gateway limit of 2 requests per second, burst 10, and a daily token budget. The restart abuse was fixed with an ownership check and a cap of 3 restarts per day in the tool service. The test model copied into LineWatch production was caught by a start-up hash check. The misfiled staff-only article was fixed by limiting the customer index to the public collection. None of those needed a data scientist.
1.5 Worked example (synthetic Kestrel case)
Ana is asked to document HelpBot. She lists eleven components and traces a "restart router" request. She notices that the router-management credential is stored in the orchestrator's configuration file, readable by every engineer with server access. She reports it; the team moves it to the secrets store and restricts the tool service so it accepts restarts only for the router linked to the authenticated customer.
Two details made this finding worth more than a tidy diagram. First, Ana did not test whether anyone had used the exposed credential; she reported it and let the team check access logs. Second, moving the secret alone would not have been enough, because the tool service would still have restarted any router it was asked to. The ownership restriction is the change that later reduced cross-account restarts from 9 of 60 to 0 of 60.
1.6 Errors and limits
- Documenting the model but not the tools.
- Secrets in configuration files.
- Assuming the vendor handles all security.
Each item has a Kestrel instance. Documenting only the model would have missed the router-restart tool, which caused the most serious finding. The secret in a configuration file is the router credential Ana found in her first week. Assuming the vendor handles security would have left the 40,000-message weekend unexplained, because the vendor billed the traffic correctly; nothing on its side was broken. The weakness was the missing per-account limit on Kestrel's own gateway. A service diagram should therefore show the tools, secrets and gateway limits as clearly as the model.
Exercises
- EX001 — Components. List eight components of HelpBot and one control per component. Rubric: 3 = eight with apt controls; 2 = six; 1 = three to five; 0 = fewer.
- EX002 — Request trace. Write the steps of a "restart router" request. Rubric: 3 = auth, retrieval, prompt, model, check, tool, reply, logs; 2 = six; 1 = three; 0 = none.
- EX003 — Secrets. Where should the router credential live, and who should read it? Rubric: 3 = secrets store, tool service only, rotation; 2 = two; 1 = one; 0 = none.
- EX004 — Configuration. Name four configuration settings that affect HelpBot security. Rubric: 3 = four apt; 2 = three; 1 = one or two; 0 = none.
Synthesis
An AI service is many components; technicians secure it mostly through configuration — knowing where data and secrets go and setting controls correctly.