5.8 additions (BC-SECURITY#730)

* allow starkiller to be disabled

* allow port to be configured via the config.yaml

* changelog

* allow for unset field

CHANGELOG.md

@@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   Add tags search to credentials endpoints (@Vinnybod)
 -   Remove unused migration scripts (@Vinnybod)
 -   Simplify TestClient setup (@Vinnybod)
+-   Allow Starkiller to be disabled (@Vinnybod)
+-   Allow API port to be configured from the config.yaml (@Vinnybod)
 
 ## [5.8.0] - 2023-11-06
 

docs/quickstart/configuration/server.md

@@ -3,6 +3,14 @@
 The Server configuration is managed via [empire/server/config.yaml](https://github.com/BC-SECURITY/Empire/blob/master/empire/client/config.yaml).
 
 * **suppress-self-cert-warning** - Suppress the http warnings when launching an Empire instance that uses a self-signed cert.
+
+* **api** - Configure the RESTful API. The only option is the port to run the API on.
+
+```yaml
+api:
+  port: 1337
+```
+
 * **database** - Configure Empire's database. Empire defaults to SQLite and has the ability to run with MySQL. For more info on the database, see the [Database](database/README.md) section.
 
 SQLite - The location of the SQLite db file is configurable.
@@ -21,8 +29,8 @@ database:
   use: mysql
   mysql:
     url: localhost
-    username: 
-    password: 
+    username:
+    password:
     database_name:
 ```
 

docs/restful-api/README.md

@@ -1,16 +1,17 @@
 # RESTful API
 
 ## Introduction
-The Empire v2 API is a RESTful API that provides access to the data in Empire. It was introduced in Empire 5.0 and replaced the old v1 API. 
-The API is powered by [FastAPI](https://fastapi.tiangolo.com/) and is available at [http://localhost:1337/api/v2/](http://localhost:1337/api/v2/). 
+The Empire v2 API is a RESTful API that provides access to the data in Empire. It was introduced in Empire 5.0 and replaced the old v1 API.
+The API is powered by [FastAPI](https://fastapi.tiangolo.com/) and is available at [http://localhost:1337/api/v2/](http://localhost:1337/api/v2/).
 The Swagger UI is available at [http://localhost:1337/docs/](http://localhost:1337/docs/).
-The docs here are to be used as a reference for the API and to explain nuances for interacting with it. For actual endpoint definitions, use the OpenAPI Spec. For explanations of what the heck a listener, stager, etc is, see the associated non-API documentation. 
+The docs here are to be used as a reference for the API and to explain nuances for interacting with it. For actual endpoint definitions, use the OpenAPI Spec. For explanations of what the heck a listener, stager, etc is, see the associated non-API documentation.
 
 The server can be launched by running `./ps-empire server` and can be connected to with the built-in client or [Starkiller](https://github.com/BC-SECURITY/Starkiller). By default, the RESTful API is started on port 1337, over HTTP without a certificate. This is because self-signed certs are blocked by most web browsers and Starkiller is used via a web browser.
 
 If launched with `--secure-api`, https will be used using the certificate located at `empire/server/data/empire.pem`, which is generated at startup.
 
-The port can be changed by supplying `--restport <PORT_NUM>` on launch.
+The port can be configured in the server `config.yaml` file by the `api.port` property.
+It can also be set by supplying `--restport <PORT_NUM>` on launch, which will take precedence over the config file.
 
 ## API Authentication
 API Authentication is handled via JSON Web Tokens (JWT).
@@ -55,7 +56,7 @@ options dictionary to contain the options that are required for associated stage
 and will be validated against the template. The options can be sent as strings, but Empire will
 still validate that they can be parsed to the correct type and raise an exception if it isn't correct.
 
-They can be created, updated, and deleted via the API. 
+They can be created, updated, and deleted via the API.
 When creating a stager, there is an option to only "generate" instead of save.
 If `save=false`, then the stager will not be saved to the database, but will be returned in the response. If the stager is a file, then the response will contain a reference to the download uri for that file.
 
@@ -101,7 +102,7 @@ is based on its internal IP address and name.
 
 ### Host Processes
 */api/v2/hosts/{host_id}/host-processes/*
-Host processes are the processes that are scraped via the `ps` command on an agent. They are read-only via the API. 
+Host processes are the processes that are scraped via the `ps` command on an agent. They are read-only via the API.
 
 ### Downloads
 */api/v2/downloads*
@@ -155,4 +156,3 @@ At the moment, there is only an endpoint for getting the version of the server.
 Users support basic CRUD operations via the API.
 There is also an endpoint for updating a user's password. Only an admin user can create and
 update other users.
-

empire/server/api/app.py

@@ -149,7 +149,11 @@ def shutdown_event():
 
     setup_socket_events(sio, main)
 
-    load_starkiller(v2App, ip, port)
+    if empire_config.starkiller.enabled:
+        log.info("Starkiller enabled. Loading.")
+        load_starkiller(v2App, ip, port)
+    else:
+        log.info("Starkiller disabled. Not loading.")
 
     cert_path = os.path.abspath("./empire/server/data/")
 

empire/server/config.yaml

@@ -1,4 +1,6 @@
 suppress-self-cert-warning: true
+api:
+  port: 1350
 database:
   use: mysql
   mysql:
@@ -40,6 +42,7 @@ database:
     #   format is "192.168.1.1,192.168.1.10-192.168.1.100,10.0.0.0/8"
     ip-blacklist: ""
 starkiller:
+  enabled: false
   repo: [email protected]:BC-SECURITY/Starkiller-Sponsors.git
   directory: empire/server/api/v2/starkiller
   # Can be a branch, tag, or commit hash

empire/server/core/config.py

@@ -17,11 +17,16 @@ def set_path(cls, v):
         return v
 
 
+class ApiConfig(EmpireBaseModel):
+    port: int = 1337
+
+
 class StarkillerConfig(EmpireBaseModel):
     repo: str = "bc-security/starkiller"
     directory: Path = "empire/server/api/v2/starkiller"
     ref: str = "main"
     auto_update: bool = True
+    enabled: bool | None = True
 
 
 class DatabaseDefaultObfuscationConfig(EmpireBaseModel):
@@ -88,6 +93,7 @@ class EmpireConfig(EmpireBaseModel):
     supress_self_cert_warning: bool = Field(
         alias="supress-self-cert-warning", default=True
     )
+    api: ApiConfig | None = ApiConfig()
     starkiller: StarkillerConfig
     database: DatabaseConfig
     plugins: dict[str, dict[str, str]] = {}

empire/server/server.py

@@ -142,7 +142,7 @@ def run(args):
     check_recommended_configuration()
 
     if not args.restport:
-        args.restport = 1337
+        args.restport = empire_config.api.port
     else:
         args.restport = int(args.restport[0])