policy

Definition

The policy command has 10 subcommands:

  • generate-secret
  • list-users
  • rbac-attach
  • rbac-detach
  • rbac-get
  • rbac-status
  • validation-add
  • validation-remove
  • validation-get
  • validation-list

These commands allow the user to manage role-based access control policy and runtime validation for Fugue.

Note: Runtime validations (and validation-* commands) are only allowed on the paid version of Fugue.

Usage

fugue [global options] policy [options] [command] [command arguments]

Subcommands

generate-secret
Generate a new secret for a specific user.
list-users
Display a list of all users.
rbac-attach
Attach a policy to the Conductor.
rbac-detach
Remove the policy from the Conductor.
rbac-get
Download the policy on the Conductor to the current working directory.
rbac-status
Query the status of the RBAC policy.
validation-add
Add a new validation module to the Conductor.
validation-remove
Remove a validation module from the Conductor.
validation-get
Retrieve a validation module from the Conductor.
validation-list
List validation modules installed on the Conductor.

Options

Global options are detailed here.

-h | --help
Show help text. The help flag is available throughout the CLI in both an application-level and command-level context. It enables a user to view help text for any command within the Fugue CLI.

Policy Subcommands

generate-secret

Definition

Generate a new user secret, or access token, for the provided <user_id>. The <user_id> must exist on a policy that has been set on the Conductor. If a user secret already exists for the provided <user_id>, this command will expire the existing secret and create a new one.

Note: The field user_id corresponds to user in the credentials file.

Usage

fugue policy generate-secret [options] <user_id>

Options

--kms-key str
The KMS key used to encrypt the secret when saving to S3. You can use a KMS key ID, alias, or ARN. Default key alias: alias/fugue/rbac/secrets.
-y | --yes
Suppress confirmation dialogs.
--json
Emit output as JSON.
-h | --help
Show help text.

Arguments

<user_id>
The user to generate the secret for. Required.

list-users

Definition

Display the list of users from the policy that has been set on the Conductor.

Usage

fugue policy list-users [options]

Options

--json
Emit output as JSON.
-h | --help
Show help text.

rbac-attach

Definition

Attach the provided <policy_file> to the Conductor. A policy is a Ludwig composition that defines RBAC rules.

Note: Fugue run will accept an RBAC policy composition or even a mixture of RBAC and standard library types, but it will have no effect.

Usage

fugue policy rbac-attach [options] <policy_file>

Options

--json
Emit output as JSON.
-h | --help
Show help text.
--werror
Treats any lwc compiler warnings as an error and forces the CLI to exit.

Arguments

<policy_file>
The policy to be attached to the Conductor. Required.

rbac-detach

Definition

Detach the currently applied policy from the Conductor.

Usage

fugue policy rbac-detach [options]

Options

-y | --yes
Suppress confirmation dialogs.
--json
Emit output as JSON.
-h | --help
Show help text.

rbac-get

Definition

Download the policy that has been set on the Conductor to the current working directory, or optionally, to <destination>. The downloaded file contains the uncompiled content of the Ludwig policy in a gzipped tarball (.tar.gz).

Usage

fugue policy rbac-get [options] <destination>

Options

--stdout
Display retrieved policy via standard output.
-h | --help
Show help text.

Arguments

<destination>
The file to which the policy should be downloaded.

rbac-status

Definition

Query the status of the RBAC policy. Status is either Attached or Detached.

Usage

fugue policy rbac-status [options]

Options

--json
Emit output as JSON.
-h | --help
Show help text.

validation-add

Definition

Add a new validation module to the Conductor. Validation module names must be unique. After a validation module is added to the Conductor, only compositions that pass validation will be run.

At the time fugue policy validation-add is executed, if the Conductor is running any processes that would fail validation, the module will not be uploaded, and you’ll see an error message:

[ ERROR ] No validation module created: Failed to validate against existing compositions.

Usage

fugue policy validation-add [options] <validation_file>

Options

--json
Emit output as JSON.
--h | --help
Show help text.
--werror
Treats any lwc compiler warnings as an error and forces the CLI to exit.

Arguments

--name <name>
Name of the new validation module. Required.

validation-remove

Definition

Remove a validation module from the Conductor. When a validation module is removed from the Conductor, those validations are no longer enforced.

Usage

fugue policy validation-remove [options] <name>

Options

--json
Emit output as JSON.
-y | --yes
Suppress confirmation dialogs.
-h | --help
Show help text.

