Skip to content

feat: enhance documentation with security and operations guidelines#966

Merged
cfc4n merged 1 commit intomasterfrom
feat/v2-security
Mar 28, 2026
Merged

feat: enhance documentation with security and operations guidelines#966
cfc4n merged 1 commit intomasterfrom
feat/v2-security

Conversation

@cfc4n
Copy link
Copy Markdown
Member

@cfc4n cfc4n commented Mar 28, 2026

This pull request updates the documentation for both the English (README.md) and Chinese (README-zh_Hans.md) readme files, as well as the PR agent profile, to improve clarity, enhance security guidance, and provide more comprehensive operational and contribution instructions. The changes focus on making privilege requirements clearer, adding security best practices, improving output examples, and refining the PR agent's workflow and constraints.

Key changes include:

Security and Privilege Guidance

  • Clearly state that running eCapture requires either root privileges or specific Linux capabilities, and link to a new "Minimum Privileges Guide" for more secure deployments. This is reflected in both readme files and the Docker usage instructions. [1] [2] [3] [4]

  • Add explicit security warnings about using --privileged=true with Docker, recommending the use of specific capabilities instead, and link to detailed documentation for secure container deployment. [1] [2]

  • Introduce a new "Security & Operations" (English) / "安全与运维" (Chinese) section in the table of contents and main body, with links to security policy, privilege guides, detection/defense, performance benchmarks, and release verification. [1] [2] [3]

Output and Usage Documentation

  • Streamline and clarify the output examples for both plaintext and pcapng capture modes, referencing a new docs/example-outputs.md for complete outputs, and removing overly verbose logs from the main readme. [1] [2] [3]

  • Add notes and references for using and interpreting output files, and highlight the importance of using provided scripts and tools for e2e testing. [1] [2]

PR Agent Profile and Contribution Process

  • Major rewrite and expansion of the PR agent profile:
    • Add detailed repository structure, branch policy, Go module/version requirements, and build system conventions.
    • Provide a step-by-step checklist for adding new OpenSSL version support, covering kernel source, build targets, userland mapping, and testing.
    • Refine software testing requirements for Go and C/eBPF code, including CI requirements and e2e script expectations.
    • Clarify forbidden actions and strict constraints for the agent, especially regarding compatibility, release, and documentation files. [1] [2]
    • Standardize PR template structure and naming conventions, encouraging English usage and clear change breakdowns.
    • Add and clarify security and conservative change principles.

General Improvements

  • Improve table of contents and navigation in both readme files for easier access to security and operational topics. [1] [2]
  • Minor formatting and wording improvements throughout for clarity and consistency. [1] [2]

These changes collectively improve the project's documentation quality, security posture, and contributor guidance.


References: [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12]

Copilot AI review requested due to automatic review settings March 28, 2026 13:06
@dosubot dosubot bot added size:XXL This PR changes 1000+ lines, ignoring generated files. documentation Improvements or additions to documentation labels Mar 28, 2026
@github-actions
Copy link
Copy Markdown

🔧 Debug Build Complete (PR #966)

📦 Download Links:

⏰ Files will be retained for 7 days, please download and test promptly.


This build includes debug binaries for: android/linux (arm64/amd64)

Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR expands and reorganizes project documentation to better cover security/least-privilege operation, operational guidance (performance + release integrity), and contributor/agent workflow expectations across both English and Chinese entrypoints.

Changes:

  • Add new security/operations documentation (minimum privileges, defense/detection, performance benchmarks, release verification) and link it from docs index + READMEs.
  • Update README.md and README-zh_Hans.md to clarify privilege requirements and streamline output examples by linking to a dedicated examples document.
  • Rewrite/expand the PR agent profile and formalize security/CI/testing expectations; refresh SECURITY.md policy content.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 8 comments.

Show a summary per file
File Description
docs/release-verification.md Adds a guide for verifying release artifacts and Docker images
docs/performance-benchmarks.md Adds benchmark methodology + expected overhead guidance
docs/minimum-privileges.md Documents least-privilege capability setups (sudo/setcap/Docker)
docs/example-outputs.md Centralizes verbose example outputs referenced by READMEs
docs/defense-detection.md Adds detection/defense guidance for eBPF-based capture tools
docs/README.md Links new security/ops docs and example outputs from the docs index
SECURITY.md Replaces template with supported versions + vuln reporting process
README.md Clarifies privilege needs, adds Security & Operations section, trims logs
README-zh_Hans.md Chinese equivalent of README security/ops and output simplification updates
.github/agents/pr-agent.md Expanded agent profile with repo structure, constraints, CI/testing expectations

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@github-actions
Copy link
Copy Markdown

✅ E2E Test Results: PASSED

Test Run: #23685857872

Tests Executed:

  • TLS/OpenSSL Module (curl → github.com)
  • GnuTLS Module (wget/curl → github.com)
  • GoTLS Module (Go client → github.com)
  • ecaptureQ Module (WebSocket event streaming)

✅ All e2e tests passed successfully! The TLS capture functionality is working correctly.


Automated e2e test results for commit 0a015f0

@cfc4n cfc4n merged commit 824655c into master Mar 28, 2026
15 of 16 checks passed
@cfc4n cfc4n deleted the feat/v2-security branch March 28, 2026 13:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size:XXL This PR changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants