Faction API

Faction provides two ways to access its API, REST and SocketIO. REST leverages traditional HTTP verbs to perform actions against objects. SocketIO is a transport provided over Web Sockets to allow for real-time API access. It uses message types and JSON messages to perform actions.

All parameter names for the Faction API are Case Sensitive

Authenticating to the API

No matter the API calls you're using you'll need an API key to authenticate. API keys consist of a key ID and a secret and they can be used in the following ways:

  • Cookies: Set the AccessKeyId and AccessSecret cookies

  • Header: The format for this is Authorization: token [base64 string] where "base64 string" is the base64 value of [AccessKeyId]:[AccessSecret]

  • GET Parameter: You can append your key ID and secret to a URL in the format of ?token=[AccessKeyId]:[AccessSecret]

Logging into Faction

To interact with Faction, you'll need an API key. To get an API key, use the Login endpoint.

The login endpoint is the only endpoint in Faction that will accept a username and password for authentication. All other endpoints need to use an API key.

get
Get Login Status

https://faction_api_url/api/v1/login/
Request
Response
200: OK
{
"Message": "User is logged in",
"Success": true
}

post
Login to Faction

https://faction_api_url/api/v1/login/
This method responds with a Session API key. This key will be revoked the next time you login.
Request
Response
Body Parameters
Username
required
string
The username
Password
required
string
The password
200: OK
{
"AccessKeyId": "<Access Key Name>",
"AccessSecret": "<Access Key Secret>",
"Success": true,
"UserId": <User ID>,
"UserRole": "<User Role>",
"Username": "<Username>"
}

Whenever this endpoint is used, any previous Session API keys are invalided. Because of this you should not use the API key you receive from this endpoint in scripts or programs. Instead, create a new API key using the API key endpoint. This API key should be used by users Faction client (for example, the Faction Console)

API Keys

get
List API Keys for a User

https://faction_api_url/api/v1/user/:user_id/apikey/
Returns a list of API keys
Request
Response
Path Parameters
user_id
required
integer
The User ID of the user you're getting API keys for
200: OK
{
"Results": [
{
"Created": "<ISO 8601 Date/Time>",
"Id": <API Key ID>,
"LastUsed": "<ISO 8601 Date/Time>",
"Name": "<API Key Name>",
"Type": "<API Key Type (SessionToken or Access)>"
}
],
"Success": true
}

post
Create a new API key

https://faction_api_url/api/v1/user/:user_id/apikey/
This method allows you to create a new API key
Request
Response
Path Parameters
user_id
required
integer
The User ID of the user you're creating an API key for
200: OK
{
"Id": API Key ID,
"Name": "<API Key Name>",
"Secret": "<API Secret>",
"Success": true
}

delete
Delete an API key

https://faction_api_url/api/v1/user/:user_id/apikey/:api_key_id/
The method disables a given API key
Request
Response
Path Parameters
user_id
required
integer
The User ID of the user you're getting an API key for
api_key_id
required
integer
The ID of the API key
200: OK
{
"Message": "Api Key <API Key Name> deleted",
"Success": true
}

Interacting with Agents

get
Get Agent Details

https://faction_api_url/api/v1/agent/:agent_id/
This method is used to request either an individual Faction agent, or a list of all agents.
Request
Response
Path Parameters
agent_id
optional
integer
The ID of the Agent
200: OK
{
"Admin": <Boolean>,
"AgentType": {
"Id": <Agent Type ID>,
"Name": "<Agent Type Name>"
},
"ExternalIP": "<External IP Address>",
"Hostname": "<Hostname>",
"Id": <Agent ID>,
"InitialCheckin": "<ISO 8601 Date/Time>",
"InternalIP": "INternal IP Address>,
"LastCheckin": "<ISO 8601 Date/Time>",
"Name": "<Agent Name>",
"OperatingSystem": "<Agent Operating System>",
"Pid": <Process ID>,
"Transport": {
"Id": <Transport ID>,
"Name": "<Transport Name>",
"TransportType": "<Transport Type>"
},
"Username": "<Username the Agent is running under>",
"Visible": <Boolean>
}

put
Update an Agent

https://faction_api/api/v1/agents/:agent_id/
Updates an Agent
Request
Response
Path Parameters
agent_id
required
integer
The ID of the Agent
Body Parameters
Visibility
optional
boolean
Whether the agent is visible in Faction or not
Name
optional
string
The name of the agent
200: OK
{
"Admin": <Boolean>,
"AgentType": {
"Id": <Agent Type ID>,
"Name": "<Agent Type Name>"
},
"ExternalIP": "<External IP Address>",
"Hostname": "<Hostname>",
"Id": <Agent ID>,
"InitialCheckin": "<ISO 8601 Date/Time>",
"InternalIP": "INternal IP Address>,
"LastCheckin": "<ISO 8601 Date/Time>",
"Name": "<Agent Name>",
"OperatingSystem": "<Agent Operating System>",
"Pid": <Process ID>,
"Transport": {
"Id": <Transport ID>,
"Name": "<Transport Name>",
"TransportType": "<Transport Type>"
},
"Username": "<Username the Agent is running under>",
"Visible": <Boolean>
}

