menu

  • Module trufflehog3.models

    Helper classes for passing data around.

Classes
                    
                        class CaseInsensitiveEnumMeta(*args, **kwargs)
                    
                    
    
    
        
            open_in_new

Meta class for case-insensitive enum.

Ancestors
  • enum.EnumMeta
  • builtins.type
                    
                        class Severity(value, *args, **kwargs)
                    
                    
    
    
        
            open_in_new

Issue severity based on match confidence and other factors.

Ancestors
  • enum.Enum
Class variables
var LOW
var MEDIUM
var HIGH
                    
                        class Format(value, *args, **kwargs)
                    
                    
    
    
        
            open_in_new

Supported output formats.

Ancestors
  • enum.Enum
Class variables
var TEXT
var JSON
var HTML
                    
                        class Model
                    
                    
    
    
        
            open_in_new

Model is a base class for all models definitions.

Method generated by attrs for class Model.

Subclasses
Methods
            
                

                def asdict(self)
                
            
            
    
    
        
            open_in_new

Convert model to dictionary.

                    
                        class File(

                            path: str,

                            branch: Optional[str] = None,

                            message: Optional[str] = None,

                            commit: Optional[str] = None,

                            author: Optional[str] = None,

                            date: Optional[datetime.datetime] = None,

                            content: Optional[str] = None,

                            real: Optional[str] = None,

                        )
                    
                    
    
    
        
            open_in_new

File is a basic wrapper with Git metadata support.

Attributes

path (str)
File path.
branch (str, optional)
Git commit branch.
message (str, optional)
Git commit message.
author (str, optional)
Git commit author as name <email>.
commit (str, optional)
Git commit hash.
date (datetime.datetime, optional)
Git commit timestamp.

Args

content (str, optional)
File content.

Examples

Basic usage examples

>>> f = File("tests/data/test_file.txt")
>>> f.read()
'Test'
>>> f = File("nosuchpath/test_file.txt", content="Test")
>>> f.read()
'Test'

Method generated by attrs for class File.

Ancestors
Class variables
var path : str
var branch : Optional[str]
var message : Optional[str]
var commit : Optional[str]
var author : Optional[str]
var date : Optional[datetime.datetime]
Methods
            
                

                def read(self)
                 ‑> str
            
            
    
    
        
            open_in_new

Return the given content or read file from path.

Inherited members
                    
                        class Rule
                    
                    
    
    
        
            open_in_new

Rule is a base class for rules definitions.

Method generated by attrs for class Rule.

Ancestors
Subclasses
Static methods
            
                

                def fromany(x: Any)
                 ‑> Any
            
            
    
    
        
            open_in_new

Convert any object to rule.

            
                

                def fromdict(x: Dict[str, Any])
                 ‑> Any
            
            
    
    
        
            open_in_new

Convert dict to rule subclass.

            
                

                def fromargs(**x: Any)
                 ‑> Any
            
            
    
    
        
            open_in_new

Convert args to rule subclass.

Methods
            
                

                def findall(self, s: str)
                 ‑> List[str]
            
            
    
    
        
            open_in_new

Find all substrings matching rule.

Inherited members
                    
                        class Entropy(

                            id: str = 'high-entropy',

                            message: str = 'High Entropy',

                            severity=MEDIUM,

                            alphabet: Optional[str] = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789+/=',

                            threshold: Optional[float] = 4.5,

                            minlen: Optional[int] = 20,

                        )
                    
                    
    
    
        
            open_in_new

Entropy is used for detecting high entropy strings.

Attributes

id (str)
Rule ID, should be unique.
message (str)
Short explanation of what is matched by the rule.
severity (Severity)
Severity of issues detected by the rule.

Args

alphabet (str, optional)
Alphabet to search characters from.
threshold (float, optional)
Shannon entropy threshold.
minlen (int, optional)
Minimum match length.

Examples

There are two ways to customize high entropy check. The easiest one is to set custom minimum length for matched strings. The other way is to set custom alphabets and/or thresholds for them.

