Skip to content

PingCastle 4.0 documentation - #1270

Open
JoeDibley wants to merge 27 commits into
devfrom
JD/PingCastle-4-0
Open

PingCastle 4.0 documentation#1270
JoeDibley wants to merge 27 commits into
devfrom
JD/PingCastle-4-0

Conversation

@JoeDibley

@JoeDibley JoeDibley commented Jul 28, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • New PingCastle 4.0 documentation: install/architecture, Entra scanning, scheduler rewrite, audit log, split settings pages
  • Adds screenshots for the new 4.0 pages (audit log, Entra tenant wizard, scheduler, settings tabs)

Test plan

  • Vale/Dale clean on changed files
  • Build succeeds with no broken links
  • Spot-check screenshots render correctly in each doc

Closes #1278

JoeDibley and others added 12 commits July 26, 2026 08:31
Adds Enterprise/Pro/Standard docs for PingCastle 4.0, registers the
version in products.js as the new default, and removes the unsupported
Azure hosting section from the Enterprise install guide now that
deployment is Windows-only via the installer.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
…r labels

CloudAPI microservice and PingCastleSchedulerService replace the old
Windows Task Scheduler model; docs and diagrams updated to match.
Manual/Linux install and appsettings.json sections removed since
Enterprise 4.0 is Windows Server + IIS + SQL Server only. Logging
docs rewritten for the new web portal-based configuration.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
…NET version refs

Expand quick install Step 2 in both tabs with the full wizard walkthrough (prerequisite check, license, install type, app pool identity, auth methods, HTTPS, email) and post-install gotchas; correct ASP.NET 8.0 references to 10.0.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Break the monolithic install page into architecture, requirements,
auth setup, email setup, license, post-install, settings, and
troubleshooting pages; update sidebar and cross-links accordingly.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Note deleted objects lack links, and list the two audit-log settings
under Data Retention instead of just linking out.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Break out action plans, application, data retention, Entra scanner,
and scanning/scheduling settings into dedicated pages; update related
docs and sidebar links.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Link text still said "Settings: X" and "Enterprise Scheduling" from
before the settings pages were split and renamed; update references
to match the current page titles, and fill in the Entra tenant
connection steps.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
… clarify 3.5-only migration

Config migration content belongs with settings docs, not the upgrade guide; also flags the exe.config migration as a one-time 3.5 event.
…/Graph conflict

Setup-EntraScannerApp.ps1 had several runtime bugs found while testing against
a live tenant: wrong Add-RoleGroupMember param for EXO's cmdlet, missing
Get-MgDirectoryRole module import, non-idempotent app role grants on reuse,
EXO replication lag on the new service principal, and an Azure.Core version
clash between Az.Resources and Microsoft.Graph in the same process. Also
exports the generated self-signed cert as a .pfx.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
…duler, and settings pages

Captures 18 cropped screenshots (content panels only, no nav/sidebar chrome)
for new PingCastle 4.0 pages and replaces their TODO markers.
@JoeDibley
JoeDibley requested a review from a team as a code owner July 28, 2026 01:20
@github-actions

Copy link
Copy Markdown
Contributor

⚠️ Broken Anchor Links

