Installation
We recommend the use of Kali, Poetry, or our Docker images to run Empire. Kali Linux users and Direct Sponsors will receive 30-day early access to new Empire and Starkiller features.
The following operating systems have been tested for Empire compatibility. We will be unable to provide support for other OSs at this time. Consider using our Prebuilt Docker containers which can run on any system.
- Kali Linux Rolling
- Ubuntu 20.04
- Debian 10
As of Empire 4.0, Python 3.8 is the minimum Python version required.
Kali
You can install the latest version of Empire by running the following:
1
sudo apt install powershell-empire
Copied!
Note: Newer versions of Kali require you to run
sudo before starting Empire.Github
Poetry is a dependency and virtual environment management tool. This is highly recommended if using the SocketIO notification feature introduced in 3.5.0. To install Poetry, please follow the installation guide in the documentation or run
sudo pip3 install poetry.To install and run:
1
git clone --recursive https://github.com/BC-SECURITY/Empire.git
2
cd Empire
3
sudo ./setup/install.sh
Copied!
Common Issues
Empire still has a few issues installing on Python 3.10. We recommend Python 3.8 or Python 3.9.
cffi fails to install via pip/poetry
Output
1
• Installing cffi (1.14.5): Failed
2
​
3
EnvCommandError
4
​
5
Command ['/root/.cache/pypoetry/virtualenvs/empire-bc-security-fork-QbDnA-QX-py3.10/bin/pip', 'install', '--no-deps', '/root/.cache/pypoetry/artifacts/d0/e3/60/58172107607ad40fd710df22e324a3ee48174e11f9e228acdaa720f6d1/cffi-1.14.5.tar.gz'] errored with the following return code 1, and output:
6
Processing /root/.cache/pypoetry/artifacts/d0/e3/60/58172107607ad40fd710df22e324a3ee48174e11f9e228acdaa720f6d1/cffi-1.14.5.tar.gz
7
Preparing metadata (setup.py): started
8
Preparing metadata (setup.py): finished with status 'done'
9
Building wheels for collected packages: cffi
10
Building wheel for cffi (setup.py): started
11
Building wheel for cffi (setup.py): finished with status 'error'
12
error: subprocess-exited-with-error
13
​
14
× python setup.py bdist_wheel did not run successfully.
15
│ exit code: 1
Copied!
This has been found to occur when using Python 3.10. Install Python 3.9, switch the poetry env to use it, then rerun the install.
Solution
1
# If 3.9 isn't available via apt, install it manually or via pyenv
2
apt install python3.9 python3.9-dev
3
poetry env use $(which python3.9)
4
setup/install.sh
Copied!
ModuleNotFoundError: No module named '_tkinter'
In Empire 4.7.0 this has been updated to be non-fatal. The error will show up as
[!] Failed to load tkinter. Please install tkinter to use the file prompts.
tkinter is a GUI tool built into python itself. It is possible for some distributions of Python to exclude it.tkinter is only used in the Empire client when using the
-p option to prompt a file selection on certain commands. For this reason, its not a critical dependency. In Empire 4.7, we made the inclusion of tkinter optional.Solution
There is no single way to fix this problem, because it depends on how your Python was installed. It has been reported that a variation of the following apt commands will add tkinter to the right place. The command you use would depend on how your python version was installed to begin with. For example, if your Python lives in
/usr/local/lib/python3.8/, you’d want to use apt install python3.8-tk.1
apt install python3-tk
2
apt install python3.8-tk
Copied!
Docker
If you want to run Empire using a pre-built docker container.
Note: For size savings on the image, it is not pre-built with the libraries needed for jar, dmg, and nim stagers. To add these to your image, run the
install.sh script in the container and answer y to the prompts.1
# Pull the latest image
2
docker pull bcsecurity/empire:latest
3
​
4
# Run the server with the rest api and socket ports open
5
docker run -it -p 1337:1337 -p 5000:5000 bcsecurity/empire:latest
6
​
7
# Run the client
8
docker run -it -p 1337:1337 -p 5000:5000 bcsecurity/empire:latest client
9
​
10
# To run the client against the already running server container
11
docker container ls
12
docker exec -it {container-id} ./ps-empire client
13
​
14
# with persistent storage
15
docker pull bcsecurity/empire:latest
16
docker create -v /empire --name data bcsecurity/empire:latest
17
docker run -it -p 1337:1337 -p 5000:5000 --volumes-from data bcsecurity/empire:latest
18
​
19
# if you prefer to be dropped into bash instead of directly into empire
20
docker run -it -p 1337:1337 -p 5000:5000 --volumes-from data --entrypoint /bin/bash bcsecurity/empire:latest
Copied!
Note: These are example basic commands to get started with docker. Depending on the use case of the individual, one may need to reference the Docker documentation.
- The last commit from master will be deployed to the
latesttag - The last commit from the dev branch will be deployed to the
devtag - All GitHub tagged releases will be deployed using their version numbers (v3.0.0, v3.1.0, etc)
Community-Supported Operating Systems
At this time, we are choosing to only support Kali, Debian 10, and Ubuntu 20.04 installations, however, we will accept pull requests that fix issues or provide installation scripts specific to other operating systems to this wiki.
Last modified 6d ago
Copy link