Arguments

<name>
Name of the validation module to be removed. Required.

validation-get

Definition

Retrieve a validation module (composition) from the Conductor. This downloads the module to the current working directory, or optionally, to <destination>. The downloaded file is a Ludwig snapshot, containing several other files:

MANIFEST
File containing the name of the validation module and the version of lwc.
env.json
JSON file containing environment variables and file mapping.
lib
A folder containing a copy of the Fugue Standard Library modules and any other libraries required for validations.
src
A folder containing the entry point for the validation.

Usage

fugue policy validation-get [options] <name>

Options

--json
Emit output as JSON.
--dest <destination>
Location to download the validation module to.
-h | --help
Show help text.

Arguments

<name>
Name of the validation module to be retrieved. Required.

validation-list

Definition

List validation modules installed on the Conductor. You may optionally use <prefix> to filter the list to modules that start with the provided argument.

Usage

fugue policy validation-list [options] <prefix>

Options

<prefix>
Show only modules matching this prefix.
--json
Emit output as JSON.
-h | --help
Show help text.

Examples

Attaching a policy to the Conductor

Attaching an RBAC policy to the Conductor allows the Conductor to enforce that policy’s rules. The Conductor will also create Fugue users listed in the policy.

To attach a policy to the Conductor, use the policy rbac-attach command:

fugue policy rbac-attach MyPolicy.lw

The CLI will compile the policy, upload it to S3, and ask the Conductor to apply the new policy. If successful, the CLI output will look like this:

Compiling Ludwig file MyPolicy.lw ...
[ OK ] Successfully compiled. No errors.

Uploading policy to S3 ...
[ OK ] Successfully uploaded.

Requesting the Conductor set new policy ...
[ DONE ] Policy uploaded and applied.

If there is a compilation error, the CLI will return an error message, and the policy will not be attached to the Conductor.

A newly-attached policy will overwrite the current policy on the Conductor, as only one policy may be set at a time.

Detaching a policy from the Conductor

Detaching a policy from the Conductor returns the Conductor to single-user mode, where root is the active user.

To remove a policy from the Conductor, use the policy rbac-detach command:

fugue policy rbac-detach

The CLI will prompt for confirmation, then produce output like this:

[ WARN ] Are you sure you want to detach the policy from the Conductor? [y/N]: y

Detaching policy from Conductor ...
[ DONE ] Policy detached.

Note: If users were declared in the policy that was removed, they still exist and their secrets are still set; they just cannot perform any actions. To permit the users to take action again, reattach the policy file with policy rbac-attach.

Downloading the policy from the Conductor

You can download the current policy attached to the Conductor. The downloaded file contains the uncompiled content of the Ludwig policy as a gzipped tarball (.tar.gz). The .tar.gz format is made using Ludwig snapshot semantics. To retrieve the file, use the policy rbac-get command:

fugue policy rbac-get

You’ll see output like this:

[ fugue policy ] Requesting policy document from the Conductor.

[ OK ] Retrieved policy document location

[ fugue policy ] Downloading the policy document.

[ DONE ] Policy document saved to ./policy20170605201915.tar.gz

If you want to save the policy to a specific location, specify the filename as an argument:

fugue policy rbac-get ~/mypolicy.tar.gz

Listing Fugue users

Fugue users are created when they’re declared in a policy document attached to the Conductor. To see a list of all Fugue users, use policy list-users:

fugue policy list-users

You’ll see a table like this:

Fugue User list for becki/xxxxxxxxxxxx - Mon Jan 23 2017 5:35pm

User Id    Enabled    Created      Updated
---------  ---------  -----------  -----------
becki      yes        Wed 1:18pm   Wed 3:00pm
root       yes        Dec 29 2016  Dec 29 2016
alice      no         2:53pm       2:53pm

[ HELP ] To enable a user, run "fugue policy generate-secret <user_id>".
User Id
The user’s ID in Fugue’s RBAC system
Enabled
Whether credentials have been generated for a user
Created
When the user was created
Updated
When the user was last updated

Generating a secret for a user

Generating a secret, or access token, for a user enables that user to operate Fugue, assuming both the user and rules pertaining to that user have been declared in the policy attached to the Conductor. You can also generate a secret for a user who already has one; the existing secret will expire and Fugue will create a new one.

To generate a user secret, use the policy generate-secret command:

fugue policy generate-secret alice

You’ll see output like this:

[ fugue policy ] Requesting the Conductor generate a secret for: alice ...

User Credential Details:

   User ID: alice
   User Secret: 7y4sK8ZwbpEXAMPLEEXAMPLEEAMPLEEXAMPLEEXAMPLE

[ DONE ] Secret successfully generated.

Root credentials are generated upon install, or upon upgrade if upgrading from a version of Fugue without the RBAC feature.

Warning

Do not lose your root credentials. They cannot be replaced with the policy generate-secret command. If you have lost your root credentials, see the reset-secret command or contact support@fugue.co.

Changing the KMS key for encrypting secrets

When the CLI generates a secret, it encrypts it and saves it to S3. By default, the KMS customer master key used for encryption is alias/fugue/rbac/secrets (which appears in the AWS Management Console as “fugue/rbac/secrets”).

If you want the generated secret to be encrypted with a different key, you can use the --kms-key option with fugue policy generate-secret. You can specify the key by its key ID, alias, or ARN. If the specified key does not exist, it will be created for you. If you provide an alias, be sure to prepend it with alias/. For example, if the AWS console lists a key named myAlias, then you must format it as alias/myAlias:

fugue policy generate-secret --kms-key alias/myAlias alice

Two other supported ways of changing the key:

conductor:
  ami: ami-5800e125
  region: us-east-1
  secretsKeyId: 96b8bb05-42e8-49e5-aae9-d69fbc57a940
  • Set the environment value FUGUE_CONDUCTOR_SECRETSKEYID to your KMS key ID, alias, or ARN. For example:
export FUGUE_CONDUCTOR_SECRETSKEYID=alias/myAlias

The order of precedence is the --kms-key argument, the FUGUE_CONDUCTOR_SECRETSKEYID environment value, and the secretsKeyId field in fugue.yaml.

Checking RBAC status

To determine whether an RBAC policy has been attached to the Conductor, execute the policy rbac-status command:

fugue policy rbac-status

If an RBAC policy has been attached, the output will say “Attached”:

[ fugue policy rbac-status ] Querying Conductor...

Status: Attached

If no RBAC policy is currently attached, the output will say “Detached”:

[ fugue policy rbac-status ] Querying Conductor...

Status: Detached

Adding a validation module to the Conductor

When you add a validation module to the Conductor, all future processes are tested against the validations. If a composition fails validation, it will not be run.

Validation module names must be unique. To add a validation module to the Conductor, use the policy validation-add command and give your new validation module a name with the required option --name:

fugue policy validation-add --name usWest2Only UsWest2OnlyValidation.lw

The Fugue CLI will compile the validation module, upload it to S3, and ask the Conductor to create the new validation module. You’ll see output like this:

[fugue validation] Compiling Ludwig File UsWest2OnlyValidation.lw
[ OK ] Successfully compiled. No errors.

Uploading validation module to S3 ...
[ OK ] Successfully uploaded.

Requesting the Conductor create new validation module ...
[ DONE ] Validation module 'usWest2Only' uploaded and added to the Conductor.

Removing a validation module from the Conductor

Removing a validation module from the Conductor means that those validations are no longer enforced.

To remove a validation module from the Conductor, use the policy validation-remove command with the name of the module. This should be the name you entered during policy validation-add, not the filename of the composition:

fugue policy validation-remove usWest2Only

The CLI will prompt for confirmation and, upon y, return output like the following:

[fugue validation] Deleting Validation Module: 'usWest2Only'

[ WARN ] Are you sure you want to delete this validation module: 'usWest2Only'? [y/N]: y

Requesting the Conductor to delete validation module: 'usWest2Only' ...
[ DONE ] The Conductor is deleting the validation module: 'usWest2Only'

Retrieving a validation module from the Conductor

You can download a validation module from the Conductor. The validation module is downloaded as a gzipped tarball (.tar.gz). The .tar.gz format is made using Ludwig snapshot semantics. To retrieve the file, use the policy validation-get command with the name of the module. This should be the name you entered during policy validation-add, not the filename of the composition:

fugue policy validation-get usWest2Only

You’ll see the following output:

[fugue validation] Downloading Validation Module usWest2Only

Retrieving validation metatdata from the Conductor...

Downloading the validation module to /Users/main-user/projects/usWest2Only.tar.gz
Successfully downloaded usWest2Only to /Users/main-user/projects/usWest2Only.tar.gz

