Memasang dan menjalankan CS-Agent

Apa itu CS-Agent?

CS-Agent adalah program yang Anda pasang di server tempat aplikasi berjalan. Aplikasi meminta CS-Agent untuk mengenkripsi, mendekripsi, atau menandatangani data, sehingga aplikasi Anda tidak perlu menyimpan cryptographic key sendiri.

Pemasangan pertama terdiri dari empat pekerjaan, masing-masing cukup sekali:

1. Login — mendaftarkan server ini ke akun TILE Anda.
2. Sertifikat — membuat identitas digital agar hanya aplikasi Anda yang boleh memakai CS-Agent.
3. Pengaturan — menulis file .env kecil.
4. Menjalankan — menyalakan CS-Agent. Setelah itu, sehari-hari hanya langkah ini yang diperlukan.

1Sebelum mulai

• Akun portal TILE yang sudah disetujui admin. Masuk dengan Google di halaman masuk; akun baru menunggu persetujuan dulu.
• Server Windows 10/11 atau Windows Server 2016 ke atas, 64-bit.
• Server Linux 64-bit (x86-64 atau ARM64).
• Hak Administratorsudo saat pemasangan.
• Server boleh membuka koneksi keluar HTTPS (port 443) ke alamat onboarding akun Anda.
• Alamat onboarding akun Anda. Alamat ini tertera di halaman Mulai pada portal dan diawali https://onboarding. Di panduan ini ditulis sebagai <ALAMAT-ONBOARDING>.
• Disarankan: server dengan TPM 2.0 aktif.

2Download

1. Masuk ke portal di halaman masuk dengan akun Google Anda.
2. Di menu kiri, bagian CS-Agent, pilih Download.
3. Pada rilis berlabel Terbaru, download tiga file ke satu folder:
   • program cs-agent-windows-amd64-v8.1.1.exe dan file .sha256-nya,
   • program cs-agent-linux-amd64-v8.1.1 (server x86-64) atau cs-agent-linux-arm64-v8.1.1 (server ARM64), dan file .sha256-nya. Belum tahu jenis server Anda? Jalankan uname -m: x86_64 berarti amd64, aarch64 berarti arm64.
   • sertifikat onboarding ca-onboarding.crt.

Buka halaman Download Belum masuk? Anda akan diarahkan ke halaman masuk dulu.

Download CS-Agent hanya dari portal ini. Jangan memakai salinan yang dikirim lewat email, chat, atau situs lain.

3Verifikasi checksum

Pastikan file yang Anda download utuh dan asli sebelum dijalankan.

Get-FileHash .\cs-agent-windows-amd64-v8.1.1.exe -Algorithm SHA256

sha256sum -c cs-agent-linux-*-v8.1.1.sha256

sha256sum -c cs-agent-v8.1.1.sha256sums --ignore-missing
openssl pkeyutl -verify -pubin -inkey tile-release-ed25519.pub.pem -rawin -in cs-agent-v8.1.1.sha256sums -sigfile cs-agent-v8.1.1.sha256sums.ed25519.sig

4Menyiapkan folder

Semua file CS-Agent tinggal dalam satu folder yang sama, dan perintah selalu dijalankan dari folder itu.

Unblock-File .\cs-agent.exe
.\cs-agent.exe --version

sudo mkdir -p /opt/cs-agent
sudo chown "$USER": /opt/cs-agent
mv cs-agent-linux-*-v8.1.1 /opt/cs-agent/cs-agent
mv ca-onboarding.crt /opt/cs-agent/
cd /opt/cs-agent
chmod +x cs-agent
./cs-agent --version

Jika nomor versi muncul (misalnya v8.1.1), program siap dipakai. Tambahkan --help pada perintah apa pun untuk melihat penjelasannya.

5Mendaftarkan server (login)

Langkah ini menghubungkan server dengan akun TILE Anda. Ganti <ALAMAT-ONBOARDING> dengan alamat dari halaman Mulai di portal.

.\cs-agent.exe login --cluster <ALAMAT-ONBOARDING> --ca-cert .\ca-onboarding.crt

./cs-agent login --cluster <ALAMAT-ONBOARDING> --ca-cert ./ca-onboarding.crt