delete
Hide an Agent

https://faction_api/api/v1/agents/:agent_id/
Hides the specified agent
Request
Response
Path Parameters
agent_id
required
integer
The ID of the Agent
200: OK
{
"Admin": <Boolean>,
"AgentType": {
"Id": <Agent Type ID>,
"Name": "<Agent Type Name>"
},
"ExternalIP": "<External IP Address>",
"Hostname": "<Hostname>",
"Id": <Agent ID>,
"InitialCheckin": "<ISO 8601 Date/Time>",
"InternalIP": "INternal IP Address>,
"LastCheckin": "<ISO 8601 Date/Time>",
"Name": "<Agent Name>",
"OperatingSystem": "<Agent Operating System>",
"Pid": <Process ID>,
"Transport": {
"Id": <Transport ID>,
"Name": "<Transport Name>",
"TransportType": "<Transport Type>"
},
"Username": "<Username the Agent is running under>",
"Visible": false
}

Agent Staging

post
Stage an Agent

https://faction_api/api/v1/agent/:payload_name/:staging_id/
This endpoint is used by a payload to register an Agent with Faction. The payload encrypts a json blob of system information using the payloads password. In response, Faction returns a series of tasks for the payload to run that set it up as an agent, including a new password that is used for all future communication.
Request
Response
Path Parameters
payload_name
required
string
The name of the payload that is making the staging request
staging_id
required
string
This is a string generated by the payload that is used to identify the staging request in the future.
Body Parameters
Message
required
string
The Base64 encoded, encrypted JSON blob of system information.
TransportId
required
integer
The ID of the Transport server that made this request
SourceIp
optional
string
The External IP address that this request is coming from. Typically this is added by a Transport server so Faction knows the IP that this request came from. If this isn't specified, Faction will use the IP address from the API connection.
200: OK
{
"AgentName": "<The Staging Id>",
"Message": "<Base64 encoded, encrypted JSON blob of AgentTasks>"
}

Agent Checkins

This endpoint is used by Transports and Agents when they check in. It handles returning encrypted tasks for agents and receiving encrypted task results from agents.

get
Get Agent Task Messages

https://faction_url/api/v1/agent/:agent_name/checkin/
Returns a JSON string containing an base64 encoded, encrypted list of Agent Task Messages (if any are avaiable)
Request
Response
Path Parameters
agent_name
required
string
The name of the agent that you're receiving tasks for
200: OK
{
"AgentName": "<The Agent Name>",
"Message": "<Base64 encoded, encrypted JSON blob of AgentTasks>"
}

post
Upload Agent Task Response

https://faction_url/api/v1/agent/:agent_name/checkin/
Request
Response
Path Parameters
agent_name
required
string
The name of the agent that the message is coming from
Body Parameters
Message
required
string
The base64 encoded, encrypted JSON blob of Agent Task Response messages
TransportId
required
integer
The ID of the Transport handling this request
SourceIp
optional
string
The external IP address for the agent, else the IP of the transport is used. If this field is not populated, Faction will use the IP address from the connection.
200: OK
{
"AgentName": "<The Agent Name>",
"Message": "<Base64 encoded, encrypted JSON blob of AgentTasks>"
}

Agent Tasks

Used to get existing agent tasks. If you need to create a new agent task, use the Console (Agent) API endpoint.

get
Get Agent Tasks

https://faction_api_url/api/v1/task/:task_id/
Request
Response
Path Parameters
task_id
optional
string
If specified, returns a single task matching that ID
200: OK
{
"Results": [
{
"Action": "<Task Action>",
"AgentId": <Agent ID>,
"AgentName": "<Agent Name>",
"Command": "<Task Command>",
"Complete": <Has the Task Completed: Boolean>,
"Created": "<ISO 8601 Date Time>",
"Id": <Task ID>,
"Success": <Was the Task Successful: Boolean>,
"Updates": [
{
"Complete": <Boolean>,
"Message": "<Task Output>",
"Received": "<ISO 8601 Date Time>",
"Success": <Boolean>
}
],
"Username": "<Username that issued the task>"
}
],
"Success": true
}

Console Message (Agent)

This endpoint is used for to issue commands against a Faction agent

get
Get Console Messages

