Merge pull request #2 from PowerShell/master

Syncing with Master

Author: HemantMahawar

README.md

@@ -1,12 +1,12 @@
 # PowerShell Documentation
 
-Welcome to the PowerShell-Docs repository, housing the official PowerShell documentation [available on MSDN](https://msdn.microsoft.com/powershell/dsc/overview). 
+Welcome to the PowerShell-Docs repository, housing the official Windows PowerShell documentation [available on MSDN](https://msdn.microsoft.com/powershell/dsc/overview). 
 
-> **Note**: right now, this repo is only intended for PowerShell Desired State Configuration (DSC) content and Windows Management Framework (WMF) Release Notes. 
-In the future, it will be expanded to include a greater set of PowerShell documentation. 
+> **Note**: Currently, this repository is intended only for PowerShell [Desired State Configuration (DSC)](https://msdn.microsoft.com/en-us/powershell/dsc/overview) content and Windows Management Framework (WMF) release notes. 
+In the future, the repo will be expanded to include a wider range of PowerShell documentation. 
 
 ## Contributing
 
-We will be actively merging contributions into this repository via pull request. 
-Please note that before contributing, you must [sign a Contribution License Agreement](https://cla.microsoft.com/) to ensure that the community is free to use your contributions.
+We actively merge contributions into this repository via [pull request](https://help.github.com/articles/using-pull-requests/). 
+Please note that before you submit a pull request you must [sign a Contribution License Agreement](https://cla.microsoft.com/) to ensure that the community is free to use your submissions.
 For more information on contributing, read our [contributions guide](CONTRIBUTING.md).

wmf/TOC.md

@@ -76,7 +76,7 @@
 ## [PowerShell Module Discovery, Install and Inventory with PowerShellGet](psget_module_overview.md)
 ### [Register a PowerShell Repository](psget_psrepository.md)
 ### [Side-by-Side Version Support on PowerShell 5.0 or newer](psget_modulesxsinstall.md)
-### [Installtion of Module Dependencies](psget_moduledependency.md)
+### [Installation of Module Dependencies](psget_moduledependency.md)
 ### [PowerShellGet Cmdlets for Module Management](psget_modulecmdlets.md)
 
 ## [PowerShell Script Discovery, Install and Management with PowerShellGet](psget_script_overview.md)

wmf/audit_cms.md

@@ -1,113 +1,76 @@
-### Cryptographic Message Syntax (CMS) cmdlets
+# Cryptographic Message Syntax (CMS) cmdlets
 
 The Cryptographic Message Syntax cmdlets support encryption and decryption of content using the IETF standard format for cryptographically protecting messages as documented by [RFC5652](http://tools.ietf.org/html/rfc5652).
-
+```powershell
   Get-CmsMessage \[-Content\] <string>
-
   Get-CmsMessage \[-Path\] <string>
-
   Get-CmsMessage \[-LiteralPath\] <string>
-
   Protect-CmsMessage \[-To\] <CmsMessageRecipient\[\]> \[-Content\] <string> \[\[-OutFile\] <string>\]
-
   Protect-CmsMessage \[-To\] <CmsMessageRecipient\[\]> \[-Path\] <string> \[\[-OutFile\] <string>\]
-
   Protect-CmsMessage \[-To\] <CmsMessageRecipient\[\]> \[-LiteralPath\] <string> \[\[-OutFile\] <string>\]
-
   Unprotect-CmsMessage \[-EventLogRecord\] <EventLogRecord> \[\[-To\] <CmsMessageRecipient\[\]>\] \[-IncludeContext\]
-
   Unprotect-CmsMessage \[-Content\] <string> \[\[-To\] <CmsMessageRecipient\[\]>\] \[-IncludeContext\]
-
   Unprotect-CmsMessage \[-Path\] <string> \[\[-To\] <CmsMessageRecipient\[\]>\] \[-IncludeContext\]
-
   Unprotect-CmsMessage \[-LiteralPath\] <string> \[\[-To\] <CmsMessageRecipient\[\]>\] \[-IncludeContext\]
-
+```
 The CMS encryption standard implements public key cryptography, where the keys used to encrypt content (the *public key*) and the keys used to decrypt content (the *private key*) are separate.
 
 Your public key can be shared widely, and is not sensitive data. If any content is encrypted with this public key, only your private key can decrypt it. For more information about Public Key Cryptography, see: <http://en.wikipedia.org/wiki/Public-key_cryptography>.
 
 To be recognized in Windows PowerShell, encryption certificates require a unique key usage identifier (EKU) to identify them as data encryption certificates (like the identifiers for 'Code Signing', 'Encrypted Mail').
 
 Here is an example of creating a certificate that is good for Document Encryption:
-
+```powershell
 (Change the text in **Subject** to your name, email, or other identifier), and put in a file (i.e.: DocumentEncryption.inf):
-
   \[Version\]
-
   Signature = "$Windows NT$"
-
   \[Strings\]
-
   szOID\_ENHANCED\_KEY\_USAGE = "2.5.29.37"
-
   szOID\_DOCUMENT\_ENCRYPTION = "1.3.6.1.4.1.311.80.1"
-
   \[NewRequest\]
-
   Subject = "<[email protected]>"
-
   MachineKeySet = false
-
   KeyLength = 2048
-
   KeySpec = AT\_KEYEXCHANGE
-
   HashAlgorithm = Sha1
-
   Exportable = true
-
   RequestType = Cert
-
   KeyUsage = "CERT\_KEY\_ENCIPHERMENT\_KEY\_USAGE | CERT\_DATA\_ENCIPHERMENT\_KEY\_USAGE"
-
   ValidityPeriod = "Years"
-
   ValidityPeriodUnits = "1000"
-
   \[Extensions\]
-
   %szOID\_ENHANCED\_KEY\_USAGE% = "{text}%szOID\_DOCUMENT\_ENCRYPTION%"
-
+```
 Then run:
-
+```powershell
   certreq -new DocumentEncryption.inf DocumentEncryption.cer
-
+```
 And you can now encrypt and decrypt content:
-
-> 106 \[C:\\temp\]
-> &gt;&gt; $protected = "Hello World" | Protect-CmsMessage -To "\*[email protected]\*[](mailto:*[email protected]*)"
->
-> 107 \[C:\\temp\]
-> &gt;&gt; $protected
-> -----BEGIN CMS-----
-> MIIBqAYJKoZIhvcNAQcDoIIBmTCCAZUCAQAxggFQMIIBTAIBADA0MCAxHjAcBgNVBAMMFWxlZWhv
-> bG1AbWljcm9zb2Z0LmNvbQIQQYHsbcXnjIJCtH+OhGmc1DANBgkqhkiG9w0BAQcwAASCAQAnkFHM
-> proJnFy4geFGfyNmxH3yeoPvwEYzdnsoVqqDPAd8D3wao77z7OhJEXwz9GeFLnxD6djKV/tF4PxR
-> E27aduKSLbnxfpf/sepZ4fUkuGibnwWFrxGE3B1G26MCenHWjYQiqv+Nq32Gc97qEAERrhLv6S4R
-> G+2dJEnesW8A+z9QPo+DwYU5FzD0Td0ExrkswVckpLNR6j17Yaags3ltNVmbdEXekhi6Psf2MLMP
-> TSO79lv2L0KeXFGuPOrdzPAwCkV0vNEqTEBeDnZGrjv/5766bM3GW34FXApod9u+VSFpBnqVOCBA
-> DVDraA6k+xwBt66cV84OHLkh0kT02SIHMDwGCSqGSIb3DQEHATAdBglghkgBZQMEASoEEJbJaiRl
-> KMnBoD1dkb/FzSWAEBaL8xkFwCu0e1ZtDj7nSJc=
-> -----END CMS-----
->
-> 108 \[C:\\temp\]
-> &gt;&gt; $protected | Unprotect-CmsMessage
-> Hello World
-
+```powershell
+$protected = "Hello World" | Protect-CmsMessage -To "\*[email protected]\*[](mailto:*[email protected]*)"
+$protected
+ -----BEGIN CMS-----
+ MIIBqAYJKoZIhvcNAQcDoIIBmTCCAZUCAQAxggFQMIIBTAIBADA0MCAxHjAcBgNVBAMMFWxlZWhv
+ bG1AbWljcm9zb2Z0LmNvbQIQQYHsbcXnjIJCtH+OhGmc1DANBgkqhkiG9w0BAQcwAASCAQAnkFHM
+ proJnFy4geFGfyNmxH3yeoPvwEYzdnsoVqqDPAd8D3wao77z7OhJEXwz9GeFLnxD6djKV/tF4PxR
+ E27aduKSLbnxfpf/sepZ4fUkuGibnwWFrxGE3B1G26MCenHWjYQiqv+Nq32Gc97qEAERrhLv6S4R
+ G+2dJEnesW8A+z9QPo+DwYU5FzD0Td0ExrkswVckpLNR6j17Yaags3ltNVmbdEXekhi6Psf2MLMP
+ TSO79lv2L0KeXFGuPOrdzPAwCkV0vNEqTEBeDnZGrjv/5766bM3GW34FXApod9u+VSFpBnqVOCBA
+ DVDraA6k+xwBt66cV84OHLkh0kT02SIHMDwGCSqGSIb3DQEHATAdBglghkgBZQMEASoEEJbJaiRl
+ KMnBoD1dkb/FzSWAEBaL8xkFwCu0e1ZtDj7nSJc=
+ -----END CMS-----
+
+$protected | Unprotect-CmsMessage
+ Hello World
+```
 Any parameter of type **CMSMessageRecipient** supports identifiers in the following formats:
-
--   An actual certificate (as retrieved from the certificate provider)
-
--   Path to the a file containing the certificate
-
--   Path to a directory containing the certificate
-
--   Thumbprint of the certificate (used to look in the certificate store)
-
--   Subject name of the certificate (used to look in the certificate store)
-
-To view document encryption certificates in the certificate provider, you can use the -**DocumentEncryptionCert** dynamic parameter:
-
-58 \[Cert:\\currentuser\\my\]
-
-&gt;&gt; dir -DocumentEncryptionCert
+- An actual certificate (as retrieved from the certificate provider)
+- Path to the a file containing the certificate
+- Path to a directory containing the certificate
+- Thumbprint of the certificate (used to look in the certificate store)
+- Subject name of the certificate (used to look in the certificate store)
+
+To view document encryption certificates in the certificate provider, you can use the **-DocumentEncryptionCert** dynamic parameter:
+```powershell
+dir -DocumentEncryptionCert
+```

wmf/audit_overview.md

@@ -1,2 +1,5 @@
-## Audit PowerShell Usage using Transcript and Logging
+# Audit PowerShell Usage using Transcript and Logging
 
+[Enhanced Transcription Options](audit_transcript.md)
+[Script Tracing and Loggging](audit_script.md)
+[Cryptographic Message Syntax (CMS) cmdlets](audit_cms.md)

wmf/audit_script.md

@@ -1,4 +1,4 @@
-### Script Tracing and Loggging
+# Script Tracing and Loggging
 
 While Windows PowerShell already has the **LogPipelineExecutionDetails** Group Policy setting to log the invocation of cmdlets, Windows PowerShell’s scripting language has plenty of features that you might want to log and/or audit. The new Detailed Script Tracing feature lets you enable detailed tracking and analysis of Windows PowerShell scripting use on a system. After you enable detailed script tracing, Windows PowerShell logs all script blocks to the ETW event log, **Microsoft-Windows-PowerShell/Operational**. If a script block creates another script block (for example, a script that calls the Invoke-Expression cmdlet on a string), that resulting script block is logged as well.
 
@@ -42,94 +42,58 @@ Percent signs in the invocation message represent structured ETW properties. Whi
 
 Here's an example of how this functionality can help unwrap a malicious attempt to encrypt and obfuscate a script:
 
-> \#\# Malware
->
-> function SuperDecrypt
->
-> {
->
->     param($script)
->
->     $bytes = \[Convert\]::FromBase64String($script)
->
->                
->
->     \#\# XOR “encryption”
->
->     $xorKey = 0x42
->
->     for($counter = 0; $counter -lt $bytes.Length; $counter++)
->
->     {
->
->         $bytes\[$counter\] = $bytes\[$counter\] -bxor $xorKey
->
->     }
->
->     \[System.Text.Encoding\]::Unicode.GetString($bytes)
->
-> }
->
-> $decrypted = SuperDecrypt "FUIwQitCNkInQm9CCkItQjFCNkJiQmVCEkI1QixCJkJlQg=="
->
-> Invoke-Expression $decrypted 
+```powershell
+ \#\# Malware
+ function SuperDecrypt
+ {
+     param($script)
+     $bytes = \[Convert\]::FromBase64String($script)
+              
+     \#\# XOR “encryption”
+     $xorKey = 0x42
+     for($counter = 0; $counter -lt $bytes.Length; $counter++)
+     {
+         $bytes\[$counter\] = $bytes\[$counter\] -bxor $xorKey
+     }
+     \[System.Text.Encoding\]::Unicode.GetString($bytes)
+ }
+
+ $decrypted = SuperDecrypt "FUIwQitCNkInQm9CCkItQjFCNkJiQmVCEkI1QixCJkJlQg=="
+ Invoke-Expression $decrypted 
+```
 
 Running this generates the following log entries:
-
+```powershell
 Compiling Scriptblock text (1 of 1):
-
 function SuperDecrypt
-
 {
-
 param($script)
-
 $bytes = \[Convert\]::FromBase64String($script)
-
 \#\# XOR "encryption"
-
 $xorKey = 0x42
-
 for($counter = 0; $counter -lt $bytes.Length; $counter++)
-
 {
-
 $bytes\[$counter\] = $bytes\[$counter\] -bxor $xorKey
-
 }
-
 \[System.Text.Encoding\]::Unicode.GetString($bytes)
-
 }
-
 ScriptBlock ID: ad8ae740-1f33-42aa-8dfc-1314411877e3
-
 Compiling Scriptblock text (1 of 1):
-
 $decrypted = SuperDecrypt "FUIwQitCNkInQm9CCkItQjFCNkJiQmVCEkI1QixCJkJlQg=="
-
 ScriptBlock ID: ba11c155-d34c-4004-88e3-6502ecb50f52
-
 Compiling Scriptblock text (1 of 1):
-
 Invoke-Expression $decrypted
-
 ScriptBlock ID: 856c01ca-85d7-4989-b47f-e6a09ee4eeb3
-
 Compiling Scriptblock text (1 of 1):
-
 Write-Host 'Pwnd'
-
 ScriptBlock ID: 5e618414-4e77-48e3-8f65-9a863f54b4c8
+```
 
 If the script block length exceeds what ETW is capable of holding in a single event, Windows PowerShell breaks the script into multiple parts. Here is sample code to recombine a script from its log messages:
-
+```powershell
     $created = Get-WinEvent -FilterHashtable @{ ProviderName="Microsoft-Windows-PowerShell"; Id = 4104 } |
-
         Where-Object { $\_.<...> }
-
     $sortedScripts = $created | sort { $\_.Properties\[0\].Value }
-
     $mergedScript = -join ($sortedScripts | % { $\_.Properties\[2\].Value })
-
+```
 As with all logging systems that have a limited retention buffer (i.e., ETW logs), one attack against this infrastructure is to flood the log with spurious events to hide earlier evidence. To protect yourself from this attack, ensure that you have some form of event log collection set up (i.e., Windows Event Forwarding, <http://www.nsa.gov/ia/_files/app/Spotting_the_Adversary_with_Windows_Event_Log_Monitoring.pdf>) to move event logs off of the computer as soon as possible.

wmf/audit_transcript.md

@@ -1,4 +1,4 @@
-### Enhanced Transcription Options
+# Enhanced Transcription Options
 
 Windows PowerShell transcription has been improved to apply to all hosting applications (such as Windows PowerShell ISE) rather than just the console host (powershell.exe).
 

wmf/class_base.md

@@ -1,4 +1,4 @@
-### Declare Base Class
+# Declare Base Class
 You can declare a Windows PowerShell class as a base type for another Windows PowerShell class.
 
 ```PowerShell

wmf/class_baseconstructor.md

@@ -1,4 +1,4 @@
-### Call Base Class Constructor
+# Call Base Class Constructor
 
 To call a base class constructor from a subclass, use the keyword **base**.
 ```PowerShell

wmf/class_basemethod.md

@@ -1,4 +1,4 @@
-### Call Base Class Method
+# Call Base Class Method
 
 You can override existing methods in subclasses. To do this, declare methods by using the same name and signature.
 ```PowerShell

wmf/class_interface.md

@@ -1,4 +1,4 @@
-### Declare Implemented Interface
+# Declare Implemented Interface
 
 You can declare implemented interfaces after base types, or immediately after a colon (:), if there is no base type specified. Separate all type names by using commas. It’s very similar to C\# syntax.