seristack

Seristack

1 つの YAML 設定で、CLI コマンド、HTTP エンドポイント、MCP ツールを利用できます。

Seristack は、DevOps、プラットフォーム、SRE、クラウドのチーム向けの軽量な自動化エンジンです。

YAML でシェルベースのワークフローを定義し、依存関係と変数を管理して、ローカルまたは HTTP 経由で実行できます。また、選択したスタックを AI エージェントや IDE 連携向けの MCP ツールとして公開できます。

GitHub リポジトリ

Seristack を選ぶ理由

運用ワークフローは、シェルスクリプト、運用手順書、CI ジョブ、文書化されていない手順として個別に管理されていることがよくあります。

Seristack は、そうしたワークフローを再利用可能な実行スタックに変換するための単一の設定レイヤーを提供します。スタックは次のように利用できます。

• CLI から実行
• HTTP エンドポイントとして公開
• MCP ツールとして公開
• スタックごとの認可で保護
• 構造化 JSON ログで監査
• 依存関係と共有結果を利用して構成

ドキュメント

• 設定リファレンス

機能

• 🚀 1 つの YAML 設定から複数のコマンドスタックを実行
• 🔁 スタックを順次または並行して実行
• 🔢 設定可能な回数でスタックの実行を繰り返す
• 🔗 スタック間の依存関係を定義
• 🧩 検証ルール付きの変数置換
• 📦 依存するスタック間で出力と結果を共有
• 🌐 スタックを HTTP エンドポイントとして公開
• 🔐 ID ヘッダーを使用したスタックごとの認可
• 📋 構造化 JSON 監査ログ
• 🧠 AI エージェントや IDE 連携向けの MCP サーバーとして実行
• 🛠 mvdan shell、Bash、sh、PowerShell に対応
• ⏱ スタックごとの実行タイムアウト
• 📁 作業ディレクトリを設定可能
• 🛡 スタック変数の許可ルールと拒否ルール

---

インストール

Homebrew — macOS および Linux

brew install TechXploreLabs/tap/seristack

Linux — インストーラー

curl -fsSL https://raw.githubusercontent.com/TechXploreLabs/seristack/main/install.sh | bash

Linux — リリースアーカイブ

1. Seristack のリリースにアクセスします。
2. 最新版をダウンロードします。

seristack_VERSION_linux_ARCH.tar.gz

例：

seristack_0.4.1_linux_amd64.tar.gz

3. アーカイブを展開します。

tar -xzf seristack_VERSION_linux_ARCH.tar.gz

4. バイナリをインストールします。

sudo mv seristack /usr/local/bin/
sudo chmod +x /usr/local/bin/seristack

5. 動作を確認します。

seristack --help

Windows — インストーラー

バイナリをインストールする権限を持つユーザーとして PowerShell を実行します。

irm https://raw.githubusercontent.com/TechXploreLabs/seristack/main/install.ps1 | iex

Windows — リリースアーカイブ

1. Seristack のリリースにアクセスします。
2. Windows リリースアーカイブをダウンロードします。

seristack_VERSION_windows_ARCH.tar.gz

例：

seristack_0.4.1_windows_amd64.tar.gz

3. .tar.gz に対応したツールでアーカイブを展開します。

4. seristack.exe を %PATH% に含まれるディレクトリに配置します。

5. 動作を確認します。

seristack --help

---

設定

Seristack では YAML を使って実行スタックを定義します。

すべての設定フィールドの詳しい説明については、設定リファレンスを参照してください。

例

stacks:

  - name: stack1
    workDir: ./
    description: Print welcome message
    method: GET
    urlPath: /show
    continueOnError: false
    count: 3
    timeouts: 1h
    executionMode: PARALLEL

    vars:
      - name: samplekey
        value: samplevalue
        required: true
        allowed_value:
          - samplevalue
          - devvalue

    cmds:
      - |
        export samplekey={{.Vars.samplekey}}
        echo $samplekey
        echo "count={{.Count.index}}"
        echo "Hey I'm Seristack!"

  - name: stack2
    workDir: ./
    continueOnError: false
    count: 3
    executionMode: SEQUENTIAL

    vars:
      - name: env
        value: Dev

    dependsOn:
      - stack1

    cmds:
      - |
        echo "{\"index\": {{.Count.index}}, \"step\": \"metadata\", \"status\": \"ok\"}"

      - |
        echo "{\"index\": {{.Count.index}}, \"step\": \"metrics\", \"value\": $((RANDOM % 100))}"

    output: |
      echo "--- Aggregation Summary ---"
      echo '{{.Self.result}}' | grep "^{" | jq -s '{
        total_records: length,
        environment: "{{.Vars.env}}",
        results: .
      }'

---

スタックの実行

すべてのスタックを実行

seristack trigger -c config.yaml

特定のスタックを実行

seristack trigger -c config.yaml -s stack1

HTTP サーバーを起動

seristack run -c config.yaml

MCP サーバーを起動

seristack mcp -t streamableHTTP

---

