Skip to content

Commit 0d0d941

Browse files
committed
docs: CONTRIBUTING and SECURITY
How to report a rule that disagrees with a device, the checks to run, and what the module touches: the harness's scheduled tasks and run cache, the read-only Graph pre-flight, the diagnostic zip's contents, and the validation kit.
1 parent e95e7a1 commit 0d0d941

2 files changed

Lines changed: 118 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Contributing
2+
3+
Thank you for looking. Issues and pull requests are welcome.
4+
5+
## Before you start
6+
7+
- **A rule fires on something Intune tolerates, or misses something it does not:** that is the
8+
most useful issue this project can get. Open one with the script (or a cut-down version that
9+
still shows it), the script type, and what Intune actually did on a device. Every rule cites its
10+
`Evidence`, ending in experiment ids such as `REM-EXIT-2`; those are the entries in
11+
`Validation/Experiments.psd1` whose results `Validation/Findings.md` records, so say which
12+
finding you think is wrong.
13+
- **A harness result that differs from the portal:** include `-Verbose` output and the result
14+
object. `Output` and `ExitCode` on it are the values Intune reports; the portal only formats them.
15+
- **A change:** open an issue first if it is more than a fix, so the shape can be agreed before
16+
the work. `CLAUDE.md` lists the invariants that look arbitrary until you know the reason.
17+
18+
## The conventions
19+
20+
General PowerShell conventions - module layout, comment-based help, Pester, error handling - are
21+
mirrored into `.github/` from
22+
[ai-powershell-standards](https://github.com/fadwen/ai-powershell-standards). Those paths are
23+
overwritten on every sync, so a change to a convention belongs upstream.
24+
25+
Everything specific to this module is in `CLAUDE.md`. The ones most often tripped over:
26+
27+
- A rule is backed by what a device did, not by what a document says. A new rule needs an
28+
experiment in `Validation/Experiments.psd1`, a run recorded in `Validation/Findings.md`, and the
29+
experiment ids in its `Evidence`.
30+
- Only exported functions carry `.EXTERNALHELP`; their help lives in `docs/` and is compiled to
31+
`en-US/IntuneScriptLab-Help.xml` by `Build/Build-Help.ps1`. Rebuild it in the same change as a
32+
docs edit; the help gate compares byte for byte.
33+
- `docs/Rules.md` is generated by `Build/Build-RuleReference.ps1` and a unit test keeps it
34+
current. Rebuild it after changing a rule's message, severity or evidence.
35+
- A new command goes in the manifest, the `Export-ModuleMember` list in the root module, the
36+
contract test, and `docs/`.
37+
- Windows PowerShell 5.1 and PowerShell 7 both have to work, so nothing 7-only anywhere the
38+
module loads. The suites run on 5.1 and on Windows on ARM in CI.
39+
40+
## The checks
41+
42+
```powershell
43+
Invoke-Pester ./Tests, ./Validation/Tests # a few minutes; suites needing elevation,
44+
# a lab account or Graph skip themselves
45+
Invoke-ScriptAnalyzer -Path . -Recurse -Severity Error, Warning -ExcludeRule PSAvoidLongLines
46+
./Build/Build-Help.ps1 # after editing docs/
47+
./Build/Build-RuleReference.ps1 # after changing a rule
48+
./Build/Publish-Module.ps1 -WhatIf # the full release rehearsal
49+
```
50+
51+
Run the unit suites under Windows PowerShell 5.1 as well:
52+
53+
```powershell
54+
powershell -NoProfile -Command "Invoke-Pester ./Tests/Unit, ./Validation/Tests/Unit"
55+
```
56+
57+
The suites reach no tenant: every Graph call goes through a mocked seam. A change to what a rule
58+
or the harness claims about Intune should also be run against a device you own, and the pull
59+
request should say what you ran and what it did. The validation kit under `Validation/` is how
60+
the existing evidence was produced; it needs a tenant and lab devices of your own and its README
61+
explains the rounds.
62+
63+
## Pull requests
64+
65+
- One rule, one command or one concern per pull request.
66+
- Add or update the tests that pin the behaviour, and a line in `CHANGELOG.md` under
67+
`[Unreleased]`.
68+
- The quality gates run on every pull request on PowerShell 7, Windows PowerShell 5.1, Windows on
69+
ARM, and a case-sensitive filesystem for the help.

‎SECURITY.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Security
2+
3+
## Reporting a vulnerability
4+
5+
Please report a vulnerability privately through
6+
[GitHub's private vulnerability reporting](https://github.com/fadwen/IntuneScriptLab/security/advisories/new)
7+
rather than in a public issue. You will get an acknowledgement within a few days and a fix or a
8+
mitigation as soon as one is ready; the report is credited in the release notes unless you ask
9+
otherwise.
10+
11+
## What this module touches
12+
13+
The static analysis (`Test-IntuneScript`, the PSScriptAnalyzer rules) only reads the scripts you
14+
point it at. `Repair-IntuneScript` rewrites them, previews with `-WhatIf`, and never applies a fix
15+
that changes behaviour.
16+
17+
The runtime harness (`Invoke-Intune*Test`) runs the script you give it on this machine, the way
18+
the Intune Management Extension would: it copies the script to a cache folder, launches a
19+
Windows PowerShell host, and kills it at the timeout. With `-Context System` or `-Credential` it
20+
registers a scheduled task to launch under that account and unregisters it when the run ends.
21+
The script itself runs with whatever rights that account has, exactly as it would under Intune;
22+
run scripts you trust.
23+
24+
The Graph pre-flight (`Test-IntuneDeployedScript`, `Compare-IntuneDeployedScript`,
25+
`Get-IntuneScriptHealth`) reads the tenant through the caller's own Microsoft.Graph session. Its
26+
only write is submitting a report export job, which changes nothing in the tenant. If you find a
27+
path by which any command modifies a policy, an app, an assignment or a device, that is a
28+
vulnerability: report it as one.
29+
30+
`Export-IntuneAgentDiagnostic` packs the agent's logs, the enrollment and agent registry keys,
31+
`dsregcmd /status` and the parsed timelines into a zip. That content names the device, the
32+
tenant, the user and every deployed policy. Treat the zip as sensitive and review it before
33+
sharing it.
34+
35+
The validation kit under `Validation/` deploys and removes `ISL-*` objects in a tenant you own and
36+
runs probes on lab devices. Nothing it produces is shipped in the package, and its raw results
37+
are git-ignored because they contain tenant identifiers.
38+
39+
## Credentials
40+
41+
Nothing is stored. A `-Credential` is used once to register the scheduled task and, when the
42+
account has no session, the scheduler holds the password for the life of that task, which is
43+
deleted at the end of the run. The run cache under `ProgramData\IntuneScriptLab\Runs` is granted
44+
to that account for the run and removed afterwards. Graph access is the session you already
45+
opened; the module never prompts for, caches or writes a token.
46+
47+
## Supported versions
48+
49+
Only the latest release on the PowerShell Gallery receives fixes.

0 commit comments

Comments
 (0)