Merge pull request #91 from PerimeterX/release/3.2.0

Release version 3.2.0 to master

CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 
+## [3.2.0] - 2023-01-03
+### Added
+- Support for credentials intelligence protocols `v2` and `multistep_sso`
+- Support for login successful reporting methods `header`, `status`, `body`, and `custom`
+- Support for automatic sending of `additional_s2s` activity
+- Support for manual sending of `additional_s2s` activity via header
+- Support for sending raw username on `additional_s2s` activity
+- Support for login credentials extraction via custom function
+- New `request_id` field to all enforcer activities
+
 ## [3.1.4] - 2022-12-05
 ### Added
 - Compatibility with .NET Framework 4.7 and higher

PerimeterXModule/CustomBehavior/ICredentialsExtractionHandler.cs

@@ -0,0 +1,9 @@
+using System.Web;
+
+namespace PerimeterX.CustomBehavior
+{
+ public interface ICredentialsExtractionHandler
+ {
+ ExtractedCredentials Handle(HttpRequest httpRequest);
+ }
+}

PerimeterXModule/CustomBehavior/ILoginSuccessfulHandler.cs

@@ -0,0 +1,9 @@
+using System.Web;
+
+namespace PerimeterX.CustomBehavior
+{
+ public interface ILoginSuccessfulHandler
+ {
+ bool Handle(HttpResponse httpResponse);
+ }
+}

PerimeterXModule/DataContracts/Activities/ActivityDetails.cs

@@ -40,6 +40,18 @@ public class ActivityDetails : IActivityDetails
 
  [DataMember(Name = "simulated_block")]
  public bool? SimulatedBlock;
+
+ [DataMember(Name = "ci_version")]
+ public string CiVersion { get; set; }
+
+ [DataMember(Name = "credentials_compromised")]
+ public bool CredentialsCompromised { get; set; }
+
+ [DataMember(Name = "sso_step")]
+ public string SsoStep { get; set; }
+
+ [DataMember(Name = "request_id")]
+ public string RequestId { get; set; }
  }
 
  [DataContract]
@@ -59,5 +71,37 @@ public class EnforcerTelemetryActivityDetails : IActivityDetails
 
  [DataMember(Name = "enforcer_configs")]
  public string EnforcerConfigs;
- }
+ }
+
+ [DataContract]
+ public class AdditionalS2SActivityDetails : IActivityDetails
+ {
+
+ [DataMember(Name = "client_uuid")]
+ public string ClientUuid { get; set; }
+
+ [DataMember(Name = "request_id")]
+ public string RequestId { get; set; }
+
+ [DataMember(Name = "ci_version")]
+ public string CiVersion { get; set; }
+
+ [DataMember(Name = "credentials_compromised", EmitDefaultValue = false)]
+ public bool CredentialsCompromised { get; set; }
+
+ [DataMember(Name = "http_status_code")]
+ public int HttpStatusCode { get; set; }
+
+ [DataMember(Name = "login_successful")]
+ public bool LoginSuccessful { get; set; }
+
+ [DataMember(Name = "raw_username")]
+ public string RawUsername { get; set; }
+
+ [DataMember(Name = "sso_step")]
+ public string SsoStep { get; set; }
+
+ [DataMember(Name = "module_version")]
+ public string ModuleVersion { get; internal set; }
+ }
 }

PerimeterXModule/DataContracts/Requests/Additional.cs

@@ -46,5 +46,24 @@ public class Additional
 
  [DataMember(Name = "enforcer_vid_source", EmitDefaultValue = false)]
  public string VidSource;
- }
+
+ [DataMember(Name = "user")]
+ public string Username;
+
+ [DataMember(Name = "pass")]
+ public string Password;
+
+ [DataMember(Name = "raw_username", IsRequired = false)]
+ public string RawUsername;
+
+ [DataMember(Name = "ci_version")]
+ public string CiVersion;
+
+ [DataMember(Name = "sso_step", IsRequired = false)]
+ public string SsoStep;
+
+ [DataMember(Name = "request_id")]
+ public string RequestId { get; set; }
+
+ }
 }

PerimeterXModule/Internals/CredentialsIntelligence/CredentialIntelligenceManager.cs

