Quickstart
Run Commands
Empire uses a server/client architecture, which is handled automatically by the startup script. The server will continue running from the terminal that it is launched from and Starkiller will be started on the configured port.
Server
# Start Server
./ps-empire server
# Help
./ps-empire server -hTesting
Run the test suite via pytest. All arguments after test are passed directly to pytest.
# Run all tests
./ps-empire test
# Verbose with slow tests
./ps-empire test -v --runslow
# Single test file
./ps-empire test empire/test/test_agent_api.py -vUpdate
Refresh the Empire source, Starkiller, Empire-Compiler, and plugin registries in one step:
What it does, in order:
Source. If the install is a git checkout at a release tag (the documented install path uses
setup/checkout-latest-tag.sh), runsgit fetch --tagsand re-runscheckout-latest-tag.shto move HEAD to the latest tag for the appropriate channel (sponsors,kali, or mainline, detected fromorigin). If HEAD is on a development branch, the source step is skipped — manage upstream pulls yourself with git. Skipped entirely if the install is not a git checkout.Config. Overwrites
~/.config/empire/config.yamlwith the shipped template from the repo. Local customizations belong in~/.config/empire/config.user.yaml, which the server merges on top of the base config at startup (see User Config Overrides).Database. Checks for pending Alembic migrations and, if any are found, prompts to back up the database and apply them (
-yauto-confirms). See Migrations.Starkiller / plugin registries. Fast-forwards the existing clone of the configured ref. If the configured ref changed (e.g. 7.0 moves the plugin registry from
mainto7.x), prompts before downloading the new ref into the cache.Empire-Compiler. Re-downloads the binary if the configured release tag changed.
Step 2 overwrites the base config every run. Any edits made directly to ~/.config/empire/config.yaml will be lost — move overrides to config.user.yaml first.
Reset
The server can be reset by passing a --reset flag. This will delete the database and any files that were created at runtime. It is recommended to run a --reset after any upgrades.
Default credentials are set in the config.yaml and are:
Upgrading from pre-7.0? Empire 7.0 replaced bcrypt password hashing with PBKDF2-HMAC-SHA256 for FIPS compliance, so pre-7.0 password hashes are unusable. 7.0 requires a fresh database — see Upgrading to 7.0.
The Basics
Listeners 101
The first thing you need to do is set up a local listener. The listeners tab will display any active listeners, and active listeners can be disabled or modified from this tab. The create button in the top right will prompt you to select a listener type to build. The dropdown supports fuzzy search and tab completion. Each listener will have its own set of required and optional parameters.
HTTP is the most commonly used listener and supports both HTTP and HTTPS. For HTTPS, CertPath is the directory holding the certificate/key pair — Empire appends the empire-chain.pem and empire-priv.key filenames itself, so it is a folder, not a single .pem file. Empire generates a self-signed pair on first server start in the data directory's cert/ folder (~/.local/share/empire/cert/ by default; see data & config locations); point CertPath there to use it.
Set any optional parameters such as WorkingHours, KillDate, DefaultDelay, and DefaultJitter for the listener, as well as whatever name you want it to be referred to as. You can then hit submit to start the listener. If the name is already taken, a nameX variant will be used, and Empire will alert you if the port is already in use.
Stagers 101
Empire implements various stagers in a modular format in ./empire/server/stagers/ . These include dlls, macros, one-liners, and more. To use a stager, select the stagers tab and click create, and you'll be taken to the individual stager's menu. The stagers tab will display any previously created stagers, along with key information about it them such as the agent language it will use and what listener it is keyed to.
For UserAgent and proxy options, the default uses the system defaults, none clears that option from being used in the stager, and anything else is assumed to be a custom setting.
Agents 101
When an agent checks in, you will get a notification both on the server and in Starkiller.
On the server you will see the staging exchange and the check-in:
In Starkiller the same check-in arrives as a notification:
Once you have received a check-in notification, you can go to the agents tab and see all checked-in agents. If an agent turns red, it means the agent has failed to check in and the server cannot currently communicate with it. These are referred to as stale agents
From here you can click on any agent where you will be presented with a number of tabs including the interact tab for running modules, tasks, and view. The view tab will provide you with information that has been collected about the host, along with other key information like delay and jitter intervals.
For each registered agent, a downloads/AGENT_NAME/ folder is created. An agent.log is created here with timestamped commands/results for agent communication. Downloads/module outputs are broken out into relevant folders here as well.
When you're finished with an agent, you can either kill it from its interaction page or from the Agents tab.
Modules 101
To see available modules, use the modules tab under agents. This will provide a list of all available modules within Empire. These modules can be searched using the search bar on the left or filtered by a number of criteria.
Clicking on a module will take you to the module overview, where you can read more information and configure settings. You can also select agents to task the module to and can deploy a module to multiple agents simultaneously.
Last updated
Was this helpful?