scan

scan コマンドついて、以下に記します。

概要

scan コマンドは SSH 接続によるホストのスキャン、および yamory-cli をインストールしたローカルホストのスキャンを行います。

scan コマンドでスキャンを行う際に、コマンドフラグ及び設定ファイルの内容で動作を決定します。
設定ファイルはコマンドフラグ --config より指定できますが、指定がない場合、自動的にカレントディレクトリ直下の config.yaml を読み込みます。

また、スキャンにはアクセストークンが必要です。
アクセストークンは、チーム設定画面より発行できます。
発行手順などはこちらを参照してください。

アクセストークンは、コマンドフラグ、または設定ファイルで指定できます。
両方指定された場合の優先順位は以下の通りとなり、設定ファイルの設定が無視されます。

コマンドフラグ（--token） > 設定ファイル（token 項目）

コマンドフラグ

フラグ	説明
`--config`	設定ファイルの場所 (省略時は`./config.yaml` )
`--token`/`-T`	ホストスキャンのアクセストークン

設定ファイル

設定ファイルは yaml 形式で記述します。直下に token と hosts キーを記述できます。

キー	型	必須	説明
token	文字列		ホストスキャンのアクセストークン
hosts	配列	✔	スキャン対象の情報

hosts

スキャン対象のホストの情報が記述されているリストです。それぞれのリスト項目に下記のキーを記述できます。

SSH 接続でホストをスキャンする場合

キー	型	必須	説明
title	文字列		yamory サービス上表示されるスキャン対象の名前 (省略時は `hostname` の値)
hostname	文字列	✔	SSH 接続する際に使われるホスト名（ドメイン名もしくは IP アドレス）
identifier	文字列		ホスト識別子。ホスト識別子には `半角英数字`, `-`, `_` のみ使用できます。
scanMode	文字列		スキャンモードの指定 (省略時は `ssh`)
port	数字		SSH 接続する際に使われるポート番号 (省略時は `22`)
distribution	文字列		ホストの OS
version	文字列		ホストのバージョン
sshAgent	マップ		ssh-agent の設定
credentials	マップ	✔	SSH 接続する際に使われる認証情報
openSystem	文字列		公開ホストの設定を `true` または `false` で指定
tags	文字列		ホストタグ名をカンマ区切りで指定
useSudo	文字列		スキャン時に sudo を使用するか否かを指定。デフォルト `true`

yamory-cli をインストールしたローカルホストをスキャンする場合

キー	型	必須	説明
title	文字列		yamory サービス上表示されるスキャン対象の名前 (省略時は `hostname` コマンドの実行結果)
identifier	文字列		ホスト識別子。ホスト識別子には `半角英数字`, `-`, `_` のみ使用できます
scanMode	文字列	✔	スキャンモードの指定。`local` を指定します。
distribution	文字列		ホストの OS
version	文字列		ホストのバージョン
openSystem	文字列		公開ホストの設定を `true` または `false` で指定
tags	文字列		ホストタグ名をカンマ区切りで指定
useSudo	文字列		スキャン時に sudo を使用するか否かを指定。デフォルト `true`

identifier パラメーターについて

yamory のホストスキャン機能では、ホストの一意性を特定するためにマシン ID（/etc/machine-id の値）を使用していますが、クラウド環境などでコピーしたイメージを利用する際にマシン ID が同値となり、意図せずスキャン結果を上書きしてしまうことがあります。
そのような場合に identifier パラメーターを設定することでスキャン情報の上書きを回避できます。
identifier パラメーターには、チーム内でホストごとに一意の値になるように設定してください。

distribution、および version パラメーターについて

ホストの OS（distribution）、およびバージョン（version）が指定されている場合、 OS の自動判別が無効になります。
なお、現在指定できるdistributionは以下の通りです。

Amazon Linux: amazon-linux
CentOS: centos
Debian: debian
Oracle Linux: oracle-linux
Red Hat Enterprise Linux: redhat
Ubuntu: ubuntu

openSystem パラメーターについて

公開ホスト（外部ネットワークからパブリックアクセスが可能なホスト）として使用するかを指定することができます。
公開ホストの場合は true、非公開ホストの場合は false を指定します。
openSystem が未指定の場合、前回スキャン情報があればその状態を引き継ぎ、初回スキャン時は公開ホストとして登録されます。
本パラメータはトリアージレベルの計算に使用されます。

useSudo パラメーターについて

yamory のホストスキャンでは、一部のディストリビューションにおいてホスト情報を取得するコマンドを実行する際に
no password で sudo コマンドを実行できるか確認し、実行できる場合、sudo コマンドを使用してホスト情報を取得しています。
スキャンを実行するユーザーにコマンドの実行制限がない場合、 useSudo パラメーターに false を指定すると sudo を使用せずにスキャンすることができます。
useSudo パラメーターは以下のディストリビューションでのみ有効です。

Amazon Linux
CentOS
Oracle Linux
Red Hat Enterprise Linux

sshAgent

キー	型	必須	説明
useAgent	文字列		ssh-agent を使用するか否かを `true` または `false` で指定する。デフォルト `false`

credentials

現在パスワード認証、公開鍵認証、ssh-agent の使用の 3 つのパターンをサポートしています。

パスワード認証の場合

キー	型	必須	説明
user	文字列	✔	SSH 接続する際に使われるユーザ名
password	文字列	✔	SSH 接続する際に使われるパスワード

公開鍵認証の場合

キー	型	必須	説明
user	文字列	✔	SSH 接続する際に使われるユーザ名
key	文字列	✔	SSH 接続する際に使われる秘密鍵のパス
keyPassphrase	文字列		SSH 接続する際に使われる秘密鍵のパスフレーズ

ssh-agent の使用の場合

キー	型	必須	説明
user	文字列	✔	SSH 接続する際に使われるユーザ名

※ ssh-agent を利用する場合は、scan コマンドの実行前に、対応する秘密鍵を ssh-agent にあらかじめ登録しておく必要があります。

設定ファイル例

token: "xxxxx"
hosts:
  - title: "my-server"
    hostname: "192.168.0.111"
    identifier: "Change-to-unique-identifier-for-your-team!"
    port: 22
    credentials:
      user: "ubuntu"
      key: "path/to/ssh-key.pem"
      keyPassphrase: "ubuntupass1234"
    openSystem: true
    tags: "tag1"
  - title: "my-redhat-server"
    hostname: "192.168.0.222"
    identifier: "Change-to-unique-identifier-for-your-team!"
    port: 22
    credentials:
      user: "admin"
      password: "123456"
    openSystem: false
    tags: "tag1,tag2"
    useSudo: false
  - title: "my-new-server-via-ssh-agent"
    hostname: "192.168.0.333"
    identifier: "Change-to-unique-identifier-for-your-team!"
    port: 22
    distribution: "ubuntu"
    version: "20.04"
    sshAgent:
      useAgent: true
    credentials:
      user: "admin"
    openSystem: false
  - title: "local-server"
    identifier: "Change-to-unique-identifier-for-your-team!"
    scanMode: "local"

yamory の使い方