If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mizzy/serverspec shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 16 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ Concentrated ownership — top contributor handles 69% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mizzy/serverspec repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mizzy/serverspec.

What it runs against: a local clone of mizzy/serverspec — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mizzy/serverspec | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 410 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mizzy/serverspec. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mizzy/serverspec.git
#   cd serverspec
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mizzy/serverspec and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mizzy/serverspec(\\.git)?\\b" \\
  && ok "origin remote is mizzy/serverspec" \\
  || miss "origin remote is not mizzy/serverspec (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/serverspec.rb" \\
  && ok "lib/serverspec.rb" \\
  || miss "missing critical file: lib/serverspec.rb"
test -f "lib/serverspec/type/base.rb" \\
  && ok "lib/serverspec/type/base.rb" \\
  || miss "missing critical file: lib/serverspec/type/base.rb"
test -f "lib/serverspec/matcher.rb" \\
  && ok "lib/serverspec/matcher.rb" \\
  || miss "missing critical file: lib/serverspec/matcher.rb"
test -f "lib/serverspec/commands/base.rb" \\
  && ok "lib/serverspec/commands/base.rb" \\
  || miss "missing critical file: lib/serverspec/commands/base.rb"
test -f "lib/serverspec/subject.rb" \\
  && ok "lib/serverspec/subject.rb" \\
  || miss "missing critical file: lib/serverspec/subject.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 410 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~380d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mizzy/serverspec"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Serverspec is an RSpec-based testing framework that validates server infrastructure state by running assertions against a live server's properties—packages, services, ports, files, users, etc.—regardless of whether it was configured with Puppet, Chef, Ansible, CFEngine, Itamae, or manually. It acts as a post-deployment verification layer, catching configuration drift and misconfigurations by querying the actual server state rather than testing configuration code. Modular matcher-command architecture: lib/serverspec/type/ defines resource types (package.rb, service.rb, port.rb, file.rb, etc.), lib/serverspec/matcher/ contains RSpec matchers (be_installed.rb, be_running.rb, be_listening.rb), lib/serverspec/commands/base.rb abstracts OS-specific command execution, and lib/serverspec/helper/ provides test setup utilities. bin/serverspec-init bootstraps new test suites.

Infrastructure engineers and DevOps practitioners who use configuration management tools (Puppet, Chef, Ansible) and need to validate that servers are actually configured correctly in production. They write RSpec tests in lib/serverspec/type/ and lib/serverspec/matcher/ to assert on file permissions, running services, installed packages, listening ports, and system state.

Production-ready but showing age. The repo has 138,080 lines of Ruby across a mature matcher and type system (.github/workflows/ci.yml indicates active CI), but recent commit frequency is not visible in the provided data. The project accepts PRs only and has disabled issues (per README), suggesting stable maintenance rather than active feature development. Travis CI and AppVeyor configs present indicate professional testing infrastructure.

Single-maintainer risk is real (mizzy/serverspec implies single owner), and the README explicitly states 'I accept pull requests only and disable issues', limiting community engagement channels. No dependency list visible in provided data, but a 138KB Ruby codebase with no node_modules suggests minimal external dependencies—a strength. However, the project's age and apparent maintenance-by-PRs-only model means critical bugs may have slow turnaround.

No recent PR or milestone data visible in provided file list, but .github/workflows/ci.yml and .github/workflows/stale.yaml suggest active CI automation. The stale.yaml workflow indicates an automated bot manages stale issues—consistent with the PR-only policy.

git clone https://github.com/mizzy/serverspec.git
cd serverspec
bundle install
bundle exec rake

The Rakefile is the entry point; 'bundle exec rake' is required instead of plain 'rspec' (per README).

Daily commands:

bundle exec rake

This runs the full test suite (gems/RSpec defined in Gemfile). For linting/guard: bundle exec guard (Guardfile present).

• lib/serverspec.rb — Main entry point that loads all core Serverspec modules and establishes the public API surface.
• lib/serverspec/type/base.rb — Abstract base class for all resource types; every matcher and command depends on this foundation.
• lib/serverspec/matcher.rb — Core matcher infrastructure that RSpec tests use to assert server state; defines all matcher patterns.
• lib/serverspec/commands/base.rb — Base command executor that abstracts OS-specific command invocation across Linux, Windows, BSD, and AIX.
• lib/serverspec/subject.rb — Sets up RSpec subject DSL, allowing test syntax like describe service('nginx') { ... }.
• lib/serverspec/helper.rb — RSpec helper integration point that loads backend backends and configures test environment.
• serverspec.gemspec — Gem metadata and dependencies; required for understanding build artifacts and external contracts.

