Setup

awspx can be installed on either Linux or macOS and comes packaged with an INSTALL script that will automatically pull and setup a Neo4j Docker container that hosts awspx's ingestor and web interface. The accompanying CLI, installed alongside this container, is a copy of this script, renamed to /usr/local/bin/awspx — which simply forwards commands to this container using docker exec.

This container mounts /opt/awspx/data (or ${HOME}/bin/awspx/data on macOS) and binds ports TCP/80, TCP/7373, TCP/7474, and TCP/7687 on localhost by default. Setting up remote access will require additional steps.

Before proceeding, make sure Docker is installed.

Installation

The installation process should hopefully be as simple as executing the following two steps; however, if it doesn't work out of the box, there are a couple things you can check.

1. Clone this repo:

   git clone https://github.com/FSecureLABS/awspx.git

2. Run the install script

   cd awspx && ./INSTALL 

Next, ingest an environment to explore.

Configuring remote access (optional)

By default, awspx will only be accessible on your local network interface. You will need to perform additional actions to allow remote access.

Setting up an SSH tunnel

The preferred method to do this is to setup an SSH tunnel. This will allow you to tunnel communications between your client and the local interface of the remote system hosting awspx: making it appear as though awspx was installed locally. To do this, set up SSH and issue the below command on your client (replacing 10.0.0.50 with the IP address of your remote system):

ssh 10.0.0.50 \
    -L 80:127.0.0.1:80 \
    -L 7373:127.0.0.1:7373 \
    -L 7474:127.0.0.1:7474 \
    -L 7687:127.0.0.1:7687    

The web interface will then be available on http://localhost from your client.

Modifying port bindings

Alternatively, if you are hosting awspx on a trusted system, that has been designated a static IP address, you can do away with the overhead of setting up an SSH tunnel my modifying INSTALL. To allow remote access, find and alter the values associated with the docker run command before running INSTALL.

    if docker run -itd \
        --name awspx \
        --hostname=awspx \
        --env NEO4J_AUTH=neo4j/password \
        -p 127.0.0.1:80:80 \
        -p 127.0.0.1:7687:7687 \
        -p 127.0.0.1:7373:7373 \
        -p 127.0.0.1:7474:7474 \
        -v ${MOUNT}/data:/opt/awspx/data \
        --restart=always beatro0t/awspx:latest >/dev/null; then

For further information, see https://docs.docker.com/engine/reference/commandline/run/

Troubleshooting

• The awspx Docker container binds web and Neo4j ports TCP/80, TCP/7373, TCP/7474, and TCP/7687 on your local network adapter. If anything else is already using any of one of these ports (e.g. another Neo4j instance) the installation will likely fail. You will need to terminate any offending processes before retrying.

• Kernel security modules such as SELinux or AppArmour may prevent the Docker container from doing everything it needs to. Try temporarily disabling these services before debugging further.

• Docker makes changes to iptables. You may need to adjust your iptables configuration to get awspx to work.

Related Activities

For details pertaining to updating, reinstalling, or removing awspx, see the relevant section below:

Updating

Once awspx has been installed, it can be updated by simply running:

awspx update

Reinstalling

You can reinstall awspx at any time by rerunning INSTALL.

If an existing container is detected, you will be prompted for confirmation. Continuing with this process will delete all profile and database information, ingested ZIP files will not be touched.

Uninstalling

To completely remove awspx and all of its data, execute the following commands:

1. Stop and remove the awspx container

    docker stop awspx && docker rm awspx
   

2. Remove ALL mounted data (including ZIPs)

   • Linux

     rm -rf /opt/awspx

   • macOS

     rm -rf ${HOME}/bin/awspx

3. Remove the awspx binary

   rm /usr/local/bin/awspx