1. Terminal menampilkan baris Open browser: https://… dan batas waktu Code expires at.
2. Buka tautan itu di browser — boleh di komputer lain atau ponsel — lalu masuk dengan akun portal Anda.
3. Periksa nama server yang tampil, pilih aplikasi yang boleh dipakai server ini, lalu setujui.
4. Kembali ke terminal. Jika berhasil, muncul Authentication successful!

6Membuat sertifikat untuk aplikasi

CS-Agent hanya melayani aplikasi yang membawa sertifikat yang sah. Buat tiga jenis, berurutan:

a. Penerbit. Pakai bawaan bila aplikasi Anda dibuat dengan Go 1.27+ atau memakai OpenSSL 3.5+. Untuk .NET, Java, atau bila ragu, pakai pilihan kompatibel.

.\cs-agent.exe cert ca                    # bawaan
.\cs-agent.exe cert ca --alg ecdsa-p384   # kompatibel

./cs-agent cert ca                        # bawaan
./cs-agent cert ca --alg ecdsa-p384       # kompatibel

b. Server. Jika aplikasi berjalan di server yang sama, cukup perintah pertama. Jika aplikasi menghubungi CS-Agent dari komputer lain, sebutkan alamat IP server ini (contoh 192.168.1.50).

.\cs-agent.exe cert server
.\cs-agent.exe cert server --dns localhost --ip 127.0.0.1 --ip 192.168.1.50

./cs-agent cert server
./cs-agent cert server --dns localhost --ip 127.0.0.1 --ip 192.168.1.50

c. Aplikasi. Satu sertifikat per aplikasi, supaya akses satu aplikasi bisa dicabut tanpa mengganggu yang lain. Sertakan --app berisi Application ID aplikasi itu (dari menu Aplikasi di portal), agar sertifikat siap dipakai bila client binding diaktifkan (langkah 11).

.\cs-agent.exe cert client --name app-1 --cn app-1 --app <APPLICATION-ID>

./cs-agent cert client --name app-1 --cn app-1 --app <APPLICATION-ID>

--app diisi Application ID, bukan Client ID atau fingerprint agent. Nilainya ditulis ke sertifikat sebagai urn:tile:app:<APPLICATION-ID>.

File .key bersifat rahasia, terutama ca.key. Jangan kirim lewat email atau chat. Jangan memakai --force pada cert ca: semua sertifikat lama akan ditolak.

7File pengaturan .env

Salin seluruh perintah sekaligus. Perintah ini membuat file .env di folder CS-Agent.

@"
PORT_SERVICE_CS=8112
PORT_SERVICE_GRPC=8113
CA_CERT_PATH=./ca.crt
SERVER_CERT_PATH=./server.crt
SERVER_KEY_PATH=./server.key
"@ | Set-Content -Encoding ascii .env

cat > .env <<'EOF'
PORT_SERVICE_CS=8112
PORT_SERVICE_GRPC=8113
CA_CERT_PATH=./ca.crt
SERVER_CERT_PATH=./server.crt
SERVER_KEY_PATH=./server.key
EOF

8112 adalah port untuk aplikasi HTTPS, 8113 untuk aplikasi gRPC (hapus barisnya bila tidak dipakai). Jika port sudah dipakai program lain, ganti dengan angka lain antara 1024 dan 65535.

.env hanya boleh berisi lima baris ini. CS-Agent menolak menyala bila ada baris lain, atau bila environment service menyetel GODEBUG, SSL_CERT_FILE/SSL_CERT_DIR, variabel proxy (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY), atau GRPC_*: pengaturan lain datang dari cluster. Baris LOG_RETENTION_DAYS dari panduan lama diabaikan (dengan peringatan); hapus saja.

8Menjalankan CS-Agent

.\cs-agent.exe serve

./cs-agent serve

Penyalaan pertama butuh beberapa detik. CS-Agent siap melayani ketika muncul tulisan OPERATIONAL.

• Biarkan jendela terminal terbuka; menutupnya berarti mematikan CS-Agent. Untuk berjalan tanpa jendela, lihat langkah 9.
• Untuk mematikan: klik jendela terminal, tekan Ctrl + C.
• Untuk catatan rinci di layar saat mencari masalah: tambahkan --verbose.
• Jika muncul Your environment is not secure. Use an environment with TPM 2.0., CS-Agent tetap berjalan. Untuk perlindungan terbaik, pakai server dengan TPM 2.0 aktif.

9Menyala otomatis