Add a New Server Resource Type (e.g., Docker, Kubernetes)

1. Create a new type class inheriting from lib/serverspec/type/base.rb (lib/serverspec/type/my_resource.rb)
2. Implement resource_type class method and define state-checking methods (lib/serverspec/type/my_resource.rb)
3. Create matchers (e.g., be_foo) in lib/serverspec/matcher/ directory (lib/serverspec/matcher/be_foo.rb)
4. Add test specs to spec/type/{os}/ directories (e.g., spec/type/linux/my_resource_spec.rb) (spec/type/linux/my_resource_spec.rb)
5. Load your type in lib/serverspec.rb so it becomes available in tests (lib/serverspec.rb)

Add Support for a New Operating System or Backend

1. Create OS-specific command implementations by subclassing lib/serverspec/commands/base.rb (lib/serverspec/commands/my_os.rb)
2. Override command methods in existing types to handle OS-specific variations (lib/serverspec/type/service.rb)
3. Add test specs in a new OS directory (e.g., spec/type/my_os/) (spec/type/my_os/service_spec.rb)
4. Register the new backend in lib/serverspec/helper.rb (lib/serverspec/helper.rb)

Add a New Matcher (Assertion Style)

1. Create matcher file in lib/serverspec/matcher/ (lib/serverspec/matcher/be_my_condition.rb)
2. Inherit from lib/serverspec/matcher.rb base class and implement match/failure_message (lib/serverspec/matcher/be_my_condition.rb)
3. Reference the type method that performs the underlying check (lib/serverspec/type/base.rb)
4. Add unit tests for the new matcher (spec/type/{os}/service_spec.rb)

• RSpec — Provides familiar BDD syntax (describe/it/expect) for server testing; allows reusing existing Ruby testing ecosystem.
• Ruby — Dominant infrastructure-as-code language (Puppet, Chef); enables easy integration with provisioning tools and allows dynamic type/matcher definitions.
• SSH/WinRM/Local execution — Provides agnostic backend abstraction allowing tests to run against any server accessible via standard protocols without agent installation.
• Command-based assertions — Avoids parsing /proc, sysfs, or binary APIs; instead invokes standard OS utilities (systemctl, dpkg, netstat) making tests portable across OS versions.

• Command execution + parsing vs. direct API inspection

  • Why: Simplicity and portability across OS versions and variants.
  • Consequence: Slower than direct file/API reads; depends on command-line tools being installed and having consistent output format.

• Type/Matcher separation vs. monolithic assertion classes

  • Why: Allows reuse of type state logic across multiple matchers; cleaner DSL.
  • Consequence: Requires navigating multiple files per feature; more indirection at runtime.

• Backend abstraction (SSH/WinRM/local) vs. platform-specific clients

  • Why: Single test suite can target heterogeneous infrastructure without rewriting tests.
  • Consequence: Backend implementations are thin wrappers; advanced features of cloud APIs are not exposed.

• Per-OS command overrides in type classes vs. separate OS modules

  • Why: Keeps type definition in one place; easier to compare behavior across OSes.
  • Consequence: Type classes grow with conditional logic; can be hard to find which OS path is taken.

• Does not manage infrastructure state (no provisioning/apply); read-only validation only.
• Does not provide configuration management (no enforce desired state); only asserts current state.
• Does not include authentication or credential management; relies on existing SSH keys or WinRM trust setup.
• Not a real-time monitoring tool; tests are ad-hoc/scheduled, not continuous.
• Does not provide a central dashboard or reporting UI; outputs only to RSpec formatters.

Critical: 'bundle exec rake' is mandatory; plain 'rspec' will fail (README warning). Backend selection is implicit via spec/spec_helper.rb—must set Serverspec.set_property before tests run, or a default backend (likely local) is used. OS-specific commands in lib/serverspec/commands/ are tightly coupled to shell command output parsing; changes to system tools (e.g., 'service' vs 'systemctl') require command class updates. No built-in documentation generation; matcher behavior is defined only in test fixtures, making onboarding to new matchers difficult.

