API Reference
File Security Module.
A comprehensive file security system for validating uploads and preventing attacks.
AuditEvent
dataclass
A structured security audit event.
Attributes:
| Name | Type | Description |
|---|---|---|
event_type |
AuditEventType
|
Category of the audit event. |
correlation_id |
str
|
Unique ID linking related events. |
filename |
str
|
Name of the file being validated. |
result |
str
|
Outcome description. |
details |
str
|
Additional context information. |
duration_ms |
float
|
Elapsed time in milliseconds. |
source_ip |
str | None
|
Optional client IP address. |
timestamp |
float
|
Monotonic time when event was created. |
Source code in safeuploads/audit.py
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 | |
AuditEventType
Bases: Enum
Types of security audit events.
Attributes:
| Name | Type | Description |
|---|---|---|
VALIDATION_START |
Validation process started. |
|
VALIDATION_SUCCESS |
Validation completed successfully. |
|
VALIDATION_FAILURE |
Validation failed with error. |
|
THREAT_DETECTED |
Security threat detected. |
|
RESOURCE_LIMIT |
Resource limit exceeded. |
Source code in safeuploads/audit.py
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 | |
BaseInspector
Base class for file content inspectors.
Centralizes storage of the security configuration and the shared audit logger used by all inspectors.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
File security configuration. |
Source code in safeuploads/inspectors/base.py
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | |
__init__
__init__(config)
Initialize the inspector with configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FileSecurityConfig
|
File security configuration. |
required |
Source code in safeuploads/inspectors/base.py
24 25 26 27 28 29 30 31 32 33 34 | |
BaseValidator
Bases: ABC
Abstract base class for file security validators.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
File security configuration parameters. |
Source code in safeuploads/validators/base.py
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | |
__init__
__init__(config)
Initialize validator with configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FileSecurityConfig
|
File security settings to apply. |
required |
Source code in safeuploads/validators/base.py
22 23 24 25 26 27 28 29 30 31 32 | |
validate
abstractmethod
validate(*args, **kwargs)
Validate data using subclass-specific logic.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*args
|
Any
|
Positional arguments for concrete validator. |
()
|
**kwargs
|
Any
|
Keyword arguments for concrete validator. |
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
Validated result defined by subclass. |
Source code in safeuploads/validators/base.py
34 35 36 37 38 39 40 41 42 43 44 45 | |
BinaryFileCategory
Bases: Enum
Enumeration of binary file categories.
Attributes:
| Name | Type | Description |
|---|---|---|
FITNESS_FILES |
Fitness/activity binary file extensions (e.g., '.fit'). |
Source code in safeuploads/enums.py
6 7 8 9 10 11 12 13 14 15 16 | |
CompoundExtensionCategory
Bases: Enum
Categorized compound file extensions that combine multiple suffixes.
Attributes:
| Name | Type | Description |
|---|---|---|
COMPRESSED_ARCHIVES |
Multi-part archive formats. |
|
JAVASCRIPT_VARIANTS |
Specialized JavaScript files. |
|
WEB_CONTENT |
Minified static web assets. |
Source code in safeuploads/enums.py
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 | |
CompressionSecurityError
Bases: FileValidationError
Compressed file security check failed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
filename
|
str | None
|
Optional filename of compressed file. |
None
|
error_code
|
str | None
|
Optional machine-readable error code (defaults to ZIP_INVALID_STRUCTURE). |
None
|
Source code in safeuploads/exceptions.py
476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 | |
__init__
__init__(message, filename=None, error_code=None)
Initialize with message and filename.
Source code in safeuploads/exceptions.py
487 488 489 490 491 492 493 494 495 496 497 498 | |
CompressionSecurityValidator
Bases: BaseValidator
Validates ZIP uploads against zip bombs and compression attacks.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
Security configuration for validation limits. |
Source code in safeuploads/validators/compression_validator.py
559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 | |
__init__
__init__(config)
Initialize the compression validator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FileSecurityConfig
|
Security configuration with compression limits. |
required |
Source code in safeuploads/validators/compression_validator.py
567 568 569 570 571 572 573 574 575 576 577 | |
validate
validate(file_obj, compressed_size)
Validate the compression ratio of a ZIP file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_obj
|
SeekableFile
|
Seekable file-like object of the ZIP. |
required |
compressed_size
|
int
|
Size of the file after compression in bytes. |
required |
Raises:
| Type | Description |
|---|---|
ZipBombError
|
If compression ratio exceeds maximum. |
CompressionSecurityError
|
If ZIP structure is invalid. |
FileProcessingError
|
If unexpected error occurs. |
Source code in safeuploads/validators/compression_validator.py
1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 | |
validate_zip_compression_ratio
validate_zip_compression_ratio(file_obj, compressed_size)
Validate ZIP archive against security limits.
The central-directory records are counted, reading only
their fixed headers, before zipfile parses them, so an
archive with too many entries is rejected at bounded cost;
the parsed count is checked again after parsing.
Once the declared sizes pass, the listed entries, the
central directory and the end records must fill the file
exactly, with no gap, overlap, prepended or trailing bytes,
and each local header must agree with its directory entry.
Size and ratio checks read the declared file_size and
compress_size from the archive's central directory,
which an attacker can forge. Enable
limits.verify_zip_decompression to additionally
decompress every entry and reject archives whose real
content does not match the declared metadata.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_obj
|
SeekableFile
|
Seekable file-like object containing ZIP data. |
required |
compressed_size
|
int
|
Size of the compressed archive in bytes. |
required |
Raises:
| Type | Description |
|---|---|
ZipBombError
|
If compression ratio exceeds maximum allowed or total uncompressed size is too large. |
CompressionSecurityError
|
If ZIP structure is invalid (including bytes outside the listed entries and a directory entry that declares file data), too many entries, nested archives detected, or individual file too large. |
ResourceLimitError
|
If the active resource monitor's time or memory limit is exceeded. |
FileProcessingError
|
If unexpected error occurs during validation such as memory errors or I/O errors. |
Source code in safeuploads/validators/compression_validator.py
579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 | |
ConfigValidationIssue
dataclass
Configuration validation issue with severity and recommendation.
A plain record, not an exception: validate_instance() and
validate_configuration() return a list of them, and
FileSecurityConfigurationError.errors carries them.
Attributes:
| Name | Type | Description |
|---|---|---|
error_type |
str
|
Type of the validation error. |
message |
str
|
Human-readable error message. |
severity |
str
|
Error severity level ('error', 'warning', 'info'). |
component |
str
|
Component that failed validation. |
recommendation |
str
|
Optional recommendation to fix the issue. |
Source code in safeuploads/exceptions.py
11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | |
ContentSecurityInspector
Bases: BaseInspector
Scans file content for embedded malware and scripts.
Three detection layers: 1. Executable signatures — PE, ELF, Mach-O, Java class headers in files that should not be executables. 2. Script injection — Common web shell and script markers in non-script files. 3. Polyglot detection — Secondary format signatures (ZIP/JAR, RAR, Java class) embedded after a valid image or document header.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
File security configuration. |
Source code in safeuploads/inspectors/content_inspector.py
185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 | |
__init__
__init__(config)
Initialize the content inspector.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FileSecurityConfig
|
File security configuration. |
required |
Source code in safeuploads/inspectors/content_inspector.py
202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 | |
scan_content
scan_content(content, filename='', expected_type='')
Scan file content for embedded threats.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
content
|
bytes
|
Raw bytes to inspect (typically the
first |
required |
filename
|
str
|
Original filename for context. |
''
|
expected_type
|
str
|
Logical file type the content should represent (e.g. "image", "zip"). |
''
|
Returns:
| Type | Description |
|---|---|
list[str]
|
List of threat descriptions found. Empty list |
list[str]
|
means content is clean. |
Source code in safeuploads/inspectors/content_inspector.py
221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 | |
ContentThreatError
Bases: FileValidationError
Content analysis found threats in the file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
filename
|
str | None
|
Optional name of the file with the threats. |
None
|
threats
|
list[str] | None
|
Optional list of detected threat descriptions. |
None
|
error_code
|
str | None
|
Optional error code (defaults to CONTENT_THREAT_DETECTED). |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
threats |
List of detected threat descriptions. |
Source code in safeuploads/exceptions.py
629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 | |
__init__
__init__(
message, filename=None, threats=None, error_code=None
)
Initialize with threat details.
Source code in safeuploads/exceptions.py
644 645 646 647 648 649 650 651 652 653 654 655 656 657 | |
DangerousExtensionCategory
Bases: Enum
File extension categories considered potentially dangerous for uploads.
Attributes:
| Name | Type | Description |
|---|---|---|
WINDOWS_EXECUTABLES |
Traditional Windows executable formats. |
|
SCRIPT_FILES |
Script files that can execute code. |
|
WEB_SCRIPTS |
Web server and dynamic content scripts. |
|
UNIX_EXECUTABLES |
Unix/Linux executables and shell scripts. |
|
MACOS_EXECUTABLES |
macOS specific executables and applications. |
|
JAVA_EXECUTABLES |
Java related executables and bytecode. |
|
MOBILE_APPS |
Mobile application packages. |
|
BROWSER_EXTENSIONS |
Browser extensions and web applications. |
|
PACKAGE_FORMATS |
Modern package managers and distribution formats. |
|
ARCHIVE_FORMATS |
Archive formats that can contain executables. |
|
VIRTUALIZATION_FORMATS |
Virtualization and container formats. |
|
OFFICE_MACROS |
Office documents with macro capabilities. |
|
SYSTEM_FILES |
System shortcuts and configuration files. |
|
SYSTEM_DRIVERS |
System drivers and low-level components. |
|
WINDOWS_THEMES |
Windows theme and customization files. |
|
HELP_FILES |
Help and documentation files that can execute code. |
Source code in safeuploads/enums.py
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 | |
ErrorCode
Bases: StrEnum
Machine-readable error codes for file validation failures.
Error codes are string-valued enum members grouped by
validation failure type (filename, extension, MIME, size,
signature, image dimension, XML, PDF, compression, resource,
and processing). As a StrEnum each member compares equal to
its string value, so existing string comparisons and JSON
serialization keep working unchanged.
Source code in safeuploads/exceptions.py
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 | |
ExtensionSecurityError
Bases: FilenameSecurityError
Dangerous file extension detected.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
filename
|
str | None
|
Optional filename with dangerous extension. |
None
|
extension
|
str | None
|
Optional specific extension that was blocked. |
None
|
error_code
|
str | None
|
Optional error code (defaults to EXTENSION_BLOCKED). |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
extension |
The specific extension that was blocked. |
Source code in safeuploads/exceptions.py
268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 | |
__init__
__init__(
message, filename=None, extension=None, error_code=None
)
Initialize with blocked extension.
Source code in safeuploads/exceptions.py
283 284 285 286 287 288 289 290 291 292 293 294 295 296 | |
ExtensionSecurityValidator
Bases: BaseValidator
Validates filenames against configured forbidden extensions.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
File security configuration settings. |
Source code in safeuploads/validators/extension_validator.py
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 | |
__init__
__init__(config)
Initialize the validator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FileSecurityConfig
|
File security configuration settings. |
required |
Source code in safeuploads/validators/extension_validator.py
31 32 33 34 35 36 37 38 39 40 41 42 43 | |
validate
validate(filename)
Validate the given filename.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
Name of the file to validate. |
required |
Raises:
| Type | Description |
|---|---|
ExtensionSecurityError
|
If filename extension is not permitted. |
Source code in safeuploads/validators/extension_validator.py
165 166 167 168 169 170 171 172 173 174 175 176 | |
validate_allowed
validate_allowed(filename, allowed_extensions)
Validate a filename extension against allowed and blocked lists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str | None
|
Name of the file whose extension is checked. |
required |
allowed_extensions
|
frozenset[str]
|
Set of allowed file extensions. |
required |
Raises:
| Type | Description |
|---|---|
FilenameSecurityError
|
Filename is missing. |
ExtensionSecurityError
|
Extension is missing, not allowed or blocked. |
Source code in safeuploads/validators/extension_validator.py
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 | |
validate_extensions
validate_extensions(filename)
Validate filename against blocked extensions.
Trailing dots and spaces are ignored, because Windows drops
them when it saves a file, so run.exe . is checked as
run.exe.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
Name of the file to validate. |
required |
Raises:
| Type | Description |
|---|---|
ExtensionSecurityError
|
If blocked compound or single extension detected in filename. |
Source code in safeuploads/validators/extension_validator.py
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 | |
FileProcessingError
Bases: FileSecurityError
Unexpected processing error during file validation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
original_error
|
Exception | None
|
Optional original exception that was caught. |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
original_error |
The original exception that was caught. |
Source code in safeuploads/exceptions.py
665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 | |
__init__
__init__(message, original_error=None)
Initialize with original error.
Source code in safeuploads/exceptions.py
677 678 679 680 | |
FileSecurityConfig
Centralizes file upload security settings and validation.
Attributes:
| Name | Type | Description |
|---|---|---|
limits |
Security limits configuration instance. |
|
ALLOWED_IMAGE_TYPES |
Mapping[str, frozenset[str]]
|
Permitted image MIME types, each mapped to the extensions its content may carry. |
ALLOWED_ZIP_TYPES |
Mapping[str, frozenset[str]]
|
Permitted ZIP MIME types and extensions. |
ALLOWED_ACTIVITY_TYPES |
Mapping[str, frozenset[str]]
|
Permitted activity file (GPX/TCX/FIT) MIME types and extensions. |
ALLOWED_GZIP_TYPES |
Mapping[str, frozenset[str]]
|
Permitted gzip MIME types and extensions. |
ALLOWED_PDF_TYPES |
Mapping[str, frozenset[str]]
|
Permitted PDF MIME types and extensions. |
BLOCKED_PDF_NAMES |
frozenset[str]
|
PDF names, without the leading "/", that reject a PDF wherever they occur outside strings, comments and stream data. |
BLOCKED_EXTENSIONS |
frozenset[str]
|
Dangerous file extensions to block. |
COMPOUND_BLOCKED_EXTENSIONS |
frozenset[str]
|
Multi-part extensions to block. |
DANGEROUS_UNICODE_CHARS |
frozenset[int]
|
Unicode characters for filename attacks. |
WINDOWS_RESERVED_NAMES |
frozenset[str]
|
Platform-specific reserved filenames. |
Source code in safeuploads/config.py
200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 | |
__init__
__init__()
Create a config instance with isolated mutable state.
Copies the class-level limits so mutating one
instance's limits never affects other instances or
the shared class default.
Source code in safeuploads/config.py
405 406 407 408 409 410 411 412 413 414 | |
__init_subclass__
classmethod
__init_subclass__(**kwargs)
Validate configuration on subclass creation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
**kwargs
|
Any
|
Subclass initialization arguments. |
{}
|
Source code in safeuploads/config.py
417 418 419 420 421 422 423 424 425 426 427 428 429 430 | |
get_compound_extensions_by_category
classmethod
get_compound_extensions_by_category(category)
Return compound extensions for a category.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
category
|
CompoundExtensionCategory
|
The compound extension category. |
required |
Returns:
| Type | Description |
|---|---|
set[str]
|
Mutable copy of compound extensions in the specified category. |
Source code in safeuploads/config.py
447 448 449 450 451 452 453 454 455 456 457 458 459 460 | |
get_extension_category
classmethod
get_extension_category(extension)
Return the dangerous extension category for an extension.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
extension
|
str
|
The file extension to evaluate. |
required |
Returns:
| Type | Description |
|---|---|
DangerousExtensionCategory | None
|
Matching category if dangerous, None otherwise. |
Source code in safeuploads/config.py
493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 | |
get_extensions_by_category
classmethod
get_extensions_by_category(category)
Return extensions for a dangerous extension category.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
category
|
DangerousExtensionCategory
|
The dangerous extension category. |
required |
Returns:
| Type | Description |
|---|---|
set[str]
|
Mutable copy of extensions in the specified category. |
Source code in safeuploads/config.py
432 433 434 435 436 437 438 439 440 441 442 443 444 445 | |
get_unicode_chars_by_category
classmethod
get_unicode_chars_by_category(category)
Return Unicode code points for an attack category.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
category
|
UnicodeAttackCategory
|
The Unicode attack category. |
required |
Returns:
| Type | Description |
|---|---|
set[int]
|
Mutable copy of code points in the specified category. |
Source code in safeuploads/config.py
462 463 464 465 466 467 468 469 470 471 472 473 474 475 | |
is_extension_in_category
classmethod
is_extension_in_category(extension, category)
Check if extension belongs to a dangerous category.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
extension
|
str
|
File extension to evaluate. |
required |
category
|
DangerousExtensionCategory
|
Category to check against. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if extension is in the category, False otherwise. |
Source code in safeuploads/config.py
477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 | |
validate_and_report
classmethod
validate_and_report(strict=True)
Validate the class-level configuration and log outcomes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
If True, raise on errors/warnings. |
True
|
Raises:
| Type | Description |
|---|---|
FileSecurityConfigurationError
|
If strict and issues found. |
Source code in safeuploads/config.py
1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 | |
validate_and_report_instance
validate_and_report_instance(strict=True)
Validate this instance's configuration and log outcomes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
If True, raise on errors/warnings. |
True
|
Raises:
| Type | Description |
|---|---|
FileSecurityConfigurationError
|
If strict and issues found. |
Source code in safeuploads/config.py
1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 | |
validate_configuration
classmethod
validate_configuration()
Validate the class-level default configuration.
Returns:
| Type | Description |
|---|---|
list[ConfigValidationIssue]
|
List of detected validation errors. |
Source code in safeuploads/config.py
512 513 514 515 516 517 518 519 520 | |
validate_instance
validate_instance()
Validate this instance's configuration.
Validates the per-instance limits and the instance's
MIME, extension, reserved-name and Unicode sets, so a
customized instance is checked instead of the class
default.
Returns:
| Type | Description |
|---|---|
list[ConfigValidationIssue]
|
List of detected validation errors. |
Source code in safeuploads/config.py
522 523 524 525 526 527 528 529 530 531 532 533 534 | |
FileSecurityConfigurationError
Bases: Exception
Configuration validation failed with aggregated errors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
errors
|
list[ConfigValidationIssue]
|
List of ConfigValidationIssue instances. |
required |
Attributes:
| Name | Type | Description |
|---|---|---|
errors |
List of validation errors that caused failure. |
Source code in safeuploads/exceptions.py
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | |
__init__
__init__(errors)
Initialize with validation errors.
Source code in safeuploads/exceptions.py
46 47 48 49 50 51 52 53 54 | |
__reduce__
__reduce__()
Rebuild from errors so pickling round-trips.
Source code in safeuploads/exceptions.py
56 57 58 | |
FileSecurityError
Bases: Exception
Base exception for all file security validation failures.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
error_code
|
str | None
|
Optional machine-readable error code (defaults to PROCESSING_ERROR). |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
message |
Human-readable error message. |
|
error_code |
Machine-readable error code from ErrorCode. |
Source code in safeuploads/exceptions.py
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 | |
__init__
__init__(message, error_code=None)
Initialize with message and error code.
Source code in safeuploads/exceptions.py
173 174 175 176 177 | |
FileSignatureError
Bases: FileValidationError
File header signature invalid or mismatched.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
filename
|
str | None
|
Optional filename with signature issue. |
None
|
expected_type
|
str | None
|
Optional expected file type based on extension. |
None
|
error_code
|
str | None
|
Optional error code (defaults to FILE_SIGNATURE_MISMATCH). |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
expected_type |
The expected file type based on extension. |
Source code in safeuploads/exceptions.py
401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 | |
__init__
__init__(
message,
filename=None,
expected_type=None,
error_code=None,
)
Initialize with expected type.
Source code in safeuploads/exceptions.py
416 417 418 419 420 421 422 423 424 425 426 427 428 429 | |
FileSignatureValidator
Bases: BaseValidator
Checks the leading bytes of a file against its expected type.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
File security configuration settings. |
Source code in safeuploads/validators/signature_validator.py
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 | |
__init__
__init__(config)
Initialize the validator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FileSecurityConfig
|
File security configuration settings. |
required |
Source code in safeuploads/validators/signature_validator.py
81 82 83 84 85 86 87 88 | |
validate
validate(content, expected_type, *, filename=None)
Verify content begins with a known signature for the type.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
content
|
bytes
|
Leading bytes of the uploaded file. |
required |
expected_type
|
str
|
Logical file category ("image", "zip", "gzip", "activity", "fit" or "pdf"). |
required |
filename
|
str | None
|
Optional sanitized filename for error context. |
None
|
Raises:
| Type | Description |
|---|---|
FileSignatureError
|
Content is too short or its header does not match the expected type. |
Source code in safeuploads/validators/signature_validator.py
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 | |
FileSizeError
Bases: FileValidationError
File exceeds configured size limits.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
filename
|
str | None
|
Optional filename that exceeded size limits. |
None
|
size
|
int | None
|
Optional actual file size in bytes. |
None
|
max_size
|
int | None
|
Optional maximum allowed size in bytes. |
None
|
error_code
|
str | None
|
Optional error code (defaults to FILE_TOO_LARGE). |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
size |
The actual file size in bytes. |
|
max_size |
The maximum allowed size in bytes. |
Source code in safeuploads/exceptions.py
332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 | |
__init__
__init__(
message,
filename=None,
size=None,
max_size=None,
error_code=None,
)
Initialize with size details.
Source code in safeuploads/exceptions.py
348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 | |
FileValidationError
Bases: FileSecurityError
File validation failed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
filename
|
str | None
|
Optional name of the file that failed validation. |
None
|
error_code
|
str | None
|
Optional machine-readable error code (defaults to VALIDATION_FAILED). |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
filename |
Name of the file that failed validation. |
Source code in safeuploads/exceptions.py
185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 | |
__init__
__init__(message, filename=None, error_code=None)
Initialize with message and filename.
Source code in safeuploads/exceptions.py
199 200 201 202 203 204 205 206 207 | |
FileValidator
Coordinated security validation for uploaded files.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
Active security configuration. |
|
unicode_validator |
Validator for Unicode-related checks. |
|
extension_validator |
Validator for file extension rules. |
|
windows_validator |
Validator enforcing Windows-specific constraints. |
|
compression_validator |
Validator handling compressed file limits. |
|
zip_inspector |
Inspector for ZIP archive contents. |
|
pdf_inspector |
Inspector for PDF structure and active content. |
|
filename_validator |
Validator for path and length rules. |
|
signature_validator |
Validator for file header signatures. |
|
mime_validator |
Validator for content MIME detection. |
|
magic_mime |
Magic
|
MIME type detector of the MIME validator. |
magic_available |
bool
|
Whether python-magic was successfully initialized. |
Source code in safeuploads/file_validator.py
108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 | |
magic_available
property
writable
magic_available
Whether python-magic initialized successfully.
magic_mime
property
writable
magic_mime
MIME type detector owned by the MIME validator.
__init__
__init__(config=None, executor=None)
Initialize file validator with configuration and detection utilities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FileSecurityConfig | None
|
Optional configuration object defining file security rules. Defaults to new FileSecurityConfig instance. |
None
|
executor
|
Executor | None
|
Optional executor used by the async
|
None
|
Raises:
| Type | Description |
|---|---|
FileSecurityConfigurationError
|
If the configuration has any error-severity issue. |
Attributes:
| Name | Type | Description |
|---|---|---|
config |
Active security configuration. |
|
unicode_validator |
Validator for Unicode-related checks. |
|
extension_validator |
Validator for file extension rules. |
|
windows_validator |
Validator enforcing Windows constraints. |
|
compression_validator |
Validator for compressed file limits. |
|
zip_inspector |
Inspector for ZIP archive contents. |
|
pdf_inspector |
Inspector for PDF structure and content. |
|
filename_validator |
Validator for path and length rules. |
|
signature_validator |
Validator for file header signatures. |
|
mime_validator |
Validator for content MIME detection. |
|
magic_mime |
MIME type detector of the MIME validator. |
|
magic_available |
Whether python-magic initialized successfully. |
Source code in safeuploads/file_validator.py
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 | |
validate_activity_file
async
validate_activity_file(file)
Validate uploaded activity file (GPX, TCX, FIT).
For XML-based formats (GPX/TCX) performs XXE-safe
parsing via defusedxml. For FIT files validates
the binary signature.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
UploadFileProtocol
|
Uploaded activity file to validate. |
required |
Raises:
| Type | Description |
|---|---|
FilenameSecurityError
|
Filename fails security. |
ExtensionSecurityError
|
Extension not allowed. |
FileSizeError
|
File exceeds size limit or empty. |
MimeTypeError
|
MIME type not allowed, or the extension is not one listed for it. |
FileSignatureError
|
Signature mismatch. |
XmlSecurityError
|
The XML is forbidden or malformed. |
FileProcessingError
|
Unexpected error during validation. |
Source code in safeuploads/file_validator.py
1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 | |
validate_activity_file_sync
validate_activity_file_sync(file, filename)
Validate an activity file from a seekable file in this thread.
Runs the same checks, in the same order, as
validate_activity_file. It blocks, so it cannot run on an
event loop thread; await validate_activity_file() or run
this in a worker thread. The file is rewound to position 0
on success and is never closed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
SeekableFile
|
Seekable binary file to validate. |
required |
filename
|
str
|
Filename supplied by the client. |
required |
Returns:
| Type | Description |
|---|---|
ValidationResult
|
Sanitized filename and detected MIME type. |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
Called on a thread running an event loop. |
FilenameSecurityError
|
Filename fails security. |
ExtensionSecurityError
|
Extension not allowed. |
FileSizeError
|
File exceeds size limit or empty. |
MimeTypeError
|
MIME type not allowed, or the extension is not one listed for it. |
FileSignatureError
|
Signature mismatch. |
XmlSecurityError
|
The XML is forbidden or malformed. |
FileProcessingError
|
Unexpected error during validation. |
Source code in safeuploads/file_validator.py
1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 | |
validate_gzip_file
async
validate_gzip_file(file)
Validate uploaded gzip archive.
Checks filename, extension, size, MIME type, signature, and performs decompression bomb detection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
UploadFileProtocol
|
Uploaded gzip file to validate. |
required |
Raises:
| Type | Description |
|---|---|
FilenameSecurityError
|
Filename fails security. |
ExtensionSecurityError
|
Extension not allowed. |
FileSizeError
|
File exceeds size limit or empty. |
MimeTypeError
|
MIME type not allowed, or the extension is not one listed for it. |
FileSignatureError
|
Signature mismatch. |
ZipBombError
|
Decompression bomb detected. |
CompressionSecurityError
|
Invalid gzip structure. |
FileProcessingError
|
Unexpected error. |
Source code in safeuploads/file_validator.py
1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 | |
validate_gzip_file_sync
validate_gzip_file_sync(file, filename)
Validate a gzip archive from a seekable file in this thread.
Runs the same checks, in the same order, as
validate_gzip_file. It blocks, so it cannot run on an
event loop thread; await validate_gzip_file() or run
this in a worker thread. The file is rewound to position 0
on success and is never closed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
SeekableFile
|
Seekable binary file to validate. |
required |
filename
|
str
|
Filename supplied by the client. |
required |
Returns:
| Type | Description |
|---|---|
ValidationResult
|
Sanitized filename and detected MIME type. |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
Called on a thread running an event loop. |
FilenameSecurityError
|
Filename fails security. |
ExtensionSecurityError
|
Extension not allowed. |
FileSizeError
|
File exceeds size limit or empty. |
MimeTypeError
|
MIME type not allowed, or the extension is not one listed for it. |
FileSignatureError
|
Signature mismatch. |
ZipBombError
|
Decompression bomb detected. |
CompressionSecurityError
|
Invalid gzip structure. |
FileProcessingError
|
Unexpected error during validation. |
Source code in safeuploads/file_validator.py
1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 | |
validate_image_file
async
validate_image_file(file)
Validate an uploaded PNG, JPEG, WebP or HEIC image.
Checks filename, extension, size, MIME type, signature and the pixel count the image header declares, then runs the optional content scan.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
UploadFileProtocol
|
Uploaded file to validate. |
required |
Returns:
| Type | Description |
|---|---|
ValidationResult
|
Sanitized filename and detected MIME type. |
Raises:
| Type | Description |
|---|---|
FilenameSecurityError
|
Filename is empty, invalid, or fails security checks. |
ExtensionSecurityError
|
File extension is not allowed or is blocked. |
FileSizeError
|
File size exceeds maximum or file is empty. |
MimeTypeError
|
MIME type is not in allowed image types, or the extension is not one listed for it. |
FileSignatureError
|
File signature doesn't match expected image format, or the dimension header is missing or invalid. |
ImageDimensionError
|
The image header declares more than
|
ContentThreatError
|
Content analysis found threats. |
FileProcessingError
|
Unexpected error during validation. |
Source code in safeuploads/file_validator.py
816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 | |
validate_image_file_sync
validate_image_file_sync(file, filename)
Validate an image from a seekable file in the calling thread.
Runs the same checks, in the same order, as
validate_image_file. It blocks, so it cannot run on an
event loop thread; await validate_image_file() or run
this in a worker thread. The file is rewound to position 0
on success and is never closed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
SeekableFile
|
Seekable binary file to validate. |
required |
filename
|
str
|
Filename supplied by the client. |
required |
Returns:
| Type | Description |
|---|---|
ValidationResult
|
Sanitized filename and detected MIME type. |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
Called on a thread running an event loop. |
FilenameSecurityError
|
Filename is empty, invalid, or fails security checks. |
ExtensionSecurityError
|
File extension is not allowed or is blocked. |
FileSizeError
|
File size exceeds maximum or file is empty. |
MimeTypeError
|
MIME type is not in allowed image types, or the extension is not one listed for it. |
FileSignatureError
|
File signature doesn't match expected image format, or the dimension header is missing or invalid. |
ImageDimensionError
|
The image header declares more than
|
ContentThreatError
|
Content analysis found threats. |
FileProcessingError
|
Unexpected error during validation. |
Source code in safeuploads/file_validator.py
854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 | |
validate_pdf_file
async
validate_pdf_file(file)
Validate an uploaded PDF document.
Checks filename, extension, size, MIME type and signature, then the PDF structure, encryption, blocked names and decoded stream size, and runs the optional content scan.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
UploadFileProtocol
|
Uploaded PDF to validate. |
required |
Returns:
| Type | Description |
|---|---|
ValidationResult
|
Sanitized filename and detected MIME type. |
Raises:
| Type | Description |
|---|---|
FilenameSecurityError
|
Filename fails security. |
ExtensionSecurityError
|
Extension not allowed. |
FileSizeError
|
File exceeds size limit or empty. |
MimeTypeError
|
MIME type not allowed, or the extension is not one listed for it. |
FileSignatureError
|
The file does not start with a PDF header. |
PdfSecurityError
|
The PDF is malformed, encrypted, carries blocked content or is a stream bomb. |
ContentThreatError
|
Content analysis found threats. |
FileProcessingError
|
Unexpected error during validation. |
Source code in safeuploads/file_validator.py
1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 | |
validate_pdf_file_sync
validate_pdf_file_sync(file, filename)
Validate a PDF from a seekable file in the calling thread.
Runs the same checks, in the same order, as
validate_pdf_file. It blocks, so it cannot run on an
event loop thread; await validate_pdf_file() or run
this in a worker thread. The file is rewound to position 0
on success and is never closed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
SeekableFile
|
Seekable binary file to validate. |
required |
filename
|
str
|
Filename supplied by the client. |
required |
Returns:
| Type | Description |
|---|---|
ValidationResult
|
Sanitized filename and detected MIME type. |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
Called on a thread running an event loop. |
FilenameSecurityError
|
Filename fails security. |
ExtensionSecurityError
|
Extension not allowed. |
FileSizeError
|
File exceeds size limit or empty. |
MimeTypeError
|
MIME type not allowed, or the extension is not one listed for it. |
FileSignatureError
|
The file does not start with a PDF header. |
PdfSecurityError
|
The PDF is malformed, encrypted, carries blocked content or is a stream bomb. |
ContentThreatError
|
Content analysis found threats. |
FileProcessingError
|
Unexpected error during validation. |
Source code in safeuploads/file_validator.py
1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 | |
validate_zip_file
async
validate_zip_file(file)
Validate uploaded ZIP archive against service configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
UploadFileProtocol
|
Incoming ZIP file-like object to validate. |
required |
Raises:
| Type | Description |
|---|---|
FilenameSecurityError
|
Filename is empty, invalid, or fails security checks. |
ExtensionSecurityError
|
File extension is not allowed or is blocked. |
FileSizeError
|
File size exceeds maximum or file is empty. |
MimeTypeError
|
MIME type is not in allowed ZIP types, or the extension is not one listed for it. |
FileSignatureError
|
File signature doesn't match expected ZIP format. |
CompressionSecurityError
|
ZIP compression validation failed (zip bomb detected). |
ContentThreatError
|
Content analysis found threats. |
FileProcessingError
|
Unexpected error during validation. |
Source code in safeuploads/file_validator.py
1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 | |
validate_zip_file_sync
validate_zip_file_sync(file, filename)
Validate a ZIP archive from a seekable file in the calling thread.
Runs the same checks, in the same order, as
validate_zip_file. It blocks, so it cannot run on an
event loop thread; await validate_zip_file() or run
this in a worker thread. The file is rewound to position 0
on success and is never closed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
SeekableFile
|
Seekable binary file to validate. |
required |
filename
|
str
|
Filename supplied by the client. |
required |
Returns:
| Type | Description |
|---|---|
ValidationResult
|
Sanitized filename and detected MIME type. |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
Called on a thread running an event loop. |
FilenameSecurityError
|
Filename is empty, invalid, or fails security checks. |
ExtensionSecurityError
|
File extension is not allowed or is blocked. |
FileSizeError
|
File size exceeds maximum or file is empty. |
MimeTypeError
|
MIME type is not in allowed ZIP types, or the extension is not one listed for it. |
FileSignatureError
|
File signature doesn't match expected ZIP format. |
CompressionSecurityError
|
ZIP compression validation failed (zip bomb detected). |
ContentThreatError
|
Content analysis found threats. |
FileProcessingError
|
Unexpected error during validation. |
Source code in safeuploads/file_validator.py
1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 | |
FilenameSecurityError
Bases: FileValidationError
Filename failed security checks.
The error code defaults to FILENAME_INVALID.
Source code in safeuploads/exceptions.py
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 | |
__init__
__init__(message, filename=None, error_code=None)
Initialize with message and filename.
Source code in safeuploads/exceptions.py
222 223 224 225 226 227 228 229 230 231 232 233 | |
FilenameSecurityValidator
Bases: BaseValidator
Reduces filenames to a bounded, path-free form.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
File security configuration settings. |
Source code in safeuploads/validators/filename_validator.py
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 | |
__init__
__init__(config)
Initialize the validator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FileSecurityConfig
|
File security configuration settings. |
required |
Source code in safeuploads/validators/filename_validator.py
29 30 31 32 33 34 35 36 | |
limit_length
limit_length(filename)
Truncate the base name and replace an empty one.
The extension is preserved. A blank base name is replaced by
a random file_<hex> name so no upload ends up as just an
extension.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
Filename returned by
:meth: |
required |
Returns:
| Type | Description |
|---|---|
str
|
Filename whose base name is at most |
str
|
|
Source code in safeuploads/validators/filename_validator.py
54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 | |
replace_dangerous_characters
replace_dangerous_characters(filename)
Drop path components and replace characters unsafe in paths.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
Filename that already passed Unicode checks. |
required |
Returns:
| Type | Description |
|---|---|
str
|
Basename of |
str
|
replaced by an underscore. |
Source code in safeuploads/validators/filename_validator.py
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 | |
validate
validate(filename)
Replace path components and dangerous characters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
Filename that already passed Unicode checks. |
required |
Returns:
| Type | Description |
|---|---|
str
|
Basename of |
str
|
replaced. |
Source code in safeuploads/validators/filename_validator.py
86 87 88 89 90 91 92 93 94 95 96 97 | |
FitSecurityValidator
Bases: BaseValidator
Validates the container structure of FIT activity files.
A FIT file is one or more sections back to back. Each section
is a 12 or 14 byte header, data_size bytes of records and a
CRC-16 over the header and records. The sections must cover the
file exactly, so nothing can hide before, between or after
them. Record contents are not interpreted.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
Security configuration for validation limits. |
Source code in safeuploads/validators/fit_validator.py
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 | |
__init__
__init__(config)
Initialize the FIT structure validator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FileSecurityConfig
|
Security configuration with file limits. |
required |
Source code in safeuploads/validators/fit_validator.py
107 108 109 110 111 112 113 114 | |
validate
validate(file_obj, *, filename=None)
Validate the FIT container structure of a file.
The file is read in chunks of limits.chunk_size and
resource limits are checked after every chunk.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_obj
|
SeekableFile
|
Seekable file containing FIT data. |
required |
filename
|
str | None
|
Optional sanitized filename for error context. |
None
|
Raises:
| Type | Description |
|---|---|
FileSignatureError
|
If a header, data size or CRC is invalid, or bytes are left outside the sections (FIT_INVALID_STRUCTURE). |
ResourceLimitError
|
If the active resource monitor's time or memory limit is exceeded. |
Source code in safeuploads/validators/fit_validator.py
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 | |
GzipContentInspector
Bases: BaseInspector
Inspects gzip archives for decompression bomb attacks.
Reads the compressed stream in chunks, tracking the compression ratio and total uncompressed size against configurable limits.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
File security configuration. |
Source code in safeuploads/inspectors/gzip_inspector.py
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 | |
inspect_gzip_content
inspect_gzip_content(file_obj, compressed_size)
Inspect gzip archive for decompression bombs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_obj
|
SeekableFile
|
Seekable file containing gzip data. |
required |
compressed_size
|
int
|
Size of the compressed file in bytes. |
required |
Raises:
| Type | Description |
|---|---|
ZipBombError
|
If compression ratio or uncompressed size exceeds configured limits. |
CompressionSecurityError
|
If the gzip structure is invalid or corrupted. |
ResourceLimitError
|
If the active resource monitor's time or memory limit is exceeded. |
FileProcessingError
|
If an unexpected error occurs. |
Source code in safeuploads/inspectors/gzip_inspector.py
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 | |
ImageDimensionError
Bases: FileValidationError
Image header declares more pixels than the configured limit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
filename
|
str | None
|
Optional filename of the image. |
None
|
width
|
int | None
|
Optional width declared in the image header. |
None
|
height
|
int | None
|
Optional height declared in the image header. |
None
|
max_pixels
|
int | None
|
Optional maximum allowed pixel count. |
None
|
error_code
|
str | None
|
Optional error code (defaults to IMAGE_DIMENSIONS_EXCEEDED). |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
width |
Width declared in the image header. |
|
height |
Height declared in the image header. |
|
max_pixels |
Maximum allowed pixel count. |
Source code in safeuploads/exceptions.py
432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 | |
__init__
__init__(
message,
filename=None,
width=None,
height=None,
max_pixels=None,
error_code=None,
)
Initialize with dimension details.
Source code in safeuploads/exceptions.py
451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 | |
ImageDimensionValidator
Bases: BaseValidator
Rejects images whose header declares too many pixels.
Width and height are read from the PNG IHDR chunk, the first JPEG frame header (SOF), the first WebP chunk (VP8, VP8L or VP8X canvas) or the HEIC primary item's ispe property, after every ispe property in the file is checked and, for a grid, its descriptor and tiles are matched to it. No pixel data is decoded. A small file can declare a huge image that exhausts memory when decoded, so the pixel count is bounded before a host decodes the upload.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
Security configuration with |
Source code in safeuploads/validators/image_dimension_validator.py
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 | |
__init__
__init__(config)
Initialize the image dimension validator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FileSecurityConfig
|
Security configuration with image limits. |
required |
Source code in safeuploads/validators/image_dimension_validator.py
79 80 81 82 83 84 85 86 | |
validate
validate(file_obj, *, filename=None)
Check the pixel count an image header declares.
The format is taken from the leading bytes; content that is not PNG, JPEG, WebP or HEIC is rejected.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_obj
|
SeekableFile
|
Seekable file containing the image. |
required |
filename
|
str | None
|
Optional sanitized filename for error context. |
None
|
Raises:
| Type | Description |
|---|---|
FileSignatureError
|
If the format is not PNG, JPEG, WebP or HEIC, or its dimension header or HEIF item structure is missing, truncated or invalid (IMAGE_INVALID_STRUCTURE). |
ImageDimensionError
|
If width times height exceeds
|
ResourceLimitError
|
If the active resource monitor's time or memory limit is exceeded. |
Source code in safeuploads/validators/image_dimension_validator.py
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 | |
MalwareSignatureCategory
Bases: Enum
Byte-level signatures for embedded malware detection.
The executable members hold the leading magic of each format.
A magic alone is too short to be evidence (random data
contains MZ every few kilobytes), so the content
inspector reports a match only when the format's header
structure also verifies at that offset.
Attributes:
| Name | Type | Description |
|---|---|---|
PE_EXECUTABLE |
Windows PE |
|
ELF_EXECUTABLE |
Linux ELF magic; reported only with a valid class, byte order and version. |
|
MACHO_EXECUTABLE |
macOS Mach-O magics; reported only with a known CPU type and file type. |
|
JAVA_CLASS |
Java class / universal Mach-O magic; reported only with a valid class-file version or fat header. |
|
WINDOWS_SHORTCUT |
Windows .lnk header size; reported only when followed by the Shell Link CLSID. |
|
WEBSHELL_PATTERNS |
Distinctive web shell script markers. |
|
POLYGLOT_SIGNATURES |
Multi-format file signatures. |
Source code in safeuploads/enums.py
593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 | |
MimeTypeError
Bases: FileValidationError
File MIME type not allowed or mismatches extension.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
filename
|
str | None
|
Optional filename with MIME type issue. |
None
|
detected_mime
|
str | None
|
Optional detected MIME type string. |
None
|
allowed_mimes
|
list[str] | None
|
Optional list of allowed MIME types. |
None
|
error_code
|
str | None
|
Optional error code (defaults to MIME_TYPE_INVALID). |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
detected_mime |
The detected MIME type string. |
|
allowed_mimes |
List of allowed MIME types. |
Source code in safeuploads/exceptions.py
366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 | |
__init__
__init__(
message,
filename=None,
detected_mime=None,
allowed_mimes=None,
error_code=None,
)
Initialize with MIME type details.
Source code in safeuploads/exceptions.py
383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 | |
MimeTypeValidator
Bases: BaseValidator
Detects content MIME types and checks them against extensions.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
File security configuration settings. |
|
magic_mime |
python-magic detector; unset when initialization failed. |
|
magic_available |
Whether python-magic initialized successfully. |
Source code in safeuploads/validators/mime_validator.py
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 | |
__init__
__init__(config)
Initialize the validator and the libmagic detector.
Initialization failure is logged and leaves
magic_available False, so every detection is rejected.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FileSecurityConfig
|
File security configuration settings. |
required |
Source code in safeuploads/validators/mime_validator.py
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 | |
detect
detect(content, filename)
Determine MIME type for file content using libmagic.
Detection never falls back to the filename: the extension is already allow-listed, so a guess from it would let the MIME check pass for any content.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
content
|
bytes
|
Raw bytes of the file to inspect. |
required |
filename
|
str
|
Filename used for error context. |
required |
Returns:
| Type | Description |
|---|---|
str
|
Detected MIME type. |
Raises:
| Type | Description |
|---|---|
MimeTypeError
|
If libmagic is unavailable, raises, or
returns an empty result
( |
Source code in safeuploads/validators/mime_validator.py
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 | |
enforce
enforce(
detected,
allowed_types,
filename,
*,
allow_octet_stream=False,
error_code=None,
)
Raise unless the detected MIME type permits the extension.
The detected type must be allowed, and the filename's extension must be one listed for it, so the name never claims a format other than the content's.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
detected
|
str
|
MIME type reported for the content. |
required |
allowed_types
|
Mapping[str, frozenset[str]]
|
Allowed MIME types for the category, each mapped to the extensions its content may carry. |
required |
filename
|
str
|
Sanitized filename whose extension is checked. |
required |
allow_octet_stream
|
bool
|
Accept |
False
|
error_code
|
str | None
|
Optional error code for a MIME type that is not allowed. |
None
|
Raises:
| Type | Description |
|---|---|
MimeTypeError
|
If the MIME type is not allowed, or with
|
Source code in safeuploads/validators/mime_validator.py
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 | |
validate
validate(content, filename)
Detect the MIME type of the given content.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
content
|
bytes
|
Raw bytes of the file to inspect. |
required |
filename
|
str
|
Filename used for error context. |
required |
Returns:
| Type | Description |
|---|---|
str
|
Detected MIME type. |
Raises:
| Type | Description |
|---|---|
MimeTypeError
|
If detection fails. |
Source code in safeuploads/validators/mime_validator.py
179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 | |
PdfContentInspector
Bases: BaseInspector
Inspects PDF documents for active content and stream bombs.
Rejects a PDF that is encrypted, names a feature from
BLOCKED_PDF_NAMES anywhere outside strings, comments and
stream data (including inside object streams), reads stream
data from another file, uses a stream filter it cannot decode,
has a structure readers could parse differently from the scan,
or whose Flate streams decompress past
max_pdf_uncompressed_size or max_compression_ratio.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
File security configuration. |
Source code in safeuploads/inspectors/pdf_inspector.py
1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 | |
inspect_pdf_content
inspect_pdf_content(file_obj, *, filename=None)
Inspect a PDF held in a seekable file.
The whole file is read into memory; its size is bounded by
max_pdf_size before inspection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_obj
|
SeekableFile
|
Seekable file holding the PDF; rewound to the start on return. |
required |
filename
|
str | None
|
Sanitized filename for error context. |
None
|
Raises:
| Type | Description |
|---|---|
PdfSecurityError
|
The PDF is malformed, encrypted, carries blocked content or is a stream bomb. |
ResourceLimitError
|
The active resource monitor's time or memory limit is exceeded. |
Source code in safeuploads/inspectors/pdf_inspector.py
1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 | |
PdfSecurityError
Bases: FileValidationError
PDF document is malformed, encrypted or carries blocked content.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
filename
|
str | None
|
Optional name of the file with the PDF problem. |
None
|
error_code
|
str | None
|
Optional error code (defaults to PDF_INVALID_STRUCTURE). |
None
|
Source code in safeuploads/exceptions.py
604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 | |
__init__
__init__(message, filename=None, error_code=None)
Initialize with message and filename.
Source code in safeuploads/exceptions.py
615 616 617 618 619 620 621 622 623 624 625 626 | |
ResourceLimitError
Bases: FileProcessingError
Validation exceeded configured resource limits.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
error_code
|
str
|
Machine-readable error code (keyword-only). |
RESOURCE_LIMIT_EXCEEDED
|
elapsed_seconds
|
float | None
|
Optional wall-clock time consumed (keyword-only). |
None
|
memory_bytes
|
int | None
|
Optional peak memory consumed in bytes (keyword-only). |
None
|
original_error
|
Exception | None
|
Optional original exception (keyword-only). |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
elapsed_seconds |
Wall-clock seconds consumed. |
|
memory_bytes |
Peak memory consumed in bytes. |
Source code in safeuploads/exceptions.py
688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 | |
__init__
__init__(
message,
*,
error_code=ErrorCode.RESOURCE_LIMIT_EXCEEDED,
elapsed_seconds=None,
memory_bytes=None,
original_error=None,
)
Initialize with resource limit details.
Source code in safeuploads/exceptions.py
706 707 708 709 710 711 712 713 714 715 716 717 718 719 | |
ResourceMonitor
Context manager that enforces wall-clock and memory limits.
While the block runs the monitor is the active one for the
current context (and worker threads that copy it), so
check_resource_limits enforces both limits at the loop
boundaries of long-running work; they are checked again on
exit. A single blocking call, such as one zipfile parse,
is not interrupted mid-call. Memory is the process-wide peak
RSS (ru_maxrss), a high-water mark, so the delta is not an
upper bound: an earlier, higher peak hides later allocations,
and concurrent work can also trip it.
Attributes:
| Name | Type | Description |
|---|---|---|
max_time_seconds |
Maximum allowed wall-clock seconds. |
|
max_memory_bytes |
Maximum allowed peak-RSS growth in bytes. |
|
start_time |
float
|
Timestamp when the context was entered. |
start_memory |
int
|
Peak process RSS in bytes at context entry. |
Source code in safeuploads/utils.py
137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 | |
elapsed
property
elapsed
Return elapsed seconds since context entry.
Returns:
| Type | Description |
|---|---|
float
|
Elapsed wall-clock seconds. |
memory_delta
property
memory_delta
Return peak-RSS growth since context entry.
Returns:
| Type | Description |
|---|---|
int
|
Non-negative peak-RSS growth in bytes. Because the |
int
|
underlying metric is a process-wide high-water mark, |
int
|
this never decreases and may include memory used by |
int
|
concurrent work outside this monitor. |
__enter__
__enter__()
Record baseline time and memory and become the active monitor.
Returns:
| Type | Description |
|---|---|
ResourceMonitor
|
Self for use in |
Source code in safeuploads/utils.py
180 181 182 183 184 185 186 187 188 189 190 | |
__exit__
__exit__(exc_type, exc_val, exc_tb)
Restore the previous active monitor and check usage.
The previous monitor is restored even when the block raised; the limits are checked only on a clean exit so an exception from the block is not masked.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
exc_type
|
type[BaseException] | None
|
Exception type if raised inside block. |
required |
exc_val
|
BaseException | None
|
Exception value if raised inside block. |
required |
exc_tb
|
TracebackType | None
|
Exception traceback if raised inside block. |
required |
Raises:
| Type | Description |
|---|---|
ResourceLimitError
|
If time or memory limits were exceeded during the monitored block. |
Source code in safeuploads/utils.py
192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 | |
__init__
__init__(max_time_seconds=30.0, max_memory_mb=512)
Initialize the resource monitor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
max_time_seconds
|
float
|
Wall-clock timeout in seconds. |
30.0
|
max_memory_mb
|
int
|
Maximum memory delta in megabytes. |
512
|
Source code in safeuploads/utils.py
161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 | |
check_memory
check_memory()
Check peak memory growth mid-operation.
Uses the process peak RSS high-water mark, so an earlier, higher peak hides later growth.
Raises:
| Type | Description |
|---|---|
ResourceLimitError
|
If peak-RSS growth since context entry exceeds the configured memory limit. |
Source code in safeuploads/utils.py
237 238 239 240 241 242 243 244 245 246 247 248 249 | |
check_time
check_time()
Check elapsed time mid-operation.
Raises:
| Type | Description |
|---|---|
ResourceLimitError
|
If the wall-clock time limit has been exceeded since context entry. |
Source code in safeuploads/utils.py
227 228 229 230 231 232 233 234 235 | |
SecurityAuditLogger
Emits structured audit log records.
All records are emitted under the safeuploads.audit
logger with extra fields containing the structured
AuditEvent data. The application configures handlers
on this logger (or a parent) to capture events.
Attributes:
| Name | Type | Description |
|---|---|---|
enabled |
Whether audit logging is active. |
Source code in safeuploads/audit.py
199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 | |
__init__
__init__(enabled=False)
Initialize the audit logger.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
enabled
|
bool
|
Whether to emit audit events. |
False
|
Source code in safeuploads/audit.py
212 213 214 215 216 217 218 219 | |
failure
failure(
filename, correlation_id, duration_ms, error, details=""
)
Log a validation failure event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
Name of the failed file. |
required |
correlation_id
|
str
|
Unique operation identifier. |
required |
duration_ms
|
float
|
Validation duration in milliseconds. |
required |
error
|
str
|
Short error description. |
required |
details
|
str
|
Additional failure context. |
''
|
Source code in safeuploads/audit.py
313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 | |
log_event
log_event(event)
Emit an audit event as a structured log record.
The correlation ID, filename, result, details and source IP are escaped and length-bounded before being logged.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event
|
AuditEvent
|
The audit event to record. |
required |
Source code in safeuploads/audit.py
221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 | |
resource_limit
resource_limit(
filename, correlation_id, duration_ms, error
)
Log a resource limit event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
Name of the file being validated. |
required |
correlation_id
|
str
|
Unique operation identifier. |
required |
duration_ms
|
float
|
Validation duration in milliseconds. |
required |
error
|
str
|
Short description of the exceeded limit. |
required |
Source code in safeuploads/audit.py
366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 | |
start
start(filename, correlation_id)
Log a validation start event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
Name of the file being validated. |
required |
correlation_id
|
str
|
Unique operation identifier. |
required |
Source code in safeuploads/audit.py
268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 | |
success
success(filename, correlation_id, duration_ms)
Log a validation success event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
Name of the validated file. |
required |
correlation_id
|
str
|
Unique operation identifier. |
required |
duration_ms
|
float
|
Validation duration in milliseconds. |
required |
Source code in safeuploads/audit.py
289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 | |
threat
threat(filename, correlation_id, threat_description)
Log a threat detection event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
Name of the threatening file. |
required |
correlation_id
|
str
|
Unique operation identifier. |
required |
threat_description
|
str
|
Description of the threat. |
required |
Source code in safeuploads/audit.py
342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 | |
SecurityLimits
dataclass
Security constraints for file submissions.
Attributes:
| Name | Type | Description |
|---|---|---|
max_image_size |
int
|
Maximum size in bytes for image files. |
max_image_pixels |
int
|
Maximum pixel count (width times height) an image header may declare. |
max_zip_size |
int
|
Maximum size in bytes for ZIP archives. |
max_activity_file_size |
int
|
Maximum size in bytes for GPX/TCX/FIT activity files. |
max_gzip_size |
int
|
Maximum size in bytes for gzip files. |
max_pdf_size |
int
|
Maximum size in bytes for PDF files. |
max_pdf_uncompressed_size |
int
|
Maximum total size in bytes of the decoded streams of one PDF. |
max_memory_buffer_size |
int
|
Bytes kept in memory before a streamed upload spills to a temporary file on disk. |
chunk_size |
int
|
Chunk size in bytes for streaming reads. |
max_validation_memory_mb |
int
|
Maximum memory in MB allowed during a single validation. |
max_validation_time_seconds |
float
|
Overall validation timeout in seconds. |
max_compression_ratio |
int
|
Maximum expansion ratio for ZIP, gzip and PDF files. |
max_uncompressed_size |
int
|
Maximum cumulative size of ZIP contents. |
max_individual_file_size |
int
|
Maximum size of single file in ZIP. |
max_zip_entries |
int
|
Maximum number of file entries in ZIP. |
zip_analysis_timeout |
float
|
Maximum seconds for ZIP analysis. |
max_zip_depth |
int
|
Maximum directory nesting depth in ZIP. |
max_filename_length |
int
|
Maximum length for filenames in ZIP. |
max_path_length |
int
|
Maximum length for full paths in ZIP. |
max_sanitized_name_length |
int
|
Maximum length of the base name (extension excluded) kept when sanitizing an uploaded filename. |
max_number_files_same_type |
int
|
Maximum number of files sharing the same extension inside a ZIP. |
allow_nested_archives |
bool
|
Whether nested archives are permitted. |
allow_symlinks |
bool
|
Whether symbolic links are permitted. |
allow_absolute_paths |
bool
|
Whether absolute paths are permitted. |
scan_zip_content |
bool
|
Whether deep content inspection is enabled. |
verify_zip_decompression |
bool
|
Whether to decompress every ZIP entry to reject forged central-directory metadata. |
max_total_entries_recursive |
int
|
Maximum cumulative entry count across all nesting levels of nested archives. |
enable_audit_logging |
bool
|
Whether structured security audit logging is emitted. |
enable_content_analysis |
bool
|
Whether optional deep content scanning (malware/script/polyglot) runs. |
content_scan_max_size |
int
|
Maximum bytes scanned during optional content analysis. |
Source code in safeuploads/config.py
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 | |
SeekableFile
Bases: Protocol
Protocol for seekable binary file-like objects.
Implemented by BytesIO, SpooledTemporaryFile, and regular file objects opened in binary mode.
Attributes:
| Name | Type | Description |
|---|---|---|
read |
bytes
|
Read bytes from the file. |
seek |
int
|
Move file pointer to specified position. |
tell |
int
|
Return current file pointer position. |
Source code in safeuploads/protocols.py
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 | |
read
read(size=-1)
Read bytes from the file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
size
|
int
|
Number of bytes to read. -1 reads all. |
-1
|
Returns:
| Type | Description |
|---|---|
bytes
|
Bytes read from the file. |
Source code in safeuploads/protocols.py
26 27 28 29 30 31 32 33 34 35 36 | |
seek
seek(offset, whence=0)
Move file pointer to specified position.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
offset
|
int
|
Position offset in bytes. |
required |
whence
|
int
|
Reference point for offset (0=start, 1=current, 2=end). |
0
|
Returns:
| Type | Description |
|---|---|
int
|
New absolute position in the file. |
Source code in safeuploads/protocols.py
38 39 40 41 42 43 44 45 46 47 48 49 50 | |
tell
tell()
Return current file pointer position.
Returns:
| Type | Description |
|---|---|
int
|
Current position in the file. |
Source code in safeuploads/protocols.py
52 53 54 55 56 57 58 59 | |
SuspiciousFilePattern
Bases: Enum
Categorized patterns used to flag potentially malicious uploads.
Attributes:
| Name | Type | Description |
|---|---|---|
DIRECTORY_TRAVERSAL |
Directory traversal attack patterns. |
|
SUSPICIOUS_NAMES |
Suspicious filename patterns. |
|
EXECUTABLE_SIGNATURES |
Dangerous file content signatures. |
|
SUSPICIOUS_PATHS |
Suspicious path components. |
|
SCRIPT_PATTERNS |
Script injection markers in text. |
Source code in safeuploads/enums.py
351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 | |
UnicodeAttackCategory
Bases: Enum
Categorized Unicode code points used in obfuscation attacks.
Attributes:
| Name | Type | Description |
|---|---|---|
DIRECTIONAL_OVERRIDES |
Right-to-left and directional controls. |
|
ZERO_WIDTH_CHARACTERS |
Zero-width and invisible characters. |
|
LANGUAGE_MARKS |
Language and format specific characters. |
|
CONFUSING_PUNCTUATION |
Punctuation that can disguise extensions. |
Source code in safeuploads/enums.py
294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 | |
UnicodeSecurityError
Bases: FilenameSecurityError
Dangerous Unicode characters detected in filename.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
filename
|
str | None
|
Optional filename containing dangerous Unicode. |
None
|
dangerous_chars
|
list[tuple[str, int, int]] | None
|
Optional list of (char, code_point, position) tuples for each dangerous character found. |
None
|
error_code
|
str | None
|
Optional error code (defaults to UNICODE_DANGEROUS_CHARS). |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
dangerous_chars |
List of dangerous character tuples. |
Source code in safeuploads/exceptions.py
236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 | |
__init__
__init__(
message,
filename=None,
dangerous_chars=None,
error_code=None,
)
Initialize with dangerous characters.
Source code in safeuploads/exceptions.py
252 253 254 255 256 257 258 259 260 261 262 263 264 265 | |
UnicodeSecurityValidator
Bases: BaseValidator
Validates filenames for Unicode security threats.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
Runtime configuration for file security rules. |
Source code in safeuploads/validators/unicode_validator.py
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 | |
__init__
__init__(config)
Initialize the Unicode validator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FileSecurityConfig
|
Runtime configuration that controls file security rules. |
required |
Source code in safeuploads/validators/unicode_validator.py
34 35 36 37 38 39 40 41 42 43 44 45 46 | |
compatibility_form
compatibility_form(filename)
Return the NFKC form of a filename for security checks.
The NFKC form folds compatibility characters (fullwidth letters, superscript digits) onto the ASCII text they impersonate. It is only used to run name checks; callers keep the NFC name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
The NFC-normalized filename. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The NFKC-normalized filename. |
Raises:
| Type | Description |
|---|---|
FilenameSecurityError
|
If NFKC folding introduces a path
separator or |
Source code in safeuploads/validators/unicode_validator.py
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 | |
validate
validate(filename)
Validate a filename for Unicode security issues.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
The name of the file to assess. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The validated and normalized filename. |
Source code in safeuploads/validators/unicode_validator.py
204 205 206 207 208 209 210 211 212 213 214 | |
validate_unicode_security
validate_unicode_security(filename)
Validate filename for unsafe Unicode characters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
The filename to validate and normalize. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The NFC-normalized filename. |
Raises:
| Type | Description |
|---|---|
UnicodeSecurityError
|
If dangerous Unicode characters are detected in the filename or result from normalization. |
Source code in safeuploads/validators/unicode_validator.py
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 | |
UploadFileProtocol
Bases: Protocol
Protocol for file upload objects from any web framework.
This protocol defines the minimal interface required for file validation. Any object with these attributes and methods can be validated, regardless of the web framework being used.
Attributes:
| Name | Type | Description |
|---|---|---|
filename |
str | None
|
Original filename from the client. |
size |
int | None
|
Size of the uploaded file in bytes. |
Source code in safeuploads/protocols.py
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 | |
read
async
read(size=-1)
Read bytes from the uploaded file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
size
|
int
|
Number of bytes to read. -1 reads entire file. |
-1
|
Returns:
| Type | Description |
|---|---|
bytes
|
Bytes read from the file. |
Source code in safeuploads/protocols.py
79 80 81 82 83 84 85 86 87 88 89 | |
seek
async
seek(offset)
Move file pointer to specified position.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
offset
|
int
|
Position to move to in bytes. |
required |
Returns:
| Type | Description |
|---|---|
int | None
|
New position in the file, or None for implementations |
int | None
|
(such as Starlette's UploadFile) that return nothing. |
Source code in safeuploads/protocols.py
91 92 93 94 95 96 97 98 99 100 101 102 | |
ValidationResult
dataclass
What a successful validation verified about an upload.
Attributes:
| Name | Type | Description |
|---|---|---|
filename |
str
|
Sanitized filename. Its extension is one the
configuration lists for |
mime_type |
str
|
MIME type libmagic detected from the content,
for the |
Source code in safeuploads/file_validator.py
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 | |
WindowsReservedNameError
Bases: FilenameSecurityError
Windows reserved device name used.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
filename
|
str | None
|
Optional filename using a reserved name. |
None
|
reserved_name
|
str | None
|
Optional specific reserved name detected. |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
reserved_name |
The specific reserved name that was detected. |
Source code in safeuploads/exceptions.py
299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 | |
__init__
__init__(message, filename=None, reserved_name=None)
Initialize with reserved name.
Source code in safeuploads/exceptions.py
312 313 314 315 316 317 318 319 320 321 322 323 324 | |
WindowsSecurityValidator
Bases: BaseValidator
Validator for Windows reserved device names.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
File security configuration settings. |
Source code in safeuploads/validators/windows_validator.py
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 | |
__init__
__init__(config)
Initialize the validator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FileSecurityConfig
|
File security configuration settings. |
required |
Source code in safeuploads/validators/windows_validator.py
27 28 29 30 31 32 33 34 | |
validate
validate(filename)
Validate filename against Windows reserved naming rules.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
The filename to validate. |
required |
Raises:
| Type | Description |
|---|---|
WindowsReservedNameError
|
If filename matches a Windows reserved device name. |
Source code in safeuploads/validators/windows_validator.py
98 99 100 101 102 103 104 105 106 107 108 109 | |
validate_windows_reserved_names
validate_windows_reserved_names(filename)
Validate filename against Windows reserved device names.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
The filename to validate. |
required |
Raises:
| Type | Description |
|---|---|
WindowsReservedNameError
|
If filename matches a Windows reserved device name. |
Source code in safeuploads/validators/windows_validator.py
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 | |
XmlSecurityError
Bases: FileValidationError
XML document is forbidden, unsafe or malformed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
filename
|
str | None
|
Optional name of the file with the XML problem. |
None
|
error_code
|
str | None
|
Optional error code (defaults to XML_MALFORMED). |
None
|
Source code in safeuploads/exceptions.py
580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 | |
__init__
__init__(message, filename=None, error_code=None)
Initialize with message and filename.
Source code in safeuploads/exceptions.py
590 591 592 593 594 595 596 597 598 599 600 601 | |
XmlSecurityValidator
Bases: BaseValidator
Validates XML-based activity files for XXE and entity attacks.
Uses defusedxml to parse XML safely. Rejects files
containing DTD declarations, external entities, or
excessive entity expansion.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
Security configuration for validation limits. |
Source code in safeuploads/validators/xml_validator.py
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 | |
__init__
__init__(config)
Initialize the XML security validator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FileSecurityConfig
|
Security configuration with file limits. |
required |
Source code in safeuploads/validators/xml_validator.py
51 52 53 54 55 56 57 58 | |
validate
validate(file_obj, *, filename=None)
Validate XML file for security threats.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_obj
|
SeekableFile
|
Seekable file containing XML data. |
required |
filename
|
str | None
|
Optional sanitized filename for error context. |
None
|
Raises:
| Type | Description |
|---|---|
XmlSecurityError
|
If the XML fails safety checks. |
FileProcessingError
|
If reading the file fails unexpectedly. |
ResourceLimitError
|
If a resource limit is exceeded. |
Source code in safeuploads/validators/xml_validator.py
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 | |
validate_xml_safety
validate_xml_safety(file_obj, *, filename=None)
Parse XML with XXE protections and validate structure.
The document is fed to defusedxml's parser in chunks of
limits.chunk_size with a target that builds no element
tree, so memory does not grow with the number of elements
(expat buffers only the token it is parsing); resource
limits are checked after every chunk.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_obj
|
SeekableFile
|
Seekable file containing XML data. |
required |
filename
|
str | None
|
Optional sanitized filename for error context. |
None
|
Raises:
| Type | Description |
|---|---|
XmlSecurityError
|
If the XML contains a DTD, which is the only place entities and external references can be declared (XML_DTD_FORBIDDEN), or is malformed (XML_MALFORMED). |
FileProcessingError
|
If reading the file fails unexpectedly. |
ResourceLimitError
|
If the active resource monitor's time or memory limit is exceeded. |
Source code in safeuploads/validators/xml_validator.py
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 | |
ZipBombError
Bases: CompressionSecurityError
Zip archive exceeds compression ratio or uncompressed size limits.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
filename
|
str | None
|
Optional filename of zip bomb. |
None
|
compression_ratio
|
float | None
|
Optional actual compression ratio detected. |
None
|
uncompressed_size
|
int | None
|
Optional total uncompressed size in bytes. |
None
|
max_ratio
|
float | None
|
Optional maximum allowed compression ratio. |
None
|
max_size
|
int | None
|
Optional maximum allowed uncompressed size in bytes. |
None
|
error_code
|
str | None
|
Optional error code (defaults to ZIP_BOMB_DETECTED). |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
compression_ratio |
Actual compression ratio detected. |
|
uncompressed_size |
Total uncompressed size in bytes. |
|
max_ratio |
Maximum allowed compression ratio. |
|
max_size |
Maximum allowed uncompressed size in bytes. |
Source code in safeuploads/exceptions.py
501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 | |
__init__
__init__(
message,
filename=None,
compression_ratio=None,
uncompressed_size=None,
max_ratio=None,
max_size=None,
error_code=None,
)
Initialize with compression details.
Source code in safeuploads/exceptions.py
522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 | |
ZipContentError
Bases: CompressionSecurityError
Zip archive contains dangerous content or structure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
filename
|
str | None
|
Optional filename of problematic archive. |
None
|
threats
|
list[str] | None
|
Optional list of detected threat descriptions. |
None
|
error_code
|
str | None
|
Optional error code (defaults to ZIP_CONTENT_THREAT). |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
threats |
List of detected threat descriptions. |
Source code in safeuploads/exceptions.py
544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 | |
__init__
__init__(
message, filename=None, threats=None, error_code=None
)
Initialize with threat details.
Source code in safeuploads/exceptions.py
559 560 561 562 563 564 565 566 567 568 569 570 571 572 | |
ZipContentInspector
Bases: BaseInspector
Inspects ZIP archive contents for security threats.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
File security configuration. |
Source code in safeuploads/inspectors/zip_inspector.py
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 | |
__init__
__init__(config)
Initialize ZIP inspector with configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FileSecurityConfig
|
File security configuration. |
required |
Source code in safeuploads/inspectors/zip_inspector.py
81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 | |
inspect_nested_archives
inspect_nested_archives(
file_obj,
*,
depth=0,
seen_hashes=None,
entry_counter=None,
start_time=None,
)
Recursively inspect nested archives.
Only called when allow_nested_archives is True. The
archive in file_obj is not itself checked here when
depth is 0; the caller checks it. Every nested ZIP
archive (an entry with a recursable archive extension or
starting with a ZIP signature) is streamed into a spooled
temporary file, checked like a top-level archive (the
compression checks of CompressionSecurityValidator and
the entry and structure checks of this inspector) and then
recursed into. Depth, cumulative entry count and elapsed time are
tracked across all levels, and the hashes of an archive's
ancestors to detect recursive and quine structures. Sibling
archives with identical content are not a quine. An inner archive that
cannot be read, parsed or fully inspected is rejected.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_obj
|
SeekableFile
|
Seekable file containing ZIP data. |
required |
depth
|
int
|
Current nesting depth (0 = outermost). |
0
|
seen_hashes
|
set[str] | None
|
SHA-256 hashes of ancestor archives of
|
None
|
entry_counter
|
list[int] | None
|
Single-element list holding the cumulative entry count shared across all recursion branches. |
None
|
start_time
|
float | None
|
Monotonic timestamp of initial call. |
None
|
Raises:
| Type | Description |
|---|---|
ZipBombError
|
If a nested archive is a zip bomb. |
ZipContentError
|
If recursive structure, quine, or complexity attack is detected, a nested archive fails a check, or an archive cannot be read or parsed. Threats in a nested archive name its nesting path. |
ResourceLimitError
|
If the active resource monitor's time or memory limit is exceeded. |
Source code in safeuploads/inspectors/zip_inspector.py
783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 | |
inspect_zip_content
inspect_zip_content(file_obj)
Inspect ZIP archive for potential security threats.
When allow_nested_archives is enabled, every nested ZIP
archive is then inspected as well (see
inspect_nested_archives).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_obj
|
SeekableFile
|
Seekable file-like object containing ZIP data. |
required |
Raises:
| Type | Description |
|---|---|
ZipBombError
|
If a nested archive is a zip bomb. |
ZipContentError
|
If security threats are detected in ZIP
content such as directory traversal, symlinks, nested
archives, or suspicious patterns, or a nested archive
fails any check. Its |
CompressionSecurityError
|
With |
ResourceLimitError
|
If the active resource monitor's time or memory limit is exceeded. |
FileProcessingError
|
If an unexpected error occurs during inspection. |
Source code in safeuploads/inspectors/zip_inspector.py
139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 | |
ZipThreatCategory
Bases: Enum
Categories of potentially harmful contents within ZIP archives.
Attributes:
| Name | Type | Description |
|---|---|---|
NESTED_ARCHIVES |
Archive format threats. |
|
NESTED_ARCHIVE_SIGNATURES |
Magic-byte prefixes of archive formats (ZIP and ZIP-based, gzip, bzip2, xz, 7z, RAR). |
|
RECURSABLE_ARCHIVES |
ZIP-family formats openable for recursion. |
|
EXECUTABLE_FILES |
Executable content threats. |
|
SCRIPT_FILES |
Script and code threats. |
|
SYSTEM_FILES |
System and configuration threats. |
|
RECURSIVE_STRUCTURE |
Self-referencing ZIP structures. |
|
QUINE_ARCHIVE |
ZIP that contains a copy of itself. |
|
COMPLEXITY_ATTACK |
Algorithmic complexity exploits. |
Source code in safeuploads/enums.py
471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 | |
get_correlation_id
get_correlation_id()
Return the current correlation ID.
Returns:
| Type | Description |
|---|---|
str | None
|
Correlation ID string or None if not set. |
Source code in safeuploads/audit.py
35 36 37 38 39 40 41 42 | |
set_correlation_id
set_correlation_id(cid=None)
Set a new correlation ID for the current context.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cid
|
str | None
|
Explicit ID to use. Generates a UUID4 if None. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
The correlation ID that was set. |
Source code in safeuploads/audit.py
45 46 47 48 49 50 51 52 53 54 55 56 57 58 | |