[Design] Deployment

[KCarretto]

Deployment

Realm should have a mechanism where implants can be deployed using the Tavern UI.

Constraints

We want to design a deployment system with the following constraints:

• No need to recompile binaries, we can just use existing compilations
• Ability to easily redeploy (using the worker or through imix)
• Unusable IoCs on target machine disk
• Does not depend on callback / outbound connections on target system
• Can serve as an Ansible replacement (e.g. has equivalent functionality)
• Deployments should be easily tracked through the UI (e.g. which deployments does a Target have)
• Manual deployment must be possible

Initial Design

• DeploymentConfigs will be associated with a DeploymentBundle
• DeploymentBundles are associated with 0 or more files and 0 or more tomes
• DeploymentBundles may have an encryption key (indicating they are encrypted)
• Worker will download the DeploymentBundle for a deployment via the API
• Worker will upload DeploymentBundle to target
• Worker will upload eldritch interpreter (imix) to target
• Worker will execute eldritch interpreter with DeploymentBundle and bundle encryption key (if it exists)
• Eldritch interpreter should run all tomes present in DeploymentBundle

[hulto]

@KCarretto what does a deployment config define and how will that be different than an eldritch tome?

[KCarretto]

A DeploymentConfig is what associates the various elements of a deployment together. It also gives the deployment a name. When deploying to targets, one Deployment is created per target to track results and output.

[KCarretto]

Issues

In this model, how do tomes know where the files they are referencing are? For example if I was to deploy imix with a tome, how would my tome know where the imix binary was located? Additionally, since we want these to be run as agent tasks as well as included in part of deployment, my tome would depend on the imix binary being accessible. This creates a separation between deployment and regular agent-run tasks that tomes would need to be aware of and manage, which would lead to a poor user experience and some pretty complicated tome logic.

Proposal

TL;DR; Eldritch is one of the primary things that's special about Realm, let's really double down on it and reduce the complexity of deployment.

For these reasons, perhaps we should think of a tome as a bundle, with their own little spells (or whatever we want to call them) and any dependencies they might have. Then when imix receives a task, it will unpack the tome bundle and cast all the spells within it.

I think our goal with Realm should be to limit our focus areas and do incredibly well in the areas we do focus on. One of which is obviously eldritch, and I think consolidating deployment into tomes would help remove the complexity of the current deployment design.

Making tomes into tar bundles has the following advantages:

• We remove the need for any CDN/file API since the tomes will already include all of their dependencies
• Tomes will not need to be aware of their execution environment (e.g. worker vs agent)
• We enable an easy way for tomes to define metadata about themselves (parameters, authors, etc.)
• Enabling multiple subtasks per task (via multiple eldritch spells in a tome) has many advantages
  • We could section output and report status per spell and aggregate this into the UI
  • We could also use this for handling error boundaries, for example if there is an error in one spell it won't prevent other spells from running
  • A tome's config.yml could define execution order of these spells as well as if they are critical
    • For example, if a spell is marked as critical and fails, no other spells will be run
