Technical

Security by Architecture

by Prasad Hemakumara8 October 20267 min read

A forensic team loads a custodian’s mailbox into a matter. The firm, its client and an outside accountant all work in that matter, and each may see different documents. An agent will run for an hour on the investigator’s behalf, searching and reading. Three questions decide whether any of this is safe.

  • Who can read this data, and what stops everyone else?
  • What can the agent do while it holds the investigator’s authority?
  • Can we show the evidence has not changed since it arrived, and who touched it?

This post explains how Donna’s architecture answers them. The rule we design by is short: when a control can live in the structure of the system, it goes there, because a rule built into the system does not depend on someone remembering to follow it.

Where Procedure Breaks

The conventional build relies on people at three points. Services reach their databases with a key kept in configuration, which someone has to rotate and nobody may paste into a log. The backend connects as one broad system user, and every route is trusted to filter by who is asking. And when an agent acts for a person, it is handed that person’s whole session, so anything the person could do, a prompt-injected agent could do too.

Each of those works until the one time it does not. In an investigation, that one time can cost a finding or a privilege claim. So we took each assumption and moved it into the architecture.

No Keys to Steal

Donna’s services hold no stored data-plane credentials. Each service runs with a managed identity that the cloud platform issues and rotates, and signs in to the databases, storage, search index, queues and key vault with that identity. Where a data service allows it, we go a step further and turn key access off at the resource: the databases, document storage and messaging accept identity tokens and nothing else. A leaked configuration file has nothing in it worth stealing.

The links that let a browser download a file follow the same rule. They are signed with a key derived from the service’s identity rather than an account key, and they are short-lived. Each time someone opens the file again, a new link is minted through the same access check, so a link cannot outlive the permission it was issued under for long.

Two Questions on Every Request

Inside the platform, every internal call to the API answers two questions with two credentials. Which workload is calling is proved by a token from the calling service’s own managed identity, checked against the services allowed to call. On whose behalf travels separately, as a credential bound to the person. Keeping the two apart matters. A service cannot turn its own identity into a person’s, and a person’s credential never lets a service do anything the person could not.

Only after both are settled do the route’s own checks run: membership of the matter, the person’s role in it and the visibility of the item requested. Retrieval follows the same rule beneath the model layer. Search queries are filtered to the matter the request was authorised for, so an agent searching a matter can only find what that matter holds.

  1. 1 · ExchangeAt the start of a run, the investigator’s live sign-in is traded for a delegation the agent worker carries.
  2. 2 · Workload checkEach call names the calling service with its own identity. Unknown callers are refused.
  3. 3 · Delegation checkThe delegation must be in scope for the route, not revoked, and its person still a member.
  4. 4 · Matter accessThe route’s usual membership, role and visibility checks run unchanged.
  5. 5 · ReadOnly then is data read, over a private network path.
  6. Any failed check refuses the request before anything is read.
One request from an agent run. Two credentials travel together, the checks run in order, and matter data is reached only after all of them pass.

What an Agent Carries

Agent runs raised a problem a normal web request never does. A run can outlast the person’s sign-in token, and the easy workaround, letting the worker authenticate as itself and pass the person’s id along as a string, quietly turns “acting as this person” into something the caller asserts rather than something anyone can verify.

Instead, at the start of a run, the worker exchanges the person’s live sign-in for a delegation that Donna issues and signs itself. The exchange requires a live sign-in. There is deliberately no path that produces a person’s authority from a service identity alone, so a worker that has lost the person’s token has to wait for their next request.

Delegation for one agent runissued and signed by Donna
Acting asPriya Shah, investigator
Held byThe agent worker, verified from its own identity
May reachmattersfilesdocumentsdraftsreview tables
Neverbillingmembershipinvitationsaccount settingsaudit export
Tied toPriya’s sign-in session, and a grant record that can be revoked
  • User-bound. The person is inside the signature, so no caller can swap in someone else.
  • Attributed. The audit trail can say which worker held it.
  • Scoped. Only the kinds of request the agent’s tools use.
  • Revocable. Ending the session, or removing the person, ends it.
Anatomy of a delegation. The values are illustrative; the structure is the real one.

The scope took the most care. It names the kinds of request the agent’s tools actually make, derived from what those tools call, and the API refuses anything outside it before the route’s own checks run. It fails closed twice. A new kind of route is unreachable by a delegation until someone adds it on purpose, and the areas we never want an agent near, such as billing, membership and audit export, are listed explicitly as excluded, so a test can hold the line.

Scope narrows what the credential can reach. It never widens what the person can do.”

Scope is not permission. A delegation for someone who is not a member of a matter still meets that matter’s refusal. And because neither the signature nor the session notices a membership change, verification rechecks membership as it goes. Remove someone from a matter, and the agent working for them loses access shortly after, without waiting for the delegation to expire.

