# Quickstart

## Run Commands

Empire uses a server/client architecture which requires running each in separate terminals.

### Server

```bash
# Start Server
./ps-empire server

# Help
./ps-empire server -h
```

### Client

```bash
# Start Client
./ps-empire client

# Help
./ps-empire client -h
```

Both the client and 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.\


```
./ps-empire client --reset
./ps-empire server --reset
```

## Main Menu

Once you hit the main menu, you'll see the number of active agents, listeners, and loaded modules.

![](<../.gitbook/assets/image (8).png>)

The **help** command should work for all menus, and almost everything that can be tab-completable is (menu commands, agent names, local file paths where relevant, etc.).

You can ctrl+C to rage quit at any point. Starting Empire back up should preserve existing communicating agents, and any existing listeners will be restarted (as their config is stored in the SQLite backend database).

## Listeners 101

The first thing you need to do is set up a local listener. The **listeners** command will jump you to the listener management menu. Any active listeners will be displayed, and this information can be redisplayed at any time with the **list** command. The `uselistener` command will allow you to select the type of listener. Hitting TAB after this command will show all available listener types. The info command will display the currently set listener options.

![](<../.gitbook/assets/image (7).png>)

The info command will display the currently configured listener options. Set your host/port by doing something like set Host [http://192.168.52.142:8081](http://192.168.52.142:8081). This is tab-completable, and you can also use domain names here). The port will automatically be pulled out, and the backend will detect if you're doing a HTTP or HTTPS listener. For HTTPS listeners, you must first set the CertPath to be a local .pem file. The provided **./setup/cert.sh** script will generate a self-signed cert and place it in **./data/empire.pem**.

Set optional and WorkingHours, KillDate, DefaultDelay, and DefaultJitter for the listener, as well as whatever name you want it to be referred to as. You can then type **execute** 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

The staging process is described \[\[here|Staging]].

Empire implements various stagers in a modular format in **./lib/stagers/\*** . These include dlls, macros, one-liners, and more. To use a stager, from the main, listeners, or agents menu, use usestager \[tab] to tab-complete the set of available stagers, and you'll be taken to the individual stager's menu. The UI here functions similarly to the post module menu, i.e set/unset/info and generate to generate the particular output code.

![](<../.gitbook/assets/image (5).png>)

For UserAgent and proxy options, 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 (note, this last bit isn't properly implemented for proxy settings yet). From the Listeners menu, you can run the **launcher \[listener ID/name]** alias to generate the stage0 launcher for a particular listener (this is the stagers/launcher module in the background). This command can be run from a command prompt on any machine to kick off the staging process.

## Agents 101

You should see a status message when an agent checks in (i.e. \[+] Initial agent CGUBKC1R3YLHZM4V from 192.168.52.168 now active). Jump to the Agents menu with **agents**. Basic information on active agents should be displayed. Various commands can be executed on specific agent IDs or **all** from the agent menu, i.e. **kill all**. To interact with an agent, use **interact AGENT\_NAME**. Agent names should be tab-completable for all commands.

![](<../.gitbook/assets/image (6).png>)

In an Agent menu, **info** will display more detailed agent information, and help will display all agent commands. If a typed command isn't resolved, Empire will try to interpret it as a shell command (like ps). You can **cd** directories, **upload/download** files, and **rename NEW\_NAME**.

For each registered agent, a **./downloads/AGENT\_NAME/** folder is created (this folder is renamed with an agent rename). 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, use **exit** from the Agent menu or **kill NAME/all** from the Agents menu. You'll get a red notification when the agent exits, and the agent will be removed from the interactive list after.

## Modules 101

To see available modules, type **usemodule \[tab]**. To search module names/descriptions, use **searchmodule privesc** and matching module names/descriptions will be output.

To use a module, for example share finder from PowerView, type **usemodule situational\_awareness/network/sharefinder** and press enter. info will display all current module options.

![](../.gitbook/assets/image.png)

To set an option, like the domain for sharefinder, use **set Domain testlab.local**. The Agent argument is always required, and should be auto-filled from jumping to a module from an agent menu. You can also **set Agent \[tab]** to tab-complete an agent name. **execute** will task the agent to execute the module, and **back** will return you to the agent's main menu. Results will be displayed as they come back.

## Scripts

In addition to formalized modules, you are able to simply import and use a .ps1 script in your remote empire agent. Use the **scriptimport ./path/** command to import the script. The script will be imported and any functions accessible to the script will now be tab completable using the "scriptcmd" command in the agent. This works well for very large scripts with lots of functions that you do not want to break into a module.