• We would achieve a huge reduction in deployment complexity:
  • Remove Deployments, DeploymentConfigs, ServiceConfigs, CallbackConfigs, Implants, ImplantConfigs, as well as the imix install subcommand entirely
  • Instead when running a tome, we can just have a flag that marks the run as for the worker (e.g. a "deploy" checkbox) and track that separately
    • This is actually quite similar to how we do this in Paragon, but with less complexity and more specific to our use-case (e.g. we aren't generically supporting services to run these)

In addition to the above, I propose we also enable eldritch to handle implant registration / configuration. This means that if we were to deploy a backdoor (e.g. a PAM backdoor), the tome responsible for deployment could register it with Tavern. This will enable one method of reporting what we have on a Target, as opposed to several different ways that would likely go untracked. Tomes will exist to update an implants config (e.g. change imix callback interval), and then report the status (e.g. if the config was successfully updated or something went wrong).

Example

• imix-deploy (tome folder)
  • imix (binary)
  • deploy.eld (we can work on the extension, or keep it as .tome)
  • config.yml (defines metadata for the tome)

Given the above directory structure, our workflow would look like this:

eldritch build ./imix-deploy

Which would perform a few useful tasks:

1. Perform basic lint operations on the tome, for example:
   • Any undefined / unused files?
   • Any undefined / unused params?
2. Produce a targz bundle result imix-deploy.tome

Next, we would just upload our tome to Tavern:

eldritch upload imix.tome

Though perhaps we prefer to combine the build & upload steps.

Thoughts @hulto / @Cictrone ?

[hulto]

• We remove the need for any CDN/file API since the tomes will already include all of their dependencies
  - I think a CDN/file API will still be valuable as many other redteamers expect/rely on one for more tarditional deployments. Plus the flexibility to download may come in handy.
• Tomes will not need to be aware of their execution environment (e.g. worker vs agent)
  - Will tomes executing in the worker environment execute on the worker or against the target? I think target makes the most sense but would like to verify.
• We enable an easy way for tomes to define metadata about themselves (parameters, authors, etc.)
• Enabling multiple subtasks per task (via multiple eldritch spells in a tome) has many advantages
  - Is deploy.eld from the example an eldritch spell? Or does a .eld file contain multiple spells?
  - can a deploy.eld file include other deploy.eld?
• A tome's config.yml could define execution order of these spells as well as if they are critical
  - Will tomes always execute sequentially? Can tomes fork independent spells / support a free strategy a la Ansible strategy=Free.
• In addition to the above, I propose we also enable eldritch to handle implant registration / configuration. This means that if we were to deploy a backdoor (e.g. a PAM backdoor), the tome responsible for deployment could register it with Tavern. This will enable one method of reporting what we have on a Target, as opposed to several different ways that would likely go untracked. Tomes will exist to update an implants config (e.g. change imix callback interval), and then report the status (e.g. if the config was successfully updated or something went wrong).
  - Yes!
  - How will tomes define registration? Will there be a stdlib function to register the agent?
  - What behavior is expected if no registration tome is provided to the agent? Will the registration tome be a unique type of/hardcoded tome?

[KCarretto]

I think a CDN/file API will still be valuable as many other redteamers expect/rely on one for more tarditional deployments. Plus the flexibility to download may come in handy.

See #22

Tomes will not need to be aware of their execution environment (e.g. worker vs agent)

All tomes are executed on the target, the role of the worker is just to upload them and run them on the target

Is deploy.eld from the example an eldritch spell? Or does a .eld file contain multiple spells?

Yeah in this example it's an eldritch spell, so when viewing a task it's output & status would be listed in it's own subsection

Can a deploy.eld file include other deploy.eld?

If by this you mean can the deploy.eld spell import another spell, Starlark supports this functionality through the loads() function but I'm not sure we plan to. For now perhaps it's best to keep things simple and introduce support for it later if there is a clear value-add.

Will tomes always execute sequentially? Can tomes fork independent spells / support a free strategy a la Ansible strategy=Free.

The default behavior is for tomes to not depend on each other and run concurrently, you must define dependencies in config.yml if they exist. For example, to download and run a file perhaps you have a download.eld and a exec.eld, and in the config.yml you would define that exec.eld depends on download.eld to complete successfully.

How will tomes define registration? Will there be a stdlib function to register the agent?

This warrants some further discussion, but I imagine some type of implant standard library, which could include functions for registration and config management. For example:

• implant.register("imix")
• implant.set_interval(120)
• implant.add_transport("realm-c2", "https://c2.realm.pub", proxy="https://my.proxy.org", priority=5)
• implant.remove_transport("realm-c2")
• file.write("/etc/imix.conf", implant.get_config())

What behavior is expected if no registration tome is provided to the agent? Will the registration tome be a unique type of/hardcoded tome?

To clarify, registration isn't handled by any special tome. It's something that a deployment tome could perform. For example, imagine an imix deployment tome looking like this:

• imix-deploy
  • config.yml
  • metadata.yml
  • deploy.eld
  • register.eld

In this example, deploy.eld would be responsible for setting up and persisting imix whereas register.eld would call implant methods to register installation of the implant.

[Cictrone]

I STRONGLY advise against the language setting state of the bot. If it would update a config file that’s different but updating the bot’s internal variables is just a mess going forward. We could also manage these things via the config.yml

[KCarretto]

I STRONGLY advise against the language setting state of the bot. If it would update a config file that’s different but updating the bot’s internal variables is just a mess going forward. We could also manage these things via the config.yml

Since this seems like a separate conversation that deployment, let's move it to #24

[Cictrone]

I think the main issue is going to be flinging around these chonky tomes. I think we will still need a CDN (library?) for all the times to be hosted. Also for nits:

1. the inner extension should be diff maybe .spl or .eld but having two things be tome is bad.

2. Eldritch can’t build imix as the dependency is reversed

3. the build and upload steps must be separate so we have a lint and check stage otherwise we will have garbage in the tome library.

[KCarretto]

Thanks for being engaged with the community!

A few clarifications:

• You may be right that we will still need an upload/download api for tomes, but this will require investigation
• eldritch is not building imix, it’s building the imix tome
  • I have edited the original post to make this more clear by renaming the tome to imix-deploy

My concern is that if the agent receives a task with a tome uri and needs to download it, it will cause a few issues:

• that agent is likely limited to using http(s) to download the tome, otherwise we would need to do something funky to change the tome uri based on the callback protocol
• We now must make multiple outbound requests (one for initial callback and one per task), which is not ideal as it is more noisy and increases our chances for network failure.

[KCarretto]

Implementation Details

• Tome Upload Endpoint
  • Untar uploaded file
  • Parse metadata.yml
    • Perform basic sanity checks
    • This will include parameter info (e.g. names & types) on the Tome ent
  • Create Tome ent
• Queue Tome Endpoint
  • Receive []Targets, Tome, and parameters
  • Untar Tome, replace {{ parameter }} statements with parameter values
  • Targz the result (e.g. with parameters substituted)
  • Create one task per target with the resulting targz'd Tome
• Callback Endpoint
  • Find all queued tasks for targets
  • Tar them, where the file names are the task ids
  • Agent downloads tar bundle
• SubmitTaskResult Endpoint
  • POST with format like:

{
    "task_id": 123456,
    "subtasks": [
        {
            "name": "download",
            "output": "...",
            "error_type": "",
            "error": "",
        },
         {
            "name": "exec",
            "output": "...",
            "error_type": "PythonUnavailable",
            "error": "failed to run file 'hello_world.py', no Python interpreter available",
        },
    ]
}

[hulto]

A pattern I've seen before that I kinda like is detonating an implant on your jump box / attacker VM.
This would remove the need for a separate worker node.

We'd then double down on eldritch having the ability to connect to remote hosts or proxy a users connection which IMO is the direction we should go.