FSRM-Anti-ransomware development notes_2.5.0.txt

KB's Development Notes - I've made a ton of different choices from the inspirational version and I'm no PowerShell expert. The inspiration for this script was originated by Luke Orellana. Thanks Luke!
	inspiration script source:
		https://www.altaro.com/hyper-v/using-file-server-resource-manager-screen-ransomware/
		https://www.altaro.com/hyper-v/author/luke-orellana/
		And Luke's works with Windows 2008 too. This script does not.
	Also a big thank you to the folks Changemaker Studios who make PowerCut, a very simple SMTP server emulator that is fantastic for testing.
		https://github.com/ChangemakerStudios/Papercut (they deserve your appreciation)
	Also a big thank you to the folks who host regex 101
		https://regex101.com/ (this site helps me just about any time I attempt regex, they deserve your appreciation)
	HUGE! Thank you to:
		https://fsrm.experiant.ca
			They update their list of ransomware file names and extensions every few days. So thankful for them. They deserve your business if you have a need.
		https://fsrm.experiant.ca/api/v1/combined
			They host an up to date list of the latest file names in json download format, the maintainers deserve your appreciation
	A quick note about this document's formatting:
		I've been using Smith/White formatting since the K&R days of C. I know it's not to everyone's liking. Sorry in advance.
		Because the Windows PowerShell ISE is a pain about tabs, all the tabs in this script are hard. For best viewing set your spacing to 4 like ISE.
		I let my comments and code go way beyond the old 80 character boundary. Scroll if you gotta.
		This is my first significant PowerShell script and I'm pretty sure I don't like PowerShell. It's even wordier than me.

