Merge branch 'master' of github.com-ddupdyke-sei:cmu-sei/GHOSTS

src/Ghosts.Api/Controllers/ClientIdController.cs

@@ -12,6 +12,10 @@
 
 namespace Ghosts.Api.Controllers
 {
+    /// <summary>
+    /// GHOSTS CLIENT CONTROLLER
+    /// These endpoints are typically only used by GHOSTS Clients installed and configured to use the GHOSTS C2
+    /// </summary>
     [Produces("application/json")]
     [Route("api/[controller]")]
     public class ClientIdController : Controller
@@ -25,8 +29,9 @@ public ClientIdController(IMachineService service)
         }
 
         /// <summary>
-        ///     Clients post to this endpoint to get their unique GHOSTS system ID
+        /// Clients use this endpoint to get their unique GHOSTS system ID
         /// </summary>
+        /// <param name="ct">Cancellation Token</param>
         /// <returns>A client's particular unique GHOSTS system ID (GUID)</returns>
         [HttpGet]
         public async Task<IActionResult> Index(CancellationToken ct)

src/Ghosts.Api/Controllers/ClientResultsController.cs

@@ -15,6 +15,10 @@
 
 namespace Ghosts.Api.Controllers
 {
+    /// <summary>
+    /// GHOSTS CLIENT CONTROLLER
+    /// These endpoints are typically only used by GHOSTS Clients installed and configured to use the GHOSTS C2
+    /// </summary>
     [Produces("application/json")]
     [Route("api/[controller]")]
     public class ClientResultsController : Controller
@@ -28,7 +32,7 @@ public ClientResultsController(IBackgroundQueue service)
         }
 
         /// <summary>
-        ///     Clients post an encrypted timeline or health payload to this endpoint
+        /// Clients post an encrypted timeline or health payload to this endpoint
         /// </summary>
         /// <param name="transmission">The encrypted timeline or health log payload</param>
         /// <param name="ct">Cancellation Token</param>
