msguard

Name	msguard JSON
Version	0.0.5 JSON
	download
home_page	None
Summary	MindStudio Guard Repo
upload_time	2025-07-15 00:41:39
maintainer	None
docs_url	None
author	None
requires_python	>=3.7
license	Apache-2.0
keywords	ms guard security
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # 安装

`pip3 install msguard`

# 使用

假设有如下函数

```py
def find_csv_path(input_dir):
	# 在 input_dir 下找到 csv 文件
	# xxx
```

需要对 `input_dir` 做校验，我们可以使用

## 装饰器用法
```py
from msguard import validate_params, Rule

@validate_params({'input_dir': Rule.input_dir_traverse})
def find_csv_path(input_dir):
	# xxx
```

这样，会在调用函数 `find_csv_path` 前，自动对入参 `input_dir` 进行路径校验。

注意事项：

1. `validate_params` 的入参是一个字典，字典的 key 值一定要和要校验的入参变量名一致，否则不会校验
2. 如果 `input_dir` 不满足条件会直接 raise 错误，如果不希望 raise 可以考虑下列其他使用方法

## 函数内部判断
```py
from msguard import validate_params, Rule

def find_csv_path(input_dir):
	if not Rule.input_dir_traverse.is_satisfied_by(input_dir):
        return
	# xxx
```

`Rule` 承载了所有的常规路径校验，其每一个属性都是一个校验项 `Constraint`，每个校验项会有一个方法叫做 `is_satisfied_by`，用于判断入参是否满足校验。因此 `Rule.input_dir_traverse.is_satisfied_by(input_dir)` 判断 `input_dir` 是否符合 `input_dir_traverse` 的要求。这里的逻辑是，如果不符合，则 `return`。这样，就可以避免直接 raise 导致的程序中断

## argparse 用法
```py
from msguard import validate_args

parser.add_argument('--input-path', type=validate_args(Rule.input_dir_traverse), help="输入目录")
```

我们很多命令行用法都使用的是标准库 `argparse`，该库的 `add_argument` 函数支持一个入参 `type`，可以支持自定义函数校验命令行入参。
安全库提供 `validate_args` 用法，接受一个入参 Constraint，用来限制命令行输入，如果判断通过，则返回输入的路径。在最外层进行安全防护，并传递真实路径杜绝软链接风险。

## 任意函数包裹
```py
import os

import pandas
from msguard import validate_params, Rule


def read_csv_from_dir(input_dir):
    csv_file = os.path.join(input_dir, "a.csv")
    df = validate_params({"filepath_or_buffer": Rule.input_file_read})(pd.read_csv)(csv_file)
```