HTTP サーバー

HTTP サーバーは、設定済みのスタックを HTTP エンドポイントとして公開します。

例：

stacks:
  - name: system-health
    method: GET
    urlPath: /health
    cmds:
      - echo "system-health is good"

サーバーを起動します。

seristack run \
  --config config.yaml \
  --addr 127.0.0.1 \
  --port 8080

nginx や Caddy などのリバースプロキシを使うと、Seristack を localhost にバインドしたまま、サービスを外部に公開できます。

---

本番環境へのデプロイ

Seristack はシェルコマンドを実行するため、パブリックインターネットに直接公開しないでください。

推奨アーキテクチャは次のとおりです。

Client
  │
  ▼
nginx / Caddy
  │
  ├── TLS termination
  ├── Authentication
  ├── Rate limiting
  │
  ▼
Seristack
127.0.0.1
  │
  ├── Authorization
  └── Command execution

Seristack を localhost で起動します。

seristack run \
  --config config.yaml \
  --addr 127.0.0.1 \
  --port 8080

リモート MCP のデプロイにも、同じパターンを使用できます。

AI Agent / IDE
      │
      ▼
    HTTPS
      │
      ▼
nginx / oauth2-proxy
      │
      ├── TLS
      ├── OIDC authentication
      └── Identity headers
      │
      ▼
Seristack MCP
127.0.0.1:8081
      │
      ├── Stack authorization
      └── Command execution

認証は ID を認識するプロキシまたはゲートウェイで処理し、Seristack は個々のスタック単位で認可を行います。

---

スタックごとの認可

Seristack では、認証済みのリバースプロキシから転送された ID ヘッダーを使用して、個々のスタックへのアクセスを制限できます。

例：

stacks:

  - name: deploy-production
    method: POST
    urlPath: /deploy/production

    matchAccess: ANY

    access:
      - headerName: X-Auth-Request-Groups
        headerValue:
          - sre
          - platform

      - headerName: X-Auth-Request-Roles
        headerValue:
          - admin

    count: 1

    cmds:
      - ./deploy.sh

アクセスの照合

matchAccess は、複数のアクセスルールをどのように評価するかを制御します。

ANY

matchAccess: ANY

少なくとも 1 つのアクセスルールに一致すると、アクセスが許可されます。

これは OR ロジックです。

ALL

matchAccess: ALL

すべてのアクセスルールに一致した場合にのみ、アクセスが許可されます。

これは AND ロジックです。

アクセスルールがない場合

スタックに access ブロックが定義されていない場合、スタックレベルのアクセス制限はありません。

本番環境では、認証レイヤーでサービス自体も引き続き保護してください。

ID ヘッダー

実際のヘッダーは、認証プロバイダーとリバースプロキシによって異なります。

ID プロバイダー	一般的なプロキシ	ID 情報の例
Entra ID / Azure AD	oauth2-proxy	X-Auth-Request-Groups、X-Auth-Request-Roles、X-Auth-Request-Email
GCP	IAP	X-Goog-Authenticated-User-Email
AWS Cognito	ALB	X-Amzn-Oidc-Data
OCI IAM	nginx + oauth2-proxy	X-Auth-Request-Groups、X-Auth-Request-Email
Okta / Auth0	oauth2-proxy	プロキシで設定された ID ヘッダー

ヘッダーを設定し、認証済みのプロキシから送信された場合にのみ信頼する必要があります。

信頼できない外部クライアントが認可ヘッダーを直接送信できないようにしてください。

---

監査ログ

Seristack は、スタックの実行に関する構造化 JSON 監査ログを出力できます。

監査ログを有効にします：

seristack run \
  --config config.yaml \
  --audit-log /var/log/seristack/audit.log

監査エントリーには、次のような情報が含まれます：

• タイムスタンプ
• イベント
• スタック名
• HTTP パスとメソッド
• 取得可能な場合は送信元 IP
• ID ヘッダー
• 変数
• 成功／失敗
• 実行時間
• 出力
• エラー情報

例：

{
  "timestamp": "2026-09-19T10:00:00Z",
  "event": "stack_executed",
  "stack": "system-health",
  "success": true,
  "duration_ms": 42,
  "output": "system-health is good"
}

ログローテーションを管理するには、logrotate または同等のログシステムを使用してください。

スタック変数にシークレットを設定しないでください

変数が監査記録に含まれる場合があります。

パスワード、トークン、API キー、その他のシークレットをスタック変数として渡さないでください。

次の方法を推奨します：

• 環境変数
• シークレットマネージャー
• ワークロード ID
• 外部の認証情報プロバイダー

---

MCP サーバー

Seristack は、設定済みのスタックを MCP ツールとして公開できます。

Streamable HTTP MCP サーバーを起動します：

seristack mcp \
  -t streamableHTTP \
  --addr 127.0.0.1 \
  --port 8081

description があるスタックは、MCP ツールとして公開できます。

AI エージェントと MCP 互換 IDE は、利用可能なスタックを検出して呼び出せるようになります。

