Skip to main content
Preview. This part of the console is still being built. What you see here describes the intended behavior and can change before general availability.

How an outpost works

Before your security and platform teams agree to an outpost, they will ask the same three questions: what leaves the network, what holds which credential, and what happens when the box is down. This page answers them end to end, so the rest of the section reads as detail rather than surprise.

The short version​

Dwaar keeps the brain, the outpost does the hands-on work. Dwaar decides what to discover and what to scan, plans each scan, stores credentials, and turns results into findings. The outpost asks Dwaar for work every few seconds, runs it next to your systems, and sends back what it found.

Every arrow that crosses into Dwaar starts at the outpost. Dwaar gives work only by answering the outpost's own requests.

What stays in your network and what goes to Dwaar​

Stays in your networkGoes to Dwaar
The checked out source and the image layers. Each scan works in its own directory on the outpost's disk, and the directory is deleted when the scan ends.The raw results each analyzer writes, uploaded to Dwaar's results storage. Dwaar turns them into findings.
Every call to the provider: listing, cloning, pulling, assuming an AWS role.What discovery found: names, refs, digests and the other metadata a connection on Dwaar would read.
The analyzer containers and the network they run on.The result of each connection test, and the preview of what discovery would find.
The AWS credentials an outpost uses to assume a connection's role.The outpost's status: heartbeats with its version, CPUs, memory, free disk, free scan slots and the capacity settings it runs with, the progress of its jobs, and the ARN of the AWS identity it runs as, so the console can name the role a trust policy must trust. Never an AWS credential.

Be precise with your security team about one thing. Raw results are not just counts. A code finding carries the lines it points at, and a secret scanner's result carries the secret it matched. They go to Dwaar so it can show them to you, exactly as for a scan that ran on Dwaar. An outpost keeps your source and images in your network. It does not keep the findings about them there.

How credentials move​

There are three kinds of credential in play. Keep them apart and the model is simple.

CredentialWhere it livesWho uses it
The enrollment tokenShown once in the console. Works once, for one hour, and can be cancelled until it is spent.The outpost, on its first start, to get its own credential.
The outpost's credentialA file on the outpost's host, readable by root only. Dwaar keeps only a hash of it.The outpost, on every call to Dwaar. Revoking the outpost stops it at once.
A connection's credential: a token, a password, a keyStored in Dwaar, encrypted, as for any connection.The outpost, for one job at a time.

A connection's credential reaches the outpost only while it holds a job that needs it, over its own authenticated channel, and only once per attempt. The outpost holds it in memory and never writes it to disk. Inside a scan, the analyzers never receive it: only the container that checks out the source or pulls the image asks for it, through a one use token that works for that scan alone.

When you test a connection that is not saved yet, the secret you typed travels from your browser to Dwaar, which keeps it sealed with the test job and drops it when the job ends. The outpost fetches it from there.

AWS is the exception, and the reason many teams deploy an outpost at all. Set an AWS connection's Role assumed by to An outpost and Dwaar stores only the role's ARN and your external id. The outpost assumes the role with its own AWS identity in your account, and each scan receives a one hour session for that role. No AWS credential of yours exists outside your account. See AWS connections the outpost assumes.

How a job moves​

Every piece of work is a job with a lease. A lease is the outpost's claim on a job: it lasts three minutes, and the outpost extends it every 30 seconds while it works. Only the outpost that holds the lease can report on the job, fetch its credential or complete it.

The outpost's pane under Scan Center, then Outposts, shows these as each job's status: Waiting, Running, Completed, Failed, Cancelled and Lost.

What happensWhat Dwaar does
The outpost stops reporting on a job for three minutesThe lease runs out. The job goes back to the queue after 15 seconds and the next attempt starts from an empty directory.
The lease runs out three timesThe job ends as Lost. A discovery reads "the outpost stopped reporting 3 times".
You cancel a scan or a discovery in the queueThe outpost hears it at its next heartbeat or progress report, within about 30 seconds, stops the containers and deletes the scan's directory.
The outpost is told to stopIt takes no new work, keeps sending heartbeats and shows as Stopping, and lets running scans finish for up to five minutes (100 seconds on ECS). What is still running then is stopped and goes back to the queue. Once it exits, it reads Offline after two minutes of silence, and Online again at the first heartbeat after it restarts.
The outpost restarts after a crashIt removes what the crashed run left behind, its containers, networks and scan directories, and starts asking for work again.

What each kind of work waits for​

Discovery and tests need an answer soon; scans can wait. Dwaar treats them differently on purpose.

WorkIf the outpost is offline, stopping or revoked when the work is handed overIf it is online but does not take the work
DiscoveryRefused at once. The queue shows Refused on with the outpost's name, and nothing is queued.Fails after five minutes: "the outpost did not take the job within 00:05:00".
Connection testFails at once with the reason, such as "the outpost is stopping; try again when it is back". The connection's status and health stay as they were.Fails after 90 seconds: "the outpost did not answer within 1m30s".
Scan, outpost offline or stoppingWaits for the outpost and runs when it is back. The queue says why, such as "Waiting for : stopping". The scan plane gives a scan its run budget plus one hour from the hand over, so a scan that waits much more than an hour fails.
Scan, outpost revokedFails at once.

An outpost that is Offline keeps its bound connections. Nothing is moved for you, and nothing about the connections changes: they wait for the outpost or for you to move them.

How the outpost decides it has room​

Discovery and tests are light. They run inside the outpost's own process, four at a time by default, and do not count against the host's capacity.

Scans are counted, then admitted on memory. Each outpost has two capacity settings of its own, stored in Dwaar and changed in its pane: Scan concurrency, 2 by default, and Memory overcommit, 1.0 by default. Dwaar hands an outpost at most Scan concurrency of its scans at a time, and keeps the rest queued with the reason. The outpost asks for a scan only while its CPUs hold one more 2 CPU share, and its free memory and disk one more scan of the size it assumes before a plan is known, so a 2 CPU host runs one scan at a time whatever Scan concurrency says. When you save a setting, the outpost applies it at its next heartbeat and reports it back to Dwaar within a second. Dwaar's own limit on how many of your scans run at once counts only the scans that run on Dwaar, so an idle outpost never waits behind them.

Each analyzer container has a memory limit set by Dwaar's scanner catalogue. Before an outpost starts a scan, it works out the scan's peak: the most memory the containers that can run at the same time could claim by their limits. It starts the scan only if that peak fits what is free. Plan an outpost shows the arithmetic and what it means for the host you pick.

Revoking​

Revoking an outpost in Dwaar is immediate and final. Its credential stops working at once, its waiting and running jobs fail, and at its next heartbeat the outpost stops their containers and exits. It cannot come back: to run work there again, enroll a new outpost with a new token. See Revoking and replacing.

Versions​

The outpost and Dwaar speak a versioned protocol. Dwaar accepts the outpost's protocol and the one before it, so you do not have to upgrade every outpost the day Dwaar changes. An outpost whose protocol Dwaar no longer accepts is refused on every call and turns Offline until you upgrade it.

Try this next​

Bind one connection, then open its next scan in Scan Center, Queue, while it runs. Find the outpost's name under Runs on, then open the outpost's pane and watch the same scan under Live jobs move from Waiting to Running. Seeing both views of one job once makes every later status easier to read.