Installation

The easiest way to get started is to use Docker or the Azure button above (which requires an Azure account). It is highly recommended that you run Counterfit inside a Docker container instance or install Counterfit in a virtual environment.

Azure

To run Counterfit from your browser

1. Click the button below to initiate small resource deployment to your Azure account.

   

2. In the configuration blade, specify your subscription and resource group.

3. In your Azure Shell, type the following, replacing RESOURCE_GROUP with the name of the resource group selected in the previous step.

   az container exec --resource-group RESOURCE_GROUP –name counterfit –exec-command '/bin/bash'
   

4. Within the container, launch Counterfit.

   python counterfit
   

Docker -- Terminal Only

1. Install Docker Desktop
2. Execute Counterfit as follows

   docker run -it azuretrustworthyml/counterfit:latest python counterfit.py
   

Docker -- JupyterLab

1. Install Docker Desktop
2. Pull and execute Counterfit-Jupyterlab as follows

   docker pull azuretrustworthyml/counterfit-jupyterlab:latest
   docker run -p8888:8888 azuretrustworthyml/counterfit-jupyterlab:latest
   

3. Navigate your browser to the URL specified that includes a token, e.g., http://127.0.0.1:8888/lab?token=<token>

Anaconda Python Environment

1. Install Anaconda Python and git.

2. Clone the repository.

   git clone https://github.com/Azure/counterfit.git
   

3. Open an Anaconda shell and create a virtual environment and install dependencies.

   conda update -c conda-forge --all -y
   conda create --yes -n counterfit python=3.8.0
   conda activate counterfit
   git clone -b main https://github.com/Azure/counterfit.git
   cd counterfit
   pip install .[dev]
   

4. Launch Counterfit

   counterfit
   

Python Virtual Environment

1. Clone the repository.

    git clone https://github.com/Azure/counterfit.git
    cd counterfit
   

2. Create a virtual environment and install dependencies.

    python3 -m venv counterfit-venv
    # Activate virtual environment (Linux)
    source counterfit-venv/bin/activate
    # Activate virtual environment (Windows)
    counterfit-venv\scripts\activate.bat
    pip install .[dev]
   

3. Launch Counterfit CLI

   counterfit

Non-Azure Environments

1. Use your container service of choice.
2. Pull the Docker image

Docker pull azuretrustworthyml/counterfit:1.1

3. Execute the image

docker run -it azuretrustworthyml/counterfit:1.1 counterfit

Note: There is a known bug installing TextAttack on Windows. A workaround is to download paramcf manually, change the file extension to .zip, extract it, and drop the extracted paramcf folder into c:\users\user.cache. See Frameworks for more information on the caching mechanism.