Edit

Freta Command-Line Interface (CLI) Reference

  • Article

alt text

freta is a command line utility supporting scriptable bulk upload to the Freta volatile memory image inspection service.

Note

Interactive device authentication, similar to that of az login, will be requested as needed. The resulting access token will be cached in the user's home directory. Please see Sign in with Azure CLI for more information.

freta

Usage

$ freta --help
Project Freta client
Usage: freta <COMMAND>
Commands:
  eula
  config     config
  login
  logout
  licenses
  info
  images
  artifacts
  help       Print this message or the help of the given subcommand(s)
Options:
  -h, --help     Print help information
  -V, --version  Print version information
$

freta eula

The eula subcommands interact with the service to retrieve, accept, and reject the current EULA required to use the service.`

Usage

$ freta eula --help
Usage: freta eula <COMMAND>
Commands:
  get
  accept
  reject
  help    Print this message or the help of the given subcommand(s)
Options:
  -h, --help  Print help information
$

freta eula get

Retrieve the current eula.

Usage

$ freta eula get --help
Usage: freta eula get
Options:
  -h, --help  Print help information
$

Example

$ freta eula get > eula.html
$

freta eula reject

Reject the current eula.

Usage

$ freta eula reject --help
Usage: freta eula reject
Options:
  -h, --help  Print help information
$

Example

$ freta eula reject 
$

freta eula accept

Accept the current eula

Usage

$ freta eula accept --help
Usage: freta eula accept
Options:
  -h, --help  Print help information
$

Example

$ freta eula accept 
$

freta config

Sets the configuration for the CLI

Usage

$ freta config --help
config
Usage: freta config [OPTIONS]
Options:
      --reset
          reset configuration to default
      --tenant-id <TENANT_ID>
      --client-id <CLIENT_ID>
      --client-secret <CLIENT_SECRET>
          note: use the empty string to remove an existing client secret
      --api-url <API_URL>
      --scope <SCOPE>
          note: use the empty string to remove an exisitng scope
  -h, --help
          Print help information
$

Example

$ freta config --reset

[2022-10-21T20:23:04Z INFO  freta] config saved: Config { api url: "https://freta.microsoft.com/", client id: "574efb07-14a8-4232-a200-89714a0324c9", tenant id: "common", scope: "api://a934fc14-92d7-4127-aecd-bddab35935da/.default" }
$

freta login

The login command authenticates to obtain an access token for the Freta service.

Note

If you already have a saved access token then no action will be required. The token is saved to ~/.config/freta/login.cache.

Usage

$ freta login --help
Usage: freta login
Options:
  -h, --help  Print help information
$

Example

$ freta login 
$

freta logout

The logout command deletes any saved Freta access token.

Usage

$ freta logout --help
Usage: freta logout
Options:
  -h, --help  Print help information
$

freta images list

List the available images

Usage

$ freta images list --help
list images
Usage: freta images list [OPTIONS]
Options:
      --image-id <IMAGE_ID>
          image id
      --owner-id <OWNER_ID>
          owner id
      --state <STATE>
          state
          Possible values:
          - waiting-for-upload: The service has not recieved notification the upload has completed
          - to-queue:           The image is ready to be queued
          - queued:             The image has been queued for analysis
          - running:            The image is currently being analyzed
          - finalizing:         The results of the analysis are being uploaded
          - completed:          The analysis has completed successfully
          - failed:             The analysis of the image failed
          - deleting:           The image and it's related artifacts are currently being deleted
      --include-samples
          include sample images
  -h, --help
          Print help information (use `-h` for a summary)
$

Example

$ freta images list --state completed | jq

{
  "images": [
    {
      "last_updated": "2022-09-28T17:49:01.8367376Z",
      "owner_id": "11111111-1111-1111-1111-111111111111_11111111-1111-1111-1111-111111111111",
      "image_id": "11111111-1111-1111-1111-111111111111",
      "state": "completed",
      "format": "lime",
      "tags": {
        "name": "Canonical:UbuntuServer:14.04.5-LTS:latest"
      },
      "shareable": false
    }
  ]
}
$

freta images get

Get the status of a single image

Usage

$ freta images get --help
get information about an image
Usage: freta images get <IMAGE_ID>
Arguments:
  <IMAGE_ID>
Options:
  -h, --help  Print help information
$

Example

$ freta images get 11111111-1111-1111-1111-111111111111
{
  "last_updated": "2022-10-21T20:33:59.491417Z",
  "owner_id": "11111111-1111-1111-1111-111111111111_11111111-1111-1111-1111-111111111111",
  "image_id": "11111111-1111-1111-1111-111111111111",
  "state": "completed",
  "format": "lime",
  "image_url": "https://REDACTED_URL",
  "artifacts_url": "https://REDACTED_URL",
  "tags": {
    "name": "Canonical:0001-com-ubuntu-server-hirsute:21_04:latest"
  },
  "shareable": false
}
$

freta images upload

Upload an image file for analysis

Usage

$ freta images upload --help
upload image
Usage: freta images upload [OPTIONS] <FILE>
Arguments:
  <FILE>
          image path
Options:
      --format <FORMAT>
          image format
          Possible values:
          - vmrs:
            Hyper-V 'checkpoint' files
          - raw:
            RAW memory dumps, such as created with `dd`
          - lime:
            Lime memory dumps, as created with AVML or LiME
          - core:
            Full-system Linux core dumps, such as memory dumps as created by VirtualBox or Dumpit for Linux
          - avmh:
            Internal memory snapshot feature
      --monitor
          monitor
      --show-result
          show result (after monitoring)
      --tags <KEY=VALUE>
          specify multiple times to include multiple key/value pairs
  -h, --help
          Print help information (use `-h` for a summary)
$

Example

$ freta images upload ./image.lime --tags 'name=test image'
[2022-10-21T20:34:26Z INFO  freta::client] uploading as image id: 11111111-1111-1111-1111-111111111111
$

freta images monitor

Monitor the analysis state of an image

Usage

$ freta images monitor --help
monitor the analysis of an image
Usage: freta images monitor <IMAGE_ID>
Arguments:
  <IMAGE_ID>
Options:
  -h, --help  Print help information
$

Example

$ freta images monitor 11111111-1111-1111-1111-111111111111
[2022-10-21T20:34:27Z INFO  freta::client] analysis completed
$

freta images create

Creates an image reference with a SAS URI authorizing an upload of an image.

Note

Use the resulting image.image_url with an azure blob store utility, such as azcopy, to upload the image. The image will be analyzed once the upload has completed.

Usage

$ freta images create --help
create
Usage: freta images create [OPTIONS] <FORMAT>
Arguments:
  <FORMAT>
          image format
          Possible values:
          - vmrs:
            Hyper-V 'checkpoint' files
          - raw:
            RAW memory dumps, such as created with `dd`
          - lime:
            Lime memory dumps, as created with AVML or LiME
          - core:
            Full-system Linux core dumps, such as memory dumps as created by VirtualBox or Dumpit for Linux
          - avmh:
            Internal memory snapshot feature
Options:
      --tags <KEY=VALUE>
          specify multiple times to include multiple key/value pairs
  -h, --help
          Print help information (use `-h` for a summary)
$

Example

$ freta images create lime --tags 'name=test image'
{
  "owner_id": "11111111-1111-1111-1111-111111111111_11111111-1111-1111-1111-111111111111",
  "image_id": "11111111-1111-1111-1111-111111111111",
  "state": "waiting_for_upload",
  "format": "lime",
  "image_url": "https://REDACTED_URL",
  "tags": {
    "name": "test image"
  },
  "shareable": false
}
$

freta images delete

Deletes an image

Usage

$ freta images delete --help
delete an image
Usage: freta images delete <IMAGE_ID>
Arguments:
  <IMAGE_ID>
Options:
  -h, --help  Print help information
$

freta images update

Update the metadata for an image: shareable and tags.

Usage

$ freta images update --help
Usage: freta images update [OPTIONS] <IMAGE_ID>
Arguments:
  <IMAGE_ID>  image id
Options:
      --shareable <SHAREABLE>  [possible values: true, false]
      --tags <KEY=VALUE>       specify multiple times to include multiple key/value pairs
  -h, --help                   Print help information
$

Example

$ freta images update 11111111-1111-1111-1111-111111111111 --shareable false
{
  "last_updated": "2022-10-21T20:33:59.491417Z",
  "owner_id": "11111111-1111-1111-1111-111111111111_11111111-1111-1111-1111-111111111111",
  "image_id": "11111111-1111-1111-1111-111111111111",
  "state": "completed",
  "format": "lime",
  "tags": {
    "name": "Canonical:0001-com-ubuntu-server-hirsute:21_04:latest"
  },
  "shareable": false
}
$

freta images reanalyze

Reanalyze the specified image

Usage

$ freta images reanalyze --help
reanalyze an image
Usage: freta images reanalyze <IMAGE_ID>
Arguments:
  <IMAGE_ID>
Options:
  -h, --help  Print help information
$

freta artifacts list

Lists the available artifacts from a successfully analyzed image

Usage

$ freta artifacts list --help
List artifacts for an image
Usage: freta artifacts list <IMAGE_ID>
Arguments:
  <IMAGE_ID>
Options:
  -h, --help  Print help information
$

freta artifacts get

Gets the contents of an artifact

Usage

$ freta artifacts get --help
Usage: freta artifacts get [OPTIONS] <IMAGE_ID> <PATH>
Arguments:
  <IMAGE_ID>
  <PATH>
Options:
      --output <OUTPUT>  output path
  -h, --help             Print help information
$

Example

$ freta artifacts get 11111111-1111-1111-1111-111111111111 report.json > report.json
$

freta licenses

Gets the licenses for third-party libraries used by Freta

Usage

$ freta licenses --help
Usage: freta licenses
Options:
  -h, --help  Print help information
$

Example

$ freta licenses >licenses.txt
$

freta info

Gets information on the service

Usage

$ freta info --help
Usage: freta info
Options:
  -h, --help  Print help information
$

Example

$ freta info 
{
  "api_version": "0.7.2",
  "models_version": "0.10.0",
  "current_eula": "993C44214D3E5D0EEB92679E41FC0C4D69DA9C37EF97988FB724C7B2493695BB",
  "formats": [
    "vmrs",
    "raw",
    "lime",
    "core",
    "avmh"
  ]
}
$