bluearch-aws-core

bluearch-aws-core is the shared local runtime for the BlueArch AWS tools. It runs on loopback only, owns the local SQLite database, issues a local service token for product backends, and centralizes setup, AWS account context, collectors, scans, templates, notifications, and product storage APIs.

What This Repo Is Not

This repo is not a hosted auth service, analytics collector, commercial license service, or SaaS backend. It does not include BlueArch-hosted analytics, private release infrastructure, or internal deployment scripts.

How It Works With The Other Repos

• bluearch-aws-core must be installed and started first.
• bluearch-aws-ops, bluearch-aws-tags, and bluearch-aws-governance call core over http://127.0.0.1:8094.
• Product backends authenticate to core with the local service token stored under ~/.bluearch-core/runtime/api-token.
• Users keep using their own AWS auth: profiles, AWS SSO, assume-role, and multi-account role setup.

Install

Installing a fully qualified formula automatically adds the tap and trusts only that formula. A separate brew tap or brew trust command is not needed for a first-time install. See Homebrew's tap-trust documentation.

brew install bluearchio/tap/bluearch-aws-core
bluearch-aws-core start --daemon
bluearch-aws-core status

brew tap bluearchio/tap only downloads and registers the repository; it does not grant trust. Whole-tap trust is unnecessary.

Recovery for an existing tap

If an existing or partially completed installation refuses to load Core, trust only the Core formula and retry:

brew trust --formula bluearchio/tap/bluearch-aws-core
brew install bluearchio/tap/bluearch-aws-core

Linux:

curl -fsSL https://github.com/bluearchio/bluearch-aws-core/releases/latest/download/install-linux.sh | bash
export PATH="$HOME/.local/bin:$PATH"
bluearch-aws-core start --daemon

By default, the installer downloads the verified archive and SHA256SUMS directly from GitHub Releases. Set BLUEARCH_CORE_VERSION=vX.Y.Z for an immutable release. BLUEARCH_DIST_BASE_URL is supported only when explicitly set to an approved mirror base URL.

From source:

python -m venv .venv
. .venv/bin/activate
pip install -e .
bluearch-aws-core start --daemon

Local Development

. .venv/bin/activate
bluearch-aws-core start --host 127.0.0.1 --port 8094

Shortcut:

make setup
make dev

Run The Full Source Stack

For local development across all four public repos, clone them as siblings:

bluearch/
  bluearch-aws-core/
  bluearch-aws-ops/
  bluearch-aws-tags/
  bluearch-aws-governance/

Then create each repo's virtual environment once, and run the stack from core:

cd bluearch-aws-core
make dev-stack

This starts:

• Core: http://127.0.0.1:8094
• Ops: http://127.0.0.1:8095
• Tags: http://127.0.0.1:8096
• Governance: http://127.0.0.1:8097

Press Ctrl-C to stop the whole source stack.

For installed/Homebrew usage, use the packaged runtime manager to start Core and its managed product dashboards:

bluearch-aws-core start --daemon
bluearch-aws-core status

The loopback services use these ports:

• Core: http://127.0.0.1:8094
• Ops: http://127.0.0.1:8095
• Tags: http://127.0.0.1:8096
• Governance: http://127.0.0.1:8097

Useful endpoints:

• GET /api/v1/core/health
• GET /api/v1/setup/status
• GET /api/v1/templates
• GET /api/v1/account-context/current
• GET /api/v1/storage/{namespace}/{table}

Tests

python -m pytest
python -m compileall bluearch_core

Shortcut:

make test

Verifying Release Assets

Tagged releases are published from GitHub Actions after Linux and signed/notarized macOS artifacts are built. Release assets include platform archives, CycloneDX SBOMs, SHA256SUMS, and GitHub artifact attestations.

sha256sum -c SHA256SUMS
# macOS: shasum -a 256 -c SHA256SUMS
gh attestation verify bluearch-aws-core-linux-x86_64.tar.gz --repo bluearchio/bluearch-aws-core

For macOS, run the same checksum and attestation checks against bluearch-aws-core-macos-arm64.zip.

The publish job can safely resume an existing draft. If a runner stops after making the release public but before the job completes, an existing public release is accepted only when its tag target and every remote asset name and GitHub-provided SHA-256 digest exactly match the rebuilt local set. The workflow then continues without mutating it; any mismatch fails closed.

After publication, a separate Homebrew job checks out bluearchio/homebrew-tap at main, uses its scripts/update_formula.py to generate the immutable GitHub Release URL and exact macOS archive SHA-256, and opens or updates release/bluearch-aws-core-vX.Y.Z. It requests an automatic squash merge and waits up to two hours for the pull request to report MERGED; the product release workflow does not succeed merely because auto-merge was requested. A failed Homebrew job can be rerun without republishing the immutable release: use GitHub Actions' Re-run failed jobs action. Re-run all jobs is reserved for exact crash recovery and succeeds after publication only under the tag-target and asset/digest equality checks above. Before creating a release tag, the tap must have auto-merge enabled and main protected by its required CI checks. Configure HOMEBREW_TAP_TOKEN_2 as a fine-grained token for that tap with Contents and Pull requests read/write access.

Security And Privacy Defaults

• Core binds to loopback by default.
• Product backends authenticate with the local service token.
• AWS credentials stay in the user's local AWS config/credential chain.
• No BlueArch-hosted telemetry, hosted sign-in, license gates, or private release services are included.
• Report suspected vulnerabilities privately; see SECURITY.md.

Contributing

Keep core local-only and API-only. Do not add hosted analytics, product sign-in, commercial licensing, private bucket URLs, internal AWS account IDs, or private release/signing automation. If a product needs new shared behavior, add it as a versioned local API and update the product minimum_core_version.

See CONTRIBUTING.md for the full contribution workflow.