asterinas/tools/sctrace

Syscall Compatibility Tracer

Syscall Compatibility Tracer (sctrace) is a powerful system call compatibility verification tool that analyzes and validates system call against user-defined patterns. Written in SCML (System Call Matching Language), these patterns describe supported functionality of system calls. sctrace supports both real-time monitoring of running programs and post-analysis of existing trace logs, providing comprehensive insights into system call compatibility with intuitive pattern matching and visual feedback.

Features

• Pattern-based filtering: Define system call patterns using SCML syntax
• Dual mode operation:
  • Online mode: Real-time tracing of running programs
  • Offline mode: Analysis of existing strace log files
• Multi-threaded support: Automatic handling of multi-threaded program traces with syscall reconstruction. When tracing multi-threaded programs, strace may split system calls across multiple lines due to thread interleaving. sctrace automatically handles this reconstruction.
• Multiple SCML files support: Specify multiple .scml files as arguments to load all of them. Each file maintains its own scope for bitflags and struct definitions, preventing cross-file pollution.

How to build and install

Prerequisites

• strace version 5.15 or higher (for online mode)
  • Debian/Ubuntu: sudo apt install strace
  • Fedora/RHEL: sudo dnf install strace
• Rust toolchain

Build instructions

Make sure you have Rust installed, then build the project:

cargo build --release

The binary will be available at target/release/sctrace.

Installation instructions

To install the binary (for example, to /usr/local/bin), you can use:

sudo cp target/release/sctrace /usr/local/bin/

Or you can install from crates.io directly (Recommended):

cargo install sctrace

This will automatically download, build, and install the latest version of sctrace.

Usage

Basic Syntax

sctrace <SCML_FILE1> [SCML_FILE2 ...] [OPTIONS] -- [program] [args...]

Options

• --input <FILE>: Specify input file for offline mode
• --quiet: Enable quiet mode (only show unsupported calls)

Online Mode (Real-time tracing)

Trace a program in real-time:

sctrace pattern1.scml pattern2.scml -- ls -la
sctrace file_ops.scml network.scml --quiet -- ./my_program arg1 arg2

Offline Mode (Log file analysis)

Analyze an existing strace log file:

sctrace pattern1.scml pattern2.scml --input trace.log
sctrace file_ops.scml network.scml --input trace.log --quiet

Note: When generating strace logs for offline analysis, use -yy and -f flags:

strace -yy -f -o trace.log ls -la

• -yy: Print paths associated with file descriptor arguments
• -f: Trace child processes created by fork/vfork/clone

Examples

Example 1: Basic File Operations

Create file_ops.scml:

openat(dirfd, flags = O_RDONLY | O_WRONLY | O_RDWR, mode);
read(fd, buf, count = <INTEGER>);
write(fd, buf, count = <INTEGER>);
close(fd);

Run:

sctrace file_ops.scml -- cat /etc/passwd

Example 2: Network Operations

Create network.scml:

socket(domain = AF_INET | AF_INET6, type = SOCK_STREAM | SOCK_DGRAM, protocol);
connect(sockfd, addr, addrlen);
send(sockfd, buf, len, flags);
recv(sockfd, buf, len, flags);

Run:

sctrace network.scml -- curl http://example.com

Example 3: Using Asterinas Compatibility Patterns

Use the provided directory syscall-feature-coverage (work in progress) and test with various commands:

# Monitor file system operations
sctrace $(find . -name "*.scml") -- tree .

# Monitor process information calls
sctrace $(find . -name "*.scml") -- top

# Monitor network operations
sctrace $(find . -name "*.scml") -- ping 127.0.0.1

Example 4: Offline Analysis

# Generate trace log
strace -yy -f -o trace.log ls -la

# Analyze with sctrace
sctrace patterns.scml --input trace.log

Output

sctrace provides colored output to distinguish between supported and unsupported system calls:

• Supported calls: Normal output (or hidden in quiet mode)
• Unsupported calls: Highlighted in red with "unsupported" message

Example Output

openat(AT_FDCWD, "/etc/passwd", O_RDONLY) = 3
read(3, "root:x:0:0:root:/root:/bin/bash\n"..., 4096) = 1234
close(3) = 0
chmod("/tmp/test", 0755) (unsupported)

Dependencies

• clap: Command-line argument parsing
• regex: Regular expression support
• nom: Parser combinator library
• nix: Unix system interface for process management

Troubleshooting

Permission Issues

For online tracing, you may need elevated privileges:

sudo sctrace patterns.scml -- target_program