cem_acpt 0.12.1 → 0.12.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9db8e060c748eb655248cac9a3a00d67802081d0d63b31f9f3a5daa6385c13f
-  data.tar.gz: 365a1e9551b3721869e7b9dc649408f544be47eddc84cccb3b8cf0f0ab025178
+  metadata.gz: 1e37459e007c8e05a53fddf7920cefb42223e7e490785a3601372fdf172de82f
+  data.tar.gz: 1147801fce2be7b5d0a1847d817449ad2492c8ec04707d5a82713663b2406804
 SHA512:
-  metadata.gz: e33957643fc4601962aff311034849f6840972ba8d47860ebabcaef9b42cab1e8cf874aa06be1f0e3743d8511c494a2ec92d57d92f74ef0f3cfa673d08e14b39
-  data.tar.gz: 9fadc4795a4b18a1ad889719c69b2962c70c19b54775cebafd00c67f3d876e118913a06267b973d17080942a67937deab2b00bee6bec97b7c36741910fa1e488
+  metadata.gz: e3e28851afbfdeeb9a2d4ca0cfc0fb10f304ba121111422416f5a50757fc9ea50bdc30db20149d00b0d04dcf91d548e73c03276863601037417ce1c39a914090
+  data.tar.gz: 232de289f1ba433d6e5c25737cadffc8641dae7052075e359e663f935225547b44f3e430f8509c9f2519f8d8abf41204b83c76964eee387cf554f45bafd04b49

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cem_acpt (0.12.1)
+    cem_acpt (0.12.2)
       async-http (>= 0.60, < 0.70)
       bcrypt_pbkdf (>= 1.0, < 2.0)
       deep_merge (>= 1.2, < 2.0)

data/lib/cem_acpt/config/cem_acpt_scan.rb

