README

Scan your Laravel working tree for security issues before you push.

tutamen snapshots your local code, uploads it to Tutamen, and the server runs the same sandboxed scanners as a repository scan — secrets (gitleaks), dependency CVEs (composer audit), SAST (opengrep) and Laravel-aware AST rules. Results are returned to you with a meaningful exit code, so a pre-push git hook can block risky pushes. Nothing is scanned locally and no rule binaries are distributed — there is nothing to keep up to date but this package.

Requirements

• PHP 8.3+
• git and tar on your PATH
• A Tutamen account and an API token (Settings → API tokens)

Install

composer global require tutamen/cli

Make sure Composer's global bin directory is on your PATH (typically ~/.composer/vendor/bin or ~/.config/composer/vendor/bin). Then:

tutamen --version

Authenticate

Create an org-scoped token in the dashboard under Settings → API tokens (it is shown once), then:

tutamen auth --server=https://app.tutamen.io
# paste your token when prompted (input is hidden)

tutamen auth:status   # show the server and a masked token
tutamen auth:logout   # forget stored credentials

Credentials are stored in ~/.config/tutamen/config.json with 0600 permissions. This file is personal — never commit it. The committed .tutamen.json (below) holds hook settings only and must never contain a token; the CLI refuses to read it if it looks like it does.

Scan

From anywhere inside your repository:

tutamen scan                      # tracked + locally-modified files
tutamen scan --include-untracked  # also untracked, non-ignored files
tutamen scan --fail-on=high       # only fail on high/critical findings
tutamen scan --json               # machine-readable envelope

The snapshot includes your tracked files at their current working-tree content (so a secret you just edited but have not committed is still caught) and excludes anything git ignores — vendor/, node_modules/ and .git/ are never uploaded. Results are ephemeral: they are returned to you and never merged into your repository's dashboard findings.

Exit codes

The threshold is set with --fail-on=critical|high|medium|low|any (default any) or in .tutamen.json. An explicit flag always wins.

Pre-push hooks

tutamen hooks:install                                   # native .git/hooks/pre-push
tutamen hooks:install --husky                           # .husky/pre-push instead
tutamen hooks:install --branches='^(main|release/.*)$' --fail-on=high
tutamen hooks:uninstall                                 # remove the tutamen hook

--branches and --fail-on are written into a committed .tutamen.json so your whole team shares them:

{
  "hooks": {
    "branches": "^(main|release/.*)$",
    "failOn": "high"
  }
}

The hook only scans branches matching branches (omit it to scan every branch). It is installed as a clearly marked block, so an existing hook is appended to — never clobbered — and hooks:uninstall removes only Tutamen's part. A blocked push shows the findings and reminds you that git push --no-verify bypasses the hook once.

Continuous integration

The exit codes make tutamen scan usable in any CI pipeline without a dedicated integration:

tutamen scan --server="$TUTAMEN_SERVER" --token="$TUTAMEN_TOKEN" --fail-on=high

License

MIT © Arctic Works. See LICENSE.