Merge pull request EmpireProject#797 from BC-SECURITY/5.10-dev

5.10-dev -> private-main

.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    target-branch: "private-main"

.github/workflows/lint-and-test.yml

@@ -12,10 +12,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - uses: psf/black@23.12.0
+      - uses: psf/black@24.2.0
       - name: Run ruff
         run: |
-          pip install ruff==0.1.9
+          pip install ruff==0.2.1
           ruff .
   matrix-prep-config:
     runs-on: ubuntu-latest

.pre-commit-config.yaml

@@ -9,13 +9,13 @@ repos:
     - id: end-of-file-fixer
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.1.9
+  rev: v0.2.1
   hooks:
     - id: ruff
       args: [--fix, --exit-non-zero-on-fix]
 
 -   repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 23.12.0
+    rev: 24.2.0
     hooks:
     - id: black
       language_version: python3.10

CHANGELOG.md

@@ -14,6 +14,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+-   Added dependabot for github actions dependencies (@Vinnybod)
+-   Added install option to ./ps-empire file (@Cx01N)
+-   Added auto pull options for submodules on startup (@Cx01N)
+-   Added hook and socket message to receive callback messages for individual agents (@AaronVigal)
+-   Added sacrificial Spawn Process bof (@Cx01N)
+-   Added suggested values to most modules (@Cx01N)
+
+### Changed
+
+-   Updated all dependencies (@Vinnybod)
+-   Updated Dockerfile and install script to Python 3.12.2 (@Vinnybod)
+-   Updated starkiller snyc to no longer require root (@Cx01N)
+-   Change file permissions for empire and listener logs to be non-root (@Cx01N)
+
+### Fixed
+
+-   Fixed issue loading `openapi.json` (@Vinnybod)
+-   Fixed issue when False is given for options and option is appended with 'False' (@Cx01N)
+-   Fixed module generation error in ComputerDetails (@Cx01N)
+
 ## [5.9.5] - 2024-02-22
 
 ## [5.9.4] - 2024-02-17

Dockerfile

@@ -7,7 +7,7 @@
 # 2) create volume storage: `docker create -v /empire --name data bcsecurity/empire`
 # 3) run out container: `docker run -it --volumes-from data bcsecurity/empire /bin/bash`
 
-FROM python:3.12.1-bullseye
+FROM python:3.12.2-bullseye
 
 LABEL maintainer="bc-security"
 LABEL description="Dockerfile for Empire server and client. https://bc-security.gitbook.io/empire-wiki/quickstart/installation#docker"

README.md

