kitlabs/kit-soar-bundle
A Laravel/PHP bundle from KitLabs for SOAR workflows, packaging integrations and automation utilities to help orchestrate security operations. Review its docs for supported connectors, configuration, and usage before installing.
Before touching the package, confirm what you're actually installing. Despite the "Laravel-native" pitch in the description, kitlabs/kit-soar-bundle is a Symfony bundle that wraps the soar Go binary. There is no Laravel service provider, no facade, no config/kit_soar.php, and no Artisan commands in the repo. If you're on Laravel, the fastest correct move is to read the bundle source as a reference implementation and skip the dependency entirely.
Where to look first:
composer.json — confirm the Symfony version constraints and PHP floor. Older Symfony bundles frequently cap below PHP 8.2/8.3.soar — this is the entire value of the repo (~100–200 lines). Copy the shape, not the code.XiaoMi/soar README — this is the real product. Everything the bundle advertises lives here.Prerequisites (do these before anything else):
soar binary itself. It is not installable via Composer; it's a Go build artifact. Pin the version and checksum in your Dockerfile or CI image.EXPLAIN connections with the credentials soar will use. Soar targets the MySQL family; MariaDB/Postgres are out of scope.soar -report-type=explain -query "SELECT * FROM users WHERE id = 1". If that output doesn't make sense to you, no wrapper will help.First use case. For most teams the correct first step is not integrating the bundle. Run soar by hand against a slice of your real slow-query log:
soar -report-type=slow-log -query /path/to/slow.log > report.txt
soar -report-type=explain -query "SELECT ..." -online-dsn "user:pass@host:3306/db"
Read the index suggestions and fingerprinting output. If those recommendations don't change a decision (an added index, a blocked merge, a fixed slow query) within a day, stop — the wrapper adds nothing on top of a CLI you already won't use.
Pattern 1 — CI-only (recommended for Laravel teams). Skip the package. Install soar in the CI image and add a pipeline stage that lints changed SQL or runs -report-type=explain against a scratch schema. Zero production footprint, no Composer dependency, credentials confined to ephemeral CI DB, ~80% of the value with ~5% of the risk.
# .github/workflows/sql-review.yml (sketch)
- run: curl -L -o soar https://github.com/XiaoMi/soar/releases/download/vX.Y.Z/soar.linux-amd64 && chmod +x soar && echo "$SHA256 soar" | sha256sum -c -
- run: ./soar -report-type=explain -online-dsn "$CI_DSN" -query "$(cat changed.sql)"
Run report-only for 2–4 weeks. Gate only on new/changed queries — full-repo linting on day one generates noise that trains the team to ignore it.
Pattern 2 — Artisan command (if developers want it locally). Wrap soar directly with Symfony\Component\Process\Process or Laravel's Process facade. Do not pull the Symfony bundle in; it drags DI plumbing you'll have to unwind.
// app/Console/Commands/SoarAdvise.php (sketch)
class SoarAdvise extends Command
{
protected $signature = 'db:soar-advise {query}';
protected $description = 'Run soar index advice on a SQL query';
public function handle(): int
{
$this->ensureEnvironmentAllowsRun(); // local/testing only
$process = new Process([
config('services.soar.binary', '/usr/local/bin/soar'),
'-report-type=explain',
'-query', $this->argument('query'),
], timeout: 20, env: [
'SOAR_ONLINE_DSN' => config('services.soar.dsn'), // env, never argv
]);
$process->run();
if (! $process->isSuccessful()) {
$this->error($process->getErrorOutput());
return self::FAILURE;
}
$this->line($process->getOutput());
return self::SUCCESS;
}
}
Bind config via config/services.php (binary path, DSN, timeout). Gate the command behind local/testing in a middleware or a guard clause.
Pattern 3 — Port the bundle (Symfony only). If you genuinely are on Symfony, register the bundle via config/bundles.php and publish its config. Treat it as scaffolding for a spike. Budget one to two days to read the source, pin the binary, and confirm behavior before anyone treats it as a dependency.
Pattern 4 — Fork the bundle. Only justified if its specific output shaping is important to you and you can't reproduce it in Pattern 2. Assume you own every future fix: pinned binary, checksum, smoke test asserting the binary runs and emits parseable output, documented upgrade path.
Integration tips across all patterns:
ps and process listings).soar.soar's stdout as human-oriented text, not a stable schema. Snapshot-test your parser against a pinned binary version.The Laravel/Symfony mismatch is the headline. Copy-pasting install instructions that assume Symfony (AppKernel, bundles.php, DI compiler passes) into a Laravel app will fail at boot. The description's "auto-discovered service provider" and "Artisan commands" claims don't reflect the actual repo — verify everything against the source before you promise a feature to anyone.
The binary is not a Composer dependency. soar must be present in every environment where the feature runs. Missing binary or wrong architecture (darwin-arm64 on Apple Silicon vs linux-amd64 in CI) is a hard failure. Validate at boot (a command -v soar in a ServiceProvider::boot() or a CI preflight step), not at first use.
Version drift breaks parsing silently. A binary upgrade can change output formatting and your parser will happily return empty advice. Mitigate with a pinned digest, a smoke test that asserts known-good output on a known query, and treating upgrades as reviewed changes.
MySQL-family only. Soar targets MySQL. If you're on MariaDB, Postgres, or a SQL Server mix, this capability is out of scope — don't scope it into the roadmap.
EXPLAIN connectivity is a hidden prerequisite. Online mode needs a live DB connection with working credentials. Common failure modes: network policy from the CI runner, credentials scoped to replica but not primary, and MySQL 8 syntax that the pinned binary doesn't fully understand. The last one is the most dangerous because it produces false negatives — a clean pass on unsupported SQL — not an error.
Do not put this in the request path. Each invocation is a Go cold start (~100–1000ms) plus a MySQL connection. Under concurrency that becomes process fan-out and DB connection-pool pressure. Any proposal to run soar in middleware or a controller is the failure mode to push back on. Queue it or move it to CI.
Credentials and process arguments. Never pass -online-dsn "user:pass@host/db" as argv; use env vars and redact in logs. For a Laravel app this is a new adjacent surface to your DB and should go through security review.
Upstream health is the real risk. XiaoMi/soar has been dormant for years. Confirm current commit activity and MySQL 8.x coverage before committing. The wrapper (1 star, 0 dependents) has no maintainer capacity; assume you own every fix. Document the two or three people who understand the tool — bus factor is real on both the package and your internal usage.
Recommendation for a Laravel team. Treat the package as a capability probe, not a dependency. Run a two-week spike that shells out to soar directly (Pattern 1 then Pattern 2). Success criterion: does the output change a real decision — a blocked merge, an added index, a fixed slow query — within that window? If yes, own a ~200-line Artisan wrapper with pinned binary versions, env-passed DSNs, explicit timeouts, and a documented exit (drop the CI stage) if the signal goes stale. If no, walk away — and consider PHP-native parsers (greenlion/php-sql-parser, phpmyadmin/sql-parser) for the linting subset, which removes the binary dependency entirely.
How can I help you explore Laravel packages today?