>>> BASE32_CHARS = string.ascii_letters + "234567="
>>> rule = Entropy(
...     alphabet=BASE32_CHARS,
...     threshold=3.75,
...     minlen=10,
... )
>>> rule.findall("password = 'irtksdajfhaeu356'")
['irtksdajfhaeu356']

Method generated by attrs for class Entropy.

Ancestors
Class variables
var id : str
var message : str
var severity : Optional[Severity]
Methods
            
                

                def findall(self, s: str)
                 ‑> List[str]
            
            
    
    
        
            open_in_new

Find high entropy substring occurrences in the string.

Examples

Basic usage examples. The first match here is from base64 alphabet and the second one exceeded defined hexadecimal entropy threshold.

>>> rule = Entropy()
>>> rule.findall("token = 'abcdefghijklmnopqrstuvwxyz'")
['abcdefghijklmnopqrstuvwxyz']

>>> rule = Entropy(
...     alphabet=HEX_CHARS,
...     threshold=HEX_LIMIT,
...     minlen=10,
... )
>>> rule.findall("password = '1234567890'")
['1234567890']
Inherited members
                    
                        class Pattern(

                            id: str,

                            message: str,

                            pattern: str,

                            severity=MEDIUM,

                        )
                    
                    
    
    
        
            open_in_new

Pattern holds all neccessary metadata for pattern-based rule definition.

Attributes

id (str)
Rule ID, should be unique.
message (str)
Short explanation of what is matched by the rule.
pattern (Pattern)
Python re.Pattern to search for.
severity (Severity, optional)
Severity of issues detected by the rule.

Examples

Match letmein string everywhere

>>> rule = Pattern(
...     id="bad-password-letmein",
...     message="Bad Password 'letmein'",
...     pattern="letmein",
...     severity="high",
... )

Match letmein Python re.Pattern, case-insensitive

>>> rule = Pattern(
...     id="bad-password-letmein",
...     message="Bad Password 'letmein'",
...     pattern="(?i)letmein",
...     severity="high",
... )

Method generated by attrs for class Pattern.

Ancestors
Class variables
var id : str
var message : str
var pattern : str
var severity : Optional[Severity]
Methods
            
                

                def findall(self, s: str)
                 ‑> List[str]
            
            
    
    
        
            open_in_new

Find pattern occurrences in the string.

Examples

Basic usage examples

>>> rule = Pattern(
...     id="bad-password-letmein",
...     message="Bad Password 'letmein'",
...     pattern="letmein",
...     severity="high",
... )
>>> rule.findall("password = 'letmein'")
['letmein']
Inherited members
                    
                        class Exclude(

                            message: str,

                            id: Optional[str] = None,

                            pattern=None,

                            paths: Optional[List[str]] = None,

                        )
                    
                    
    
    
        
            open_in_new

Exclude is used for referencing rules in configuration exclude list.

Attributes

message (str)
Short explanation of what is matched by the rule.
id (str, optional)
Rule ID, should be unique.
pattern (Pattern, optional)
Python re.Pattern to search for.
paths (List[str], optional)
File paths for rule to be applied on, defaults to everywhere. Each item should be a glob pattern as recognized by pathlib.Path.match.

Note

Only one of id, pattern must be set.

If paths is set, exclude will only be applied on the specified paths.

Examples

Skip rule by its ID, but only in YAML files

>>> rule = Exclude(
...     id="bad-password.letmein",
...     message="Not Password 'letmein'",
...     paths=["*.yaml", "*.yml"],
... )

Skip lines containing letmein string

>>> rule = Exclude(
...     message="Not Password 'letmein'",
...     pattern="letmein",
... )

Skip lines containing letmein Python re.Pattern, case-insensitive

>>> rule = Exclude(
...     message="Not Password 'letmein'",
...     pattern="(?i)letmein",
... )

Method generated by attrs for class Exclude.