@@ -45,6 +45,7 @@ module CemAcpt
             daemon: {
               port: 8084,
               ready_timeout: 60,
+              poll_interval: 10,
             },
             profiles: {
               openscap: {},

data/lib/cem_acpt/scan/daemon_client.rb

@@ -9,33 +9,42 @@ require_relative 'result'
 module CemAcpt
   module Scan
     # HTTP client for the on-node scan daemon. Mirrors the role of
-    # {CemAcpt::Goss::Api}: build URIs, GET them, parse the JSON response,
-    # turn the response into a typed result.
+    # {CemAcpt::Goss::Api}: build URIs, drive the async scan endpoints, parse
+    # JSON responses, turn the result into a typed {Result}.
     #
     # The daemon is installed by {CemAcpt::Provision::Linux#scan_provision_commands}
-    # and serves two endpoints on the configurable scan port:
+    # and serves four endpoints on the configurable scan port:
     #
-    #   GET /health -> 200 OK once the daemon has started and the scanner
-    #                  binaries it needs are present on disk.
-    #   GET /scan   -> 200 with a JSON body shaped like:
-    #                    { "score":  87.4, "passed_count": 187, "failed_count": 27,
-    #                      "not_applicable_count": 14, "error_count": 0, "rules": [...] }
-    #                  Non-200 responses or unparseable bodies raise
-    #                  {ScannerInvocationError}.
+    #   GET  /health  -> 200 OK once the daemon has started and the scanner
+    #                    binaries it needs are present on disk.
+    #   POST /scan    -> 202 Accepted; kicks off the scan in a background thread.
+    #                    409 Conflict if a scan is already running.
+    #   GET  /status  -> { "state": "idle" | "running" | "done" | "error" }.
+    #   GET  /result  -> 200 with the JSON result when state is terminal,
+    #                    404 otherwise.
+    #
+    # {#scan} drives the async flow: POST /scan, then poll /status, then
+    # GET /result. Each request is short-lived to avoid the connection-drop
+    # failure mode that affected the previous synchronous /scan design.
     class DaemonClient
       DEFAULT_PORT = 8084
       DEFAULT_READY_TIMEOUT = 60
-      DEFAULT_HTTP_TIMEOUT = 1800 # 30 minutes — scans can be long
+      DEFAULT_HTTP_TIMEOUT = 1800 # 30 minutes — overall deadline for a scan
+      DEFAULT_POLL_INTERVAL = 10
+      DEFAULT_REQUEST_TIMEOUT = 60
 
       # @param host [String] The IP or DNS name of the test node.
       # @param port [Integer] The port the daemon listens on.
       # @param ready_timeout [Integer] How long to wait for /health.
-      # @param http_timeout [Integer] How long a single /scan request may take.
-      def initialize(host:, port: DEFAULT_PORT, ready_timeout: DEFAULT_READY_TIMEOUT, http_timeout: DEFAULT_HTTP_TIMEOUT)
+      # @param http_timeout [Integer] Overall deadline for a scan (POST + polls + result fetch).
+      # @param poll_interval [Integer] Seconds between /status polls.
+      def initialize(host:, port: DEFAULT_PORT, ready_timeout: DEFAULT_READY_TIMEOUT,
+                     http_timeout: DEFAULT_HTTP_TIMEOUT, poll_interval: DEFAULT_POLL_INTERVAL)
         @host = host
         @port = port
         @ready_timeout = ready_timeout
         @http_timeout = http_timeout
+        @poll_interval = poll_interval
       end
 
       # Polls /health until it returns 200 or the timeout elapses.
@@ -56,35 +65,90 @@ module CemAcpt
         raise DaemonNotReadyError, msg
       end
 
-      # Hits /scan and turns the response into a {Result}.
+      # Kicks off the scan, polls until it finishes, and fetches the result.
       # @param test_case [String] Acceptance-test directory name.
       # @param scanner [Symbol] :openscap or :ciscat.
       # @param profile [String] Scanner-native profile id.
       # @param threshold [Float] Pass threshold (0-100).
       # @return [Result]
-      # @raise [ScannerInvocationError] on non-200 or unparseable body.
+      # @raise [ScannerInvocationError] on protocol errors or scan deadline exceeded.
       def scan(test_case:, scanner:, profile:, threshold:)
-        uri = URI("http://#{@host}:#{@port}/scan")
-        status, body = get(uri, timeout: @http_timeout)
+        start_scan
+        wait_for_completion
+        body = fetch_result
+        Result.new(test_case: test_case, scanner: scanner, profile: profile, threshold: threshold, body: body)
+      end
+
+      private
+
+      def start_scan
+        status, body = post(URI("http://#{@host}:#{@port}/scan"), timeout: DEFAULT_REQUEST_TIMEOUT)
+        return if status.to_i == 202
+
+        raise ScannerInvocationError, "Scan kickoff at #{@host}:#{@port} returned status #{status}: #{body.inspect}"
+      end
+
+      def wait_for_completion
+        deadline = Time.now + @http_timeout
+        loop do
+          raise ScannerInvocationError, "Scan did not finish within #{@http_timeout}s" if Time.now > deadline
+
+          _status, body = get(URI("http://#{@host}:#{@port}/status"), timeout: DEFAULT_REQUEST_TIMEOUT)
+          case body['state']
+          when 'done', 'error' then return
+          when 'running' then sleep @poll_interval
+          else
+            raise ScannerInvocationError, "Unexpected scan state from #{@host}:#{@port}: #{body['state'].inspect}"
+          end
+        end
+      end
+
+      def fetch_result
+        status, body = get(URI("http://#{@host}:#{@port}/result"), timeout: DEFAULT_REQUEST_TIMEOUT)
         unless status.to_i == 200
           raise ScannerInvocationError, "Scan daemon at #{@host}:#{@port} returned status #{status}: #{body.inspect}"
         end
 
-        Result.new(test_case: test_case, scanner: scanner, profile: profile, threshold: threshold, body: body)
+        body
       end
 
-      private
-
       def get(uri, timeout:)
+        request(uri, Net::HTTP::Get.new(uri.request_uri), timeout: timeout)
+      end
+
+      def post(uri, timeout:)
+        request(uri, Net::HTTP::Post.new(uri.request_uri), timeout: timeout)
+      end
+
+      def request(uri, req, timeout:)
         http = Net::HTTP.new(uri.host, uri.port)
         http.read_timeout = timeout
         http.open_timeout = [timeout, 30].min
-        response = http.get(uri.request_uri)
+        http.start
+        enable_tcp_keepalive(http)
+        response = http.request(req)
         body = response.body.to_s
         parsed = body.empty? ? {} : JSON.parse(body)
         [response.code, parsed]
       rescue JSON::ParserError => e
         raise ScannerInvocationError, "Scan daemon at #{@host}:#{@port} returned non-JSON body: #{e.message}"
+      ensure
+        http.finish if http.started?
+      end
+
+      def enable_tcp_keepalive(http)
+        socket = http.instance_variable_get(:@socket)&.io
+        return unless socket
+
+        socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_KEEPALIVE, true)
+        # Linux uses TCP_KEEPIDLE; macOS uses TCP_KEEPALIVE for the same idle-time option.
+        idle_opt = Socket.const_defined?(:TCP_KEEPIDLE) ? Socket::TCP_KEEPIDLE : Socket::TCP_KEEPALIVE
+        socket.setsockopt(Socket::IPPROTO_TCP, idle_opt,              60)
+        socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_KEEPINTVL, 10)
+        socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_KEEPCNT,   6)
+      rescue Errno::ENOPROTOOPT
+        # Platform supports SO_KEEPALIVE but not the fine-grained probe constants;
+        # SO_KEEPALIVE alone was already set and provides partial protection.
       end
     end
   end