@@ -0,0 +1,199 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Text;
+using System.Text.RegularExpressions;
+using System.Threading.Tasks;
+using System.Web;
+using Jil;
+using PerimeterX.CustomBehavior;
+
+namespace PerimeterX
+{
+ public class CredentialIntelligenceManager
+ {
+ private ICredentialsIntelligenceProtocol protocol;
+ private List<ExtractorObject> loginCredentialsExtractors;
+
+ public CredentialIntelligenceManager(string ciVersion, List<ExtractorObject> loginCredentialsExraction)
+ {
+ this.protocol = CredentialsIntelligenceProtocolFactory.Create(ciVersion);
+ this.loginCredentialsExtractors = loginCredentialsExraction;
+ }
+
+ public LoginCredentialsFields ExtractCredentialsFromRequest(PxContext context, HttpRequest request, ICredentialsExtractionHandler credentialsExtractionHandler)
+ {
+ try
+ { 
+ ExtractorObject extractionDetails = FindMatchCredentialsDetails(request);
+
+ if (extractionDetails != null)
+ {
+ ExtractedCredentials extractedCredentials = ExtractLoginCredentials(context, request, credentialsExtractionHandler, extractionDetails);
+
+
+ if (extractedCredentials != null)
+ {
+ return protocol.ProcessCredentials(extractedCredentials);
+ }
+ }
+
+ } catch (Exception ex)
+ {
+ PxLoggingUtils.LogError(string.Format("Failed to extract credentials.", ex.Message));
+ }
+
+ return null;
+ }
+
+ private ExtractedCredentials ExtractLoginCredentials(PxContext context, HttpRequest request, ICredentialsExtractionHandler credentialsExtractionHandler, ExtractorObject extractionDetails)
+ {
+ if (credentialsExtractionHandler != null)
+ {
+ return credentialsExtractionHandler.Handle(request);
+ }
+ else
+ {
+ return HandleExtractCredentials(extractionDetails, context, request);
+ }
+ }
+
+ private ExtractorObject FindMatchCredentialsDetails(HttpRequest request)
+ {
+ foreach (ExtractorObject loginObject in this.loginCredentialsExtractors)
+ {
+ if (IsRequestMatchLoginRequestConfiguration(loginObject, request))
+ {
+ return loginObject;
+ }
+ }
+
+ return null;
+ }
+
+ private static bool IsRequestMatchLoginRequestConfiguration(ExtractorObject extractorObject, HttpRequest request)
+ {
+ if (request.HttpMethod.ToLower() == extractorObject.Method)
+ {
+ if (extractorObject.PathType == "exact" && request.Path == extractorObject.Path)
+ {
+ return true;
+ }
+
+ if (extractorObject.PathType == "regex" && Regex.IsMatch(request.Path, extractorObject.Path))
+ {
+ return true;
+ }
+ }
+
+ return false;
+ }
+
+ private ExtractedCredentials HandleExtractCredentials(ExtractorObject extractionDetails, PxContext pxContext, HttpRequest request)
+ {
+ string userFieldName = extractionDetails.UserFieldName;
+ string passwordFieldName = extractionDetails.PassFieldName;
+
+ if (userFieldName == null || passwordFieldName == null)
+ {
+ return null;
+ }
+
+ Dictionary<string, string> headers = pxContext.GetLowercaseHeadersAsDictionary();
+
+ if (extractionDetails.SentThrough == "header")
+ {
+ return ExtractFromHeader(userFieldName, passwordFieldName, headers);
+ } else if (extractionDetails.SentThrough == "query-param")
+ {
+ return new ExtractedCredentials(
+ request.QueryString[userFieldName].Replace(" ", "+"),
+ request.QueryString[passwordFieldName].Replace(" ", "+")
+ );
+ } else if (extractionDetails.SentThrough == "body")
+ {
+ return ExtractFromBody(userFieldName, passwordFieldName, headers, request);
+ }
+
+ return null;
+ }
+
+ public static ExtractedCredentials ExtractFromHeader(string userFieldName, string passwordFieldName, Dictionary<string, string> headers)
+ {
+ bool isUsernameHeaderExist = headers.TryGetValue(userFieldName.ToLower(), out string userName);
+ bool isPasswordHeaderExist = headers.TryGetValue(passwordFieldName.ToLower(), out string password);
+
+ if (!isUsernameHeaderExist && !isPasswordHeaderExist) { return null; }
+
+ return new ExtractedCredentials(userName, password);
+ }
+
+ private ExtractedCredentials ExtractFromBody(string userFieldName, string passwordFieldName, Dictionary<string, string> headers, HttpRequest request)
+ {
+ bool isContentTypeHeaderExist = headers.TryGetValue("content-type", out string contentType);
+
+ string body = BodyReader.ReadRequestBody(request);
+
+ if (!isContentTypeHeaderExist)
+ {
+ return null;
+ } else if (contentType.Contains("application/json"))
+ {
+ return ExtractCredentialsFromJson(body, userFieldName, passwordFieldName);
+ } else if (contentType.Contains("x-www-form-urlencoded"))
+ {
+ return ReadValueFromUrlEncoded(body, userFieldName, passwordFieldName);
+ } else if (contentType.Contains("form-data"))
+ {
+ return ExtractValueFromMultipart(body, contentType, userFieldName, passwordFieldName);
+ }
+
+ return null;
+ }
+
+ private ExtractedCredentials ExtractCredentialsFromJson(string body, string userFieldName, string passwordFieldName) {
+
+ dynamic jsonBody = JSON.DeserializeDynamic(body, PxConstants.JSON_OPTIONS);
+
+ string userValue = PxCommonUtils.ExtractValueFromNestedJson(userFieldName, jsonBody);
+ string passValue = PxCommonUtils.ExtractValueFromNestedJson(passwordFieldName, jsonBody);
+
+ return new ExtractedCredentials(userValue, passValue);
+ }
+
+ private ExtractedCredentials ReadValueFromUrlEncoded(string body, string userFieldName, string passwordFieldName)
+ {
+ var parametersQueryString = HttpUtility.ParseQueryString(body);
+ var parametersDictionary = new Dictionary<string, string>();
+ foreach (var key in parametersQueryString.AllKeys)
+ {
+ parametersDictionary.Add(key, parametersQueryString[key]);
+ }
+
+ return ExtractCredentialsFromDictionary(parametersDictionary, userFieldName, passwordFieldName);
+ }
+
+ private ExtractedCredentials ExtractValueFromMultipart(string body, string contentType, string userFieldName, string passwordFieldName)
+ {
+ Dictionary<string, string> formData = BodyReader.GetFormDataContentAsDictionary(body, contentType);
+
+ return ExtractCredentialsFromDictionary(formData, userFieldName, passwordFieldName);
+ }
+
+ private ExtractedCredentials ExtractCredentialsFromDictionary(Dictionary<string, string> parametersDictionary, string userFieldName, string passwordFieldName)
+ {
+ bool isUsernameExist = parametersDictionary.TryGetValue(userFieldName, out string userField);
+ bool isPasswordExist = parametersDictionary.TryGetValue(passwordFieldName, out string passwordField);
+
+ if (!isUsernameExist && !isPasswordExist)
+ {
+ return null;
+ }
+
+ return new ExtractedCredentials(userField, passwordField);
+ }
+ } 
+
+
+}

PerimeterXModule/Internals/CredentialsIntelligence/CredentialsIntelligenceProtocolFactory.cs

@@ -0,0 +1,21 @@
+using System;
+using PerimeterX;
+
+namespace PerimeterX
+{
+ public class CredentialsIntelligenceProtocolFactory
+ {
+ public static ICredentialsIntelligenceProtocol Create(string protocolVersion)
+ {
+ switch(protocolVersion)
+ {
+ case CIVersion.V2:
+ return new V2CredentialsIntelligenceProtocol();
+ case CIVersion.MULTISTEP_SSO:
+ return new MultistepSSoCredentialsIntelligenceProtocol();
+ default:
+ throw new Exception("Unknown CI protocol version: " + protocolVersion);
+ }
+ }
+ }
+}

PerimeterXModule/Internals/CredentialsIntelligence/ExtractedCredentials.cs

@@ -0,0 +1,19 @@
+using System.Runtime.Serialization;
+
+namespace PerimeterX
+{
+ public class ExtractedCredentials
+ {
+ [DataMember(Name = "username")]
+ public string Username { get; set; }
+
+ [DataMember(Name = "password")]
+ public string Password { get; set; }
+
+ public ExtractedCredentials(string username, string password)
+ {
+ this.Username = username;
+ this.Password = password;
+ }
+ }
+}

PerimeterXModule/Internals/CredentialsIntelligence/ExtractorObject.cs

@@ -0,0 +1,26 @@
+using System.Runtime.Serialization;
+
+namespace PerimeterX
+{
+ [DataContract]
+ public class ExtractorObject
+ {
+ [DataMember(Name = "path")]
+ public string Path;
+
+ [DataMember(Name = "path_type")]
+ public string PathType;
+
+ [DataMember(Name = "method")]
+ public string Method;
+
+ [DataMember(Name = "sent_through")]
+ public string SentThrough;
+
+ [DataMember(Name = "pass_field")]
+ public string PassFieldName;
+
+ [DataMember(Name = "user_field")]
+ public string UserFieldName;
+ }
+}

PerimeterXModule/Internals/CredentialsIntelligence/ICredentialsIntelligenceProtocol.cs

@@ -0,0 +1,8 @@
+
+namespace PerimeterX
+{
+ public interface ICredentialsIntelligenceProtocol
+ {
+ LoginCredentialsFields ProcessCredentials(ExtractedCredentials extractedCredentials);
+ }
+}