Ancestors
Class variables
var message : str
var id : Optional[str]
var pattern : Optional[re.Pattern]
var paths : Optional[List[str]]
Static methods
            
                

                def fromany(x: Any)
                 ‑> Any
            
            
    
    
        
            open_in_new

Convert any object to exclude rule.

            
                

                def fromdict(x: Dict[str, Any])
                 ‑> Any
            
            
    
    
        
            open_in_new

Convert dict to exclude rule.

Methods
            
                

                def findall(self, s: str)
                 ‑> List[str]
            
            
    
    
        
            open_in_new

Find pattern occurrences in the string.

Inherited members
                    
                        class Context(*args, **kwargs)
                    
                    
    
    
        
            open_in_new

Dumb workaround for dict being unhashable by default.

Note

It is only intended to be used as context property for models.Issue, which uses its own hashing algorithm.

Ancestors
  • builtins.dict
                    
                        class Issue(

                            rule,

                            path: str,

                            line: str,

                            secret: str,

                            context,

                            id: Optional[uuid.UUID] = NOTHING,

                            branch: Optional[str] = None,

                            message: Optional[str] = None,

                            author: Optional[str] = None,

                            commit: Optional[str] = None,

                            date: Optional[datetime.datetime] = None,

                        )
                    
                    
    
    
        
            open_in_new

Issue holds finding metadata.

Attributes

rule (Rule):
Rule the issue was detected by.
path (str):
File path.
line (int):
Line number of the matched line. For Git history this is the line number in diff blob, not the real one.
secret (str):
String matched by the rule.
context (str):
Code lines containing secret matched by the rule.
id (str, optional):
Issue ID. Generated automatically from path, secret and rule UUID.
branch (str, optional)
Git commit branch.
message (str, optional)
Git commit message.
author (str, optional)
Git commit author as name <email>.
commit (str, optional)
Git commit hash.
date (datetime.datetime, optional)
Git commit timestamp.

Examples

Basic usage examples

>>> rule = Pattern(
...     id="bad-password-letmein",
...     message="Bad Password 'letmein'",
...     pattern="letmein",
...     severity="high",
... )
>>> issue = Issue(
...     rule=rule,
...     path="/path/to/code.py",
...     line="10",
...     secret="letmein",
...     context={
...         "9":  "username = 'admin'",
...         "10": "password = 'letmein'",
...         "11": "response = authorize(username, password)",
...     },
... )
>>> issue.id
UUID('bfd860e4-2002-30dd-a1b1-24e29083c7d5')

Method generated by attrs for class Issue.

Ancestors
Class variables
var rule : Rule
var path : str
var line : str
var secret : str
var context : Context
var id : Optional[uuid.UUID]
var branch : Optional[str]
var message : Optional[str]
var author : Optional[str]
var commit : Optional[str]
var date : Optional[datetime.datetime]
Instance variables
var multiline : bool

Return true if context contains multiple lines.

var lines : List[int]

Return context keys containing line numbers.

var line_start : int

Return first context line number.

var line_end : int

Return last context line number.

Inherited members
                    
                        class Config(

                            exclude=None,

                            severity=LOW,

                            ignore_nosecret: Optional[bool] = False,

                            no_entropy: Optional[bool] = False,

                            no_pattern: Optional[bool] = False,

                            branch: Optional[str] = None,

                            depth: Optional[int] = 10000,

                            since: Optional[str] = None,

                            no_current: Optional[bool] = False,

                            no_history: Optional[bool] = False,

                            context: Optional[int] = 0,

                        )
                    
                    
    
    
        
            open_in_new

Config holds all configuration.

Method generated by attrs for class Config.

Ancestors
Class variables
var exclude : Optional[List[Exclude]]
var severity : Optional[Severity]
var ignore_nosecret : Optional[bool]
var no_entropy : Optional[bool]
var no_pattern : Optional[bool]
var branch : Optional[str]
var depth : Optional[int]
var since : Optional[str]
var no_current : Optional[bool]
var no_history : Optional[bool]
var context : Optional[int]
Inherited members