By default, Fugue saves the file to your current working directory. If you want to save the policy to a specific location, specify the target directory as an argument with the --dest option:

fugue policy validation-get usWest2Only --dest ~/

Listing validation modules on the Conductor

To see a list of all validation modules currently enabled, use the policy validation-list command:

fugue policy validation-list

You’ll see a table:

Fugue Validation Modules for user/xxxxxxxxxxxx - Wed Jun 28 2017 4:36pm

Name         Created     File Name                 Sha256
-----------  ----------  ------------------------  --------
usWest2Only  Mon 4:00pm  UsWest2OnlyValidation.lw  7f7ab649
Name
The name of the validation module
Created
When the validation module was created
Filename
The original filename of the validation module
Sha256
The first 8 digits of the SHA-256 hash for the validation module

To view the full SHA for a validation module, use the --json option:

fugue policy validation-list --json
[
    {
        "created": 1498507220,
        "file_name": "UsWest2OnlyValidation.lw",
        "name": "usWest2Only",
        "sha256": "7f7ab649212af16f794d4a8a2e4aef3ee3b0933ecb454c6c3a0bfba86425e00f"
    }
]

Setting FUGUE_LWC_OPTIONS to Pass Ludwig Compiler Options to policy rbac-attach

You can pass lwc options to the Fugue CLI during policy rbac-attach by using the FUGUE_LWC_OPTIONS environment variable.

First, set the environment variable FUGUE_LWC_OPTIONS to yes or true:

export FUGUE_LWC_OPTIONS=yes

You can then pass any lwc option to rbac-attach, like so:

fugue policy rbac-attach <composition.lw> -- <LWC_OPTIONS>

Just make sure that the lwc option(s) are after the --. For example, the following command disables color output by passing the lwc option --no-color:

fugue policy rbac-attach MyPolicy.lw -- --no-color

For a full list of lwc options, see The Ludwig Compiler.

Overriding a Binding During rbac-attach

If you’ve exported the FUGUE_LWC_OPTIONS environment variable, you can override bindings marked with an @override annotation when you use rbac-attach on a policy composition.

The lwc option --set allows you to selectively override bindings marked with an @override annotation. If you’ve exported the FUGUE_LWC_OPTIONS environment variable, you can pass the --set option to fugue policy rbac-attach. After successful compilation, Fugue uploads the overridden policy to the Conductor.

fugue policy rbac-attach <composition.lw> -- --set: "<binding>: <value>"

Note: You can override more than one binding at a time. Just use the --set option for each binding.

For example, if your RBAC policy composition declares a NamedAccount called "fugue", you can override the account name by passing a new value at the command line when you attach the policy with fugue policy rbac-attach.

Say your policy composition looks like this:

composition

import Fugue.System.Policy as Policy

default: Policy.NamedAccount {accountName: account}

account: @override "fugue"

alice: Policy.User {userId: "alice"}

aliceRunInDefault: Policy.accountRules {
          principals: [alice],
          accounts: [default],
          actions: [Policy.AccountRunProcess]
}

The top-level binding account is set to "fugue", which is the default Fugue-managed AWS account. Because the binding has the @override annotation, you can override it with another value (e.g., "web") when you execute fugue policy rbac-attach. In that case, the aliceRunInDefault rule would apply to the "web" account instead of the "fugue" account.

Use the --set option to set account to "web":

fugue policy rbac-attach MyPolicy.lw -- --set "account: 'web'"

The Conductor will attach the policy with the overriding binding, allowing alice to run compositions in the "web" account instead of the default "fugue" account.

If you later retrieve the attached policy using fugue policy rbac-get, you’ll see the original MyPolicy.lw composition, but the overriding values will be listed in the env.json file:

{"dirs":{},"overrides":["account: 'web'"],"environment":{},"files":{}}

Note: Overriding bindings makes it simple to share and reuse code. However, it makes it difficult to tell if an applied policy or validation has changed from the original code, so use overrides judiciously in rbac-attach.

For more information on overrides, see Overriding a binding in a composition.

Best Practices for Authoring Runtime Validations

When authoring runtime validations, keep in mind:

Validations should not use @override bindings.

The use of @override is an anti-pattern for validations and can lead to unwanted side effects at runtime. Given the appropriate user permissions in Fugue, validations with @override bindings can be altered at runtime to allow behavior that violates the intention of the validation. Fugue disallows @override bindings in some, but not all, conditions. Avoid this issue entirely by writing runtime validations without the use of @override bindings.