Skip to content

3. Usage

Jump to bottom
Min Hee Jo edited this page Mar 31, 2026 · 2 revisions

Quick-Start

Make sure to go over the Set Up before going through this page.

Prepare a Target Application Image

For example, to use minicokr/aut image, execute the following commands. You can skip this step, if you already have a target application Docker image followed by How to Test Your Own Application.

docker pull minicokr/aut:python
docker tag minicokr/aut:python aut_python:latest

Build a Test Docker Image for the Target Application

./scripts/build_test_image.sh

Build a Docker Image for Syscall Monitor

./scripts/build_monitor_image.sh

Start Testing

./scripts/run.sh

How to Test Your Own Application

To integrate your own containerized application into the workflow, you will need the following:

  • A testable execution command
    Ensure that your application produces observable outputs—such as logs, stdout, return codes, or memory dumps—so the effects of fault injection can be analyzed.

  • Input files or workload
    Provide representative input data that exercises your application during testing. By default, these should be placed in examples/input directory.

  • A unified launch script (for multi-process containers)
    If your container runs multiple processes (e.g., a client and a server), create a wrapper script that launches all required processes together.
    This script should be invoked using the Dockerfile's CMD or ENTRYPOINT directive.

Example

As an example, we show how to test a Nginx container.

Build a Docker image

Prepare a Dockerfile and an accompanying script if you are using ENTRYPOINT to execute your application logic for testing.

  • Dockerfile

    FROM nginx:stable

# set up
RUN apt-get update && apt-get install -y curl && apt-get clean

# entry script to copy files at runtime
COPY entrypoint.sh /entrypoint.sh
# change permission
RUN chmod +x /entrypoint.sh

# entrypoint
ENTRYPOINT ["/entrypoint.sh"]

# export port
EXPOSE 80

  • entrypoint.sh

    #!/bin/bash

# exit on error
set -e

# copy files
cp /app/input/nginx.html /usr/share/nginx/html/
cp /app/input/nginx.css /usr/share/nginx/html/
cp /app/input/nginx.png /usr/share/nginx/html/

# start nginx in the background
nginx &

# wait until server
sleep 1

# create output directory
mkdir -p /app/output

# fetch html file
curl -s "http://localhost/nginx.html" > "/app/output/output.txt"

You can build the image from where your Dockerfile is located at by:

docker build -t aut_nginx .

Make sure that the name should start with aut_.

Prepare the Workloads

Prepare the input workloads that will be used during the testing. For example:

  • examples/input/nginx.html

    <!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>SyscaLLM Demo Page</title>
  <link rel="stylesheet" href="nginx.css">
  <script>
    document.addEventListener('DOMContentLoaded', function () {
      document.getElementById('changeText').addEventListener('click', function () {
        document.getElementById('dynamic').innerText = 'Text changed via JavaScript!';
      });
    });
  </script>
</head>
<body>
  <h1>Welcome to SyscaLLM HTML Test</h1>
  <p id="dynamic">Original text here.</p>
  <button id="changeText">Change Text</button>

  <img src="nginx.png" alt="Logo" width="200">

  <form action="/submit" method="GET">
    <label for="fname">Name:</label>
    <input type="text" id="fname" name="fname">
    <input type="submit" value="Submit">
  </form>
</body>
</html>

  • examples/input/nginx.css

    body {
  font-family: Arial, sans-serif;
  background-color: #f0f0f0;
  color: #333;
  padding: 20px;
}
h1 {
  color: #0055aa;
}
button {
  padding: 10px;
  background-color: #007acc;
  color: white;
  border: none;
  cursor: pointer;
}

  • examples/input/nginx.png (some image)

Failure Analysis

In order to run the failure analysis, it is important to run an oracle.json (error-free) configuration that looks like the following, in order to enable silent data corruption.

{                                                                                                                         
  "syslog_monitor_config": {
    "id": "oracle",
    "strace_output": "/export/strace.output.{id}",
  }
}

Parameters

To list all the parameters of Failure Analysis function, run:

python3 ./src/failure_analysis/main.py -h

The parameters can be enabled individually to reduce the output and can be customized (e.g., allowed deviation in timing).

Usage Examples

The failure analysis is done with the following command:

python3 ./src/failure_analysis/main.py

Clone this wiki locally