diff --git a/.memory-bank/activeContext.md b/.memory-bank/activeContext.md new file mode 100644 index 0000000..0cef07c --- /dev/null +++ b/.memory-bank/activeContext.md @@ -0,0 +1,30 @@ +--- +status: current +last-verified: 2026-10-02 +owner: active-agent +source: current task evidence +--- + +# Active context + +## Current focus + +PR #91 (`ai/docs-alignment`): CI fixed by building the module from source +in `appveyor.yml` and checking the docs against that build. + +## Evidence + +- AppVeyor build 54825990 failed in step 01: `Update-MarkdownHelp` against + the Gallery module 4.2.6 rewrote `Remove-Item2 -PassThru` to `-PassThur`. +- Against a Release build of the source, `Update-MarkdownHelp` changes none + of the 36 pages; a simulation of all `appveyor.yml` steps in a fresh clone + passed, and a page with stale syntax made it fail as intended. +- The link check (`Get-MarkdownLink -BrokenOnly`) finds 308 links, none + broken. +- Read the Docs project `ntfssecurity` still builds the fork + `Sup3rlativ3/NTFSSecurity`. + +## Next step + +PR #91 is green (AppVeyor 54828078 branch and 54828080 pull request, both +on `dbd8d16`). Await review and merge; open follow-ups are in `progress.md`. diff --git a/.memory-bank/index.md b/.memory-bank/index.md new file mode 100644 index 0000000..8b8ddb1 --- /dev/null +++ b/.memory-bank/index.md @@ -0,0 +1,46 @@ +--- +schema-version: 1 +loading-mode: routed +status: accepted +owner: shared +last-verified: 2026-10-02 +source: repository evidence +--- + +# Memory Bank index + +Read this file first. It routes tasks to the smallest relevant set of Memory +Bank files. + +## Full-read fallback + +Set `loading-mode` to `full` to restore complete-base loading. Also fail open +when this index is missing or invalid, the task is ambiguous, routes conflict, +a listed file is missing, or a critical fact cannot be found. Full mode also +reads every existing `decisions/*.md` record. + +## Routing table + +Combine routes when a task spans topics. For durable repository writes, also +read `activeContext.md` before editing. + +| Route | Task signals | Read | +|---|---|---| +| `general` | General Q&A with no project decision | Index only | +| `continuation` | Resume, current focus, next step | `activeContext.md`, `progress.md` | +| `scope` | Purpose, scope, requirements, Acceptance criteria | `projectbrief.md` | +| `product` | Users, problem, workflow, experience goal | `productContext.md` | +| `implementation` | Code, configuration, build, test, dependency, deployment | `techContext.md`, `activeContext.md` | +| `architecture` | Design, pattern, decision, migration, integration | `systemPatterns.md`, relevant `decisions/*.md` | +| `status` | Progress, recent change, open work | `progress.md`, `activeContext.md` | +| `language` | Canonical terms in authored artifacts | `glossary.md` | +| `interaction-history` | Session analysis, prompt trends, Memory Bank evals | `promptHistory.md`, `progress.md` | +| `role` | Active Custom agent domain workflow | Only that agent's declared role files | + +## Authority order + +1. The user's current request controls task constraints. +2. Repository source, configuration, tests, and evidence control facts. +3. Accepted decision records control durable architectural choices. +4. Core Memory Bank files control only their assigned topic. +5. Historical logs never override current source. diff --git a/.memory-bank/productContext.md b/.memory-bank/productContext.md new file mode 100644 index 0000000..b350f72 --- /dev/null +++ b/.memory-bank/productContext.md @@ -0,0 +1,42 @@ +--- +status: current +last-verified: 2026-10-02 +owner: shared +source: repository evidence +--- + +# Product context + +## Problem + +PowerShell ships only `Get-Acl` and `Set-Acl`; everything between reading +and writing an ACL (permission reports, adding or removing one entry, +inheritance, ownership, orphaned SIDs) needs custom .NET code. The module +provides task-level cmdlets for these jobs (`README.md` summary). + +## Users + +- People who manage NTFS file and folder permissions with PowerShell + (README summary). Specific personas: To confirm. + +## Core workflows + +1. Report permissions: `Get-NTFSAccess`, `Get-NTFSSimpleAccess`, + `Get-NTFSEffectiveAccess`. +2. Change permissions: `Add-NTFSAccess`, `Remove-NTFSAccess`, + `Clear-NTFSAccess`; the audit equivalents manage the SACL. +3. Back up and restore explicit permissions through CSV + (`Get-NTFSAccess | Export-Csv`, `Import-Csv | Add-NTFSAccess`). +4. Find and remove orphaned entries: `Get-NTFSOrphanedAccess`. +5. Repair inheritance and ownership: `*-NTFSAccessInheritance`, + `Set-NTFSInheritance`, `Set-NTFSOwner`, using backup/restore privileges. +6. Work with paths longer than 260 characters: `Get-ChildItem2` and the other + `*-Item2` cmdlets. + +## Experience goals + +- Pipeline first: item cmdlets emit objects whose `FullName` binds to `-Path`. +- Accept account names and SIDs; output shows both when resolvable. +- Output formatted like `Get-ChildItem` (`NTFSSecurity.format.ps1xml`). +- Work on files the caller cannot normally open by enabling the Backup, + Restore, TakeOwnership, and Security privileges automatically. diff --git a/.memory-bank/progress.md b/.memory-bank/progress.md new file mode 100644 index 0000000..449bbfa --- /dev/null +++ b/.memory-bank/progress.md @@ -0,0 +1,53 @@ +--- +status: current +last-verified: 2026-10-02 +owner: active-agent +source: repository evidence +--- + +# Progress + +## Current status + +Documentation matches the cmdlets at HEAD. The module source is unchanged +since the 4.2.6 release except the `Remove-Item2 -PassThru` rename and +`CompatiblePSEditions`. + +## Recent milestones + +- 2026-10-02: Memory Bank initialized. +- 2026-10-02: Documentation aligned with the code: 36 cmdlet pages filled + from the C# source and checked at runtime in a sandbox; Concepts, Examples, + home page, contributor guide, README rewritten; `mkdocs.yml` nav, + `edit_uri`, and `.readthedocs.yml` (`build.os`) fixed; `CHANGELOG.md` + created. +- 2026-10-02: PR #91 build fixed: `appveyor.yml` builds the module from + source and checks the docs against that build instead of the Gallery + release (root cause of the `Remove-Item2 -PassThru` drift failure). + +## Stable capabilities + +- 36 cmdlets: access (7), audit (5), inheritance (6), owner and security + descriptor (4), privileges (3), long-path items (6), links, hash, and + disk space (5). +- Works in Windows PowerShell 5.1 and PowerShell 7 (smoke-tested), except + `Get-FileHash2`, which fails in PowerShell 7 (missing `RIPEMD160` type). + +## Open work + +- Ship help: add the generated `en-US\NTFSSecurity.dll-Help.xml` to the + build and drop the stale `NTFSSecurity-Help.xml`. +- Publishing: re-point Read the Docs from the fork `Sup3rlativ3/NTFSSecurity` + to this repository (or create a new Read the Docs project). +- Manifest: remove `Show-NTFSSimpleAccess` and duplicates from + `CmdletsToExport`; bump `ModuleVersion` (4.2.5 in source, 4.2.6 released). +- Code defects found while documenting (each documented on its page): + `Add-NTFSAudit` duplicate position 2; SD parameter sets of + `Add/Remove-NTFSAccess/Audit` need `-AppliesTo`; `Set-NTFSInheritance` + nullable crash and hard-coded removal; inheritance cmdlets ignore + `EnablePrivileges = $false`; `Get-NTFSEffectiveAccess` + `-ExcludeNoneAccessEntries` and SD set ineffective; `-Account`/SD ignored by + `Get-NTFSOrphanedAccess/Audit` and `Get-NTFSSimpleAccess`; `Copy-Item2` + fails on folders with files; `Get-ChildItem2` throws on a file path; + `return` instead of `continue` in several `ProcessRecord` loops; wrong + `OutputType` on several cmdlets; `Get-FileHash2` in PowerShell 7. diff --git a/.memory-bank/projectbrief.md b/.memory-bank/projectbrief.md new file mode 100644 index 0000000..98aa2d7 --- /dev/null +++ b/.memory-bank/projectbrief.md @@ -0,0 +1,42 @@ +--- +status: current +last-verified: 2026-10-02 +owner: shared +source: repository evidence +--- + +# Project brief + +## Purpose + +NTFSSecurity is a binary (C#) PowerShell module that fills the gap between +`Get-Acl` and `Set-Acl`: cmdlets to read, add, remove, and clear NTFS +permissions (DACL) and audit rules (SACL), manage inheritance and ownership, +copy security descriptors, control process privileges, and work with long +paths (`*-Item2` cmdlets via AlphaFS), hard links, and symbolic links. +Source: `README.md`, `NTFSSecurity/NTFSSecurity.psd1`. + +## Scope + +- In scope: module source (`NTFSSecurity`, `Security2`, `PrivilegeControl`, + `ProcessPrivileges`), module manifest and type/format data, the MkDocs + documentation site in `Docs/`, and `README.md`. +- Out of scope: registry security. `Security2/Registry/RegistrySecurity.cs` + exists, but no registry cmdlet is exported. +- Distribution: PowerShell Gallery package `NTFSSecurity` and GitHub releases. + +## Stakeholders + +- Maintainer and author: Raimund Andree (`raandree`), per the manifest. +- Documentation contributors: James Smith (`mkdocs.yml` `site_author`); + the AppVeyor documentation build runs under the `Sup3rlativ3` account. +- End users: To confirm beyond the README summary. + +## Acceptance criteria + +1. Every exported cmdlet has an accurate platyPS page in `Docs/Cmdlets`. +2. `Update-MarkdownHelp` against the module produces no parameter drift + (the check in `appveyor.yml`). +3. The module imports in Windows PowerShell 5.1 and PowerShell 7 + (`CompatiblePSEditions = 'Core', 'Desktop'`). +4. Further release criteria: To confirm. diff --git a/.memory-bank/systemPatterns.md b/.memory-bank/systemPatterns.md new file mode 100644 index 0000000..19319cc --- /dev/null +++ b/.memory-bank/systemPatterns.md @@ -0,0 +1,95 @@ +--- +status: current +last-verified: 2026-10-02 +owner: active-agent +source: repository evidence +--- + +# System patterns + +## Architecture + +```text +NTFSSecurity.psd1 ─┬─ ScriptsToProcess: NTFSSecurity.Init.ps1 + │ Add-Type: Security2.dll, PrivilegeControl.dll, + │ ProcessPrivileges.dll, inline NTFS.DriveInfoExt; + │ Update-FormatData -PrependPath format.ps1xml + ├─ TypesToProcess: NTFSSecurity.types.ps1xml + │ (Owner, IsInheritanceBlocked, LengthOnDisk on + │ FileInfo/DirectoryInfo; AccountType on ACEs) + ├─ ModuleToProcess: NTFSSecurity.psm1 (aliases) + └─ NestedModules: NTFSSecurity.dll (36 cmdlets) +NTFSSecurity.dll ── cmdlets ──> Security2.dll (FileSystemAccessRule2, + FileSystemAuditRule2, IdentityReference2, + FileSystemInheritanceInfo, EffectiveAccess) + ── long paths ──> AlphaFS + ── privileges ──> PrivilegeControl / ProcessPrivileges +``` + +- `BaseCmdlet` resolves relative paths against `$PWD`. +- `BaseCmdletWithPrivControl` (access, audit, inheritance, owner, security + descriptor, and privilege cmdlets) enables Backup, Restore, TakeOwnership, + and Security in `BeginProcessing` when `PrivateData.EnablePrivileges` is + `$true`, and disables the ones it enabled in `EndProcessing`. +- `PrivateData` switches: `EnablePrivileges` (base cmdlet), + `GetInheritedFrom` (`Get-NTFSAccess`, `Get-NTFSAudit`), + `GetFileSystemModeProperty` and `IdentifyHardLinks` (`Get-ChildItem2`), + `ShowAccountSid` (format file). +- Cmdlets accept either `-Path` (alias `FullName`) or `-SecurityDescriptor` + (from `Get-NTFSSecurityDescriptor`); SD sets change the in-memory object + until `Set-NTFSSecurityDescriptor` writes it back. + +## Decisions + +### Decision 1: Use the canonical Memory Bank base + +- Choice: Keep durable project context in .memory-bank. +- Rationale: Preserve evidence-backed context across sessions. + +### Decision 2: Cmdlet reference stays platyPS markdown + +- Choice: `Docs/Cmdlets/*.md` keep the platyPS 0.14 schema 2.0.0 layout + (upper-case section headings, YAML parameter blocks, one paragraph per + line) so `Update-MarkdownHelp` and `New-ExternalHelp` round-trip. +- Rationale: `appveyor.yml` checks the pages with `Update-MarkdownHelp`; + the same files can generate MAML help. + +### Decision 3: Document the source at HEAD + +- Choice: Docs describe the code on `master`. Where HEAD differs from the + latest Gallery release, the page says which version changed. +- Rationale: The user asked to align docs with the actual code; the only + current difference is `Remove-Item2 -PassThru` (4.2.6 spells `-PassThur`). + +### Decision 4: Online help points to GitHub + +- Choice: `online version` of every cmdlet page is + `https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/.md`. +- Rationale: The Read the Docs project builds a stale fork, so its URLs show + outdated pages; GitHub always shows `master`. + +### Decision 5: Document defects, don't fix them in docs work + +- Choice: Code defects found while documenting are described on the affected + page (workaround or limitation) and listed in `progress.md`; source code is + changed only in separate, tested work. +- Rationale: No build toolchain was available to verify code changes, and + the docs must describe current behavior. + +### Decision 6: CI checks the docs against a build of the source + +- Choice: `appveyor.yml` builds `NTFSSecurity.csproj` and runs + `Update-MarkdownHelp` against `NTFSSecurity\bin\Release`, not against the + module from the PowerShell Gallery. +- Rationale: Checking against the last release fails for every unreleased + parameter change (PR #91 failed on `Remove-Item2 -PassThru`) and never + compiled the code. + +### Pattern: verifying documentation + +- Run platyPS in Windows PowerShell 5.1 against a module build; a copy of + `Docs/Cmdlets` must round-trip through `Update-MarkdownHelp` unchanged. +- platyPS rewrites non-ASCII punctuation such as em dashes; keep cmdlet pages + ASCII-only. +- Verify examples in a `$env:TEMP` sandbox, never on real data; parse every + example and check its parameters against `Get-Command` metadata. diff --git a/.memory-bank/techContext.md b/.memory-bank/techContext.md new file mode 100644 index 0000000..290a78f --- /dev/null +++ b/.memory-bank/techContext.md @@ -0,0 +1,71 @@ +--- +status: current +last-verified: 2026-10-02 +owner: active-agent +source: repository evidence +--- + +# Tech context + +## Stack + +- C# class libraries, old-style `.csproj`, .NET Framework 4.5.2, + solution `NTFSSecurity.sln` (Visual Studio 2017 format). +- Projects: `NTFSSecurity` (cmdlets), `Security2` (ACL object model, Win32 + interop), `PrivilegeControl` and `ProcessPrivileges` (token privileges), + `Log`, `TestClient`, `NTFSSecurityTest` (MSTest, minimal coverage). +- NuGet (`packages.config`): AlphaFS 2.2.x for long paths; + `System.Management.Automation.dll` 10.0.10586.0. +- Module: `NTFSSecurity.psd1` loads `NTFSSecurity.psm1` (aliases `dir2`, + `gi2`, `rm2`, `del2`), `NTFSSecurity.Init.ps1` (Add-Type of the helper + assemblies, prepends `NTFSSecurity.format.ps1xml`), and `NTFSSecurity.dll`. +- Documentation: MkDocs (`mkdocs.yml`, theme `readthedocs`, `docs_dir: ./Docs`) + built by Read the Docs (`.readthedocs.yml` v2); cmdlet pages are platyPS + 0.14 markdown (schema 2.0.0) in `Docs/Cmdlets`. + +## Environment + +- Windows only (NTFS, Win32 security APIs). +- The Debug build writes straight into + `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity\`. +- No Visual Studio MSBuild or .NET Framework targeting pack on the + workstation. A local build works with the .NET Framework MSBuild + (`%WINDIR%\Microsoft.NET\Framework64\v4.0.30319\MSBuild.exe`) plus + `/p:CscToolPath` to the Roslyn `csc.exe` of the `Microsoft.Net.Compilers` + package; the legacy C# 5 compiler fails with CS0136. `dotnet msbuild` + fails on the binary resources in `Resources.resx` (MSB3822, MSB3823). + +## Constraints + +- `ModuleVersion` in the source manifest is `4.2.5`; the latest tag and + Gallery release is `4.2.6`. +- HEAD differs from tag `4.2.6` only by the `Remove-Item2 -PassThur` to + `-PassThru` rename and `CompatiblePSEditions` in the manifest. +- `CmdletsToExport` lists `Show-NTFSSimpleAccess`, which no longer exists + (WinForms code removed in `d3063de`), and repeats the inheritance cmdlets. +- `NTFSSecurity/NTFSSecurity-Help.xml` is a stale pre-4.x MAML file for old + command names; binary-module help must be named `NTFSSecurity.dll-Help.xml`. +- CI: AppVeyor project `raandree/ntfssecurity` builds branches and pull + requests. Read the Docs (`ntfssecurity`) and a second AppVeyor project are + attached to the fork `Sup3rlativ3/NTFSSecurity`. +- `Get-FileHash2` fails in PowerShell 7; all other cmdlets passed a smoke + test in PowerShell 7.6. + +## Validation + +- CI (`appveyor.yml`, image Visual Studio 2022): restore `packages.config` + per project plus `Microsoft.NETFramework.ReferenceAssemblies.net452` + 1.0.3, build `NTFSSecurity.csproj` in Release with + `TargetFrameworkRootPath`/`FrameworkPathOverride`, import + `NTFSSecurity\bin\Release\NTFSSecurity.psd1`, run `Update-MarkdownHelp`, + and fail on `git diff -- Docs/Cmdlets`; then `Get-MarkdownLink -BrokenOnly`. +- Run platyPS in Windows PowerShell 5.1 to avoid PowerShell 7.4+ + `-ProgressAction` noise. +- Placeholder check: no `{{` left in `Docs/Cmdlets/*.md`. +- Help build check: `New-ExternalHelp -Path ./Docs/Cmdlets` to a temp folder. +- Markdown lint: `npx markdownlint-cli2` with `MD013` limited to prose + (tables, code, and headings excluded) on the conceptual pages. +- YAML: `ConvertFrom-Yaml` (powershell-yaml) on `mkdocs.yml`, + `.readthedocs.yml`, and `appveyor.yml`; every `nav` target must exist. +- MkDocs needs Python, which this workstation does not have; `mkdocs build + --strict` was not run. diff --git a/.readthedocs.yml b/.readthedocs.yml index 58fb067..be2da6e 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -5,9 +5,17 @@ # Required version: 2 +# Required: the build image and the Python version +build: + os: ubuntu-24.04 + tools: + python: "3.12" + # Build documentation with MkDocs mkdocs: configuration: mkdocs.yml -# Optionally build your docs in additional formats such as PDF and ePub -formats: all \ No newline at end of file +# Install the MkDocs version that the site is built with +python: + install: + - requirements: Docs/requirements.txt diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..6dae653 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,31 @@ +# Changelog + +All notable changes to this project are documented in this file. + +The format is based on +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Releases up to +4.2.6 are described in the +[version history](https://github.com/raandree/NTFSSecurity/wiki/Version-History) +in the wiki. + +## [Unreleased] + +### Changed + +- **Breaking:** rename the `-PassThur` parameter of `Remove-Item2` to + `-PassThru` ([#64](https://github.com/raandree/NTFSSecurity/pull/64)) +- Declare support for Windows PowerShell and PowerShell 7 in the module + manifest ([#61](https://github.com/raandree/NTFSSecurity/issues/61)) +- Document every cmdlet with synopsis, description, parameters, examples, + inputs, outputs, and notes, checked against the source code +- Rewrite the home, concepts, examples, and contributor pages to match the + current cmdlets, including module settings, privileges, and long paths + +### Fixed + +- Fix documentation examples that did not work, such as restoring + permissions from a CSV file and filtering entries by account +- Fix the documentation site navigation, the "Edit on GitHub" links, and the + Read the Docs build configuration + +[Unreleased]: https://github.com/raandree/NTFSSecurity/compare/4.2.6...HEAD diff --git a/Docs/Cmdlets/Add-NTFSAccess.md b/Docs/Cmdlets/Add-NTFSAccess.md index bca6469..68619c2 100644 --- a/Docs/Cmdlets/Add-NTFSAccess.md +++ b/Docs/Cmdlets/Add-NTFSAccess.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml Module Name: NTFSSecurity -online version: +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Add-NTFSAccess.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -Adds an access control entry (ACE) to an object. +Adds an access control entry (ACE) to a file, a folder, or a security descriptor. ## SYNTAX @@ -42,62 +42,55 @@ Add-NTFSAccess [-SecurityDescriptor] [-Account] Add-NTFSAccess -Path C:\Data -Account 'NT AUTHORITY\Authenticated Users' -AccessRights Read ``` -The above command gives the read permissions to the built-in group of 'Authenticated users'. +This command grants read access to the built-in group of authenticated users. The ACE applies to the folder, its subfolders, and its files, because `-AppliesTo` defaults to `ThisFolderSubfoldersAndFiles`. + +### Example 2: Grant full control and show the resulting ACL + +```PowerShell +PS C:\> Add-NTFSAccess -Path C:\Data -Account 'CONTOSO\Domain Admins' -AccessRights FullControl -PassThru +``` + +This command grants full control to a domain group. `-PassThru` writes all access control entries of the folder, explicit and inherited, after the change. -### Example 2 +### Example 3: Deny a right on a single folder ```PowerShell -PS C:\> Add-NTFSAccess -Path C:\Data -Account 'Contoso\Domain Admins' -AccessRights Full +PS C:\> Add-NTFSAccess -Path C:\Data -Account 'CONTOSO\Domain Users' -AccessRights CreateFiles -AccessType Deny -AppliesTo ThisFolderOnly ``` -The above command gives full permissions to the domain administrators group in the contoso active directory. +This command denies the creation of files in `C:\Data` to the members of a domain group. The ACE is not inherited by subfolders or files, because `-AppliesTo` is set to `ThisFolderOnly`. -### Example 3 +### Example 4: Restore explicit permissions from a CSV backup ```PowerShell -PS C:\> Add-NTFSAccess -Path C:\Data -Account 'NT AUTHORITY\Authenticated Users' -AccessRights CreateFiles -AccessType Deny -AppliesTo ThisFolderOnly +PS C:\> Import-Csv -Path C:\Backup\acl.csv | Add-NTFSAccess ``` -The above command denies the the built-in group of 'Authenticated users' from creating files in this folder only. +This command restores the access control entries that `Get-NTFSAccess` exported to a CSV file. The columns `FullName`, `Account`, `AccessRights`, `AccessControlType`, `InheritanceFlags`, and `PropagationFlags` bind to the matching parameters, so every row recreates the ACE it was exported from. ## PARAMETERS ### -AccessRights -The AccessRights parameter designates the permissions to assign. There are individual permissions as well as 'basic' permissions. See the below table for how the basic permissions permissions map the the advanced permissions in the advanced security window. +Specifies the rights the ACE grants or denies. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. An `Allow` ACE always receives `Synchronize` in addition to the specified rights. See [Concepts](../Concepts.md) for how the values relate to the Windows security dialog. ```yaml Type: FileSystemRights2 @@ -114,7 +107,7 @@ Accept wildcard characters: False ### -AccessType -The AccessType parameter determines if the ACE allows or denies the permissions assigned. +Specifies whether the ACE allows or denies the rights in `-AccessRights`. The default is `Allow`. A `Deny` ACE takes precedence over `Allow` ACEs that grant the same rights. ```yaml Type: AccessControlType @@ -124,14 +117,14 @@ Accepted values: Allow, Deny Required: False Position: Named -Default value: None +Default value: Allow Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Account -The Account parameter defines the account or group to apply the permissions to. +Specifies one or more accounts or groups the ACE applies to. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-32-544`. A name that cannot be translated into a SID raises an error, a SID that cannot be translated into a name is accepted. ```yaml Type: IdentityReference2[] @@ -147,7 +140,7 @@ Accept wildcard characters: False ### -AppliesTo -The AppliesTo parameter defines where the permissions apply to and if there is any inheritance e.g "this folder only" or "this folder and subfolders". +Specifies the scope of the ACE in the wording of the Windows security dialog, for example `ThisFolderOnly`, `ThisFolderAndSubfolders`, or `SubfoldersAndFilesOnly`. The default is `ThisFolderSubfoldersAndFiles`. The cmdlet translates the value into the equivalent inheritance and propagation flags, so this parameter and the pair `-InheritanceFlags` and `-PropagationFlags` are two ways to describe the same ACE. The values ending in `OneLevel` limit inheritance to the direct children of the folder. ```yaml Type: ApplyTo @@ -157,20 +150,16 @@ Accepted values: ThisFolderOnly, ThisFolderSubfoldersAndFiles, ThisFolderAndSubf Required: False Position: Named -Default value: None +Default value: ThisFolderSubfoldersAndFiles Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -InheritanceFlags -The InheritanceFlags parameter defines the inheritance of the ACLs. - -ObjectInherit will apply the ACE to files and folders in the folder defined by the Path parameter. - -ContainerInherit will apply the ACE to subfolders but not files. +Specifies which kind of child objects inherit the ACE. `ContainerInherit` passes the ACE on to child folders, `ObjectInherit` passes it on to child files, and `None` keeps the ACE on the item itself. The default is `ContainerInherit, ObjectInherit`. Inheritance flags have no effect on files, where the ACE is always created with `None`. -There is more information on Microsoft Docs [here](https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms229747(v=vs.100)?redirectedfrom=MSDN) +For details about the flags, see [InheritanceFlags Enum](https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.inheritanceflags) in the .NET documentation. ```yaml Type: InheritanceFlags @@ -180,14 +169,14 @@ Accepted values: None, ContainerInherit, ObjectInherit Required: False Position: Named -Default value: None +Default value: ContainerInherit, ObjectInherit Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -PassThru -The PassThru parameter will return the new permissions as a table. If the PassThru parameter is omitted, there is no information returned if the operation was successful. +Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output. ```yaml Type: SwitchParameter @@ -203,7 +192,7 @@ Accept wildcard characters: False ### -Path -The Path parameter defines where the file or container exists. +Specifies the path of one or more files or folders the ACE is added to. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`. ```yaml Type: String[] @@ -219,13 +208,7 @@ Accept wildcard characters: False ### -PropagationFlags -The PropagationFlags parameter defines how the ACE is propagated to child objects. - -Inherit specifies that the ACE is propagated only to child objects. This includes both folder and file child objects. - -NoPropagateInherit specifies that the ACE is not propagated to child objects. - -None specifies that no inheritance flags are set. +Specifies how the ACE is propagated to child objects. `None` propagates the ACE to all levels that the inheritance flags allow, `InheritOnly` keeps the ACE from applying to the item it is defined on, and `NoPropagateInherit` limits inheritance to the direct children of the folder. The default is `None`, and propagation flags only have an effect in combination with `-InheritanceFlags`. ```yaml Type: PropagationFlags @@ -242,7 +225,7 @@ Accept wildcard characters: False ### -SecurityDescriptor -The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. +Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, that the ACE is added to. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system. A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. @@ -265,24 +248,58 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +One or more paths of files or folders, piped by value or by the property `FullName`. + ### Security2.FileSystemSecurity2[] +One or more security descriptors returned by `Get-NTFSSecurityDescriptor`. + ### Security2.IdentityReference2[] +The accounts the ACE is created for, bound from a property named `Account`, `IdentityReference`, or `ID`. The output of `Get-NTFSAccess` supplies `Account`. + ### Security2.FileSystemRights2 +The rights of the ACE, piped by the property `AccessRights` or `FileSystemRights`. + ### System.Security.AccessControl.AccessControlType +The type of the ACE, piped by the property `AccessType` or `AccessControlType`. + ### System.Security.AccessControl.InheritanceFlags +The inheritance flags of the ACE, piped by the property `InheritanceFlags` in the `Complex` parameter sets. + ### System.Security.AccessControl.PropagationFlags +The propagation flags of the ACE, piped by the property `PropagationFlags` in the `Complex` parameter sets. + ### Security2.ApplyTo +The scope of the ACE, piped by the property `AppliesTo` in the `Simple` parameter sets. + ## OUTPUTS ### Security2.FileSystemAccessRule2 +With `-PassThru`, the cmdlet writes all access control entries of every processed item, explicit and inherited. Without `-PassThru` it writes nothing. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +If the ACL of an item cannot be written because access is denied, the cmdlet tries once more after making the current account the owner of the item, and restores the previous owner afterwards. Changing the owner of an item requires the Take Ownership and Restore privileges, so this fallback only succeeds in an elevated session of an account that holds them. + ## RELATED LINKS + +[Get-NTFSAccess](Get-NTFSAccess.md) + +[Remove-NTFSAccess](Remove-NTFSAccess.md) + +[Clear-NTFSAccess](Clear-NTFSAccess.md) + +[Get-NTFSEffectiveAccess](Get-NTFSEffectiveAccess.md) + +[Get-NTFSSecurityDescriptor](Get-NTFSSecurityDescriptor.md) + +[Set-NTFSSecurityDescriptor](Set-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Add-NTFSAudit.md b/Docs/Cmdlets/Add-NTFSAudit.md index 59183f5..25ac651 100644 --- a/Docs/Cmdlets/Add-NTFSAudit.md +++ b/Docs/Cmdlets/Add-NTFSAudit.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Add-NTFSAudit.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -Add auditing to a folder or file. +Adds an audit entry to a file or folder. ## SYNTAX @@ -42,24 +42,57 @@ Add-NTFSAudit [-SecurityDescriptor] [-Account] Add-NTFSAudit -Path C:\Data -Account 'CONTOSO\Domain Users' -AccessRights FullControl -AuditFlags Failure +``` + +This command audits every failed attempt of the group `CONTOSO\Domain Users` to use one of the rights contained in `FullControl` on `C:\Data`. Because `-AppliesTo` and the inheritance parameters are omitted, the entry applies to the folder, its subfolders, and its files. + +### Example 2: Audit successful deletions in one folder + +```PowerShell +PS C:\> Add-NTFSAudit -Path C:\Data -Account Everyone -AccessRights Delete, DeleteSubdirectoriesAndFiles -AuditFlags Success -AppliesTo ThisFolderOnly +``` + +This command audits successful deletions performed by any account in the folder `C:\Data`. `-AppliesTo ThisFolderOnly` keeps the entry from being inherited by subfolders and files. + +### Example 3: Audit several folders from the pipeline ```PowerShell -PS C:\> Add-NTFSAudit -Path C:\Data -Account 'NT AUTHORITY\Authenticated Users' -AcessRights generic All -AuditFlags Failure +PS C:\> Get-ChildItem2 -Path C:\Data -Directory | Add-NTFSAudit -Account 'BUILTIN\Users' -AccessRights ReadData -AuditFlags Success -PassThru ``` -The above command adds auditing to the folder C:\Data on any failure. +This command adds the same audit entry to every subfolder of `C:\Data` and returns all audit entries of each folder afterwards, including the inherited ones, so that you can check the result. + +### Example 4: Add an audit entry to a security descriptor + +```PowerShell +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Add-NTFSAudit -SecurityDescriptor $sd -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AuditFlags Success, Failure -AppliesTo SubfoldersAndFilesOnly +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd +``` + +This command adds an audit entry for `CONTOSO\JohnDoe` to the in-memory security descriptor of `C:\Data` and then writes the descriptor back. The entry applies to the subfolders and files of `C:\Data` but not to the folder itself. + ## PARAMETERS ### -AccessRights -The AccessRights parameter designates the permissions to monitor or audit. There are individual permissions as well as 'basic' permissions. See the below table for how the basic permissions permissions map the the advanced permissions in the advanced security window. +Specifies the access rights to audit. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. See [Concepts](../Concepts.md) for the meaning of each right. ```yaml Type: FileSystemRights2 @@ -76,7 +109,7 @@ Accept wildcard characters: False ### -Account -The Account parameter defines the account or group to apply the auditing to. +Specifies the accounts whose access to the item is audited. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. When you pass several accounts, the cmdlet adds one audit entry per account. ```yaml Type: IdentityReference2[] @@ -92,7 +125,7 @@ Accept wildcard characters: False ### -AppliesTo -The AppliesTo parameter defines where the auditing will apply to and if there is any inheritance e.g "this folder only" or "this folder and subfolders". +Specifies the scope of the audit entry with a single value instead of the `-InheritanceFlags` and `-PropagationFlags` pair, in the same wording the Advanced Security Settings dialog uses. `ThisFolderOnly` audits the folder itself, `ThisFolderSubfoldersAndFiles` audits the folder and everything below it, `SubfoldersAndFilesOnly` audits the content but not the folder itself, and the values ending in `OneLevel` limit inheritance to the direct children. The default is `ThisFolderSubfoldersAndFiles`. ```yaml Type: ApplyTo @@ -102,14 +135,14 @@ Accepted values: ThisFolderOnly, ThisFolderSubfoldersAndFiles, ThisFolderAndSubf Required: False Position: Named -Default value: None +Default value: ThisFolderSubfoldersAndFiles Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -AuditFlags -The AuditFlags parameter defines what types of events will be audited. If you would only like to audit denied access you would choose failure. +Specifies which access attempts are audited. `Success` audits attempts that succeeded, `Failure` audits attempts that were denied, and `Success, Failure` audits both. The default is `Success, Failure`. ```yaml Type: AuditFlags @@ -119,20 +152,14 @@ Accepted values: None, Success, Failure Required: False Position: Named -Default value: None +Default value: Success, Failure Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -InheritanceFlags -The InheritanceFlags parameter defines the inheritance of the auditing. - -ObjectInherit will apply the auditing to files and folders in the folder defined by the Path parameter. - -ContainerInherit will apply the auditing to subfolders but not files. - -There is more information on Microsoft Docs [here](https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms229747(v=vs.100)?redirectedfrom=MSDN) +Specifies which child items inherit the audit entry. `ContainerInherit` passes the entry on to child folders, `ObjectInherit` passes it on to child files, and `None` keeps the entry on the item itself. The values can be combined, and the default is `ContainerInherit, ObjectInherit`. Use `-PropagationFlags` to control whether the entry also applies to the item itself and how far it propagates. ```yaml Type: InheritanceFlags @@ -142,14 +169,14 @@ Accepted values: None, ContainerInherit, ObjectInherit Required: False Position: Named -Default value: None +Default value: ContainerInherit, ObjectInherit Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -PassThru -The PassThru parameter will return the new auditing as a table. If the PassThru parameter is omitted, there is no information returned if the operation was successful. +Indicates that the cmdlet writes the audit entries of the processed item to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was added. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns. ```yaml Type: SwitchParameter @@ -165,7 +192,7 @@ Accept wildcard characters: False ### -Path -The Path parameter defines where the file or container exists to apply the auditing to. +Specifies the files or folders the audit entry is added to. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. ```yaml Type: String[] @@ -181,13 +208,7 @@ Accept wildcard characters: False ### -PropagationFlags -The PropagationFlags parameter defines how the auditing is propagated to child objects. - -Inherit specifies that the auditing is propagated only to child objects. This includes both folder and file child objects. - -NoPropagateInherit specifies that the auditing is not propagated to child objects. - -None specifies that no inheritance flags are set. +Specifies how the inheritance selected with `-InheritanceFlags` propagates. `None` applies the entry to the item itself and to all inheriting child items, `InheritOnly` applies it to the inheriting child items but not to the item itself, and `NoPropagateInherit` limits inheritance to the direct children. The values `InheritOnly` and `NoPropagateInherit` can be combined, and the default is `None`. The parameter has no effect when `-InheritanceFlags` is `None`. ```yaml Type: PropagationFlags @@ -204,9 +225,7 @@ Accept wildcard characters: False ### -SecurityDescriptor -The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. - -A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. +Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet adds the audit entry to the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. ```yaml Type: FileSystemSecurity2[] @@ -227,24 +246,64 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe paths to this cmdlet, or objects that have a `Path` or `FullName` property, such as the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2`. + ### Security2.FileSystemSecurity2[] +You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + ### Security2.IdentityReference2[] +The accounts passed to `-Account` are converted to this type from an account name or a SID string. The parameter binds by property name through its own name and its aliases `IdentityReference` and `ID`, so the `Account` property of the entries this module returns supplies the value. + ### Security2.FileSystemRights2 +The value passed to `-AccessRights` is converted to this type. The parameter binds by property name, so an object with an `AccessRights` or `FileSystemRights` property supplies the value. + ### System.Security.AccessControl.AuditFlags +The value passed to `-AuditFlags` is converted to this type and binds by property name. + ### System.Security.AccessControl.InheritanceFlags +The value passed to `-InheritanceFlags` is converted to this type and binds by property name in the `PathComplex` and `SDComplex` parameter sets. + ### System.Security.AccessControl.PropagationFlags +The value passed to `-PropagationFlags` is converted to this type and binds by property name in the `PathComplex` and `SDComplex` parameter sets. + ### Security2.ApplyTo +The value passed to `-AppliesTo` is converted to this type and binds by property name in the `PathSimple` and `SDSimple` parameter sets. + ## OUTPUTS ### Security2.FileSystemAccessRule2 +Without `-PassThru` the cmdlet writes nothing. With `-PassThru` the type depends on the parameter set: in the `Path` sets the cmdlet writes all audit entries of the item, explicit and inherited ones, as `Security2.FileSystemAuditRule2` objects, while in the `SecurityDescriptor` sets it writes the access entries of the descriptor as `Security2.FileSystemAccessRule2` objects. Use `Get-NTFSAudit` when you need the audit entries of a security descriptor. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +Writing the SACL requires the Security privilege (`SeSecurityPrivilege`, "Manage auditing and security log"), so run this cmdlet in an elevated session of an account that holds that privilege. Without it, the cmdlet writes a non-terminating `AddAceError` whose message states that a required privilege is not held by the client, and the item is left unchanged. + +If the security descriptor cannot be read or written because access is denied, the cmdlet takes ownership of the item, repeats the operation, and restores the previous owner. If the second attempt fails as well, the cmdlet writes an error, and the ownership change is not rolled back. + +The syntax shows `-Path`, `-Account`, and `-AccessRights` as positional parameters, but `-Account` and `-AccessRights` are both declared at position 2. A command that passes them positionally therefore fails with the error that positional parameters cannot be bound because no names were given, and `Get-Command Add-NTFSAudit -Syntax` leaves `-Account` out for the same reason. Pass `-Account` and `-AccessRights` by name, as the examples above do. + +An audit entry alone does not create events. Windows writes the events to the security log only while the "Audit object access" policy, or the corresponding "Audit File System" advanced audit policy, is enabled for success, failure, or both. That policy is a Windows setting and is not managed by this module. + ## RELATED LINKS + +[Get-NTFSAudit](Get-NTFSAudit.md) + +[Remove-NTFSAudit](Remove-NTFSAudit.md) + +[Clear-NTFSAudit](Clear-NTFSAudit.md) + +[Get-NTFSOrphanedAudit](Get-NTFSOrphanedAudit.md) + +[Add-NTFSAccess](Add-NTFSAccess.md) + +[Set-NTFSSecurityDescriptor](Set-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Clear-NTFSAccess.md b/Docs/Cmdlets/Clear-NTFSAccess.md index 5eb4198..7c2278b 100644 --- a/Docs/Cmdlets/Clear-NTFSAccess.md +++ b/Docs/Cmdlets/Clear-NTFSAccess.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Clear-NTFSAccess.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -Removes all access control entries from a file or folder. +Removes all explicit access control entries from a file or folder. ## SYNTAX @@ -25,23 +25,54 @@ Clear-NTFSAccess [-SecurityDescriptor] [-DisableInherita ## DESCRIPTION -{{ Fill in the Description }} +Removes every access control entry (ACE) that is defined on a file or a folder itself. Inherited entries are not touched and continue to apply, so an item whose permissions come from its parent folder keeps them. + +`-DisableInheritance` additionally protects the item from its parents and discards the inherited entries instead of copying them into the item. An item that is cleared with `-DisableInheritance` therefore ends up with an empty DACL, which denies access to everyone; only its owner can still change the permissions. Grant the required rights with `Add-NTFSAccess` right after clearing, or re-enable inheritance with `Enable-NTFSAccessInheritance`. + +In the `Path` parameter set the cmdlet reads the item from disk and writes the changed DACL back immediately; relative paths are resolved against the current location. In the `SD` parameter set it changes a `Security2.FileSystemSecurity2` object returned by `Get-NTFSSecurityDescriptor` in memory until `Set-NTFSSecurityDescriptor` writes it back. The cmdlet writes no output, and a failure on one item is reported as a non-terminating error while the remaining items are processed. ## EXAMPLES -### Example 1 +### Example 1: Remove the explicit permissions of a folder + +```PowerShell +PS C:\> Clear-NTFSAccess -Path C:\Data +``` + +This command removes all access control entries that are defined on `C:\Data` itself. The entries that the folder inherits from its parent remain in effect. + +### Example 2: Remove all permissions and break inheritance + +```PowerShell +PS C:\> Clear-NTFSAccess -Path C:\Data -DisableInheritance +``` + +This command removes the explicit entries of `C:\Data` and disables inheritance without copying the inherited entries. The folder is left with an empty DACL and is inaccessible until new permissions are granted. + +### Example 3: Reset the permissions of several folders + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Directory | Clear-NTFSAccess +``` + +This command removes the explicit entries of every subfolder of `C:\Data` so that all of them rely on the permissions inherited from `C:\Data`. + +### Example 4: Rebuild an ACL in memory ```PowerShell -PS C:\> Clear-NTFSAccess -Path C:\Data\ -DisableInheritance +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Clear-NTFSAccess -SecurityDescriptor $sd -DisableInheritance +PS C:\> Add-NTFSAccess -SecurityDescriptor $sd -Account 'BUILTIN\Administrators' -AccessRights FullControl -AppliesTo ThisFolderSubfoldersAndFiles +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd ``` -The above example would remove all access control entries from the folder C:\Data and disable inheritance on the folder as well. +These commands replace the complete ACL of `C:\Data` in one write. The security descriptor is changed in memory, and the file system is only touched by `Set-NTFSSecurityDescriptor`. ## PARAMETERS ### -DisableInheritance -The DisableInheritance parameter defines if you would like to didable the inheritance on the file or folder when clearing permissions. +Indicates that inheritance is disabled after the explicit entries are removed, and that the inherited entries are discarded rather than copied into the item. Without this switch the inherited entries remain in effect. ```yaml Type: SwitchParameter @@ -57,7 +88,7 @@ Accept wildcard characters: False ### -Path -The Path parameter defines where the file or container exists to remove the access control entries from. +Specifies the path of one or more files or folders whose explicit access control entries are removed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`. ```yaml Type: String[] @@ -73,7 +104,7 @@ Accept wildcard characters: False ### -SecurityDescriptor -The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. +Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose explicit access control entries are removed. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system. A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. @@ -96,12 +127,34 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +One or more paths of files or folders, piped by value or by the property `FullName`. + ### Security2.FileSystemSecurity2[] +One or more security descriptors returned by `Get-NTFSSecurityDescriptor`. + ## OUTPUTS ### System.Object +The cmdlet writes nothing. Use `Get-NTFSAccess` to inspect the result. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +If the ACL of an item cannot be written because access is denied, the cmdlet tries once more after making the current account the owner of the item, and restores the previous owner afterwards. Changing the owner of an item requires the Take Ownership and Restore privileges, so this fallback only succeeds in an elevated session of an account that holds them. + ## RELATED LINKS + +[Add-NTFSAccess](Add-NTFSAccess.md) + +[Get-NTFSAccess](Get-NTFSAccess.md) + +[Remove-NTFSAccess](Remove-NTFSAccess.md) + +[Disable-NTFSAccessInheritance](Disable-NTFSAccessInheritance.md) + +[Enable-NTFSAccessInheritance](Enable-NTFSAccessInheritance.md) + +[Set-NTFSSecurityDescriptor](Set-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Clear-NTFSAudit.md b/Docs/Cmdlets/Clear-NTFSAudit.md index 7b2ded4..7acbcf7 100644 --- a/Docs/Cmdlets/Clear-NTFSAudit.md +++ b/Docs/Cmdlets/Clear-NTFSAudit.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Clear-NTFSAudit.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Removes all explicit audit entries from a file or folder. ## SYNTAX @@ -25,23 +25,53 @@ Clear-NTFSAudit [-SecurityDescriptor] [-DisableInheritan ## DESCRIPTION -{{ Fill in the Description }} +The `Clear-NTFSAudit` cmdlet removes every audit entry that is set on a file or folder itself from its system access control list (SACL). Entries that the item inherits from a parent folder are left alone, because they are stored on that parent. Add `-DisableInheritance` to protect the item from its parent and to drop the inherited entries as well, which leaves the item without any auditing. + +In the `Path` parameter set the cmdlet reads the security descriptor of every item in `-Path`, removes the entries, and writes the descriptor back right away. Relative paths are resolved against the current location, and the parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it. In the `SD` parameter set the cmdlet changes an in-memory `Security2.FileSystemSecurity2` object that `Get-NTFSSecurityDescriptor` returned, and the change reaches the file system only when you pass the object to `Set-NTFSSecurityDescriptor`. + +To remove a single audit entry instead of all of them, use `Remove-NTFSAudit`. The cmdlet writes no object; use `Get-NTFSAudit` to check the result. ## EXAMPLES -### Example 1 +### Example 1: Remove the explicit audit entries of a folder + +```PowerShell +PS C:\> Clear-NTFSAudit -Path C:\Data +``` + +This command removes every audit entry that is set on `C:\Data` itself. The entries that the folder inherits from its parent stay in place. + +### Example 2: Remove all auditing from a folder + +```PowerShell +PS C:\> Clear-NTFSAudit -Path C:\Data -DisableInheritance +``` + +This command removes the explicit audit entries of `C:\Data` and then stops the folder from inheriting audit entries, discarding the inherited entries instead of copying them to the folder. + +### Example 3: Clear the audit entries of a folder tree + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Clear-NTFSAudit +``` + +This command pipes every item below `C:\Data` into `Clear-NTFSAudit` and removes the audit entries that are set on those items themselves. + +### Example 4: Clear the audit entries of a security descriptor ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Clear-NTFSAudit -SecurityDescriptor $sd +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd ``` -{{ Add example description here }} +This command removes the explicit audit entries from the in-memory security descriptor of `C:\Data` and then writes the descriptor back to the file system. ## PARAMETERS ### -DisableInheritance -{{ Fill DisableInheritance Description }} +Indicates that the item no longer inherits audit entries from its parent folder. The inherited entries are discarded rather than copied to the item, so the item is left with no audit entries at all. Without this switch the item keeps inheriting audit entries from its parent. ```yaml Type: SwitchParameter @@ -57,7 +87,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the files or folders whose audit entries are removed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. ```yaml Type: String[] @@ -73,9 +103,7 @@ Accept wildcard characters: False ### -SecurityDescriptor -The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. - -A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. +Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet removes the explicit audit entries from the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. ```yaml Type: FileSystemSecurity2[] @@ -96,12 +124,36 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe paths to this cmdlet, or objects that have a `Path` or `FullName` property, such as the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2`. + ### Security2.FileSystemSecurity2[] +You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + ## OUTPUTS ### System.Object +This cmdlet writes nothing to the pipeline. Use `Get-NTFSAudit` to check which audit entries an item has after the operation. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +Reading and writing the SACL requires the Security privilege (`SeSecurityPrivilege`, "Manage auditing and security log"), so run this cmdlet in an elevated session of an account that holds that privilege. Without that privilege the cmdlet reads the security descriptor without its SACL, finds no audit entries to remove, and finishes without an error although nothing was changed. `-DisableInheritance` fails in that situation with a `ClearAclError` whose message states that a required privilege is not held by the client. + +If the security descriptor cannot be read or written because access is denied, the cmdlet takes ownership of the item, repeats the operation, and restores the previous owner. If the second attempt fails as well, the cmdlet writes an error, and the ownership change is not rolled back. + ## RELATED LINKS + +[Get-NTFSAudit](Get-NTFSAudit.md) + +[Add-NTFSAudit](Add-NTFSAudit.md) + +[Remove-NTFSAudit](Remove-NTFSAudit.md) + +[Disable-NTFSAuditInheritance](Disable-NTFSAuditInheritance.md) + +[Enable-NTFSAuditInheritance](Enable-NTFSAuditInheritance.md) + +[Clear-NTFSAccess](Clear-NTFSAccess.md) diff --git a/Docs/Cmdlets/Copy-Item2.md b/Docs/Cmdlets/Copy-Item2.md index a62de6e..4c93df3 100644 --- a/Docs/Cmdlets/Copy-Item2.md +++ b/Docs/Cmdlets/Copy-Item2.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Copy-Item2.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Copies a file to another location, including paths longer than 260 characters. ## SYNTAX @@ -20,17 +20,47 @@ Copy-Item2 [-Path] [-Destination] [-Force] [-PassThru Copy-Item2 -Path C:\Data\report.docx -Destination C:\Data\Archive +``` + +Copies `report.docx` into the existing folder `C:\Data\Archive`, where it keeps its name. The command fails if `C:\Data\Archive\report.docx` already exists. + +### Example 2: Copy and rename a file in one step ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Copy-Item2 -Path C:\Data\report.docx -Destination C:\Data\Archive\report-2026.docx -Force ``` -{{ Add example description here }} +Copies the file under a new name and, because of `-Force`, replaces an existing `report-2026.docx`. + +### Example 3: Copy files with very long paths + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data\Projects -Recurse -File -Filter '*.log' | Copy-Item2 -Destination C:\Data\Logs -Force +``` + +Collects every log file below `C:\Data\Projects`, no matter how long its path is, and copies them all into `C:\Data\Logs`. Because each file keeps only its name, the files from the different source folders end up side by side in the target folder. + +### Example 4: Preview a copy operation + +```PowerShell +PS C:\> Copy-Item2 -Path C:\Data\report.docx -Destination C:\Data\Archive -WhatIf +``` + +Shows which operation the cmdlet would perform without copying anything. ## PARAMETERS @@ -52,7 +82,7 @@ Accept wildcard characters: False ### -Destination -{{ Fill Destination Description }} +Specifies the target of the copy operation. If the value names an existing folder, the cmdlet copies the item into that folder under its current name; otherwise the value is the full path of the new item. The path is resolved against the current location once, when the cmdlet starts, so pass an absolute path when you supply `-Destination` through the pipeline. ```yaml Type: String @@ -68,7 +98,7 @@ Accept wildcard characters: False ### -Force -{{ Fill Force Description }} +Indicates that the cmdlet overwrites an existing destination file. Without `-Force`, an existing file causes the error `DestinationFileAlreadyExists` and the item is not copied. ```yaml Type: SwitchParameter @@ -84,7 +114,7 @@ Accept wildcard characters: False ### -PassThru -{{ Fill PassThru Description }} +Specifies whether the cmdlet returns an object for each item that it copied. This parameter is typed `Boolean` rather than a switch, so it needs an explicit value, as in `-PassThru $true`. By default, the cmdlet produces no output. After a successful file copy, the returned object describes the file at the destination path. ```yaml Type: Boolean @@ -100,7 +130,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of one or more items to copy. Relative paths are resolved against the current location, and wildcard characters are not supported. The parameter accepts pipeline input by value and by the property name `FullName`, so you can pipe the output of `Get-ChildItem2` or `Get-Item2` into this cmdlet. ```yaml Type: String[] @@ -138,12 +168,34 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more paths to this cmdlet, either as strings or as objects that have a `FullName` property, such as the output of `Get-ChildItem2` or `Get-Item2`. + ### System.String +You can pipe an object that has a `Destination` property to supply the target of the copy operation. + ## OUTPUTS ### System.Object +By default this cmdlet returns nothing. With `-PassThru $true` it returns an `Alphaleonis.Win32.Filesystem.FileInfo` or `Alphaleonis.Win32.Filesystem.DirectoryInfo` object for each item that it copied. + ## NOTES +`Copy-Item2` copies through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), which is why it handles source and destination paths that exceed the 260-character `MAX_PATH` limit of the built-in `Copy-Item` cmdlet. + +Copying a folder that contains files currently fails with a `CopyError` that reports a `DirectoryNotFoundException` for the first file in the folder. Copy files individually, for example by piping `Get-ChildItem2 -Recurse -File` into this cmdlet, and create the target folders beforehand. + +If a path in `-Path` does not exist or the destination file exists and `-Force` is missing, the cmdlet writes a non-terminating error and skips the remaining paths that were passed in the same call. Items that arrive one by one through the pipeline are not affected, because each of them is processed separately. + ## RELATED LINKS + +[Move-Item2](Move-Item2.md) + +[Remove-Item2](Remove-Item2.md) + +[Get-ChildItem2](Get-ChildItem2.md) + +[Get-Item2](Get-Item2.md) + +[Test-Path2](Test-Path2.md) diff --git a/Docs/Cmdlets/Disable-NTFSAccessInheritance.md b/Docs/Cmdlets/Disable-NTFSAccessInheritance.md index be0fbf4..6c9d98b 100644 --- a/Docs/Cmdlets/Disable-NTFSAccessInheritance.md +++ b/Docs/Cmdlets/Disable-NTFSAccessInheritance.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Disable-NTFSAccessInheritance.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Blocks the inheritance of access rules on a file or folder. ## SYNTAX @@ -27,23 +27,55 @@ Disable-NTFSAccessInheritance [-SecurityDescriptor] [-Re ## DESCRIPTION -{{ Fill in the Description }} +The `Disable-NTFSAccessInheritance` cmdlet protects the discretionary access control list (DACL) of a file or folder, so that the access rules of the parent folder no longer apply to the item. From then on, only the access rules stored in the item's own DACL grant or deny access to it. + +By default, the rules that the item currently inherits are copied into its DACL before inheritance is blocked. The effective permissions therefore stay the same, and the copies become explicit rules that you can change or remove individually. The `-RemoveInheritedAccessRules` switch discards the inherited rules instead of copying them. If the item has no explicit rules of its own, that leaves an empty DACL, which denies access to everyone except the owner, so check the item with `Get-NTFSAccess` before you use the switch. + +In the `Path` parameter set the cmdlet reads the access section of the item's security descriptor, changes it, and writes it back to disk immediately. In the `SecurityDescriptor` parameter set it changes the `Security2.FileSystemSecurity2` object in memory only; nothing reaches the file system until you pass that object to `Set-NTFSSecurityDescriptor`. + +`-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. Relative paths are resolved against the current location. The cmdlet affects only the access rules; use `Disable-NTFSAuditInheritance` for the audit rules. ## EXAMPLES -### Example 1 +### Example 1: Block inheritance and keep the current permissions + +```PowerShell +PS C:\> Disable-NTFSAccessInheritance -Path C:\Data\Projects +``` + +This command protects the DACL of `C:\Data\Projects` and copies the access rules that the folder inherited from `C:\Data` into its own DACL. The effective permissions do not change, but later permission changes on `C:\Data` no longer reach the folder. + +### Example 2: Block inheritance and discard the inherited rules ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Disable-NTFSAccessInheritance -Path C:\Data\Projects -RemoveInheritedAccessRules -PassThru ``` -{{ Add example description here }} +This command protects the DACL and removes the inherited access rules instead of copying them, which leaves only the rules that were already explicit on the folder. `-PassThru` returns the resulting state, in which `AccessInheritanceEnabled` is `$false`. + +### Example 3: Block inheritance on every subfolder + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Directory | Disable-NTFSAccessInheritance -PassThru +``` + +This command pipes every subfolder of `C:\Data` to the cmdlet, which binds the `FullName` property of each item to `-Path`. Each folder keeps its current permissions as explicit rules, and `-PassThru` reports the new state of each of them. + +### Example 4: Change a security descriptor in memory + +```PowerShell +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Projects +PS C:\> Disable-NTFSAccessInheritance -SecurityDescriptor $sd +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd +``` + +The first two commands read the security descriptor and protect its DACL in memory, which does not change anything on disk. The third command writes the descriptor back and applies the change. ## PARAMETERS ### -PassThru -{{ Fill PassThru Description }} +Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. ```yaml Type: SwitchParameter @@ -59,7 +91,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files or folders whose access inheritance is blocked. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline. ```yaml Type: String[] @@ -75,7 +107,7 @@ Accept wildcard characters: False ### -RemoveInheritedAccessRules -{{ Fill RemoveInheritedAccessRules Description }} +Indicates that the access rules the item currently inherits are discarded. By default, when the switch is omitted, those rules are copied into the item's own DACL as explicit rules and the effective permissions stay the same. With the switch, the item keeps only the access rules that were already explicit on it, which can be none at all. ```yaml Type: SwitchParameter @@ -95,6 +127,8 @@ The SecurityDescriptor parameter allows passing an security descriptor or an arr A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. +This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + ```yaml Type: FileSystemSecurity2[] Parameter Sets: SecurityDescriptor @@ -114,12 +148,36 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet. + ### Security2.FileSystemSecurity2[] +You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + ## OUTPUTS ### System.Object +By default this cmdlet returns no output. With `-PassThru` it writes one `Security2.FileSystemInheritanceInfo` object per item, which reports the `AccessInheritanceEnabled` and `AuditInheritanceEnabled` state after the change. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +Blocking access inheritance requires permission to change the DACL of the item, which the owner of an item always has. If the descriptor cannot be opened, the cmdlet takes ownership of the item, applies the change, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; otherwise the cmdlet writes an error and continues with the next item. + +A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths. + ## RELATED LINKS + +[Enable-NTFSAccessInheritance](Enable-NTFSAccessInheritance.md) + +[Get-NTFSInheritance](Get-NTFSInheritance.md) + +[Set-NTFSInheritance](Set-NTFSInheritance.md) + +[Disable-NTFSAuditInheritance](Disable-NTFSAuditInheritance.md) + +[Get-NTFSAccess](Get-NTFSAccess.md) + +[Set-NTFSSecurityDescriptor](Set-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Disable-NTFSAuditInheritance.md b/Docs/Cmdlets/Disable-NTFSAuditInheritance.md index 8b31e55..59d9246 100644 --- a/Docs/Cmdlets/Disable-NTFSAuditInheritance.md +++ b/Docs/Cmdlets/Disable-NTFSAuditInheritance.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Disable-NTFSAuditInheritance.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Blocks the inheritance of audit rules on a file or folder. ## SYNTAX @@ -27,23 +27,55 @@ Disable-NTFSAuditInheritance [-SecurityDescriptor] [-Rem ## DESCRIPTION -{{ Fill in the Description }} +The `Disable-NTFSAuditInheritance` cmdlet protects the system access control list (SACL) of a file or folder, so that the audit rules of the parent folder no longer apply to the item. From then on, only the audit rules stored in the item's own SACL decide which access attempts are written to the security event log. + +By default, the audit rules that the item currently inherits are copied into its SACL before inheritance is blocked, so the auditing behavior stays the same. The `-RemoveInheritedAccessRules` switch discards the inherited audit rules instead of copying them, which leaves only the audit rules that were already explicit on the item. Despite its name, the switch acts on audit rules, not on access rules. + +In the `Path` parameter set the cmdlet reads the audit section of the item's security descriptor, changes it, and writes it back to disk immediately. In the `SecurityDescriptor` parameter set it changes the `Security2.FileSystemSecurity2` object in memory only; nothing reaches the file system until you pass that object to `Set-NTFSSecurityDescriptor`. + +Reading and writing the audit section requires the Security privilege, so run this cmdlet in an elevated session. `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet affects only the audit rules; use `Disable-NTFSAccessInheritance` for the access rules. ## EXAMPLES -### Example 1 +### Example 1: Block audit inheritance and keep the current auditing + +```PowerShell +PS C:\> Disable-NTFSAuditInheritance -Path C:\Data\Projects +``` + +This command protects the SACL of `C:\Data\Projects` and copies the audit rules that the folder inherited from `C:\Data` into its own SACL. Auditing continues to work the same way, but later changes to the audit rules of `C:\Data` no longer reach the folder. + +### Example 2: Block audit inheritance and discard the inherited rules + +```PowerShell +PS C:\> Disable-NTFSAuditInheritance -Path C:\Data\Projects -RemoveInheritedAccessRules -PassThru +``` + +This command protects the SACL and removes the inherited audit rules instead of copying them, so the folder is audited only by the rules that were already explicit on it. `-PassThru` returns the resulting state, in which `AuditInheritanceEnabled` is `$false`. + +### Example 3: Block audit inheritance on every subfolder + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Directory | Disable-NTFSAuditInheritance +``` + +This command pipes every subfolder of `C:\Data` to the cmdlet, which binds the `FullName` property of each item to `-Path`. Each folder keeps its current audit rules as explicit rules. + +### Example 4: Change a security descriptor in memory ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Projects +PS C:\> Disable-NTFSAuditInheritance -SecurityDescriptor $sd +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd ``` -{{ Add example description here }} +The first two commands read the security descriptor and protect its SACL in memory, which does not change anything on disk. The third command writes the descriptor back and applies the change. ## PARAMETERS ### -PassThru -{{ Fill PassThru Description }} +Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. ```yaml Type: SwitchParameter @@ -59,7 +91,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files or folders whose audit inheritance is blocked. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline. ```yaml Type: String[] @@ -75,7 +107,7 @@ Accept wildcard characters: False ### -RemoveInheritedAccessRules -{{ Fill RemoveInheritedAccessRules Description }} +Indicates that the audit rules the item currently inherits are discarded. Despite its name, the switch acts on the audit rules in the SACL, not on access rules. By default, when the switch is omitted, the inherited audit rules are copied into the item's own SACL as explicit rules and auditing continues unchanged. ```yaml Type: SwitchParameter @@ -95,6 +127,8 @@ The SecurityDescriptor parameter allows passing an security descriptor or an arr A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. +This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + ```yaml Type: FileSystemSecurity2[] Parameter Sets: SecurityDescriptor @@ -114,12 +148,38 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet. + ### Security2.FileSystemSecurity2[] +You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + ## OUTPUTS ### System.Object +By default this cmdlet returns no output. With `-PassThru` it writes one `Security2.FileSystemInheritanceInfo` object per item, which reports the `AccessInheritanceEnabled` and `AuditInheritanceEnabled` state after the change. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +The audit section of a security descriptor can only be read and written with the Security privilege (`SeSecurityPrivilege`), which an account can only use in an elevated session. Without it, the cmdlet writes a non-terminating error that reports Windows error 1314, "A required privilege is not held by the client", and the audit rules of the item stay unchanged. + +If the descriptor cannot be opened because the account has no permission to the item, the cmdlet takes ownership of the item, applies the change, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; a missing Security privilege is not an access problem and is not repaired by it. + +A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths. + ## RELATED LINKS + +[Enable-NTFSAuditInheritance](Enable-NTFSAuditInheritance.md) + +[Get-NTFSInheritance](Get-NTFSInheritance.md) + +[Set-NTFSInheritance](Set-NTFSInheritance.md) + +[Disable-NTFSAccessInheritance](Disable-NTFSAccessInheritance.md) + +[Get-NTFSAudit](Get-NTFSAudit.md) + +[Set-NTFSSecurityDescriptor](Set-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Disable-Privileges.md b/Docs/Cmdlets/Disable-Privileges.md index 8cb7f0a..97b1fcc 100644 --- a/Docs/Cmdlets/Disable-Privileges.md +++ b/Docs/Cmdlets/Disable-Privileges.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Disable-Privileges.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Disables the file system privileges in the access token of the current PowerShell process. ## SYNTAX @@ -19,23 +19,54 @@ Disable-Privileges [-PassThru] [] ## DESCRIPTION -{{ Fill in the Description }} +The `Disable-Privileges` cmdlet disables the Take Ownership, Restore, Backup, and Security privileges in the access token of the current PowerShell process. It is the counterpart of `Enable-Privileges`, which leaves those privileges enabled for the rest of the session. + +Before it changes anything, the cmdlet checks whether at least one of the Take Ownership, Restore, and Backup privileges is currently enabled. If none of them is, it writes a non-terminating error that reports that the privileges are not enabled and does nothing. This is what happens in a session that never enabled the privileges or that does not hold them at all. A privilege that cannot be disabled produces a warning, and the cmdlet continues with the remaining privileges. + +The change affects nothing but the access token of the PowerShell process that runs the cmdlet. Disabling a privilege does not remove it from the account; it only takes it out of use until something enables it again, which the file system cmdlets of the module do on their own while they run. ## EXAMPLES -### Example 1 +### Example 1: Disable the privileges in the current session + +```PowerShell +PS C:\> Disable-Privileges +``` + +This command disables the Take Ownership, Restore, Backup, and Security privileges in the current PowerShell process. + +### Example 2: Disable the privileges and return the result + +```PowerShell +PS C:\> Disable-Privileges -PassThru +``` + +This command disables the privileges and returns all privileges of the current process, so you can confirm their new state right away. + +### Example 3: Enable the privileges for a task and turn them off afterwards ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Enable-Privileges +PS C:\> Set-NTFSOwner -Path C:\Data -Account 'BUILTIN\Administrators' +PS C:\> Disable-Privileges ``` -{{ Add example description here }} +The privileges stay enabled while the owner of the folder is changed and are turned off again by the last command, which returns the session to its normal rights. + +### Example 4: Check the state of the privileges after disabling them + +```PowerShell +PS C:\> Disable-Privileges +PS C:\> Get-Privileges | Where-Object { $_.Privilege -in 'Backup', 'Restore', 'TakeOwnership', 'Security' } +``` + +The second command lists the four file system privileges with their current state, which shows that they are no longer enabled. ## PARAMETERS ### -PassThru -{{ Fill PassThru Description }} +Indicates that the cmdlet returns the privileges of the current process after disabling them. Without this parameter, the cmdlet produces no output. ```yaml Type: SwitchParameter @@ -56,10 +87,24 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### None +This cmdlet does not accept pipeline input. + ## OUTPUTS ### ProcessPrivileges.PrivilegeAndAttributes +With `-PassThru`, the cmdlet writes the privilege collection of the current process. The pipeline enumerates it into one `ProcessPrivileges.PrivilegeAndAttributes` object per privilege, each with a `Privilege`, a `PrivilegeAttributes`, and a `PrivilegeState` property. Without `-PassThru`, the cmdlet writes nothing. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), the file system cmdlets of the module try to enable the Backup, Restore, Take Ownership, and Security privileges while they run and disable the privileges they enabled when they finish. You therefore need `Disable-Privileges` only after an explicit `Enable-Privileges`. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. + ## RELATED LINKS + +[Enable-Privileges](Enable-Privileges.md) + +[Get-Privileges](Get-Privileges.md) + +[Set-NTFSOwner](Set-NTFSOwner.md) + +[Get-NTFSSecurityDescriptor](Get-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Enable-NTFSAccessInheritance.md b/Docs/Cmdlets/Enable-NTFSAccessInheritance.md index 1d2577c..2d8fb50 100644 --- a/Docs/Cmdlets/Enable-NTFSAccessInheritance.md +++ b/Docs/Cmdlets/Enable-NTFSAccessInheritance.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Enable-NTFSAccessInheritance.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Restores the inheritance of access rules on a file or folder. ## SYNTAX @@ -26,23 +26,55 @@ Enable-NTFSAccessInheritance [-SecurityDescriptor] [-Pas ## DESCRIPTION -{{ Fill in the Description }} +The `Enable-NTFSAccessInheritance` cmdlet removes the protection from the discretionary access control list (DACL) of a file or folder, so that the item inherits access rules from its parent folder again. + +By default, the access rules that are stored directly on the item are kept, and the inherited rules are added to them. An item that was processed by `Disable-NTFSAccessInheritance` therefore ends up with the inherited rules twice: once as the explicit copies that were created when inheritance was blocked, and once as true inherited rules. The `-RemoveExplicitAccessRules` switch deletes every access rule that is stored directly on the item, which leaves only the inherited rules and restores the permission model of the parent folder. + +In the `Path` parameter set the cmdlet reads the access section of the item's security descriptor, changes it, and writes it back to disk immediately. In the `SecurityDescriptor` parameter set it changes the `Security2.FileSystemSecurity2` object in memory only; nothing reaches the file system until you pass that object to `Set-NTFSSecurityDescriptor`. + +`-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. Relative paths are resolved against the current location. The cmdlet affects only the access rules; use `Enable-NTFSAuditInheritance` for the audit rules. ## EXAMPLES -### Example 1 +### Example 1: Restore inheritance and keep the explicit rules + +```PowerShell +PS C:\> Enable-NTFSAccessInheritance -Path C:\Data\Projects +``` + +This command lets `C:\Data\Projects` inherit the access rules of `C:\Data` again. The rules that are stored directly on the folder stay in place and are added to the inherited ones. + +### Example 2: Restore inheritance and drop the explicit rules ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Enable-NTFSAccessInheritance -Path C:\Data\Projects -RemoveExplicitAccessRules -PassThru ``` -{{ Add example description here }} +This command removes every access rule that is stored directly on the folder and lets it inherit from `C:\Data` again, so the folder ends up with exactly the permissions of its parent. `-PassThru` returns the resulting state, in which `AccessInheritanceEnabled` is `$true`. + +### Example 3: Repair a whole folder tree + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSInheritance | Where-Object { -not $_.AccessInheritanceEnabled } | Enable-NTFSAccessInheritance -RemoveExplicitAccessRules +``` + +This command finds every item below `C:\Data` whose access inheritance is blocked and restores it. `Get-NTFSInheritance` writes objects with a `FullName` property, which binds to `-Path`. + +### Example 4: Change a security descriptor in memory + +```PowerShell +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Projects +PS C:\> Enable-NTFSAccessInheritance -SecurityDescriptor $sd -RemoveExplicitAccessRules +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd +``` + +The first two commands read the security descriptor and restore inheritance in memory, which does not change anything on disk. The third command writes the descriptor back and applies the change. ## PARAMETERS ### -PassThru -{{ Fill PassThru Description }} +Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. ```yaml Type: SwitchParameter @@ -58,7 +90,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files or folders whose access inheritance is restored. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline. ```yaml Type: String[] @@ -74,7 +106,7 @@ Accept wildcard characters: False ### -RemoveExplicitAccessRules -{{ Fill RemoveExplicitAccessRules Description }} +Indicates that every access rule stored directly on the item is removed when inheritance is restored, so that the item ends up with the inherited rules only. By default, when the switch is omitted, the explicit rules are kept and the inherited rules are added to them, which usually duplicates the rules that `Disable-NTFSAccessInheritance` copied earlier. ```yaml Type: SwitchParameter @@ -94,6 +126,8 @@ The SecurityDescriptor parameter allows passing an security descriptor or an arr A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. +This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + ```yaml Type: FileSystemSecurity2[] Parameter Sets: SecurityDescriptor @@ -113,12 +147,36 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet. + ### Security2.FileSystemSecurity2[] +You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + ## OUTPUTS ### System.Object +By default this cmdlet returns no output. With `-PassThru` it writes one `Security2.FileSystemInheritanceInfo` object per item, which reports the `AccessInheritanceEnabled` and `AuditInheritanceEnabled` state after the change. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +Restoring access inheritance requires permission to change the DACL of the item, which the owner of an item always has. If the descriptor cannot be opened, the cmdlet takes ownership of the item, applies the change, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; otherwise the cmdlet writes an error and continues with the next item. + +A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths. + ## RELATED LINKS + +[Disable-NTFSAccessInheritance](Disable-NTFSAccessInheritance.md) + +[Get-NTFSInheritance](Get-NTFSInheritance.md) + +[Set-NTFSInheritance](Set-NTFSInheritance.md) + +[Enable-NTFSAuditInheritance](Enable-NTFSAuditInheritance.md) + +[Get-NTFSAccess](Get-NTFSAccess.md) + +[Set-NTFSSecurityDescriptor](Set-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Enable-NTFSAuditInheritance.md b/Docs/Cmdlets/Enable-NTFSAuditInheritance.md index 5e2af62..fec40fe 100644 --- a/Docs/Cmdlets/Enable-NTFSAuditInheritance.md +++ b/Docs/Cmdlets/Enable-NTFSAuditInheritance.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Enable-NTFSAuditInheritance.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Restores the inheritance of audit rules on a file or folder. ## SYNTAX @@ -26,23 +26,55 @@ Enable-NTFSAuditInheritance [-SecurityDescriptor] [-Pass ## DESCRIPTION -{{ Fill in the Description }} +The `Enable-NTFSAuditInheritance` cmdlet removes the protection from the system access control list (SACL) of a file or folder, so that the item inherits audit rules from its parent folder again. + +By default, the audit rules that are stored directly on the item are kept, and the inherited rules are added to them. An item that was processed by `Disable-NTFSAuditInheritance` therefore ends up with the inherited audit rules twice: once as the explicit copies that were created when inheritance was blocked, and once as true inherited rules. The `-RemoveExplicitAccessRules` switch deletes every audit rule that is stored directly on the item, which leaves only the inherited ones. Despite its name, the switch acts on audit rules, not on access rules. + +In the `Path` parameter set the cmdlet reads the audit section of the item's security descriptor, changes it, and writes it back to disk immediately. In the `SecurityDescriptor` parameter set it changes the `Security2.FileSystemSecurity2` object in memory only; nothing reaches the file system until you pass that object to `Set-NTFSSecurityDescriptor`. + +Reading and writing the audit section requires the Security privilege, so run this cmdlet in an elevated session. `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet affects only the audit rules; use `Enable-NTFSAccessInheritance` for the access rules. ## EXAMPLES -### Example 1 +### Example 1: Restore audit inheritance and keep the explicit rules + +```PowerShell +PS C:\> Enable-NTFSAuditInheritance -Path C:\Data\Projects +``` + +This command lets `C:\Data\Projects` inherit the audit rules of `C:\Data` again. The audit rules that are stored directly on the folder stay in place and are added to the inherited ones. + +### Example 2: Restore audit inheritance and drop the explicit rules + +```PowerShell +PS C:\> Enable-NTFSAuditInheritance -Path C:\Data\Projects -RemoveExplicitAccessRules -PassThru +``` + +This command removes every audit rule that is stored directly on the folder and lets it inherit from `C:\Data` again, so the folder is audited exactly like its parent. `-PassThru` returns the resulting state, in which `AuditInheritanceEnabled` is `$true`. + +### Example 3: Repair a whole folder tree + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSInheritance | Where-Object { $_.AuditInheritanceEnabled -eq $false } | Enable-NTFSAuditInheritance -RemoveExplicitAccessRules +``` + +This command finds every item below `C:\Data` whose audit inheritance is blocked and restores it. The comparison with `$false` is deliberate: `AuditInheritanceEnabled` is `$null` for items whose audit section could not be read, and those items are skipped instead of being processed. + +### Example 4: Change a security descriptor in memory ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Projects +PS C:\> Enable-NTFSAuditInheritance -SecurityDescriptor $sd -RemoveExplicitAccessRules +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd ``` -{{ Add example description here }} +The first two commands read the security descriptor and restore audit inheritance in memory, which does not change anything on disk. The third command writes the descriptor back and applies the change. ## PARAMETERS ### -PassThru -{{ Fill PassThru Description }} +Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. ```yaml Type: SwitchParameter @@ -58,7 +90,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files or folders whose audit inheritance is restored. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline. ```yaml Type: String[] @@ -74,7 +106,7 @@ Accept wildcard characters: False ### -RemoveExplicitAccessRules -{{ Fill RemoveExplicitAccessRules Description }} +Indicates that every audit rule stored directly on the item is removed when inheritance is restored, so that the item ends up with the inherited audit rules only. Despite its name, the switch acts on the audit rules in the SACL, not on access rules. By default, when the switch is omitted, the explicit audit rules are kept and the inherited rules are added to them, which usually duplicates the rules that `Disable-NTFSAuditInheritance` copied earlier. ```yaml Type: SwitchParameter @@ -94,6 +126,8 @@ The SecurityDescriptor parameter allows passing an security descriptor or an arr A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. +This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + ```yaml Type: FileSystemSecurity2[] Parameter Sets: SecurityDescriptor @@ -113,12 +147,38 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet. + ### Security2.FileSystemSecurity2[] +You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + ## OUTPUTS ### System.Object +By default this cmdlet returns no output. With `-PassThru` it writes one `Security2.FileSystemInheritanceInfo` object per item, which reports the `AccessInheritanceEnabled` and `AuditInheritanceEnabled` state after the change. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +The audit section of a security descriptor can only be read and written with the Security privilege (`SeSecurityPrivilege`), which an account can only use in an elevated session. Without it, the cmdlet writes a non-terminating error that reports Windows error 1314, "A required privilege is not held by the client", and the audit rules of the item stay unchanged. + +If the descriptor cannot be opened because the account has no permission to the item, the cmdlet takes ownership of the item, applies the change, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; a missing Security privilege is not an access problem and is not repaired by it. + +A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths. + ## RELATED LINKS + +[Disable-NTFSAuditInheritance](Disable-NTFSAuditInheritance.md) + +[Get-NTFSInheritance](Get-NTFSInheritance.md) + +[Set-NTFSInheritance](Set-NTFSInheritance.md) + +[Enable-NTFSAccessInheritance](Enable-NTFSAccessInheritance.md) + +[Get-NTFSAudit](Get-NTFSAudit.md) + +[Set-NTFSSecurityDescriptor](Set-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Enable-Privileges.md b/Docs/Cmdlets/Enable-Privileges.md index 81606bb..a8c7fa3 100644 --- a/Docs/Cmdlets/Enable-Privileges.md +++ b/Docs/Cmdlets/Enable-Privileges.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Enable-Privileges.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Enables the file system privileges in the access token of the current PowerShell process. ## SYNTAX @@ -19,23 +19,56 @@ Enable-Privileges [-PassThru] [] ## DESCRIPTION -{{ Fill in the Description }} +The `Enable-Privileges` cmdlet enables the Take Ownership, Restore, Backup, and Security privileges in the access token of the current PowerShell process. Together these privileges let the other cmdlets of the module read and change the security of files and folders that your account has no permissions on, take ownership of them, and work with audit entries. + +The change affects nothing but the access token of the PowerShell process that runs the cmdlet. Other processes, other PowerShell sessions, and the computer configuration stay untouched, and the privileges are gone as soon as the process ends. + +Unlike the other cmdlets of the module, `Enable-Privileges` leaves the privileges enabled after it finishes, which is the point of the cmdlet: the file system cmdlets enable the same privileges only for the duration of a single call. Calling `Enable-Privileges` is therefore useful when you want the privileges to stay enabled for a whole sequence of commands, or when you turned the automatic handling off by setting `EnablePrivileges` to `$false` in the `PrivateData` section of NTFSSecurity.psd1. When you call the cmdlet yourself, it enables the privileges regardless of that setting. + +A privilege can only be enabled when it is present in the access token, which in practice means an elevated session of an account that holds the privilege, such as a member of the local Administrators group. When all four privileges are enabled, the cmdlet writes a verbose message that names them; otherwise it writes a non-terminating error that reports that the requested privileges could not be enabled and that the cmdlets of the module will only work on resources you have access to. ## EXAMPLES -### Example 1 +### Example 1: Enable the privileges for the current session + +```PowerShell +PS C:\> Enable-Privileges +``` + +This command enables the Take Ownership, Restore, Backup, and Security privileges in the current PowerShell process and leaves them enabled. + +### Example 2: Enable the privileges and check the result + +```PowerShell +PS C:\> Enable-Privileges +PS C:\> Get-Privileges | Where-Object { $_.Privilege -in 'Backup', 'Restore', 'TakeOwnership', 'Security' } +``` + +The second command lists the four file system privileges with their current state, which confirms whether the session now holds them in the enabled state. + +### Example 3: Enable the privileges and return them in one step ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Enable-Privileges -PassThru ``` -{{ Add example description here }} +This command enables the privileges and returns all privileges of the current process, so you can see the result without a second call to `Get-Privileges`. + +### Example 4: Work with enabled privileges and turn them off afterwards + +```PowerShell +PS C:\> Enable-Privileges +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOwner +PS C:\> Disable-Privileges +``` + +The privileges stay enabled while the folder tree is read and are turned off again by the last command. Running `Disable-Privileges` when you are done keeps the session at its normal rights. ## PARAMETERS ### -PassThru -{{ Fill PassThru Description }} +Indicates that the cmdlet returns the privileges of the current process after enabling them. Without this parameter, the cmdlet produces no output. ```yaml Type: SwitchParameter @@ -56,10 +89,26 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### None +This cmdlet does not accept pipeline input. + ## OUTPUTS ### ProcessPrivileges.PrivilegeAndAttributes +With `-PassThru`, the cmdlet writes the privilege collection of the current process. The pipeline enumerates it into one `ProcessPrivileges.PrivilegeAndAttributes` object per privilege, each with a `Privilege`, a `PrivilegeAttributes`, and a `PrivilegeState` property. Without `-PassThru`, the cmdlet writes nothing. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), the file system cmdlets of the module try to enable the Backup, Restore, Take Ownership, and Security privileges while they run and disable the privileges they enabled when they finish. `Enable-Privileges` enables the same privileges but keeps them enabled, so they remain available to every later command in the session until you run `Disable-Privileges` or close the session. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. + +The cmdlet reads the `EnablePrivileges` entry from the `PrivateData` section of the module manifest. If that entry is missing or cannot be read as a Boolean value, the cmdlet throws a parse error that points to the manifest. + ## RELATED LINKS + +[Disable-Privileges](Disable-Privileges.md) + +[Get-Privileges](Get-Privileges.md) + +[Set-NTFSOwner](Set-NTFSOwner.md) + +[Get-NTFSSecurityDescriptor](Get-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Get-ChildItem2.md b/Docs/Cmdlets/Get-ChildItem2.md index 4b0a5ba..477c3ae 100644 --- a/Docs/Cmdlets/Get-ChildItem2.md +++ b/Docs/Cmdlets/Get-ChildItem2.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-ChildItem2.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Gets the files and folders in one or more folders, including paths longer than 260 characters. ## SYNTAX @@ -21,23 +21,55 @@ Get-ChildItem2 [[-Path] ] [[-Filter] ] [-Recurse] [-Directory] ## DESCRIPTION -{{ Fill in the Description }} +The `Get-ChildItem2` cmdlet lists the files and folders in the folders that you specify with `-Path`. It returns an `Alphaleonis.Win32.Filesystem.FileInfo` object for every file and an `Alphaleonis.Win32.Filesystem.DirectoryInfo` object for every folder. The cmdlet is the long-path counterpart of the built-in `Get-ChildItem` cmdlet: it enumerates the file system through the AlphaFS library (`Alphaleonis.Win32.Filesystem`) instead of `System.IO`, so it also returns items whose path is longer than the 260-character `MAX_PATH` limit. + +If you omit `-Path`, the cmdlet lists the current location. Relative paths and the `.` and `..` notations are resolved against the current location. Each path must name a folder, and wildcard characters are not supported. The parameter accepts pipeline input by value and by the property name `FullName`, so you can pipe folders from `Get-ChildItem2` or `Get-Item2` into another `Get-ChildItem2` call, and you can pipe the result into `Get-NTFSAccess` and the other NTFSSecurity cmdlets. + +By default the cmdlet returns the immediate content of each folder and omits hidden items. Use `-Recurse` to walk the whole tree, `-Depth` to limit how deep the recursion goes, `-Filter` to restrict the result by name, `-Directory` or `-File` to restrict it by item type, and `-Force`, `-Hidden`, `-System`, `-ReadOnly`, or `-Attributes` to restrict it by file attributes. + +Two settings in the `PrivateData` section of the module manifest change the objects that this cmdlet emits. `GetFileSystemModeProperty` adds the `Mode` property, which shows the directory, archive, read-only, hidden, and system attributes in `darhs` notation. `IdentifyHardLinks` adds a `HardLinkCount` property to every file object. Both are `$true` by default and are read once when the cmdlet starts. + +A folder that the cmdlet cannot read produces a non-terminating error, and the enumeration continues with the next folder. If a folder cannot be opened while `-Recurse` looks for subfolders, the cmdlet reports the problem as a verbose message instead, so run the command with the `-Verbose` common parameter if you need to know which branches were skipped. ## EXAMPLES -### Example 1 +### Example 1: Find files with a path longer than MAX_PATH + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -File | Where-Object { $_.FullName.Length -gt 260 } +``` + +Walks the whole folder tree below `C:\Data` and returns the files whose full path is too long for the built-in `Get-ChildItem` cmdlet. + +### Example 2: Read the permissions of every subfolder ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Directory | Get-NTFSAccess ``` -{{ Add example description here }} +Lists every subfolder of `C:\Data` and pipes the objects to `Get-NTFSAccess`, which binds their `FullName` property to its own `-Path` parameter and returns the access control entries of each folder. + +### Example 3: Limit the depth of a recursive listing + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Depth 1 -Filter '*.log' +``` + +Returns the log files in `C:\Data` and in its immediate subfolders. Without `-Depth`, the command would descend through the entire tree. + +### Example 4: List hidden system files + +```PowerShell +PS C:\> dir2 -Path C:\Data -Attributes Hidden, System +``` + +Uses the `dir2` alias and returns the items of `C:\Data` that have both the hidden and the system attribute. ## PARAMETERS ### -Attributes -{{ Fill Attributes Description }} +Specifies a set of file attributes. The cmdlet returns only the items that have all the attributes you list; separate several values with commas, as in `-Attributes Hidden, System`. When you use this parameter, the cmdlet ignores `-Force`, `-Hidden`, `-System`, and `-ReadOnly`, and it returns matching hidden items without `-Force`. ```yaml Type: FileAttributes @@ -54,7 +86,7 @@ Accept wildcard characters: False ### -Depth -{{ Fill Depth Description }} +Specifies how many additional levels of subfolders a recursive listing covers. `-Depth` takes effect only together with `-Recurse`: `-Depth 0` limits the result to the content of the folders in `-Path`, `-Depth 1` adds one more level of subfolders, and so on. If you omit the parameter, `-Recurse` walks the entire tree. ```yaml Type: Int32 @@ -70,7 +102,7 @@ Accept wildcard characters: False ### -Directory -{{ Fill Directory Description }} +Indicates that the cmdlet returns only folders. If you specify `-Directory` and `-File` together, `-Directory` wins. The parameter restricts the returned items only; `-Recurse` still descends into every subfolder. ```yaml Type: SwitchParameter @@ -86,7 +118,7 @@ Accept wildcard characters: False ### -File -{{ Fill File Description }} +Indicates that the cmdlet returns only files. The parameter is ignored if you also specify `-Directory`. ```yaml Type: SwitchParameter @@ -102,7 +134,7 @@ Accept wildcard characters: False ### -Filter -{{ Fill Filter Description }} +Specifies a name pattern that an item must match to be returned. The pattern supports the `*` and `?` wildcard characters, and the match ignores case. The default value is `*`, which returns every item. The pattern is applied to the name of each item, not to its path, and during a recursive listing it restricts only the returned items; the cmdlet still descends into every subfolder. ```yaml Type: String @@ -111,14 +143,14 @@ Aliases: Required: False Position: 2 -Default value: None +Default value: * Accept pipeline input: False Accept wildcard characters: False ``` ### -Force -{{ Fill Force Description }} +Indicates that the cmdlet also returns hidden items. Without `-Force`, hidden items are left out of the result. The parameter is ignored when you use `-Attributes`. ```yaml Type: SwitchParameter @@ -134,7 +166,7 @@ Accept wildcard characters: False ### -Hidden -{{ Fill Hidden Description }} +Indicates that the cmdlet returns only hidden items. You do not need `-Force` in addition, because `-Hidden` implies it. ```yaml Type: SwitchParameter @@ -150,7 +182,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the folders whose content you want to list. Relative paths are resolved against the current location, and wildcard characters are not supported. If you omit this parameter, the cmdlet lists the current location. A value that points to a file instead of a folder produces an error. ```yaml Type: String[] @@ -166,7 +198,7 @@ Accept wildcard characters: False ### -ReadOnly -{{ Fill ReadOnly Description }} +Indicates that the cmdlet returns only items that have the read-only attribute. Hidden read-only items appear in the result only if you add `-Force`. ```yaml Type: SwitchParameter @@ -182,7 +214,7 @@ Accept wildcard characters: False ### -Recurse -{{ Fill Recurse Description }} +Indicates that the cmdlet lists the content of all subfolders as well. Without `-Recurse`, only the immediate content of each folder in `-Path` is returned. Use `-Depth` to limit how far the recursion goes. ```yaml Type: SwitchParameter @@ -198,7 +230,7 @@ Accept wildcard characters: False ### -SkipMountPoints -{{ Fill SkipMountPoints Description }} +Indicates that the cmdlet does not descend into volume mount points. The mount point itself is still returned as an item of its parent folder. The parameter takes effect only together with `-Recurse`. ```yaml Type: SwitchParameter @@ -214,7 +246,7 @@ Accept wildcard characters: False ### -SkipSymbolicLinks -{{ Fill SkipSymbolicLinks Description }} +Indicates that the cmdlet does not descend into folders that are symbolic links. The link itself is still returned as an item of its parent folder. The parameter takes effect only together with `-Recurse`, and it protects a recursive listing against loops that symbolic links can create. ```yaml Type: SwitchParameter @@ -230,7 +262,7 @@ Accept wildcard characters: False ### -System -{{ Fill System Description }} +Indicates that the cmdlet returns only items that have the system attribute. System files are often hidden as well, so combine this parameter with `-Force` or `-Hidden` to see them. ```yaml Type: SwitchParameter @@ -251,12 +283,38 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more folder paths to this cmdlet, either as strings or as objects that have a `FullName` property, such as the output of `Get-ChildItem2` or `Get-Item2`. + ## OUTPUTS ### Alphaleonis.Win32.Filesystem.FileInfo +The cmdlet returns this object for every file it finds. Depending on the module settings, the object carries the additional properties `Mode` and `HardLinkCount`. + ### Alphaleonis.Win32.Filesystem.DirectoryInfo +The cmdlet returns this object for every folder it finds. Depending on the module settings, the object carries the additional property `Mode`. + ## NOTES +`Get-ChildItem2` enumerates the file system through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), which is why it returns items whose path exceeds the 260-character `MAX_PATH` limit that the built-in `Get-ChildItem` cmdlet is bound to. The objects are AlphaFS objects, not `System.IO` objects, and the other NTFSSecurity cmdlets accept them directly because their `-Path` parameters have the alias `FullName`. + +The module defines the alias `dir2` for this cmdlet. + +The `PrivateData` section of the module manifest `NTFSSecurity.psd1` contains two settings that this cmdlet reads when it starts. `GetFileSystemModeProperty` adds the calculated `Mode` property to every item. `IdentifyHardLinks` adds the `HardLinkCount` property to every file, which requires an extra call into the file system for each file and therefore slows down large listings noticeably. Set either value to `$false` in the manifest and import the module again if you prefer the faster enumeration over the additional properties. + +A folder that cannot be read produces a non-terminating error with the ID `DirUnauthorizedAccessError` for an access denial or `DirUnspecifiedError` for any other failure, and a path that does not exist produces the error `FileNotFound`. In each case the cmdlet continues with the next path. Failures that occur while `-Recurse` collects the subfolders of a folder are reported as verbose messages only, not as errors. + ## RELATED LINKS + +[Get-Item2](Get-Item2.md) + +[Copy-Item2](Copy-Item2.md) + +[Move-Item2](Move-Item2.md) + +[Remove-Item2](Remove-Item2.md) + +[Test-Path2](Test-Path2.md) + +[Get-NTFSAccess](Get-NTFSAccess.md) diff --git a/Docs/Cmdlets/Get-DiskSpace.md b/Docs/Cmdlets/Get-DiskSpace.md index 7b52c52..3369f14 100644 --- a/Docs/Cmdlets/Get-DiskSpace.md +++ b/Docs/Cmdlets/Get-DiskSpace.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-DiskSpace.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Gets size, free space, and cluster information for the volumes of a computer. ## SYNTAX @@ -19,23 +19,61 @@ Get-DiskSpace [[-DriveLetter] ] [] ## DESCRIPTION -{{ Fill in the Description }} +The `Get-DiskSpace` cmdlet returns one `DiskSpaceInfo` object per volume. The object describes how large the volume is, how much space is free, and how the volume is organized into sectors and clusters. + +When you omit `-DriveLetter`, the cmdlet enumerates all volumes of the computer, including volumes that have no drive letter, and returns the ones that report a total size greater than zero. Volumes that report a size of zero, such as an empty removable drive, are skipped silently, and a volume whose details cannot be read produces a warning instead of an object. + +Each returned object exposes the following properties: + +- `DriveName`: the volume the object describes. +- `TotalNumberOfBytes`, `TotalNumberOfFreeBytes`, and `FreeBytesAvailable`: the size of the volume, the free space on it, and the free space that is available to the account that runs the cmdlet, all as 64-bit byte counts. +- `TotalSizeUnitSize`, `UsedSpaceUnitSize`, and `AvailableFreeSpaceUnitSize`: the same figures formatted as readable strings. +- `UsedSpacePercent` and `AvailableFreeSpacePercent`: used and free space as formatted percentage strings. +- `BytesPerSector`, `SectorsPerCluster`, `ClusterSize`, `TotalNumberOfClusters`, and `NumberOfFreeClusters`: the sector and cluster layout of the volume. + +The percentage and unit-size properties are strings that are meant for display. Use the byte and cluster properties when you need to calculate or compare values. + +The cmdlet only reads volume information and does not change anything on disk. `-DriveLetter` does not accept pipeline input. ## EXAMPLES -### Example 1 +### Example 1: Get the disk space of every volume + +```PowerShell +PS C:\> Get-DiskSpace +``` + +This command returns one object for every volume of the computer, including volumes that are mounted without a drive letter. + +### Example 2: Get the disk space of a single drive ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Get-DiskSpace -DriveLetter C: ``` -{{ Add example description here }} +This command returns the size and free space of drive C. The drive letter must be written as a letter followed by a colon. + +### Example 3: Show a readable summary of two drives + +```PowerShell +PS C:\> Get-DiskSpace -DriveLetter C:, D: | Select-Object -Property DriveName, TotalSizeUnitSize, AvailableFreeSpaceUnitSize, AvailableFreeSpacePercent +``` + +This command returns the formatted size and free space strings of drives C and D, which are easier to read than the raw byte counts. + +### Example 4: Find volumes with little free space + +```PowerShell +PS C:\> Get-DiskSpace | Where-Object { $_.TotalNumberOfFreeBytes -lt 10GB } +``` + +This command returns every volume that has less than 10 GB of free space. The filter uses `TotalNumberOfFreeBytes` because the percentage properties are formatted strings and cannot be compared numerically. ## PARAMETERS ### -DriveLetter -{{ Fill DriveLetter Description }} +Specifies one or more drives to query. Each value must be a single letter followed by a colon, such as `C:`; other forms, including `C` and `C:\`, are rejected. When you omit this parameter, the cmdlet queries all volumes of the computer, including volumes without a drive letter. ```yaml Type: String[] @@ -56,10 +94,24 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### None +This cmdlet does not accept pipeline input. Pass the drives to query with the `-DriveLetter` parameter. + ## OUTPUTS ### Alphaleonis.Win32.Filesystem.DiskSpaceInfo +The cmdlet writes one `DiskSpaceInfo` object per queried volume that reports a total size greater than zero. The object carries the size, free space, percentage, and cluster properties that are listed in the description. + ## NOTES +A volume that cannot be queried, for example a drive that is not ready, produces a warning that names the volume. Use `-WarningAction SilentlyContinue` to suppress those warnings when you query all volumes. + +Because the cmdlet enumerates volumes rather than drive letters when `-DriveLetter` is omitted, the result can contain volumes that are mounted into a folder or that have no mount point at all. + ## RELATED LINKS + +[Get-ChildItem2](Get-ChildItem2.md) + +[Get-Item2](Get-Item2.md) + +[Get-FileHash2](Get-FileHash2.md) diff --git a/Docs/Cmdlets/Get-FileHash2.md b/Docs/Cmdlets/Get-FileHash2.md index 51204e5..3eb6d05 100644 --- a/Docs/Cmdlets/Get-FileHash2.md +++ b/Docs/Cmdlets/Get-FileHash2.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-FileHash2.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Gets the hash value of one or more files. ## SYNTAX @@ -19,23 +19,53 @@ Get-FileHash2 [-Path] [[-Algorithm] ] [ Get-FileHash2 -Path C:\Data\Report.txt +``` + +This command calculates the hash of `Report.txt` with the default `SHA256` algorithm and returns the file object with the `Algorithm` and `Hash` properties attached. + +### Example 2: Get the MD5 hash of a file + +```PowerShell +PS C:\> Get-FileHash2 -Path C:\Data\Report.txt -Algorithm MD5 +``` + +This command calculates the `MD5` hash of the same file. `MD5` and `SHA1` are fast but are no longer considered collision resistant, so use them for change detection rather than for security decisions. + +### Example 3: Hash every file in a folder tree + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-FileHash2 -Algorithm SHA1 | Select-Object -Property Algorithm, Hash, FullName +``` + +This command pipes all items below `C:\Data` into `Get-FileHash2`. The cmdlet binds the `FullName` property of each item to `-Path`, hashes the files, and skips the folders. + +### Example 4: Find files with identical content ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-FileHash2 | Group-Object -Property Hash | Where-Object { $_.Count -gt 1 } ``` -{{ Add example description here }} +This command groups the files below `C:\Data` by hash value and returns the groups that contain more than one file, which identifies files whose content is identical. ## PARAMETERS ### -Algorithm -{{ Fill Algorithm Description }} +Specifies the hash algorithm to use. The accepted values are `SHA1`, `SHA256`, `SHA384`, `SHA512`, `MACTripleDES`, `MD5`, and `RIPEMD160`. When you omit this parameter, the cmdlet uses `SHA256`. ```yaml Type: HashAlgorithms @@ -45,14 +75,14 @@ Accepted values: SHA1, SHA256, SHA384, SHA512, MACTripleDES, MD5, RIPEMD160 Required: False Position: 2 -Default value: None +Default value: SHA256 Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files to hash. Folders are skipped. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. ```yaml Type: String[] @@ -73,12 +103,34 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2` and `Get-Item2`, to this cmdlet. + ### Security2.FileSystem.FileInfo.HashAlgorithms +You can supply the `-Algorithm` value through a pipeline object that has an `Algorithm` property. + ## OUTPUTS ### Security2.FileSystemAccessRule2 +The cmdlet does not return access rules. For every hashed file it writes the file object of that file, decorated with the type name `Alphaleonis.Win32.Filesystem.FileInfo+Hash` and extended with the `Hash` and `Algorithm` note properties, so all regular file properties such as `FullName`, `Name`, and `Length` remain available. + ## NOTES +The cmdlet works only in Windows PowerShell. In PowerShell 7, it fails for every algorithm with the error `Could not load type 'System.Security.Cryptography.RIPEMD160'`, because .NET no longer includes the RIPEMD-160 implementation that the cmdlet references. In PowerShell 7, use the built-in `Get-FileHash` cmdlet instead. + +If the file cannot be opened because access is denied, the cmdlet takes ownership of the file with the account that runs it, calculates the hash, and restores the previous owner afterward. That fallback fails with a `GetHashError` when the account is not allowed to change the owner of the file. + +The hash is returned as an uppercase hexadecimal string without separators, which differs from the lowercase output of some other hashing tools. Compare hash values case-insensitively. + +`MACTripleDES` is a keyed message authentication code that is created with a key that is generated for each call, so its result is not reproducible across invocations and is not suitable for comparing files. + ## RELATED LINKS + +[Get-ChildItem2](Get-ChildItem2.md) + +[Get-Item2](Get-Item2.md) + +[Test-Path2](Test-Path2.md) + +[Copy-Item2](Copy-Item2.md) diff --git a/Docs/Cmdlets/Get-Item2.md b/Docs/Cmdlets/Get-Item2.md index 8b62835..7230f18 100644 --- a/Docs/Cmdlets/Get-Item2.md +++ b/Docs/Cmdlets/Get-Item2.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-Item2.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Gets the file or folder at a specified path, including paths longer than 260 characters. ## SYNTAX @@ -19,23 +19,51 @@ Get-Item2 [[-Path] ] [] ## DESCRIPTION -{{ Fill in the Description }} +The `Get-Item2` cmdlet gets the item at a location and returns an `Alphaleonis.Win32.Filesystem.FileInfo` object for a file or an `Alphaleonis.Win32.Filesystem.DirectoryInfo` object for a folder. It is the long-path counterpart of the built-in `Get-Item` cmdlet: it works through the AlphaFS library (`Alphaleonis.Win32.Filesystem`) instead of `System.IO`, so it also reaches items whose path is longer than the 260-character `MAX_PATH` limit. + +If you omit `-Path`, the cmdlet returns the item for the current location. Relative paths and the `.` and `..` notations are resolved against the current location as well. Wildcard characters are not supported, so each value of `-Path` must name one existing file or folder. For a path that does not exist, the cmdlet writes a non-terminating error and continues with the remaining paths. + +Every returned object carries an additional `Mode` property that reports the directory, archive, read-only, hidden, and system attributes in the same `darhs` notation that `Get-ChildItem` uses. Because the objects expose a `FullName` property and the `-Path` parameters of the NTFSSecurity cmdlets have the alias `FullName`, you can pipe the result straight into cmdlets such as `Get-NTFSAccess`, `Add-NTFSAccess`, or `Get-NTFSOwner`. ## EXAMPLES -### Example 1 +### Example 1: Get a folder + +```PowerShell +PS C:\> Get-Item2 -Path C:\Data +``` + +Returns the `DirectoryInfo` object for the `C:\Data` folder. + +### Example 2: Read the permissions of a deeply nested file ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Get-Item2 -Path C:\Data\Projects\Archive\2026\Q1\Reports\Regional\Summary.docx | Get-NTFSAccess ``` -{{ Add example description here }} +Gets the file and pipes it to `Get-NTFSAccess`, which binds the `FullName` property of the object to its own `-Path` parameter. The command also works when the full path is longer than 260 characters. + +### Example 3: Get several items from the pipeline + +```PowerShell +PS C:\> 'C:\Data', 'C:\Data\Reports' | Get-Item2 | Select-Object Mode, LastWriteTime, FullName +``` + +Pipes two paths into the cmdlet and shows the attribute mode, the last write time, and the full path of each item. + +### Example 4: Use the alias and the positional parameter + +```PowerShell +PS C:\> gi2 C:\Data\report.docx +``` + +Uses the `gi2` alias and passes the path positionally to get a single file. ## PARAMETERS ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files or folders. Relative paths are resolved against the current location, and wildcard characters are not supported. If you omit this parameter, the cmdlet returns the item for the current location. ```yaml Type: String[] @@ -56,12 +84,36 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more paths to this cmdlet, either as strings or as objects that have a `FullName` property, such as the output of `Get-ChildItem2` or `Get-Item2`. + ## OUTPUTS ### Alphaleonis.Win32.Filesystem.FileInfo +The cmdlet returns this object for every path that points to a file, extended with a `Mode` property. + ### Alphaleonis.Win32.Filesystem.DirectoryInfo +The cmdlet returns this object for every path that points to a folder, extended with a `Mode` property. + ## NOTES +`Get-Item2` builds on the AlphaFS library (`Alphaleonis.Win32.Filesystem`), which is why it reaches files and folders whose path exceeds the 260-character `MAX_PATH` limit that the built-in `Get-Item` cmdlet is bound to. The objects it returns are AlphaFS objects, not `System.IO` objects, and the other NTFSSecurity cmdlets accept them directly through the `FullName` alias of their `-Path` parameters. + +The module defines the alias `gi2` for this cmdlet. + +`Get-Item2` always adds the `Mode` property. The `GetFileSystemModeProperty` setting in the `PrivateData` section of the module manifest controls only `Get-ChildItem2`. + ## RELATED LINKS + +[Get-ChildItem2](Get-ChildItem2.md) + +[Copy-Item2](Copy-Item2.md) + +[Move-Item2](Move-Item2.md) + +[Remove-Item2](Remove-Item2.md) + +[Test-Path2](Test-Path2.md) + +[Get-NTFSAccess](Get-NTFSAccess.md) diff --git a/Docs/Cmdlets/Get-NTFSAccess.md b/Docs/Cmdlets/Get-NTFSAccess.md index 9e3e099..8036d44 100644 --- a/Docs/Cmdlets/Get-NTFSAccess.md +++ b/Docs/Cmdlets/Get-NTFSAccess.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSAccess.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Gets the access control entries (ACEs) of a file, a folder, or a security descriptor. ## SYNTAX @@ -27,23 +27,53 @@ Get-NTFSAccess [-SecurityDescriptor] [-Account Get-NTFSAccess -Path C:\Data +``` + +This command returns the explicit and the inherited access control entries of `C:\Data`. + +### Example 2: Get only the permissions defined on the item itself ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Get-NTFSAccess -Path C:\Data -ExcludeInherited ``` -{{ Add example description here }} +This command returns the explicit access control entries of `C:\Data` and omits everything the folder inherits from its parents. + +### Example 3: Find the permissions of one account in a folder tree + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Directory | Get-NTFSAccess -Account 'CONTOSO\JohnDoe' -ExcludeInherited +``` + +This command searches all subfolders of `C:\Data` for access control entries that were defined for a single account. `Get-ChildItem` and `Get-Item2` can be used in the same way, because the `FullName` property of their output binds to `-Path`. + +### Example 4: Export the explicit permissions of a folder tree to a CSV file + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSAccess -ExcludeInherited | Export-Csv -Path C:\Backup\acl.csv -NoTypeInformation +``` + +This command writes a backup of all explicit access control entries below `C:\Data`. `Import-Csv C:\Backup\acl.csv | Add-NTFSAccess` recreates them, because the exported columns bind to the parameters of `Add-NTFSAccess`. ## PARAMETERS ### -Account -{{ Fill Account Description }} +Specifies the account whose access control entries are returned. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-32-544`. When the parameter is omitted, the entries of all accounts are returned. ```yaml Type: IdentityReference2 @@ -59,7 +89,7 @@ Accept wildcard characters: False ### -ExcludeExplicit -{{ Fill ExcludeExplicit Description }} +Indicates that the access control entries defined on the item itself are omitted and only the inherited entries are returned. ```yaml Type: SwitchParameter @@ -75,7 +105,7 @@ Accept wildcard characters: False ### -ExcludeInherited -{{ Fill ExcludeInherited Description }} +Indicates that the inherited access control entries are omitted and only the entries defined on the item itself are returned. ```yaml Type: SwitchParameter @@ -91,7 +121,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files or folders whose access control entries are read. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted. The parameter accepts pipeline input by value and by property name through its alias `FullName`. ```yaml Type: String[] @@ -107,7 +137,7 @@ Accept wildcard characters: False ### -SecurityDescriptor -The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. +Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose access control entries are read. This includes changes that were made to the object in memory and not written back yet. A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. @@ -130,14 +160,40 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +One or more paths of files or folders, piped by value or by the property `FullName`. + ### Security2.FileSystemSecurity2[] +One or more security descriptors returned by `Get-NTFSSecurityDescriptor`. + ### Security2.IdentityReference2 +The account to filter on. The parameter does not take pipeline input; it is listed here because it accepts the remaining arguments of the command line. + ## OUTPUTS ### Security2.FileSystemAccessRule2 +One object per access control entry, with the account, the rights, the access type, the inheritance and propagation flags, the `IsInherited` and `InheritedFrom` properties, and the path of the item. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +If the ACL of an item cannot be read because access is denied, the cmdlet tries once more after making the current account the owner of the item, and restores the previous owner afterwards. Changing the owner of an item requires the Take Ownership and Restore privileges, so this fallback only succeeds in an elevated session of an account that holds them. + +Entries whose account cannot be translated into a name are returned with their SID. Use `Get-NTFSOrphanedAccess` to list only those entries. + ## RELATED LINKS + +[Add-NTFSAccess](Add-NTFSAccess.md) + +[Remove-NTFSAccess](Remove-NTFSAccess.md) + +[Get-NTFSOrphanedAccess](Get-NTFSOrphanedAccess.md) + +[Get-NTFSSimpleAccess](Get-NTFSSimpleAccess.md) + +[Get-NTFSEffectiveAccess](Get-NTFSEffectiveAccess.md) + +[Get-NTFSSecurityDescriptor](Get-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Get-NTFSAudit.md b/Docs/Cmdlets/Get-NTFSAudit.md index 0bdbfdb..d76b5d2 100644 --- a/Docs/Cmdlets/Get-NTFSAudit.md +++ b/Docs/Cmdlets/Get-NTFSAudit.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSAudit.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Gets the audit entries of a file or folder. ## SYNTAX @@ -27,23 +27,54 @@ Get-NTFSAudit [-SecurityDescriptor] [-Account Get-NTFSAudit -Path C:\Data +``` + +This command returns every audit entry of the folder `C:\Data`, including the entries that the folder inherits from its parent. + +### Example 2: List the explicit audit entries of a folder tree ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSAudit -ExcludeInherited ``` -{{ Add example description here }} +This command pipes every item below `C:\Data` into `Get-NTFSAudit` and returns only the audit entries that are set on the items themselves. + +### Example 3: Filter the audit entries by account + +```PowerShell +PS C:\> Get-NTFSAudit -Path C:\Data -Account 'CONTOSO\JohnDoe' +``` + +This command returns only the entries that audit the account `CONTOSO\JohnDoe`. Passing the SID of the account instead of its name returns the same entries. + +### Example 4: Read the audit entries from a security descriptor + +```PowerShell +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Get-NTFSAudit -SecurityDescriptor $sd +``` + +This command reads the security descriptor of `C:\Data` once and then lists its audit entries from the in-memory object. ## PARAMETERS ### -Account -{{ Fill Account Description }} +Specifies the account whose audit entries are returned. The value is an account name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. Entries are matched by SID, and when you omit the parameter the entries of all accounts are returned. ```yaml Type: IdentityReference2 @@ -59,7 +90,7 @@ Accept wildcard characters: False ### -ExcludeExplicit -{{ Fill ExcludeExplicit Description }} +Indicates that the entries that are set on the item itself are left out, so that only the inherited entries are returned. By default the cmdlet returns explicit and inherited entries. ```yaml Type: SwitchParameter @@ -75,7 +106,7 @@ Accept wildcard characters: False ### -ExcludeInherited -{{ Fill ExcludeInherited Description }} +Indicates that the entries the item inherits from a parent folder are left out, so that only the explicit entries are returned. By default the cmdlet returns explicit and inherited entries. ```yaml Type: SwitchParameter @@ -91,7 +122,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the files or folders whose audit entries are returned. Relative paths are resolved against the current location, and when you omit the parameter the cmdlet uses the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. ```yaml Type: String[] @@ -107,9 +138,7 @@ Accept wildcard characters: False ### -SecurityDescriptor -The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. - -A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. +Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet reads the audit entries from the system access control list (SACL) of the in-memory object instead of reading the item from disk again. ```yaml Type: FileSystemSecurity2[] @@ -130,14 +159,38 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe paths to this cmdlet, or objects that have a `Path` or `FullName` property, such as the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2`. + ### Security2.FileSystemSecurity2[] +You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + ### Security2.IdentityReference2 +You can pass an account name or a SID string to `-Account`, which the cmdlet converts to this type. The parameter does not accept pipeline input. + ## OUTPUTS ### Security2.FileSystemAuditRule2 +The cmdlet returns one object per audit entry, with the audited account, the audited access rights, the audit flags, the inheritance and propagation flags, the `IsInherited` flag, and the `InheritedFrom` path. When an item has no audit entries, or when the SACL cannot be read, the cmdlet returns nothing for that item. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +Reading the SACL requires the Security privilege (`SeSecurityPrivilege`, "Manage auditing and security log"), so run this cmdlet in an elevated session of an account that holds that privilege. Without it the cmdlet falls back to reading the security descriptor without its SACL; it then returns no audit entries and reports no error, which looks the same as an item that is not audited at all. + +If the security descriptor cannot be read because access is denied, the cmdlet takes ownership of the item, reads the descriptor again, and restores the previous owner. If the second attempt fails as well, the cmdlet writes an error, and the ownership change is not rolled back. + ## RELATED LINKS + +[Add-NTFSAudit](Add-NTFSAudit.md) + +[Remove-NTFSAudit](Remove-NTFSAudit.md) + +[Clear-NTFSAudit](Clear-NTFSAudit.md) + +[Get-NTFSOrphanedAudit](Get-NTFSOrphanedAudit.md) + +[Get-NTFSSecurityDescriptor](Get-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Get-NTFSEffectiveAccess.md b/Docs/Cmdlets/Get-NTFSEffectiveAccess.md index 35b5d22..78632c1 100644 --- a/Docs/Cmdlets/Get-NTFSEffectiveAccess.md +++ b/Docs/Cmdlets/Get-NTFSEffectiveAccess.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSEffectiveAccess.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Gets the rights an account effectively has on a file or folder. ## SYNTAX @@ -27,23 +27,53 @@ Get-NTFSEffectiveAccess [-SecurityDescriptor] [[-Account ## DESCRIPTION -{{ Fill in the Description }} +Calculates the rights an account really has on a file or a folder and writes the result as a single `Security2.FileSystemAccessRule2` object per item. The cmdlet evaluates the complete discretionary access control list (DACL) of the item against the group memberships of the account with the Windows Authorization API, so allow entries, deny entries, and inherited entries are combined the same way the Windows access check combines them. This is the equivalent of the "Effective Access" tab of the advanced security dialog. + +The calculation covers the NTFS permissions of the item only. Share permissions are stored in a separate security descriptor and are not part of the result, so access over a network share can be more restrictive than this cmdlet reports. + +When `-Account` is omitted, the account that runs the session is used. `-ServerName` selects the computer whose authorization manager resolves the group memberships of the account and defaults to `localhost`; when the remote authorization manager of the named computer cannot be reached, the cmdlet falls back to the local one and warns that the result is based on the group memberships known on this computer and may be inaccurate. Reading effective access relies on the Security privilege, and the cmdlet warns when the account does not hold it or the privilege is disabled. + +Although `-Path` is optional, the cmdlet writes nothing when the parameter is omitted; pass a path or pipe items in. The `SecurityDescriptor` parameter set is accepted by the parameter binder but produces no output, so use `-Path` to query effective access. ## EXAMPLES -### Example 1 +### Example 1: Get the effective access of the current user + +```PowerShell +PS C:\> Get-NTFSEffectiveAccess -Path C:\Data +``` + +This command returns the rights the account that runs the session has on `C:\Data`, combining all allow and deny entries of the folder. + +### Example 2: Get the effective access of another account ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Get-NTFSEffectiveAccess -Path C:\Data -Account 'CONTOSO\JohnDoe' ``` -{{ Add example description here }} +This command returns the rights of a domain user on `C:\Data`. A group such as `CONTOSO\Domain Users` or `BUILTIN\Users` can be used in the same way. + +### Example 3: Compare the effective access of a folder tree + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Directory | Get-NTFSEffectiveAccess -Account 'CONTOSO\JohnDoe' +``` + +This command shows for every subfolder of `C:\Data` what an account is allowed to do there, which makes the folders visible where inheritance is broken or a deny entry applies. + +### Example 4: Calculate effective access with the group memberships of a file server + +```PowerShell +PS C:\> Get-NTFSEffectiveAccess -Path \\FileServer\Data -Account 'CONTOSO\JohnDoe' -ServerName FileServer +``` + +This command asks the authorization manager of the file server to resolve the group memberships of the account, which gives a more accurate result than the local fallback. ## PARAMETERS ### -Account -{{ Fill Account Description }} +Specifies the account the effective access is calculated for. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-32-544`. The default is the account that runs the current session. ```yaml Type: IdentityReference2 @@ -52,14 +82,14 @@ Aliases: NTAccount, IdentityReference Required: False Position: 2 -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -ExcludeNoneAccessEntries -{{ Fill ExcludeNoneAccessEntries Description }} +Indicates that items on which the account has no rights at all are left out of the result. In this release the switch does not suppress anything: the cmdlet writes a result for every item it processes, even when the calculated access mask is `None`. ```yaml Type: SwitchParameter @@ -75,7 +105,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files or folders the effective access is calculated for. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`. The cmdlet writes nothing when no path is supplied. ```yaml Type: String[] @@ -91,7 +121,7 @@ Accept wildcard characters: False ### -SecurityDescriptor -The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. +This parameter is accepted by the parameter binder but has no effect. The cmdlet produces no output in this parameter set; use `-Path` instead. A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. @@ -109,7 +139,7 @@ Accept wildcard characters: False ### -ServerName -{{ Fill ServerName Description }} +Specifies the computer whose authorization manager resolves the group memberships of the account. The default is `localhost`. Name the computer that stores the item when you query a network path, because the group memberships known there determine the result; if that computer cannot be reached, the cmdlet falls back to the local authorization manager and warns that the result may be inaccurate. ```yaml Type: String @@ -118,7 +148,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: localhost Accept pipeline input: False Accept wildcard characters: False ``` @@ -130,14 +160,36 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +One or more paths of files or folders, piped by value or by the property `FullName`. + ### Security2.FileSystemSecurity2[] +Security descriptors are accepted by the parameter binder but produce no result in this cmdlet. + ### Security2.IdentityReference2 +The account the effective access is calculated for, piped by the property `Account`, `NTAccount`, or `IdentityReference`. + ## OUTPUTS ### Security2.FileSystemAccessRule2 +One object per item, with the calculated rights in `AccessRights` and the account in `Account`. The object describes a result, not an entry of the ACL, so it is always of the access type `Allow`, it is never inherited, and it carries no inheritance or propagation flags. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +Reading effective access needs the Security privilege. In a session that does not hold it, the cmdlet warns before it starts and the calculation may fail with an error. Use `Enable-Privileges` in an elevated session to enable the privilege, and `Get-Privileges` to see which privileges the session holds. + ## RELATED LINKS + +[Get-NTFSAccess](Get-NTFSAccess.md) + +[Get-NTFSSimpleAccess](Get-NTFSSimpleAccess.md) + +[Get-NTFSInheritance](Get-NTFSInheritance.md) + +[Enable-Privileges](Enable-Privileges.md) + +[Get-Privileges](Get-Privileges.md) diff --git a/Docs/Cmdlets/Get-NTFSHardLink.md b/Docs/Cmdlets/Get-NTFSHardLink.md index af36e38..5febacc 100644 --- a/Docs/Cmdlets/Get-NTFSHardLink.md +++ b/Docs/Cmdlets/Get-NTFSHardLink.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSHardLink.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Gets all hard links that refer to the same file as the specified path. ## SYNTAX @@ -19,23 +19,53 @@ Get-NTFSHardLink [[-Path] ] [] ## DESCRIPTION -{{ Fill in the Description }} +On an NTFS volume, a file is a block of data that one or more directory entries, called hard links, refer to. The `Get-NTFSHardLink` cmdlet asks the file system for every hard link of the file that `-Path` points to and writes a file object for each of them, including the name that you passed in. + +A file that has only one name returns a single object. A file that has additional hard links returns one object per name, which lets you find all the places on the volume from which the same data is reachable. The file system reports the links relative to the root of the volume, and the cmdlet combines them with the root of the path you specify, so the result contains full paths. All hard links of a file are always on the same volume as the file. + +`-Path` must point to a file. A folder causes an error, because NTFS does not support hard links to folders. If you omit `-Path`, the cmdlet falls back to the current location, which is a folder and therefore produces the same error, so always pass the path of a file. + +The parameter accepts an array of paths and takes pipeline input by value and by property name through its `FullName` alias. `Get-ChildItem2` adds a `HardLinkCount` property to each file as long as the `IdentifyHardLinks` entry in the `PrivateData` section of the module manifest is `$true`, which lets you select the files that have more than one name before you resolve them. ## EXAMPLES -### Example 1 +### Example 1: Get all names of a file + +```PowerShell +PS C:\> Get-NTFSHardLink -Path C:\Data\Report.txt +``` + +This command returns one object for every hard link of `Report.txt`, including `Report.txt` itself. If the file has no additional links, the command returns that single file. + +### Example 2: List the full paths of all hard links + +```PowerShell +PS C:\> Get-NTFSHardLink -Path C:\Data\Report.txt | Select-Object -ExpandProperty FullName +``` + +This command returns the full path of every name under which the data of `Report.txt` is reachable on the volume. + +### Example 3: Resolve the hard links of all multi-link files in a folder + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Where-Object { $_.HardLinkCount -gt 1 } | Get-NTFSHardLink +``` + +This command uses the `HardLinkCount` property that `Get-ChildItem2` adds to files to select the files that have more than one name, and then resolves all names of each of them. + +### Example 4: Count the names of a file ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> (Get-NTFSHardLink -Path C:\Data\Report.txt).Count ``` -{{ Add example description here }} +This command returns the number of hard links that refer to the data of `Report.txt`. A result of `1` means that deleting the file releases its data. ## PARAMETERS ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files whose hard links you want to resolve. The path must point to a file; folders cause an error. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. ```yaml Type: String[] @@ -56,12 +86,32 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more file path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2` and `Get-Item2`, to this cmdlet. + ## OUTPUTS ### Alphaleonis.Win32.Filesystem.FileInfo +The cmdlet writes one file object per hard link of the file, extended with a `Mode` property that renders the file attributes in the same notation as `Get-ChildItem2`. + ### Alphaleonis.Win32.Filesystem.DirectoryInfo +The cmdlet never writes folder objects, because it rejects folders with the error `The item must be a file`. + ## NOTES +Hard links exist only within a single NTFS volume. Every object that this cmdlet returns therefore refers to a path on the volume of the file that you passed in. + +Because all hard links of a file share the same data, they also share the file content, the file size, and the time stamps. The security descriptor is stored with the file as well, so changing permissions through one name changes them for every name. + +The cmdlet resolves paths through the AlphaFS library and therefore also works with paths that exceed the 260-character `MAX_PATH` limit. + ## RELATED LINKS + +[New-NTFSHardLink](New-NTFSHardLink.md) + +[New-NTFSSymbolicLink](New-NTFSSymbolicLink.md) + +[Get-ChildItem2](Get-ChildItem2.md) + +[Get-Item2](Get-Item2.md) diff --git a/Docs/Cmdlets/Get-NTFSInheritance.md b/Docs/Cmdlets/Get-NTFSInheritance.md index f434759..dcd0577 100644 --- a/Docs/Cmdlets/Get-NTFSInheritance.md +++ b/Docs/Cmdlets/Get-NTFSInheritance.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSInheritance.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Gets the inheritance state of the access rules and the audit rules of a file or folder. ## SYNTAX @@ -25,23 +25,53 @@ Get-NTFSInheritance [-SecurityDescriptor] [ Get-NTFSInheritance -Path C:\Data\Projects +``` + +This command reports whether `C:\Data\Projects` inherits access rules and audit rules from `C:\Data`. In a session that does not hold the Security privilege, the `AuditInheritanceEnabled` column stays empty. + +### Example 2: Find the items whose access inheritance is blocked + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSInheritance | Where-Object { -not $_.AccessInheritanceEnabled } +``` + +This command walks the whole tree below `C:\Data` and returns only the items whose DACL is protected. These are the places where the permission model of the tree is interrupted and permissions have to be maintained separately. + +### Example 3: Report the current location + +```PowerShell +PS C:\> Get-NTFSInheritance +``` + +This command reports the inheritance state of the current location, because `-Path` is omitted and no item arrives from the pipeline. + +### Example 4: Read the state from a security descriptor ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Get-NTFSSecurityDescriptor -Path C:\Data\Projects | Get-NTFSInheritance ``` -{{ Add example description here }} +This command reads the security descriptor once and reports its inheritance state from memory. The access value is always accurate; the audit value is only meaningful when the descriptor was retrieved with its audit section, which requires the Security privilege. ## PARAMETERS ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files or folders to report on. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted and no item arrives from the pipeline. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it. ```yaml Type: String[] @@ -61,6 +91,8 @@ The SecurityDescriptor parameter allows passing an security descriptor or an arr A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. +This cmdlet reads the inheritance state from the descriptor in memory and does not access the file system for it. + ```yaml Type: FileSystemSecurity2[] Parameter Sets: SecurityDescriptor @@ -80,12 +112,38 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet. + ### Security2.FileSystemSecurity2[] +You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + ## OUTPUTS ### Security2.FileSystemInheritanceInfo +For each item the cmdlet writes one object with the `Name`, `FullName`, `Item`, `AccessInheritanceEnabled`, and `AuditInheritanceEnabled` properties. `AccessInheritanceEnabled` and `AuditInheritanceEnabled` are `$true` when the item inherits the rules of the corresponding section from its parent folder, and `AuditInheritanceEnabled` is `$null` when the audit section could not be read. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +Reading the audit section (SACL) of an item requires the Security privilege (`SeSecurityPrivilege`), which an account can only use in an elevated session. Without it, the cmdlet still reports the access state and sets `AuditInheritanceEnabled` to `$null` instead of writing an error. + +If the security descriptor of an item cannot be opened because the account has no permission to it, the cmdlet takes ownership of the item, reads the state, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; otherwise the cmdlet writes an error and continues with the next item. + +A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths. + ## RELATED LINKS + +[Set-NTFSInheritance](Set-NTFSInheritance.md) + +[Enable-NTFSAccessInheritance](Enable-NTFSAccessInheritance.md) + +[Disable-NTFSAccessInheritance](Disable-NTFSAccessInheritance.md) + +[Enable-NTFSAuditInheritance](Enable-NTFSAuditInheritance.md) + +[Disable-NTFSAuditInheritance](Disable-NTFSAuditInheritance.md) + +[Get-NTFSSecurityDescriptor](Get-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Get-NTFSOrphanedAccess.md b/Docs/Cmdlets/Get-NTFSOrphanedAccess.md index 9d99a82..22e89db 100644 --- a/Docs/Cmdlets/Get-NTFSOrphanedAccess.md +++ b/Docs/Cmdlets/Get-NTFSOrphanedAccess.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSOrphanedAccess.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Gets the access control entries whose account cannot be resolved to a name. ## SYNTAX @@ -27,23 +27,45 @@ Get-NTFSOrphanedAccess [-SecurityDescriptor] [-Account < ## DESCRIPTION -{{ Fill in the Description }} +Reads the discretionary access control list (DACL) of a file or a folder like `Get-NTFSAccess` and returns only the access control entries whose account name is empty. The account name of an entry is empty when Windows cannot translate the SID stored in the entry into an account name, which is what remains after the account the entry was created for has been deleted. + +An entry counts as orphaned only as long as the name resolution fails, and the cmdlet cannot tell a deleted account from an account that cannot be looked up right now. A domain controller that is unreachable, a broken trust, or a SID from a domain the computer does not know make intact entries look orphaned as well. Confirm that the accounts are really gone before you remove anything, and run the search from a computer that can resolve all domains involved. + +Relative paths are resolved against the current location, and the current location is searched when `-Path` is omitted. By default both explicit and inherited entries are returned, which means that the same orphaned entry appears on every item that inherits it; `-ExcludeInherited` reports it only on the item where it is defined. With `-Verbose`, the cmdlet reports the number of orphaned entries per item and the total at the end. + +The `-Account` and `-SecurityDescriptor` parameters are inherited from `Get-NTFSAccess` and have no effect on this cmdlet. Entries are never filtered by account, and a security descriptor passed to `-SecurityDescriptor` is ignored; the cmdlet reads the current location instead. ## EXAMPLES -### Example 1 +### Example 1: Find orphaned entries in a folder + +```PowerShell +PS C:\> Get-NTFSOrphanedAccess -Path C:\Data +``` + +This command returns the access control entries of `C:\Data` whose SID cannot be resolved, including the entries the folder inherits from its parent. + +### Example 2: Search a folder tree for orphaned entries + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOrphanedAccess -ExcludeInherited +``` + +This command searches all files and folders below `C:\Data` and reports every orphaned entry on the item where it is defined. Without `-ExcludeInherited` the same entry would also be reported on every item that inherits it. + +### Example 3: Remove orphaned entries ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOrphanedAccess -ExcludeInherited | Remove-NTFSAccess ``` -{{ Add example description here }} +This command deletes the orphaned entries from the items they are defined on. The piped objects supply the path, the SID, the rights, the access type, and the flags, so each entry is matched exactly as it exists. ## PARAMETERS ### -Account -{{ Fill Account Description }} +This parameter is inherited from `Get-NTFSAccess` and has no effect. The cmdlet always returns the entries of all accounts that cannot be resolved. ```yaml Type: IdentityReference2 @@ -59,7 +81,7 @@ Accept wildcard characters: False ### -ExcludeExplicit -{{ Fill ExcludeExplicit Description }} +Indicates that the access control entries defined on the item itself are omitted and only the inherited entries are searched. ```yaml Type: SwitchParameter @@ -75,7 +97,7 @@ Accept wildcard characters: False ### -ExcludeInherited -{{ Fill ExcludeInherited Description }} +Indicates that the inherited access control entries are omitted and only the entries defined on the item itself are searched. Use this switch to report an orphaned entry once instead of on every item that inherits it. ```yaml Type: SwitchParameter @@ -91,7 +113,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files or folders that are searched for orphaned access control entries. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted. The parameter accepts pipeline input by value and by property name through its alias `FullName`. ```yaml Type: String[] @@ -107,7 +129,7 @@ Accept wildcard characters: False ### -SecurityDescriptor -The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. +This parameter is inherited from `Get-NTFSAccess` and has no effect. A security descriptor passed here is ignored, and the cmdlet searches the path in `-Path` or the current location instead. A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. @@ -130,14 +152,36 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +One or more paths of files or folders, piped by value or by the property `FullName`. + ### Security2.FileSystemSecurity2[] +Security descriptors are accepted by the parameter binder but ignored by this cmdlet. + ### Security2.IdentityReference2 +An account is accepted by the parameter binder but ignored by this cmdlet. + ## OUTPUTS ### Security2.FileSystemAccessRule2 +One object per orphaned access control entry. The `Account` property holds the unresolved SID and reports an empty account name. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +If the ACL of an item cannot be read because access is denied, the cmdlet tries once more after making the current account the owner of the item, and restores the previous owner afterwards. Changing the owner of an item requires the Take Ownership and Restore privileges, so this fallback only succeeds in an elevated session of an account that holds them. + ## RELATED LINKS + +[Get-NTFSAccess](Get-NTFSAccess.md) + +[Remove-NTFSAccess](Remove-NTFSAccess.md) + +[Get-NTFSOrphanedAudit](Get-NTFSOrphanedAudit.md) + +[Get-NTFSSimpleAccess](Get-NTFSSimpleAccess.md) + +[Get-ChildItem2](Get-ChildItem2.md) diff --git a/Docs/Cmdlets/Get-NTFSOrphanedAudit.md b/Docs/Cmdlets/Get-NTFSOrphanedAudit.md index 3237e5e..bf967d6 100644 --- a/Docs/Cmdlets/Get-NTFSOrphanedAudit.md +++ b/Docs/Cmdlets/Get-NTFSOrphanedAudit.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSOrphanedAudit.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Gets the audit entries whose account cannot be resolved. ## SYNTAX @@ -27,23 +27,54 @@ Get-NTFSOrphanedAudit [-SecurityDescriptor] [-Account Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOrphanedAudit +``` + +This command examines every item below `C:\Data` and returns the audit entries whose account cannot be resolved. + +### Example 2: Find orphaned entries that are set on the item itself ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Get-NTFSOrphanedAudit -Path C:\Data -ExcludeInherited ``` -{{ Add example description here }} +This command skips the audit entries that `C:\Data` inherits from its parent and reports only the orphaned entries that are set on the folder itself. Those are the entries that can be removed on this item. + +### Example 3: Collect the orphaned entries for a report + +```PowerShell +PS C:\> $orphaned = Get-NTFSOrphanedAudit -Path C:\Data -Verbose +PS C:\> $orphaned | Select-Object FullName, Account, AccessRights, AuditFlags +``` + +This command stores the result in a variable and then lists the item, the unresolved SID, the audited rights, and the audit flags of every orphaned entry. Storing the result first is necessary because the cmdlet writes one collection per item rather than one object per entry. + +### Example 4: Check the current location + +```PowerShell +PS C:\> Get-NTFSOrphanedAudit +``` + +This command examines the current location, because `-Path` is omitted. ## PARAMETERS ### -Account -{{ Fill Account Description }} +Specifies an account in the base cmdlet `Get-NTFSAudit`. `Get-NTFSOrphanedAudit` inherits the parameter but does not evaluate it, so the result always contains the entries of every account whose SID cannot be resolved. ```yaml Type: IdentityReference2 @@ -59,7 +90,7 @@ Accept wildcard characters: False ### -ExcludeExplicit -{{ Fill ExcludeExplicit Description }} +Indicates that the entries that are set on the item itself are left out, so that only inherited entries are examined. By default the cmdlet examines explicit and inherited entries. ```yaml Type: SwitchParameter @@ -75,7 +106,7 @@ Accept wildcard characters: False ### -ExcludeInherited -{{ Fill ExcludeInherited Description }} +Indicates that the entries the item inherits from a parent folder are left out, so that only the explicit entries are examined. By default the cmdlet examines explicit and inherited entries. ```yaml Type: SwitchParameter @@ -91,7 +122,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the files or folders that are examined. Relative paths are resolved against the current location, and when you omit the parameter the cmdlet uses the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. ```yaml Type: String[] @@ -107,9 +138,7 @@ Accept wildcard characters: False ### -SecurityDescriptor -The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. - -A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. +Specifies one or more security descriptors in the base cmdlet `Get-NTFSAudit`. `Get-NTFSOrphanedAudit` inherits the parameter but does not read from it; the cmdlet always examines the items in `-Path` and therefore the current location when `-Path` is omitted. Use `Get-NTFSAudit -SecurityDescriptor` to inspect the audit entries of a security descriptor. ```yaml Type: FileSystemSecurity2[] @@ -130,14 +159,38 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe paths to this cmdlet, or objects that have a `Path` or `FullName` property, such as the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2`. + ### Security2.FileSystemSecurity2[] +Security descriptors bind to the inherited `-SecurityDescriptor` parameter, but this cmdlet does not read their audit entries. + ### Security2.IdentityReference2 +An account name or a SID string binds to the inherited `-Account` parameter, which this cmdlet does not evaluate. + ## OUTPUTS ### Security2.FileSystemAuditRule2 +The cmdlet returns the audit entries whose account SID cannot be translated into a name, each with the item, the unresolved account, the audited access rights, the audit flags, and the inheritance information. The entries of an item are written as a single collection rather than one object per entry, so store the result in a variable before you filter or format it; an item without orphaned entries still produces one empty collection, and a command placed directly after this cmdlet in the pipeline receives the collection instead of the individual entries. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +Reading the SACL requires the Security privilege (`SeSecurityPrivilege`, "Manage auditing and security log"), so run this cmdlet in an elevated session of an account that holds that privilege. Without it the cmdlet reads the security descriptor without its SACL and reports no orphaned entries at all, which looks the same as a tree that has none. + +If an item cannot be read, the cmdlet writes a warning and continues with the next item. Unlike `Get-NTFSAudit`, it does not try to take ownership of the item when access is denied. + ## RELATED LINKS + +[Get-NTFSAudit](Get-NTFSAudit.md) + +[Remove-NTFSAudit](Remove-NTFSAudit.md) + +[Clear-NTFSAudit](Clear-NTFSAudit.md) + +[Add-NTFSAudit](Add-NTFSAudit.md) + +[Get-NTFSOrphanedAccess](Get-NTFSOrphanedAccess.md) diff --git a/Docs/Cmdlets/Get-NTFSOwner.md b/Docs/Cmdlets/Get-NTFSOwner.md index 0ce560a..bd23beb 100644 --- a/Docs/Cmdlets/Get-NTFSOwner.md +++ b/Docs/Cmdlets/Get-NTFSOwner.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSOwner.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Gets the owner of a file or folder. ## SYNTAX @@ -25,23 +25,54 @@ Get-NTFSOwner [-SecurityDescriptor] [] ## DESCRIPTION -{{ Fill in the Description }} +The `Get-NTFSOwner` cmdlet reads the owner from the security descriptor of a file or folder and returns a `Security2.FileSystemOwner` object. That object exposes the item in the `Item` property, its full path in `FullName`, and the owning account in both the `Owner` and the `Account` property. + +The `Path` parameter set reads the owner from the file system. The `SecurityDescriptor` parameter set reads the owner from a security descriptor that `Get-NTFSSecurityDescriptor` returned. The second form also shows an owner that `Set-NTFSOwner` changed in memory but that has not been written back with `Set-NTFSSecurityDescriptor` yet. + +The `Path` parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem` binds to it. Relative paths are resolved against the current location. Unlike `Get-NTFSSecurityDescriptor`, this cmdlet does not fall back to the current location: when you omit `-Path`, it returns nothing. + +Every path is processed on its own. When a path does not exist or its owner cannot be read, the cmdlet writes a non-terminating error and continues with the next path. ## EXAMPLES -### Example 1 +### Example 1: Get the owner of a folder + +```PowerShell +PS C:\> Get-NTFSOwner -Path C:\Data +``` + +This command reads the owner of the `C:\Data` folder and returns a single `FileSystemOwner` object. + +### Example 2: Get the owner of every item in a folder tree + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOwner +``` + +This command pipes every file and folder below `C:\Data` to `Get-NTFSOwner`. The items bind to `-Path` through the `FullName` alias, so the cmdlet returns one result per item. + +### Example 3: Find items that a specific account does not own + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOwner | Where-Object { $_.Account.AccountName -ne 'CONTOSO\JohnDoe' } +``` + +This command returns the items below `C:\Data` whose owner is not `CONTOSO\JohnDoe`. The `AccountName` property holds the resolved account name; compare the `Sid` property instead when an account cannot be resolved. + +### Example 4: Read the owner from a security descriptor in memory ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Get-NTFSOwner -SecurityDescriptor $sd ``` -{{ Add example description here }} +The first command reads the security descriptor of `C:\Data` into a variable. The second command returns the owner that is stored in that descriptor without reading the file system again. ## PARAMETERS ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files or folders whose owner you want to read. Relative paths are resolved against the current location. When you omit this parameter, the cmdlet returns nothing. ```yaml Type: String[] @@ -57,9 +88,7 @@ Accept wildcard characters: False ### -SecurityDescriptor -The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. - -A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. +Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet reads the owner from the descriptor in memory instead of from the file system, which includes an owner that `Set-NTFSOwner -SecurityDescriptor` changed but that has not been written back yet. ```yaml Type: FileSystemSecurity2[] @@ -80,12 +109,30 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more paths to this cmdlet. Objects that expose a `Path` or `FullName` property, such as the output of `Get-ChildItem2` and `Get-Item2`, bind to `-Path` as well. + ### Security2.FileSystemSecurity2[] +You can pipe security descriptors that `Get-NTFSSecurityDescriptor` returned to this cmdlet. + ## OUTPUTS ### Security2.FileSystemOwner +The cmdlet returns one object per item. It contains the item itself in `Item`, an `Alphaleonis.Win32.Filesystem.FileInfo` or `DirectoryInfo`, the path of the item in `FullName`, and the owning account in `Owner` and `Account`, both of type `Security2.IdentityReference2`. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +The module also adds an `Owner` script property to `System.IO.FileInfo` and `System.IO.DirectoryInfo`, so `(Get-Item C:\Data).Owner` returns the owning account as a `Security2.IdentityReference2` object as well. + ## RELATED LINKS + +[Set-NTFSOwner](Set-NTFSOwner.md) + +[Get-NTFSSecurityDescriptor](Get-NTFSSecurityDescriptor.md) + +[Get-NTFSAccess](Get-NTFSAccess.md) + +[Get-ChildItem2](Get-ChildItem2.md) diff --git a/Docs/Cmdlets/Get-NTFSSecurityDescriptor.md b/Docs/Cmdlets/Get-NTFSSecurityDescriptor.md index b3f2648..9228d41 100644 --- a/Docs/Cmdlets/Get-NTFSSecurityDescriptor.md +++ b/Docs/Cmdlets/Get-NTFSSecurityDescriptor.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSSecurityDescriptor.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Gets the security descriptor of a file or folder. ## SYNTAX @@ -19,23 +19,59 @@ Get-NTFSSecurityDescriptor [[-Path] ] [] ## DESCRIPTION -{{ Fill in the Description }} +The `Get-NTFSSecurityDescriptor` cmdlet reads the security descriptor of a file or folder into memory and returns it as a `Security2.FileSystemSecurity2` object. A security descriptor holds the owner of an item, its primary group, the discretionary access control list (DACL) that grants or denies access, and the system access control list (SACL) that controls auditing. + +The returned object is the starting point of the security descriptor workflow. Many cmdlets of the module accept it through a `-SecurityDescriptor` parameter and then change the copy in memory instead of the file system, among them `Add-NTFSAccess`, `Remove-NTFSAccess`, `Clear-NTFSAccess`, `Add-NTFSAudit`, `Remove-NTFSAudit`, `Clear-NTFSAudit`, `Set-NTFSInheritance`, `Enable-NTFSAccessInheritance`, `Disable-NTFSAccessInheritance`, and `Set-NTFSOwner`. Nothing reaches the disk until you pass the descriptor to `Set-NTFSSecurityDescriptor`, which makes it possible to collect several changes and apply them in a single write. Discard the variable to discard the changes. + +The cmdlet reads all sections of the descriptor. When that fails, for example because the session may not read the SACL, it falls back to the access, owner, and group sections, and then to the access section alone. `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem` binds to it. Relative paths are resolved against the current location, and when you omit `-Path` entirely, the cmdlet returns the descriptor of the current location. + +Every path is processed on its own. When a path does not exist, the cmdlet writes a non-terminating error and continues with the next one. When reading the descriptor fails because access is denied, the cmdlet takes ownership of the item with the account of the current session, reads the descriptor, and restores the previous owner; if that fails as well, it writes a non-terminating error. ## EXAMPLES -### Example 1 +### Example 1: Get the security descriptor of a folder + +```PowerShell +PS C:\> Get-NTFSSecurityDescriptor -Path C:\Data +``` + +This command reads the security descriptor of `C:\Data` and returns it as a `FileSystemSecurity2` object. + +### Example 2: Collect several changes and apply them in one write ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Add-NTFSAccess -SecurityDescriptor $sd -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AppliesTo ThisFolderSubfoldersAndFiles +PS C:\> Remove-NTFSAccess -SecurityDescriptor $sd -Account 'BUILTIN\Users' -AccessRights ReadAndExecute -AppliesTo ThisFolderSubfoldersAndFiles +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd ``` -{{ Add example description here }} +The first three commands read the descriptor of `C:\Data` and change its access control list in memory, which leaves the folder untouched. The last command writes both changes to the folder at once. + +### Example 3: Inspect the access control list of the descriptor before writing it + +```PowerShell +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Add-NTFSAccess -SecurityDescriptor $sd -Account 'CONTOSO\JohnDoe' -AccessRights FullControl -AppliesTo ThisFolderOnly +PS C:\> Get-NTFSAccess -SecurityDescriptor $sd +``` + +The third command lists the access control entries of the descriptor in memory, which already include the permissions that were just added. Compare the result with `Get-NTFSAccess -Path C:\Data` to see that the folder itself has not changed yet. + +### Example 4: Get the security descriptor of the current location + +```PowerShell +PS C:\> Set-Location -Path C:\Data +PS C:\Data> Get-NTFSSecurityDescriptor +``` + +Without `-Path`, the cmdlet returns the security descriptor of the current location. ## PARAMETERS ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files or folders whose security descriptor you want to read. Relative paths are resolved against the current location. When you omit this parameter, the cmdlet uses the current location. ```yaml Type: String[] @@ -56,10 +92,28 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more paths to this cmdlet. Objects that expose a `Path` or `FullName` property, such as the output of `Get-ChildItem2` and `Get-Item2`, bind to `-Path` as well. + ## OUTPUTS ### Security2.FileSystemSecurity2 +The cmdlet returns one object per item. It wraps the item in `Item` and the underlying `System.Security.AccessControl.FileSecurity` or `DirectorySecurity` object in `SecurityDescriptor`, and it exposes the path in `FullName`, the item name in `Name`, and whether the item is a file in `IsFile`. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +`Add-NTFSAccess`, `Remove-NTFSAccess`, `Add-NTFSAudit`, and `Remove-NTFSAudit` offer two parameter sets for a security descriptor, one with `-AppliesTo` and one with `-InheritanceFlags` and `-PropagationFlags`. Specify at least one of those parameters when you pass a descriptor to them; otherwise PowerShell cannot decide which parameter set to use and reports an ambiguous parameter set. + ## RELATED LINKS + +[Set-NTFSSecurityDescriptor](Set-NTFSSecurityDescriptor.md) + +[Get-NTFSAccess](Get-NTFSAccess.md) + +[Add-NTFSAccess](Add-NTFSAccess.md) + +[Get-NTFSOwner](Get-NTFSOwner.md) + +[Get-NTFSInheritance](Get-NTFSInheritance.md) diff --git a/Docs/Cmdlets/Get-NTFSSimpleAccess.md b/Docs/Cmdlets/Get-NTFSSimpleAccess.md index 7958182..ebe3c12 100644 --- a/Docs/Cmdlets/Get-NTFSSimpleAccess.md +++ b/Docs/Cmdlets/Get-NTFSSimpleAccess.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSSimpleAccess.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Gets the permissions of folders reduced to read, write, and delete. ## SYNTAX @@ -27,23 +27,45 @@ Get-NTFSSimpleAccess [-IncludeRootFolder] [-SecurityDescriptor] Get-NTFSSimpleAccess -Path C:\Data +``` + +This command shows who may read, write, or delete in `C:\Data`. The permissions of the parent folder are shown first, because `-IncludeRootFolder` is on by default. + +### Example 2: Find the folders whose permissions differ ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Directory | Get-NTFSSimpleAccess ``` -{{ Add example description here }} +This command walks the folder tree below `C:\Data` and reports only the entries that a folder does not already inherit in the same form from its parent, which reveals where permissions were added or broken. + +### Example 3: Report only the permissions defined on the folder itself + +```PowerShell +PS C:\> Get-NTFSSimpleAccess -Path C:\Data -ExcludeInherited -IncludeRootFolder:$false +``` + +This command shows the explicit entries of `C:\Data` in simplified form and leaves both the inherited entries and the parent folder out of the result. ## PARAMETERS ### -Account -{{ Fill Account Description }} +This parameter is inherited from `Get-NTFSAccess` and has no effect. The cmdlet always returns the entries of all accounts. ```yaml Type: IdentityReference2 @@ -59,7 +81,7 @@ Accept wildcard characters: False ### -ExcludeExplicit -{{ Fill ExcludeExplicit Description }} +Indicates that the access control entries defined on the folder itself are omitted and only the inherited entries are reported. ```yaml Type: SwitchParameter @@ -75,7 +97,7 @@ Accept wildcard characters: False ### -ExcludeInherited -{{ Fill ExcludeInherited Description }} +Indicates that the inherited access control entries are omitted and only the entries defined on the folder itself are reported. ```yaml Type: SwitchParameter @@ -91,7 +113,7 @@ Accept wildcard characters: False ### -IncludeRootFolder -{{ Fill IncludeRootFolder Description }} +Indicates that the parent folder of the first path is reported as well and serves as the baseline the following folders are compared against. This behavior is on by default; use `-IncludeRootFolder:$false` to start with the first path itself. ```yaml Type: SwitchParameter @@ -107,7 +129,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of one or more folders whose permissions are reported. Paths that point to a file are skipped. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted. The parameter accepts pipeline input by value and by property name through its alias `FullName`. ```yaml Type: String[] @@ -123,7 +145,7 @@ Accept wildcard characters: False ### -SecurityDescriptor -The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. +This parameter is inherited from `Get-NTFSAccess` and has no effect. A security descriptor passed here is ignored, and the cmdlet reads the path in `-Path` or the current location instead. A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. @@ -146,14 +168,34 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +One or more paths of folders, piped by value or by the property `FullName`. + ### Security2.FileSystemSecurity2[] +Security descriptors are accepted by the parameter binder but ignored by this cmdlet. + ### Security2.IdentityReference2 +An account is accepted by the parameter binder but ignored by this cmdlet. + ## OUTPUTS ### Security2.SimpleFileSystemAccessRule +One object per reported entry, with the folder in `FullName` and `Name`, the account in `Identity`, the access type in `AccessControlType`, and the simplified rights `Read`, `Write`, and `Delete` in `AccessRights`. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +The simplified rights hide which exact rights an account holds. Use `Get-NTFSAccess` when you need the full access control entry, and `Get-NTFSEffectiveAccess` when you need the rights that result from all entries together. + ## RELATED LINKS + +[Get-NTFSAccess](Get-NTFSAccess.md) + +[Get-NTFSEffectiveAccess](Get-NTFSEffectiveAccess.md) + +[Get-NTFSInheritance](Get-NTFSInheritance.md) + +[Get-ChildItem2](Get-ChildItem2.md) diff --git a/Docs/Cmdlets/Get-Privileges.md b/Docs/Cmdlets/Get-Privileges.md index e75bed8..dae6b7f 100644 --- a/Docs/Cmdlets/Get-Privileges.md +++ b/Docs/Cmdlets/Get-Privileges.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-Privileges.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Gets the privileges in the access token of the current PowerShell process. ## SYNTAX @@ -19,45 +19,45 @@ Get-Privileges [] ## DESCRIPTION -{{ Fill in the Description }} +The `Get-Privileges` cmdlet reads the access token of the current PowerShell process and returns one `ProcessPrivileges.PrivilegeAndAttributes` object for every privilege the token contains. Each object names the privilege in the `Privilege` property, the raw token attributes in `PrivilegeAttributes`, and the resulting state in `PrivilegeState`, which is `Enabled`, `Disabled`, or `Removed`. + +The cmdlet only reads; it never changes a privilege. Use it to check whether the four privileges that NTFSSecurity depends on (Backup, Restore, Take Ownership, and Security) are available before you run the file system cmdlets, and to confirm the result of `Enable-Privileges` and `Disable-Privileges`. + +Only privileges that the account holds in this session appear in the list; privileges the account does not have are not listed at all. Because Windows removes the administrative privileges from the token of a session that is not elevated, a standard session returns a much shorter list than an elevated one. ## EXAMPLES -### Example 1 +### Example 1: List the privileges of the current session ```PowerShell PS C:\> Get-Privileges +``` + +This command returns every privilege in the access token of the current PowerShell process together with its state. + +### Example 2: List only the privileges that are currently enabled + +```PowerShell +PS C:\> Get-Privileges | Where-Object { $_.PrivilegeState -eq 'Enabled' } +``` + +This command filters the result down to the privileges that are in use, which is a short list in a session that has not enabled anything. + +### Example 3: Check the privileges that NTFSSecurity uses + +```PowerShell +PS C:\> Get-Privileges | Where-Object { $_.Privilege -in 'Backup', 'Restore', 'TakeOwnership', 'Security' } +``` + +This command shows the four file system privileges. An empty result means that the session does not hold them, which is the normal case outside an elevated session. + +### Example 4: Test a single privilege before taking ownership -------------------------------------------------------------------------- -| Privilege | PrivilegeAttributes | PriviliegeState | -|-------------------------------|---------------------|-----------------| -| IncreaseQuota | Disabled | Disabled | -| Security | Enabled | Enabled | -| TakeOwnership | Enabled | Enabled | -| LoadDriver | Disabled | Disabled | -| SystemProfile | Disabled | Disabled | -| SystemTime | Disabled | Disabled | -| ProfileSingleProcess | Disabled | Disabled | -| IncreaseBasePriority | Disabled | Disabled | -| CreatePageFile | Disabled | Disabled | -| Backup | Enabled | Enabled | -| Restore | Enabled | Enabled | -| Shutdown | Disabled | Disabled | -| Debug | Enabled | Enabled | -| SystemEnvironment | Disabled | Disabled | -| ChangeNotify EnabledByDefault | Enabled | Enabled | -| RemoteShutdown | Disabled | Disabled | -| Undock | Disabled | Disabled | -| ManageVolume | Disabled | Disabled | -| Impersonate EnabledByDefault | Enabled | Enabled | -| CreateGlobal EnabledByDefault | Enabled | Enabled | -| IncreaseWorkingSet | Disabled | Disabled | -| TimeZone | Disabled | Disabled | -| CreateSymbolicLink | Disabled | Disabled | -------------------------------------------------------------------------- +```PowerShell +PS C:\> (Get-Privileges | Where-Object { $_.Privilege -eq 'TakeOwnership' }).PrivilegeState ``` -The above command gets the privliges. +This command returns the state of the Take Ownership privilege alone and returns nothing when the session does not hold it. ## PARAMETERS @@ -68,10 +68,26 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### None +This cmdlet does not accept pipeline input. + ## OUTPUTS ### ProcessPrivileges.PrivilegeAndAttributes +The cmdlet returns one object per privilege in the token of the current process. `Privilege` names the privilege, `PrivilegeAttributes` holds the token attributes as a combination of `Disabled`, `EnabledByDefault`, `Enabled`, `Removed`, and `UsedForAccess`, and `PrivilegeState` reduces those attributes to `Enabled`, `Disabled`, or `Removed`. + ## NOTES +This cmdlet reads the access token of the current PowerShell process only. It reports no privileges of other processes or sessions, and it changes nothing. Use `Enable-Privileges` and `Disable-Privileges` to change the state of the file system privileges. + +Unlike the file system cmdlets of the module, `Get-Privileges` is not affected by the `EnablePrivileges` setting in the `PrivateData` section of NTFSSecurity.psd1 and never enables a privilege on its own. + ## RELATED LINKS + +[Enable-Privileges](Enable-Privileges.md) + +[Disable-Privileges](Disable-Privileges.md) + +[Set-NTFSOwner](Set-NTFSOwner.md) + +[Get-NTFSSecurityDescriptor](Get-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Move-Item2.md b/Docs/Cmdlets/Move-Item2.md index 217fb2a..addffd2 100644 --- a/Docs/Cmdlets/Move-Item2.md +++ b/Docs/Cmdlets/Move-Item2.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Move-Item2.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Moves a file or folder to another location, including paths longer than 260 characters. ## SYNTAX @@ -20,17 +20,47 @@ Move-Item2 [-Path] [-Destination] [-Force] [-PassThru Move-Item2 -Path C:\Data\report.docx -Destination C:\Data\Archive +``` + +Moves `report.docx` into the existing folder `C:\Data\Archive`, where it keeps its name. + +### Example 2: Rename an item ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Move-Item2 -Path C:\Data\Archive\report.docx -Destination C:\Data\Archive\report-2026.docx ``` -{{ Add example description here }} +Moves the file to a new path inside the same folder, which renames it. + +### Example 3: Move a folder with a very long path + +```PowerShell +PS C:\> Move-Item2 -Path C:\Data\Projects\Archive\2026\Q1\Reports\Regional\Northwest -Destination C:\Data\Archive\Northwest -PassThru $true +``` + +Moves the folder and everything it contains, even when the paths below it exceed 260 characters, and returns the folder object at its new location. + +### Example 4: Preview a move operation + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -File -Filter '*.tmp' | Move-Item2 -Destination C:\Data\Temp -WhatIf +``` + +Shows which temporary files the cmdlet would move into `C:\Data\Temp` without moving anything. Remove `-WhatIf` to carry the operation out. ## PARAMETERS @@ -52,7 +82,7 @@ Accept wildcard characters: False ### -Destination -{{ Fill Destination Description }} +Specifies the target of the move operation. If the value names an existing folder, the cmdlet moves the item into that folder under its current name; otherwise the value is the full path of the new item. The path is resolved against the current location once, when the cmdlet starts, so pass an absolute path when you supply `-Destination` through the pipeline. ```yaml Type: String @@ -68,7 +98,7 @@ Accept wildcard characters: False ### -Force -{{ Fill Force Description }} +Indicates that the cmdlet replaces an existing destination item. Without `-Force`, an existing destination file causes the error `DestinationFileAlreadyExists` and the item is not moved. ```yaml Type: SwitchParameter @@ -84,7 +114,7 @@ Accept wildcard characters: False ### -PassThru -{{ Fill PassThru Description }} +Specifies whether the cmdlet returns an object for each item that it moved. This parameter is typed `Boolean` rather than a switch, so it needs an explicit value, as in `-PassThru $true`. By default, the cmdlet produces no output. The returned object describes the item at its new location. ```yaml Type: Boolean @@ -100,7 +130,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of one or more items to move. Relative paths are resolved against the current location, and wildcard characters are not supported. The parameter accepts pipeline input by value and by the property name `FullName`, so you can pipe the output of `Get-ChildItem2` or `Get-Item2` into this cmdlet. ```yaml Type: String[] @@ -138,12 +168,34 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more paths to this cmdlet, either as strings or as objects that have a `FullName` property, such as the output of `Get-ChildItem2` or `Get-Item2`. + ### System.String +You can pipe an object that has a `Destination` property to supply the target of the move operation. + ## OUTPUTS ### System.Object +By default this cmdlet returns nothing. With `-PassThru $true` it returns an `Alphaleonis.Win32.Filesystem.FileInfo` or `Alphaleonis.Win32.Filesystem.DirectoryInfo` object for each item that it moved, pointing at the new location. + ## NOTES +`Move-Item2` moves through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), which is why it handles source and destination paths that exceed the 260-character `MAX_PATH` limit of the built-in `Move-Item` cmdlet. + +The cmdlet chooses between two mutually exclusive move options. Without `-Force` it moves with `CopyAllowed`, which permits a file to cross volume boundaries because Windows then copies and deletes it. With `-Force` it moves with `ReplaceExisting`, which overwrites the destination but does not request `CopyAllowed`, so a move across volumes can fail when `-Force` is specified. + +If a path in `-Path` does not exist or the destination file exists and `-Force` is missing, the cmdlet writes a non-terminating error and skips the remaining paths that were passed in the same call. Items that arrive one by one through the pipeline are not affected, because each of them is processed separately. + ## RELATED LINKS + +[Copy-Item2](Copy-Item2.md) + +[Remove-Item2](Remove-Item2.md) + +[Get-ChildItem2](Get-ChildItem2.md) + +[Get-Item2](Get-Item2.md) + +[Test-Path2](Test-Path2.md) diff --git a/Docs/Cmdlets/New-NTFSHardLink.md b/Docs/Cmdlets/New-NTFSHardLink.md index 04cc5c8..16c4fdd 100644 --- a/Docs/Cmdlets/New-NTFSHardLink.md +++ b/Docs/Cmdlets/New-NTFSHardLink.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/New-NTFSHardLink.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Creates a hard link to an existing file. ## SYNTAX @@ -19,23 +19,53 @@ New-NTFSHardLink [[-Path] ] [[-Target] ] [-PassThru] [ New-NTFSHardLink -Path C:\Data\Report-Current.txt -Target C:\Data\Report-2026.txt +``` + +This command creates the new hard link `Report-Current.txt` for the existing file `Report-2026.txt`. Both names now refer to the same data, and no second copy of the content is stored. + +### Example 2: Create a hard link with positional parameters + +```PowerShell +PS C:\> New-NTFSHardLink C:\Data\Archive\Report.txt C:\Data\Report.txt +``` + +This command uses the positional form of the parameters. The first position is `-Path`, the new link, and the second position is `-Target`, the existing file. Both paths are on drive C, as a hard link and its target must be on the same volume. + +### Example 3: Create a link and list all names of the file + +```PowerShell +PS C:\> New-NTFSHardLink -Path C:\Data\Report-Current.txt -Target C:\Data\Report-2026.txt -PassThru +``` + +This command creates the link and then returns one object for every hard link of the file, so the output contains both `Report-2026.txt` and the new `Report-Current.txt`. + +### Example 4: Verify the result ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Get-NTFSHardLink -Path C:\Data\Report-2026.txt | Select-Object -ExpandProperty FullName ``` -{{ Add example description here }} +This command lists all names of the file after the link was created, which is the same information that `-PassThru` returns. ## PARAMETERS ### -PassThru -{{ Fill PassThru Description }} +Indicates that the cmdlet returns an object for every hard link of the file after the new link has been created, including the names that already existed. By default, this cmdlet produces no output. ```yaml Type: SwitchParameter @@ -51,7 +81,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of the new hard link that the cmdlet creates. The path must not exist yet, and it must be on the same NTFS volume as `-Target`. Relative paths are resolved against the current location. ```yaml Type: String @@ -67,7 +97,7 @@ Accept wildcard characters: False ### -Target -{{ Fill Target Description }} +Specifies the path of the existing file that the new link refers to. The target must exist and must be a file; folders are rejected, because NTFS supports hard links for files only. ```yaml Type: String @@ -88,12 +118,32 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String +You can pass the path of the new link and the path of the target as strings. + ## OUTPUTS ### Alphaleonis.Win32.Filesystem.FileInfo +With `-PassThru`, the cmdlet writes one file object per hard link of the file, extended with a `Mode` property that renders the file attributes in the same notation as `Get-ChildItem2`. Without `-PassThru`, the cmdlet writes nothing. + ### Alphaleonis.Win32.Filesystem.DirectoryInfo +The cmdlet never writes folder objects, because hard links are supported for files only. + ## NOTES +Windows supports hard links only for files on the same NTFS volume. A link that points to a file on another volume, or a target on a file system that does not implement hard links, cannot be created. + +The cmdlet does not overwrite anything. If `-Path` already exists, or if `-Target` is missing or is a folder, the cmdlet reports an error and leaves the file system unchanged. + +Because all names of a file share the same data, the number of hard links is a property of the file, not of an individual name. Use `Get-NTFSHardLink` to list them, and delete a link with `Remove-Item2` or `Remove-Item`, which removes only that name as long as other names remain. + ## RELATED LINKS + +[Get-NTFSHardLink](Get-NTFSHardLink.md) + +[New-NTFSSymbolicLink](New-NTFSSymbolicLink.md) + +[Get-ChildItem2](Get-ChildItem2.md) + +[Remove-Item2](Remove-Item2.md) diff --git a/Docs/Cmdlets/New-NTFSSymbolicLink.md b/Docs/Cmdlets/New-NTFSSymbolicLink.md index 854a647..2be53db 100644 --- a/Docs/Cmdlets/New-NTFSSymbolicLink.md +++ b/Docs/Cmdlets/New-NTFSSymbolicLink.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/New-NTFSSymbolicLink.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Creates a symbolic link to an existing file or folder. ## SYNTAX @@ -19,23 +19,53 @@ New-NTFSSymbolicLink [[-Path] ] [[-Target] ] [-PassThru] [ New-NTFSSymbolicLink -Path C:\Data\Report-Current.txt -Target C:\Data\Archive\Report-2026.txt +``` + +This command creates the symbolic link `Report-Current.txt`, which redirects to the existing file `Report-2026.txt`. Because the target is a file, the cmdlet creates a file symbolic link. + +### Example 2: Create a symbolic link to a folder + +```PowerShell +PS C:\> New-NTFSSymbolicLink -Path C:\Data\Current -Target C:\Data\Archive\2026 +``` + +This command creates the symbolic link `C:\Data\Current`, which redirects to the existing folder `C:\Data\Archive\2026`. Because the target is a folder, the cmdlet creates a directory symbolic link, and paths below `C:\Data\Current` resolve to the corresponding items in the target folder. + +### Example 3: Create a link and return it + +```PowerShell +PS C:\> New-NTFSSymbolicLink -Path C:\Data\Current -Target C:\Data\Archive\2026 -PassThru +``` + +This command creates the link and returns an object for the new link, which you can use to confirm the result in a script. + +### Example 4: Verify that the link resolves ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Test-Path2 -Path C:\Data\Current\Report.txt -PathType Leaf ``` -{{ Add example description here }} +This command tests a path that leads through the symbolic link. It returns `$true` when the link resolves and the file exists in the target folder. ## PARAMETERS ### -PassThru -{{ Fill PassThru Description }} +Indicates that the cmdlet returns an object for the new link. By default, this cmdlet produces no output. The returned object is a file object even when the link points to a folder. ```yaml Type: SwitchParameter @@ -51,7 +81,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of the new symbolic link that the cmdlet creates. The path must not exist yet. Relative paths are resolved against the current location. ```yaml Type: String @@ -67,7 +97,7 @@ Accept wildcard characters: False ### -Target -{{ Fill Target Description }} +Specifies the path of the existing file or folder that the new link points to. The target must exist when the link is created and determines whether the cmdlet creates a file symbolic link or a directory symbolic link. Relative paths are resolved against the current location, so the link stores an absolute target path. ```yaml Type: String @@ -88,12 +118,32 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String +You can pass the path of the new link and the path of the target as strings. + ## OUTPUTS ### Alphaleonis.Win32.Filesystem.FileInfo +With `-PassThru`, the cmdlet writes a file object for the new link. The cmdlet writes that object type for a link to a folder as well. Without `-PassThru`, the cmdlet writes nothing. + ### Alphaleonis.Win32.Filesystem.DirectoryInfo +The cmdlet does not write folder objects. A directory symbolic link is also returned as a file object. + ## NOTES +Creating a symbolic link on Windows requires the "Create symbolic links" user right, `SeCreateSymbolicLinkPrivilege`, which is granted to the Administrators group by default. Without that right, Windows rejects the operation with error 1314, "A required privilege is not held by the client", so run the cmdlet from an elevated session or grant the right to the account. On a computer that runs in Windows Developer Mode, Windows also allows accounts without that right to create symbolic links. + +Unlike a hard link, a symbolic link is a separate file system entry that stores a path, so it can point to an item on another volume and the link and its target can be managed independently. The cmdlet still requires the target to exist at the moment the link is created. If the target is removed later, the link remains and stops resolving. + +Deleting a symbolic link removes the link only and leaves the target untouched. Delete a directory symbolic link as a link rather than recursively, so that the content of the target folder is not affected. + ## RELATED LINKS + +[New-NTFSHardLink](New-NTFSHardLink.md) + +[Get-NTFSHardLink](Get-NTFSHardLink.md) + +[Get-ChildItem2](Get-ChildItem2.md) + +[Test-Path2](Test-Path2.md) diff --git a/Docs/Cmdlets/Remove-Item2.md b/Docs/Cmdlets/Remove-Item2.md index d0c9cc9..8cde166 100644 --- a/Docs/Cmdlets/Remove-Item2.md +++ b/Docs/Cmdlets/Remove-Item2.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Remove-Item2.md schema: 2.0.0 --- @@ -9,27 +9,55 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Deletes a file or folder, including paths longer than 260 characters. ## SYNTAX ``` -Remove-Item2 [[-Path] ] [-Force] [-Recurse] [-PassThur] [-WhatIf] [-Confirm] [] +Remove-Item2 [[-Path] ] [-Force] [-Recurse] [-PassThru] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -{{ Fill in the Description }} +The `Remove-Item2` cmdlet deletes the files and folders in `-Path`. It is the long-path counterpart of the built-in `Remove-Item` cmdlet: it works through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), so it also deletes items whose path exceeds the 260-character `MAX_PATH` limit. The items are deleted permanently and are not moved to the Recycle Bin. + +Relative paths and the `.` and `..` notations are resolved against the current location, and wildcard characters are not supported. `-Path` has no default value: if you omit it, the cmdlet does nothing. Use `-Recurse` to delete a folder that is not empty and `-Force` to delete items that have the read-only attribute. + +The cmdlet supports `-WhatIf` and `-Confirm`, and it writes nothing to the pipeline unless you specify `-PassThru`. ## EXAMPLES -### Example 1 +### Example 1: Delete a file + +```PowerShell +PS C:\> Remove-Item2 -Path C:\Data\report.docx +``` + +Deletes a single file. If the file is read-only, the command fails with a `DeleteError` until you add `-Force`. + +### Example 2: Delete a folder tree with very long paths ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Remove-Item2 -Path C:\Data\Projects\Archive -Recurse -Force ``` -{{ Add example description here }} +Deletes the folder with everything it contains, including read-only files and files whose path is too long for the built-in `Remove-Item` cmdlet. + +### Example 3: Preview what would be deleted + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -File -Filter '*.tmp' | Remove-Item2 -WhatIf +``` + +Lists every temporary file below `C:\Data` and shows which of them the cmdlet would delete. Remove `-WhatIf` to delete them. + +### Example 4: Delete items and keep a record of them + +```PowerShell +PS C:\> rm2 -Path C:\Data\Logs\old.log -PassThru | Select-Object -ExpandProperty FullName +``` + +Uses the `rm2` alias and returns the object of the deleted file, from which the command takes the full path for a log. Since the item no longer exists, only its path information is still meaningful; properties such as `Length` are empty. ## PARAMETERS @@ -51,7 +79,7 @@ Accept wildcard characters: False ### -Force -{{ Fill Force Description }} +Indicates that the cmdlet also deletes items that have the read-only attribute. Without `-Force`, a read-only item causes a `DeleteError`. Combine `-Force` with `-Recurse` to delete a folder that contains read-only files. ```yaml Type: SwitchParameter @@ -65,9 +93,9 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -PassThur +### -PassThru -{{ Fill PassThur Description }} +Indicates that the cmdlet returns an object for each item that it deleted. By default, the cmdlet produces no output. The object describes a path that no longer exists, so use it for logging rather than for further file operations. In NTFSSecurity 4.2.6 and earlier, this parameter is spelled `-PassThur`. ```yaml Type: SwitchParameter @@ -83,7 +111,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of one or more items to delete. Relative paths are resolved against the current location, and wildcard characters are not supported. The parameter has no default value, so the cmdlet deletes nothing if you omit it. It accepts pipeline input by value and by the property name `FullName`, so you can pipe the output of `Get-ChildItem2` or `Get-Item2` into this cmdlet. ```yaml Type: String[] @@ -99,7 +127,7 @@ Accept wildcard characters: False ### -Recurse -{{ Fill Recurse Description }} +Indicates that the cmdlet deletes a folder together with everything it contains. Without `-Recurse`, a folder that is not empty causes a `DeleteError`. The parameter has no effect on files. ```yaml Type: SwitchParameter @@ -137,10 +165,30 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more paths to this cmdlet, either as strings or as objects that have a `FullName` property, such as the output of `Get-ChildItem2` or `Get-Item2`. + ## OUTPUTS ### System.Object +By default this cmdlet returns nothing. With `-PassThru` it returns an `Alphaleonis.Win32.Filesystem.FileInfo` or `Alphaleonis.Win32.Filesystem.DirectoryInfo` object for each item that it deleted. + ## NOTES +`Remove-Item2` deletes through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), which is why it reaches items whose path exceeds the 260-character `MAX_PATH` limit of the built-in `Remove-Item` cmdlet. Deletion is permanent; the cmdlet does not use the Recycle Bin. + +The module defines the aliases `rm2` and `del2` for this cmdlet. + +A path that does not exist causes the error `FileNotFound`, and a deletion that the file system rejects causes a `DeleteError`. In both cases the cmdlet skips the remaining paths that were passed in the same call. Items that arrive one by one through the pipeline are not affected, because each of them is processed separately. + ## RELATED LINKS + +[Copy-Item2](Copy-Item2.md) + +[Move-Item2](Move-Item2.md) + +[Get-ChildItem2](Get-ChildItem2.md) + +[Get-Item2](Get-Item2.md) + +[Test-Path2](Test-Path2.md) diff --git a/Docs/Cmdlets/Remove-NTFSAccess.md b/Docs/Cmdlets/Remove-NTFSAccess.md index 0736c23..bd3d0d4 100644 --- a/Docs/Cmdlets/Remove-NTFSAccess.md +++ b/Docs/Cmdlets/Remove-NTFSAccess.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Remove-NTFSAccess.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Removes rights from the access control entries (ACEs) of a file, a folder, or a security descriptor. ## SYNTAX @@ -42,23 +42,53 @@ Remove-NTFSAccess [-SecurityDescriptor] [-Account] Remove-NTFSAccess -Path C:\Data -Account 'CONTOSO\JohnDoe' -AccessRights Modify +``` + +This command removes the modify rights of an account from `C:\Data`. The entry is matched with the default values of the remaining parameters, which are the access type `Allow` and the inheritance flags `ContainerInherit, ObjectInherit` with no propagation flags. + +### Example 2: Take a single right away from an existing entry ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Remove-NTFSAccess -Path C:\Data -Account 'CONTOSO\Domain Users' -AccessRights DeleteSubdirectoriesAndFiles -AppliesTo ThisFolderSubfoldersAndFiles ``` -{{ Add example description here }} +This command removes one right from the entry of a domain group and leaves the other rights of that entry untouched. + +### Example 3: Remove all explicit permissions of an account + +```PowerShell +PS C:\> Get-NTFSAccess -Path C:\Data -Account 'CONTOSO\JohnDoe' -ExcludeInherited | Remove-NTFSAccess +``` + +This command removes every access control entry that was defined for an account on `C:\Data`. The piped objects supply the path, the account, the rights, the access type, and the flags, so each entry is matched exactly as it exists. + +### Example 4: Clean up orphaned entries in a folder tree + +```PowerShell +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOrphanedAccess -ExcludeInherited | Remove-NTFSAccess +``` + +This command removes the access control entries of deleted accounts from all items below `C:\Data`. `-ExcludeInherited` makes sure that each entry is removed where it is defined instead of where it is inherited. ## PARAMETERS ### -AccessRights -{{ Fill AccessRights Description }} +Specifies the rights to remove from the matching access control entry. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. Rights that the entry grants but that are not listed here remain in place. See [Concepts](../Concepts.md) for how the values relate to the Windows security dialog. ```yaml Type: FileSystemRights2 @@ -75,7 +105,7 @@ Accept wildcard characters: False ### -AccessType -{{ Fill AccessType Description }} +Specifies whether an `Allow` or a `Deny` entry is addressed. The default is `Allow`. An entry of the other type is not touched. ```yaml Type: AccessControlType @@ -85,14 +115,14 @@ Accepted values: Allow, Deny Required: False Position: Named -Default value: None +Default value: Allow Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Account -{{ Fill Account Description }} +Specifies one or more accounts or groups whose entries are changed. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-21-1234567890-1234567890-1234567890-1001`, which is how the entries of deleted accounts are addressed. ```yaml Type: IdentityReference2[] @@ -108,7 +138,7 @@ Accept wildcard characters: False ### -AppliesTo -{{ Fill AppliesTo Description }} +Specifies the scope of the entry that is addressed, in the wording of the Windows security dialog, for example `ThisFolderOnly`, `ThisFolderAndSubfolders`, or `SubfoldersAndFilesOnly`. The cmdlet translates the value into the equivalent inheritance and propagation flags, so this parameter and the pair `-InheritanceFlags` and `-PropagationFlags` are two ways to describe the same entry. Use the scope that `Get-NTFSAccess` shows in the "Applies to" column of the entry. ```yaml Type: ApplyTo @@ -125,7 +155,7 @@ Accept wildcard characters: False ### -InheritanceFlags -{{ Fill InheritanceFlags Description }} +Specifies the inheritance flags of the entry that is addressed. `ContainerInherit` marks an entry that child folders inherit, `ObjectInherit` marks an entry that child files inherit, and `None` marks an entry that is not inherited at all. The default is `ContainerInherit, ObjectInherit`, which is the scope `ThisFolderSubfoldersAndFiles`. Entries on files always carry `None`. ```yaml Type: InheritanceFlags @@ -135,14 +165,14 @@ Accepted values: None, ContainerInherit, ObjectInherit Required: False Position: Named -Default value: None +Default value: ContainerInherit, ObjectInherit Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -PassThru -{{ Fill PassThru Description }} +Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output. ```yaml Type: SwitchParameter @@ -158,7 +188,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files or folders whose access control entries are changed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`. ```yaml Type: String[] @@ -174,7 +204,7 @@ Accept wildcard characters: False ### -PropagationFlags -{{ Fill PropagationFlags Description }} +Specifies the propagation flags of the entry that is addressed. `None` marks an entry that is inherited by all levels allowed by its inheritance flags, `InheritOnly` marks an entry that does not apply to the item it is defined on, and `NoPropagateInherit` marks an entry that is only inherited by the direct children of the folder. The default is `None`. ```yaml Type: PropagationFlags @@ -191,7 +221,7 @@ Accept wildcard characters: False ### -SecurityDescriptor -The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. +Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose access control entries are changed. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system. A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. @@ -214,24 +244,60 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +One or more paths of files or folders, piped by value or by the property `FullName`. + ### Security2.FileSystemSecurity2[] +One or more security descriptors returned by `Get-NTFSSecurityDescriptor`. + ### Security2.IdentityReference2[] +The accounts whose entries are changed, bound from a property named `Account`, `IdentityReference`, or `ID`. The output of `Get-NTFSAccess` and `Get-NTFSOrphanedAccess` supplies `Account`. + ### Security2.FileSystemRights2 +The rights to remove, piped by the property `AccessRights` or `FileSystemRights`. + ### System.Security.AccessControl.AccessControlType +The type of the entry, piped by the property `AccessType` or `AccessControlType`. + ### System.Security.AccessControl.InheritanceFlags +The inheritance flags of the entry, piped by the property `InheritanceFlags` in the `Complex` parameter sets. + ### System.Security.AccessControl.PropagationFlags +The propagation flags of the entry, piped by the property `PropagationFlags` in the `Complex` parameter sets. + ### Security2.ApplyTo +The scope of the entry, piped by the property `AppliesTo` in the `Simple` parameter sets. + ## OUTPUTS ### Security2.FileSystemAccessRule2 +With `-PassThru`, the cmdlet writes all access control entries of every processed item, explicit and inherited. Without `-PassThru` it writes nothing. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +If the ACL of an item cannot be written because access is denied, the cmdlet tries once more after making the current account the owner of the item, and restores the previous owner afterwards. Changing the owner of an item requires the Take Ownership and Restore privileges, so this fallback only succeeds in an elevated session of an account that holds them. + +Removing rights from an entry that does not exist is not an error; the cmdlet leaves the ACL unchanged. + ## RELATED LINKS + +[Get-NTFSAccess](Get-NTFSAccess.md) + +[Add-NTFSAccess](Add-NTFSAccess.md) + +[Clear-NTFSAccess](Clear-NTFSAccess.md) + +[Get-NTFSOrphanedAccess](Get-NTFSOrphanedAccess.md) + +[Disable-NTFSAccessInheritance](Disable-NTFSAccessInheritance.md) + +[Set-NTFSSecurityDescriptor](Set-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Remove-NTFSAudit.md b/Docs/Cmdlets/Remove-NTFSAudit.md index a40dbc1..425464f 100644 --- a/Docs/Cmdlets/Remove-NTFSAudit.md +++ b/Docs/Cmdlets/Remove-NTFSAudit.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Remove-NTFSAudit.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Removes an audit entry from a file or folder. ## SYNTAX @@ -42,23 +42,55 @@ Remove-NTFSAudit [-SecurityDescriptor] [-Account] {{ Add example code here }} +PS C:\> Remove-NTFSAudit -Path C:\Data -Account 'CONTOSO\Domain Users' -AccessRights FullControl -AuditFlags Failure ``` -{{ Add example description here }} +This command removes the entry that audits failed access of `CONTOSO\Domain Users` to `C:\Data`, its subfolders, and its files. + +### Example 2: Remove an audit entry that applies to one folder + +```PowerShell +PS C:\> Remove-NTFSAudit -Path C:\Data -Account Everyone -AccessRights Delete, DeleteSubdirectoriesAndFiles -AuditFlags Success -AppliesTo ThisFolderOnly +``` + +This command removes the entry that audits successful deletions in the folder `C:\Data` itself. Use the same `-AppliesTo` value to remove an audit entry from a file, because audit entries on files are never inherited by child items. + +### Example 3: Remove the audit entries of one account + +```PowerShell +PS C:\> Get-NTFSAudit -Path C:\Data -Account 'CONTOSO\JohnDoe' -ExcludeInherited | Remove-NTFSAudit +``` + +This command reads the explicit audit entries of `CONTOSO\JohnDoe` and pipes them back into `Remove-NTFSAudit`, which removes each of them from the item it came from. The path, account, access rights, audit flags, and inheritance flags all bind from the properties of the piped entries. + +### Example 4: Remove an audit entry from a security descriptor + +```PowerShell +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Remove-NTFSAudit -SecurityDescriptor $sd -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AuditFlags Success, Failure -AppliesTo SubfoldersAndFilesOnly +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd +``` + +This command removes the entry from the in-memory security descriptor of `C:\Data` and then writes the descriptor back to the file system. ## PARAMETERS ### -AccessRights -{{ Fill AccessRights Description }} +Specifies the audited access rights to remove. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. Rights that an existing entry audits beyond the ones you specify stay in place. See [Concepts](../Concepts.md) for the meaning of each right. ```yaml Type: FileSystemRights2 @@ -75,7 +107,7 @@ Accept wildcard characters: False ### -Account -{{ Fill Account Description }} +Specifies the accounts whose audit entries are removed. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. A SID is the only way to address an entry whose account no longer resolves to a name. When you pass several accounts, the cmdlet removes one entry per account. ```yaml Type: IdentityReference2[] @@ -91,7 +123,7 @@ Accept wildcard characters: False ### -AppliesTo -{{ Fill AppliesTo Description }} +Specifies the scope of the audit entry to remove with a single value instead of the `-InheritanceFlags` and `-PropagationFlags` pair, in the same wording the Advanced Security Settings dialog uses. The value must describe the entry as `Get-NTFSAudit` reports it, otherwise nothing is removed. The default is `ThisFolderOnly`. ```yaml Type: ApplyTo @@ -101,14 +133,14 @@ Accepted values: ThisFolderOnly, ThisFolderSubfoldersAndFiles, ThisFolderAndSubf Required: False Position: Named -Default value: None +Default value: ThisFolderOnly Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -AuditFlags -{{ Fill AuditFlags Description }} +Specifies which audited access attempts are removed from the entry. `Success` removes the auditing of successful attempts, `Failure` removes the auditing of denied attempts, and `Success, Failure` removes both. An entry that audits the flag you did not specify stays in place with that flag. The default is `Success, Failure`. ```yaml Type: AuditFlags @@ -118,14 +150,14 @@ Accepted values: None, Success, Failure Required: False Position: Named -Default value: None +Default value: Success, Failure Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -InheritanceFlags -{{ Fill InheritanceFlags Description }} +Specifies the inheritance flags of the audit entry to remove. `ContainerInherit` addresses an entry that child folders inherit, `ObjectInherit` an entry that child files inherit, and `None` an entry that stays on the item itself. The values can be combined, and the default is `ContainerInherit, ObjectInherit`. The flags must match the entry as `Get-NTFSAudit` reports it, otherwise nothing is removed. ```yaml Type: InheritanceFlags @@ -135,14 +167,14 @@ Accepted values: None, ContainerInherit, ObjectInherit Required: False Position: Named -Default value: None +Default value: ContainerInherit, ObjectInherit Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -PassThru -{{ Fill PassThru Description }} +Indicates that the cmdlet writes the access control entries of the processed item or descriptor to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was removed. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns. ```yaml Type: SwitchParameter @@ -158,7 +190,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the files or folders the audit entry is removed from. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. ```yaml Type: String[] @@ -174,7 +206,7 @@ Accept wildcard characters: False ### -PropagationFlags -{{ Fill PropagationFlags Description }} +Specifies the propagation flags of the audit entry to remove. `None` addresses an entry that applies to the item itself and to all inheriting child items, `InheritOnly` an entry that applies to the child items only, and `NoPropagateInherit` an entry whose inheritance stops at the direct children. The values `InheritOnly` and `NoPropagateInherit` can be combined, and the default is `None`. ```yaml Type: PropagationFlags @@ -191,9 +223,7 @@ Accept wildcard characters: False ### -SecurityDescriptor -The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. - -A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. +Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet removes the audit entry from the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. ```yaml Type: FileSystemSecurity2[] @@ -214,24 +244,62 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe paths to this cmdlet, or objects that have a `Path` or `FullName` property, such as the output of `Get-NTFSAudit`, `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2`. + ### Security2.FileSystemSecurity2[] +You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + ### Security2.IdentityReference2[] +The accounts passed to `-Account` are converted to this type from an account name or a SID string. The parameter binds by property name through its own name and its aliases `IdentityReference` and `ID`, so the `Account` property of the entries this module returns supplies the value. + ### Security2.FileSystemRights2 +The value passed to `-AccessRights` is converted to this type. The parameter binds by property name, so an object with an `AccessRights` or `FileSystemRights` property supplies the value. + ### System.Security.AccessControl.AuditFlags +The value passed to `-AuditFlags` is converted to this type and binds by property name. + ### System.Security.AccessControl.InheritanceFlags +The value passed to `-InheritanceFlags` is converted to this type and binds by property name in the `PathComplex` and `SDComplex` parameter sets. + ### System.Security.AccessControl.PropagationFlags +The value passed to `-PropagationFlags` is converted to this type and binds by property name in the `PathComplex` and `SDComplex` parameter sets. + ### Security2.ApplyTo +The value passed to `-AppliesTo` is converted to this type and binds by property name in the `PathSimple` and `SDSimple` parameter sets. + ## OUTPUTS ### Security2.FileSystemAccessRule2 +Without `-PassThru` the cmdlet writes nothing. With `-PassThru` the type depends on the parameter set: in the `Path` sets the cmdlet writes all access entries of the item, explicit and inherited ones, as `Security2.FileSystemAccessRule2` objects, while in the `SecurityDescriptor` sets it writes all audit entries of the descriptor as `Security2.FileSystemAuditRule2` objects. Use `Get-NTFSAudit` to check the audit entries of an item after the removal. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +Reading and writing the SACL requires the Security privilege (`SeSecurityPrivilege`, "Manage auditing and security log"), so run this cmdlet in an elevated session of an account that holds that privilege. Without it, the cmdlet writes a non-terminating `RemoveAceError` whose message states that a required privilege is not held by the client, and the item is left unchanged. + +If the security descriptor cannot be read or written because access is denied, the cmdlet takes ownership of the item, repeats the operation, and restores the previous owner. If the second attempt fails as well, the cmdlet writes an error, and the ownership change is not rolled back. + +The cmdlet reports no error when no entry matches the supplied values. Compare the result with `Get-NTFSAudit` to confirm that the entry is gone. + ## RELATED LINKS + +[Get-NTFSAudit](Get-NTFSAudit.md) + +[Add-NTFSAudit](Add-NTFSAudit.md) + +[Clear-NTFSAudit](Clear-NTFSAudit.md) + +[Get-NTFSOrphanedAudit](Get-NTFSOrphanedAudit.md) + +[Remove-NTFSAccess](Remove-NTFSAccess.md) + +[Set-NTFSSecurityDescriptor](Set-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Set-NTFSInheritance.md b/Docs/Cmdlets/Set-NTFSInheritance.md index cf6301c..4297cf6 100644 --- a/Docs/Cmdlets/Set-NTFSInheritance.md +++ b/Docs/Cmdlets/Set-NTFSInheritance.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Set-NTFSInheritance.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Sets the inheritance of the access rules and the audit rules of a file or folder. ## SYNTAX @@ -27,23 +27,57 @@ Set-NTFSInheritance [-SecurityDescriptor] [-AccessInheri ## DESCRIPTION -{{ Fill in the Description }} +The `Set-NTFSInheritance` cmdlet turns the inheritance of access rules and audit rules on or off in a single call. It reads the current state of the item first and changes a section only when the requested value differs from the current one, which makes the cmdlet suitable for repeatedly applying a desired state to a folder tree. + +The cmdlet performs the same operations as `Enable-NTFSAccessInheritance`, `Disable-NTFSAccessInheritance`, `Enable-NTFSAuditInheritance`, and `Disable-NTFSAuditInheritance`, but it does not expose their switches and it does not use their defaults. `-AccessInheritanceEnabled $false` discards the inherited access rules instead of copying them into the item's own DACL, `-AccessInheritanceEnabled $true` keeps the explicit access rules, `-AuditInheritanceEnabled $false` copies the inherited audit rules into the item's own SACL, and `-AuditInheritanceEnabled $true` removes the explicit audit rules. Use the individual Enable and Disable cmdlets when you need the opposite behavior. + +Specify both `-AccessInheritanceEnabled` and `-AuditInheritanceEnabled`. The cmdlet compares the current state against the parameter value even when the parameter was not supplied, and when such a comparison reports a difference it fails with the non-terminating error "Nullable object must have a value". Omitting `-AccessInheritanceEnabled` always triggers that error, and omitting `-AuditInheritanceEnabled` triggers it in a session that can read the audit section. Changing the audit section requires the Security privilege and therefore an elevated session. + +In the `Path` parameter set the cmdlet writes each changed section back to disk immediately. In the `SecurityDescriptor` parameter set it changes the `Security2.FileSystemSecurity2` object in memory only; nothing reaches the file system until you pass that object to `Set-NTFSSecurityDescriptor`. `-Path`, `-AccessInheritanceEnabled`, and `-AuditInheritanceEnabled` all accept pipeline input by property name, so a `Security2.FileSystemInheritanceInfo` object from `Get-NTFSInheritance` binds to all three at once. ## EXAMPLES -### Example 1 +### Example 1: Block inheritance of both sections ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Set-NTFSInheritance -Path C:\Data\Projects -AccessInheritanceEnabled $false -AuditInheritanceEnabled $false ``` -{{ Add example description here }} +This command protects the DACL and the SACL of `C:\Data\Projects`. The inherited access rules are discarded, so make sure the folder has explicit access rules of its own; the inherited audit rules are copied into the folder's SACL. Changing the audit section requires an elevated session. + +### Example 2: Restore inheritance of both sections + +```PowerShell +PS C:\> Set-NTFSInheritance -Path C:\Data\Projects -AccessInheritanceEnabled $true -AuditInheritanceEnabled $true -PassThru +``` + +This command lets the folder inherit from `C:\Data` again. The explicit access rules are kept, the explicit audit rules are removed, and `-PassThru` returns the resulting state. + +### Example 3: Save a state and apply it again + +```PowerShell +PS C:\> $state = Get-NTFSInheritance -Path C:\Data\Projects +PS C:\> Disable-NTFSAccessInheritance -Path C:\Data\Projects +PS C:\> $state | Set-NTFSInheritance +``` + +The first command records the inheritance state of the folder. After the second command changed it, the third command pipes the recorded object back and restores both values, because `FullName`, `AccessInheritanceEnabled`, and `AuditInheritanceEnabled` bind by property name. + +### Example 4: Change a security descriptor in memory + +```PowerShell +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Projects +PS C:\> Set-NTFSInheritance -SecurityDescriptor $sd -AccessInheritanceEnabled $false -AuditInheritanceEnabled $false +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd +``` + +The first two commands read the security descriptor and change its inheritance in memory, which does not change anything on disk. The third command writes the descriptor back and applies the change. ## PARAMETERS ### -AccessInheritanceEnabled -{{ Fill AccessInheritanceEnabled Description }} +Specifies whether the item inherits access rules from its parent folder. `$true` removes the protection from the DACL and keeps the access rules that are stored directly on the item; `$false` protects the DACL and discards the rules the item currently inherits, which leaves only its explicit rules. The section is left untouched when the requested value already matches the current state. Always supply this parameter, because the cmdlet fails with "Nullable object must have a value" when it has to compare against a value that was not provided. ```yaml Type: Boolean @@ -59,7 +93,7 @@ Accept wildcard characters: False ### -AuditInheritanceEnabled -{{ Fill AuditInheritanceEnabled Description }} +Specifies whether the item inherits audit rules from its parent folder. `$true` removes the protection from the SACL and removes the audit rules that are stored directly on the item; `$false` protects the SACL and copies the inherited audit rules into it. The section is left untouched when the requested value already matches the current state. Reading and writing the audit section requires the Security privilege and therefore an elevated session. ```yaml Type: Boolean @@ -75,7 +109,7 @@ Accept wildcard characters: False ### -PassThru -{{ Fill PassThru Description }} +Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the changes were attempted, so an object is also written when a change failed. ```yaml Type: SwitchParameter @@ -91,7 +125,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files or folders whose inheritance is set. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline. ```yaml Type: String[] @@ -111,6 +145,8 @@ The SecurityDescriptor parameter allows passing an security descriptor or an arr A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. +This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + ```yaml Type: FileSystemSecurity2[] Parameter Sets: SecurityDescriptor @@ -130,14 +166,42 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet. + ### Security2.FileSystemSecurity2[] +You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + ### System.Nullable`1[[System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]] +You can supply `-AccessInheritanceEnabled` and `-AuditInheritanceEnabled` through a pipeline object that has properties of those names, such as the `Security2.FileSystemInheritanceInfo` objects that `Get-NTFSInheritance` returns. + ## OUTPUTS ### System.Object +By default this cmdlet returns no output. With `-PassThru` it writes one `Security2.FileSystemInheritanceInfo` object per item, which reports the `AccessInheritanceEnabled` and `AuditInheritanceEnabled` state after the change. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +The audit section of a security descriptor can only be read and written with the Security privilege (`SeSecurityPrivilege`), which an account can only use in an elevated session. Without it, a requested change of `-AuditInheritanceEnabled` produces a non-terminating error that reports Windows error 1314, "A required privilege is not held by the client". The access section is processed first, so a change of `-AccessInheritanceEnabled` in the same command is applied even when the audit change fails. + +If the descriptor cannot be opened because the account has no permission to the item, the cmdlet takes ownership of the item, applies the changes, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; otherwise the cmdlet writes an error and continues with the next item. + +A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths. + ## RELATED LINKS + +[Get-NTFSInheritance](Get-NTFSInheritance.md) + +[Enable-NTFSAccessInheritance](Enable-NTFSAccessInheritance.md) + +[Disable-NTFSAccessInheritance](Disable-NTFSAccessInheritance.md) + +[Enable-NTFSAuditInheritance](Enable-NTFSAuditInheritance.md) + +[Disable-NTFSAuditInheritance](Disable-NTFSAuditInheritance.md) + +[Set-NTFSSecurityDescriptor](Set-NTFSSecurityDescriptor.md) diff --git a/Docs/Cmdlets/Set-NTFSOwner.md b/Docs/Cmdlets/Set-NTFSOwner.md index 44ff4d0..a461968 100644 --- a/Docs/Cmdlets/Set-NTFSOwner.md +++ b/Docs/Cmdlets/Set-NTFSOwner.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Set-NTFSOwner.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Sets the owner of a file or folder. ## SYNTAX @@ -26,23 +26,55 @@ Set-NTFSOwner [-SecurityDescriptor] [-Account] Set-NTFSOwner -Path C:\Data -Account 'CONTOSO\JohnDoe' +``` + +This command makes `CONTOSO\JohnDoe` the owner of the `C:\Data` folder and writes the change immediately. + +### Example 2: Set the owner of a folder tree and show the result ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Set-NTFSOwner -Account 'BUILTIN\Administrators' -PassThru ``` -{{ Add example description here }} +This command makes the local Administrators group the owner of every file and folder below `C:\Data`. The `-PassThru` parameter returns the new owner of each item. + +### Example 3: Change the owner in a security descriptor and write it back + +```PowerShell +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Set-NTFSOwner -SecurityDescriptor $sd -Account 'BUILTIN\Administrators' +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd +``` + +The first two commands read the security descriptor of `C:\Data` and change its owner in memory. The third command writes the descriptor, which applies the new owner together with every other change made to `$sd`. + +### Example 4: Set the owner by security identifier + +```PowerShell +PS C:\> Set-NTFSOwner -Path C:\Data\Report.docx -Account 'S-1-5-32-544' +``` + +This command makes the account with the security identifier `S-1-5-32-544`, which is the local Administrators group, the owner of the file. Use a SID when an account name cannot be resolved on the current computer. ## PARAMETERS ### -Account -{{ Fill Account Description }} +Specifies the account that becomes the new owner. The value is a `Security2.IdentityReference2` object, which the module creates from an account name such as `CONTOSO\JohnDoe` or `BUILTIN\Administrators`, or from a security identifier such as `S-1-5-32-544`. An account name that cannot be resolved fails during parameter binding. ```yaml Type: IdentityReference2 @@ -58,7 +90,7 @@ Accept wildcard characters: False ### -PassThru -{{ Fill PassThru Description }} +Indicates that the cmdlet returns the owner of each processed item as a `Security2.FileSystemOwner` object. Without this parameter, the cmdlet produces no output. ```yaml Type: SwitchParameter @@ -74,7 +106,7 @@ Accept wildcard characters: False ### -Path -{{ Fill Path Description }} +Specifies the path of one or more files or folders whose owner you want to change. The change is written to the file system immediately. Relative paths are resolved against the current location. When you omit this parameter, the cmdlet does nothing. ```yaml Type: String[] @@ -90,9 +122,7 @@ Accept wildcard characters: False ### -SecurityDescriptor -The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. - -A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. +Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet changes the owner only in memory; pass the descriptor to `Set-NTFSSecurityDescriptor` to write the change to the file system. ```yaml Type: FileSystemSecurity2[] @@ -113,14 +143,34 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more paths to this cmdlet. Objects that expose a `Path` or `FullName` property, such as the output of `Get-ChildItem2` and `Get-Item2`, bind to `-Path` as well. + ### Security2.FileSystemSecurity2[] +You can pipe security descriptors that `Get-NTFSSecurityDescriptor` returned to this cmdlet. + ### Security2.IdentityReference2 +An account binds to `-Account` by property name, so an object that exposes an `Account` property supplies the new owner. + ## OUTPUTS ### Security2.FileSystemOwner +The cmdlet returns one object per processed item only when you use `-PassThru`. It contains the item in `Item`, its path in `FullName`, and the new owner in `Owner` and `Account`. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +Without those privileges, Windows allows the change only when your account already holds the Take Ownership right on the item, and it refuses to assign ownership to another account. In a session that is not elevated, setting an owner other than your own account therefore fails with a non-terminating error. + ## RELATED LINKS + +[Get-NTFSOwner](Get-NTFSOwner.md) + +[Get-NTFSSecurityDescriptor](Get-NTFSSecurityDescriptor.md) + +[Set-NTFSSecurityDescriptor](Set-NTFSSecurityDescriptor.md) + +[Enable-Privileges](Enable-Privileges.md) diff --git a/Docs/Cmdlets/Set-NTFSSecurityDescriptor.md b/Docs/Cmdlets/Set-NTFSSecurityDescriptor.md index d24ee5c..524a566 100644 --- a/Docs/Cmdlets/Set-NTFSSecurityDescriptor.md +++ b/Docs/Cmdlets/Set-NTFSSecurityDescriptor.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Set-NTFSSecurityDescriptor.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Writes a security descriptor to the file or folder it was read from. ## SYNTAX @@ -19,23 +19,59 @@ Set-NTFSSecurityDescriptor [-SecurityDescriptor] [-PassT ## DESCRIPTION -{{ Fill in the Description }} +The `Set-NTFSSecurityDescriptor` cmdlet writes a `Security2.FileSystemSecurity2` object to the file system. It is the final step of the security descriptor workflow: `Get-NTFSSecurityDescriptor` reads a descriptor into memory, cmdlets such as `Add-NTFSAccess`, `Remove-NTFSAccess`, `Set-NTFSOwner`, and `Disable-NTFSAccessInheritance` change that copy through their `-SecurityDescriptor` parameter, and this cmdlet applies all of those changes in a single write. + +Each descriptor remembers the item it was read from, and the cmdlet writes it back to exactly that item. There is no parameter that redirects the write to a different path, and writing a descriptor that you did not change simply re-applies its current content. + +The cmdlet produces no output unless you use `-PassThru`, which reads the item again after the write and returns a new `FileSystemSecurity2` object that reflects what is now stored on disk. Descriptors can be passed as an array or through the pipeline, and each one is processed on its own. + +When the write fails because access is denied, the cmdlet takes ownership of the item with the account of the current session, writes the descriptor, and restores the previous owner. If that fails as well, it writes a non-terminating error and continues with the next descriptor. Windows checks each section separately: changing the access control list requires the Change Permissions right on the item, changing the owner requires the Take Ownership right or the Take Ownership privilege, assigning ownership to another account requires the Restore privilege, and writing audit entries requires the Security privilege. ## EXAMPLES -### Example 1 +### Example 1: Write a changed security descriptor + +```PowerShell +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Add-NTFSAccess -SecurityDescriptor $sd -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AppliesTo ThisFolderSubfoldersAndFiles +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd +``` + +The first two commands add an access control entry to the descriptor in memory, which leaves `C:\Data` untouched. The third command writes the descriptor and applies the new entry to the folder. + +### Example 2: Write several descriptors in one pipeline ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> $descriptors = Get-ChildItem2 -Path C:\Data | Get-NTFSSecurityDescriptor +PS C:\> $descriptors | ForEach-Object { Add-NTFSAccess -SecurityDescriptor $_ -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AppliesTo ThisFolderSubfoldersAndFiles } +PS C:\> $descriptors | Set-NTFSSecurityDescriptor ``` -{{ Add example description here }} +The descriptors of all items in `C:\Data` are read, changed in memory, and then written back. Each descriptor goes to the item it came from. + +### Example 3: Write a new owner + +```PowerShell +PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Report.docx +PS C:\> Set-NTFSOwner -SecurityDescriptor $sd -Account 'BUILTIN\Administrators' +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd +``` + +This sequence changes the owner inside the descriptor and then writes the owner section to the file. + +### Example 4: Verify the result after writing + +```PowerShell +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd -PassThru | Get-NTFSAccess +``` + +This command writes the descriptor, reads the item again, and lists the access control entries that are now stored on it. ## PARAMETERS ### -PassThru -{{ Fill PassThru Description }} +Indicates that the cmdlet reads each item again after the write and returns its current security descriptor. Without this parameter, the cmdlet produces no output. ```yaml Type: SwitchParameter @@ -51,9 +87,7 @@ Accept wildcard characters: False ### -SecurityDescriptor -The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. - -A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. +Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. Each descriptor is written to the file or folder it was read from, including every change that was made to it in memory. ```yaml Type: FileSystemSecurity2[] @@ -74,10 +108,30 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### Security2.FileSystemSecurity2[] +You can pipe one or more security descriptors that `Get-NTFSSecurityDescriptor` returned to this cmdlet. + ## OUTPUTS ### Security2.FileSystemSecurity2 +The cmdlet returns a descriptor per written item only when you use `-PassThru`. That descriptor is read from the item after the write, so it is a new object and not the one you passed in. + ## NOTES +When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message. + +The cmdlet always writes to the item that is stored in the descriptor, so it cannot apply the descriptor of one item to another file or folder. To copy permissions, read the descriptor of the target item, add the entries you need with `Add-NTFSAccess`, and write the target descriptor. + +`Add-NTFSAccess`, `Remove-NTFSAccess`, `Add-NTFSAudit`, and `Remove-NTFSAudit` offer two parameter sets for a security descriptor, one with `-AppliesTo` and one with `-InheritanceFlags` and `-PropagationFlags`. Specify at least one of those parameters when you pass a descriptor to them; otherwise PowerShell cannot decide which parameter set to use and reports an ambiguous parameter set. + ## RELATED LINKS + +[Get-NTFSSecurityDescriptor](Get-NTFSSecurityDescriptor.md) + +[Add-NTFSAccess](Add-NTFSAccess.md) + +[Remove-NTFSAccess](Remove-NTFSAccess.md) + +[Set-NTFSOwner](Set-NTFSOwner.md) + +[Disable-NTFSAccessInheritance](Disable-NTFSAccessInheritance.md) diff --git a/Docs/Cmdlets/Test-Path2.md b/Docs/Cmdlets/Test-Path2.md index 71f3664..ee925f0 100644 --- a/Docs/Cmdlets/Test-Path2.md +++ b/Docs/Cmdlets/Test-Path2.md @@ -1,7 +1,7 @@ --- external help file: NTFSSecurity.dll-Help.xml -Module Name: ntfssecurity -online version: +Module Name: NTFSSecurity +online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Test-Path2.md schema: 2.0.0 --- @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Determines whether a file or folder exists at the specified path. ## SYNTAX @@ -19,23 +19,51 @@ Test-Path2 [-Path] [-PathType ] [] ## DESCRIPTION -{{ Fill in the Description }} +The `Test-Path2` cmdlet returns `$true` when an item exists at the specified path and `$false` when it does not. It resolves paths with the AlphaFS library instead of the Windows PowerShell file system provider, so it also reports items whose full path exceeds the 260-character `MAX_PATH` limit, where the built-in `Test-Path` cmdlet returns `$false`. + +The `-PathType` parameter narrows the test. `Any`, the default, returns `$true` for a file and for a folder, `Container` returns `$true` only for a folder, and `Leaf` returns `$true` only for a file. A path that does not exist returns `$false` for every `-PathType` value. + +`-Path` accepts an array of paths and writes one Boolean value for each of them, in the order in which they are passed. The parameter takes pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem` binds to it. Relative paths are resolved against the current location. ## EXAMPLES -### Example 1 +### Example 1: Test whether a file exists + +```PowerShell +PS C:\> Test-Path2 -Path C:\Data\Report.txt +``` + +This command returns `$true` when `Report.txt` exists in the `C:\Data` folder, regardless of whether it is a file or a folder. + +### Example 2: Test whether a path is a folder + +```PowerShell +PS C:\> Test-Path2 -Path C:\Data -PathType Container +``` + +This command returns `$true` only when `C:\Data` exists and is a folder. If `C:\Data` is a file, the command returns `$false`. + +### Example 3: Test several paths at once + +```PowerShell +PS C:\> Test-Path2 -Path C:\Data\Report.txt, C:\Data\Archive\Report.txt -PathType Leaf +``` + +This command tests both paths and writes one Boolean value for each of them, in the order in which they are given. + +### Example 4: Test paths that come from the pipeline ```PowerShell -PS C:\> {{ Add example code here }} +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Test-Path2 -PathType Leaf ``` -{{ Add example description here }} +This command pipes every item below `C:\Data` to `Test-Path2`, which binds the `FullName` property of each item to `-Path` and reports `$true` for the files and `$false` for the folders. ## PARAMETERS ### -Path -{{ Fill Path Description }} +Specifies one or more paths to test. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. ```yaml Type: String[] @@ -51,7 +79,7 @@ Accept wildcard characters: False ### -PathType -{{ Fill PathType Description }} +Specifies the kind of item that the path must point to. `Any`, the default, matches a file and a folder, `Container` matches only a folder, and `Leaf` matches only a file. ```yaml Type: TestPathType @@ -61,7 +89,7 @@ Accepted values: Any, Container, Leaf Required: False Position: Named -Default value: None +Default value: Any Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` @@ -73,14 +101,34 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String[] +You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2` and `Get-Item2`, to this cmdlet. + ### NTFSSecurity.TestPathType +You can supply the `-PathType` value through a pipeline object that has a `PathType` property. + ## OUTPUTS ### Alphaleonis.Win32.Filesystem.FileInfo +`Test-Path2` does not write file objects. For each path it writes a single `System.Boolean` value that is `$true` when the item exists and matches `-PathType`, and `$false` otherwise. + ### Alphaleonis.Win32.Filesystem.DirectoryInfo +`Test-Path2` does not write folder objects either. A folder is reported through the same `System.Boolean` result as a file. + ## NOTES +The cmdlet resolves paths through the AlphaFS library, which is not bound by the 260-character `MAX_PATH` limit of the Windows PowerShell file system provider. Use `Test-Path2` instead of `Test-Path` when a path can be longer than that limit. + +A path that does not exist is not an error condition. The cmdlet writes `$false` and continues with the next path. + ## RELATED LINKS + +[Get-Item2](Get-Item2.md) + +[Get-ChildItem2](Get-ChildItem2.md) + +[Get-FileHash2](Get-FileHash2.md) + +[Remove-Item2](Remove-Item2.md) diff --git a/Docs/Concepts.md b/Docs/Concepts.md index be71b62..d51cb0d 100644 --- a/Docs/Concepts.md +++ b/Docs/Concepts.md @@ -1,98 +1,268 @@ -# CORE CONCEPTS - -## Overview - -Before starting with the NTFSSecurity module there are some core concepts that you will need to understand. - -There are two ways you can handle permissions, basic and advanced. The basic set of permissions are goups of advanced permissions that allow you to assign common role such as 'Read', 'Read/Write', or 'Full'. Advanced permissions allow you granular control of what can and can't be access or used. The advanced permissions are commonly used to build custom Role-Based Access Control tooling. - -Below is an explaination taken from the fantastic site NTFS.com for each of the advanced file permissions. - -### Traverse Folder/Execute File - -* **Traverse Folder**: Allows or denies moving through a restricted folder to reach files and folders beneath the restricted folder in the folder hierarchy. Traverse folder takes effect only when the group or user is not granted the "Bypass traverse checking user" right in the Group Policy snap-in. This permission does not automatically allow running program files. - -* **Execute File**: Allows or denies running program (executable) files. - -### List Folder/Read Data - -* **List Folder**: Allows or denies viewing file names and subfolder names within the folder. List Folder only affects the contents of that folder and does not affect whether the folder you are setting the permission on will be listed. - -* **Read Data**: Allows or denies viewing data in files. - -### Read Attributes - -* Allows or denies viewing the attributes of a file or folder, for example, "read-only" and "hidden". - -### Read Extended Attributes - -* Allows or denies viewing the extended attributes of a file or folder. Extended attributes are defined by programs and may vary by program. - -### Create Files/Write Data - -* **Create Files**: Allows or denies creating files within the folder. - -* **Write Data**: Allows or denies making changes to a file and overwriting existing content. - -### Create Folders/Append Data - -* **Create Folders**: Allows or denies creating subfolders within the folder. - -* **Append Data**: Allows or denies making changes to the end of the file but not changing, deleting, or overwriting existing data. - -### Write Attributes - -* Allows or denies changing the attributes of a file or folder, for example, "read-only" or "hidden". - -* The Write Attributes permission does not imply creating or deleting files or folders, it only includes the permission to make changes to the attributes of an existing file or folder. - -### Write Extended Attributes - -* Allows or denies changing the extended attributes of a file or folder. Extended attributes are defined by programs and may vary by program. - -* The Write Extended Attributes permission does not imply creating or deleting files or folders, it only includes the permission to make changes to the extended attributes of an existing file or folder. - -### Delete Subfolders and Files - -* Allows or denies deleting subfolders and files, even if the Delete permission has not been granted on the subfolder or file. - -### Delete - -* Allows or denies deleting the file or folder. If you don't have Delete permission on a file or folder, you can still delete it if you have been granted Delete Subfolders and Files on the parent folder. - -### Read Permissions - -* Allows or denies reading permissions of a file or folder. - -### Change Permissions - -* Allows or denies changing permissions of the file or folder. - -### Take Ownership - -* Allows or denies taking ownership of the file or folder. The owner of a file or folder can always change permissions on it, regardless of any existing permissions that protect the file or folder. - -You can see how the basic permissions, advanced permissions, and the NTFSSecurity module relate to one another in the below table. - -| NTFSSecurity | AccessRight displayed | Advanced Security Window | -|------------------------------|------------------------------|---------------------------------------------------------------------------------------------------------------------------| -| ReadData | ListDirectory | List Folder / Read Data | -| ListDirectory | ListDirectory | List Folder / Read Data | -| WriteData | CreateFile | Create Files / Write Data | -| CreateFiles | CreateFile | Create Files / Write Data | -| AppendData | CreateDirectories | Create Folders / Append Data | -| CreateDirectories | CreateDirectories | Create Folders / Append Data | -| ReadExtendedAttributes | ReadExtendedAttributes | Read Extended Attributes | -| WriteExtendedAttributes | WriteExtendedAttributes | WriteExtendedAttributes | -| ExecuteFile | Traverse | Traverse Folder / Execute File | -| Traverse | Traverse | Traverse Folder / Execute File | -| DeleteSubdirectoriesAndFiles | DeleteSubdirectoriesAndFiles | Delete Sub-folders and Files | -| ReadAttributes | ReadAttributes | Read Attributes | -| WriteAttributes | WriteAttributes | Write Attributes | -| Write | Write | Create Files / Write Data, Create Folders / Append Data, Write-Attributes, Write Extended Attributes | -| Delete | Delete | Delete | -| ReadPermissions | ReadPermissions | Read Permissions | -| Read | Read | List Folder / Read Data, Read Attributes, Read Extended Attributes, Read Permissions | -| ReadAndExecute | ReadAndExecute | Traverse Folder / Execute File, List Folder / Read Data, Read Attributes, Read Extended Attributes, Read Permissions | -| Modify | Modify | Everything except Full Control, Delete SubFolders and Files, Change Permissions, Take Ownership | -| ChangePermissions | ChangePermissions | Change Permissions | +# Concepts + +This page explains the Windows security concepts that the NTFSSecurity +cmdlets work with: security descriptors, accounts, access rights, +inheritance, privileges, long paths, and the module settings. Read it before +you change permissions on production data. + +## Security descriptors + +Every file and folder on an NTFS volume has a security descriptor. The module +manages three of its parts: + +| Part | Purpose | Cmdlets | +| --- | --- | --- | +| Owner | The account that owns the item. The owner can always read and change the item's permissions. | `Get-NTFSOwner`, `Set-NTFSOwner` | +| Discretionary access control list (DACL) | Access control entries (ACEs) that allow or deny access. | `Get-NTFSAccess`, `Add-NTFSAccess`, `Remove-NTFSAccess`, `Clear-NTFSAccess` | +| System access control list (SACL) | Audit entries that tell Windows which access attempts to write to the Security event log. | `Get-NTFSAudit`, `Add-NTFSAudit`, `Remove-NTFSAudit`, `Clear-NTFSAudit` | + +Each entry is either explicit, which means it is set on the item itself, or +inherited from a parent folder. Inheritance is controlled separately for the +DACL and the SACL; see [Inheritance](#inheritance). + +Most cmdlets accept either `-Path` or `-SecurityDescriptor`: + +- With `-Path`, the cmdlet reads or writes the item directly. `-Path` + accepts pipeline input, so you can pipe the output of `Get-ChildItem`, + `Get-ChildItem2`, or `Get-Item2` into the cmdlet. +- With `-SecurityDescriptor`, the cmdlet changes a security descriptor object + that you got from `Get-NTFSSecurityDescriptor`. Nothing is written to disk + until you pass the object to `Set-NTFSSecurityDescriptor`, so you can make + several changes and write them in one step. + +When you pass a security descriptor to `Add-NTFSAccess`, `Remove-NTFSAccess`, +`Add-NTFSAudit`, or `Remove-NTFSAudit`, also specify `-AppliesTo` or the +`-InheritanceFlags` and `-PropagationFlags` parameters. Without them, +PowerShell cannot choose between the two security descriptor parameter sets +and reports that the parameter set cannot be resolved. + +## Accounts + +The `-Account` parameter accepts an account name, such as +`CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or a security +identifier (SID) string, such as `S-1-5-32-545`. The output shows the account +name when Windows can resolve the SID. + +An entry whose SID no longer resolves to an account is called orphaned. +This happens when an account was deleted. `Get-NTFSOrphanedAccess` and +`Get-NTFSOrphanedAudit` list such entries. A SID can also fail to resolve +temporarily, for example when a domain controller is unreachable, so check +the results before you remove them. + +## Access rights + +The `-AccessRights` parameter takes a `FileSystemRights2` value. You can +combine values by passing a list, for example +`-AccessRights Delete, DeleteSubdirectoriesAndFiles`. + +PowerShell also accepts any unambiguous prefix of a value name, so `Full` +binds to `FullControl` and `Mod` binds to `Modify`. Use the full names in +scripts. + +### Basic permissions + +The basic permissions on the **Security** tab of the file or folder +properties are combinations of the advanced permissions: + +| `-AccessRights` value | Includes | Basic permission | +| --- | --- | --- | +| `Read` | `ListDirectory`, `ReadAttributes`, `ReadExtendedAttributes`, `ReadPermissions` | Read | +| `ReadAndExecute` | `Read` and `Traverse` | Read & execute | +| `Write` | `CreateFiles`, `CreateDirectories`, `WriteAttributes`, `WriteExtendedAttributes` | Write | +| `Modify` | `ReadAndExecute`, `Write`, and `Delete` | Modify | +| `FullControl` | `Modify`, `DeleteSubdirectoriesAndFiles`, `ChangePermissions`, `TakeOwnership`, and `Synchronize` | Full control | + +### Advanced permissions + +Several advanced permissions have two names because the same bit means +something different for files and for folders. The output always shows the +first name in the table. + +| `-AccessRights` value | Shown as | Advanced permission | Effect | +| --- | --- | --- | --- | +| `ListDirectory`, `ReadData` | `ListDirectory` | List folder / read data | List the contents of a folder; read the data of a file. | +| `CreateFiles`, `WriteData` | `CreateFiles` | Create files / write data | Create files in a folder; change or overwrite the data of a file. | +| `CreateDirectories`, `AppendData` | `CreateDirectories` | Create folders / append data | Create subfolders; append data to the end of a file. | +| `Traverse`, `ExecuteFile` | `Traverse` | Traverse folder / execute file | Move through a folder to reach items below it; run a program file. | +| `ReadAttributes` | `ReadAttributes` | Read attributes | Read attributes such as read-only and hidden. | +| `WriteAttributes` | `WriteAttributes` | Write attributes | Change attributes such as read-only and hidden. | +| `ReadExtendedAttributes` | `ReadExtendedAttributes` | Read extended attributes | Read the extended attributes that programs define. | +| `WriteExtendedAttributes` | `WriteExtendedAttributes` | Write extended attributes | Change the extended attributes that programs define. | +| `DeleteSubdirectoriesAndFiles` | `DeleteSubdirectoriesAndFiles` | Delete subfolders and files | Delete items in a folder, even without `Delete` on those items. | +| `Delete` | `Delete` | Delete | Delete the item. | +| `ReadPermissions` | `ReadPermissions` | Read permissions | Read the owner and the permissions. | +| `ChangePermissions` | `ChangePermissions` | Change permissions | Change the permissions. | +| `TakeOwnership` | `TakeOwnership` | Take ownership | Make yourself the owner. | +| `Synchronize` | `Synchronize` | Not shown | Wait on a file handle. | + +Windows adds `Synchronize` to every allow entry except `FullControl`, which +already contains it. Reading an entry back therefore shows, for example, +`Modify, Synchronize`. + +Windows also merges entries that have the same account, type, and +inheritance settings. Adding `Read` and then `Write` for the same account +results in one entry with both rights. + +The generic rights `GenericRead`, `GenericWrite`, `GenericExecute`, and +`GenericAll` are mapped by Windows to the file rights above. On a folder that +passes the entry on to its children, Windows stores two entries: one with the +mapped rights for the folder and one that keeps the generic right for the +child items. + +`Get-NTFSSimpleAccess` works on folders only. It condenses the rights of each +entry into the simple values `Read`, `Write`, and `Delete`. For every folder +after the first one, it reports only the entries that differ from the parent +folder, which shows where the permissions change in a folder tree. + +## Inheritance + +A folder passes its inheritable entries on to its child items. You can stop +an item from inheriting entries, separately for access entries and for audit +entries: + +- `Disable-NTFSAccessInheritance` blocks inheritance. By default, it copies + the inherited entries as explicit entries; `-RemoveInheritedAccessRules` + drops them instead. +- `Enable-NTFSAccessInheritance` restores inheritance and keeps the explicit + entries unless you use `-RemoveExplicitAccessRules`. +- `Get-NTFSInheritance` and `Set-NTFSInheritance` read and set both + settings at once. Unlike the dedicated cmdlets, `Set-NTFSInheritance` + removes the inherited access entries when it turns access inheritance off, + and removes the explicit audit entries when it turns audit inheritance on. + The audit equivalents of the dedicated cmdlets are + `Disable-NTFSAuditInheritance` and `Enable-NTFSAuditInheritance`. + +### The AppliesTo parameter + +Whether and how an entry is passed on is defined by its inheritance flags +and propagation flags. The `-AppliesTo` parameter of `Add-NTFSAccess`, +`Remove-NTFSAccess`, `Add-NTFSAudit`, and `Remove-NTFSAudit` sets both with +the names that the **Applies to** list in the **Advanced Security Settings** +dialog uses: + +| `-AppliesTo` value | `InheritanceFlags` | `PropagationFlags` | Applies to | +| --- | --- | --- | --- | +| `ThisFolderOnly` | `None` | `None` | This folder only | +| `ThisFolderSubfoldersAndFiles` | `ContainerInherit, ObjectInherit` | `None` | This folder, subfolders and files | +| `ThisFolderAndSubfolders` | `ContainerInherit` | `None` | This folder and subfolders | +| `ThisFolderAndFiles` | `ObjectInherit` | `None` | This folder and files | +| `SubfoldersAndFilesOnly` | `ContainerInherit, ObjectInherit` | `InheritOnly` | Subfolders and files only | +| `SubfoldersOnly` | `ContainerInherit` | `InheritOnly` | Subfolders only | +| `FilesOnly` | `ObjectInherit` | `InheritOnly` | Files only | + +Each value also exists with the suffix `OneLevel`, for example +`ThisFolderAndSubfoldersOneLevel`. These values add the `NoPropagateInherit` +propagation flag, which passes the entry on to the direct children only. In +the dialog, this is the check box **Only apply these permissions to objects +and/or containers within this container**. + +The flags mean: + +- `ContainerInherit`: child folders inherit the entry. +- `ObjectInherit`: child files inherit the entry. +- `InheritOnly`: the entry applies only to the children, not to the item + that holds it. +- `NoPropagateInherit`: the entry is passed on one level only. + +`Add-NTFSAccess` and `Add-NTFSAudit` use `ThisFolderSubfoldersAndFiles` by +default. Files have no children, so entries on files are stored without +inheritance flags. + +## Privileges + +Windows grants the following privileges to the local Administrators group. +They bypass the permission checks that would otherwise stop you from reading +or changing an item: + +| Privilege | Windows name | What it allows | +| --- | --- | --- | +| Backup | `SeBackupPrivilege` | Read any file or folder, regardless of its permissions. | +| Restore | `SeRestorePrivilege` | Write any file or folder and set any account as the owner. | +| Take ownership | `SeTakeOwnershipPrivilege` | Make yourself the owner of any item. | +| Security | `SeSecurityPrivilege` | Read and change audit entries (the SACL). | + +A privilege can only be enabled if the account holds it and the PowerShell +session runs elevated (**Run as administrator**). + +The access, audit, inheritance, owner, and security descriptor cmdlets enable +these privileges automatically while they run and disable the ones they +enabled when they finish. If a privilege cannot be enabled, the cmdlet +continues without it. You can turn this behavior off with the +`EnablePrivileges` module setting. The inheritance cmdlets are an exception: +they always try to enable the privileges, and when `EnablePrivileges` is +`$false`, they leave them enabled. + +`Enable-Privileges` enables the four privileges for the current PowerShell +process until you run `Disable-Privileges` or close the session. +`Get-Privileges` lists the privileges of the current process and their +state. + +When reading or changing an item fails with an access-denied error, most of +these cmdlets make the current user the owner of the item, retry, and then +restore the previous owner. This requires the privileges above. + +Reading or changing audit entries always requires the Security privilege. +Without it, the audit cmdlets fail, and `Get-NTFSEffectiveAccess` warns that +it might not be able to read the effective permissions. + +## Long paths + +Windows PowerShell 5.1 cannot handle paths longer than 260 characters; +`Get-ChildItem` fails on them. The cmdlets `Get-ChildItem2`, `Get-Item2`, +`Copy-Item2`, `Move-Item2`, `Remove-Item2`, and `Test-Path2` use the +[AlphaFS](https://github.com/alphaleonis/AlphaFS) library and work with long +paths. Their output binds to the `-Path` parameter of the NTFSSecurity +cmdlets, which handle long paths as well: + +```powershell +Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSAccess -ExcludeInherited +``` + +The module defines the aliases `dir2` for `Get-ChildItem2`, `gi2` for +`Get-Item2`, and `rm2` and `del2` for `Remove-Item2`. + +## Extended file and folder objects + +The module extends the `FileInfo` and `DirectoryInfo` objects that +`Get-Item` and `Get-ChildItem` return. These members are not available on +the AlphaFS objects that the `*-Item2` cmdlets return. + +| Member | Type | Available on | Description | +| --- | --- | --- | --- | +| `Owner` | Property | Files and folders | The owner of the item. | +| `IsInheritanceBlocked` | Property | Files and folders | `$true` if the item does not inherit access entries. | +| `LengthOnDisk` | Property | Files | The file size rounded up to whole clusters of the volume. `Size` is an alias. | +| `EnableInheritance()` | Method | Files and folders | Turns on access inheritance. | +| `DisableInheritance()` | Method | Files and folders | Turns off access inheritance. Pass `$false` to drop the inherited entries instead of copying them. | +| `GetHash()` | Method | Files | Returns the SHA1 hash of the file as a hexadecimal string. | + +Access entries returned by `Get-NTFSAccess` have an additional `AccountType` +property. When the current user is a domain account, reading the property +queries Active Directory and returns the object class of the account, such +as `user` or `group`; otherwise, the property is empty. + +## Module settings + +The `PrivateData` section of `NTFSSecurity.psd1` contains switches that +change the module's behavior: + +| Setting | Default | Effect | +| --- | --- | --- | +| `EnablePrivileges` | `$true` | The security cmdlets enable the Backup, Restore, Take Ownership, and Security privileges while they run. | +| `GetInheritedFrom` | `$true` | `Get-NTFSAccess` and `Get-NTFSAudit` fill the `InheritedFrom` property with the path of the folder that an inherited entry comes from. | +| `GetFileSystemModeProperty` | `$true` | `Get-ChildItem2` adds the `Mode` property to its output. | +| `IdentifyHardLinks` | `$true` | `Get-ChildItem2` adds a `HardLinkCount` property to each file. | +| `ShowAccountSid` | `$false` | The default table output of access and audit entries shows the SID next to the account name. | + +`GetInheritedFrom`, `GetFileSystemModeProperty`, and `IdentifyHardLinks` +cost extra work for every item. Turn them off to speed up large folder +trees when you don't need the information. + +To change a setting for the current session only, change the value after +you import the module: + +```powershell +(Get-Module -Name NTFSSecurity).PrivateData.ShowAccountSid = $true +``` + +To change the default, edit `NTFSSecurity.psd1` in the module folder. diff --git a/Docs/Contributing.md b/Docs/Contributing.md index f9e0e26..016690e 100644 --- a/Docs/Contributing.md +++ b/Docs/Contributing.md @@ -1,10 +1,14 @@ -# Contributor Guide +# Contributor guide -Thank you for your interest in contributing to quality documentations. -As an open source project, we welcome input and updates from the community. -The following topics explain how to contribute to the NTFSAccess documentation. +Thank you for your interest in improving NTFSSecurity and its documentation. +As an open source project, NTFSSecurity welcomes input and updates from the +community. The following pages explain how to contribute to the +documentation: -1. [Get started](./Contributing/01-Getting-Started.md) -2. [Writing PowerShell documentation](./Contributing/02-Writing.md) +1. [Get started](Contributing/01-Getting-Started.md) +2. [Write documentation](Contributing/02-Writing.md) +3. [Style guide](Contributing/03-Style-Guide.md) +4. [Markdown and platyPS specifics](Contributing/04-Markdown-Specifics.md) -This contributor guide is a modified version of the one found on the [Powershell Docs](https://github.com/PowerShell/PowerShell-Docs) GitHub page. +This guide is adapted from the contributor guide of the +[PowerShell documentation](https://github.com/MicrosoftDocs/PowerShell-Docs). diff --git a/Docs/Contributing/01-Getting-Started.md b/Docs/Contributing/01-Getting-Started.md index 42ba548..9a02eb6 100644 --- a/Docs/Contributing/01-Getting-Started.md +++ b/Docs/Contributing/01-Getting-Started.md @@ -1,54 +1,46 @@ -# Contributing to PowerShell Documentation +# Get started -Thank you for your interest in NTFSAccess documentation! +This page explains how to report a problem with the NTFSSecurity +documentation and how to propose a change. For general information about Git +and GitHub, see the [GitHub documentation][git-help]. -See below for details on how you can contribute to our technical documentation. +## Report a problem -> For general information about getting started with Git and GitHub, see [GitHub Help][git-help]. +Report errors, suggest changes, or request new topics by +[creating an issue][new-issue] in the +[NTFSSecurity repository][issues]. Issues about the documentation use the +**Documentation** label. -## Providing feedback on NTFSAccess documentation +## Make a small change -Report errors, suggest changes, or request new topics by [creating an issue][new-issue] on the -[NTFSAccess repository issues page][doc-issues]. +To fix a typo or a sentence, open the page in the +[NTFSSecurity repository][repo] and select **Edit this file**. GitHub +creates a fork of the repository in your account for you. When you're done, +commit your change and open a [pull request][pull] against the `master` +branch. A maintainer reviews the pull request before merging it. -## Making minor edits to existing topics +## Make a larger change -To [edit an existing file][edit-file], navigate to it and click the "Edit" button. GitHub will -automatically create your own fork of our repository where you can make your changes. Once you are -finished, save your edits and submit a [pull request][pull] to the *staging* branch of the -[NTFSAccess-Docs][docs-repo] repository. After your pull request is created, someone on the -NTFSAccess documentation team reviews your changes before merging them into the *staging* branch. +For new pages, new images, or changes to many pages, work in your own clone: -## Making major edits to existing topics - -If you are making significant changes, adding or changing images, or contributing a new article, you -need to create a GitHub fork and clone it to your computer. A fork is a GitHub-based replica of the -main repository, under your GitHub account, that provides you with a working copy which you can use -in isolation. You create pull requests from your fork. Similarly, a clone is a local-based replica -of the repository which, in this case, is a clone of your fork. The clone allows you to work on Git -repositories offline, and using more powerful native software/tools. - -Here is the workflow for making major edits to existing documentation: - -1. [Create a fork][fork] of the [NTFSAccess][docs-repo] repository. -2. [Create a clone of your fork][clone] on your local computer. -3. Create a new local branch in your cloned repository. -4. Make changes to the file(s) you want to update in a Markdown editor. -5. [Push your local branch][push] to your fork. -6. [Create a pull request][pull] to the *staging* branch of the [NTFSAccess-Docs][docs-repo] - repository. +1. [Fork][fork] the [NTFSSecurity repository][repo]. +2. [Clone][clone] your fork to your computer. +3. Create a branch in your clone. +4. Change the files in a Markdown editor. +5. [Push][push] the branch to your fork. +6. [Open a pull request][pull] against the `master` branch of + [raandree/NTFSSecurity][repo]. ## Next steps -See [Writing documentation](02-Writing.md). +See [Write documentation](02-Writing.md). -[git-help]: https://help.github.com/ -[new-issue]: https://help.github.com/articles/creating-an-issue/ -[doc-issues]: https://github.com/raandree/NTFSSecurity/issues -[edit-file]: https://help.github.com/articles/editing-files-in-another-user-s-repository/ -[docs-repo]: https://github.com/raandree/NTFSSecurity/ -[fork]: https://help.github.com/articles/fork-a-repo/ -[clone]: https://help.github.com/articles/cloning-a-repository/ -[push]: https://help.github.com/articles/pushing-to-a-remote/ -[pull]: https://help.github.com/articles/creating-a-pull-request/ \ No newline at end of file +[git-help]: https://docs.github.com/en/get-started +[new-issue]: https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue +[issues]: https://github.com/raandree/NTFSSecurity/issues +[repo]: https://github.com/raandree/NTFSSecurity +[fork]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo +[clone]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository +[push]: https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository +[pull]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request diff --git a/Docs/Contributing/02-Writing.md b/Docs/Contributing/02-Writing.md index b546560..8c850d0 100644 --- a/Docs/Contributing/02-Writing.md +++ b/Docs/Contributing/02-Writing.md @@ -1,55 +1,122 @@ -# WRITING DOCUMENTATION +# Write documentation -One of the easiest ways to contribute to the NTFSAccess PowerShell module is by helping to write and edit documentation. -All the documentation hosted on GitHub is written using *Markdown*. Markdown is a lightweight markup -language with plain text formatting syntax. Markdown forms the basis of our documentation's -conceptual authoring language. Creating new articles is as easy as writing a simple text file by -using your favorite text editor. +The NTFSSecurity documentation is written in Markdown and built into a +website with [MkDocs][mkdocs]. This page explains how the documentation is +organized and how to change it. + +## Documentation structure + +| Path | Content | +| --- | --- | +| `Docs/index.md` | Home page with features, requirements, and the cmdlet list | +| `Docs/Concepts.md` | Background on security descriptors, rights, inheritance, and privileges | +| `Docs/Examples.md` | Task-oriented examples | +| `Docs/Cmdlets/*.md` | One reference page per cmdlet, in platyPS format | +| `Docs/Contributing.md`, `Docs/Contributing/*.md` | This contributor guide | +| `mkdocs.yml` | Site settings and navigation | +| `.readthedocs.yml` | Build settings for Read the Docs | +| `README.md` | Front page of the GitHub repository | + +When you add a page, add it to the `nav` section of `mkdocs.yml`. ## Markdown editors -Here are some Markdown editors you can try out: +Any text editor works. These editors have good Markdown support: + +- [Visual Studio Code](https://code.visualstudio.com) with the + [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) + extension +- [Sublime Text](https://www.sublimetext.com/) + +To get started with Markdown, see +[How to use Markdown for writing Docs](https://learn.microsoft.com/contribute/content/markdown-reference). +Don't use hard tabs. For the rules that apply to this repository, see +[Markdown and platyPS specifics](04-Markdown-Specifics.md). + +## Update the cmdlet reference + +The pages in `Docs/Cmdlets` are [platyPS][platyps] Markdown files. platyPS +reads the parameter metadata from the module, so the syntax and the parameter +details always match the code. You write the synopsis, the description, the +parameter descriptions, the examples, and the notes. + +When a cmdlet changes, build the module, import the build output, and update +the pages in Windows PowerShell 5.1. A Release build writes the module to +`NTFSSecurity\bin\Release`; the `before_build` and `build_script` steps in +`appveyor.yml` show the commands that the CI build uses: + +```powershell +Install-Module -Name platyPS -RequiredVersion 0.14.2 +Import-Module -Name .\NTFSSecurity\bin\Release\NTFSSecurity.psd1 +Update-MarkdownHelp -Path .\Docs\Cmdlets +``` + +`Update-MarkdownHelp` updates the syntax and the parameter metadata and keeps +the text that you wrote. Fill in the description of every new parameter. + +Use Windows PowerShell 5.1 for platyPS. In PowerShell 7.4 and later, +platyPS 0.14.2 adds the `-ProgressAction` common parameter to every page. + +For a new cmdlet, create the page, replace every placeholder in it, and add +the page to `mkdocs.yml`. Replace `Get-NTFSExample` with the name of the new +cmdlet: + +```powershell +New-MarkdownHelp -Command Get-NTFSExample -OutputFolder .\Docs\Cmdlets +``` + +To check that the pages can be converted to the help file that `Get-Help` +reads, run `New-ExternalHelp`: + +```powershell +New-ExternalHelp -Path .\Docs\Cmdlets -OutputPath $env:TEMP\NTFSSecurityHelp +``` + +## Preview the website -- [Visual Studio Code](https://code.visualstudio.com) -- [Atom](https://atom.io/) -- [Sublime Text](http://www.sublimetext.com/) +MkDocs needs Python. Install the MkDocs version that the site is built with +and start the preview server: -## Get started using Markdown +```powershell +pip install -r Docs/requirements.txt +mkdocs serve +``` -To get started using Markdown, see [How to use Markdown for writing Docs](https://docs.microsoft.com/contribute/how-to-write-use-markdown). +Open `http://127.0.0.1:8000` in a browser. The preview reloads when you save +a file. Run `mkdocs build --strict` to find broken links and pages that are +missing from the navigation. -NTFSSecurity uses the [Mkdocs][mkdocs] builder on ReadTheDocs for documentation. +## Check your change -Don't use hard tabs in Markdown. For more detailed information about the Markdown specification, see the -[Markdown Specifics](04-Markdown-Specifics.md) article. +Before you open a pull request, check the following: -## Creating new topics +- No page in `Docs/Cmdlets` contains a `{{ ... }}` placeholder. +- `Update-MarkdownHelp` doesn't change any page in `Docs/Cmdlets`. The build + defined in `appveyor.yml` runs the same check. +- All links work. The build checks them with `Get-MarkdownLink` from the + MarkdownLinkCheck module: -To contribute new documentation, check for issues tagged as ["Help Wanted"][labels] to make sure -you're not duplicating efforts. If no one seems to be working on what you have planned: + ```powershell + Get-MarkdownLink -Path .\Docs -BrokenOnly + ``` -- Open a new issue and label it as "in progress". If you don't have rights to assign labels, add "in - progress" as a comment to tell others what you're working on. -- Follow the same workflow as described above for making major edits to existing topics. -- Add your new article to the `TOC.yml` file (located in the top-level folder of each - documentation set). +- Every example works. Test examples in a test folder, never on production + data. -## Updating topics that exist in multiple versions +## Create new topics -Most reference topics are duplicated across all versions of PowerShell. When reporting an issue -about a cmdlet reference or an About_ article, you must specify which versions are affected by the -issue. The default issue template in GitHub includes a [GFM task list][gfm-task]. Use the checkboxes -in the task list to specify which versions of the content are affected. When you submit a change to -a article for an issue that affects multiple versions of the content, you must apply the appropriate -change to each version of the file. +Before you write a new topic, check the issues labeled +[Documentation][label-documentation] or [Help Wanted][label-help-wanted] to +make sure nobody else is working on it. If nobody is, open an issue that +describes the topic and say that you're working on it. Then follow the +workflow for larger changes in [Get started](01-Getting-Started.md). -## Next Steps +## Next steps -Read the [Style Guide](03-Style-Guide.md). +Read the [Style guide](03-Style-Guide.md). -[markdig]: https://github.com/lunet-io/markdig -[CommonMark]: https://spec.commonmark.org/ -[gfm-help]: https://help.github.com/categories/writing-on-github/ -[labels]: https://github.com/raandree/NTFSSecurity/labels/Help%20Wanted -[mkdocs]: https://www.mkdocs.org/user-guide/writing-your-docs/ \ No newline at end of file +[mkdocs]: https://www.mkdocs.org/user-guide/writing-your-docs/ +[platyps]: https://github.com/PowerShell/platyPS +[label-documentation]: https://github.com/raandree/NTFSSecurity/labels/Documentation +[label-help-wanted]: https://github.com/raandree/NTFSSecurity/labels/Help%20Wanted diff --git a/Docs/Contributing/03-Style-Guide.md b/Docs/Contributing/03-Style-Guide.md index e69de29..7b330dc 100644 --- a/Docs/Contributing/03-Style-Guide.md +++ b/Docs/Contributing/03-Style-Guide.md @@ -0,0 +1,52 @@ +# Style guide + +Follow these rules so that the NTFSSecurity documentation reads as one +consistent set of pages. + +## Language + +- Write in American English, in the present tense, and in the active voice. +- Address the reader as "you". +- Keep sentences short, with one idea per sentence. +- Write product names as their owners do: PowerShell, Windows PowerShell, + NTFS, Active Directory, GitHub. +- Format cmdlet names, parameter names, values, type names, paths, and code + as code with backticks, for example `Add-NTFSAccess -AccessRights Modify`. +- Describe what the code does. Check every statement about behavior against + the source code or a test run. + +## Examples + +- Use the sample accounts `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, + `BUILTIN\Users`, and `BUILTIN\Administrators`. +- Use sample paths below `C:\Data`. +- Use full cmdlet names, full parameter names, and full value names, for + example `FullControl` instead of `Full`. Don't use aliases or positional + parameters unless the example is about them. +- Test every example in a test folder before you publish it. +- Don't publish output that shows real computer, domain, or user names. + Describe the result in a sentence instead. +- Say when an example needs an elevated session. + +## Cmdlet reference pages + +| Section | Content | +| --- | --- | +| SYNOPSIS | One sentence that starts with a verb in the third person, for example "Gets ..." or "Adds ...". | +| DESCRIPTION | What the cmdlet does, what it works on, how the parameter sets differ, defaults, and the module settings that affect it. | +| EXAMPLES | Two to four realistic tasks. Each example has a title, the command, and a sentence that explains the result. | +| PARAMETERS | "Specifies ..." for parameters that take a value and "Indicates that ..." for switches. Name the default when the parameter is omitted. | +| INPUTS and OUTPUTS | One sentence per type. Say when the cmdlet writes nothing by default. | +| NOTES | Required privileges, limitations, and differences between versions. | +| RELATED LINKS | Links to closely related cmdlet pages. | + +## Conceptual pages + +- Use one level 1 heading per page and sentence case for all headings. +- Start each page with a short introduction that says what the page covers. +- Wrap lines at 80 characters, except in tables, links, and code blocks. +- Link to the cmdlet reference instead of repeating parameter details. + +## Next steps + +Read [Markdown and platyPS specifics](04-Markdown-Specifics.md). diff --git a/Docs/Contributing/04-Markdown-Specifics.md b/Docs/Contributing/04-Markdown-Specifics.md index e69de29..0e85423 100644 --- a/Docs/Contributing/04-Markdown-Specifics.md +++ b/Docs/Contributing/04-Markdown-Specifics.md @@ -0,0 +1,48 @@ +# Markdown and platyPS specifics + +This page lists the Markdown rules for the NTFSSecurity documentation and +the additional rules for the cmdlet reference pages, which platyPS processes. + +## Markdown + +- Use ATX headings (`#`), one level 1 heading per page, and don't skip + heading levels. +- Use `-` for bulleted lists and `1.` for numbered lists. +- Surround headings, lists, tables, and code blocks with blank lines. +- Give every fenced code block a language, for example `powershell`. +- Don't use hard tabs or trailing spaces. +- Link to other pages with relative links to the `.md` file, for example + `[Concepts](Concepts.md)` or `[Get-NTFSAccess](Cmdlets/Get-NTFSAccess.md)`. + MkDocs converts them to links to the generated pages. +- End every file with a single newline. + +## Cmdlet reference pages + +platyPS converts the pages in `Docs/Cmdlets` to help files and updates them +from the module. Keep the structure that platyPS expects: + +- Keep the front matter. `external help file`, `Module Name`, and `schema` + must stay as they are. `online version` is the address of the page on + GitHub, which `Get-Help -Online` opens. +- Keep the level 2 headings in capital letters and in this order: SYNOPSIS, + SYNTAX, DESCRIPTION, EXAMPLES, PARAMETERS, INPUTS, OUTPUTS, NOTES, + RELATED LINKS. Don't add other level 2 headings. +- Don't edit the SYNTAX blocks or the YAML block of a parameter by hand. + platyPS regenerates them from the module. The only exception is + `Default value`, which platyPS keeps. +- Write each paragraph on a single line. platyPS carries line breaks into the + text that `Get-Help` shows. +- Start each example with a level 3 heading such as + `### Example 1: Get the permissions of a folder`, followed by a code block + with the language `PowerShell` whose first line starts with `PS C:\>`. +- Under INPUTS and OUTPUTS, keep the level 3 headings with the type names and + add a sentence below each one. +- In RELATED LINKS, write each link on its own line and separate the links + with blank lines. + +## MkDocs + +- The site uses the built-in `readthedocs` theme. +- Every page must be listed in the `nav` section of `mkdocs.yml`. +- Files in `Docs` that aren't Markdown are copied to the website. Exclude + files that don't belong there with `exclude_docs` in `mkdocs.yml`. diff --git a/Docs/Examples.md b/Docs/Examples.md index 1868693..b6ea942 100644 --- a/Docs/Examples.md +++ b/Docs/Examples.md @@ -1,93 +1,222 @@ -### Get-NTFSAccess -Returns a list of all access control entries found on the given object(s). +# Examples - #Get permissions from all files or folders in the current folder - dir | Get-NTFSAccess +These examples show common tasks with the NTFSSecurity module. Replace the +sample paths and accounts with your own. For background, see +[Concepts](Concepts.md). - #to read the permissions of a specific file - Get-NTFSAccess -Path C:\Windows +Changing permissions on items you don't own, changing owners, and every +audit operation need an elevated PowerShell session. See +[Privileges](Concepts.md#privileges). -#### Get permissions from all files or folders in the current folder +## Read permissions - dir | Get-NTFSAccess +Get the access entries of a folder: -#### To read and also remove only the explicitly assigned ones +```powershell +Get-NTFSAccess -Path C:\Data +``` - dir | Get-NTFSAccess -ExcludeInherited | Remove-NTFSAccess +Get the access entries of every item in a folder: -The pipeline support can also be used to backup and restore permissions of one or many items: -PowerShell +```powershell +Get-ChildItem -Path C:\Data | Get-NTFSAccess +``` -#### To backup permissions just pipe what Get-NTFSAccess returns to Export-Csv +Get only the explicit entries in a folder tree, including items with paths +longer than 260 characters: - dir | Get-NTFSAccess -ExcludeInherited | Export-Csv permissions.csv +```powershell +Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSAccess -ExcludeInherited +``` -#### To retore the permissions pipe the imported data to Get-NTFSAccess +Get the entries of one account, either with `-Account` or with +`Where-Object`: -As the imported data also contains the path you do not need to specify the item +```powershell +Get-NTFSAccess -Path C:\Data -Account 'CONTOSO\JohnDoe' +Get-NTFSAccess -Path C:\Data | Where-Object { $_.Account -like '*JohnDoe*' } +``` - Import-Csv .\permissions.csv | Get-NTFSAccess +## Grant permissions -All cmdlets can handle SIDs and also SamAccountNames. The output contains always both unless a SID is not resolvable. -The types.ps1xml file is extending the common objects with some useful information and the format.ps1xml file formats all the output in almost the same way like the Get-ChildItem output. +Give an account the Modify permission on a folder, its subfolders, and its +files: -By implementing the [Process Privilege http://processprivileges.codeplex.com/] project the cmdlets can activate the required privileges for setting the ownership for example. +```powershell +Add-NTFSAccess -Path C:\Data -Account 'CONTOSO\JohnDoe' -AccessRights Modify +``` +Give a group read access to a folder and its subfolders, but not to the +files: -# Add-NTFSAccess -Adds a specific ace to the current object. This can be done in just one line: +```powershell +Add-NTFSAccess -Path C:\Data -Account 'CONTOSO\Domain Users' -AccessRights ReadAndExecute -AppliesTo ThisFolderAndSubfolders +``` - Get-Item .\VMWare | Add-NTFSAccess -Account Contoso\JohnD -AccessRights FullControl +Deny a group the right to delete anything in a folder: -# Get-NTFSAccess +```powershell +Add-NTFSAccess -Path C:\Data\Public -Account 'CONTOSO\Interns' -AccessRights Delete, DeleteSubdirectoriesAndFiles -AccessType Deny +``` -Gives you a list of all permissions . normally you are interested not in the inherited permissions so the switch ExcludeInherited can be useful +## Remove permissions - Get-Item F:\backup | Get-NTFSAccess –ExcludeInherited +Remove an entry by account and rights: +```powershell +Remove-NTFSAccess -Path C:\Data -Account 'CONTOSO\JohnDoe' -AccessRights Modify +``` -## Filtering works with Where-Object +Remove all explicit entries of an account by piping them to +`Remove-NTFSAccess`: - Get-Item F:\backup | Get-NTFSAccess | Where-Object { $_.ID -like "*users*" } +```powershell +Get-NTFSAccess -Path C:\Data -Account 'CONTOSO\JohnDoe' -ExcludeInherited | Remove-NTFSAccess +``` -# Get-NTFS Orphaned Access +## Back up and restore permissions -Lists all permissions that can no longer be resolved. This normally happens if the account is no longer available so the permissions show up as a SID and not as an account name. +Save the explicit entries of a folder and everything below it to a CSV file: -To remove all non-resolvable or orphaned permissions you can use the following line. But be very careful with that as maybe the account is not resolvable due to a network problem. +```powershell +$items = @(Get-Item2 -Path C:\Data) + @(Get-ChildItem2 -Path C:\Data -Recurse) +$items | Get-NTFSAccess -ExcludeInherited | Export-Csv -Path C:\Backup\permissions.csv -NoTypeInformation +``` - dir -Recurse | Get-NTFSOrphanedAccess | Remove-NTFSAccess +Restore the entries. Each row contains the path, account, rights, type, and +inheritance settings of one entry, which `Add-NTFSAccess` binds by property +name: -# Remove- NTFSAccess +```powershell +Import-Csv -Path C:\Backup\permissions.csv | Add-NTFSAccess +``` -Removes the permission for a certain account. As the pipeline is supported it takes also -ACEs coming from Get-NTFSAccess or Get-NTFSOrphanedAccess +Restoring adds the saved entries. It doesn't remove entries that were added +after the backup. +## Find and remove orphaned entries -# Get-NTFSEffectiveAccess +List entries whose account no longer exists: -Shows the permissions an account actually has on a file or folder. If no parameter is specified it shows the effective permissions for the current user. However you can supply a user by using the SID or account name -PowerShell +```powershell +Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOrphanedAccess +``` - Get-Item F:\backup | Get-NTFSEffectiveAccess -Account S-1-5-32-545 +Remove them: -# Get-NTFSInheritance -Shows if inheritance is blocked +```powershell +Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOrphanedAccess | Remove-NTFSAccess +``` -# Enable-NTFSInheritance -It can be a problem if certain files or folders on a volume have inheritance disabled. Making sure that inheritance is enabled can be done using this cmdlets: +Review the list before you remove anything. An account also looks orphaned +when Windows can't resolve it temporarily, for example because a domain +controller is unreachable. - Get-Item .\Data -Recurse | Enable-NTFSAccessInheritance +## Check effective access -# Disable-NTFSInheritance -See Enable-NTFSInheritance +Show the access that the current user has on a folder: -# Get-NTFSOwner -Shows the owner of a file or folder +```powershell +Get-NTFSEffectiveAccess -Path C:\Data +``` - dir -Recurse | Get-NTFSOwner +Show the access of another account, by name or by SID: -# Set-NTFSOwner -Sets the owner to a specific account like: +```powershell +Get-NTFSEffectiveAccess -Path C:\Data -Account 'CONTOSO\JohnDoe' +Get-NTFSEffectiveAccess -Path C:\Data -Account S-1-5-32-545 +``` - Get-Item .\Data | Set-NTFSOwner -Account builtin\administrators +## Manage inheritance + +Find the folders that don't inherit permissions from their parent: + +```powershell +Get-ChildItem2 -Path C:\Data -Recurse -Directory | Get-NTFSInheritance | Where-Object { -not $_.AccessInheritanceEnabled } +``` + +Turn inheritance back on for a whole folder tree. Explicit entries stay in +place: + +```powershell +Get-ChildItem2 -Path C:\Data -Recurse | Enable-NTFSAccessInheritance +``` + +Block inheritance on a folder. The inherited entries are copied as explicit +entries: + +```powershell +Disable-NTFSAccessInheritance -Path C:\Data\Finance +``` + +Reset a folder to inherited permissions only: + +```powershell +Enable-NTFSAccessInheritance -Path C:\Data\Finance -RemoveExplicitAccessRules +``` + +## Manage ownership + +List the owners of all items in a folder tree: + +```powershell +Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOwner +``` + +Make the local Administrators group the owner of a folder. This needs an +elevated session: + +```powershell +Set-NTFSOwner -Path C:\Data -Account 'BUILTIN\Administrators' +``` + +## Make several changes in one write + +Get the security descriptor once, change it in memory, and write it back. +With security descriptor input, specify `-AppliesTo` (or the inheritance and +propagation flags) so that PowerShell can choose the parameter set: + +```powershell +$sd = Get-NTFSSecurityDescriptor -Path C:\Data +$sd | Add-NTFSAccess -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AppliesTo ThisFolderSubfoldersAndFiles +$sd | Remove-NTFSAccess -Account 'CONTOSO\Interns' -AccessRights ReadAndExecute -AppliesTo ThisFolderSubfoldersAndFiles +$sd | Set-NTFSSecurityDescriptor +``` + +## Audit access + +Log every successful and failed attempt to delete items in a folder. This +needs an elevated session, and Windows only writes the events when the +**Audit File System** policy is enabled: + +```powershell +Add-NTFSAudit -Path C:\Data\Finance -Account 'Everyone' -AccessRights Delete, DeleteSubdirectoriesAndFiles +Get-NTFSAudit -Path C:\Data\Finance +``` + +## Work with long paths + +Find files whose full path is longer than 260 characters and show their +permissions: + +```powershell +Get-ChildItem2 -Path C:\Data -Recurse -File | Where-Object { $_.FullName.Length -gt 260 } | Get-NTFSAccess +``` + +## Use privileges + +List the privileges of the current PowerShell process: + +```powershell +Get-Privileges +``` + +In an elevated session, enable the Backup, Restore, Take Ownership, and +Security privileges for the rest of the session, and disable them again +when you're done: + +```powershell +Enable-Privileges +Get-ChildItem2 -Path D:\Shares -Recurse | Get-NTFSAccess -ExcludeInherited +Disable-Privileges +``` diff --git a/Docs/index.md b/Docs/index.md index eee4b41..b1f4531 100644 --- a/Docs/index.md +++ b/Docs/index.md @@ -1,31 +1,153 @@ # NTFSSecurity -[![Build status](https://ci.appveyor.com/api/projects/status/2gfb58t9qh655b8x?svg=true)](https://ci.appveyor.com/project/Sup3rlativ3/ntfssecurity) [![Documentation Status](https://readthedocs.org/projects/ntfssecurity/badge/?version=latest)](https://ntfssecurity.readthedocs.io/en/latest/?badge=latest) +NTFSSecurity is a PowerShell module for managing the permissions, audit +settings, inheritance, and ownership of files and folders on NTFS volumes. -Managing file & folder permissions with PowerShell is only a bit easier than in VBS or the command line as there are no cmdlets for most day-to-day tasks like getting a permission report or adding permission to an item. PowerShell only offers Get-Acl and Set-Acl but everything in between getting and setting the ACL is missing. This module closes the gap. +PowerShell offers only `Get-Acl` and `Set-Acl`; everything between reading +and writing an access control list is up to you. NTFSSecurity closes this gap +with task-level cmdlets that work with the PowerShell pipeline. -[Version History](https://github.com/raandree/NTFSSecurity/wiki/Version-History) +## Features -## Installation +- Read, add, remove, and clear access entries and audit entries. +- Show the effective access of an account and find orphaned entries. +- Inspect, enable, and disable inheritance. +- Get and set the owner of files and folders. +- Change several entries in memory and write them in one step. +- Enable the Backup, Restore, Take Ownership, and Security privileges to + work on items that you can't otherwise access. +- Work with paths longer than 260 characters. +- Create hard links and symbolic links, list the hard links of a file, and + get file hashes and disk space. + +## Requirements -You have two options: +- Windows with NTFS volumes. +- Windows PowerShell 5.1 or PowerShell 7. `Get-FileHash2` works only in + Windows PowerShell. +- An elevated session for audit operations, owner changes, and access to + items that your account can't open. See + [Privileges](Concepts.md#privileges). + +## Installation -* Download the latest release from the [releases](https://github.com/raandree/NTFSSecurity/releases) section on GitHub. -* Download the module from the [PowerShell Gallery](https://www.powershellgallery.com/packages/NTFSSecurity): +Install the module from the +[PowerShell Gallery](https://www.powershellgallery.com/packages/NTFSSecurity): -```PowerShell +```powershell Install-Module -Name NTFSSecurity ``` -Further help can be found in How to install if you face difficulties getting this module installed. +You can also download a release from the +[releases page](https://github.com/raandree/NTFSSecurity/releases) on GitHub. +If you have trouble, see +[How to install](https://github.com/raandree/NTFSSecurity/wiki/How-to-install). + +## Getting started + +```powershell +Import-Module -Name NTFSSecurity +Get-Command -Module NTFSSecurity +Get-NTFSAccess -Path C:\Windows +``` + +Read [Concepts](Concepts.md) for the background and [Examples](Examples.md) +for common tasks. Every cmdlet has a reference page with all parameters and +examples; see the [cmdlet list](#cmdlets). + +## Cmdlets + +### Permissions + +| Cmdlet | Description | +| --- | --- | +| [Get-NTFSAccess](Cmdlets/Get-NTFSAccess.md) | Gets the access control entries (ACEs) of a file, a folder, or a security descriptor. | +| [Add-NTFSAccess](Cmdlets/Add-NTFSAccess.md) | Adds an access control entry (ACE) to a file, a folder, or a security descriptor. | +| [Remove-NTFSAccess](Cmdlets/Remove-NTFSAccess.md) | Removes rights from the access control entries (ACEs) of a file, a folder, or a security descriptor. | +| [Clear-NTFSAccess](Cmdlets/Clear-NTFSAccess.md) | Removes all explicit access control entries from a file or folder. | +| [Get-NTFSEffectiveAccess](Cmdlets/Get-NTFSEffectiveAccess.md) | Gets the rights an account effectively has on a file or folder. | +| [Get-NTFSOrphanedAccess](Cmdlets/Get-NTFSOrphanedAccess.md) | Gets the access control entries whose account cannot be resolved to a name. | +| [Get-NTFSSimpleAccess](Cmdlets/Get-NTFSSimpleAccess.md) | Gets the permissions of folders reduced to read, write, and delete. | + +### Auditing + +| Cmdlet | Description | +| --- | --- | +| [Get-NTFSAudit](Cmdlets/Get-NTFSAudit.md) | Gets the audit entries of a file or folder. | +| [Add-NTFSAudit](Cmdlets/Add-NTFSAudit.md) | Adds an audit entry to a file or folder. | +| [Remove-NTFSAudit](Cmdlets/Remove-NTFSAudit.md) | Removes an audit entry from a file or folder. | +| [Clear-NTFSAudit](Cmdlets/Clear-NTFSAudit.md) | Removes all explicit audit entries from a file or folder. | +| [Get-NTFSOrphanedAudit](Cmdlets/Get-NTFSOrphanedAudit.md) | Gets the audit entries whose account cannot be resolved. | + +### Inheritance -## Documentation +| Cmdlet | Description | +| --- | --- | +| [Get-NTFSInheritance](Cmdlets/Get-NTFSInheritance.md) | Gets the inheritance state of the access rules and the audit rules of a file or folder. | +| [Set-NTFSInheritance](Cmdlets/Set-NTFSInheritance.md) | Sets the inheritance of the access rules and the audit rules of a file or folder. | +| [Enable-NTFSAccessInheritance](Cmdlets/Enable-NTFSAccessInheritance.md) | Restores the inheritance of access rules on a file or folder. | +| [Disable-NTFSAccessInheritance](Cmdlets/Disable-NTFSAccessInheritance.md) | Blocks the inheritance of access rules on a file or folder. | +| [Enable-NTFSAuditInheritance](Cmdlets/Enable-NTFSAuditInheritance.md) | Restores the inheritance of audit rules on a file or folder. | +| [Disable-NTFSAuditInheritance](Cmdlets/Disable-NTFSAuditInheritance.md) | Blocks the inheritance of audit rules on a file or folder. | -The cmdlets are yet not documented completely so Get-Help will not show help for all the cmdlets. This ReadTheDocs site is the first step to documenting the module. +### Owner and security descriptor + +| Cmdlet | Description | +| --- | --- | +| [Get-NTFSOwner](Cmdlets/Get-NTFSOwner.md) | Gets the owner of a file or folder. | +| [Set-NTFSOwner](Cmdlets/Set-NTFSOwner.md) | Sets the owner of a file or folder. | +| [Get-NTFSSecurityDescriptor](Cmdlets/Get-NTFSSecurityDescriptor.md) | Gets the security descriptor of a file or folder. | +| [Set-NTFSSecurityDescriptor](Cmdlets/Set-NTFSSecurityDescriptor.md) | Writes a security descriptor to the file or folder it was read from. | + +### Privileges + +| Cmdlet | Description | +| --- | --- | +| [Get-Privileges](Cmdlets/Get-Privileges.md) | Gets the privileges in the access token of the current PowerShell process. | +| [Enable-Privileges](Cmdlets/Enable-Privileges.md) | Enables the file system privileges in the access token of the current PowerShell process. | +| [Disable-Privileges](Cmdlets/Disable-Privileges.md) | Disables the file system privileges in the access token of the current PowerShell process. | + +### Files and folders with long paths + +| Cmdlet | Description | +| --- | --- | +| [Get-ChildItem2](Cmdlets/Get-ChildItem2.md) | Gets the files and folders in one or more folders, including paths longer than 260 characters. | +| [Get-Item2](Cmdlets/Get-Item2.md) | Gets the file or folder at a specified path, including paths longer than 260 characters. | +| [Copy-Item2](Cmdlets/Copy-Item2.md) | Copies a file to another location, including paths longer than 260 characters. | +| [Move-Item2](Cmdlets/Move-Item2.md) | Moves a file or folder to another location, including paths longer than 260 characters. | +| [Remove-Item2](Cmdlets/Remove-Item2.md) | Deletes a file or folder, including paths longer than 260 characters. | +| [Test-Path2](Cmdlets/Test-Path2.md) | Determines whether a file or folder exists at the specified path. | + +### Links, hashes, and disk space + +| Cmdlet | Description | +| --- | --- | +| [Get-NTFSHardLink](Cmdlets/Get-NTFSHardLink.md) | Gets all hard links that refer to the same file as the specified path. | +| [New-NTFSHardLink](Cmdlets/New-NTFSHardLink.md) | Creates a hard link to an existing file. | +| [New-NTFSSymbolicLink](Cmdlets/New-NTFSSymbolicLink.md) | Creates a symbolic link to an existing file or folder. | +| [Get-FileHash2](Cmdlets/Get-FileHash2.md) | Gets the hash value of one or more files. | +| [Get-DiskSpace](Cmdlets/Get-DiskSpace.md) | Gets size, free space, and cluster information for the volumes of a computer. | ## Tutorials -There are a number of tutorials available on the web. The below two were written by the author of the NTFSSecurity module. +The author of the module wrote two tutorials in 2014. Some cmdlet names in +them have changed since; use the cmdlet reference for the current names. + +- [NTFSSecurity Tutorial 1 - Getting, adding and removing permissions](https://learn.microsoft.com/en-us/archive/blogs/fieldcoding/ntfssecurity-tutorial-1-getting-adding-and-removing-permissions) +- [NTFSSecurity Tutorial 2 - Managing NTFS Inheritance and Using Privileges](https://learn.microsoft.com/en-us/archive/blogs/fieldcoding/ntfssecurity-tutorial-2-managing-ntfs-inheritance-and-using-privileges) + +## Version history + +See the [changelog](https://github.com/raandree/NTFSSecurity/blob/master/CHANGELOG.md) +and the +[version history](https://github.com/raandree/NTFSSecurity/wiki/Version-History) +in the wiki. + +## Contributing + +Contributions are welcome. See the [contributor guide](Contributing.md). + +## License -[NTFSSecurity Tutorial 1 - Getting, adding and removing permissions](http://blogs.technet.com/b/fieldcoding/archive/2014/12/05/ntfssecurity-tutorial-1-getting-adding-and-removing-permissions.aspx) -[NTFSSecurity Tutorial 2 - Managing NTFS Inheritance and Using Privileges](http://blogs.technet.com/b/fieldcoding/archive/2014/12/05/ntfssecurity-tutorial-2-managing-ntfs-inheritance-and-using-privileges.aspx) +NTFSSecurity is licensed under the +[MIT license](https://github.com/raandree/NTFSSecurity/blob/master/LICENSE). diff --git a/Docs/requirements.txt b/Docs/requirements.txt new file mode 100644 index 0000000..f2caded --- /dev/null +++ b/Docs/requirements.txt @@ -0,0 +1 @@ +mkdocs==1.6.1 diff --git a/README.md b/README.md index e2269cc..b2c0960 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,67 @@ -### Summary -Managing permissions with PowerShell is only a bit easier than in VBS or the command line as there are no cmdlets for most day-to-day tasks like getting a permission report or adding permission to an item. PowerShell only offers Get-Acl and Set-Acl but everything in between getting and setting the ACL is missing. This module closes the gap. +# NTFSSecurity -### [Version History](https://github.com/raandree/NTFSSecurity/wiki/Version-History) +A PowerShell module for managing the permissions, audit settings, +inheritance, and ownership of files and folders on NTFS volumes. -### Installation -You have two options: -1. Download the latest release from [the releases section](https://github.com/raandree/NTFSSecurity/releases). -2. Download the module from the [PowerShell Gallery](https://www.powershellgallery.com/packages/NTFSSecurity): Install-Module -Name NTFSSecurity +PowerShell offers only `Get-Acl` and `Set-Acl`; everything between reading +and writing an access control list is up to you. NTFSSecurity closes this gap +with cmdlets for everyday tasks, such as permission reports, adding or +removing a single permission, repairing inheritance, and taking ownership. -Further help can be found in [How to install](https://github.com/raandree/NTFSSecurity/wiki/How-to-install) if you face difficulties getting this module installed. +## Installation -### Documentation -The cmdlets are documented in Docs/. -They are not documented completely so Get-Help will not show help for all the cmdlets. Providing documentation is planned though. +Install the module from the +[PowerShell Gallery](https://www.powershellgallery.com/packages/NTFSSecurity): -See [Examples](Docs/Examples.md) for some usage examples. +```powershell +Install-Module -Name NTFSSecurity +``` -Additional documentation is available: -* [NTFSSecurity Tutorial 1 - Getting, adding and removing permissions](https://docs.microsoft.com/en-us/archive/blogs/fieldcoding/ntfssecurity-tutorial-1-getting-adding-and-removing-permissions) -* [NTFSSecurity Tutorial 2 - Managing NTFS Inheritance and Using Privileges](https://docs.microsoft.com/en-us/archive/blogs/fieldcoding/ntfssecurity-tutorial-2-managing-ntfs-inheritance-and-using-privileges) +You can also download a release from the +[releases page](https://github.com/raandree/NTFSSecurity/releases). If you +have trouble, see +[How to install](https://github.com/raandree/NTFSSecurity/wiki/How-to-install). + +The module runs on Windows in Windows PowerShell 5.1 and PowerShell 7. + +## Quick start + +```powershell +# Show the permissions of a folder +Get-NTFSAccess -Path C:\Data + +# Give an account the Modify permission on a folder, its subfolders, and files +Add-NTFSAccess -Path C:\Data -Account 'CONTOSO\JohnDoe' -AccessRights Modify + +# Remove the explicit permissions of that account again +Get-NTFSAccess -Path C:\Data -Account 'CONTOSO\JohnDoe' -ExcludeInherited | + Remove-NTFSAccess + +# List the explicit permissions in a folder tree, including long paths +Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSAccess -ExcludeInherited +``` + +## Documentation + +- [Overview](Docs/index.md): features, requirements, and the list of cmdlets +- [Concepts](Docs/Concepts.md): security descriptors, access rights, + inheritance, privileges, long paths, and module settings +- [Examples](Docs/Examples.md): common tasks +- [Cmdlet reference](Docs/Cmdlets): one page per cmdlet +- [Contributor guide](Docs/Contributing.md) + +The module author's tutorials from 2014 are still a good introduction, +although some cmdlet names have changed since: + +- [NTFSSecurity Tutorial 1 - Getting, adding and removing permissions](https://learn.microsoft.com/en-us/archive/blogs/fieldcoding/ntfssecurity-tutorial-1-getting-adding-and-removing-permissions) +- [NTFSSecurity Tutorial 2 - Managing NTFS Inheritance and Using Privileges](https://learn.microsoft.com/en-us/archive/blogs/fieldcoding/ntfssecurity-tutorial-2-managing-ntfs-inheritance-and-using-privileges) + +## Version history + +See [CHANGELOG.md](CHANGELOG.md) for changes since version 4.2.6 and the +[version history](https://github.com/raandree/NTFSSecurity/wiki/Version-History) +in the wiki for earlier releases. + +## License + +NTFSSecurity is licensed under the [MIT license](LICENSE). diff --git a/appveyor.yml b/appveyor.yml index a0573d6..effe479 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -1,31 +1,48 @@ -install: - - ps: | - Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force - Install-Module platyPS -Force - Install-Module MarkdownLinkCheck -Force - Install-Module NTFSSecurity -Force - Import-Module platyPS - Import-Module MarkdownLinkCheck +# Builds the NTFSSecurity module from source and checks that the cmdlet +# documentation in Docs/Cmdlets matches the cmdlets of that build. +image: Visual Studio 2022 init: - - ps: git config --global core.autocrlf true + - ps: git config --global core.autocrlf true + +install: + - ps: | + [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12 + Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force | Out-Null + Install-Module -Name platyPS -RequiredVersion 0.14.2 -Force + Install-Module -Name MarkdownLinkCheck -RequiredVersion 0.2.0 -Force + +before_build: + - nuget restore NTFSSecurity\packages.config -PackagesDirectory packages -NonInteractive + - nuget restore Security2\packages.config -PackagesDirectory packages -NonInteractive + # Provides the .NET Framework 4.5.2 reference assemblies, so the build does + # not depend on a targeting pack installed on the build image. + - nuget install Microsoft.NETFramework.ReferenceAssemblies.net452 -Version 1.0.3 -OutputDirectory packages -NonInteractive build_script: - - ps: Import-Module -Force NTFSSecurity + - ps: | + $referenceAssemblies = "$env:APPVEYOR_BUILD_FOLDER\packages\Microsoft.NETFramework.ReferenceAssemblies.net452.1.0.3\build" + msbuild NTFSSecurity\NTFSSecurity.csproj /nologo /verbosity:minimal /p:Configuration=Release "/p:TargetFrameworkRootPath=$referenceAssemblies" "/p:FrameworkPathOverride=$referenceAssemblies\.NETFramework\v4.5.2" + if ($LASTEXITCODE -ne 0) { + throw "MSBuild failed with exit code $LASTEXITCODE." + } test_script: - - ps: | - $ErrorActionPreference = 'Stop' - - # 01. Test that documentation is up-to-date - Update-MarkdownHelp -Path ./Docs/Cmdlets - $Diff = git diff - if ($Diff) { - throw "Help is not up-to-date, run Update-MarkdownHelp: $diff" - } + - ps: | + $ErrorActionPreference = 'Stop' + Import-Module -Name platyPS + Import-Module -Name MarkdownLinkCheck + Import-Module -Name .\NTFSSecurity\bin\Release\NTFSSecurity.psd1 -Force + + # 01. Test that the documentation matches the cmdlets built from source + Update-MarkdownHelp -Path ./Docs/Cmdlets | Out-Null + $diff = git diff -- Docs/Cmdlets + if ($diff) { + throw "Help is not up-to-date, run Update-MarkdownHelp: $diff" + } - # 02. Verify hyperlinks - $BrokenLinks = Get-MarkdownLink -Path .\Docs\ -BrokenOnly - if ($brokenLinks) { - throw "Found broken hyperlinks $brokenLinks" - } \ No newline at end of file + # 02. Verify hyperlinks + $brokenLinks = Get-MarkdownLink -Path .\Docs\ -BrokenOnly + if ($brokenLinks) { + throw "Found broken hyperlinks $brokenLinks" + } diff --git a/mkdocs.yml b/mkdocs.yml index a25b256..c4f3155 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,8 +1,10 @@ -copyright: The NTFSSecurity module is licensed under the MIT license +copyright: "The NTFSSecurity module is licensed under the MIT license." repo_url: https://github.com/raandree/NTFSSecurity +edit_uri: edit/master/Docs/ nav: - Home: ./index.md - Concepts: ./Concepts.md +- Examples: ./Examples.md - Cmdlets: - Add-NTFSAccess: Cmdlets/Add-NTFSAccess.md - Add-NTFSAudit: Cmdlets/Add-NTFSAudit.md @@ -41,11 +43,15 @@ nav: - Set-NTFSSecurityDescriptor: Cmdlets/Set-NTFSSecurityDescriptor.md - Test-Path2: Cmdlets/Test-Path2.md - Contributing: + - Overview: Contributing.md - Getting Started: Contributing/01-Getting-Started.md - Writing: Contributing/02-Writing.md - Style Guide: Contributing/03-Style-Guide.md - - Markdown Specifics: Contributing:04-Markdown-Specifics.md + - Markdown Specifics: Contributing/04-Markdown-Specifics.md site_name: NTFSSecurity +site_description: PowerShell module for managing NTFS permissions, auditing, inheritance, and ownership theme: readthedocs site_author: Raimund Andrée, James Smith -docs_dir: ./Docs \ No newline at end of file +docs_dir: ./Docs +exclude_docs: | + /requirements.txt