runyourapp_apachephp8.md

In this demo you will

This tutorial explains how to setup a "cage" system for a Php 8-Apache based application

Index

• Prepare the HAM container
• Prepare the Application container
• Docker with proxy access On the same machine (e.g. local docker or Docker Desktop)
  • Write the compose
  • Modify the configuration
  • Run it!
• Docker with VPN access When the client accessing the app is on a physically different machine or in a VM
• What's next

Suppose you have an application named... testapp

Prepare the HAM container

Create a directory "master" and inside it

Prepare the configuration file, e.g. here you can find the default template external.json

Just setup a "Dockerfile" like the following for the HAM master

FROM ham.master:latest
# Copy the configuration
COPY .external.json /etc/app/ham/app/external.json

And create the image

docker build --rm -t testapp.master .

Prepare the application container

Create a directory, let's say "core" in the Dockerfile directory that will contain all the source file for the application (html,php etc)

Prepare the Dockerfile. Note that the client images already handles all basic initializations like DNS resolution, services initializations and certificates management.

FROM ham.apache.php8:latest

# Copy the source files
COPY core/ /htdocs/

And create the image

docker build --rm -t testapp.app .

Docker compose for proxy access

Docker compose

Prepare a docker compose to connect to the application

version: "2"
networks:
  testappnet:  # Setup a network for the system:
    driver: bridge
    ipam:
      config:
        - subnet: 172.25.7.0/24 # Define a subnet not already used
services:
  testapp.master:  # The HAM instance
    container_name: testapp.master # The DNS name of the instance
    privileged: true  # Needed for DNS hijacking
    environment:
      - ROOT_PWD=root
    cap_add:    # Needed for DNS hijacking
      - NET_ADMIN
      - DAC_READ_SEARCH
    dns:
      - 127.0.0.1
    image: testapp.master
    networks:
      - testappnet
    ports:
      - "5025:5025" # Ham debug port (optional)
      - "1080:1080" # Socks5 Proxy
      - "1081:1081" # Http/s Proxy
  testapp.app:  # The application
    container_name: www.testapp.com # The DNS name of the instance
    environment:
      - DNS_HIJACK_SERVER=testapp.master  # Use HAM as final DNS server
      - ROOT_PWD=root
    privileged: true # Needed for DNS hijacking
    cap_add: # Needed for DNS hijacking
      - NET_ADMIN
      - DAC_READ_SEARCH
    dns:  
      - 127.0.0.1
    image: testapp.app
    ports:
      - "8080:80" # To expose the application directly (optional)
    networks:
      - testappnet
    depends_on: # Wait for HAM to start
      - testapp.master

Adapt the configuration

To make the test "real" we will add a DNS and SSL entry to the configuration.

In the section DNS of the "external.json" we tells that HAM should intercept all requests to our application. They will then be forwarded to the real instance

[
  {
    "id": "dns",
    ...,
    "resolved": [
      ...,
      {
        "id": "123456",
        "dns": "www.testapp.com",
        "ip": "127.0.0.1"
      }
    ] ...

In the section SSL of the "external.json" we tells that HAM should build certificates for all testapp.com domains

  {
    "id": "ssl",
    ...,
    "domains": [
      {
        "id": "123456",
        "address": "*.testapp.com"
      }
    ] ...

Run and connect!

Run the compose

docker-compose up

Setup the proxy on Firefox or Chrome (For the latter install Switch Omega) or for the application you are using to stimulate the application, like Postman

Docker compose for vpn access

First complete the common steps:

• Prepare the HAM container
• Prepare the Application container
• Docker with proxy access On the same machine (e.g. local docker or Docker Desktop)
  • Write the compose
  • Modify the configuration

Install OpenVpn Connect Client on the client machine

Download the connection script and change the following line with the address of the machine running docker.

remote 127.0.0.1 3000 udp

Install the .ovpn file in your OpenVPN connect

Add the following instance to the docker compose. There is a custom image ready for that :)

  testapp.vpn:  # The application
    container_name: testapp.vpn # The DNS name of the instance
    environment:
      - DNS_HIJACK_SERVER=testapp.master  # Use HAM as final DNS server
      - ROOT_PWD=root
    privileged: true # Needed for DNS hijacking
    cap_add: # Needed for DNS hijacking
      - NET_ADMIN
      - DAC_READ_SEARCH
    dns:  
      - 127.0.0.1
    image: ham.openvpn/latest
    ports:
      - "3000:1194/udp" # To expose the OpenVpn port
    networks:
      - testappnet
    depends_on: # Wait for HAM to start
      - testapp.master

Start the composer wait for the whole system to start and connect the client machine :) Now you are completely inside the HAM cage!

What's next

Running the application you can now

• Intercept the DNS calls and add them as HAM resolved, with the local CA
• Add custom Javascript filters and APIs
• Record/Replay/Test the app automatically and without coding
• Rewrite any url to anything
• Intercept ALL http/s interactions dynamically