我们有很多时候会遇到入参不是需要校验的对象，拼接之后的路径需要被校验。除了使用 [装饰器](#装饰器用法) 的方式外，我们可以将任意函数显式地包裹，如果不符合要求则自动报错。
这里我们通过 `validate_params` 装饰了 `pd.read_csv` 的三方库函数，要求它的入参 `"filepath_or_buffer"` 必须满足 `Rule.input_file_read`，否则报错。但是需要注意，这里 `"filepath_or_buffer"` 和 `pd.read_csv` 的第一个入参的变量名是一致的，如果入参名改动，则校验无效。

## 其他场景

除此之外，安全库还包含了其他的常用场景，如
- `open_s`：原 `msopen`，会在创建文件，读取文件时自动进行校验，返回句柄
- `walk_s`：会在遍历目录的时候自动进行最大文件数和深度判断
- `update_env_s`：会在添加环境变量搜索路径的时候，自动的判断是否为绝对路径，不会添加 trailing ":"。防护动态库劫持。

还有其他的用法等待大家的探索


            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "msguard",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": null,
    "keywords": "ms, guard, security",
    "author": null,
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/99/33/14fa5b8310d54c050c2d7dd43a1115061c192b49df55925fee690b98122b/msguard-0.0.5.tar.gz",
    "platform": null,
    "description": "# \u5b89\u88c5\n\n`pip3 install msguard`\n\n# \u4f7f\u7528\n\n\u5047\u8bbe\u6709\u5982\u4e0b\u51fd\u6570\n\n```py\ndef find_csv_path(input_dir):\n\t# \u5728 input_dir \u4e0b\u627e\u5230 csv \u6587\u4ef6\n\t# xxx\n```\n\n\u9700\u8981\u5bf9 `input_dir` \u505a\u6821\u9a8c\uff0c\u6211\u4eec\u53ef\u4ee5\u4f7f\u7528\n\n## \u88c5\u9970\u5668\u7528\u6cd5\n```py\nfrom msguard import validate_params, Rule\n\n@validate_params({'input_dir': Rule.input_dir_traverse})\ndef find_csv_path(input_dir):\n\t# xxx\n```\n\n\u8fd9\u6837\uff0c\u4f1a\u5728\u8c03\u7528\u51fd\u6570 `find_csv_path` \u524d\uff0c\u81ea\u52a8\u5bf9\u5165\u53c2 `input_dir` \u8fdb\u884c\u8def\u5f84\u6821\u9a8c\u3002\n\n\u6ce8\u610f\u4e8b\u9879\uff1a\n\n1. `validate_params` \u7684\u5165\u53c2\u662f\u4e00\u4e2a\u5b57\u5178\uff0c\u5b57\u5178\u7684 key \u503c\u4e00\u5b9a\u8981\u548c\u8981\u6821\u9a8c\u7684\u5165\u53c2\u53d8\u91cf\u540d\u4e00\u81f4\uff0c\u5426\u5219\u4e0d\u4f1a\u6821\u9a8c\n2. \u5982\u679c `input_dir` \u4e0d\u6ee1\u8db3\u6761\u4ef6\u4f1a\u76f4\u63a5 raise \u9519\u8bef\uff0c\u5982\u679c\u4e0d\u5e0c\u671b raise \u53ef\u4ee5\u8003\u8651\u4e0b\u5217\u5176\u4ed6\u4f7f\u7528\u65b9\u6cd5\n\n## \u51fd\u6570\u5185\u90e8\u5224\u65ad\n```py\nfrom msguard import validate_params, Rule\n\ndef find_csv_path(input_dir):\n\tif not Rule.input_dir_traverse.is_satisfied_by(input_dir):\n        return\n\t# xxx\n```\n\n`Rule` \u627f\u8f7d\u4e86\u6240\u6709\u7684\u5e38\u89c4\u8def\u5f84\u6821\u9a8c\uff0c\u5176\u6bcf\u4e00\u4e2a\u5c5e\u6027\u90fd\u662f\u4e00\u4e2a\u6821\u9a8c\u9879 `Constraint`\uff0c\u6bcf\u4e2a\u6821\u9a8c\u9879\u4f1a\u6709\u4e00\u4e2a\u65b9\u6cd5\u53eb\u505a `is_satisfied_by`\uff0c\u7528\u4e8e\u5224\u65ad\u5165\u53c2\u662f\u5426\u6ee1\u8db3\u6821\u9a8c\u3002\u56e0\u6b64 `Rule.input_dir_traverse.is_satisfied_by(input_dir)` \u5224\u65ad `input_dir` \u662f\u5426\u7b26\u5408 `input_dir_traverse` \u7684\u8981\u6c42\u3002\u8fd9\u91cc\u7684\u903b\u8f91\u662f\uff0c\u5982\u679c\u4e0d\u7b26\u5408\uff0c\u5219 `return`\u3002\u8fd9\u6837\uff0c\u5c31\u53ef\u4ee5\u907f\u514d\u76f4\u63a5 raise \u5bfc\u81f4\u7684\u7a0b\u5e8f\u4e2d\u65ad\n\n## argparse \u7528\u6cd5\n```py\nfrom msguard import validate_args\n\nparser.add_argument('--input-path', type=validate_args(Rule.input_dir_traverse), help=\"\u8f93\u5165\u76ee\u5f55\")\n```\n\n\u6211\u4eec\u5f88\u591a\u547d\u4ee4\u884c\u7528\u6cd5\u90fd\u4f7f\u7528\u7684\u662f\u6807\u51c6\u5e93 `argparse`\uff0c\u8be5\u5e93\u7684 `add_argument` \u51fd\u6570\u652f\u6301\u4e00\u4e2a\u5165\u53c2 `type`\uff0c\u53ef\u4ee5\u652f\u6301\u81ea\u5b9a\u4e49\u51fd\u6570\u6821\u9a8c\u547d\u4ee4\u884c\u5165\u53c2\u3002\n\u5b89\u5168\u5e93\u63d0\u4f9b `validate_args` \u7528\u6cd5\uff0c\u63a5\u53d7\u4e00\u4e2a\u5165\u53c2 Constraint\uff0c\u7528\u6765\u9650\u5236\u547d\u4ee4\u884c\u8f93\u5165\uff0c\u5982\u679c\u5224\u65ad\u901a\u8fc7\uff0c\u5219\u8fd4\u56de\u8f93\u5165\u7684\u8def\u5f84\u3002\u5728\u6700\u5916\u5c42\u8fdb\u884c\u5b89\u5168\u9632\u62a4\uff0c\u5e76\u4f20\u9012\u771f\u5b9e\u8def\u5f84\u675c\u7edd\u8f6f\u94fe\u63a5\u98ce\u9669\u3002\n\n## \u4efb\u610f\u51fd\u6570\u5305\u88f9\n```py\nimport os\n\nimport pandas\nfrom msguard import validate_params, Rule\n\n\ndef read_csv_from_dir(input_dir):\n    csv_file = os.path.join(input_dir, \"a.csv\")\n    df = validate_params({\"filepath_or_buffer\": Rule.input_file_read})(pd.read_csv)(csv_file)\n```\n\n\u6211\u4eec\u6709\u5f88\u591a\u65f6\u5019\u4f1a\u9047\u5230\u5165\u53c2\u4e0d\u662f\u9700\u8981\u6821\u9a8c\u7684\u5bf9\u8c61\uff0c\u62fc\u63a5\u4e4b\u540e\u7684\u8def\u5f84\u9700\u8981\u88ab\u6821\u9a8c\u3002\u9664\u4e86\u4f7f\u7528 [\u88c5\u9970\u5668](#\u88c5\u9970\u5668\u7528\u6cd5) \u7684\u65b9\u5f0f\u5916\uff0c\u6211\u4eec\u53ef\u4ee5\u5c06\u4efb\u610f\u51fd\u6570\u663e\u5f0f\u5730\u5305\u88f9\uff0c\u5982\u679c\u4e0d\u7b26\u5408\u8981\u6c42\u5219\u81ea\u52a8\u62a5\u9519\u3002\n\u8fd9\u91cc\u6211\u4eec\u901a\u8fc7 `validate_params` \u88c5\u9970\u4e86 `pd.read_csv` \u7684\u4e09\u65b9\u5e93\u51fd\u6570\uff0c\u8981\u6c42\u5b83\u7684\u5165\u53c2 `\"filepath_or_buffer\"` \u5fc5\u987b\u6ee1\u8db3 `Rule.input_file_read`\uff0c\u5426\u5219\u62a5\u9519\u3002\u4f46\u662f\u9700\u8981\u6ce8\u610f\uff0c\u8fd9\u91cc `\"filepath_or_buffer\"` \u548c `pd.read_csv` \u7684\u7b2c\u4e00\u4e2a\u5165\u53c2\u7684\u53d8\u91cf\u540d\u662f\u4e00\u81f4\u7684\uff0c\u5982\u679c\u5165\u53c2\u540d\u6539\u52a8\uff0c\u5219\u6821\u9a8c\u65e0\u6548\u3002\n\n## \u5176\u4ed6\u573a\u666f\n\n\u9664\u6b64\u4e4b\u5916\uff0c\u5b89\u5168\u5e93\u8fd8\u5305\u542b\u4e86\u5176\u4ed6\u7684\u5e38\u7528\u573a\u666f\uff0c\u5982\n- `open_s`\uff1a\u539f `msopen`\uff0c\u4f1a\u5728\u521b\u5efa\u6587\u4ef6\uff0c\u8bfb\u53d6\u6587\u4ef6\u65f6\u81ea\u52a8\u8fdb\u884c\u6821\u9a8c\uff0c\u8fd4\u56de\u53e5\u67c4\n- `walk_s`\uff1a\u4f1a\u5728\u904d\u5386\u76ee\u5f55\u7684\u65f6\u5019\u81ea\u52a8\u8fdb\u884c\u6700\u5927\u6587\u4ef6\u6570\u548c\u6df1\u5ea6\u5224\u65ad\n- `update_env_s`\uff1a\u4f1a\u5728\u6dfb\u52a0\u73af\u5883\u53d8\u91cf\u641c\u7d22\u8def\u5f84\u7684\u65f6\u5019\uff0c\u81ea\u52a8\u7684\u5224\u65ad\u662f\u5426\u4e3a\u7edd\u5bf9\u8def\u5f84\uff0c\u4e0d\u4f1a\u6dfb\u52a0 trailing \":\"\u3002\u9632\u62a4\u52a8\u6001\u5e93\u52ab\u6301\u3002\n\n\u8fd8\u6709\u5176\u4ed6\u7684\u7528\u6cd5\u7b49\u5f85\u5927\u5bb6\u7684\u63a2\u7d22\n\n",
    "bugtrack_url": null,
    "license": "Apache-2.0",
    "summary": "MindStudio Guard Repo",
    "version": "0.0.5",
    "project_urls": {
        "documentation": "https://gitee.com/ascend/msit/tree/master/msprechecker",
        "source": "https://gitee.com/ascend/msit/tree/master/msserviceprofiler/msserviceprofiler",
        "tracker": "https://gitee.com/ascend/msit/issues"
    },
    "split_keywords": [
        "ms",
        " guard",
        " security"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "4c0c8ea0ee563c536343b1360c396611181fb58b00b3b65dec7ff2b6989d1cdc",
                "md5": "8acf18f3713310f4c2c448473fac8ab9",
                "sha256": "f82b8245682ac7a44f9dbd1b1ef2d04a24bc80ccb745626e7acdb6e846c7357d"
            },
            "downloads": -1,
            "filename": "msguard-0.0.5-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "8acf18f3713310f4c2c448473fac8ab9",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 31413,
            "upload_time": "2025-07-15T00:41:37",
            "upload_time_iso_8601": "2025-07-15T00:41:37.307303Z",
            "url": "https://files.pythonhosted.org/packages/4c/0c/8ea0ee563c536343b1360c396611181fb58b00b3b65dec7ff2b6989d1cdc/msguard-0.0.5-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "993314fa5b8310d54c050c2d7dd43a1115061c192b49df55925fee690b98122b",
                "md5": "3ea24b1e9cee6e4e80b0f793fa1fd80c",
                "sha256": "8e299c99bc8435090ce397012fcc541aaca6d9bbf447aa1d18019dd2dd5b5630"
            },
            "downloads": -1,
            "filename": "msguard-0.0.5.tar.gz",
            "has_sig": false,
            "md5_digest": "3ea24b1e9cee6e4e80b0f793fa1fd80c",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 19530,
            "upload_time": "2025-07-15T00:41:39",
            "upload_time_iso_8601": "2025-07-15T00:41:39.546903Z",
            "url": "https://files.pythonhosted.org/packages/99/33/14fa5b8310d54c050c2d7dd43a1115061c192b49df55925fee690b98122b/msguard-0.0.5.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-15 00:41:39",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "msguard"
}