Execute Abilities Over REST API

[BIGdeadLock]

Hello,

Really love the tool. There are some amazing features that I did not imagined an open source threat simulator will had.
The REST API is a really important feature of the tool and in my opinion still a little lacking in its documentation.
From what I see in the source code there are a lot of endpoints that are not mentioned in the documentation, for example:
the POST index="result" endpoint, the agent_configuration endpoint etc.
The one I use the most is the access/exploit endpoint to run a single ability against a single agent.
The documentation about how to use the facts in lacking because the example shown is not representive of how the facts are coded. For example showing an example of {trait: remote.host.ip ,value: 127.0.0.1} is more informative than {trait: username, value: "admin"}.
In addition in the access_api.py in the access plugin:

Every ability will return "complete" without any information if it was successfully completed or not.
I added the following code instead of returning "complete":

If the ability was ran it will return the link_id. With the link_id I can query the result endpoint and if no link_id was return I know that the ability failed to run. It is a nice workaround for now. Hope you can do even do something more advanced for that purpose like returning the status of the attack so that the user will not have to query the result endpoint in addition to fetch the status of the attack.

[bleepbop]

Hi, thanks for using CALDERA! These are some good points. The documentation for the original v1 REST api can be improved upon, and I will try to open a ticket for this.

For the exploit endpoint, abilities are added to the agent link chain where they wait to execute. I believe the reason "complete" is returned is to indicate that they have successfully been added to the chain, rather than indicating that they have finished execution (depending on the ability, this can take some time). I'm not sure if there are currently any plans on updating the plugins to the new v2 API.

We've been working on rolling out a v2 API with included Swagger documentation for a lot of the first class objects (operations, abilities, agents, etc). Some of these endpoints have already been merged into the master branch. The documentation for the completed endpoints can be seen by appending /api/docs to the server URL.

One workaround to the problem you are running into (although one that requires a few requests) could be the following:

1. send exploit POST request to desired agent.
2. Use v2 API to get link ID from agent: GET /api/v2/agents/{paw} where {paw} is from the desired agent.
3. Use the link IDs returned by the previous API request to make a result POST request.

This isn't the cleanest method, but I'm not sure if there are plans to update the access REST API as of now. Thank you for the feedback!

[BIGdeadLock]

@bleepbop

Hello.

Thanks for the answer!

Step 2 you mention will return all the links the agent was involved with is it not?

I think sending the link instead of sending "complete" accomplish the same thing - Get an indication that the attack was added to the chain.
In addition it give you additional information you can later use in the "result" endpoint. It still requires two API calls but is more cleaner (in my opinion) than returning the agent's entire links.

In addition, I want to send attacks that requires params like the host.remote.ip. I've noticed that some attacks' yaml files (in the stockpile plugin) contain the relationship field where there is information about what Facts I can add to the attack. This way I can dynamically change the attack. The problem that a lot of attacks does not have that "relationship" field but the GUI still knows that the attack need a Fact to operate. For example:

But the ability return from the API does not have that Fact:

As oppose to:

and:

As a result it is hard to dynamically on run time know what Facts the ability requires.

Do you have a solution for that?

[bleepbop]

Apologies for the late response. I do agree your method is much more straightforward, but unfortunately the steps I listed out above are the only way I currently know of accomplishing this task without making modifications to the access plugin. I will add a ticket for updating the access endpoint output to the backlog.

As for your question about the ability facts, I'm not sure that I follow entirely. I do know that not every ability executor has a parser, so when the ability is run, the link facts will not be updated by some of the base services responsible for running the link/ability. Because of this, some of the executors may not have relationships either. The exploit endpoint should allow you to specify the parameters that you mentioned. But as far as knowing which facts/variables are necessary for certain commands, I don't believe that is supported by the current GUI; you may have to refer to specific ability files, or click "populate variables" to confirm that arguments are required. Please let me know if you have any other questions!

[BIGdeadLock]

@bleepbop

Hello,

Thanks for the reply.

About the facts:

What I want to accomplish is to run abilities dynamically through the REST API by sending the ability id and the facts that it required with a python script.
The problem I don't know how to accomplish that because not all abilities have their facts mentioned in the endpoint - api/rest {index: abilities}. As a result, I don't know which facts I need to send dynamically. For the time being I'm just sending all the facts that I know exists to each attack which is not good as some attacks throw me "To much data exception" I guess because of that.

Need your help with that

[bleepbop]

Hi again, unfortunately I don't believe this functionality is currently supported by the API. With the v2 operations api, we are able to apply pre-generated links/abilities to an agent in an operation, as well as manual commands, but there is not a way to change the fact values for these links. For figuring out which facts are required dynamically, neither the old rest api nor the v2 api currently support this.

[Anth0rx]

I also vote for @BIGdeadLock's suggestion. Directly returning the link is cleaner than having to parse the entire "result" JSON object. That way it is possible to directly process the last action's results.