Jalankan CS-Agent dengan akun khusus tanpa hak administrator, dan batasi file rahasianya agar hanya akun itu yang bisa membaca.

sudo useradd --system --no-create-home --shell /usr/sbin/nologin cs-agent
sudo chown -R cs-agent:cs-agent /opt/cs-agent
sudo chmod 0600 /opt/cs-agent/.zerotrust-tile/config.json /opt/cs-agent/*.key
sudo chmod 0644 /opt/cs-agent/*.crt

[Unit]
Description=TILE CS-Agent
After=network-online.target
Wants=network-online.target

[Service]
User=cs-agent
Group=cs-agent
WorkingDirectory=/opt/cs-agent
ExecStart=/opt/cs-agent/cs-agent serve
Restart=always
RestartSec=5
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/opt/cs-agent

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now cs-agent
sudo systemctl status cs-agent
sudo journalctl -u cs-agent -f        # catatan kegiatan, Ctrl+C untuk keluar

icacls "C:\cs-agent\.zerotrust-tile\config.json" /inheritance:r /grant:r "svc-csagent:(R)"
icacls "C:\cs-agent\server.key" /inheritance:r /grant:r "svc-csagent:(R)"

$cred     = Get-Credential "$env:COMPUTERNAME\svc-csagent"
$action   = New-ScheduledTaskAction -Execute 'C:\cs-agent\cs-agent.exe' -Argument 'serve' -WorkingDirectory 'C:\cs-agent'
$trigger  = New-ScheduledTaskTrigger -AtStartup
$settings = New-ScheduledTaskSettingsSet -ExecutionTimeLimit ([TimeSpan]::Zero) -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1)
Register-ScheduledTask -TaskName 'TILE CS-Agent' -Action $action -Trigger $trigger -Settings $settings `
  -User $cred.UserName -Password $cred.GetNetworkCredential().Password
Start-ScheduledTask -TaskName 'TILE CS-Agent'

10Menghubungkan aplikasi

Bagian ini biasanya dikerjakan pembuat aplikasi. Serahkan kepada mereka lewat jalur aman:

• app-1.crt dan app-1.key (langkah 6c), serta ca.crt — bukan ca.key.
• Alamat CS-Agent, misalnya https://localhost:8112 atau https://192.168.1.50:8112, dan port gRPC bila dipakai.
• ID client dan API key aplikasi dari menu Aplikasi di portal.

Daftar endpoint REST dan gRPC lengkap dengan contoh kode (Go, PHP, Python, Node.js, .NET, Java, Ruby) ada di API Reference pada portal — buka API Reference (perlu masuk ke portal).

Aplikasi ditolak dengan pesan not allowed? Izinkan aplikasi itu untuk server ini di menu Agent pada portal, lalu jalankan ulang CS-Agent.

11Pengamanan tambahan (opsional)

Tanpa pengaturan apa pun, CS-Agent sudah mewajibkan sertifikat aplikasi (langkah 6) dan API key aplikasi. Tiga pengaman berikut bisa Anda aktifkan sendiri di portal untuk mempersempit siapa yang boleh memakai CS-Agent. Setiap perubahan meminta kode TOTP dan sampai ke CS-Agent dalam sekitar 2 menit, tanpa restart.

Urutan pemeriksaan setiap permintaan aplikasi

1. Aplikasi membawa sertifikat + API key
2. 1 Sertifikat sah diterbitkan CA Anda, belum expired, tidak dicabut gagal: client_certificate_revoked
3. 2 Aplikasi diizinkan aplikasi pada API key diizinkan di server ini gagal: application_not_allowed
4. 3 Filter source IP opsional alamat aplikasi ada di daftar IP gagal: source_ip_not_allowed
5. 4 Client binding opsional sertifikat memang untuk aplikasi pada API key gagal: client_binding_failed
6. Diproses enkripsi, dekripsi, tanda tangan

Pemeriksaan berhenti di langkah pertama yang gagal, dan aplikasi menerima kode error langkah itu. Langkah 3 dan 4 hanya berjalan bila Anda mengaktifkannya.

a. Client binding: sertifikat hanya untuk aplikasinya

Diatur per aplikasi: menu Aplikasi, lalu klik label binding aplikasi itu (off, audit, atau enforce). CS-Agent mencocokkan sertifikat yang dipakai dengan aplikasi pada API key. Aturan bawaan: sertifikat harus memuat urn:tile:app:<APPLICATION-ID>, yaitu hasil --app pada langkah 6c. Pemilik aplikasi yang sama tidak cukup: sertifikat aplikasi A tetap ditolak untuk aplikasi B walaupun keduanya milik Anda.

Halaman Client binding menampilkan Pratinjau pemakaian 24 jam sampai 90 hari terakhir: sertifikat mana yang akan diterima atau ditolak sebelum Anda menyimpan.

Opsi Source IP harus tercantum di IP SAN certificate mengikat sertifikat juga ke alamat host aplikasi. Tulis alamat itu dengan --ip saat membuat sertifikat (boleh diulang). Pakai hanya untuk host dengan IP tetap: bila IP berubah, sertifikat harus diterbitkan ulang.

.\cs-agent.exe cert client --name app-1 --cn app-1 --app <APPLICATION-ID> --ip 10.20.0.11

./cs-agent cert client --name app-1 --cn app-1 --app <APPLICATION-ID> --ip 10.20.0.11

b. Filter source IP

Diatur per agent: menu Agent → detail agent → Network. Isi daftar alamat IP untuk setiap aplikasi. Jumlah IP per aplikasi dibatasi (bawaan 2); hubungi admin TILE bila perlu lebih.

• Enforce berlaku untuk semua aplikasi di agent itu. Aplikasi yang daftar IP-nya masih kosong ikut ditolak. Mulai dengan Audit, lengkapi daftarnya, baru pindah ke Enforce.
• Aplikasi di belakang load balancer: tanpa pengaturan tambahan, CS-Agent melihat alamat load balancer, bukan alamat aplikasi. Bila load balancer L4 Anda mendukung PROXY protocol, aktifkan di load balancer, lalu pilih Load balancer L4 dengan PROXY protocol dan isi alamat load balancer di Load balancer yang dipercaya. Koneksi dari alamat lain yang mengirim header PROXY ditolak.
• Terkunci karena pengaturan sendiri dan tidak bisa membuka akses lagi? Admin TILE dapat mengembalikan Network agent ke pengaturan bawaan.

c. Mencabut sertifikat aplikasi

Sertifikat bocor atau aplikasi berhenti dipakai? Cabut sertifikatnya; sertifikat aplikasi lain tidak terpengaruh.

• Dari portal (disarankan): menu Agent → detail agent → Client certificate → Revoke. Berlaku dalam sekitar 2 menit dan tidak perlu diperbarui.
• Dari server, bila server tidak bisa menghubungi TILE: CS-Agent memuat ulang daftar pencabutan lokal (CRL) dalam satu menit.

.\cs-agent.exe cert revoke --name app-1
.\cs-agent.exe cert crl                    # perbarui CRL tanpa mencabut apa pun

./cs-agent cert revoke --name app-1
./cs-agent cert crl                        # perbarui CRL tanpa mencabut apa pun

d. Memantau masa berlaku sertifikat

.\cs-agent.exe cert status .\

./cs-agent cert status ./

Menampilkan masa berlaku dan algoritma CA, sertifikat server, dan semua sertifikat aplikasi. Exit code 0 berarti semua aman, 1 ada yang tinggal ≤ 30 hari, 2 ada yang ≤ 7 hari, sudah expired, atau tidak terbaca, sehingga bisa dipakai langsung di cron atau monitoring. Status yang sama tampil di menu Agent pada portal.

e. Contoh kasus

Dalam contoh ini Anda punya dua aplikasi, Aplikasi A dan Aplikasi B. Warna label menunjukkan sertifikat atau API key itu milik aplikasi mana.

Client binding

Filter source IP

Pencabutan

Pertanyaan lain

12Log dan Filebeat

CS-Agent menulis log ke folder logs di folder CS-Agent, satu file per tanggal (WIB):

• info-2026-10-25.log: aktivitas normal.
• error-2026-10-25.log: peringatan dan error.
• Lewat pukul 00:00 WIB, file tanggal baru dibuat otomatis tanpa restart. Bila satu file melewati 100 MB dalam sehari, log berlanjut ke info-2026-10-25.1.log, .2, dan seterusnya.

Lama penyimpanan log diatur operator cluster untuk semua agent (bawaan 30 hari, 7–3650), termasuk hari ini. Dengan 30, log hari pertama dihapus pada hari ke-31. Yang dihapus hanya file log CS-Agent di folder logs; file lain di folder itu tidak disentuh. Sebelum CS-Agent menerima pengaturan dari cluster, tidak ada log yang dihapus.

Setiap baris adalah satu objek JSON. Field yang selalu ada: @timestamp (WIB, milidetik), level, message, service; identitas agent: agent_name, agent_id, fingerprint_agent (sama dengan Agent ID dan Fingerprint di menu Agent), cs_version; dan bila ada: type, details, request_id, endpoint, status_code. Pakai fingerprint_agent untuk memfilter satu agent di Elasticsearch: nilainya tetap walau hostname atau container berganti. Baris dari detik-detik pertama penyalaan belum membawa identitas agent. Nama field tidak akan diubah antarversi, jadi mapping dan dashboard Elasticsearch Anda tetap berlaku setelah update.

Mengirim log ke Elasticsearch dengan Filebeat

Tambahkan input berikut di filebeat.yml:

filebeat.inputs:
  - type: filestream
    id: cs-agent
    paths:
      - 'C:\cs-agent\logs\*.log'
    prospector.scanner.fingerprint.enabled: false
    file_identity.native: ~
    parsers:
      - ndjson:
          target: ""
          overwrite_keys: true
          add_error_key: true

filebeat.inputs:
  - type: filestream
    id: cs-agent
    paths:
      - /opt/cs-agent/logs/*.log
    prospector.scanner.fingerprint.enabled: false
    file_identity.native: ~
    parsers:
      - ndjson:
          target: ""
          overwrite_keys: true
          add_error_key: true

• file_identity.native: CS-Agent tidak pernah mengganti nama atau memotong file log, jadi identitas file bawaan sistem aman dipakai. Jangan memakai fingerprint (bawaan Filebeat 9): file di bawah 1 KB, misalnya file error yang baru berisi satu baris, baru dikirim setelah melewati 1 KB.
• overwrite_keys membuat Elasticsearch memakai @timestamp dari CS-Agent, bukan waktu Filebeat membaca baris.
• File log hanya bisa dibaca pemiliknya dan grupnya (0640). Jalankan Filebeat sebagai root, atau masukkan user Filebeat ke grup user yang menjalankan CS-Agent.
• Field details berisi teks kunci=nilai, kunci=nilai. Untuk mencarinya per kunci, pecah di ingest pipeline Elasticsearch dengan processor kv (field_split: ", ", value_split: "=").
• Pastikan Filebeat sudah mengirim log sebelum batas penyimpanan log (bawaan 30 hari): file yang sudah dihapus tidak bisa dikirim lagi.

13Memperbarui ke versi baru

1. Download versi terbaru dari halaman Download dan periksa checksumnya (langkah 3).
2. Matikan CS-Agent: Ctrl + C di terminal, atau Stop-ScheduledTask -TaskName 'TILE CS-Agent'. Ctrl + C di terminal, atau sudo systemctl stop cs-agent.
3. Ganti file program lama dengan yang baru, dengan nama yang sama (cs-agent.execs-agent) di folder yang sama. File lain jangan dihapus.
4. Pulihkan izin: sudo chmod +x /opt/cs-agent/cs-agent && sudo chown cs-agent:cs-agent /opt/cs-agent/cs-agent
5. Jalankan Unblock-File .\cs-agent.exe.
6. Nyalakan lagi, lalu pastikan --version menunjukkan versi baru. Login ulang tidak diperlukan.

14Kapan harus login ulang?

• Muncul Bootstrap token expired atau please login again.
• Muncul Agent fingerprint mismatch — nama komputer berubah, atau folder disalin dari komputer lain.
• Muncul no cluster configured, atau folder .zerotrust-tile terhapus.
• Akun Windows yang menjalankan CS-Agent diganti.
• Admin TILE meminta Anda pindah ke alamat onboarding lain.

Caranya sama dengan langkah 5. Sertifikat dan .env tidak perlu dibuat ulang.

Jika CS-Agent sudah berjalan sebagai layanan (langkah 9), matikan dulu layanannya lalu login sebagai akun layanan: sudo systemctl stop cs-agent && sudo -u cs-agent ./cs-agent login --cluster <ALAMAT-ONBOARDING> --ca-cert ./ca-onboarding.crt, kemudian sudo systemctl start cs-agent.

15Jika ada masalah