@@ -42,7 +46,7 @@ public IActionResult Secure([FromBody] EncryptedPayload transmission, Cancellati
             {
                 var key = Request.Headers["ghosts-name"].ToString();
                 //decrypt
-                transmission.Payload = Crypto.Base64Decode(transmission.Payload);
+                transmission.Payload = Base64Encoder.Base64Decode(transmission.Payload);
                 raw = Crypto.DecryptStringAes(transmission.Payload, key);
             }
             catch (Exception exc)
@@ -58,7 +62,7 @@ public IActionResult Secure([FromBody] EncryptedPayload transmission, Cancellati
         }
 
         /// <summary>
-        ///     Clients post a timeline or health payload to this endpoint
+        /// Clients post a timeline or health payload to this endpoint
         /// </summary>
         /// <param name="value">Timeline or health log payload</param>
         /// <param name="ct">Cancellation Token</param>
@@ -74,8 +78,6 @@ private IActionResult Process(HttpContext context, HttpRequest request, Transfer
         {
             var id = request.Headers["ghosts-id"];
 
-            //log.Trace($"Request by {id}");
-
             var m = WebRequestReader.GetMachine(HttpContext);
 
             if (!string.IsNullOrEmpty(id))

src/Ghosts.Api/Controllers/ClientSurveyController.cs

@@ -1,4 +1,6 @@
-using System;
+// Copyright 2017 Carnegie Mellon University. All Rights Reserved. See LICENSE.md file for terms.
+
+using System;
 using System.Threading;
 using Ghosts.Api.Infrastructure;
 using Ghosts.Api.Models;
@@ -12,6 +14,10 @@
 
 namespace ghosts.api.Controllers
 {
+    /// <summary>
+    /// GHOSTS CLIENT CONTROLLER
+    /// These endpoints are typically only used by GHOSTS Clients installed and configured to use the GHOSTS C2
+    /// </summary>
     [Produces("application/json")]
     [Route("api/[controller]")]
     public class ClientSurveyController : Controller
@@ -25,7 +31,7 @@ public ClientSurveyController(IBackgroundQueue service)
         }
 
         /// <summary>
-        ///     Clients post an encrypted survey result to this endpoint
+        /// Clients post an encrypted survey results to this endpoint
         /// </summary>
         /// <param name="transmission">The encrypted survey result</param>
         /// <param name="ct">Cancellation Token</param>
@@ -39,7 +45,7 @@ public IActionResult Secure([FromBody] EncryptedPayload transmission, Cancellati
             {
                 var key = Request.Headers["ghosts-name"].ToString();
                 //decrypt - the headers must be the same as encrypted with the client
-                transmission.Payload = Crypto.Base64Decode(transmission.Payload);
+                transmission.Payload = Base64Encoder.Base64Decode(transmission.Payload);
                 raw = Crypto.DecryptStringAes(transmission.Payload, key);
             }
             catch (Exception exc)
@@ -55,7 +61,7 @@ public IActionResult Secure([FromBody] EncryptedPayload transmission, Cancellati
         }
 
         /// <summary>
-        ///     Clients post survey result to this endpoint
+        /// Clients post survey results to this endpoint
         /// </summary>
         /// <param name="value">The client survey result</param>
         /// <param name="ct">Cancellation Token</param>

src/Ghosts.Api/Controllers/ClientTimeline.cs

@@ -0,0 +1,77 @@
+// Copyright 2017 Carnegie Mellon University. All Rights Reserved. See LICENSE.md file for terms.
+
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using Ghosts.Api.Infrastructure;
+using Ghosts.Api.Services;
+using Ghosts.Domain;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Newtonsoft.Json;
+using NLog;
+
+namespace ghosts.api.Controllers
+{
+    /// <summary>
+    /// GHOSTS CLIENT CONTROLLER
+    /// These endpoints are typically only used by GHOSTS Clients installed and configured to use the GHOSTS C2
+    /// </summary>
+    [Produces("application/json")]
+    [Route("api/[controller]")]
+    public class ClientTimelineController : Controller
+    {
+        private static readonly Logger _log = LogManager.GetCurrentClassLogger();
+        private readonly IMachineTimelineService _service;
+        private readonly IMachineService _machineService;
+
+        public ClientTimelineController(IMachineTimelineService service, IMachineService machineService)
+        {
+            _service = service;
+            _machineService = machineService;
+        }
+
+        /// <summary>
+        /// Clients pot their timelines here, so that the C2 knows what a particular agent is doing
+        /// </summary>
+        /// <param name="timeline">The client's current timeline</param>
+        /// <param name="ct">Cancellation Token</param>
+        /// <returns>The saved timeline record</returns>
+        [HttpPost]
+        public async Task<IActionResult> Index([FromBody] string timeline, CancellationToken ct)
+        {
+            var id = Request.Headers["ghosts-id"];
+
+            _log.Trace($"Request by {id}");
+
+            var m = WebRequestReader.GetMachine(HttpContext);
+
+            if (!string.IsNullOrEmpty(id))
+            {
+                m.Id = new Guid(id);
+                await _machineService.CreateAsync(m, ct);
+            }
+            else
+            {
+                if (!m.IsValid())
+                {
+                    return StatusCode(StatusCodes.Status401Unauthorized, "Invalid machine request");
+                }
+            }
+
+            Timeline tl; 
+
+            try
+            {
+                tl = JsonConvert.DeserializeObject<Timeline>(timeline);
+            }
+            catch (Exception e)
+            {
+                Console.WriteLine(e);
+                return StatusCode(StatusCodes.Status400BadRequest, "Invalid timeline file");
+            }
+
+            return Ok(await _service.CreateAsync(m, tl, ct));
+        }
+    }
+}

src/Ghosts.Api/Controllers/ClientUpdatesController.cs

@@ -13,6 +13,10 @@
 
 namespace Ghosts.Api.Controllers
 {
+    /// <summary>
+    /// GHOSTS CLIENT CONTROLLER
+    /// These endpoints are typically only used by GHOSTS Clients installed and configured to use the GHOSTS C2
+    /// </summary>
     [Produces("application/json")]
     [Route("api/[controller]")]
     public class ClientUpdatesController : Controller
@@ -28,7 +32,7 @@ public ClientUpdatesController(IMachineUpdateService updateService, IBackgroundQ
         }
 
         /// <summary>
-        ///     Clients check for updates to download here
+        /// Clients use this endpoint to check for updates for them to download
         /// </summary>
         /// <param name="ct">Cancellation Token</param>
         /// <returns>404 if no update, or a json payload of a particular update</returns>

src/Ghosts.Api/Controllers/GroupHealthController.cs

@@ -6,12 +6,10 @@
 using System.Threading.Tasks;
 using Ghosts.Api.Models;
 using Ghosts.Api.Services;
-using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
 
 namespace Ghosts.Api.Controllers
 {
-    [Authorize(Policy = "ApiUser")]
     [Produces("application/json")]
     [Route("api/group-health")]
     [ResponseCache(Duration = 5)]
@@ -26,6 +24,12 @@ public GroupHealthController(IMachineGroupService service, IMachineService servi
             _serviceMachine = serviceMachine;
         }
 
+        /// <summary>
+        /// Endpoint returns health records for all of the machines in a group
+        /// </summary>
+        /// <param name="id">Group Id</param>
+        /// <param name="ct">Cancellation Token</param>
+        /// <returns>Health records for machines in the group</returns>
         [HttpGet("{id}")]
         public async Task<IActionResult> Index([FromRoute] int id, CancellationToken ct)
         {

src/Ghosts.Api/Controllers/HomeController.cs

@@ -9,7 +9,7 @@
 namespace Ghosts.Api.Controllers
 {
     [Produces("application/json")]
-    [Route("api/Home")]
+    [Route("api/home")]
     [ResponseCache(Duration = 60)]
     public class HomeController : Controller
     {
@@ -21,9 +21,12 @@ public HomeController(ApplicationDbContext context)
         }
 
         /// <summary>
-        ///     API Home
+        /// API Home, often used to verify API is working correctly
         /// </summary>
-        /// <returns>Basic check information including version number, and a simple database connection counting machines and groups</returns>
+        /// <returns>
+        /// Basic check information including version number,
+        /// and a simple database connection counting machines and groups
+        /// </returns>
         [HttpGet]
         public IActionResult Index()
         {

src/Ghosts.Api/Controllers/MachineGroupsController.cs

@@ -9,15 +9,13 @@
 using Ghosts.Api.Models;
 using Ghosts.Api.Services;
 using Ghosts.Domain;
-using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
 using NLog;
 
 namespace Ghosts.Api.Controllers
 {
-    //[Authorize(Policy = "ApiUser")]
     [Produces("application/json")]
-    [Route("api/MachineGroups")]
+    [Route("api/machinegroups")]
     [ResponseCache(Duration = 5)]
     public class MachineGroupsController : Controller
     {
@@ -31,14 +29,24 @@ public MachineGroupsController(IMachineGroupService service, IMachineService mac
             _serviceMachine = machineService;
         }
 
-        // GET: api/MachineGroups
+        /// <summary>
+        /// Gets the group information and the machines contained therein based on the provided query
+        /// </summary>
+        /// <param name="q">Query</param>
+        /// <param name="ct">Cancellation Token</param>
+        /// <returns>Group information</returns>
         [HttpGet]
         public async Task<IEnumerable<Group>> GetMachineGroup(string q, CancellationToken ct)
         {
             return await _service.GetAsync(q, ct);
         }
 
-        // GET: api/MachineGroups/5
+        /// <summary>
+        /// Gets the group information and the machines contained therein based on a specific group Id
+        /// </summary>
+        /// <param name="id">Group Id</param>
+        /// <param name="ct">Cancellation Token</param>
+        /// <returns>Group information</returns>
         [HttpGet("{id}")]
         public async Task<IActionResult> GetMachineGroup([FromRoute] int id, CancellationToken ct)
         {
@@ -50,7 +58,12 @@ public async Task<IActionResult> GetMachineGroup([FromRoute] int id, Cancellatio
             return Ok(machineGroup);
         }
 
-        // PUT: api/MachineGroups/5
+        /// <summary>
+        /// Updates a group's information
+        /// </summary>
+        /// <param name="model">The group to update</param>
+        /// <param name="ct">Cancellation Token</param>
+        /// <returns>The updated group</returns>
         [HttpPut("{id}")]
         public async Task<IActionResult> PutMachineGroup([FromBody] Group model, CancellationToken ct)
         {
@@ -61,7 +74,12 @@ public async Task<IActionResult> PutMachineGroup([FromBody] Group model, Cancell
             return Ok(model);
         }
 
-        // POST: api/MachineGroups
+        /// <summary>
+        /// Create new group
+        /// </summary>
+        /// <param name="model">The new group to add</param>
+        /// <param name="ct">Cancellation Token</param>
+        /// <returns>The saved group</returns>
         [HttpPost]
         public async Task<IActionResult> PostMachineGroup([FromBody] Group model, CancellationToken ct)
         {
@@ -72,7 +90,12 @@ public async Task<IActionResult> PostMachineGroup([FromBody] Group model, Cancel
             return CreatedAtAction("GetMachineGroup", new {id}, model);
         }
 
-        // DELETE: api/MachineGroups/5
+        /// <summary>
+        /// Deletes a specific group
+        /// </summary>
+        /// <param name="id">The group to delete</param>
+        /// <param name="ct">Cancellation Token</param>
+        /// <returns>204 No Content</returns>
         [HttpDelete("{id}")]
         [ResponseCache(Duration = 0)]
         public async Task<IActionResult> DeleteMachineGroup([FromRoute] int id, CancellationToken ct)
@@ -84,7 +107,13 @@ public async Task<IActionResult> DeleteMachineGroup([FromRoute] int id, Cancella
             return NoContent();
         }
 
-        [AllowAnonymous]
+        /// <summary>
+        /// Send a specific command to a group of machines
+        /// </summary>
+        /// <param name="id">Group ID</param>
+        /// <param name="command">The command to execute</param>
+        /// <param name="ct">Cancellation Token</param>
+        /// <returns>The results of running the command on each machine</returns>
         [HttpPost("{id}/command")]
         public async Task<IActionResult> SendCommand([FromRoute] int id, string command, CancellationToken ct)
         {
@@ -118,7 +147,12 @@ public async Task<IActionResult> SendCommand([FromRoute] int id, string command,
             }
         }
 
-        [AllowAnonymous]
+        /// <summary>
+        /// Gets teh activity for a group of machines
+        /// </summary>
+        /// <param name="id">Group ID</param>
+        /// <param name="ct">Cancellation token</param>
+        /// <returns>The activity for the group</returns>
         [HttpGet("{id}/activity")]
         public async Task<IActionResult> Activity([FromRoute] int id, CancellationToken ct)
         {