Actions that change things for other people take one more step. When an agent wants to invite someone or take another platform action, the run pauses until the person approves, declines or chooses to allow that action from then on, and the decision is recorded. The matter and the person an action applies to come from the authenticated run, never from anything the model writes.

No Public Route to the Data

In production, the matter databases and the search index accept traffic only over private endpoints, with public network access switched off. Our services reach them from inside the platform’s virtual network. Document storage sits behind a firewall that denies by default, and our services reach it over its private endpoint.

Matter data in the databases and in document storage is also encrypted with keys held in our own key vault, rather than the platform default.

Matter databasesIdentity only. Key access turned off.Private endpoint only, public access off. Encrypted with our own keys.
Search indexServices sign in with identity.Private endpoint only, public access off.
Document storageIdentity only. Shared keys turned off.Firewall denies by default; services use a private endpoint. Encrypted with our own keys.
Queues and messagingIdentity only. Key access turned off.Carry work between services, never credentials.
Key vaultRole-based access by identity.Holds the keys that encrypt matter data.
The data plane, service by service. Every service authenticates by identity, and matter data is reached over private endpoints.

Custody From the First Byte

In an investigation the data is evidence, so the record starts before anyone can open the file. Uploads land in a quarantine area that nothing in the matter can read, and malware scanning runs there. A file reaches the matter only on a clean verdict. A malicious file is tagged, deleted and the upload blocked. The uploader is told it was removed by a security scan, with no detail about the file, and an audit event carrying its fingerprint is recorded for administrators.

The case that taught us the most was the third verdict. A password-protected archive cannot be scanned, and the easy choice would be to let it through with a warning. We do the opposite. A file that cannot be scanned is never promoted, and the uploader is asked for an unlocked copy. Defaulting to “held back” costs a re-upload now and then. Defaulting to “let through” would mean the one file we could not inspect is the one that reaches the matter.

  1. 1 · QuarantineThe upload lands where nothing in the matter can read it.
  2. 2 · ScanMalware scanning runs on the stored bytes.
  3. 3 · CleanPromoted into the matter, fingerprinted with SHA-256 and MD5, then processed.
  4. 4 · MaliciousDeleted, the upload blocked and an audit event recorded for administrators.
  5. 5 · UnscannableHeld back, never promoted. The uploader is told why.
A file’s path into a matter. Only the clean path promotes the file; the other two never reach the matter.

Once clean, each file gets a SHA-256 fingerprint of its raw bytes, so you can show later that it has not changed. Its MD5 is computed in the same streamed read and kept alongside, so a hash list from another tool or an agency can be matched against the matter. The SHA-256 also recognises byte-identical copies. A duplicate is stored once, and the second matter is granted access to that one copy rather than receiving a new one, so the matter filter on search still decides who can find it.

An Audit Trail No Service Can Edit

Audit records are written by the system as the work happens, not remembered by people afterwards. Viewing a file and downloading it are recorded as different events. Changes to membership and roles, and the approval decisions on agent actions, write their own records.

A trail only helps if it cannot be quietly rewritten. In production the audit stores are append-only for every service identity: the role our services hold lets them add a record and nothing else, with no right to delete or replace one. The threat we designed for is an attacker who gains code execution inside a service, and that attacker cannot erase their tracks. Every audit row is also mirrored to a separate, append-only log store with its own retention, so a deletion anywhere else would be detectable.

Access checks make the opposite choice to convenience. When the system cannot decide whether someone may see something, the answer is no.

Three Ways to Deploy

Every environment we run is built from the same infrastructure modules, differing only in size and settings, so the architecture above is not a production special. The same build runs in three places. Donna Cloud is hosted on Microsoft Azure in Australia and managed by Donna, ready in days. A dedicated environment gives you your own Azure environment, still managed by Donna. Or Donna is deployed in your own cloud, inside your organisation’s boundary.

What We Took Away

  • Turn the key off, not just unused. A key that exists can leak. A resource that refuses keys cannot.
  • Keep who calls and for whom apart. Two credentials, checked separately, make impersonation a matter of structure rather than code review.
  • Give agents a credential of their own shape. Bound to the person, scoped to the tools, revocable, and closed to anything new.
  • Choose the failure direction on purpose. Unscannable files and unresolved access fail closed. When in doubt, the answer is no.

For investigation and eDiscovery teams, the result is easy to state. The investigator makes the call, and Donna does the work inside boundaries that are part of the system itself. There is no secret to rotate, the permission check is part of every request for data, and the evidence carries its own record from the first byte.

See Donna on your next investigation

Bring a matter. See the agents trace the money, review the mailbox or build the notification list, every finding cited.

Country *
Organisation type *
Team size *
How did you hear about us?