Skip to content

Bulk asynchronous downloader for multiple file hosts

security: reject downloads outside the download folder (#1929)

NTFSvolumedb2b06b875ea
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bdf4e18d9..fbcc08360 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -46,6 +46,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Security
+- Reject download with leading dots as filenames (dot files)
+- Reject downloads if the final download path is outside the config download folder (path traversal)
+- The following extensions have been hardcoded to always be rejected:
+
+1. `.bat`
+2. `.com`
+3. `.exe`
+4. `.hta`
+5. `.inf`
+6. `.jar`
+7. `.js`
+8. `.lnk`
+9. `.msc`
+10. `.msi`
+11. `.ps1`
+12. `.ps2`
+13. `.psc1`
+14. `.psc2`
+15. `.sh`
+16. `.scf`
+17. `.vb`
+18. `.vbs`
+19. `.wsc`
+20. `.wsh`
+
## [9.12.0] - 2026-05-27
### Added
diff --git a/cyberdrop_dl/constants.py b/cyberdrop_dl/constants.py
index 93e1d806d..a1b646608 100644
--- a/cyberdrop_dl/constants.py
+++ b/cyberdrop_dl/constants.py
@@ -168,3 +168,27 @@ class FileExt:
)
VIDEO_OR_IMAGE = VIDEO | IMAGE
MEDIA = AUDIO | VIDEO_OR_IMAGE
+ DANGEROUS = frozenset(
+ {
+ ".bat",
+ ".com",
+ ".exe",
+ ".hta",
+ ".inf",
+ ".jar",
+ ".js",
+ ".lnk",
+ ".msc",
+ ".msi",
+ ".ps1",
+ ".ps2",
+ ".psc1",
+ ".psc2",
+ ".sh",
+ ".scf",
+ ".vb",
+ ".vbs",
+ ".wsc",
+ ".wsh",
+ }
+ )
diff --git a/cyberdrop_dl/crawlers/crawler.py b/cyberdrop_dl/crawlers/crawler.py
index e79e23aa5..901e6c0dc 100644
--- a/cyberdrop_dl/crawlers/crawler.py
+++ b/cyberdrop_dl/crawlers/crawler.py
@@ -26,7 +26,13 @@ from cyberdrop_dl.exceptions import MaxChildrenError, NoExtensionError, ScrapeEr
from cyberdrop_dl.mediaprops import ISO639Subtitle, Resolution
from cyberdrop_dl.url_objects import AbsoluteHttpURL, MediaItem, ScrapeItem
from cyberdrop_dl.utils import css, dates, error_handling_context, is_absolute_http_url, is_blob_or_svg, m3u8, parse_url
-from cyberdrop_dl.utils.filepath import compose_filename, get_filename_and_ext, remove_file_id
+from cyberdrop_dl.utils.filepath import (
+ check_dangerous_filename,
+ check_path_traversal,
+ compose_filename,
+ get_filename_and_ext,
+ remove_file_id,
+)
from cyberdrop_dl.utils.strings import safe_format
if TYPE_CHECKING:
@@ -505,6 +511,10 @@ class Crawler(HTTPMixin, HLSMixin, ABC):
if frag:
media_item.referer = media_item.referer.with_fragment(frag)
media_item.headers.update(self._prepare_headers(scrape_item))
+ if not scrape_item.retry_path:
+ check_path_traversal(self.manager.config.settings.files.download_folder, media_item.download_folder)
+
+ check_dangerous_filename(media_item.download_filename or media_item.filename)
await self.handle_media_item(media_item, m3u8)
def _prepare_headers(self, scrape_item: ScrapeItem) -> dict[str, str]:
diff --git a/cyberdrop_dl/exceptions.py b/cyberdrop_dl/exceptions.py
index f39fcc6a5..e74d0c3a2 100644
--- a/cyberdrop_dl/exceptions.py
+++ b/cyberdrop_dl/exceptions.py
@@ -82,7 +82,10 @@ class InvalidContentTypeError(CDLBaseError):
super().__init__(ui_failure, message=message, origin=origin)
-class NoExtensionError(CDLBaseError):
+class FileNameError(CDLBaseError): ...
+
+
+class NoExtensionError(FileNameError):
def __init__(self, filename: str | None = None, *, origin: ScrapeItem | MediaItem | URL | None = None) -> None:
"""This error will be thrown when no extension is given for a file."""
ui_failure = "No File Extension"
@@ -99,6 +102,13 @@ class InvalidExtensionError(NoExtensionError):
self.ui_failure = "Invalid File Extension"
+class PathTraversalError(CDLBaseError):
+ def __init__(self, path: Path) -> None:
+ ui_failure = "Path Traversal"
+ msg = f"Download path '{path}' is outside destination download path"
+ super().__init__(ui_failure, message=msg)
+
+
class PasswordProtectedError(CDLBaseError):
def __init__(self, message: str | None = None, *, origin: ScrapeItem | MediaItem | URL | None = None) -> None:
"""This error will be thrown when a file is password protected."""
diff --git a/cyberdrop_dl/utils/filepath.py b/cyberdrop_dl/utils/filepath.py
index b5d8cd7c0..2c8134693 100644
--- a/cyberdrop_dl/utils/filepath.py
+++ b/cyberdrop_dl/utils/filepath.py
@@ -8,7 +8,7 @@ from contextvars import ContextVar
from pathlib import Path
from cyberdrop_dl.constants import FileExt
-from cyberdrop_dl.exceptions import InvalidExtensionError, NoExtensionError
+from cyberdrop_dl.exceptions import FileNameError, InvalidExtensionError, NoExtensionError, PathTraversalError
_ALLOWED_FILEPATH_PUNCTUATION = " .-_!#$%'()+,;=@[]^{}~"
_SANITIZE_FILENAME_PATTERN = r'[<>:"/\\|?*\']'
@@ -124,3 +124,21 @@ def remove_file_id(filename: str, ext: str) -> str:
if not filename.endswith(ext):
filename += ext
return filename
+
+
+def check_path_traversal(download_folder: Path, folder: Path) -> None:
+ parts = folder.parts
+ if "." in parts or ".." in parts:
+ raise PathTraversalError(folder)
+
+ if not folder.resolve().is_relative_to(download_folder):
+ raise PathTraversalError(folder)
+
+
+def check_dangerous_filename(filename: str) -> None:
+ if filename.startswith("."):
+ raise FileNameError("Dot file", message=f"Dot files are restricted: {filename}")
+
+ path = Path(filename)
+ if "\\" in filename or "/" in filename or path.name != filename or path.suffix.lower() in FileExt.DANGEROUS:
+ raise FileNameError("Dangerous File Extension", message=filename)
diff --git a/tests/crawlers/test_crawlers.py b/tests/crawlers/test_crawlers.py
index 4e103b6da..46cc54da9 100644
--- a/tests/crawlers/test_crawlers.py
+++ b/tests/crawlers/test_crawlers.py
@@ -110,7 +110,10 @@ async def test_crawler(running_manager: Manager, test_case: CrawlerTestCase) ->
assert cls, f"{test_case.domain} is not a valid crawler domain. Test case is invalid"
crawler = cls(running_manager)
await crawler.__async_init__()
- item = ScrapeItem(url=crawler.parse_url(test_case.url))
+ item = ScrapeItem(
+ url=crawler.parse_url(test_case.url),
+ download_folder=running_manager.config.settings.files.download_folder,
+ )
await crawler.run(item)
results: list[MediaItem] = sorted((call.args[0] for call in func.call_args_list), key=lambda x: str(x.url))
@@ -208,7 +211,10 @@ async def test_direct_http_crawler(running_manager: Manager, url: str, filename:
async with ScrapeMapper(running_manager)() as scrape_mapper:
crawler = scrape_mapper._direct_http
await scrape_mapper.run()
- item = ScrapeItem(url=parse_url(test_case.url))
+ item = ScrapeItem(
+ url=parse_url(test_case.url),
+ download_folder=running_manager.config.settings.files.download_folder,
+ )
await crawler.fetch(item)
results: list[MediaItem] = sorted((call.args[0] for call in func.call_args_list), key=lambda x: str(x.url))
diff --git a/tests/test_filename_safeguards.py b/tests/test_filename_safeguards.py
new file mode 100644
index 000000000..ac9f5345f
--- /dev/null
+++ b/tests/test_filename_safeguards.py
@@ -0,0 +1,111 @@
+from pathlib import Path
+
+import pytest
+
+from cyberdrop_dl.exceptions import FileNameError, PathTraversalError
+from cyberdrop_dl.utils.filepath import check_dangerous_filename, check_path_traversal
+
+
+def test_path_inside_dl_folder_are_ok(tmp_path: Path) -> None:
+ dl = tmp_path / "downloads"
+ sub = dl / "a" / "b"
+ sub.mkdir(parents=True)
+
+ check_path_traversal(dl, sub)
+ check_path_traversal(dl, dl / "a/b")
+
+
+def test_path_travesal_attempts_raise_exception(tmp_path: Path) -> None:
+ dl = tmp_path / "downloads"
+ dl.mkdir()
+
+ with pytest.raises(PathTraversalError):
+ check_path_traversal(dl, Path("a/./b"))
+
+ with pytest.raises(PathTraversalError):
+ check_path_traversal(dl, Path("a/../b"))
+
+
+def test_symlinks_outside_dl_path_raises_error(tmp_path: Path) -> None:
+ """A symlink that points outside the download folder must be rejected."""
+ dl = tmp_path / "downloads"
+ dl.mkdir()
+ outside = tmp_path / "outside"
+ outside.mkdir()
+
+ symlink = dl / "evil"
+ symlink.symlink_to(outside)
+
+ with pytest.raises(PathTraversalError):
+ check_path_traversal(dl, symlink)
+
+
+def test_traversal_paths_should_raise_error(tmp_path: Path) -> None:
+ """A path like '../../etc' must be rejected."""
+ dl = tmp_path / "downloads"
+ dl.mkdir()
+
+ with pytest.raises(PathTraversalError):
+ check_path_traversal(dl, Path(".."))
+
+ with pytest.raises(PathTraversalError):
+ check_path_traversal(dl, dl / ".." / "etc")
+
+
+ "filename",
+ [
+ ".hidden",
+ ".env",
+ ".gitignore",
+ "....double_dots",
+ ],
+)
+def test_dot_files_are_rejected(filename: str) -> None:
+ with pytest.raises(FileNameError) as exc:
+ check_dangerous_filename(filename)
+ assert exc.value.ui_failure == "Dot file"
+ assert filename in str(exc.value)
+
+
+ "filename",
+ [
+ "report.txt",
+ "archive.tar.gz",
+ "script.py",
+ "README",
+ "video.mp4",
+ ],
+)
+def test_known_exceptions_are_accepted(filename: str) -> None:
+ check_dangerous_filename(filename)
+
+
+ "filename",
+ [
+ "malware.exe",
+ "payload.EXE",
+ "startup.bat",
+ "deploy.SH",
+ "run.jar",
+ ],
+)
+def test_dangerous_extensions_are_rejected(filename: str) -> None:
+ with pytest.raises(FileNameError) as exc:
+ check_dangerous_filename(filename)
+ assert exc.value.ui_failure == "Dangerous File Extension"
+ assert exc.value.message == filename
+
+
+ "filename",
+ [
+ "f/video.mp4",
+ r"f\\payload.mp4",
+ ],
+)
+def test_filenames_w_separators_are_rejected(filename: str) -> None:
+ with pytest.raises(FileNameError):
+ check_dangerous_filename(filename)