API

ACE management and tasking occurs through the web application's RESTful API. This page describes the different components of the API, and shows examples of interacting with the API through the ACE PowerShell module.

Computer

The Computer Controller allows enumeration of Computer objects that have been populated via Discovery. Computer objects represent systems that may be targeted by ACE Sweeps. Computers must be "discovered" and thus cannot be added directly.

GET ace/computer

List computers that have been enumerated by an ACE discovery.

Example: Get-AceComputer

GET ace/computer/{id}

Return a specific computer, specified by unique identifier, that has been enumerated by an ACE discovery.

Example: Get-AceComputer

Credential

The Credential Controller is used to manage endpoint credentials. Credential objects are usernames and passwords to be used by ACE for authenticating with systems that are targeted by a sweep. Passwords are encrypted at rest and only decrypted in memory when used to authenticate.

GET ace/credential/delete/{id}

Delete a credential.

Example: Remove-AceCredential

GET ace/credential

List credentials.

Example: Get-AceCredential

POST ace/credential

Add a credential to the ACE database. Added credentials must be passed in the following format:

public class CredentialViewModel
{
    [Required]
    public string UserName { get; set; }
    
    [Required]
    public string Password { get; set; }
}

Example: New-AceCredential

PUT ace/credential/{id}

Update a credential in the ACE database. The specific credential to update must be specified by it's unique identifier. The credential object must be passed in the following format:

public class CredentialViewModel
{
    [Required]
    public string UserName { get; set; }

    [Required]
    public string Password { get; set; }
}

Example: Update-AceCredential

Discover

The Discover Controller is intended to enumerate endpoints to scan. Enumeration can be based on Active Directory or an array of systems (IP Addresses or Fully Qualified Host Names).

POST ace/discover/domain

public class DiscoveryActiveDirectoryViewModel
{
    [Required]
    public string Domain { get; set; }

    [Required]
    public Guid CredentialId { get; set; }
}

POST ace/discover/computerlist

public class DiscoveryComputerListViewModel
{
    [Required]
    public string[] ComputerName { get; set; }

    [Required]
    public Guid CredentialId { get; set; }
}

Result

The Result Controller receives and forwards scan results to the Enrichment Pipeline. The Result Controller is the only Controller that does not require API Key authentication.

POST ace/result/{sweepId}

Scan results will be posted to the Result Controller with their unique Sweep Identifier.

The required format of posted results is below:

public class SweepResultViewModel
{
    [Required]
    public string ComputerName { get; set; }

    [Required]
    public string ScanType { get; set; }

    [Required]
    public string RoutingKey { get; set; }

    [Required]
    public string ResultDate { get; set; }

    [Required]
    public string ScanId { get; set; }

    [Required]
    public string[] Data { get; set; }
}

Script

The Script Controller is used to manage scripts that are intended to collect data from endpoints.

GET ace/script/delete/{id}

Delete a script.

GET ace/script

List scripts.

POST ace/script

Add a script so it can be executed against target computers.

New scripts must follow the format below:

public class FileViewModel
{
    [Required]
    public string Name { get; set; }

    [Required]
    public byte[] Content { get; set; }

    [Required]
    public string[] Enrichment { get; set; }

    [Required]
    public string Output { get; set; }

    [Required]
    public string Language { get; set; }
}

Sweep

The Sweep Controller is used to task and manage data collection sweeps.

GET ace/sweep

List ACE sweeps.

GET ace/sweep/{id}

List an ACE sweep by unique identifier.

POST ace/sweep

public class SweepExecutionViewModel
{
    [Required]
    public Guid[] ComputerId { get; set; }

    [Required]
    public Guid ScriptId { get; set; }

    [Required]
    public string Uri { get; set; }
}

User

The User Controller is used to create and manage users for the ACE Web Application. Each new user is assigned an API Key, which must be used to authenticate future API requests. ACE is created with a default user named "Admin" with an API Key of d0bf91fa-9934-40ca-8cb9-5a1168546abc. As the Admin user's API Key is documented, it is recommended that the Admin user is used only to create a new user account before it is deleted.

GET ace/user/delete/{id}

Delete a user account.

GET ace/user

List user accounts.

POST ace/user

Add a new user account.

User accounts must follow the format below:

public class UserViewModel
{
    [Required]
    public string UserName { get; set; }

    public string FirstName { get; set; }

    public string LastName { get; set; }

    public bool IsAdmin { get; set; }
}

PUT ace/user/{id}

Update an existing user account.

User accounts must be submitted following the format shown below:

public class UserViewModel
{
    [Required]
    public string UserName { get; set; }

    public string FirstName { get; set; }

    public string LastName { get; set; }

    public bool IsAdmin { get; set; }
}