add openapi docs

docs/SUMMARY.md

@@ -9,6 +9,7 @@
     * [Server](quickstart/configuration/server.md)
     * [Client](quickstart/configuration/client.md)
 * [RESTful API](restful-api/README.md)
+  * [OpenAPI Spec](restful-api/openapi-spec.md) 
 * [Listeners](listeners/README.md)
   * [Dropbox](listeners/dropbox.md)
   * [OneDrive](listeners/onedrive.md)

empire.py

@@ -11,6 +11,10 @@
         from empire.server import server
 
         server.run(args)
+    elif args.subparser_name == "api_export":
+        from empire.scripts.api_export import api_export
+
+        api_export(args)
     elif args.subparser_name == "sync-starkiller":
         import yaml
 

empire/arguments.py

@@ -10,6 +10,7 @@
 subparsers = parent_parser.add_subparsers(dest="subparser_name")
 
 server_parser = subparsers.add_parser("server", help="Launch Empire Server")
+api_export_parser = subparsers.add_parser("api_export", help="Export the OpenAPI spec")
 client_parser = subparsers.add_parser("client", help="Launch Empire CLI")
 sync_starkiller_parser = subparsers.add_parser(
     "sync-starkiller", help="Sync Starkiller submodule with the config"

empire/scripts/api_export.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+
+import yaml
+
+from empire.server.api.app import initialize
+from empire.server.server import set_main
+
+
+def api_export(args):
+    set_main(args)
+    app = initialize(run=False)
+    openapi = app.openapi()
+    version = openapi.get("openapi", "unknown version")
+
+    print(f"writing openapi spec v{version}")
+    file_path = Path("docs/.gitbook/assets/openapi.yaml")
+
+    file_path.write_text(yaml.dump(openapi, sort_keys=False))
+    print(f"spec written to {file_path}")
+
+    gitbook_page = Path("docs/restful-api/openapi.md")
+    with gitbook_page.open("w") as f:
+        for path, data in openapi["paths"].items():
+            for method, _ in data.items():
+                # {% swagger src="sample.yaml" path="/stars" method="post" %} sample.yaml {% endswagger %}
+                f.write(f"{{% swagger src=\"../.gitbook/assets/openapi.yaml\" path=\"{path}\" method=\"{method}\" %}}\n")
+                f.write("[openapi.yaml](../.gitbook/assets/openapi.yaml)\n")
+                f.write("{% endswagger %}\n")
+
+    print(f"gitbook page written to {gitbook_page}")

empire/server/config.yaml

@@ -3,7 +3,7 @@ api:
   port: 1337
   cert_path: empire/server/data/
 database:
-  use: mysql
+  use: sqlite
   mysql:
     url: localhost:3306
     username: empire_user

empire/server/server.py

@@ -157,7 +157,12 @@ def check_recommended_configuration():
         log.warning("Consider using MySQL instead.")
 
 
-def run(args):
+def set_main(args):
+    global main  # noqa: PLW0603
+    main = empire.MainMenu(args=args)
+
+
+def run(args): # noqa: PLR0912
     setup_logging(args)
 
     if empire_config.submodules.auto_update:
@@ -195,13 +200,12 @@ def run(args):
 
     else:
         base.startup_db()
-        global main  # noqa: PLW0603
 
         # Calling run more than once, such as in the test suite
         # Will generate more instances of MainMenu, which then
         # causes shutdown failure.
         if main is None:
-            main = empire.MainMenu(args=args)
+            set_main(args)
 
         if not (Path(empire_config.api.cert_path) / "empire-chain.pem").exists():
             log.info("Certificate not found. Generating...")