Skip to content

Commit 80074dc

Browse files
KarneadesKarneades
committed
Initial release
0 parents  commit 80074dc

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

62 files changed

+19249
-0
lines changed

‎.gitattributes

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
*.ps1 -text diff merge
2+
*.psm1 -text diff merge
3+
*.psd1 -text diff merge

‎.gitignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Add any directories, files, or patterns you don't want to be tracked by version control
2+
*.swp
3+
!.gitignore
4+
/bin/*.exe

‎BUILD.md

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# BUILD
2+
3+
## Testing
4+
5+
Run all the tests:
6+
7+
`Invoke-Pester .\test\`
8+
9+
To use the code coverage assessment use `-CodeCoverage`:
10+
11+
`$res = Invoke-Pester .\Pester\ -CodeCoverage ..\PowerSponse.psm1 -PassThru`
12+
13+
The result can be read in the following manner:
14+
15+
``` powershell
16+
PS> $res.TotalCount
17+
11
18+
PS> $res.FailedCount
19+
0
20+
PS> $res.PassedCount
21+
11
22+
```
23+
24+
# Source Code Analyzer
25+
26+
`Invoke-ScriptAnalyzer -Path .\PowerSponse\`
27+
28+
## Generating Help
29+
30+
### Markdown Help
31+
First time create markdown help with the following commands
32+
33+
``` powershell
34+
# 1. Import module
35+
Import-Module .\PowerSponse.psd1 -Force
36+
37+
# 2. Create new markdown help for module, otherwise use 3.
38+
New-MarkdownHelp -Module PowerSponse -OutputFolder .\docs\ -WithModulePage -Force -HelpVersion "1.0.0.0"
39+
40+
# 3. Create new markdown help file for specific command
41+
New-MarkdownHelp -Command Restart-Computer -OutputFolder .\docs\ -OnlineVersionUrl "https://github.com/swisscom/PowerSponse/master/docs/Restart-Computer.md"
42+
```
43+
44+
For updating the markdown help use instead the following commands
45+
46+
``` powershell
47+
Import-Module .\PowerSponse.psd1 -Force
48+
Remove-Module microsoft.powershell.management
49+
ipmo microsoft.powershell.management -NoClobber
50+
Update-MarkdownHelp .\docs\
51+
```
52+
53+
### PowerShell Help
54+
Use the following command for creating a PowerShell help file (use `-force` to
55+
update an existing external help file).
56+
57+
``` powershell
58+
New-ExternalHelp -Path .\docs\ -OutputPath en-us\ -Force
59+
```
60+
61+
## Tags file for PowerShell
62+
63+
### PowerShell
64+
The following [ctags](http://ctags.sourceforge.net/ctags.html) command uses
65+
only variables which come directly after a type declaration, e.g. \[string\]
66+
var.
67+
68+
ctags.cnf (variables disabled through the regex)
69+
70+
```
71+
--langdef=powershell
72+
--langmap=powershell:.psm1.ps1
73+
--regex-powershell=/function\s+(script:)?([a-zA-Z\-]+)/\2/m, method/i
74+
--regex-powershell=/xxxxCommentxxxxx\s*\[.*\]\s*\$([a-zA-Z\-]+)/\1/v, variable/i
75+
--regex-powershell=/xxxxCommentxxxxx\$global:([a-zA-Z\-]+)/\1/v, globalvariable/i
76+
--exclude=test
77+
--exclude=bin
78+
```
79+
80+
ctags command
81+
82+
```
83+
ctags -R --languages=powershell
84+
```
85+
86+
### Pester
87+
88+
```
89+
ctags -R --langdef=pester --langmap=pester:.ps1 --regex-pester="/describe\s+'(.*)'/\1/m, method/i"
90+
```
91+
92+
Use `--excmd=number` for line numbers instead of the tag text.
93+
94+
## References
95+
* [Pester](https://github.com/pester/Pester)
96+
* [platyPS](https://github.com/PowerShell/platyPS)
97+
* [New-ModuleManifest](https://msdn.microsoft.com/en-us/powershell/reference/5.1/microsoft.powershell.core/new-modulemanifest)
98+
* [Update-ModuleManifest](https://msdn.microsoft.com/powershell/reference/5.1/PowerShellGet/Update-ModuleManifest)

‎CHANGELOG.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# CHANGELOG
2+
All notable changes to this project will be documented in this file.
3+
4+
The format is based on [Keep a Changelog](http://keepachangelog.com/)
5+
and this project adheres to [Semantic Versioning](http://semver.org/).
6+
7+
## [Unreleased](https://github.com/swisscom/PowerSponse/compare/v0.1.0...master)
8+
<!--
9+
### Added
10+
### Changed
11+
### Fixed
12+
### Security
13+
### Deprecated
14+
### Removed
15+
-->
16+
17+
## [v0.1.0](https://github.com/swisscom/PowerSponse/tree/v0.1.0) - 2018-08-02
18+
19+
:tada: Initial public release. :tada:
20+
21+
This release includes basic **commands for contain malicious scheduled tasks,
22+
services, processes and some other host commands (e.g. disable network
23+
interface)**. Allow using the commands against remote host or without a given
24+
hostname run the command against localhost. Furthermore, a **rule engine was
25+
implemented to allow using CoRe (COntainment and REmediation) rules** and use
26+
them for containment. A **plugin architecture** was used to allow an easy way
27+
to add new functions.
28+
29+
### Added
30+
* Setup for building markdown and external help with **platyPS**.
31+
* Add plugin functionality for functions. All functions are in the subfolder functions/*.
32+
* Introduce **plugin architecture** to `Invoke-PowerSponse`. Add
33+
the available functions for Invoke-PowerSponse to the repository which is
34+
then used when processing CORE rules.
35+
* Initial version of **CoRe rule** engine and syntax [CORE](CORE-RULES.md). **XML or JSON
36+
can be used for defining a CoRe rule**. By default XML is used to parse a
37+
rule, when using JSON change the method using `-Method json`.
38+
If no method is given when calling the `Invoke-PowerSponse` the file
39+
extension is used to decide whether to use the XML or JSON parser. Use
40+
OpenIOC terms for CoRe rule actions.
41+
* Add functionality to create a **cleanup package for offline deployment**
42+
for deployment without direct network connection (`New-CleanupPackage`). The
43+
function packs all available functions into one file and adds the cleanup
44+
commands at the end of the script. This script can be executed locally on
45+
the target without a remote connection.
46+
* Add following functions
47+
* Add `Invoke-PowerSponse` as the main function for using CoRe rules
48+
and to build offline cleanup packages.
49+
* Add function to parse CoRe rules (`Get-PowerSponseRule`) and display the
50+
rule.
51+
* Service functions (`Edit-Service`, `Start-Service`, `Stop-Service`,
52+
`Disable-Service`, `Enable-Service`, `Get-Service`)
53+
* Enable and disable RemoteRegistry (`Enable-RemoteRegistry`, `Disable-RemoteRegistry`)
54+
* Get, start and kill processes (`Get-Process`, `Start-process`, `Stop-Process`)
55+
* Get ,enable and disable scheduled tasks (`Get-ScheduledTask`, `Enable-ScheduledTask`,
56+
`Disable-ScheduledTask`)
57+
* Get, enable and disable network adpaters (`Get-NetworkInterface`, `Edit-NetworkInterface`,
58+
`Enable-NetworkInterface`, `Disable-NetworkInterface`)
59+
* Find files based on regex (`Find-File`)
60+
* Get PowerSponse repository (see [Repository Configuration](Repository.ps1)
61+
for functions which are supported by `Invoke-PowerSponse`). Use
62+
`Get-PowerSponseRepository` and to change the current repository use
63+
`Set-PowerSponseRepository`.
64+
* Reading certificates using WinRM based on regex (`Get-Certificate`)
65+
* Reading the open file handles by process name or pid (`Get-FileHandle`)
66+
* Restart and shutdown hosts (`Restart-Computer`,
67+
`Stop-Computer`) using WMI.
68+
* Add `Get-Autoruns` for collecting autorunsc output into a csv file. The
69+
command can be used with a target list or with multiple computer names.
70+
* Add regex functionality to different functions, e.g. to search scheduled
71+
tasks or services based on a regex expressions.
72+
* Internal support Function
73+
* Function for handling target lists (`Get-Target`). `Get-Target` can
74+
handle `-ComputerName` and/or `-ComputerList` for the definition of
75+
target hosts.
76+
* Function for creating standard PowerSponse response objects
77+
(`New-PowerSponseObject`).
78+
* Use method **WMI by default** (use "-method" to change that if function allows).
79+
* Check for missing action types to `Invoke-PowerSponse` and to
80+
`New-CleanupPackage`. If an action type is used within a CoRe rule which
81+
is not available in the repository then stop execution.
82+
* Add markdown help files and PowerShell help
83+
* Add download script for required binaries when using PsExec etc. See README
84+
and PowerShell script in the \bin folder.
85+
* Initial **Pester** tests.

‎CONTRIBUTING.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Contributing to PowerSponse
2+
3+
Great, you decided to contribute! That's awesome!
4+
5+
Please file an [issue](https://github.com/swisscom/PowerSponse/issues) if you
6+
need a new feature or found an inconvenient "situation" (bug) or get the code
7+
form Github, make a new branch, extend the functionality as its needed and
8+
make a [pull request](https://github.com/swisscom/PowerSponse/pulls) if you
9+
need a new feature or found an inconvenient "situation". See section
10+
[What is PowerSponse?](README.md#what-is-powersponse) for an overview about
11+
the repo structure.
12+
13+
Please use the guidelines as references when implementing new functions and
14+
check current cmdlets how to use supporting functions.
15+
16+
* [PowerShell scripting best practices](https://blogs.technet.microsoft.com/pstips/2014/06/17/powershell-scripting-best-practices/)
17+
* [Building-PowerShell-Functions-Best-Practices](http://ramblingcookiemonster.github.io/Building-PowerShell-Functions-Best-Practices/)
18+
* [Strongly Encouraged Development Guidelines](https://msdn.microsoft.com/en-us/library/dd878270(v=vs.85).aspx)
19+
* [Approved Verbs for Windows PowerShell Commands](https://msdn.microsoft.com/en-us/library/ms714428(v=vs.85).aspx)
20+
* [How to Write a PowerShell Module Manifest](https://msdn.microsoft.com/en-us/library/dd878337(v=vs.85).aspx)
21+
* [Windows PowerShell: Writing Cmdlets in Script](https://technet.microsoft.com/en-us/library/ff677563.aspx)
22+
23+
Some general guidelines:
24+
25+
* Functions must support the common parameters (e.g. -WhatIf)
26+
* Functions should support all methods: WMI, WinRM, External
27+
* Functions must return PowerSponse objects to be able to concatenate the
28+
output of different commands
29+
* Functions names must comply with the PowerShell approved verbs (see
30+
references below)
31+
* Functions should not throw an exception instead the field "reason" should
32+
contain the error message
33+
* Add Pester tests for new functionality in .\tests\Pester\
34+
* Register the feature to the `$Repository` variable (see PowerSponse.psm1)

‎LICENSE.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
The MIT License (MIT)
2+
3+
Copyright © 2018 Swisscom (Schweiz) AG
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
6+
7+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8+
9+
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎PowerSponse.psd1

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
#
2+
# Module manifest for module 'PowerSponse'
3+
#
4+
# Generated by: Swisscom (Schweiz) AG
5+
#
6+
# Generated on: 04.12.2016
7+
#
8+
9+
@{
10+
11+
# Script module or binary module file associated with this manifest.
12+
RootModule = 'PowerSponse.psm1'
13+
14+
# Version number of this module.
15+
ModuleVersion = '0.1.0'
16+
17+
# ID used to uniquely identify this module
18+
GUID = 'ca85e27c-3d41-49a1-9315-fb44966836b7'
19+
20+
# Author of this module
21+
Author = 'Swisscom (Schweiz) AG'
22+
23+
# Company or vendor of this module
24+
CompanyName = 'Swisscom (Schweiz) AG'
25+
26+
# Copyright statement for this module
27+
Copyright = '(c) 2018 Swisscom (Schweiz) AG'
28+
29+
# Description of the functionality provided by this module
30+
Description = 'The module allows a fast and easy way to contain and remediate a threat on a remote host.'
31+
32+
# Minimum version of the Windows PowerShell engine required by this module
33+
PowerShellVersion = '3.0'
34+
35+
# Name of the Windows PowerShell host required by this module
36+
# PowerShellHostName = ''
37+
38+
# Minimum version of the Windows PowerShell host required by this module
39+
# PowerShellHostVersion = ''
40+
41+
# Minimum version of Microsoft .NET Framework required by this module
42+
# DotNetFrameworkVersion = ''
43+
44+
# Minimum version of the common language runtime (CLR) required by this module
45+
# CLRVersion = ''
46+
47+
# Processor architecture (None, X86, Amd64) required by this module
48+
ProcessorArchitecture = 'None'
49+
50+
# Modules that must be imported into the global environment prior to importing this module
51+
# RequiredModules = @()
52+
53+
# Assemblies that must be loaded prior to importing this module
54+
RequiredAssemblies = @()
55+
56+
# Script files (.ps1) that are run in the caller's environment prior to importing this module.
57+
ScriptsToProcess = @()
58+
59+
# Type files (.ps1xml) to be loaded when importing this module
60+
TypesToProcess = @()
61+
62+
# Format files (.ps1xml) to be loaded when importing this module
63+
FormatsToProcess = @()
64+
65+
# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
66+
# NestedModules = @()
67+
68+
# Functions to export from this module
69+
FunctionsToExport = @(
70+
'Invoke-PowerSponse',
71+
'New-CleanupPackage',
72+
'Get-PowerSponseRule',
73+
'Get-Process',
74+
'Start-Process',
75+
'Stop-Process',
76+
'Start-Service',
77+
'Stop-Service',
78+
'Enable-Service',
79+
'Disable-Service',
80+
'Get-ScheduledTask',
81+
'Enable-ScheduledTask',
82+
'Disable-ScheduledTask',
83+
'Stop-Computer',
84+
'Restart-Computer',
85+
'Get-NetworkInterface',
86+
'Enable-NetworkInterface',
87+
'Disable-NetworkInterface',
88+
'Get-Autoruns',
89+
'Enable-RemoteRegistry',
90+
'Disable-RemoteRegistry',
91+
'Get-PowerSponseRepository',
92+
'Set-PowerSponseRepository',
93+
'Import-PowerSponseRepository',
94+
'Get-FileHandle'
95+
)
96+
97+
# Cmdlets to export from this module
98+
CmdletsToExport = @()
99+
100+
# Variables to export from this module
101+
VariablesToExport = @()
102+
103+
# Aliases to export from this module
104+
AliasesToExport = @()
105+
106+
# DSC resources to export from this module
107+
# DscResourcesToExport = @()
108+
109+
# List of all modules packaged with this module
110+
# ModuleList = @()
111+
112+
# List of all files packaged with this module
113+
FileList = @(
114+
'PowerSponse.psd1',
115+
'PowerSponse.psm1',
116+
'en-us\PowerSponse-help.xml'
117+
)
118+
119+
# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
120+
PrivateData = @{
121+
122+
PSData = @{
123+
124+
# Tags applied to this module. These help with module discovery in online galleries.
125+
Tags = @('IncidentResponse','Containment','Remediation','ActiveResponse')
126+
127+
# A URL to the license for this module.
128+
LicenseUri = 'https://github.com/swisscom/PowerSponse/LICENSE.md'
129+
130+
# A URL to the main website for this project.
131+
ProjectUri = 'https://github.com/swisscom/PowerSponse'
132+
133+
# A URL to an icon representing this module.
134+
# IconUri = ''
135+
136+
# ReleaseNotes of this module
137+
# ReleaseNotes = ''
138+
139+
# External dependent modules of this module
140+
# ExternalModuleDependencies = ''
141+
142+
} # End of PSData hashtable
143+
144+
} # End of PrivateData hashtable
145+
146+
# HelpInfo URI of this module
147+
# HelpInfoURI = ''
148+
149+
# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
150+
# DefaultCommandPrefix = ''
151+
152+
}

0 commit comments

Comments
 (0)