• RSpec Custom Matchers — Serverspec's entire API is built on RSpec matchers (be_installed, be_running, contain); understanding how RSpec matchers work (match clause, failure messages) is essential to reading lib/serverspec/matcher/
• Command Abstraction / Backend Pattern — lib/serverspec/commands/base.rb implements a command abstraction layer that maps Serverspec checks to OS-specific shell commands; this pattern lets Serverspec work on Linux, BSD, Windows without duplicating matcher logic
• Subject / Resource Type Pattern — lib/serverspec/type/base.rb and lib/serverspec/subject.rb implement a resource-type pattern where 'package("nginx")' creates a queryable object whose state is fetched on demand via commands; understanding this pattern is key to extending Serverspec
• Server Idempotence Testing — Serverspec is the test layer of infrastructure idempotence: after running Puppet/Chef/Ansible, Serverspec verifies the server reached the desired state; this is a core DevOps pattern for catching configuration drift
• Shell Command Output Parsing — lib/serverspec/commands/ classes parse shell command outputs (dpkg, rpm, systemctl, etc.) to extract state; understanding regex-based parsing and OS command output format is critical for debugging test failures and adding new commands
• Post-Deployment Infrastructure Validation — Serverspec is one of the few tools that validates infrastructure after deployment, not before; this catch-all-errors-in-production philosophy contrasts with pre-flight validation and is essential for reliability in heterogeneous environments