changes from version 1.0 to 2.x by Kurt Brown (KB):
	Only runs on Win2012 (Windows 6.2) or higher, this will absolutely not run on W2008. Luke's inpspirational script will however.
	script is now using PowerShell version 4
	added a huge number of suspect file extensions to the static list, not all from Experiant's list
	used all Get-CIM style calls instead of Get-Win32 calls
		Get-Win32 is now deprecated so it's time to move on
	found backtick (escaped character) bug for line containing the service force restart which was part of Luke's remediation script that gets created
		Restart-Service "File Server Resource Manager" -force
		I commented out the line but left it in his script just in case someone needs it
	used  native FSRM PowerShell commands instead of XML export/import methods
	set script creation target directory to "C:\PROGRA~1\FSRM-triggered-scripts"
		added a variable to contain the value
			sure the path name is wordy but it also tells other admins why the script(s) is there and what it is for
			! Do not use a path name with spaces in it. It will lead to an escaping of the escaping string complications.
	added option to apply template to found shares instead of only found drives
	for discovering and adding to drives I used pipelined ForEach-Object method (the single line technique that I personally prefer)
	the FSRM Command -> Command arguments does not seem to handle spaces in quoted path strings correctly, quotes in quotes may be the problem, do this
		-Command "& {C:\PROGRA~1\FSRM-triggered-scripts\XXXXXX.ps1"
		!! this assumes that "C:\Program Files" is "C:\PROGRA~1" which should be the case unless the Program Files directory was recreated manually (very unlikely)
	no mandatory parameter processing
	added Begin clause for startup version and other prereq testing
	added SMTP server and security admin email address variables
	source email address will be FSRM-[hostname]@[domain name]
		test for SMTP global settings and apply in initial settings if necessary
	no email options in our triggered script and instead added the email functions to the template or the FSRM general options since it's already built-in to FSRM
	caused the user information to be passed to the triggered script
	added honey pot directory capability, new functionality not in inpspirational script
		added second file group to catch all files
		created a passive file screen template, hopefully the bad actor will leave some footprints for forensic analysis, this could really really help you
	not counting users on a share, blocking all of them
	added variables to control which sort of screening to apply
	added option to delete current file screens so that they can be reapplied to newly found shares and drives, delete near beginning of script in case templates need to be nuked too
		especially useful for honey pots
	Special case!: if the drive roots are screened we exclude C: because it's the OS drive, added a special case to pick up any shares (however misguided they may be) on C:
	tried using try/except blocks but they don't suppress caught errors, not adequate for an "ask forgiveness" paradigm, switching to if/then "ask permission" paradigm
		Have I mentioned how frustrating PowerShell can be? Maybe it can be Python when it grows up.
	testing if templates already exist, if not then create (new), if exist then update (set)
	just added hundreds more of new suspect file names and extensions, currently 2700+ entries, *.potato is still on the list, Who's hungry? Me!
	moving the hard coded file names and extension to a variable as a default that should be overwritten dynamically later in the script
		import via JSON, either from file or from https://fsrm.experiant.ca/api/v1/combined.
			!! this import does not support exclusions, important !!
				nothing wrong with that - it would be inappropriate to have Experiant, or anyone else, provide exclusion information. Use your own local JSON or manually populate this script.
	additional error detection, warnings, and hard exits
	The json file we're using is a super-set of the Experiant version
		I've added an allowed file names section that I use with a Python script to merge and groom the Experiant data and additional sources that I've accumulated
			may change the name of this one, it's kind of confusing
		I've added an exception section too. This is used for the "Files to exclude" section of our fsrm file group.
		Default location is for the json file to be in the same location as this script. You may override that.
		Our filtered file names and extensions are more comprehensive that those on Experiant, but many are not verified and many are extended with additional wildcards.
			the point: run your file screens with only reporting and only passive for a while to make sure you don't have unintended lockouts
	added a BOM to this script source file as a work around for PowerShell ISE, now UTF-8-BOM
		UTF-8 shouldn't need a BOM at all but PowerShell seems to assume ASCII, this script relies on Unicode/UTF-8 encoding for the embedded filters
		also added ASCII to Unicode comparison strings at the top of this script so that encoding problems are very obvious
	local JSON input file reading now matches a wildcard pattern and uses the most recent one found
		most recent is indicated by date string in file's name and not by actual file date
	tested Windows and PowerShell versions, script has been tested on W2012(r1) through W2019, W2008 and below is not possible with this script
	added a confirmation variable that must be set manually to acknowledge that the user understands the security implications and is ready to proceed
	change honey pot file group to HoneyPotAllFilesWildcard or something like that
	add exclude option to honey pots, thumbs.db and desktop.ini are what I have in mind, for those who just can't resist pushing the big red button
	made triggered script path detection and creation a bit more polite
	fixed - Get-ChildItem fails silently, $? is always true, found new way to detect failure
	print each file screen's name as it's deleted, otherwise this process is too quiet and there could be hundreds of honey pots to delete
	added a "#Requires -Version 4 -RunAsAdministrator" globals to the top of the script
		do not add any spaces between the hash symbol and "Requires", you'll break it
		JSON parsing when data is pipelined from Get-Content is wonky in PowerShell 4 and below. Found out why! keep reading
			Get-Content | ConvertFrom-Json may fail without warning. The cause is the Get-Content by default creates an array of strings that ConvertFrom-Json can't always parse.
				-Raw is what you need to add to Get-Content. This tells Get-Content to treat the input as one single string.
			Not an issue at all for PowerShell 5.1 and above (WMF 5.1).
			For Windows 2012 you must install Windows Management Framework 5.1, probably should for Windows 2012r2 too
				https://www.microsoft.com/en-us/download/details.aspx?id=54616
				W2K12-KB3191565-x64.msu is the file you want (sha 256: 4a1385642c1f08e3be7bc70f4a9d74954e239317f50d1a7f60aa444d759d4f49 )
				full disclosure - you can work around this and use only PowerShell 3, but you have to modify this script. I recommend using WMF 5.1.
	added logging to Windows Application event log, source is configurable, event log is configurable but should probably always be "Application"
		create source every time script runs, will usually fail silently (and gracefully) because the source already exists
		convenience copies:
			Write-EventLog -LogName $EventLog -Source $EventLoggingSource -Category 0 -EventID 0 -EntryType Information -Message $message
			Write-EventLog -LogName Application -Source $EventLoggingSource -Category 0 -EventID 1000 -EntryType Warning -Message $message
			Write-EventLog -LogName $EventLog -Source $EventLoggingSource -Category 0 -EventID 2000 -EntryType Error -Message $message
		category always 0, puts "None" in event log
		event IDs 3001-3999 are informational and warning messages ONLY generated by the TriggeredDenySMBPermissions.PS1 script
		event IDs 2001-2999 are critical show stoppers
		event IDs 1001-1999 are warnings
		event IDs 1-999 are just informational and indicate normal operation
			1 is always script startup
			999 is always normal script shutdown
	convert all Write-Ouput to Write-Host
		colorized outputs
			information - default
			warning - yellow
			error - red
	updated default filters - 2018-08-27
	added -Raw flag to Get-Content | ConvertFrom-Json
		fixed intermittent JSON conversion error, caused by default of "array of strings", -Raw forces input to a single string
	renamed script to FSRM-Anti-ransomware.ps1
		can be renamed without problems, whatever you like, be sure declaration at top of begin and call at bottom of the script match
	adding param() block back into script now that the variables are finalized
		contains most commonly changed values, other configuration variables are located the top of the begin{} clause
	modified honey pot refresh to only remove honey pot templates that were created by the current instance of this script
		allows multiple $HoneyPotDirectoryNamePattern to be used
    output param() variables to event log
			listed in events 1 and 999 (both normal), and all warnings and errors
		formatting from https://stackoverflow.com/questions/21559724/getting-all-named-parameters-from-powershell-including-empty-and-set-ones (scroll down web page)
		added Out-String
	added $JSONfnamesubstring
		you can put any word (without spaces) you like to match the same substring in your input JSON file name
		allows for easy specification of custom JSON files, could be a client/company name, a server name, or whatever
	2.3.0
		added legacy handling of include list and skip list to section that already will download JSON data directly from source (currently Experiant)
		renamed direct download to legacy download, this is really just to be campatible with how so many people already use the older w2008 compat scripts
	2.4.0 - skipped
	2.5.0 - significant changes
		cleaning up header of script to match more typical PowerShell conventions including Comment Based Help
		adding option to handle honey pot directory names that use a leading dot in their names - thanks for the suggestion GitHub mol-tron
		adding option to force user to close all SMB share connections to triggered script - thanks for the suggestion GitHub mol-tron
		reformat comments explaining paramters
		changed triggered script path parsing to convert to short 8.3 paths, eliminated need to hard code path, actual script name still cannot contain spaces!
		changed triggered script location, configurable by editing script, non-command line option though
		changed triggered script name to better hint at actual function
		added class of events for triggered events called by FSRM
			event ID 3001 is only generated by the TriggeredDenySMBPermissions.PS1 for locking/denying events
			event ID 3002 is only generated by the TriggeredDenySMBPermissions.PS1 for unlocking/clearing events
			event ID 3101 is only generated by the TriggeredDenySMBPermissions.PS1 for unlocking a user, leave as a warning type so it stands out in a log
		changed event logging source to "FSRM Anti-ransomware Suite"
		filter validation
			Each filter is validated by substituting the legal wildcards with simple text and then using Test-Path -IsValid -Path <simplified_filter>.
			A "Warning" will be poked into the event log if any illegals are found. The illegals will be skipped but script exectution will continue with the legals.
		triggered script changes
			added ability to choose normal or rapid disconnect of SMB sessions
		can now choose rapid disconnect individaully for both ransomware and honey pot screens
		considered changing command line parms to use [switch] types instead of [bool] but decided against it, it's too convuluted to use with negative logic tests, we'll continue to support a loader script with explicit true/false flags

to do:
	add notes somewhere that we want 64bit Python
	warn if no shares, drives, or honey pots found
	add option to triggered script to disable the user's account
		dropped this idea - It's easy enough to bounce the user's SMB, but a much bigger issue to talk to the DC and shut down the entire account.
	write instructions on using multiple honey pot directory patterns
	write instruction on dangers of using actual Administrator account, should have a backdoor account that's never used but is active