fleet/cmd/fleetctl/fleetctl.go
Scott Gress d716265641
Add "generate-gitops" command (#28555)
For #27476

# Checklist for submitter

- [X] Changes file added for user-visible changes in `changes/`,
`orbit/changes/` or `ee/fleetd-chrome/changes`.
See [Changes
files](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Committing-Changes.md#changes-files)
for more information.
- [X] Input data is properly validated, `SELECT *` is avoided, SQL
injection is prevented (using placeholders for values in statements)

# Details

This PR adds a new command `generate-gitops` to the `fleetctl` tool. The
purpose of this command is to output GitOps-ready files that can then be
used with `fleetctl-gitops`.

The general usage of the command is:

```
fleectl generate-gitops --dir /path/to/dir/to/add/files/to
```

By default, the outputted files will not contain sensitive data, but
will instead add comments where the data needs to be replaced by a user.
In cases where sensitive data is redacted, the tool outputs warnings to
the user indicating which keys need to be updated.

The tool uses existing APIs to gather data for use in generating
configuration files. In some cases new API client methods needed to be
added to support the tool:

* ListConfigurationProfiles
* GetProfileContents
* GetScriptContents
* GetSoftwareTitleByID

Additionally, the response for the /api/latest/fleet/software/batch
endpoint was updated slightly to return `HashSHA256` for the software
installers. This allows policies that automatically install software to
refer to that software by hash.

Other options that we may or may not choose to document at this time:

* `--insecure`: outputs sensitive data in plaintext instead of leaving
comments
* `--print`: prints the output to stdout instead of writing files
* `--key`: outputs the value at a keypath to stdout, e.g. `--key
agent_options.config`
* `--team`: only generates config for the specified team name
* `--force`: overwrites files in the given directory (defaults to false,
which errors if the dir is not empty)

# Technical notes

The command is implemented using a `GenerateGitopsCommand` type which
holds some state (like a list of software and scripts encountered) as
well as a Fleet client instance (which may be a mock instance for tests)
and the CLI context (containing things like flags and output writers).
The actual "action" of the CLI command calls the `Run()` method of the
`GenerateGitopsCommand` var, which delegates most of the work to other
methods like `generateOrgSettings()`, `generateControls()`, etc.

Wherever possible, the subroutines use reflection to translate Go struct
fields into JSON property names. This guarantees that the correct keys
are written to config files, and protects against the unlikely event of
keys changing.

When sensitive data is encountered, the subroutines call `AddComment()`
to get a new token to add to the config files. These tokens are replaced
with comments like `# TODO - Add your enrollment secrets here` in the
final output.

# Known issues / TODOs:

* The `macos_setup` configuration is not output by this tool yet. More
planning is required for this. In the meantime, if the tool detects that
`macos_setup` is configured on the server, it outputs a key with an
invalid value and prints a warning to the user that they'll need to
configure it themselves.
* `yara_rules` are not output yet. The tool adds a warning that if you
have Yara rules (which you can only upload via GitOps right now) that
you'll have to migrate them manually. Supporting this will require a new
API that we'll have to discuss the authz for, so punting on it for now.
* Fleet maintained apps are not supported by GitOps yet (coming in
https://github.com/fleetdm/fleet/issues/24469). In the meantime, this
tool will output a `fleet_maintained_apps` key and trigger a warning,
and GitOps will fail if that key is present.

---------

Co-authored-by: Lucas Manuel Rodriguez <lucas@fleetdm.com>
Co-authored-by: Noah Talerman <47070608+noahtalerman@users.noreply.github.com>
2025-05-06 15:25:44 -05:00

116 lines
2.8 KiB
Go

package main
import (
"errors"
"fmt"
"io"
"io/fs"
"math/rand"
"os"
"path"
"runtime"
"time"
eefleetctl "github.com/fleetdm/fleet/v4/ee/fleetctl"
"github.com/fleetdm/fleet/v4/server/version"
"github.com/urfave/cli/v2"
)
const (
defaultFileMode = 0o600
)
func init() {
rand.Seed(time.Now().UnixNano())
}
func main() {
app := createApp(os.Stdin, os.Stdout, os.Stderr, exitErrHandler)
if err := app.Run(os.Args); err != nil {
fmt.Fprintf(os.Stdout, "Error: %+v\n", err)
os.Exit(1)
}
}
// exitErrHandler implements cli.ExitErrHandlerFunc. If there is an error, prints it to stderr and exits with status 1.
func exitErrHandler(c *cli.Context, err error) {
if err == nil {
return
}
fmt.Fprintf(c.App.ErrWriter, "Error: %+v\n", err)
if errors.Is(err, fs.ErrPermission) {
switch runtime.GOOS {
case "darwin", "linux":
fmt.Fprintf(c.App.ErrWriter, "\nThis error can usually be resolved by fixing the permissions on the %s directory, or re-running this command with sudo.\n", path.Dir(c.String("config")))
case "windows":
fmt.Fprintf(c.App.ErrWriter, "\nThis error can usually be resolved by fixing the permissions on the %s directory, or re-running this command with 'Run as administrator'.\n", path.Dir(c.String("config")))
}
}
cli.OsExiter(1)
}
func createApp(
reader io.Reader,
stdout io.Writer,
stderr io.Writer,
exitErrHandler cli.ExitErrHandlerFunc,
) *cli.App {
app := cli.NewApp()
app.Name = "fleetctl"
app.Usage = "CLI for operating Fleet"
app.Version = version.Version().Version
app.ExitErrHandler = exitErrHandler
cli.VersionPrinter = func(c *cli.Context) {
version.PrintFull()
}
app.Reader = reader
app.Writer = stdout
app.ErrWriter = stderr
app.Commands = []*cli.Command{
apiCommand(),
applyCommand(),
deleteCommand(),
setupCommand(),
loginCommand(),
logoutCommand(),
queryCommand(),
getCommand(),
{
Name: "config",
Usage: "Modify Fleet server connection settings",
Subcommands: []*cli.Command{
configSetCommand(),
configGetCommand(),
},
},
convertCommand(),
goqueryCommand(),
userCommand(),
debugCommand(),
previewCommand(),
eefleetctl.UpdatesCommand(),
hostsCommand(),
vulnerabilityDataStreamCommand(),
packageCommand(),
generateCommand(),
{
// It's become common for folks to unintentionally install fleetctl when they actually
// need the Fleet server. This is hopefully a more helpful error message.
Name: "prepare",
Usage: "This is not the binary you're looking for. Please use the fleet server binary for prepare commands.",
Action: func(c *cli.Context) error {
return errors.New("This is not the binary you're looking for. Please use the fleet server binary for prepare commands.")
},
},
triggerCommand(),
mdmCommand(),
upgradePacksCommand(),
runScriptCommand(),
gitopsCommand(),
generateGitopsCommand(),
}
return app
}