• puppetlabs/puppet — Puppet is a primary configuration management backend that Serverspec validates; understanding Puppet resources helps write better Serverspec assertions
• chef/chef — Chef is another primary CM backend Serverspec validates; Chef recipes and resources have semantic overlap with Serverspec resource types
• mizzy/specinfra — Specinfra is the underlying command execution library that Serverspec depends on; Specinfra abstracts OS-specific command invocation and output parsing
• rspec/rspec — RSpec is the testing DSL foundation; Serverspec matchers (be_installed, be_running) are RSpec custom matchers built on RSpec's expectation API
• ansible/ansible — Ansible is a supported CM backend; Serverspec is often used post-Ansible to verify playbook deployments matched desired state

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for lib/serverspec/type/*.rb resource types

The repo has 40+ resource type files (file.rb, package.rb, service.rb, docker_container.rb, etc.) but lacks dedicated unit test coverage for the type implementations. Currently, tests rely on integration testing via bundle exec rake. Adding unit tests would catch regressions early, enable faster development cycles, and document expected behavior of each resource type's validation logic.

• [ ] Create spec/serverspec/type/ directory structure mirroring lib/serverspec/type/
• [ ] Add unit tests for lib/serverspec/type/base.rb covering initialization, predicate methods, and command execution
• [ ] Add unit tests for at least 5 high-value types: file.rb, command.rb, docker_container.rb, linux_kernel_parameter.rb, and iptables.rb
• [ ] Ensure tests cover both happy path and error conditions
• [ ] Update Rakefile to run spec/ tests alongside existing integration tests

Add GitHub Actions workflow for Windows support validation

The repo has WINDOWS_SUPPORT.md and appveyor.yml indicating Windows is a supported platform, but the main CI workflow (.github/workflows/ci.yml) likely only tests Linux. Adding a dedicated Windows validation workflow ensures IIS-specific types (iis_app_pool.rb, iis_website.rb) and Windows matchers remain functional across updates.

• [ ] Review current .github/workflows/ci.yml to identify what's already tested on Windows
• [ ] Create .github/workflows/windows-ci.yml using windows-latest runner
• [ ] Test Windows-specific types: iis_app_pool.rb, iis_website.rb, and ipfilter.rb
• [ ] Add matrix strategy to test against multiple Ruby versions on Windows
• [ ] Reference WINDOWS_SUPPORT.md in workflow documentation

Extract duplicate command abstraction logic from lib/serverspec/commands/base.rb into helper mixins

Multiple resource type files (iptables.rb, ip6tables.rb, ipfilter.rb, ipnat.rb, linux_audit_system.rb) likely contain similar command execution and parsing patterns. Creating reusable mixins for common patterns (parsing key=value output, filtering by field, regex-based validation) would reduce duplication, improve maintainability, and make it easier for contributors to add new resource types.

• [ ] Audit lib/serverspec/type/*.rb files to identify 3+ shared command patterns (e.g., filtering by field, parsing delimited output)
• [ ] Create lib/serverspec/type/mixins/ directory with focused concern modules: parseable.rb, filterable.rb, etc.
• [ ] Refactor 5 similar types (iptables.rb, ip6tables.rb, ipnat.rb, ipfilter.rb, kernel_module.rb) to use the new mixins
• [ ] Add unit tests for each mixin to prevent regression
• [ ] Update contributing guidelines to document when to use mixins for new types

• Add a new matcher for systemd timer state verification (e.g., 'be_active_timer') in lib/serverspec/matcher/be_active_timer.rb, following the pattern of be_enabled.rb and be_running.rb, with corresponding command implementations.
• Write integration tests for lib/serverspec/type/cgroup.rb (cgroup resource type exists but may lack test coverage); add spec/ fixtures validating cgroup CPU/memory limit assertions.
• Implement a 'contain_regex' matcher in lib/serverspec/matcher/contain_regex.rb as a sibling to contain.rb but with regex pattern support for file content validation, testing against sample /etc/config files.

Serverspec is a testing framework with moderate security concerns. The primary risks stem from: (1) potential command injection vulnerabilities in the extensive type/command execution system, (2) lack of visible dependency vulnerability management, (3) unclear default security configurations for remote server connections. The codebase appears well-structured with good separation of concerns, but requires detailed code review of command execution patterns and authentication mechanisms. Critical recommendations include auditing all shell command execution, implementing automated dependency scanning, and ensuring secure defaults for all server communication channels.

• High · Command Injection Risk in Type/Matcher Classes — lib/serverspec/type/ and lib/serverspec/commands/. The codebase contains numerous type and matcher classes that execute system commands (e.g., lib/serverspec/type/*.rb files). Without proper analysis of all command execution patterns, there is a risk of command injection if user input is not properly sanitized before being passed to shell commands. Fix: Audit all command execution code to ensure proper input validation and sanitization. Use parameterized command execution instead of string concatenation. Prefer using Ruby's require 'open3' with array-based command arguments rather than shell interpolation.
• Medium · Missing Dependency Management Visibility — Gemfile (content not provided). No Gemfile.lock or dependency manifest content was provided, making it impossible to assess if the project uses outdated or vulnerable gem dependencies. This is critical for a testing framework that may be used in production environments. Fix: Ensure Gemfile.lock is committed to version control and regularly run bundle audit to check for known vulnerabilities in dependencies. Implement automated dependency scanning in CI/CD pipeline.
• Medium · Potential Insecure Default Configurations — lib/serverspec/setup.rb, bin/serverspec-init. The serverspec-init script and setup files may configure default security settings. Without reviewing the actual content of lib/serverspec/setup.rb and bin/serverspec-init, it's unclear if secure defaults are enforced for SSH connections, certificate validation, and authentication mechanisms. Fix: Review and ensure that: (1) SSH connections require certificate validation by default, (2) Default credentials are not hardcoded, (3) SSL/TLS verification is enabled by default, (4) Secure communication channels are enforced.
• Medium · Test Framework Security Exposure — lib/serverspec/type/ (all type classes). Serverspec is designed to test server configurations across multiple infrastructure platforms (CFEngine, Puppet, Chef, Ansible, etc.). If the test framework itself has vulnerabilities, it could be exploited to gain access to servers being tested. Fix: Implement security testing in CI/CD to validate: (1) No hardcoded credentials in test files, (2) Secure handling of authentication tokens, (3) Proper separation of test data from production credentials.
• Low · Missing Security Headers in CI Configuration — .travis.yml, appveyor.yml, .github/workflows/ci.yml. CI configuration files (.travis.yml, appveyor.yml, .github/workflows/) do not show explicit security scanning steps like dependency checking or static code analysis. Fix: Add security scanning steps to CI/CD: (1) bundle audit for gem vulnerabilities, (2) Brakeman for Rails security, (3) RuboCop with security plugins, (4) Dependabot or similar for dependency monitoring.
• Low · No Evidence of Input Validation Framework — lib/serverspec/type/ and lib/serverspec/matcher/. Based on the file structure, there is no apparent centralized input validation module. Individual type/matcher classes may implement validation inconsistently. Fix: Implement a centralized input validation utility that all type and matcher classes use. Validate all parameters, especially those used in command construction.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.