@@ -53,14 +53,15 @@ Empire is a post-exploitation and adversary emulation framework that is used to
 - [ProcessInjection](https://github.com/3xpl01tc0d3r/ProcessInjection)
 - And Many More
 
+<!---
 ## Sponsors
 <div align="center">
 
 [<img src="https://github.com/BC-SECURITY/Empire/assets/9831420/f273f4b0-400c-49ce-b62f-521239a86754" width="100"/>](https://www.cybrary.it/)
 
 [<img src="https://github.com/BC-SECURITY/Empire/assets/9831420/d14af000-80d2-4f67-b70c-b62ac42b6a52" width="100"/>](https://twitter.com/joehelle)
-
 </div>
+--->
 
 ## Release Notes
 
@@ -80,7 +81,7 @@ After cloning the repo, you can checkout the latest stable release by running th
 git clone --recursive https://github.com/BC-SECURITY/Empire.git
 cd Empire
 ./setup/checkout-latest-tag.sh
-./setup/install.sh
+./ps-empire install -y
 ```
 
 If you are using the sponsors version of Empire, it will pull the sponsors version of Starkiller.

docs/plugins/hooks-and-filters.md

@@ -66,6 +66,10 @@ This event is triggered after the tasking results are received and after they ar
 
  This event is triggered after the agent has completed the stage2 of the checkin process, and the sysinfo has been written to the database. Its arguments are (db: Session, agent: models.Agent)
 
+* AFTER\_AGENT\_CALLBACK\_HOOK
+
+This event is triggered each time an agent calls back to the C2 server, after the sysinfo has been written to the database. Its arguments are (db: Session, agent_id: str)
+
 _The number of events at the moment is very minimal. If there's an event that you would like added, open an issue on the GitHub repo, come chat in our Discord, or put up a pull request._
 
 ### Real World Examples

docs/quickstart/configuration/server.md

@@ -90,3 +90,10 @@ directories:
 ```
 
 * **logging** - See [Logging](../../logging/logging.md) for more information on logging configuration.
+
+* **submodules** - Control if submodules wil be auto updated on startup.
+
+```
+submodules:
+  auto_update: true
+```

docs/quickstart/installation/README.md

@@ -19,7 +19,7 @@ Note: The `main` branch is a reflection of the latest changes and may not always
 git clone --recursive https://github.com/BC-SECURITY/Empire.git
 cd Empire
 ./setup/checkout-latest-tag.sh
-./setup/install.sh
+./ps-empire install -y
 ```
 
 **Sponsors:**
@@ -28,7 +28,7 @@ cd Empire
 git clone --recursive https://github.com/BC-SECURITY/Empire-Sponsors.git
 cd Empire-Sponsors
 ./setup/checkout-latest-tag.sh sponsors
-./setup/install.sh
+./ps-empire install -y
 ```
 
 If you are using the sponsors version of Empire, it will pull the sponsors version of Starkiller.

empire/arguments.py

@@ -3,6 +3,7 @@
 Life saver comment on separating the parser.
 https://stackoverflow.com/a/30217387
 """
+
 import argparse
 
 parent_parser = argparse.ArgumentParser()
@@ -13,6 +14,12 @@
 sync_starkiller_parser = subparsers.add_parser(
     "sync-starkiller", help="Sync Starkiller submodule with the config"
 )
+install_parser = subparsers.add_parser("install", help="Install the Empire framework")
+install_parser.add_argument(
+    "-y",
+    action="store_true",
+    help="Automatically say yes to all prompts during installation",
+)
 
 # Client Args
 client_parser.add_argument(

empire/client/client.py

@@ -407,9 +407,11 @@ def parse_command_line(self, text: str, cmd_line: list[str], resource_file=False
             func = None
             with contextlib.suppress(Exception):
                 func = getattr(
-                    menu_state.current_menu
-                    if hasattr(menu_state.current_menu, cmd_line[1])
-                    else self,
+                    (
+                        menu_state.current_menu
+                        if hasattr(menu_state.current_menu, cmd_line[1])
+                        else self
+                    ),
                     cmd_line[1],
                 )
 
@@ -419,9 +421,11 @@ def parse_command_line(self, text: str, cmd_line: list[str], resource_file=False
             func = None
             with contextlib.suppress(Exception):
                 func = getattr(
-                    menu_state.current_menu
-                    if hasattr(menu_state.current_menu, cmd_line[0])
-                    else self,
+                    (
+                        menu_state.current_menu
+                        if hasattr(menu_state.current_menu, cmd_line[0])
+                        else self
+                    ),
                     cmd_line[0],
                 )
 

empire/scripts/sync_starkiller.py

@@ -1,7 +1,8 @@
 import logging
-import subprocess
 from pathlib import Path
 
+from empire.server.utils.file_util import run_as_user
+
 log = logging.getLogger(__name__)
 
 
@@ -26,23 +27,18 @@ def sync_starkiller(empire_config):
 
 
 def _clone_starkiller(starkiller_config: dict, starkiller_dir: str):
-    subprocess.run(
-        ["git", "clone", starkiller_config["repo"], starkiller_dir],
-        check=True,
-    )
+    run_as_user(["git", "clone", starkiller_config["repo"], starkiller_dir])
 
 
 def _fetch_checkout_pull(remote_repo, ref, cwd):
-    subprocess.run(
+    run_as_user(
         ["git", "remote", "set-url", "origin", remote_repo],
         cwd=cwd,
-        check=True,
     )
 
-    subprocess.run(["git", "fetch"], cwd=cwd, check=True)
-    subprocess.run(
+    run_as_user(["git", "fetch"], cwd=cwd)
+    run_as_user(
         ["git", "checkout", ref],
         cwd=cwd,
-        check=True,
     )
-    subprocess.run(["git", "pull", "origin", ref], cwd=cwd)
+    run_as_user(["git", "pull", "origin", ref], cwd=cwd)

empire/server/api/v2/obfuscation/obfuscation_api.py

@@ -122,7 +122,7 @@ async def update_obfuscation_config(
     language: str,
     obf_req: ObfuscationConfigUpdateRequest,
     db: CurrentSession,
-    db_obf_config: models.Bypass = Depends(get_obfuscation_config),
+    db_obf_config: models.ObfuscationConfig = Depends(get_obfuscation_config),
 ):
     resp, err = obfuscation_service.update_obfuscation_config(
         db, db_obf_config, obf_req
@@ -153,7 +153,7 @@ async def preobfuscate_modules(
         )
 
     background_tasks.add_task(
-        obfuscation_service.preobfuscate_modules, db, db_obf_config, reobfuscate
+        obfuscation_service.preobfuscate_modules, language, reobfuscate
     )
 
 

empire/server/api/v2/shared_dto.py

@@ -1,7 +1,11 @@
 from enum import Enum
 from typing import Annotated, Any
 
-from pydantic import BaseModel, BeforeValidator, ConfigDict, field_validator
+from pydantic import (
+    BaseModel,
+    BeforeValidator,
+    ConfigDict,
+)
 
 from empire.server.core.db import models
 
@@ -22,26 +26,22 @@ class ValueType(str, Enum):
     file = "FILE"
 
 
+# Ensure the functionality of pydantic v1 coercing values to strings
+# https://github.com/pydantic/pydantic/issues/5606
+def coerce_to_string(v: Any):
+    if isinstance(v, list):
+        return [str(value) for value in v]
+    return str(v)
+
+
 class CustomOptionSchema(BaseModel):
     description: str
     required: bool
-    value: str
-    suggested_values: list[str]
+    value: Annotated[str, BeforeValidator(coerce_to_string)]
+    suggested_values: Annotated[list[str], BeforeValidator(coerce_to_string)]
     strict: bool
     value_type: ValueType
 
-    # Ensure the functionality of pydantic v1 coercing values to strings
-    # https://github.com/pydantic/pydantic/issues/5606
-    @field_validator("value", mode="plain")
-    @classmethod
-    def check_value(cls, v):
-        return str(v)
-
-    @field_validator("suggested_values", mode="plain")
-    @classmethod
-    def check_suggested_values(cls, v):
-        return [str(value) for value in v]
-
 
 class OrderDirection(str, Enum):
     asc = "asc"

empire/server/api/v2/websocket/socketio.py

@@ -157,6 +157,9 @@ async def on_participants(sid, data=None):
     async def agent_socket_hook(db: Session, agent: models.Agent):
         await sio.emit("agents/new", domain_to_dto_agent(agent).model_dump())
 
+    async def agent_callback_hook(db: Session, agent_id: str):
+        await sio.emit("agents/callback", {"agent_id": agent_id})
+
     async def task_socket_hook(db: Session, task: models.AgentTask):
         # temporary tasks come back as None and cause an error here
         if task and "function Get-Keystrokes" not in task.input:
@@ -171,6 +174,9 @@ async def listener_socket_hook(db: Session, listener: models.Listener):
     hooks.register_hook(
         hooks.AFTER_AGENT_CHECKIN_HOOK, "agent_socket_hook", agent_socket_hook
     )
+    hooks.register_hook(
+        hooks.AFTER_AGENT_CALLBACK_HOOK, "agent_callback_hook", agent_callback_hook
+    )
     hooks.register_hook(
         hooks.AFTER_TASKING_RESULT_HOOK, "task_socket_hook", task_socket_hook
     )

empire/server/common/agents.py

@@ -33,6 +33,7 @@
 Most methods utilize self.lock to deal with the concurreny issue of kicking off threaded listeners.
 
 """
+
 import base64
 import contextlib
 import json
@@ -1197,6 +1198,12 @@ def handle_agent_request(
             if update_lastseen:
                 self.update_agent_lastseen_db(sessionID, db)
 
+            # Check if the agent has returned sysinfo yet, so that we don't
+            # send out a checkin before stage2 of registration is complete
+            if self.get_agent_from_name_or_session_id(sessionID, db).hostname:
+                # Call the hook to emit a checkin event
+                hooks.run_hooks(hooks.AFTER_AGENT_CALLBACK_HOOK, db, sessionID)
+
             # retrieve all agent taskings from the cache
             taskings = self.get_queued_agent_tasks_db(sessionID, db)
             temp_taskings = self.get_queued_agent_temporary_tasks(sessionID)

empire/server/common/credentials.py

@@ -3,6 +3,7 @@
 Credential handling functionality for Empire.
 
 """
+
 import logging
 import warnings
 

empire/server/common/encryption.py

@@ -18,6 +18,7 @@
     DiffieHellman()             -   Mark Loiseau's DiffieHellman implementation, see ./data/licenses/ for license info
 
 """
+
 import base64
 import hashlib
 import hmac

empire/server/common/helpers.py

@@ -35,6 +35,7 @@
     KThread() - a subclass of threading.Thread, with a kill() method
     slackMessage() - send notifications to the Slack API
 """
+
 import base64
 import binascii
 import ipaddress

empire/server/common/malleable/transformation.py

@@ -116,9 +116,11 @@ def _serialize(self):
             + list(
                 {
                     "type": self.type,
-                    "arg": self.arg
-                    if self.type != Transform.MASK
-                    else MalleableUtil.to_hex(self.arg[0]),
+                    "arg": (
+                        self.arg
+                        if self.type != Transform.MASK
+                        else MalleableUtil.to_hex(self.arg[0])
+                    ),
                 }.items()
             )
         )

empire/server/common/plugins.py

@@ -1,4 +1,5 @@
 """ Utilities and helpers and etc. for plugins """
+
 import logging
 
 log = logging.getLogger(__name__)

empire/server/common/templating.py

@@ -1,7 +1,6 @@
 """ Provides helper methods for templating.
 This is useful for generating stagers """
 
-
 import jinja2