1 broken anchor link(s) found — these will cause the build to fail.

  docs/pingcastle/4.0/enterprisearchitecture.md:75
    - Scheduled scans of local and trusted domains are handled by `PingCastleSchedulerService` (see [Scheduling scans](enterprisepostinstall.md#scheduling-scans))
    #scheduling-scans not found in docs/pingcastle/4.0/enterprisepostinstall.md
    Available: #post-installation-configuration-for-pingcastle-enterprise · #common-steps · #configuring-https · #iis-maximum-upload-configuration · #manual-report-import-size-limit · #automatic-forest-exploration-setup · #manual-execution · #automated-execution-for-agent-setup · #scheduling-your-first-scan · #scheduling-an-active-directory-scan · #scheduling-an-entra-scan · #initial-startup · #initial-configuration · #entities · #encryption · #bulk-import-of-existing-reports · #report-archiving-configuration · #configuration · #how-archiving-works · #what-gets-archived · #pingcastle-agent-deployment · #synchronization-feature · #configuration · #synchronization-patterns · #synchronization-patterns-at-import-time · #connection-tests

Auto-Fix Summary

2 issues fixed, 10 skipped across 26 files

Category Fixes
Dale: positional-references 2
Skipped (needs manual review) Reason
docs/pingcastle/4.0/enterpriseemailsetup.md:45 — Netwrix.TypeVsEnter 'type' is used as a noun ('the credential type the app registration uses'), not the verb instructing a user to supply text. False positive.
docs/pingcastle/4.0/enterpriseentrascan.md:118 — Netwrix.FirstPerson 'my' is part of the literal, bolded Entra admin center menu label 'APIs my organization uses'. Rewriting would misname a UI element and break accuracy.
docs/pingcastle/4.0/enterpriseentrascan.md:134 — Netwrix.FirstPerson 'my' is part of the literal, bolded Entra admin center menu label 'APIs my organization uses'. Rewriting would misname a UI element and break accuracy.
docs/pingcastle/4.0/enterprisesettings-entrascanner.md:13 — Netwrix.OxfordComma 'request and client timeouts' is a single compound list item, not a three-item series. The list already has its Oxford comma before 'and circuit breaker thresholds'. Adding a comma would be incorrect.
docs/pingcastle/4.0/enterprisetroubleshooting.md:177 — Netwrix.OxfordComma 'Enterprise and CloudAPI' is a two-item pairing, not a series of three, so no Oxford comma applies. False positive.
docs/pingcastle/4.0/enterpriseemailsetup.md:615 — Dale: exclamatory-sentences Exclamation is inside a PowerShell Write-Host string within a code block, not prose; changing it would alter the script output.
docs/pingcastle/4.0/enterpriseemailsetup.md:622 — Dale: exclamatory-sentences Exclamation is inside a PowerShell Write-Host string within a code block, not prose; changing it would alter the script output.
docs/pingcastle/4.0/enterpriseuser.md:9 — Dale: xy-slop 'The goal of the tool isn't perfection, but to provide reliable data' uses the negative-positive form, but the contrast is intentional expectation-setting; rewriting would drop meaningful nuance.
docs/pingcastle/4.0/proinstall.md:8 — Dale: xy-slop Same 'goal isn't perfection, but to provide reliable data' framing; the contrast conveys intended scope, so rewriting risks changing meaning.
docs/pingcastle/4.0/prouser.md:11 — Dale: xy-slop Same 'goal ... wasn't to aim for perfection, but to provide reliable data' framing; intentional contrast, skipped to preserve meaning.

Ask @claude on this PR if you'd like an explanation of any fix.

Comment thread docs/pingcastle/4.0/enterpriseauthsetup.md Outdated
Comment thread docs/pingcastle/4.0/index.md Outdated
Comment thread docs/pingcastle/4.0/index.md Outdated
JoeDibley and others added 2 commits July 29, 2026 07:55
…reenshots

Microsoft rebranded Azure AD to Entra ID; update terminology across enterprise/pro
4.0 docs and refresh accompanying screenshots to match current UI.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
@github-actions

Copy link
Copy Markdown
Contributor

⚠️ Broken Anchor Links

1 broken anchor link(s) found — these will cause the build to fail.

  docs/pingcastle/4.0/enterprisearchitecture.md:75
    - `PingCastleSchedulerService` handles scheduled scans of local and trusted domains (see [Scheduling scans](enterprisepostinstall.md#scheduling-scans))
    #scheduling-scans not found in docs/pingcastle/4.0/enterprisepostinstall.md
    Available: #post-installation-configuration-for-pingcastle-enterprise · #common-steps · #configuring-https · #iis-maximum-upload-configuration · #manual-report-import-size-limit · #automatic-forest-exploration-setup · #manual-execution · #automated-execution-for-agent-setup · #scheduling-your-first-scan · #scheduling-an-active-directory-scan · #scheduling-an-entra-scan · #initial-startup · #initial-configuration · #entities · #encryption · #bulk-import-of-existing-reports · #report-archiving-configuration · #configuration · #how-archiving-works · #what-gets-archived · #pingcastle-agent-deployment · #synchronization-feature · #configuration · #synchronization-patterns · #synchronization-patterns-at-import-time · #connection-tests

Auto-Fix Summary

10 issues fixed, 11 skipped across 26 files

Category Fixes
Dale: passive-voice 9
Dale: wordiness 1
Skipped (needs manual review) Reason
docs/pingcastle/4.0/enterpriseemailsetup.md:45 — Netwrix.TypeVsEnter False positive. 'The credential type' uses 'type' as a noun (a category of credential), not as an instruction to type text into a field. Changing to 'enter' would break the sentence.
docs/pingcastle/4.0/enterpriseentrascan.md:118 — Netwrix.FirstPerson False positive. 'APIs my organization uses' is the literal UI menu label in the Entra admin center. Removing 'my' would misrepresent the actual UI string the user must click.
docs/pingcastle/4.0/enterpriseentrascan.md:134 — Netwrix.FirstPerson False positive. 'APIs my organization uses' is the literal UI menu label in the Entra admin center. Removing 'my' would misrepresent the actual UI string the user must click.
docs/pingcastle/4.0/enterprisesettings-entrascanner.md:13 — Netwrix.OxfordComma False positive. 'request and client timeouts' is a compound pair (request timeouts and client timeouts), not a third series item. The list already includes its Oxford comma before 'and circuit breaker thresholds'.
docs/pingcastle/4.0/enterprisetroubleshooting.md:177 — Netwrix.OxfordComma False positive. 'If Entra ID scanning isn't available, Enterprise and CloudAPI aren't integrated correctly' is a conditional clause with a two-item subject ('Enterprise and CloudAPI'), not a three-or-more-item series requiring an Oxford comma.
docs/pingcastle/4.0/enterpriseuser.md:9 — Dale: xy-slop 'The goal of the tool isn't perfection, but to provide reliable data' — rephrasing to positive form would drop the intended 'not perfection' nuance; low confidence the meaning is preserved. Same construction also in proinstall.md:8 and prouser.md:11.
docs/pingcastle/4.0/enterpriselicense.md:8 — Dale: passive-voice 'Domain Controllers aren't counted for licensing purposes, only domains' — active rewrites either reintroduce a negative-positive contrast or shift the emphasis; not confident meaning is preserved.
docs/pingcastle/4.0/enterprisepostinstall.md:337 — Dale: passive-voice 'The Sync button is shown if the sync link is configured AND if the user has permission' — sentence contains multiple stacked passives and a conditional; restructuring risks altering the conditions.
docs/pingcastle/4.0/enterprisepostinstall.md:314 — Dale: passive-voice Synchronization section describes system behavior with dense 'will be recomputed/forwarded' constructions; rewriting the interdependent clauses risks changing technical meaning.
docs/pingcastle/4.0/enterpriseuser.md:235 — Dale: undefined-acronyms 'CMMI methodology' used without expansion, but CMMI is an industry framework rather than a product-specific acronym; not confident the intended expansion is wanted.
docs/pingcastle/4.0/prouser.md:24 — Dale: passive-voice prouser.md and proinstall.md contain dense legacy translated prose with many passive/awkward constructions; isolated fixes would leave surrounding text inconsistent and risk altering meaning.

Ask @claude on this PR if you'd like an explanation of any fix.

@github-actions

Copy link
Copy Markdown
Contributor

⚠️ Broken Anchor Links

1 broken anchor link(s) found — these will cause the build to fail.

  docs/pingcastle/4.0/enterprisearchitecture.md:75
    - `PingCastleSchedulerService` handles scheduled scans of local and trusted domains (see [Scheduling scans](enterprisepostinstall.md#scheduling-scans))
    #scheduling-scans not found in docs/pingcastle/4.0/enterprisepostinstall.md
    Available: #post-installation-configuration-for-pingcastle-enterprise · #common-steps · #configuring-https · #iis-maximum-upload-configuration · #manual-report-import-size-limit · #automatic-forest-exploration-setup · #manual-execution · #automated-execution-for-agent-setup · #scheduling-your-first-scan · #scheduling-an-active-directory-scan · #scheduling-an-entra-scan · #initial-startup · #initial-configuration · #entities · #encryption · #bulk-import-of-existing-reports · #report-archiving-configuration · #configuration · #how-archiving-works · #what-gets-archived · #pingcastle-agent-deployment · #synchronization-feature · #configuration · #synchronization-patterns · #synchronization-patterns-at-import-time · #connection-tests

Auto-Fix Summary

224 issues fixed, 54 skipped across 28 files

Category Fixes
Dale: idioms 6
Dale: misplaced-modifiers 2
Dale: negative-assumptions 1
Dale: passive-voice 193
Dale: positional-references 1
Dale: undefined-acronyms 2
Dale: wordiness 19
Skipped (needs manual review) Reason
docs/pingcastle/4.0/enterpriseemailsetup.md:45 — Netwrix.TypeVsEnter False positive. 'type' is a noun in 'The credential type the app registration uses', not the verb instructing users to enter text. No fix needed.
docs/pingcastle/4.0/enterpriseentrascan.md:118 — Netwrix.FirstPerson False positive. 'APIs my organization uses' is the literal UI tab label in the Entra admin center 'Add a permission' dialog. Rewriting 'my' would misrepresent the actual UI and break accuracy.
docs/pingcastle/4.0/enterpriseentrascan.md:134 — Netwrix.FirstPerson False positive. 'APIs my organization uses' is the literal UI tab label in the Entra admin center 'Add a permission' dialog. Rewriting 'my' would misrepresent the actual UI and break accuracy.
docs/pingcastle/4.0/enterprisesettings-entrascanner.md:13 — Netwrix.OxfordComma False positive. 'request and client timeouts' is a two-item compound (request timeouts and client timeouts), not a three-item series. The surrounding list already includes its Oxford comma before 'and circuit breaker thresholds'.
docs/pingcastle/4.0/enterprisetroubleshooting.md:177 — Netwrix.OxfordComma False positive. 'Enterprise and CloudAPI' is a two-item subject; the comma after 'available' separates the conditional clause from the main clause, not a series of three items.
docs/pingcastle/3.5/enterpriseinstall.md:285 — Dale: undefined-acronyms POC is common and 'proof-of-concept' is spelled out nearby; low confidence
docs/pingcastle/3.5/enterpriseinstall.md:352 — Dale: minimizing-difficulty 'simplest approach' compares configuration methods rather than minimizing task difficulty
docs/pingcastle/3.5/enterpriseinstall.md:457 — Dale: idioms 'middle ground' is widely understood and neutral; low confidence
docs/pingcastle/3.5/enterpriseinstall.md:427 — Dale: passive-voice 'when the solution is installed...and needs to scan' rewrite would break parallel structure and risk meaning change
docs/pingcastle/3.5/enterpriseinstall.md:2389 — Dale: passive-voice 'should be automatically configured' has unclear agent; rewrite risks wrong meaning
docs/pingcastle/3.5/index.md:76 — Dale: passive-voice 'ADWS is installed by default on Windows Server 2008 R2 and later' reads as a stative fact; active rewrite would be awkward
docs/pingcastle/3.5/index.md:355 — Dale: passive-voice 'reports must be transferred over unsecured channels' is a conditional requirement; rewrite risks meaning change
docs/pingcastle/3.5/index.md:450 — Dale: passive-voice 'This is primarily used with PingCastle Enterprise' has a vague subject; no confident active agent
docs/pingcastle/3.5/index.md:653 — Dale: passive-voice 'Release notes are now documented on GitHub' has no clean active agent
docs/pingcastle/3.5/index.md:664 — Dale: passive-voice Passive inside the :::note Security Statement blockquote left unchanged per admonition/blockquote constraint
docs/pingcastle/4.0/index.md:75 — Dale: passive-voice 'ADWS is installed by default on Windows Server 2008 R2 and later' reads as a stative fact; active rewrite would be awkward
docs/pingcastle/4.0/index.md:354 — Dale: passive-voice 'reports must be transferred over unsecured channels' is a conditional requirement; rewrite risks meaning change
docs/pingcastle/4.0/index.md:449 — Dale: passive-voice 'This is primarily used with PingCastle Enterprise' has a vague subject; no confident active agent
docs/pingcastle/4.0/index.md:663 — Dale: passive-voice Passive inside the :::note Security Statement blockquote left unchanged per admonition/blockquote constraint
docs/pingcastle/4.0/enterpriseauditlog.md:14 — Dale: xy-slop 'records one row per changed property, not one row per administrative action' is a legitimate clarifying contrast; rewrite risks meaning
docs/pingcastle/4.0/enterpriseauthsetup.md:20 — Dale: passive-voice 'can be provisioned automatically through JIT provisioning' active rewrite awkward
docs/pingcastle/4.0/enterpriseauthsetup.md:28 — Dale: passive-voice 'is enabled by default' / 'No additional configuration is required' are standard stative phrasing
docs/pingcastle/4.0/enterpriseauthsetup.md:232 — Dale: passive-voice 'must be isolated by a reverse proxy' in a security-critical danger admonition; left to preserve wording
docs/pingcastle/4.0/enterpriseemailsetup.md:200 — Dale: passive-voice 'This should be automatically configured' has no clear agent for active rewrite
docs/pingcastle/4.0/enterpriseinstall.md:46 — Dale: passive-voice 'the license file provided by Netwrix' is a common reduced noun modifier; low value and rewrite risks awkwardness
docs/pingcastle/4.0/enterpriseinstall.md:165 — Dale: passive-voice 'the account used by PingCastle Enterprise' is a reduced relative clause, not a clear full-passive construction
docs/pingcastle/4.0/enterpriseinstall.md:115 — Dale: undefined-acronyms POC used but 'proof-of-concept' is spelled out elsewhere and POC is widely understood; ambiguous
docs/pingcastle/4.0/enterpriseentrascan.md:141 — Dale: xy-slop 'determines Teams authorization, rather than a fixed Graph permission list' is not the classic x-is-not-y-x-is-z pattern; rewrite risks meaning change
docs/pingcastle/4.0/enterpriselicense.md:8 — Dale: passive-voice 'Domain Controllers aren't counted for licensing purposes' active rewrite would require inventing an actor and risk xy-slop
docs/pingcastle/4.0/enterpriselicense.md:9 — Dale: passive-voice 'Licenses are bundled in packs of 10 domains' is a stative fact with no clear actor
docs/pingcastle/4.0/enterprisepostinstall.md:163 — Dale: passive-voice 'Entities are created at Configuration -> Entities' active rewrite would restructure the sentence; skipped conservatively
docs/pingcastle/4.0/enterprisepostinstall.md:173 — Dale: passive-voice 'is marked as insecure' / 'is no longer provided' have ambiguous actor
docs/pingcastle/4.0/enterprisepostinstall.md:301 — Dale: undefined-acronyms FQDN is a widely known networking acronym closely related to DNS, not product-specific
docs/pingcastle/4.0/enterprisepostinstall.md:46 — Dale: minimizing-difficulty 'the simplest approach' is comparative/informative rather than the minimizers 'simply/just/easily'
docs/pingcastle/4.0/enterprisesettings-dataretention.md:12 — Dale: passive-voice 'user rows included in a generated HTML risk report' is a reduced adjective clause; rewrite would be awkward and risk meaning change
docs/pingcastle/4.0/enterprisesettings-entrascanner.md:16 — Dale: undefined-acronyms OTLP appears only as a literal config option value in a parenthetical list; treated like a code/option literal
docs/pingcastle/4.0/enterprisesettings-scim.md:46 — Dale: minimizing-difficulty 'The connector type field is just a label' is a heading; skipped to avoid breaking the generated anchor and per heading-conservatism guidance
docs/pingcastle/4.0/enterprisesettings-scim.md:42 — Dale: passive-voice 'the risk of a stale account being reactivated or otherwise misused' rewrite risks altering meaning
docs/pingcastle/4.0/enterpriseuser.md:9 — Dale: xy-slop 'The goal...isn't perfection, but to provide reliable data' conveys meaningful expectation-setting; direct rewrite risked losing nuance
docs/pingcastle/4.0/enterpriseuser.md:90 — Dale: passive-voice 'what claims have been pushed to PingCastle Enterprise' has ambiguous pushing actor
docs/pingcastle/4.0/enterpriseuser.md:312 — Dale: passive-voice Source sentence is grammatically broken; rewrite risked changing meaning
docs/pingcastle/4.0/enterpriseuser.md:667 — Dale: passive-voice 'a new trust...has been established/deleted/modified' describes external AD state changes with ambiguous actor
docs/pingcastle/4.0/enterpriseuser.md:239 — Dale: passive-voice Terse maturity-measure bullets have ambiguous actor; rewrite risked altering the requirement's meaning
docs/pingcastle/4.0/proinstall.md:8 — Dale: xy-slop 'The goal...isn't perfection, but to provide' rewriting risks altering the intended contrast
docs/pingcastle/4.0/proinstall.md:86 — Dale: passive-voice 'the data...is pushed' / 'may be encrypted' have ambiguous actor
docs/pingcastle/4.0/proinstall.md:232 — Dale: passive-voice 'it will be stripped' / 'user won't be seen' have ambiguous actor
docs/pingcastle/4.0/proinstall.md:269 — Dale: passive-voice Garbled source sentence; skipped to avoid altering meaning
docs/pingcastle/4.0/proinstall.md:397 — Dale: idioms 'take...in account' inside a garbled sentence; skipped
docs/pingcastle/4.0/proinstall.md:518 — Dale: passive-voice 'must be properly escaped' sentence contains delicate literal backslash/quote escapes; skipped
docs/pingcastle/4.0/proinstall.md:631 — Dale: minimizing-difficulty 'The easiest way' is a borderline superlative; skipped to avoid meaning change
docs/pingcastle/4.0/proinstall.md:767 — Dale: passive-voice 'additional logs can be stored' has ambiguous actor
docs/pingcastle/4.0/proupgrade.md:31 — Dale: passive-voice 'ASP.NET must be upgraded' lines appear to be broken table/data rows; skipped to avoid format damage
docs/pingcastle/4.0/prouser.md:24 — Dale: passive-voice 'such protections can be sometimes avoided' has ambiguous actor
docs/pingcastle/4.0/prouser.md:122 — Dale: passive-voice Trust-event 'has been established/deleted/modified' describes descriptive event states with ambiguous actor

Ask @claude on this PR if you'd like an explanation of any fix.

@github-actions

Copy link
Copy Markdown
Contributor

Documentation PR Review

This PR adds the PingCastle 4.0 Enterprise and Pro documentation set (24 new files) and applies sentence-level rewrites to two 3.5 files. The editorial review below covers added lines only. The 3.5 changes (enterpriseinstall.md, index.md) are voice/word-choice rewrites in Vale/Dale territory and are handled by the auto-fix workflow — no additional editorial issues found there.

Editorial Review

docs/pingcastle/3.5/enterpriseinstall.md

  • No issues found.

docs/pingcastle/3.5/index.md

  • No issues found.

docs/pingcastle/4.0/enterprisearchitecture.md

  • Completeness — Line 90: The PingCastle.exe Scanner section lists "standard Active Directory ports (389, 636, 88, 9389, 53)" but omits SMB port 445, which the Active Directory Scanning table below includes. A reader building firewall rules from this inline list would miss a port the product needs. Suggested fix: match the table — "(389, 636, 88, 445, 9389, 53)".
  • Clarity — Line 119: "ADWS" first appears in the LDAP row's Notes ("Fallback when ADWS isn't present") but isn't expanded until the last table row ("Active Directory Web Services"). The abbreviation precedes its definition. Suggested fix: expand on first use — "Fallback when Active Directory Web Services (ADWS) isn't present."

docs/pingcastle/4.0/enterpriseauditlog.md

  • No issues found.

docs/pingcastle/4.0/enterpriseauthsetup.md

  • Structure — Line 11: The intro lists seven authentication methods including "Entra ID Authentication," but the tabbed section provides only six tabs and none is labeled "Entra ID Authentication." A reader scanning the tabs for that method won't find it. The note below does explain it's configured through OpenID Connect, but the list-to-tab mismatch can still send readers hunting for a nonexistent tab. Suggested fix: clarify inline in the list — "Entra ID Authentication (configured through OpenID Connect)."
  • Clarity — Line 359: "CRL" and "OCSP" are used without expansion ("If your environment doesn't have CRL or OCSP revocation endpoints available") and aren't defined earlier. Newer users won't recognize these. Suggested fix: spell out on first use — "Certificate Revocation List (CRL) or Online Certificate Status Protocol (OCSP) revocation endpoints."

docs/pingcastle/4.0/enterpriseemailsetup.md

  • Completeness — Part 1 (Steps 1–4): The manual configuration only creates a client secret, but the document also supports certificate authentication (the "Create and Export Certificate" block produces a .cer, and the Settings UI offers a Certificate mode). A reader who chose certificate auth is never told to upload the certificate's public key to the app registration. Suggested fix: add a Part 1 step for certificate users — e.g., "If you use certificate authentication, go to Certificates & secrets > Certificates > Upload certificate and upload the .cer file you exported, instead of creating a client secret."

docs/pingcastle/4.0/enterpriseentrascan.md

  • Completeness — Lines 35–40: The "To connect a tenant" procedure lists the tenant ID, auth method, and secret/certificate, but never tells the reader to enter the application (client) ID — even though the screenshot caption below shows an "application client ID field." The reader can't complete the wizard from the steps alone. Suggested fix: add a step — "Enter the application (client) ID of the Entra app registration the scanner uses."
  • Completeness — Line 18: "You can download a risk definition, edit its logic, and re-upload it" introduces a capability without saying where in PingCastle Enterprise the reader does this, and there's no cross-reference. Suggested fix: point to the relevant screen — e.g., "...from Configuration > Entra Scan Config > Risk definitions."

docs/pingcastle/4.0/enterpriseinstall.md

  • Clarity — Line 209: In the SQL Authentication tab, the sample connection string includes both User Id=pingcastle;Password=pingcastle and Trusted_Connection=True. Trusted_Connection=True forces Windows integrated authentication and ignores the SQL user/password, contradicting the tab's purpose. Suggested fix: remove Trusted_Connection=True (or set it False) in the SQL Authentication example; keep it only in the Windows Authentication example.
  • Structure — Lines 27–29: #### Installation Steps sits at the same heading level as the individual #### Step 1, #### Step 2 headings that follow, so it reads as a sibling rather than a parent, and the TOC won't nest the steps under it (same for #### Prerequisites). Suggested fix: promote the section headings (Prerequisites, Installation Steps) to ### so the #### Step N headings nest under them, or remove the standalone "Installation Steps" label.

docs/pingcastle/4.0/enterpriselicense.md

  • No issues found.

docs/pingcastle/4.0/enterprisepostinstall.md

  • Completeness — Lines 265–273: The "PingCastle Enterprise high trust" and "PingCastle Enterprise low trust" subsections read as unfinished placeholders — the bold label is followed by body text that repeats it, and "low trust" is followed only by "PingCastle audits." The high-trust/low-trust concept is central to the Synchronization feature but is never explained. Suggested fix: replace the placeholder lines with real descriptions of what each role does in the security-zone model.
  • Completeness/Consistency — Lines 237–239: The "Scheduling" subsection tells the reader to "Configure Windows Task Scheduler ... to run scans weekly." This contradicts enterprisescheduling.md, which states 4.0 replaces Task Scheduler-based scanning with the web-managed PingCastleSchedulerService. Suggested fix: reconcile with the 4.0 scheduler model, or scope this clearly as the alternative/legacy manual-agent method and cross-link to enterprisescheduling.md.
  • Completeness — Line 159: "For more details see the user documentation." is a dangling reference with no link or title. Suggested fix: link the specific document — e.g., "See the PingCastle Enterprise user guide for more details."

docs/pingcastle/4.0/enterpriserequirements.md

  • No issues found.

docs/pingcastle/4.0/enterprisescheduling.md

  • Clarity — Line 16: "A credential profile bundles the information PingCastle Enterprise needs to run an unattended scan: an Agent, an API key, and the configuration for a specific scan type." The term "Agent" (a specific PingCastle concept) is used here and throughout but never defined. A reader arriving directly at this standalone page won't know what an Agent is or how one is created. Suggested fix: add a one-sentence definition on first use, or cross-link to the document that describes Agents.

docs/pingcastle/4.0/enterprisesettings.md

  • No issues found.

docs/pingcastle/4.0/enterprisesettings-actionplans.md

  • No issues found.

docs/pingcastle/4.0/enterprisesettings-application.md

  • No issues found.

docs/pingcastle/4.0/enterprisesettings-dataretention.md

  • No issues found.

docs/pingcastle/4.0/enterprisesettings-entrascanner.md

  • Structure — Line 2: sidebar_position: 13 collides with enterprisesettings-dataretention.md, which is also sidebar_position: 13. Two siblings sharing a position makes the sidebar order between them nondeterministic. Suggested fix: give one a distinct position (e.g., a value not already used in the 9–15 sequence).
  • Completeness — Lines 6–16: Unlike every other Settings page in this set, this page never states whether these settings are editable here or read-only, nor when changes take effect (the sibling pages include the "Changes ... take effect within about 30 seconds" line). Since line 6 only says the section "syncs its settings from the Entra Scanner microservice," a reader can't tell whether they configure these values here or elsewhere. Suggested fix: add a sentence — e.g., "These settings are read-only here and are configured in the Entra Scanner microservice."

docs/pingcastle/4.0/enterprisesettings-logging.md

  • Clarity — Line 38: "Entra Scanner microservice (CloudAPI) logs" introduces the identifier "CloudAPI" that appears nowhere else in this document, leaving a reader no way to connect it to the Entra Scanner. Suggested fix: drop the parenthetical or tie it in — "Entra Scanner microservice logs," or note that CloudAPI is the microservice's internal name.

docs/pingcastle/4.0/enterprisesettings-scanningscheduling.md

  • No issues found.

docs/pingcastle/4.0/enterprisesettings-scim.md

  • Completeness — Line 6: "A few settings require a restart, which PingCastle Enterprise schedules automatically" tells the reader some settings trigger a restart but never identifies which, so they can't anticipate when saving causes one. Suggested fix: name the settings that require a restart, or mark those specific fields in the sections below.

docs/pingcastle/4.0/enterprisesettings-security.md

  • No issues found.

docs/pingcastle/4.0/enterprisetroubleshooting.md

  • Clarity — Line 21: The note "The PingCastleSchedulerService doesn't use Serilog" references Serilog before it's introduced (it's explained later, at "...use Serilog for logging"). Suggested fix: introduce Serilog in the intro paragraph of "Viewing Application Logs and Errors," or move this note below the Log Files subsection where Serilog is defined.
  • Completeness — Line 85: "The last error relates to the missing KB KB2533623." states the cause but not the resolution, and "KB KB2533623" duplicates the "KB" label. Suggested fix: state the action — "The last error is caused by the missing Windows update KB2533623. Install KB2533623 to resolve it."

docs/pingcastle/4.0/enterpriseupgrade.md

  • Completeness — Line 47: "If a setting is missing or incorrect, check the backed-up file in config-backups/..." references a backup directory whose existence and location were never established earlier in the document. Suggested fix: state in the upgrade/migration section that the installer backs up the previous appsettings.production.json to config-backups/, including where that directory is located.

docs/pingcastle/4.0/enterpriseuser.md

  • Completeness — Lines 384–403: The "Privileged accounts," "Trusts," and "Anomalies" subsections each end with the identical sentence "This section covers how the Stale Objects component influences your overall Risk Score..." — a copy-paste error from the "Staled Objects" subsection. A reader on Trusts or Anomalies is told the text is about Stale Objects. Suggested fix: replace "the Stale Objects component" in each with the actual component ("the Privileged Accounts component," "the Trusts component," "the Anomalies component").
  • Clarity — Lines 380, 387, 393, 400: Each Advanced component is described as "one of the 4 main components of the Risk Score (the 2.2 area)." "The 2.2 area" is never defined. Suggested fix: explain the numbering or drop the parenthetical — e.g., "one of the four components that make up the Risk Score."
  • Structure — Lines 821–851: The "Navigation" table for Manage Your Account was flattened into wrapped plain text during conversion (e.g., "Profile Manage basic View username, Update All users / account email..."), losing the column relationships and becoming unreadable. Suggested fix: restore it as a proper Markdown table with Feature / Description / Actions / Availability columns.
  • Clarity — Lines 112–118: Under "Main pages overview," four view labels appear as a bare mix of bold and plain lines ("Configuration", "Account / User management", "Technical view", "Management view") with no connecting sentence — they read as orphaned image captions. Suggested fix: introduce them as captions tied to their images, or fold them into the preceding bulleted list.
  • Structure — Lines 148, 243, 258, 270, 285, 416, 535, 637, 725, 770: Orphaned auto-numbered list items ("1. All users can access...", "6. Pages with more detailed analysis...", etc.) appear as standalone paragraphs not part of any coherent numbered sequence — leftover numbering from the source document. They read as steps in a procedure that doesn't exist. Suggested fix: convert each to a normal paragraph or a proper list.
  • Completeness — Line 63: "PingCastle lets you set up permissions on Entities, or objects (Domains or Entra ID)" uses "Entities" as a defined concept before it's explained (Entities aren't defined until the Permission Levels and Configuration > Entities sections). Suggested fix: add a one-line definition of an entity at first use, or cross-reference the Entities section.
  • Clarity — Lines 332, 336: "removing the bank items" (apparently "blank items") and "The result is then a 15 to 20 matrix" (15-to-20 what — rows? a grid?) are both ambiguous and stop the reader. Suggested fix: correct "bank" to the intended word and clarify the matrix dimensions (e.g., "a matrix of roughly 15 to 20 rows").

docs/pingcastle/4.0/index.md

  • No issues found.

docs/pingcastle/4.0/proinstall.md

  • Clarity — Lines 50–53, 411, 700: The document (titled "PingCastle Pro Installation") refers to the product inconsistently as "PingCastle Professional," "PingCastle Enterprise," and "PingCastleEnterprise," alongside "PingCastle Pro." A reader can't tell whether Pro and Enterprise are the same product. Suggested fix: use "PingCastle Pro" consistently; if Enterprise is a separate tier, state the relationship explicitly.
  • Clarity — Lines 268–270: "Sometimes, the PingCastlePro isn't started because the Default WebSite is. not the back square at the right of the PingCastlePro website." The sentence is broken and incomprehensible (stray period, "back square" likely "black square"). Suggested fix: rewrite — e.g., "If the PingCastlePro site isn't running, the black status square appears to the right of the site name in IIS; the Default Web Site may be occupying the binding instead."
  • Completeness — Lines 311–329: The "Custom installation" hosting section references ".NET Core 2" and links containing netcore2x / aspnetcore2x, but the product requires ASP.NET Core 8.0 (stated in Requirements). This outdated guidance would send readers to install the wrong framework. Suggested fix: update the framework version and Microsoft doc links to 8.0.
  • Structure — Lines 44, 55, 72, 179, 205, 231, 259, 331, 395, 516, 675: Orphaned auto-numbered items appear as standalone paragraphs not belonging to any numbered sequence — conversion artifacts. Suggested fix: convert to normal paragraphs or admonitions.
  • Clarity — Line 331: "You can change the upload quota to allow large file uploads in Interoperability mode." "Interoperability mode" is introduced with no definition or context and never explained. Suggested fix: define the mode or link to where it's configured.

docs/pingcastle/4.0/proupgrade.md

  • Completeness — Lines 1–35: This is the "PingCastle Pro Upgrade Guide" (4.0), yet it contains only a version check, a backup step, and a partial requirements list, then ends abruptly. There's no procedure for actually performing an upgrade, and the version table stops at "3.2 to 3.x" with no path to 4.0. Suggested fix: add the upgrade steps and cover the upgrade path to the current 4.0 release.
  • Structure — Lines 29–35: "The following table lists the requirements for each version," but no table follows — the content is flattened plain text where a table was intended. Suggested fix: restore a proper Markdown table with From-version / To-version / Requirement columns.
  • Structure — Line 23: Heading levels jump from H2 ("## Before proceeding...", "## Database backup") back up to H1 ("# Software requirements"), skipping levels backward. Suggested fix: make the major sections consistent — one H1 title with H2 subsections.

docs/pingcastle/4.0/prouser.md

  • Structure — Lines 105–132: The list of event types ("Domain event," "Risk event," "Trust event," "Technical event") is dropped between the "Timeline tab" image and the "Cartography tab" with no heading of its own, interrupting the tab-caption flow with no context for where events are viewed. Suggested fix: give the events list its own subheading and a lead-in sentence explaining where these events appear.
  • Completeness — Line 46: The security section lists the framework as "asp.net core 3.1," but proinstall.md states the product requires ASP.NET Core 8.0. The conflicting version could mislead a reader about platform requirements. Suggested fix: reconcile the framework version with the installation guide.

Summary

37 editorial suggestions across 15 files (13 of the 28 changed files had no editorial issues). The most common themes are conversion artifacts in the new 4.0 files (orphaned auto-numbered items and flattened tables in enterpriseuser.md, proinstall.md, and proupgrade.md), undefined terms used before first definition (Agent, Entities, CRL/OCSP, "the 2.2 area"), incomplete or placeholder sections (enterprisepostinstall.md high/low trust, proupgrade.md missing upgrade steps), and version inconsistencies (ASP.NET Core 8.0 vs. 2/3.1, Pro vs. Enterprise naming). Vale and Dale issues are auto-fixed separately.


What to do next:

Comment @claude on this PR followed by your instructions to get help:

  • @claude fix all issues — fix all editorial issues
  • @claude help improve the flow of this document — get writing assistance
  • @claude explain the voice issues — understand why something was flagged

You can ask Claude anything about the review or about Netwrix writing standards.

Automated fixes are only available for branches in this repository, not forks.

@github-actions

Copy link
Copy Markdown
Contributor

⚠️ Broken Anchor Links

1 broken anchor link(s) found — these will cause the build to fail.

  docs/pingcastle/4.0/enterprisearchitecture.md:75
    - `PingCastleSchedulerService` handles scheduled scans of local and trusted domains (see [Scheduling scans](enterprisepostinstall.md#scheduling-scans))
    #scheduling-scans not found in docs/pingcastle/4.0/enterprisepostinstall.md
    Available: #post-installation-configuration-for-pingcastle-enterprise · #common-steps · #configuring-https · #iis-maximum-upload-configuration · #manual-report-import-size-limit · #automatic-forest-exploration-setup · #manual-execution · #automated-execution-for-agent-setup · #scheduling-your-first-scan · #scheduling-an-active-directory-scan · #scheduling-an-entra-scan · #initial-startup · #initial-configuration · #entities · #encryption · #bulk-import-of-existing-reports · #report-archiving-configuration · #configuration · #how-archiving-works · #what-gets-archived · #pingcastle-agent-deployment · #synchronization-feature · #configuration · #synchronization-patterns · #synchronization-patterns-at-import-time · #connection-tests

Auto-Fix Summary

13 issues fixed, 19 skipped across 28 files

Category Fixes
BoilerplateCrossRef (rewrite) 2
Contractions (rewrite) 1
Dale: idioms 1
Dale: minimizing-difficulty 1
Dale: passive-voice 6
Dale: wordiness 2
Skipped (needs manual review) Reason
docs/pingcastle/4.0/enterpriseemailsetup.md:45 — Netwrix.TypeVsEnter False positive. 'type' is used as a noun ('the credential type the app registration uses'), not as a verb instructing the user to type text.
docs/pingcastle/4.0/enterpriseentrascan.md:118 — Netwrix.FirstPerson False positive. 'my' is part of the literal Entra admin center UI button label 'APIs my organization uses', which must be quoted verbatim.
docs/pingcastle/4.0/enterpriseentrascan.md:134 — Netwrix.FirstPerson False positive. 'my' is part of the literal Entra admin center UI button label 'APIs my organization uses', which must be quoted verbatim.
docs/pingcastle/4.0/enterprisesettings-entrascanner.md:13 — Netwrix.OxfordComma False positive. 'request and client timeouts' is a single list item (compound noun), and the outer series already has its Oxford comma ('timeouts, and circuit breaker thresholds').
docs/pingcastle/4.0/enterprisetroubleshooting.md:177 — Netwrix.OxfordComma False positive. 'Enterprise and CloudAPI' is a two-item subject following a conditional clause ('If Entra ID scanning isn't available, ...'), not a series of three or more items.
docs/pingcastle/4.0/enterprisearchitecture.md:8 — Dale: wordiness 'provides reliable data to present the situation to management, enabling continuous improvement over time' is slightly promotional but trimming risks altering meaning
docs/pingcastle/4.0/enterpriseauthsetup.md:28 — Dale: passive-voice 'is enabled by default' and 'No additional configuration is required' are established technical phrasing
docs/pingcastle/4.0/enterprisepostinstall.md:46 — Dale: minimizing-difficulty 'the simplest approach is using PowerShell' compares available methods rather than claiming the task is easy
docs/pingcastle/4.0/enterprisepostinstall.md:378 — Dale: passive-voice 'may be contained in an inner exception' is natural technical phrasing; active rewrite not clearly better
docs/pingcastle/4.0/enterpriseentrascan.md:50 — Dale: xy-slop 'The scanner is read-only — it doesn't write back changes' is clarification, not the negative-positive 'X is not Y, X is Z' framing
docs/pingcastle/4.0/enterpriselicense.md:8 — Dale: passive-voice 'Domain Controllers aren't counted for licensing purposes' has an unclear actor; active rewrite would be awkward
docs/pingcastle/4.0/enterprisesettings-scim.md:48 — Dale: xy-slop explanatory clarification, not the prohibited negative-positive rewrite pattern
docs/pingcastle/4.0/enterprisetroubleshooting.md:133 — Dale: negative-assumptions describes a technical consequence, not an assumption that the user cannot do something without the product
docs/pingcastle/4.0/enterpriseuser.md:9 — Dale: xy-slop 'The goal of the tool isn't perfection, but to provide reliable data...' is a meaningful mission statement; rewriting risks altering meaning
docs/pingcastle/4.0/proinstall.md:8 — Dale: xy-slop genuine contrast in goal statement; conservative skip
docs/pingcastle/3.5/enterpriseinstall.md:1421 — Dale: positional-references 'Follow the preceding steps' refers backward to an immediately prior list; no clean anchor exists
docs/pingcastle/3.5/enterpriseinstall.md:352 — Dale: minimizing-difficulty 'the simplest approach is using PowerShell' is a comparative choice among methods, not a claim that the task is trivial
docs/pingcastle/3.5/index.md:677 — Dale: idioms 'in the hands of' appears inside a quoted Netwrix security statement blockquote; preserved to keep the quotation intact
docs/pingcastle/4.0/enterpriseinstall.md:64 — Dale: passive-voice 'the database isn't automatically removed' is established technical phrasing; active rewrite would be awkward

Ask @claude on this PR if you'd like an explanation of any fix.

@github-actions

Copy link
Copy Markdown
Contributor

Code Review

Reviewed for correctness, build/routing, and CI concerns (documentation content/style excluded — handled separately). Scope of non-doc changes: src/config/products.js, sidebars/pingcastle/4.0.js, and the downloadable static/files/pingcastle/Setup-EntraScannerApp.ps1.

Build & routing — no issues

  • src/config/products.js: The 4.0 version entry is correct — isLatest is flipped to true on 4.0 and false on 3.5 (exactly one latest), defaultVersion is updated to 4.0, and sidebarFile: './sidebars/pingcastle/4.0.js' matches the file added in this PR and the convention used by every other product.
  • sidebars/pingcastle/4.0.js: All 26 referenced doc IDs resolve to real files under docs/pingcastle/4.0/, and every file in that folder is represented in the sidebar — so the strict build (onBrokenLinks: 'throw') has nothing to trip on. The Knowledge Base category's autogenerated dirName: 'kb' will resolve because scripts/copy-kb-to-versions.mjs builds its config from products.js and copies docs/kb/pingcastle into every version folder (including the new 4.0/kb) at prebuild time.
  • No changes to workflows, docusaurus.config.js, or the KB copy script — nothing else in the build/deploy path is affected.

Setup-EntraScannerApp.ps1 — out of the build path; two low-severity robustness notes

This is a static file users download and run manually, so it cannot break the site build. Two genuine correctness edge cases worth considering:

  1. Global Reader lookup can be null. Get-MgDirectoryRole -Filter "displayName eq 'Global Reader'" returns nothing in tenants where that directory role has not yet been activated from its role template. $globalReaderRole would then be $null, and New-MgDirectoryRoleMemberByRef -DirectoryRoleId $null ... fails under $ErrorActionPreference = 'Stop'. Activating the role via New-MgDirectoryRole/role-template before the lookup (or adding a null check) would make this reliable.
  2. -UseExisting reuse path is not idempotent for Exchange. On a reuse run, New-ServicePrincipal -AppId ... -ObjectId $sp.Id throws if the Exchange service principal already exists, aborting the whole script. Given -UseExisting is documented for non-interactive re-runs, guarding this call (and the Add-RoleGroupMember add) against "already exists" would match the stated intent.

No secrets are committed, and no injection or unsafe-eval concerns in the config or scripts.

Overall: the config and routing changes are correct and safe to build. The PowerShell notes are optional hardening for a user-run helper.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

KB review: PingCastle 4.0 documentation (PR #1270)

4 participants