Skip to content

USER_GUIDE.md

Latest commit

 

History

History
312 lines (216 loc) · 6.62 KB

USER_GUIDE.md

File metadata and controls

312 lines (216 loc) · 6.62 KB

Atlas CLI User Guide

This guide provides detailed information on installing, configuring, and using the C2PA ML CLI tool.

Table of Contents

Installation

Prerequisites

  • Rust toolchain (1.58 or later)
  • OpenSSL development libraries

Standard Installation

# Clone repositories
git clone https://github.com/IntelLabs/atlas-cli

# Build CLI
cd atlas-cli && make

# Install (optional)
make install

Installation with TDX Attestation Support

The Atlas CLI currently supports Intel TDX 1.5 or later for Ubuntu systems on select Google Cloud Engine instances.

apt install protobuf-compiler
cargo build --features with-tdx
make install

Command Line Reference

The C2PA ML CLI provides the following main commands:

Model Commands

atlas-cli model [SUBCOMMAND]

Subcommands:

  • create - Create a new model manifest
  • list - List all model manifests
  • verify - Verify a model manifest
  • link-dataset - Link a dataset to a model

Dataset Commands

atlas-cli dataset [SUBCOMMAND]

Subcommands:

  • create - Create a new dataset manifest
  • list - List all dataset manifests
  • verify - Verify a dataset manifest

Manifest Commands

atlas-cli manifest [SUBCOMMAND]

Subcommands:

  • link - Link manifests together
  • show - Show manifest details
  • validate - Validate manifest cross-references
  • verify-link - Verify a specific link between two manifests
  • export - Export provenance graph information

Evaluation Commands

atlas-cli evaluation [SUBCOMMAND]

Subcommands:

  • create - Create a new evaluation result manifest
  • list - List all evaluation results
  • verify - Verify an evaluation result manifest

Software Commands

atlas-cli software [SUBCOMMAND]

Subcommands:

  • create - Create a new software component manifest
  • list - List all software component manifests
  • verify - Verify a software component manifest
  • link-model - Link software to a model
  • link-dataset - Link software to a dataset

Configuration Options

Keys for Signing

Generate signing keys:

make generate-keys

This creates:

  • private.pem - Private key for signing
  • public.pem - Public key for verification

Output Formats

The CLI supports two output formats:

  • json - Human-readable JSON (default)
  • cbor - Compact binary format

Specify the format using the --format flag:

atlas-cli model create --format=json ...
atlas-cli model create --format=cbor ...

Common Flags

Most commands support the following flags:

  • --print - Display the manifest without storing it
  • --key=<path> - Path to private key for signing
  • --storage-type=<type> - Storage backend type (database, filesystem)
  • --storage-url=<url> - URL or path for the storage backend

Storage Backends

Database Storage

Uses a custom HTTP API with MongoDB backend:

atlas-cli model create \
    --storage-type=database \
    --storage-url=http://localhost:8080 \
    ...

Filesystem Storage

Stores manifests in the local filesystem:

atlas-cli model create \
    --storage-type=filesystem \
    --storage-url=./storage \
    ...

Rekor Storage

Stores manifests in a Rekor transparency log:

export REKOR_URL=https://rekor.example.com
atlas-cli model create \
    --storage-type=rekor \
    ...

TDX Attestation

When built with the with-tdx feature, you can both create attested manifests and verify the guest integrity:

atlas-cli model create \
    --with-tdx \
    ...

Security Configuration

Key Generation and Management

Important: Cryptographic key generation and management are the responsibility of the end user. The security of your C2PA manifests depends entirely on the strength and proper management of your keys.

Generate signing keys using the provided Makefile:

make generate-keys

This creates:

private.pem - Private key for signing public.pem - Public key for verification

For custom key generation with specific requirements:

# Generate a strong 4096-bit RSA private key (recommended)
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:4096

# Extract the public key
openssl rsa -pubout -in private_key.pem -out public_key.pem

Key Requirements:

  • RSA keys: minimum 2048 bits (4096 bits recommended)
  • EC keys: use approved curves (P-256, P-384, or P-521)
  • Follow key management best practices, and use a well-known key management service (KMS) when possible.
  • Never commit private keys to version control
  • Rotate keys regularly according to your security policy

Hash Algorithms

The Atlas CLI supports multiple hash algorithms for signing manifests:

Uses SHA-384 by default (recommended)

atlas-cli model create --key=private.pem ...

# Use SHA-512 for maximum security
atlas-cli model create --key=private.pem --hash-algo=sha512 ...

Available algorithms:

  • sha384 - Default, recommended for security/performance balance
  • sha256 - For backward compatibility with existing systems
  • sha512 - Maximum security for sensitive applications

The --hash-alg flag is supported by all creation commands:

model create
dataset create
software create
evaluation create

Supported Formats

Models

  • ONNX (.onnx)
  • TensorFlow (.pb)
  • PyTorch (.pt, .pth)
  • Keras (.h5)

Datasets

  • Any directory structure
  • Common formats: CSV, JSON, NPY, etc.

Troubleshooting

Common Issues

Storage Connection Errors

If you encounter errors connecting to a storage backend:

  1. Verify the storage URL is correct
  2. Check if the storage service is running
  3. Verify network connectivity
  4. For database storage, check MongoDB is running

Signing Errors

If you encounter signing-related errors:

  1. Verify the private key path is correct
  2. Ensure the key is in PEM format
  3. Check file permissions on the key file

File Not Found Errors

If you encounter "file not found" errors when creating manifests:

  1. Verify the paths provided exist
  2. Use absolute paths to avoid working directory issues
  3. Check file permissions

Getting Help

For more detailed help on any command, you can use the --help flag:

atlas-cli --help
atlas-cli model --help
atlas-cli model create --help

Logging

To enable debug logging, set the RUST_LOG environment variable:

RUST_LOG=debug atlas-cli ...
⚡