Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 78 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,47 @@ version tags are published, it selects the latest release version.
Prebuilt archives for Linux, macOS, and Windows will be available with tagged
[GitHub releases](https://github.com/boostsecurityio/emBarrass/releases).

### Shell completion

Tab completion covers emBarrass subcommands, flags, and `--chain` values
(`all`, `emsign`, and `sectigo`), including flags on `embarass batch`.

For **Zsh**, add this to `~/.zshrc` after your existing completion setup:

```zsh
autoload -Uz compinit
compinit
source <(embarass completion zsh)
```

If your shell framework already runs `compinit`, only add the `source` line.
Run the same lines in your current shell to enable completion immediately.

For **Bash**, install your OS's `bash-completion` package, then add this to
`~/.bashrc` after loading it:

```bash
source <(embarass completion bash)
```

For **Fish**, generate its automatically loaded completion file:

```fish
mkdir -p ~/.config/fish/completions
embarass completion fish > ~/.config/fish/completions/embarass.fish
```

For **PowerShell**, add this to your `$PROFILE`:

```powershell
embarass completion powershell | Out-String | Invoke-Expression
```

Reopen your shell, then try `embarass ba<Tab>`, `embarass --he<Tab>`, or
`embarass batch --chain <Tab>`. For a local build, load the script with
`./embarass completion zsh` (or your shell's name). Completion covers
emBarrass's own interface; it does not complete a wrapped tool's flags.

## Why this exists

Eight eMudhra P-384 intermediate CA private scalars were generated with values below 256. Six were TLS issuing keys and two were code-signing keys. Each key appeared in both a directly issued eMudhra certificate and a Sectigo cross-certificate.
Expand Down Expand Up @@ -106,7 +147,10 @@ examples. `embarass --help` includes the complete list above.
### Batch testing installed tools

`embarass batch` discovers `curl`, `git`, `gh`, `wget`, `npm`, `go`,
`pip`/`pip3`, `docker`, and `crane` in `PATH`. Docker contributes two probes:
`pip`/`pip3`, `docker`, `crane`, `aws`, `gcloud`, `cargo`, `uv`, `kubectl`,
Python (`python3`/`python`), Node.js (`node`/`nodejs`), RubyGems (`gem`),
`dotnet`, `pnpm`, HTTPie (`http`/`https`), `helm`, and `composer` in `PATH`.
Docker contributes two probes:
`docker` tests the host-side CLI with a manifest request, while `docker/git`
runs Git inside a historical, pre-mitigation, digest-pinned image to test its
embedded CA bundle. This does not test or make any claim about Chainguard's
Expand All @@ -125,8 +169,8 @@ selected for each installed tool and marks missing tools as skipped. The prompt
defaults to **no**; only `y` starts the sweep.

The probes run sequentially against public endpoints. Child output is
discarded, the intercepted application request is not forwarded upstream, npm
and Go caches are placed inside one temporary workspace, and that workspace is
discarded, the intercepted application request is not forwarded upstream, tool
caches and temporary configurations are placed inside one workspace, which is
removed afterward. Package installation, repository checkout, and writes to
the current directory are deliberately avoided.

Expand All @@ -143,6 +187,37 @@ isolated configuration directory. It cannot read or transmit the user's GitHub
credentials. The `crane` probe similarly uses an isolated Docker configuration
directory while fetching only a public image manifest.

The additional probes work without logging in or installing packages:

| Tool | Read-only probe | Isolation |
|---|---|---|
| AWS CLI (`aws`) | Unsigned `s3api head-bucket` for the public `noaa-goes16` bucket | Temporary default profile, no shared credential file, metadata lookup disabled |
| `gcloud` | `components list` fetches Google's public component catalog | Temporary configuration, credential loading and usage reporting disabled |
| `cargo` | `search serde --limit 1 --registry crates-io` | Temporary Cargo home and sparse registry access; rustup toolchain downloads disabled |
| `uv` | Fetch a public Requests requirements file with `pip compile` | Temporary cache, no configuration discovery, builds, Python downloads, or keyring access |
| `kubectl` | `get --raw=/version` against `https://example.com` | Empty kubeconfig and temporary cache; no cluster credentials or credential plugins |
| Python | Standard-library `urllib.request` against `https://example.com/` | Isolated Python mode; no third-party packages required |
| Node.js | A TLS `HEAD` request to `https://example.com/` | Embedded probe script uses the local proxy and Node's default certificate verification |
| RubyGems (`gem`) | Remote search for `rake` on RubyGems.org | No gemrc configuration; temporary gem home, search path, and cache |
| .NET (`dotnet`) | Search for `Newtonsoft.Json` on NuGet.org | Temporary CLI home and NuGet configuration/cache; telemetry and first-run development certificate generation disabled |
| `pnpm` | Query `is-number` metadata on npmjs.org | Isolated npm configuration and caches; existing Corepack executable cache preserved and bootstrap downloads disabled |
| HTTPie | `HEAD https://example.com/` | Temporary configuration; stdin and netrc credentials ignored |
| `helm` | Show the public `hello-world` chart metadata | Temporary configuration, cache, and plugin paths; empty kubeconfig |
| `composer` | Show public `symfony/console` metadata | Temporary project/configuration; plugins, scripts, cache, and interaction disabled |

The Python probe requires Python 3, and the .NET probe requires SDK 8.0.2xx or
later. Node's probe explicitly opens the local proxy tunnel so it also works on
versions that do not automatically honor proxy environment variables. These
runtime probes test the built-in TLS client; third-party HTTP libraries may
use different trust stores. Older or incomplete tool installations can return
an inconclusive result.

The `kubectl` endpoint deliberately exercises HTTPS without requiring a real
cluster. Only the TLS decision matters; the request is never forwarded.
AWS uses [`--no-sign-request`](https://docs.aws.amazon.com/cli/latest/reference/s3api/head-bucket.html)
and gcloud uses [`auth/disable_credentials`](https://docs.cloud.google.com/sdk/gcloud/reference/topic/configurations)
to reach TLS without loading cloud credentials.

The same credential protection applies automatically to the exact individual
probe `gh api meta [--silent]`: emBarrass substitutes a throwaway token for the
child process so `gh` reaches TLS even when the user is logged out. Other `gh`
Expand Down
1 change: 1 addition & 0 deletions cmd/embarass/batch.go
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ immutable, digest-pinned image.`,
command.Flags().BoolVarP(&app.batchYes, "yes", "y", false, "run the displayed probes without prompting")
command.Flags().DurationVar(&app.timeout, "timeout", defaultTimeout, "maximum runtime per tool and trust path; 0 disables the deadline")
command.Flags().StringVar(&app.chain, "chain", chainAll, chainFlagUsage)
registerChainCompletion(command)
command.Flags().BoolVar(&app.headless, "headless", false, "emit compact log lines without the terminal UI")
command.Flags().BoolVarP(&app.verbose, "verbose", "v", false, "enable debug logging")
return command
Expand Down
31 changes: 31 additions & 0 deletions cmd/embarass/completion.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
// Copyright (C) 2026 boostsecurity.io
// SPDX-License-Identifier: GPL-3.0-or-later

package main

import (
"strings"

"github.com/spf13/cobra"
)

func registerChainCompletion(command *cobra.Command) {
err := command.RegisterFlagCompletionFunc("chain", func(_ *cobra.Command, _ []string, prefix string) ([]string, cobra.ShellCompDirective) {
choices := make([]string, 0, 1+len(allChains))
choices = append(choices, chainAll)
for _, chain := range allChains {
choices = append(choices, string(chain))
}
var matches []string
for _, choice := range choices {
if strings.HasPrefix(choice, prefix) {
matches = append(matches, choice)
}
}
return matches, cobra.ShellCompDirectiveNoFileComp
})
if err != nil {
// A missing or duplicate registration is a command construction bug.
panic(err)
}
}
82 changes: 82 additions & 0 deletions cmd/embarass/completion_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
// Copyright (C) 2026 boostsecurity.io
// SPDX-License-Identifier: GPL-3.0-or-later

package main

import (
"bytes"
"context"
"strings"
"testing"

"github.com/boostsecurityio/emBarrass/pkg/runner"
"github.com/stretchr/testify/require"
)

func TestShellCompletion(t *testing.T) {
t.Parallel()

for _, test := range []struct {
name string
args []string
want []string
}{
{"batch command", []string{"ba"}, []string{"batch", ":4"}},
{"version command", []string{"ver"}, []string{"version", ":4"}},
{"completion command", []string{"comp"}, []string{"completion", ":4"}},
{"root flag", []string{"--he"}, []string{"--headless", "--help", ":4"}},
{"batch flag", []string{"batch", "--y"}, []string{"--yes", ":4"}},
{"root chains", []string{"--chain", ""}, []string{"all", "emsign", "sectigo", ":4"}},
{"batch chains", []string{"batch", "--chain", ""}, []string{"all", "emsign", "sectigo", ":4"}},
{"chain prefix", []string{"--chain", "em"}, []string{"emsign", ":4"}},
{"chain equals", []string{"batch", "--chain=se"}, []string{"sectigo", ":4"}},
{"unknown chain", []string{"--chain", "unknown"}, []string{":4"}},
{"after flag", []string{"--headless", "--ch"}, []string{"--chain", ":4"}},
{"child flags", []string{"curl", "--he"}, []string{":0"}},
{"child chain flag", []string{"curl", "--chain", ""}, []string{":0"}},
{"separator", []string{"--", "curl", "--he"}, []string{":0"}},
} {
t.Run(test.name, func(t *testing.T) {
t.Parallel()
output := executeCompletion(t, "embarass", append([]string{"__completeNoDesc"}, test.args...))
require.ElementsMatch(t, test.want, strings.Split(strings.TrimSpace(output), "\n"))
})
}
}

func TestCompletionScriptsUseStableCommandName(t *testing.T) {
t.Parallel()

for _, shell := range []string{"bash", "zsh", "fish", "powershell"} {
for _, invocation := range []string{"embarass", "./embarass", "/tmp/local build/embarass", `.\embarass.exe`} {
t.Run(shell+"/"+invocation, func(t *testing.T) {
t.Parallel()
output := executeCompletion(t, invocation, []string{"completion", shell})
require.Contains(t, output, "embarass")
require.Contains(t, output, "__complete")
if invocation != "embarass" {
require.NotContains(t, output, invocation)
}
})
}
}
}

func executeCompletion(t *testing.T, invocation string, args []string) string {
t.Helper()
app := &application{
invocation: invocation,
run: func(context.Context, runner.Options) (runner.Result, error) {
t.Fatal("completion must not run a TLS probe")
return runner.Result{}, nil
},
}
command := newRootCommand(app)
var output, stderr bytes.Buffer
command.SetOut(&output)
command.SetErr(&stderr)
command.SetArgs(args)
require.NoError(t, command.Execute(), stderr.String())
require.Equal(t, exitProtected, app.exitCode)
return output.String()
}
6 changes: 5 additions & 1 deletion cmd/embarass/root.go
Original file line number Diff line number Diff line change
Expand Up @@ -73,8 +73,11 @@ func Execute() int {
func newRootCommand(app *application) *cobra.Command {
invocation := app.displayedInvocation()
command := &cobra.Command{
Use: invocation + " [flags] -- command [args...]",
Use: "embarass [flags] -- command [args...]",
Short: "Wrap any command and test its TLS trust",
// Keep shell function names independent of argv[0], while preserving
// the copyable invocation in help (for example, ./embarass).
Annotations: map[string]string{cobra.CommandDisplayNameAnnotation: invocation},
Long: tagline + `

emBarrass routes one command through an authenticated local HTTPS interceptor.
Expand Down Expand Up @@ -114,6 +117,7 @@ forward intercepted traffic, or change the host trust store.`,
command.Flags().SetInterspersed(false)
command.Flags().DurationVar(&app.timeout, "timeout", defaultTimeout, "maximum runtime per trust path; 0 disables the deadline")
command.Flags().StringVar(&app.chain, "chain", chainAll, chainFlagUsage)
registerChainCompletion(command)
command.Flags().BoolVar(&app.headless, "headless", false, "emit compact log lines without the terminal UI")
command.Flags().BoolVarP(&app.verbose, "verbose", "v", false, "enable debug logging")
command.AddCommand(newBatchCommand(app), newVersionCommand())
Expand Down
Loading
Loading