data/lib/cem_acpt/test_runner.rb

@@ -315,6 +315,7 @@ module CemAcpt
         logger.info('CemAcpt::TestRunner') { 'Running scan action...' }
         port = config.get('cem_acpt_scan.daemon.port') || CemAcpt::Scan::DaemonClient::DEFAULT_PORT
         ready_timeout = config.get('cem_acpt_scan.daemon.ready_timeout') || CemAcpt::Scan::DaemonClient::DEFAULT_READY_TIMEOUT
+        poll_interval = config.get('cem_acpt_scan.daemon.poll_interval') || CemAcpt::Scan::DaemonClient::DEFAULT_POLL_INTERVAL
         global_threshold = (config.get('cem_acpt_scan.threshold') || 80.0).to_f
         per_case_thresholds = config.get('cem_acpt_scan.test_thresholds') || {}
         scan_output = config.get('cem_acpt_scan.scan_output')
@@ -326,7 +327,7 @@ module CemAcpt
           scan_meta = scan_meta_for(test_name)
           threshold = per_case_thresholds[test_name] || per_case_thresholds[test_name.to_sym] || global_threshold
 
-          client = CemAcpt::Scan::DaemonClient.new(host: host, port: port, ready_timeout: ready_timeout)
+          client = CemAcpt::Scan::DaemonClient.new(host: host, port: port, ready_timeout: ready_timeout, poll_interval: poll_interval)
           client.wait_until_ready
           result = client.scan(
             test_case: test_name,

data/lib/cem_acpt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CemAcpt
-  VERSION = '0.12.1'
+  VERSION = '0.12.2'
 end

data/lib/terraform/gcp/linux/scan/scan_service.rb

@@ -127,6 +127,13 @@ def perform_scan
   end
 end
 
+# Module-level scan state guarded by a Mutex. POST /scan flips state to
+# 'running' and spawns a background thread; the thread parks the result and
+# flips state to 'done' or 'error' on completion. GET /status and GET /result
+# read the state under the mutex. One scan in flight per daemon.
+SCAN_STATE = { state: 'idle', result: nil, started_at: nil }
+SCAN_MUTEX = Mutex.new
+
 port = ENV.fetch('SCAN_DAEMON_PORT', '8084').to_i
 server = WEBrick::HTTPServer.new(Port: port, BindAddress: '0.0.0.0')
 
@@ -136,11 +143,53 @@ server.mount_proc('/health') do |_req, res|
   res.body = JSON.generate('status' => 'ok')
 end
 
-server.mount_proc('/scan') do |_req, res|
-  payload = perform_scan
-  res.status = payload['error'] ? 500 : 200
+server.mount_proc('/scan') do |req, res|
+  res['Content-Type'] = 'application/json'
+  unless req.request_method == 'POST'
+    res.status = 405
+    res.body = JSON.generate('error' => 'use POST /scan')
+    next
+  end
+  SCAN_MUTEX.synchronize do
+    if SCAN_STATE[:state] == 'running'
+      res.status = 409
+      res.body = JSON.generate('error' => 'scan already running')
+      next
+    end
+    SCAN_STATE[:state]      = 'running'
+    SCAN_STATE[:started_at] = Time.now
+    SCAN_STATE[:result]     = nil
+  end
+  Thread.new do
+    payload = perform_scan
+    SCAN_MUTEX.synchronize do
+      SCAN_STATE[:state]  = payload['error'] ? 'error' : 'done'
+      SCAN_STATE[:result] = payload
+    end
+  end
+  res.status = 202
+  res.body = JSON.generate('status' => 'started')
+end
+
+server.mount_proc('/status') do |_req, res|
+  res['Content-Type'] = 'application/json'
+  SCAN_MUTEX.synchronize do
+    res.status = 200
+    res.body = JSON.generate('state' => SCAN_STATE[:state])
+  end
+end
+
+server.mount_proc('/result') do |_req, res|
   res['Content-Type'] = 'application/json'
-  res.body = JSON.generate(payload)
+  SCAN_MUTEX.synchronize do
+    if %w[done error].include?(SCAN_STATE[:state])
+      res.status = 200
+      res.body = JSON.generate(SCAN_STATE[:result])
+    else
+      res.status = 404
+      res.body = JSON.generate('error' => "no result available, state: #{SCAN_STATE[:state]}")
+    end
+  end
 end
 
 trap('INT')  { server.shutdown }

data/specifications/CEM-6799.md

@@ -0,0 +1,294 @@
+# CEM-6799 — Async scan protocol and TCP keepalive on DaemonClient
+
+## Summary
+
+`DaemonClient#scan` makes a single synchronous `GET /scan` and holds the TCP
+connection open for the full scan duration (15–30 minutes for STIG/CIS
+benchmarks). Two failure modes follow from this:
+
+1. **Idle connection drop.** During the long wait no data flows; GCP's VPC
+   firewall, Cloud NAT, or OS-level connection tracking drops the idle session
+   and the client raises `Errno::ECONNRESET` or `Errno::ENOTCONN` at
+   `read_nonblock`. Confirmed in local runs (`ENOTCONN` after ~1007 s) and
+   GitHub Actions CI (`ECONNRESET` after ~912 s).
+2. **Response delivery failure.** Even when the scan completes successfully on
+   the node and writes its result file to disk, the response body cannot be
+   delivered back over a connection that has been idle long enough to be torn
+   down. Confirmed on Ubuntu 24.04: `ciscat-results.json` (81 KB) and
+   `ciscat-results-ARF.xml` (8.7 MB) both written to
+   `/opt/cem_acpt/scan/reports/`, but the client raised `ENOTCONN` at 736 s
+   while reading the response.
+
+The fix has two parts:
+
+1. **Async scan protocol.** `/scan` becomes a kickoff endpoint that returns
+   immediately; the daemon runs the scan in a background thread. The client
+   polls a new `/status` endpoint with short-lived HTTP calls, then fetches the
+   result via a new `/result` endpoint once the daemon reports completion.
+   Long-lived connections are eliminated entirely.
+2. **TCP keepalive on `DaemonClient#get`.** Belt-and-suspenders: even the
+   short-lived polling calls enable `SO_KEEPALIVE` so any transient idle period
+   inside a single HTTP exchange is protected.
+
+## Functional Behavior
+
+### Daemon endpoints — `lib/terraform/gcp/linux/scan/scan_service.rb`
+
+**Before:**
+
+- `GET /health` — 200 OK when daemon is up.
+- `GET /scan` — blocks for the scan duration; returns 200 with result JSON or
+  500 with an error.
+
+**After:**
+
+- `GET /health` — unchanged.
+- `POST /scan` — kicks off the scan in a background thread; returns `202
+  Accepted` with `{"status": "started"}` immediately. Returns `409 Conflict`
+  with `{"error": "scan already running"}` if a scan is already in flight.
+- `GET /status` — new. Returns `{"state": "idle" | "running" | "done" |
+  "error"}` so the client can poll.
+- `GET /result` — new. Returns `200` with the result JSON when the daemon's
+  state is `done` or `error`; `404` with `{"error": "no result available, state:
+  <current>"}` otherwise.
+
+Scan state is held in module-level variables guarded by a `Mutex`. There is no
+new class — the daemon script stays script-shaped:
+
+```ruby
+SCAN_STATE = { state: 'idle', result: nil, started_at: nil }
+SCAN_MUTEX = Mutex.new
+
+server.mount_proc('/scan') do |req, res|
+  res['Content-Type'] = 'application/json'
+  unless req.request_method == 'POST'
+    res.status = 405
+    res.body = JSON.generate('error' => 'use POST /scan')
+    next
+  end
+  SCAN_MUTEX.synchronize do
+    if SCAN_STATE[:state] == 'running'
+      res.status = 409
+      res.body = JSON.generate('error' => 'scan already running')
+      next
+    end
+    SCAN_STATE[:state]      = 'running'
+    SCAN_STATE[:started_at] = Time.now
+    SCAN_STATE[:result]     = nil
+  end
+  Thread.new do
+    result = perform_scan
+    SCAN_MUTEX.synchronize do
+      SCAN_STATE[:state]  = result['error'] ? 'error' : 'done'
+      SCAN_STATE[:result] = result
+    end
+  end
+  res.status = 202
+  res.body = JSON.generate('status' => 'started')
+end
+
+server.mount_proc('/status') do |_req, res|
+  res['Content-Type'] = 'application/json'
+  SCAN_MUTEX.synchronize do
+    res.status = 200
+    res.body = JSON.generate('state' => SCAN_STATE[:state])
+  end
+end
+
+server.mount_proc('/result') do |_req, res|
+  res['Content-Type'] = 'application/json'
+  SCAN_MUTEX.synchronize do
+    if %w[done error].include?(SCAN_STATE[:state])
+      res.status = 200
+      res.body = JSON.generate(SCAN_STATE[:result])
+    else
+      res.status = 404
+      res.body = JSON.generate('error' => "no result available, state: #{SCAN_STATE[:state]}")
+    end
+  end
+end
+```
+
+### Client — `DaemonClient#scan` (`lib/cem_acpt/scan/daemon_client.rb`)
+
+**Before:** single `GET /scan` with a 30-minute `read_timeout`.
+
+**After:** POST → poll → GET. Each request is a short-lived connection.
+
+```ruby
+DEFAULT_POLL_INTERVAL = 10
+DEFAULT_REQUEST_TIMEOUT = 60
+
+def scan(test_case:, scanner:, profile:, threshold:)
+  start_scan
+  wait_for_completion
+  body = fetch_result
+  Result.new(test_case: test_case, scanner: scanner, profile: profile, threshold: threshold, body: body)
+end
+
+private
+
+def start_scan
+  status, body = post(URI("http://#{@host}:#{@port}/scan"), timeout: DEFAULT_REQUEST_TIMEOUT)
+  return if status.to_i == 202
+  raise ScannerInvocationError, "Scan kickoff at #{@host}:#{@port} returned status #{status}: #{body.inspect}"
+end
+
+def wait_for_completion
+  deadline = Time.now + @http_timeout
+  loop do
+    raise ScannerInvocationError, "Scan did not finish within #{@http_timeout}s" if Time.now > deadline
+
+    _status, body = get(URI("http://#{@host}:#{@port}/status"), timeout: DEFAULT_REQUEST_TIMEOUT)
+    case body['state']
+    when 'done', 'error' then return
+    when 'running'       then sleep @poll_interval
+    else
+      raise ScannerInvocationError, "Unexpected scan state: #{body['state'].inspect}"
+    end
+  end
+end
+
+def fetch_result
+  status, body = get(URI("http://#{@host}:#{@port}/result"), timeout: DEFAULT_REQUEST_TIMEOUT)
+  raise ScannerInvocationError, "Scan daemon at #{@host}:#{@port} returned status #{status}: #{body.inspect}" unless status.to_i == 200
+  body
+end
+```
+
+`@poll_interval` defaults to `DEFAULT_POLL_INTERVAL` (10 s); configurable via
+`cem_acpt_scan.daemon.poll_interval`.
+
+A new private `post` helper mirrors `get` (same keepalive setup, same JSON
+handling, no request body needed for `POST /scan` so it sends an empty body).
+
+### TCP keepalive — `DaemonClient#enable_tcp_keepalive`
+
+Unchanged from the current keepalive implementation. Sets `SO_KEEPALIVE`,
+`TCP_KEEPIDLE` (Linux) / `TCP_KEEPALIVE` (macOS), `TCP_KEEPINTVL`,
+`TCP_KEEPCNT` on every socket opened by `get` and `post`. Kept as
+belt-and-suspenders even though connections are now short-lived.
+
+## Non-Goals
+
+- Persisting scan state across daemon restarts (state is in memory; a daemon
+  crash mid-scan loses the result).
+- Multiple concurrent scans on a single node. The daemon serializes to one scan
+  at a time; concurrent `POST /scan` returns 409.
+- Cancelling an in-flight scan via the API.
+- Authentication on the scan endpoints. The daemon is firewalled to the
+  provisioning host; this is unchanged.
+
+## Configuration
+
+New config key:
+
+- `cem_acpt_scan.daemon.poll_interval` — Integer, seconds between `/status`
+  polls. Default: `10`.
+
+Existing keys unchanged:
+
+- `cem_acpt_scan.daemon.port` — daemon port.
+- `cem_acpt_scan.daemon.ready_timeout` — `/health` poll timeout.
+- The host-side `http_timeout` (default 1800 s) is the total deadline for a
+  scan, including all polling, not the timeout for any single HTTP request.
+
+## Edge Cases
+
+- **Daemon crashes mid-scan.** The result file may still be on disk in
+  `/opt/cem_acpt/scan/reports/`, but the daemon's in-memory state is gone. On
+  daemon restart, `/status` returns `idle` and the client's poll loop will
+  receive an `Unexpected scan state` once it reconnects. Acceptable for now;
+  persistence is a non-goal.
+- **`POST /scan` while a scan is running.** Returns 409. The client treats this
+  as an error.
+- **`GET /result` while scan is running.** Returns 404 with state diagnostic.
+  The client only calls `/result` after `/status` reports a terminal state, so
+  this is for safety.
+- **Background thread raises.** `perform_scan` already wraps errors and returns
+  a hash with an `error` key. The thread sets state to `error` and stores the
+  hash; the client picks it up via `/result`. The existing `ScannerInvocationError`
+  path in `DaemonClient` handles this when `Result.new` sees an error body.
+- **macOS without `TCP_KEEPIDLE`.** The keepalive code already handles this
+  via `Socket.const_defined?(:TCP_KEEPIDLE)` falling back to
+  `Socket::TCP_KEEPALIVE`.
+
+## Constraints / Invariants
+
+- `DaemonClient` public interface is unchanged: `wait_until_ready` and `scan`
+  with the same signatures and return shapes.
+- The daemon script remains a single-file standalone systemd service.
+- One scan at a time per daemon. The daemon is per-node, so this matches the
+  per-test-case model.
+
+## Alternatives Considered
+
+**SCP the result file off the node.** After kicking off the scan, fetch the
+result JSON via SSH/SCP from `/opt/cem_acpt/scan/reports/` rather than HTTP.
+Rejected — would require threading SSH credentials through the scan layer (the
+scan path currently uses HTTP only) and would bypass the daemon's error
+encoding.
+
+**Keep `GET /scan` synchronous with TCP keepalive only.** This was the original
+CEM-6799 plan. Rejected because Ubuntu 24.04 testing on 2026-06-23 showed the
+scan completing successfully but the response body being undeliverable: the
+connection had been torn down despite keepalive probes. Keepalive on its own is
+not sufficient.
+
+## Tests
+
+### `spec/cem_acpt/scan/daemon_client_spec.rb`
+
+- Update existing `#scan` examples to stub three sequential calls: a `POST
+  /scan` returning 202, one or more `GET /status` returning `running` then
+  `done`, and a `GET /result` returning the JSON body.
+- Add an example: `POST /scan` returns 409 → `ScannerInvocationError` raised.
+- Add an example: `GET /status` returns an unrecognized state →
+  `ScannerInvocationError` raised.
+- Add an example: poll loop hits `@http_timeout` without `done` →
+  `ScannerInvocationError` raised with "did not finish within" message.
+- Existing `#enable_tcp_keepalive` examples unchanged.
+
+### `spec/terraform/gcp/linux/scan/scan_service_spec.rb`
+
+- Add text-grep assertions that `/status` and `/result` `mount_proc` blocks are
+  present, mirroring the style of the existing flag-presence assertions.
+- Add behavioral coverage: load `scan_service.rb` under the existing WEBrick
+  stub harness, drive the new endpoints directly. Stub `perform_scan` to return
+  a fixed hash. Assert state transitions `idle → running → done` and that
+  `/result` returns the stubbed hash.
+
+### Fixture mirror
+
+- `spec/fixtures/config_testing/user_config_dir/terraform/gcp/linux/scan/scan_service.rb`
+  updated in lockstep.
+- `spec/fixtures/config_testing/user_config_dir/terraform_checksum.txt`
+  regenerated.
+
+## Acceptance Criteria
+
+- [ ] `POST /scan` kicks off the scan in a background thread and returns 202.
+- [ ] `POST /scan` returns 409 when a scan is already running.
+- [ ] `GET /status` returns the current state.
+- [ ] `GET /result` returns 200 with the result when state is terminal, 404 otherwise.
+- [ ] `DaemonClient#scan` posts, polls, and fetches the result with short-lived requests.
+- [ ] Poll interval is configurable via `cem_acpt_scan.daemon.poll_interval` (default 10 s).
+- [ ] TCP keepalive remains enabled on every `DaemonClient#get` / `#post` call.
+- [ ] Existing `daemon_client_spec.rb` examples pass after update.
+- [ ] New unit tests for the async client flow pass.
+- [ ] New behavioral tests for `/status` and `/result` pass.
+- [ ] Long scans (15+ minutes) no longer fail with `ECONNRESET` or `ENOTCONN`.
+
+## Files Touched
+
+- `lib/cem_acpt/scan/daemon_client.rb` — async `scan` flow, new private `post`
+  helper, keepalive retained.
+- `lib/terraform/gcp/linux/scan/scan_service.rb` — `POST /scan` semantics,
+  `/status` and `/result` endpoints, module-level state + mutex.
+- `lib/cem_acpt/config/cem_acpt_scan.rb` — `poll_interval` default under
+  `cem_acpt_scan.daemon`.
+- `spec/fixtures/config_testing/user_config_dir/terraform/gcp/linux/scan/scan_service.rb` — fixture mirror update.
+- `spec/fixtures/config_testing/user_config_dir/terraform_checksum.txt` — checksum update.
+- `spec/cem_acpt/scan/daemon_client_spec.rb` — async-flow tests.
+- `spec/terraform/gcp/linux/scan/scan_service_spec.rb` — `/status` and `/result` tests.
+- `specifications/CEM-6799.md` — this file.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cem_acpt
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.12.2
 platform: ruby
 authors:
 - puppetlabs
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-10 00:00:00.000000000 Z
+date: 2026-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-http
@@ -349,6 +349,7 @@ files:
 - specifications/CEM-6762.md
 - specifications/CEM-6765.md
 - specifications/CEM-6798.md
+- specifications/CEM-6799.md
 homepage: https://github.com/puppetlabs/cem_acpt
 licenses:
 - proprietary