本番環境へのデプロイでは、MCP サーバーを HTTPS と認証レイヤーの背後に配置してください：

MCP Client
    │
    ▼
HTTPS
    │
    ▼
nginx / oauth2-proxy
    │
    ├── Authentication
    ├── TLS
    └── Identity headers
    │
    ▼
Seristack MCP
127.0.0.1:8081
    │
    ▼
Per-stack authorization
    │
    ▼
Shell execution

---

変数の検証

変数には、検証ルールと認可ルールを定義できます。

vars:

  - name: env
    value: staging
    required: true
    allowed_value:
      - staging
      - production

  - name: version
    required: true
    allowed_regex: regex("^[a-zA-Z0-9._-]+$")

  - name: command
    denied_regex: regex("(?i)rm|delete|drop")

HTTP リクエストまたは MCP 引数で上書きできるのは、vars で宣言された変数だけです。

外部入力で指定された未宣言の変数は無視されます。

検証ルールには、次のものを指定できます：

• required
• allowed_value
• denied_value
• allowed_regex
• denied_regex

---

依存関係

スタックは、ほかのスタックに依存できます：

stacks:

  - name: build
    cmds:
      - ./build.sh

  - name: test
    dependsOn:
      - build
    cmds:
      - ./test.sh

  - name: deploy
    dependsOn:
      - test
    cmds:
      - ./deploy.sh

Seristack は、実行前に依存関係の順序を解決します。

これにより、小さく再利用可能なスタックを組み合わせて、より大きなワークフローを構成できます。

---

実行モード

スタックは、順次または並行して実行するように設定できます。

順次実行

executionMode: SEQUENTIAL

コマンドまたは繰り返しの実行は順番に行われます。

並列実行

executionMode: PARALLEL

独立した実行を並行して行えます。

例：

stacks:

  - name: health-check
    executionMode: PARALLEL
    count: 3

    cmds:
      - |
        echo "health check {{.Count.index}}"

---

コマンド実行

Seristack は、設定されたシェル実行メカニズムを使用したシェルベースの実行をサポートしています。

例：

cmds:
  - echo "hello"

複数行のコマンド：

cmds:
  - |
    echo "Starting"
    ./script.sh
    echo "Finished"

使用できるシェル構文は、設定された実行環境によって異なります。

---

テスト

テストスイート全体を実行します。

go test ./...

Go のテストキャッシュを使用せずにテストを強制実行するには、次のコマンドを実行します。

go test -count=1 ./...

詳細な出力と個々のテストの実行時間を表示するには、次のコマンドを実行します。

go test -count=1 -v ./...

特定のパッケージのテストを実行します。

go test -count=1 -v ./pkg/opsy

レース検出器を実行します。

CGO_ENABLED=1 go test -race ./...

レース検出器を使用するには、サポート対象のプラットフォームで動作する C コンパイラー／ツールチェーンが必要です。

---

seristack run コマンドリファレンス

seristack run [flags]

Flags:

  -c, --config string
        config file (default "config.yaml")

  -a, --addr string
        bind address (default "127.0.0.1")

  -p, --port string
        server port (default "8080")

      --audit-log string
        path to audit log file
        enables audit logging when set

      --identity-header strings
        map identity header to a key:
        "user=X-Auth-Request-Email"
        repeatable

現在のコマンドとフラグのリファレンスを確認するには、次のコマンドを実行します。

seristack run --help

---

セキュリティに関する考慮事項

Seristack は、実行されているホスト上でコマンドを実行します。

本番環境にデプロイする前に、次の点を確認してください。

1. Seristack が localhost またはプライベートネットワークにバインドされている状態を維持します。
2. 外部からアクセス可能なエンドポイントの前段に、認証付きのリバースプロキシまたはゲートウェイを配置します。
3. リモートアクセスには HTTPS/TLS を使用します。
4. クライアントから直接送信された ID ヘッダーを信頼しないでください。
5. 機密性の高いスタックを実行できるユーザーやグループを制限します。
6. スタック変数にシークレットを設定しないでください。
7. 監査ログを確認し、定期的にローテーションします。
8. Seristack は、必要最小限のオペレーティングシステム権限で実行します。
9. 可能な場合は、ファイルシステムとネットワークの権限を制限します。
10. HTTP または MCP 経由で公開する前に、シェルコマンドを慎重に確認します。

MCP クライアントはサーバーが公開するツールを呼び出せるため、MCP アクセスも HTTP API と同様のセキュリティ上の考慮事項をもって扱う必要があります。

---

プロジェクトを支援する

Seristack が、シェルスクリプトや運用手順書を再利用可能な CLI コマンド、HTTP API、または MCP ツールに変換するうえでチームの役に立つ場合は、次のような支援をご検討ください。

• ⭐ リポジトリにスターを付ける
• 🐛 Issue を作成する
• 💡 フィードバックを共有する
• 🧪 サンプルやテストを追加する
• 🔧 改善に貢献する

GitHub リポジトリ

---

ライセンス

Apache License 2.0