https://faction_api_url/api/v1/agent/:agent_id/console/
Retrieve a list of console message from this agent. This includes messages from users (for example when they type a command) and responses from the agent (what is displayed from that command)
Request
Response
Path Parameters
agent_id
required
integer
The Agent ID
200: OK
Returns a list of Console Messages.
{
"Results": [
{
"AgentId": <Agent Id>,
"Content": "<Raw Content, used for file uploads",
"Display": "<Message to display to user>",
"Received": "<ISO 8601 Date Time>",
"Type": "<Message Type>",
"UserId": <User Id that issued the message>,
"Username": "<User name that issued the message>"
}
],
"Success": true
}

post
Send a Console Message

https://faction_api_url/api/v1/agent/:agent_id/console/
This endpoint allows you to send a command to an agent
Request
Response
Path Parameters
agent_id
required
integer
The ID of the agent you're sending a command to
Body Parameters
Content
required
string
The command being sent to the agent
200: OK
{
"AgentId": <Agent ID>,
"Content": "<Raw Command Content>",
"Display": "<Display Friendly Command>",
"UserId": <User ID>
}

Console Message (Agent Task)

This endpoint returns all of the console messages associated with a given task.

get
Retrieve a Console Message for a Task

https://faction_api_url/api/v1/task/:task_id/console/
Request
Response
Path Parameters
task_id
required
integer
The ID of the Agent Task that you're getting the console message for.
200: OK
{
"Results": [
{
"AgentId": <Agent ID>,
"Content": "<Raw Task Content>",
"Display": "<Display Friendly Content>",
"Received": "ISO 8601 Date/Time",
"Type": "<Message Type>",
"UserId": <User ID>,
"Username": "<Username>"
},
{
"AgentId": <Agent ID>,
"Content": "<Raw Task Content>",
"Display": "<Display Friendly Content>",
"Received": "ISO 8601 Date/Time",
"Type": "<Message Type>",
"UserId": <User ID>,
"Username": "<Username>"
}
],
"Success": true
}

Transports

get
Get Transport Information

https://faction_api_url/api/v1/transport/:transport_id/
This method returns information about a given Transport. If no Transport ID is provided, a list of all transports is returned.
Request
Response
Path Parameters
transport_id
optional
integer
The ID of the Transport
200: OK
{
"Results": [
{
"ApiKeyId": <API Key Id>,
"ApiKeyName": "<API Key Name>",
"Configuration": "<Agent Configuration>",
"Created": <ISO 8601 Date/Time>,
"Enabled": <Boolean>,
"Guid": "<Transport GUID>",
"Id": <Transport ID>,
"LastCheckin": <ISO 8601 Date/Time>,
"Name": "<Transport Name>",
"TransportType": "<Transport Type>",
"Visible": <Boolean>
}
],
"Success": "True"
}

post
Create a Transport

https://faction_api_url/api/v1/transport/
Creates a Transport and returns an API key for use by the Transport Server
Request
Response
Body Parameters
Name
optional
string
200: OK
{
"ApiKey": {
"KeyName": "<API Key Name>",
"Secret": "<API Secret>"
},
"Success": true,
"Transport": {
"ApiKeyId": <API Key Id>,
"ApiKeyName": "<API Key Name>",
"Configuration": null,
"Created": "<ISO 8601 Date/Time>",
"Enabled": <Boolean>,
"Guid": null,
"Id": <Transport Id>,
"LastCheckin": null,
"Name": "<Transport Name>",
"TransportType": null,
"Visible": true
},
"TransportId": 3
}

put
Update a Transport

https://faction_api_url/api/v1/transport/:transport_id/
This method is used to update a transport, it is used by transport servers to register with Faction.
Request
Response
Path Parameters
transport_id
required
integer
The ID of the Transports
Body Parameters
Name
optional
string
User provided name of the Transport
TransportType
optional
string
The type of Transport
Guid
optional
string
The GUID for the Transport. This should also be the same. It is used to map transport modules to transports.
Configuration
optional
string
The configuration used by agent transport modules. This is passed to the build script when the transport module is built.
Enabled
optional
boolean
Determines whether the Transport is enabled or not.
Visible
optional
boolean
Determines whether the Transport shows up in the Faction UI, if set to False "Enabled" is also set to False
200: OK
{
"Success": true,
"Transport": {
"ApiKeyId": <API Key Id>,
"Configuration": "<Agent Configuration>",
"Enabled": <Boolean>,
"Guid": "<Transport GUID>",
"Id": <Transport ID>,
"Name": "<Transport Name>",
"TransportType": "<Transport Type>",
"Visible": <Boolean>
}
}

delete
Remove a Transport

https://faction_api_url/api/v1/transport/:transport_id/
Hides and disables a Faction transport
Request
Response
Path Parameters
transport_id
optional
integer
The ID of the Transport
200: OK
{
"Success": true,
"Transport": {
"ApiKeyId": <API Key ID>,
"Created": "<ISO 8601 Date/Time>",
"Enabled": false,
"Id": <Transport Id>,
"Name": "<Transport Name>",
"Visible": false
}
}